> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vendo.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Server API reference for @vendoai/vendo composition

> Server-side reference for @vendoai/vendo: the createVendo composition, Vendo interface, fetch handler, Next.js adapter, and host-event seam.

Import the default composition from `@vendoai/vendo/server`.

```ts theme={null}
import type { Principal, ActAs, SecretsProvider, Json, RunId } from "@vendoai/core";
import type { LanguageModel } from "ai";                      // peerDependency (00 conventions)
import type { VendoStore } from "@vendoai/store";
import type { VendoAgent } from "@vendoai/agent";
import type { ActionsRegistry, Connector } from "@vendoai/actions";
import type { VendoGuard, PolicyConfig, Judge } from "@vendoai/guard";
import type { AppsRuntime, SandboxAdapter } from "@vendoai/apps";
import type { AutomationsEngine } from "@vendoai/automations";
import type { ComponentCatalog } from "@vendoai/core";

export function createVendo(config: {
  model: LanguageModel;                       // the one required thing
  principal: (req: Request) => Promise<Principal | null>;   // host session → principal; null → ephemeral anonymous
  store?: VendoStore;                         // default: createStore() (PGlite, .vendo/data)
  sandbox?: SandboxAdapter;                   // e.g. vendoSandbox(), e2bSandbox({ apiKey }), modalSandbox({ ... }); absent → rung 1 only
  catalog?: ComponentCatalog;                 // host components exposed to the generation prompt; see /connect/host-components
  connectors?: Connector[];
  actAs?: ActAs;
  policy?: PolicyConfig;
  judge?: Judge;                              // e.g. vendoAutoJudge({ model }); one import, no shorthand union
  secrets?: SecretsProvider;                  // default envSecrets()
  telemetry?: boolean;                        // wires @vendoai/telemetry
  mcp?: boolean;                              // opens the MCP door; off by default
  oauth?: HostOAuthAdapter;                   // required when mcp is true
  agent?: {                                   // chat context controls; see Handler options
    toolOutputCap?: number;                   // default 32000; 0 disables the cap
    maxOutputTokens?: number;
    historyWindow?: number;                   // last N whole messages re-sent per turn
  };
}): Vendo;

export interface Vendo {
  handler: (req: Request) => Promise<Response>;   // fetch-style; mount at /api/vendo/[...]
  emit(event: string, payload: Json, principal: Principal): Promise<RunId[]>;   // the host-event seam, re-exposed
  agent: VendoAgent; guard: VendoGuard; apps: AppsRuntime; automations: AutomationsEngine; actions: ActionsRegistry; connections: ConnectionsService; store: VendoStore;
}
```

When `principal(req)` resolves null, each client gets its own ephemeral session
principal, carried by a signed httpOnly cookie scoped to the wire base. Sessions
are per client, never persisted, and reset on process restart.

The composition registers app capability tools in actions and guard-binds every
tool registry passed to agent, apps, and automations.

`handler` is framework-agnostic. `nextVendoHandler(vendo)` adapts it to a
Next.js route module. Mount it at `/api/vendo/[...]` unless the client uses a
different base URL.

`emit(event, payload, principal)` is the host-event seam. It returns the ids of
runs started for enabled automations owned by that principal.

## `eraseStore`

`@vendoai/vendo/server` re-exports `eraseStore(store, target)`, the sanctioned
deletion path across every store table and the ephemeral overlay. It is the
only supported way to delete rows from the append-only `vendo_audit` table.

```ts theme={null}
import { eraseStore } from "@vendoai/vendo/server";

await eraseStore(vendo.store, { bySubject: "user_123" });
await eraseStore(vendo.store, { byApp: "app_abc" });
await eraseStore(vendo.store, { byAge: { before: cutoff } });
```

Pass exactly one of `bySubject`, `byApp`, or `byAge`. The call returns a map
of per-table deleted counts. `byAge` retains any row whose lifecycle extends
past the cutoff (for example, an unexpired standing grant or a recently
rotated secret). See [Persistence](/deploy/persistence#erasing-data) for the
full semantics.