> ## Documentation Index > Fetch the complete documentation index at: https://lousho.com/llms.txt > Use this file to discover all available pages before exploring further. # Changelog > Every notable change to @lousho/build-ai-agent, newest first. ## \[Unreleased] - 2026-09-28 ### 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). ### 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/`. ### Added * Remote sub-agent approvals go through the lead run (LOU-Y7.3): 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: []`, and a remote `ask_question` arrives as a question. Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the decision to the remote `POST /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 (LOU-V4.2): `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`): `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` / `SpecObjectSchema`, 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 (LOU-D49): `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 (LOU-D41): `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. ### Deprecated * `ExecuteOptions.onEvent`, `ExecutionEvent` and `ExecutionEventType` (LOU-D41). `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` (LOU-D41): 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 })` (LOU-D41.2, 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` (LOU-D41.2): it was never read (`AgentExecutionOptions` is a legacy type no SDK API takes). Remove the property; stream a run with `agent.stream()` / `AgentExecutor.stream()`. ### Fixed * 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. * `lousho --help`, `-h` and `help` print the usage and exit 0 (they were "unknown command" with exit 1) (LOU-D49). * Install truth (LOU-U20): 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. ### Changed * No `any` left in the SDK's types (LOU-D16): `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` 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()` (and `IStorageService`'s) defaults `T` to `unknown`: pass the type you stored, `readPlainJSONAttachment(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`; `validateAgentTools()` takes `Record`; `createDynamicZodSchemaForInputs()` returns `z.ZodObject>`. * 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 (LOU-D46.2): `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 (LOU-D2.2): 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 (LOU-D2.3): 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 (LOU-D16): 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. ### Added * Reasoning (LOU-V13): 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 (LOU-D23.2): `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 `.turn-`, as hooks see it), approval resumes (the paused run's), and sub-agents (`/`). 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 (LOU-P5.2): `approvers` (a list of platform user ids, or `(user: { id, name?, roles? }, { toolName, input, sessionId }) => boolean | Promise`) 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 (LOU-Y6): every `task` result ends with a `taskId` (the footer is now `[sub-agent '': N step(s), finish 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_` 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 (LOU-Y7.2; `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 (LOU-P8.3): `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 (LOU-W9.2): 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 (LOU-X12.2): `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 (LOU-U23): `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 (LOU-P9): 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:` (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 (LOU-D28d): `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` (LOU-D50): `lousho add [--registry ] [--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 (LOU-D43.2): `KVCheckpointStore` (and `KVStore`, with the new `historyLimit` option) keeps the bounded per-session history `memoryStore()` keeps, as one index key (`#history`) and one key per entry (`#history/`) 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 (LOU-X3): 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` (LOU-Z6): `lousho acp [--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 (LOU-P8.2): `lousho build --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 ` 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 (LOU-P4): `createRouteHandler(agent, { basePath?, auth?, uiMessageStream? })` returns `{ GET, POST, handler }`, Fetch handlers (`(request: Request) => Promise`) 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` (default none: a public route needs one; `GET /health` stays open). `useLoushoAgent({ url, approvalsUrl })` works against it (`POST ` with `{ input, sessionId? }`, `POST /approvals/:id`), and `uiMessageStream: true` adds `POST /ui` for `useChat`. `hasBearerToken` in `src/server/fetchRoutes.ts` is now exported for it. See docs/nextjs.md. * AI SDK UI stream (LOU-P1): `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 (LOU-X8): 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 (LOU-D32.2): `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()` (LOU-W8): `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 (LOU-P6): `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:`) 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 (LOU-V14): `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 (LOU-X12): `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//` form (forwarded to `https:///`, 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 LOU-X12.2. New types `CredentialBroker`, `CredentialBrokerOptions`, `BrokerHeaderValue`. See docs/workspace-tools.md#credential-broker. * Memory in agent directories (LOU-W6.3): `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 (LOU-P7.2): `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 (LOU-Z5.2): `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 (LOU-P3): 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 (LOU-V15): `createAgent()`'s `model`, `instructions` / `prompt` and `tools` each also take a function of the run, `(ctx) => value | Promise` (new types `PerRun` 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 (LOU-P2): 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 (LOU-U21): 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? })` (LOU-W6.2, 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 (LOU-P5): `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 (LOU-Y7): `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 /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 (LOU-D47): `lousho eval --url [--token ]` (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 (LOU-P8): `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 (LOU-P7): `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 /` (verify -> parse -> a turn in session `` `${name}:${sessionKey}` `` -> reply; turns of one session run one at a time) and `POST //approvals/` (`{ 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 LOU-P5 / LOU-P6. See docs/channels.md. * Cloudflare Worker parity (LOU-D51): 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 ` (constant-time compare). New `KVStore(kvBinding, { prefix?, ttl? })` (`src/deploy/kvStore.ts`) is an `AgentStore` on a Workers KV namespace: `sessions/` (transcript JSON, bytes as `{ "$bytes" }`), `checkpoints/` (`KVCheckpointStore`, which gains an optional TTL) and `approvals/`, 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 (LOU-V10): `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()` (LOU-D27): the built-in providers' `stream()` (and so `agent.stream()`) now works on `ai` v6 and v7 as well as v4, through the LOU-D26 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 (LOU-V13). `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 for LOU-D28; an override returning `CoreMessage[]` still compiles. The `ai`/`@ai-sdk/*` peer ranges still name v4 (LOU-D28). 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 (LOU-X5): `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 ` 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()` (LOU-D26): 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 naming LOU-D27 until that ticket lands; the `ai` and `@ai-sdk/*` peer ranges still name v4 (LOU-D28). 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 (LOU-V9): `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 LOU-U8 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 the follow-up, LOU-V10. See docs/streaming.md#queued-input and docs/sessions.md. * Input and output guardrails (LOU-X4): `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 (LOU-X5). See docs/guardrails.md#input-and-output-guardrails. * Deployed `/chat` upgrade (LOU-D14): 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: `, 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:`, 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 ` (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 LOU-D51). See docs/deployment.md#http-api. * `lousho chat` (LOU-D33): a terminal REPL for an agent. `lousho chat [--model provider/model] [--session id] [--store sqlite:]` 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 (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 ` (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 (LOU-W6): `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 `` block (`recall.query: 'last-input'` passes the last user message as the provider query; `recall.onSessionStart: false` turns recall off). The model gets `remember_({ text })` and `recall_({ 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 (LOU-V6): `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 (LOU-D32): `lousho dev` serves one session per browser tab. `POST /chat` with `{ sessionId, input }` streams the turn as SSE (`data: ` 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 (LOU-D45.2): 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 (LOU-D31): `lousho dev ` 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=