Server API

import type {
  ActAs, ActionsRegistry, AppsRuntime, AutomationsEngine, ComponentCatalog,
  ComponentRegistry, Connector, ExtractedTool, FilesAdapter, Harness,
  HostOAuthAdapter, Json, KnowledgeAdapter, Principal, RunId, SandboxAdapter,
  SecretsProvider, Skill, ToolDefinition, ToolRegistry, VendoGuard, VendoStore,
  VendoTheme,
} from "@vendoai/vendo";
import type {
  ComposedAgent, ConnectionsService, CreateVendoConfig, GuardRules, HarnessTurns,
  HostAuthPreset, ModelsConfig, ServerActionHandler,
} from "@vendoai/vendo/server";
import type { LanguageModel } from "ai";

export function createVendo(config: CreateVendoConfig): Vendo;

export interface Vendo {
  handler(req: Request): Promise<Response>;
  tokenFor(who: Request | string): Promise<string>;
  agentTools(who: Request | string): Promise<VendoAgentTools>;
  emit(event: string, payload: Json, principal: Principal): Promise<RunId[]>;
  putUserFile(input: {
    principal: Principal;
    name: string;
    content: Uint8Array | string;
    contentType?: string;
  }): Promise<UploadedFile>;
  usage(query: UsageTallyQuery): Promise<UsageTallyRow[]>;
  guard: VendoGuard;
  guardedTools: ToolRegistry;
  apps: AppsRuntime;
  automations: AutomationsEngine;
  agent?: ComposedAgent;
  actions: ActionsRegistry;
  connections: ConnectionsService;
  tenantConnectors: TenantConnectors;
  channels: VendoChannels;
  store: VendoStore;
  harness: HarnessTurns;
}

export function nextVendoHandler(vendo: Vendo): {
  GET: (request: Request) => Promise<Response>;
  POST: (request: Request) => Promise<Response>;
  PUT: (request: Request) => Promise<Response>;
  PATCH: (request: Request) => Promise<Response>;
  DELETE: (request: Request) => Promise<Response>;
};

export function wellKnownVendoHandler(vendo: Vendo): {
  GET: (request: Request) => Promise<Response>;
  POST: (request: Request) => Promise<Response>;
};

// @vendoai/vendo/ai-sdk
export function vendoTools(
  vendo: Vendo,
  options: { principal: Principal; sessionId?: string; include?: string[]; exclude?: string[] },
): Promise<ToolSet>;

// @vendoai/vendo/mastra
export function vendoMastraTools(
  vendo: Vendo,
  options?: { include?: string[]; exclude?: string[] },
): Promise<Record<string, VendoMastraTool>>;

export const VENDO_PRINCIPAL_KEY = "vendo-principal"; // required per request; missing fails closed
export const VENDO_SESSION_KEY = "vendo-session-id";  // optional audit continuity

import { agent, api, e2b, postgres, serve, tool, THREAD_ID_HEADER } from "@vendoai/vendo";
import { claudeCode } from "@vendoai/vendo/claude-code";

export function agent(config: AgentConfig): VendoAgent;

const support = agent({ name: "support", tools: [api()] });

import { claudeCode } from "@vendoai/vendo/claude-code";

agent({ name: "builder", harness: claudeCode({ machine: "local" }) });

agent({
  name: "builder",
  harness: claudeCode(),
  sandbox: e2b(),                                  // or any SandboxAdapter
  door: { baseUrl: "https://app.example.com" },    // or VENDO_BASE_URL
});

const user = support.forUser("u_42", { profile: { plan: "pro" } });
await user.chat("Where is my order?");

const threads = await user.threads.list();                   // newest first
const messages = await (await user.threads.get(threads[0]!.id)).messages();

export interface VendoAgent {
  readonly name: string;
  chat(message: string, options?: ChatOptions): Turn;
  run<T>(task: string, options?: RunOptions<T>): Turn<T>;
  forUser(subject: string, options?: UserOptions): AgentUser;
  respond(subject: string, message: string | UIMessage, options?: RespondOptions): Promise<Response>;
  /** @deprecated `forUser(subject)` plus `user.threads`. */
  session(subject: string, options?: SessionOptions): Promise<AgentSession>;
  on(when: When, task: string, options?: OnOptions): void;
  handler(options: HandlerOptions): (request: Request) => Promise<Response>;
  readonly permissions: (request: Request) => Promise<Response | undefined>;
  readonly door?: (request: Request) => Promise<Response>;
}

export interface AgentUser {
  chat(message: string, options?: UserChatOptions): Turn;
  readonly turns: Turns;        // list({ status: "interrupted" }), resume(turnId, decisions, options?)
  readonly threads: Threads;    // list(), get(id), delete(id)
  readonly memories: Memories;  // list(), delete(id), clear()
}

const handle = support.handler({ basePath: "/api/agent", resolveUser });
// Next:  export { handle as GET, handle as POST, handle as DELETE };
// Hono:  app.all("/api/agent/*", (c) => handle(c.req.raw));

export interface Turn<T = void> extends PromiseLike<TurnResult<T>> {
  readonly threadId: ThreadId;
  readonly turnId: TurnId;
  readonly events: AsyncIterable<RunEvent>;
}

type TurnResult<T> =
  | (TurnRun & { status: "ok"; output: T })
  | (TurnRun & {
      status: "interrupted";
      interruptions: Interruption[];
      resume(decisions: Decisions, options?: ResumeOptions): Turn<T>;
    })
  | (TurnRun & { status: "stopped"; reason: "aborted" | "maxToolCalls" })
  | {
      status: "error";
      text: "";
      threadId: ThreadId;
      turnId: TurnId;
      error: { code: VendoErrorCode; message: string };
    };

interface TurnRun {
  text: string;
  threadId: ThreadId;
  turnId: TurnId;
  toolCalls: Array<{ call: ToolCall; outcome: ToolOutcome["status"] }>;
  usage: TurnUsage;
}

type Interruption =
  | { id: string; type: "approval"; toolCall: ToolCall }
  | { id: string; type: "input"; questions: Question[] };  // wire-defined, unemitted in v1

export interface Turns {
  list(options: { status: "interrupted" }): Promise<InterruptedTurn[]>;
  resume(turnId: string, decisions: Decisions, options?: ResumeOptions): Promise<TurnResult>;
}

export interface InterruptedTurn {
  turnId: TurnId;
  threadId: ThreadId;
  interruptions: Interruption[];
}

export function api(options?: ApiOptions): ToolRegistry;
export function tool(config: ToolConfig): HostTool;

export function serve(options: { agents: readonly VendoAgent[] }): Promise<VendoRuntime>;
// VendoRuntime is { close(): Promise<void> }

export function postgres(url: string, options?: PostgresOptions): VendoStore;
export function e2b(options?: E2bOptions): SandboxAdapter;