Handler options: createVendo config and fetch settings

Composition configuration

Option	Required	Behavior
`model`	yes	AI SDK `LanguageModel` used by the agent and default app generation
`principal`	yes	resolves the host request to a principal; `null` creates an ephemeral session
`store`	no	defaults to PGlite at `.vendo/data`
`sandbox`	no	unlocks app rungs 2 through 4; absent means rung 1 only
`catalog`	no	`ComponentCatalog` of host components exposed to the generation prompt; merged with any `.vendo/catalog.json` written by `vendo sync`, with explicit entries winning by name — see Host components
`connectors`	no	adds external connector tool registries
`actAs`	no	supplies scoped auth material for away host API execution — see actAs presets
`policy`	no	policy file, rules, directions, and code escape hatch
`judge`	no	contextual guard judge
`secrets`	no	defaults to environment-backed secret lookup
`telemetry`	no	wires build and development telemetry
`mcp`	no	opens the MCP door so outside agents reach host tools through the guarded path; `true` for defaults, or an object carrying `{ baseUrl?, remoteAs?, federation? }` when door-specific settings need to flow through the umbrella (see Configure the door through the umbrella); off by default
`oauth`	conditional	`HostOAuthAdapter` used by the door for session lookup and principal resolution; required when `mcp` is enabled. The door renders consent when the adapter uses `session`, or hands off the whole page when it supplies `authorize` instead — see MCP door
`remoteAs`	no	delegates MCP bearer authentication to an external ES256-signing authorization server (`{ issuer, audience, jwksUri? }`); disables the door’s local OAuth endpoints. Also accepted under `mcp: { remoteAs }` — see MCP door
`federation`	no	enables the `/api/vendo/mcp/federate` handshake so an external authorization server can borrow the host’s login flow; takes a shared `{ secret }`. Also accepted under `mcp: { federation }` — see MCP door
`agent`	no	chat context controls: `toolOutputCap`, `maxOutputTokens`, `historyWindow` (see Agent context)

Agent context

Pass an agent block to tune what the chat loop sends to the model. All fields are optional.

createVendo({
  model,
  principal,
  agent: {
    toolOutputCap: 32_000, // char cap per tool result before it reaches the model; 0 disables
    maxOutputTokens: 4_000, // upper bound on tokens the model may emit per turn
    historyWindow: 20,      // last N whole messages re-sent per turn; omit to send the full thread
  },
});

toolOutputCap caps a single tool result before it reaches the model, so a runaway host response can’t blow the context window. Defaults to 32000 characters. Pass 0 to disable the cap. Persistence and the streamed thread are unaffected — only the copy sent to the model is truncated.
maxOutputTokens bounds tokens the model may emit per turn. Omit to defer to the model default.
historyWindow bounds how many past messages are re-sent to the model each turn. Vendo keeps whole messages so tool-call/result pairs stay paired. Omit to send the full thread (current behavior). The stored thread is untouched; only the per-turn model context shrinks.

Base path

The wire mounts under one base path, default /api/vendo. Configure createVendoClient({ baseUrl }) when mounting elsewhere. Rung 4 HTTP app UI is not proxied through this base.

Identity

Every wire request passes through principal(req). The returned Principal.subject scopes threads, apps, approvals, grants, activity, and runs. Ephemeral principals never write to disk. principal(req) must return kind: "user" (or null). Returning kind: "org" or a subject that starts with vendo: is rejected at the wire — those identities are Vendo-owned. See Principals and organizations. When principal(req) returns null, Vendo issues an anonymous session cookie. The first authenticated request afterward merges the anonymous session’s threads, apps, and state into the signed-in user; grants, approvals, connected accounts, and history stay put.

CSRF floor

Cookie-authenticated state-changing requests require Content-Type: application/json. The exhaustive exceptions are binary /apps/import, signed /webhooks/:source, and bearer-authenticated /tick.

Error envelope

Every non-2xx response has this shape:

{ "error": { "code": "validation", "message": "Readable message" } }

The fixed map is validation 400, not-found 404, blocked 403, conflict 409, cloud-required 402, and sandbox-unavailable or not-implemented 501. MCP door paths are the exception; they speak MCP and OAuth response shapes.

​Composition configuration

​Agent context

​Base path

​Identity

​CSRF floor

​Error envelope