@lunora/agent 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-BWG0uUtX.mjs";
-export type { y as AgentEmailMapper, z as AgentEmailRun, B as AgentGenerateOptions, C as AgentGenerateResult, D as AgentInstructionsContext, E as AgentLiveEvent, F as AgentMemoryOptions, G as AgentMemorySource, H as AgentMessageStatus, J as AgentOnStepFinish, K as AgentPrepareStep, L as AgentPrepareStepInput, M as AgentPrepareStepResult, N as AgentProgressEvent, O as AgentRunHandle, P as AgentStepFinishInfo, Q as AgentStepInfo, R as AgentThreadStatus, T as AgentTokenDelta, U as AgentToolCall, a as AgentToolContext, V as AgentUsage, W as AgentVoiceConfig, X as AgentWorkflowBindingLike, Y as AgentWorkflowInstanceLike } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { A as AgentDefinition, e as AgentCompact, f as AgentEpisodeExtract, g as AgentGraphExtract, h as AgentGenerate, i as AgentTokenSink, j as AgentRunInput, k as AgentFunctionPaths, l as AgentRunFunction, m as AgentStepLike, n as AgentStreamGenerate, o as AgentRunResult, p as AgentMessageRow, q as AgentConfig, d as SkillDefinition, r as AnyAgentTool, s as AgentAsToolOptions, t as AgentSubToolInput, c as AgentToolDefinition, u as AgentBindingSpec, v as AgentHandle, w as AgentToolConfig, x as AgentFunctionReference, y as AgentModelInput, z as SkillConfig } from "./packem_shared/types.d-B8WZl1rU.mjs";
+export type { B as AgentApprovalContext, C as AgentEmailMapper, D as AgentEmailRun, E as AgentGenerateOptions, F as AgentGenerateResult, G as AgentInstructionsContext, H as AgentLiveEvent, J as AgentMemoryOptions, K as AgentMemorySource, L as AgentMessageStatus, M as AgentOnReply, N as AgentOnStepFinish, O as AgentPrepareStep, P as AgentPrepareStepInput, Q as AgentPrepareStepResult, R as AgentProgressEvent, T as AgentReplyInfo, a as AgentReplyRef, U as AgentRunHandle, V as AgentStepFinishInfo, W as AgentStepInfo, X as AgentThreadStatus, Y as AgentTokenDelta, Z as AgentToolCall, b as AgentToolContext, _ as AgentUsage, $ as AgentVoiceConfig, a0 as AgentWorkflowBindingLike, a1 as AgentWorkflowInstanceLike, a2 as EnsureThreadOutcome } from "./packem_shared/types.d-B8WZl1rU.mjs";
 export { type AgentComponent, agentComponent, agentExtension } from "./component.mjs";
 import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
 export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.mjs";
@@ -8,99 +8,114 @@ import { createAi } from '@lunora/ai';
 import { WorkflowDefinition } from '@lunora/workflow';
 import '@lunora/mail/inbound';
 import '@lunora/server';
+/**
+ * `AgentLoopOptions` is part of the experimental `@lunora/agent` API and may change without a major version bump.
+ * @experimental
+ */
 interface AgentLoopOptions {
   agent: AgentDefinition;
   /**
-  * The history-compaction seam — production wires AI SDK `generateText`.
-  * Absent (the default) disables compaction, so an agent with no `compaction`
-  * config, and every unit test that doesn't opt in, is byte-identical.
-  */
+   * The history-compaction seam — production wires AI SDK `generateText`.
+   * Absent (the default) disables compaction, so an agent with no `compaction`
+   * config, and every unit test that doesn't opt in, is byte-identical.
+   */
   compact?: AgentCompact;
   env: Record<string, unknown>;
   /** The agent's `lunora/agents.ts` export name (thread attribution). */
   exportName: string;
   /**
-  * The run-end episode-summary seam — production wires AI SDK `generateText`.
-  * Absent (the default) disables episode recording, so an agent with no
-  * episodic memory, and every unit test that doesn't opt in, is byte-identical.
-  */
+   * The run-end episode-summary seam — production wires AI SDK `generateText`.
+   * Absent (the default) disables episode recording, so an agent with no
+   * episodic memory, and every unit test that doesn't opt in, is byte-identical.
+   */
   extractEpisode?: AgentEpisodeExtract;
   /**
-  * The run-end graph-extraction seam — production wires AI SDK `generateText`
-  * with a structured `Output.object`. Absent (the default) disables
-  * extraction, so an agent with no graph memory, and every unit test that
-  * doesn't opt in, is byte-identical.
-  */
+   * The run-end graph-extraction seam — production wires AI SDK `generateText`
+   * with a structured `Output.object`. Absent (the default) disables
+   * extraction, so an agent with no graph memory, and every unit test that
+   * doesn't opt in, is byte-identical.
+   */
   extractGraph?: AgentGraphExtract;
   /** The LLM-turn seam — production wires AI SDK `generateText`. */
   generate: AgentGenerate;
   /** The workflow instance id — the deterministic per-run message-key prefix. */
   instanceId: string;
   /**
-  * Live-only sink for streamed token deltas. Supplied by the runtime (tees to
-  * the existing stream transport); when present together with
-  * {@link AgentLoopOptions.streamGenerate} each turn streams its deltas here
-  * instead of a single non-streaming `generate` call. Absent (the default)
-  * keeps the byte-identical non-streaming path. Never fired on a replay — the
-  * memoized turn skips the step body that would emit deltas.
-  */
+   * Live-only sink for streamed token deltas. Supplied by the runtime (tees to
+   * the existing stream transport); when present together with
+   * {@link AgentLoopOptions.streamGenerate} each turn streams its deltas here
+   * instead of a single non-streaming `generate` call. Absent (the default)
+   * keeps the byte-identical non-streaming path. Never fired on a replay — the
+   * memoized turn skips the step body that would emit deltas.
+   */
   onTokenDelta?: AgentTokenSink;
   params: AgentRunInput;
   paths: AgentFunctionPaths;
   run: AgentRunFunction;
   step: AgentStepLike;
   /**
-  * The streaming LLM-turn seam — production wires AI SDK `streamText`. Used
-  * only when {@link AgentLoopOptions.onTokenDelta} is also present; otherwise
-  * the loop falls back to {@link AgentLoopOptions.generate} unchanged.
-  */
+   * The streaming LLM-turn seam — production wires AI SDK `streamText`. Used
+   * only when {@link AgentLoopOptions.onTokenDelta} is also present; otherwise
+   * the loop falls back to {@link AgentLoopOptions.generate} unchanged.
+   */
   streamGenerate?: AgentStreamGenerate;
 }
 /**
-* Decide the compaction split for a turn: when `compaction` is configured and the
-* history exceeds `maxMessages`, return the `older` messages to summarize and the
-* `recent` tail to keep verbatim (the most recent `keepRecent`, default
-* `ceil(maxMessages / 2)`). Returns `undefined` when compaction is unset, the
-* history is short enough, or the tail would be the whole history — a PURE
-* decision (no I/O), unit-testable in isolation.
-*/
+ * Decide the compaction split for a turn: when `compaction` is configured and the
+ * history exceeds `maxMessages`, return the `older` messages to summarize and the
+ * `recent` tail to keep verbatim (the most recent `keepRecent`, default
+ * `ceil(maxMessages / 2)`). Returns `undefined` when compaction is unset, the
+ * history is short enough, or the tail would be the whole history — a PURE
+ * decision (no I/O), unit-testable in isolation.
+ * @experimental
+ */
 declare const splitForCompaction: (history: ReadonlyArray<AgentMessageRow>, compaction: AgentConfig["compaction"]) => {
   older: AgentMessageRow[];
   recent: AgentMessageRow[];
 } | undefined;
 /**
-* The durable tool-loop. Correctness rests on two invariants:
-*
-* 1. **Deterministic step names.** Each LLM turn is `llm:turn:N` (`N` = the
-* loop index, replay-stable) and each tool call is `tool:NAME:CALL_ID`
-* (`CALL_ID` = the provider's stable id, itself replayed from the memoized LLM
-* step). Native `step.do` memoization then guarantees a COMPLETED step is
-* never re-run on replay — a resumed run cannot double-charge a card. A step
-* that FAILS mid-body is retried at-least-once; the tool receives its step
-* name as `idempotencyKey` to dedupe on.
-*
-* 2. **Idempotent persistence.** Every message write is keyed
-* `INSTANCE:ROLE:POSITION` and the append mutation dedupes on it, so a
-* replayed persist is a no-op — the thread never duplicates.
-*
-* Loop control derives ONLY from persisted step outputs (never fresh
-* `Date.now()`/`Math.random()` at the top level), so replays walk the same
-* step-name sequence.
-*/
+ * The durable tool-loop. Correctness rests on two invariants:
+ *
+ * 1. **Deterministic step names.** Each LLM turn is `llm:turn:N` (`N` = the
+ * loop index, replay-stable) and each tool call is `tool:NAME:CALL_ID`
+ * (`CALL_ID` = the provider's stable id, itself replayed from the memoized LLM
+ * step). Native `step.do` memoization then guarantees a COMPLETED step is
+ * never re-run on replay — a resumed run cannot double-charge a card. A step
+ * that FAILS mid-body is retried at-least-once; the tool receives its step
+ * name as `idempotencyKey` to dedupe on.
+ *
+ * 2. **Idempotent persistence.** Every message write is keyed
+ * `INSTANCE:ROLE:POSITION` and the append mutation dedupes on it, so a
+ * replayed persist is a no-op — the thread never duplicates.
+ *
+ * Loop control derives ONLY from persisted step outputs (never fresh
+ * `Date.now()`/`Math.random()` at the top level), so replays walk the same
+ * step-name sequence.
+ * @experimental
+ */
 declare const runAgentLoop: (options: AgentLoopOptions) => Promise<AgentRunResult>;
-/** Input the model provides to a minted `searchMemory` tool. */
+/**
+ * Input the model provides to a minted `searchMemory` tool.
+ * @experimental
+ */
 interface AgentMemorySearchInput {
   /** The natural-language query. */
   query: string;
   /** Per-call retrieval depth (overrides the source's configured `topK`). */
   topK?: number;
 }
-/** Input the model provides to a minted `readMemory` tool. */
+/**
+ * Input the model provides to a minted `readMemory` tool.
+ * @experimental
+ */
 interface AgentMemoryReadInput {
   /** The chunk/document id from a `searchMemory` hit. */
   id: string;
 }
-/** One ranked hit in a {@link AgentMemorySearchResult}. */
+/**
+ * One ranked hit in a {@link AgentMemorySearchResult}.
+ * @experimental
+ */
 interface AgentMemorySearchHit {
   id: string;
   score: number;
@@ -109,68 +124,81 @@ interface AgentMemorySearchHit {
   sourceId: string;
 }
 /**
-* The compact shape a minted `searchMemory` tool returns to the model: ranked
-* hits plus deduped source refs, with the giant joined `.context` string
-* DROPPED — the model reads snippets and decides what (if anything) to pull with
-* `readMemory`, which is the whole point of agentic (vs inject) retrieval.
-*/
+ * The compact shape a minted `searchMemory` tool returns to the model: ranked
+ * hits plus deduped source refs, with the giant joined `.context` string
+ * DROPPED — the model reads snippets and decides what (if anything) to pull with
+ * `readMemory`, which is the whole point of agentic (vs inject) retrieval.
+ * @experimental
+ */
 interface AgentMemorySearchResult {
   results: AgentMemorySearchHit[];
   sources: ReadonlyArray<unknown>;
 }
 /**
-* Project a `@lunora/ai/rag` `RetrieveResult` into the compact
-* {@link AgentMemorySearchResult} a minted `searchMemory` tool returns. Defensive
-* against a source action that returns a differently-shaped value (the dispatch
-* boundary is untyped): a missing `chunks`/`sources` degrades to empty.
-*/
+ * Project a `@lunora/ai/rag` `RetrieveResult` into the compact
+ * {@link AgentMemorySearchResult} a minted `searchMemory` tool returns. Defensive
+ * against a source action that returns a differently-shaped value (the dispatch
+ * boundary is untyped): a missing `chunks`/`sources` degrades to empty.
+ * @experimental
+ */
 declare const toSearchResults: (retrieved: unknown, snippetChars: number) => AgentMemorySearchResult;
 /**
-* Mint the model-facing tools for every `mode: "agentic"` memory source — the
-* agent's own `memory` (keyed `"default"` → `searchMemory`/`readMemory`) and
-* each skill's `knowledge` (keyed by the skill name → `search_KEY`/`read_KEY`).
-* An `"inject"`-mode source contributes NO tool (it stays on the auto-injection
-* path). The returned map is folded into the agent's flat tool namespace by
-* `defineAgent`, where a collision with a real tool throws.
-*
-* Walks the same two source origins as `collectMemorySources` so the two stay in
-* lockstep; the split is deliberate — inject sources feed retrieval, agentic
-* sources feed tools, and no source is ever on both paths.
-*/
+ * Mint the model-facing tools for every `mode: "agentic"` memory source — the
+ * agent's own `memory` (keyed `"default"` → `searchMemory`/`readMemory`) and
+ * each skill's `knowledge` (keyed by the skill name → `search_KEY`/`read_KEY`).
+ * An `"inject"`-mode source contributes NO tool (it stays on the auto-injection
+ * path). The returned map is folded into the agent's flat tool namespace by
+ * `defineAgent`, where a collision with a real tool throws.
+ *
+ * Walks the same two source origins as `collectMemorySources` so the two stay in
+ * lockstep; the split is deliberate — inject sources feed retrieval, agentic
+ * sources feed tools, and no source is ever on both paths.
+ * @experimental
+ */
 declare const collectAgenticMemoryTools: (config: AgentConfig, skills: ReadonlyArray<SkillDefinition>) => Record<string, AnyAgentTool>;
 /**
-* Adapt a declared agent into a tool the parent's model can call: `execute`
-* starts a CHILD run on the child agent's Workflow binding, waits for it to
-* finish, and returns its final answer — so a supervisor agent can delegate to
-* specialists.
-*
-* Replay-safety: the whole `execute` runs inside the loop's `tool:NAME:CALL_ID`
-* durable step, so a completed sub-run is memoized and never re-run. The child
-* `threadKey` and Workflow instance id both DERIVE from the parent's
-* (replay-stable) `threadKey` + `toolCallId`, so a retried step reuses the same
-* child run rather than forking a new one (idempotent create-or-get). No
-* `Date.now()`/`Math.random()`.
-*
-* The child's completion is observed by POLLING `instance.status()` (Cloudflare
-* Workflows has no in-step await-instance primitive), and the answer is read
-* back from the child's persisted thread — the single source of truth — via the
-* shared `agents:agentMessages` runtime function.
-*/
+ * Adapt a declared agent into a tool the parent's model can call: `execute`
+ * starts a CHILD run on the child agent's Workflow binding, waits for it to
+ * finish, and returns its final answer — so a supervisor agent can delegate to
+ * specialists.
+ *
+ * Replay-safety: the whole `execute` runs inside the loop's `tool:NAME:CALL_ID`
+ * durable step, so a completed sub-run is memoized and never re-run. The child
+ * `threadKey` and Workflow instance id both DERIVE from the parent's
+ * (replay-stable) `threadKey` + `toolCallId`, so a retried step reuses the same
+ * child run rather than forking a new one (idempotent create-or-get). No
+ * `Date.now()`/`Math.random()`.
+ *
+ * The child's completion is observed by POLLING `instance.status()` (Cloudflare
+ * Workflows has no in-step await-instance primitive), and the answer is read
+ * back from the child's persisted thread — the single source of truth — via the
+ * shared `agents:agentMessages` runtime function.
+ * @experimental
+ */
 declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<AgentSubToolInput, string>;
-/** One step of a tool-composition script — call `tool` with `input`, bind the result to `id`. */
+/**
+ * One step of a tool-composition script — call `tool` with `input`, bind the result to `id`.
+ * @experimental
+ */
 interface ToolScriptStep {
   /** A stable name later steps reference the output by. */
   id: string;
-  /** The tool's input; values may embed `{ "$from": "&lt;stepId>", "$path": "a.b" }` refs. */
+  /** The tool's input; values may embed `{ "$from": "<stepId>", "$path": "a.b" }` refs. */
   input?: Record<string, unknown>;
   /** The tool to call — one of the tools handed to {@link codeTool}. */
   tool: string;
 }
-/** The model-provided input to a {@link codeTool} call. */
+/**
+ * The model-provided input to a {@link codeTool} call.
+ * @experimental
+ */
 interface ToolScript {
   steps: ToolScriptStep[];
 }
-/** The result of running a {@link ToolScript}: each step's output plus the last one. */
+/**
+ * The result of running a {@link ToolScript}: each step's output plus the last one.
+ * @experimental
+ */
 interface ToolScriptResult {
   final: unknown;
   results: ReadonlyArray<{
@@ -178,109 +206,125 @@ interface ToolScriptResult {
     output: unknown;
   }>;
 }
-/** Author-supplied config for {@link codeTool}. */
+/**
+ * Author-supplied config for {@link codeTool}.
+ * @experimental
+ */
 interface CodeToolOptions {
   /** Override the model-facing description (the default lists the available tools). */
   description?: string;
   /** Max steps per script (default 16). */
   maxSteps?: number;
   /**
-  * Gate a whole script behind a human approval. Default: unattended. Note the
-  * COMPOSED tools cannot carry their own approval gate — `codeTool` rejects any
-  * tool with a `needsApproval`, because a code-mode script runs its steps in one
-  * shot and can't pause mid-script to hibernate for HITL. Gate the whole script
-  * here instead. Evaluated from replay-stable input, so keep it deterministic.
-  */
+   * Gate a whole script behind a human approval. Default: unattended. Note the
+   * COMPOSED tools cannot carry their own approval gate — `codeTool` rejects any
+   * tool with a `needsApproval`, because a code-mode script runs its steps in one
+   * shot and can't pause mid-script to hibernate for HITL. Gate the whole script
+   * here instead. Evaluated from replay-stable input, so keep it deterministic.
+   */
   needsApproval?: ((input: ToolScript) => boolean) | boolean;
 }
 /**
-* Resolve `{ "$from": "&lt;stepId>", "$path"?: "a.b" }` references in a step's input
-* against earlier step results, recursing through nested objects and arrays. An
-* unknown `$from` throws — a forward/typo reference is a hard error, not a silent
-* `undefined`. Pure and deterministic (no I/O), so it's unit-testable alone.
-*/
-
-/**
-* A "code mode" tool: instead of the model calling one tool per turn, it writes a
-* SCRIPT that composes several of the tools you hand `codeTool` — chaining a
-* later call's input to an earlier call's output — and the whole thing runs in a
-* single turn. This is a SAFE interpreted data-flow between whitelisted tools
-* (no `eval`, no isolate), so it runs natively in workerd; arbitrary-code
-* execution (the Cloudflare Worker Loader path) is a separate future mode.
-*
-* Each composed tool dispatches through the same durable context a normal call
-* gets (inheriting RLS), with a per-step idempotency key. A code-mode script runs
-* its steps in one shot and CANNOT pause mid-script for a human approval, so
-* `codeTool` REJECTS at construction any tool carrying a `needsApproval` gate —
-* keep approval-gated tools as normal top-level tools. Gate the whole script via
-* `opts.needsApproval` instead.
-*
-* ```ts
-* import { codeTool, defineAgent, functionTool } from "@lunora/agent";
-*
-* export const analyst = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: {
-*         run: codeTool({
-*             findUser: functionTool("users:byEmail", { description: "Look up a user by email.", inputSchema }),
-*             recentOrders: functionTool("orders:recent", { description: "List a user's recent orders.", inputSchema }),
-*         }),
-*     },
-* });
-* // The model can now, in one turn, `findUser` then feed `{ "$from": "u", "$path": "id" }` into `recentOrders`.
-* ```
-*/
+ * A "code mode" tool: instead of the model calling one tool per turn, it writes a
+ * SCRIPT that composes several of the tools you hand `codeTool` — chaining a
+ * later call's input to an earlier call's output — and the whole thing runs in a
+ * single turn. This is a SAFE interpreted data-flow between whitelisted tools
+ * (no `eval`, no isolate), so it runs natively in workerd; arbitrary-code
+ * execution (the Cloudflare Worker Loader path) is a separate future mode.
+ *
+ * Each composed tool dispatches through the same durable context a normal call
+ * gets (inheriting RLS), with a per-step idempotency key. A code-mode script runs
+ * its steps in one shot and CANNOT pause mid-script for a human approval, so
+ * `codeTool` REJECTS at construction any tool carrying a `needsApproval` gate —
+ * keep approval-gated tools as normal top-level tools. Gate the whole script via
+ * `opts.needsApproval` instead.
+ *
+ * STEP-OUTPUT CONTRACT — **every step's output must be JSON-serializable.** Each
+ * step runs inside its own durable `step.do`, so the workflow host serializes
+ * the returned value before the next step (or the tool result) ever sees it. A
+ * `Date` comes back as an ISO string, a `Map`/`Set` as `{}`, `undefined` as
+ * `null` or a dropped key, and a `bigint` throws outright. That applies to the
+ * value a later step reads through `{ "$from": … }` just as much as to the
+ * returned `results` — the hand-off is durable state, not an in-memory one. A
+ * composed tool that wants to pass a rich value should return its JSON form
+ * (`date.toISOString()`, `[...map]`) and let the consuming step rebuild it.
+ *
+ * ```ts
+ * import { codeTool, defineAgent, functionTool } from "@lunora/agent";
+ *
+ * export const analyst = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: {
+ *         run: codeTool({
+ *             findUser: functionTool("users:byEmail", { description: "Look up a user by email.", inputSchema }),
+ *             recentOrders: functionTool("orders:recent", { description: "List a user's recent orders.", inputSchema }),
+ *         }),
+ *     },
+ * });
+ * // The model can now, in one turn, `findUser` then feed `{ "$from": "u", "$path": "id" }` into `recentOrders`.
+ * ```
+ * @experimental
+ */
 declare const codeTool: (tools: Record<string, AnyAgentTool>, options?: CodeToolOptions) => AgentToolDefinition<ToolScript, ToolScriptResult>;
 /**
-* Build the `ctx.agents` producer surface from the codegen-emitted spec list
-* (`LUNORA_AGENTS`), mirroring the `ctx.queues` property-access pattern: each
-* declared agent resolves its `AGENT_*` Workflow binding off `env` lazily, so
-* a missing binding only errors when that agent is actually started.
-*
-* `cancel` also needs to write the thread's status, so it dispatches the agent
-* runtime's `agentPatchThread` mutation. Production leaves `dispatch` undefined
-* and the env-backed `createDispatchRunner` (the same runner the workflow body
-* uses — it POSTs to `/_lunora/scheduler/dispatch`) is built on demand; tests
-* inject a `dispatch` double.
-*/
+ * Build the `ctx.agents` producer surface from the codegen-emitted spec list
+ * (`LUNORA_AGENTS`), mirroring the `ctx.queues` property-access pattern: each
+ * declared agent resolves its `AGENT_*` Workflow binding off `env` lazily, so
+ * a missing binding only errors when that agent is actually started.
+ *
+ * `cancel` also needs to write the thread's status, so it dispatches the agent
+ * runtime's `agentPatchThread` mutation. Production leaves `dispatch` undefined
+ * and the env-backed `createDispatchRunner` (the same runner the workflow body
+ * uses — it POSTs to `/_lunora/scheduler/dispatch`) is built on demand; tests
+ * inject a `dispatch` double.
+ * @experimental
+ */
 declare const createAgentContext: (env: Record<string, unknown>, specs: ReadonlyArray<AgentBindingSpec>, dispatch?: AgentRunFunction) => Record<string, AgentHandle>;
 /**
-* Declare a durable agent. The definition compiles onto a Cloudflare Workflow
-* (each LLM turn and each tool call a named durable step; thread messages
-* persisted idempotently in DO SQLite), invoked from mutations/actions via
-* `ctx.agents.NAME.run(...)` and observed live by subscribing to the
-* `agents:agentMessages` query.
-*
-* ```ts
-* // lunora/agents.ts
-* import { defineAgent, defineAgentTool } from "@lunora/agent";
-*
-* export const support = defineAgent({
-*     instructions: "You are a helpful support agent.",
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: {
-*         getWeather: defineAgentTool({
-*             description: "Look up the current weather for a city.",
-*             execute: async ({ city }, { run }) => run(api.weather.lookup, { city }),
-*             inputSchema: jsonSchema({ properties: { city: { type: "string" } }, required: ["city"], type: "object" }),
-*         }),
-*     },
-* });
-* ```
-*
-* Declaring an agent is enough — codegen auto-registers the `agents:*` runtime
-* functions (from `agentComponent()`) and the `ctx.agents` producer surface.
-*/
+ * Declare a durable agent. The definition compiles onto a Cloudflare Workflow
+ * (each LLM turn and each tool call a named durable step; thread messages
+ * persisted idempotently in DO SQLite), invoked from mutations/actions via
+ * `ctx.agents.NAME.run(...)` and observed live by subscribing to the
+ * `agents:agentMessages` query.
+ *
+ * ```ts
+ * // lunora/agents.ts
+ * import { defineAgent, defineAgentTool } from "@lunora/agent";
+ *
+ * export const support = defineAgent({
+ *     instructions: "You are a helpful support agent.",
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: {
+ *         getWeather: defineAgentTool({
+ *             description: "Look up the current weather for a city.",
+ *             execute: async ({ city }, { run }) => run(api.weather.lookup, { city }),
+ *             inputSchema: jsonSchema({ properties: { city: { type: "string" } }, required: ["city"], type: "object" }),
+ *         }),
+ *     },
+ * });
+ * ```
+ *
+ * Declaring an agent is enough — codegen auto-registers the `agents:*` runtime
+ * functions (from `agentComponent()`) and the `ctx.agents` producer surface.
+ * @experimental
+ */
 declare const defineAgent: (config: AgentConfig) => AgentDefinition;
-/** Runtime brand check for a {@link AgentDefinition}. */
+/**
+ * Runtime brand check for a {@link AgentDefinition}.
+ * @experimental
+ */
 declare const isAgentDefinition: (value: unknown) => value is AgentDefinition;
 /**
-* Declare an agent tool — see `AgentToolDefinition` for why `execute` runs in
-* the loop's durable step (with an `AgentToolContext`) rather than inside the
-* model call.
-*/
+ * Declare an agent tool — see `AgentToolDefinition` for why `execute` runs in
+ * the loop's durable step (with an `AgentToolContext`) rather than inside the
+ * model call.
+ * @experimental
+ */
 declare const defineAgentTool: <Input, Output>(config: AgentToolConfig<Input, Output>) => AgentToolDefinition<Input, Output>;
-/** Author-supplied config for {@link functionTool}. */
+/**
+ * Author-supplied config for {@link functionTool}.
+ * @experimental
+ */
 interface FunctionToolOptions<Input> {
   /** What the tool does — shown to the model (the model decides from it). */
   description: string;
@@ -288,99 +332,116 @@ interface FunctionToolOptions<Input> {
   inputSchema: FlexibleSchema<Input>;
 }
 /**
-* Expose any Lunora query/mutation/action as an agent tool. The returned
-* definition's `execute` dispatches the referenced function through the loop's
-* existing `run` seam (the workflow `ctx.run`) — so there is no bespoke wrapper
-* per tool, and the call runs inside the loop's named durable step exactly like
-* any other tool.
-*
-* ```ts
-* import { functionTool } from "@lunora/agent";
-* import { api } from "./_generated/api";
-*
-* export const support = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: {
-*         lookupOrder: functionTool(api.orders.byId, {
-*             description: "Look up an order by its id.",
-*             inputSchema: jsonSchema({ properties: { id: { type: "string" } }, required: ["id"], type: "object" }),
-*         }),
-*     },
-* });
-* ```
-*
-* The function reference may be a typed `api.*` reference or a `"module:name"`
-* path. The model-provided input is passed verbatim as the function's args, so
-* `inputSchema` should mirror the referenced function's argument validator.
-*/
+ * Expose any Lunora query/mutation/action as an agent tool. The returned
+ * definition's `execute` dispatches the referenced function through the loop's
+ * existing `run` seam (the workflow `ctx.run`) — so there is no bespoke wrapper
+ * per tool, and the call runs inside the loop's named durable step exactly like
+ * any other tool.
+ *
+ * ```ts
+ * import { functionTool } from "@lunora/agent";
+ * import { api } from "./_generated/api";
+ *
+ * export const support = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: {
+ *         lookupOrder: functionTool(api.orders.byId, {
+ *             description: "Look up an order by its id.",
+ *             inputSchema: jsonSchema({ properties: { id: { type: "string" } }, required: ["id"], type: "object" }),
+ *         }),
+ *     },
+ * });
+ * ```
+ *
+ * The function reference may be a typed `api.*` reference or a `"module:name"`
+ * path. The model-provided input is passed as the function's args, so
+ * `inputSchema` should mirror the referenced function's argument validator —
+ * PLUS the call's `idempotencyKey`, pinned onto the args after the model
+ * input (so out-of-schema model input can never override it). A function
+ * that wants to dedupe a side-effecting call across an at-least-once step
+ * retry declares `idempotencyKey: v.optional(v.string())` in its own args
+ * and checks it; a function that ignores it is unaffected — an args field
+ * the function's own validator doesn't declare is dropped, not rejected.
+ * @experimental
+ */
 declare const functionTool: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(reference: AgentFunctionReference | string, options: FunctionToolOptions<Input>) => AgentToolDefinition<Input, Output>;
-/** Resolve the configured model against the Worker env (see `AgentModelInput`). */
+/**
+ * Resolve the configured model against the Worker env (see `AgentModelInput`).
+ * @experimental
+ */
 declare const resolveAgentModel: (model: AgentModelInput, env: Record<string, unknown>) => LanguageModel;
 /**
-* Build the production LLM-turn seam over AI SDK `generateText`. The agent's
-* tools are exposed to the model schema-only (NO `execute`) — the model can
-* decide to call them, but execution happens back in the loop as named
-* durable steps, never inside the model call.
-*
-* The static generation settings (`temperature`, `maxOutputTokens`,
-* `toolChoice`, `output`, `telemetry`) come off the agent config; the per-turn
-* `activeTools` / `toolChoice` / `model` overrides (from `prepareStep`) arrive
-* on each call. When `output` is set the model runs with `Output.object` and
-* the parsed answer is returned alongside the text.
-*/
+ * Build the production LLM-turn seam over AI SDK `generateText`. The agent's
+ * tools are exposed to the model schema-only (NO `execute`) — the model can
+ * decide to call them, but execution happens back in the loop as named
+ * durable steps, never inside the model call.
+ *
+ * The static generation settings (`temperature`, `maxOutputTokens`,
+ * `toolChoice`, `output`, `telemetry`) come off the agent config; the per-turn
+ * `activeTools` / `toolChoice` / `model` overrides (from `prepareStep`) arrive
+ * on each call. When `output` is set the model runs with `Output.object` and
+ * the parsed answer is returned alongside the text.
+ * @experimental
+ */
 declare const createAgentGenerate: (agent: AgentDefinition, env: Record<string, unknown>) => AgentGenerate;
 /**
-* The streaming counterpart of {@link createAgentGenerate} over AI SDK
-* `streamText`. It tees each text delta to `onDelta` as the model produces it,
-* then resolves the SAME {@link AgentGenerate} result the non-streaming seam
-* returns — identical `{ text, toolCalls, usage, output }` — so the value the
-* durable `llm:turn:N` step memoizes (and persists) is byte-for-byte unchanged
-* whether the turn streamed or not.
-*
-* Deltas are live-only: the seam runs inside the turn's durable step, so a
-* workflow replay serves the memoized final value without re-invoking it — no
-* delta is ever re-emitted. The persisted assistant message stays the single
-* source of truth.
-*/
+ * The streaming counterpart of {@link createAgentGenerate} over AI SDK
+ * `streamText`. It tees each text delta to `onDelta` as the model produces it,
+ * then resolves the SAME {@link AgentGenerate} result the non-streaming seam
+ * returns — identical `{ text, toolCalls, usage, output }` — so the value the
+ * durable `llm:turn:N` step memoizes (and persists) is byte-for-byte unchanged
+ * whether the turn streamed or not.
+ *
+ * Deltas are live-only: the seam runs inside the turn's durable step, so a
+ * workflow replay serves the memoized final value without re-invoking it — no
+ * delta is ever re-emitted. The persisted assistant message stays the single
+ * source of truth.
+ * @experimental
+ */
 declare const createStreamGenerate: (agent: AgentDefinition, env: Record<string, unknown>) => AgentStreamGenerate;
 /**
-* Build the production run-end graph-extraction seam over AI SDK `generateText`
-* with an `Output.object` setting (the non-deprecated replacement for
-* `generateObject`, and the same structured-output path the turn seams use). It
-* resolves the (optionally cheaper) extraction model against the env, runs the
-* model over {@link GRAPH_EXTRACTION_SCHEMA}, and returns the parsed
-* `{ entities, relations }`. Wired by `compileAgentWorkflow` and called inside
-* the loop's memoized `memory:extract` step.
-*/
+ * Build the production run-end graph-extraction seam over AI SDK `generateText`
+ * with an `Output.object` setting (the non-deprecated replacement for
+ * `generateObject`, and the same structured-output path the turn seams use). It
+ * resolves the (optionally cheaper) extraction model against the env, runs the
+ * model over {@link GRAPH_EXTRACTION_SCHEMA}, and returns the parsed
+ * `{ entities, relations }`. Wired by `compileAgentWorkflow` and called inside
+ * the loop's memoized `memory:extract` step.
+ * @experimental
+ */
 declare const createGraphExtract: () => AgentGraphExtract;
 /**
-* Build the production run-end episode-extraction seam over AI SDK `generateText`.
-* Unlike the graph extractor this needs no structured schema — an episode is a
-* single natural-language summary — so it returns the trimmed model text. Wired
-* by `compileAgentWorkflow` and called inside the loop's memoized
-* `memory:episode` step.
-*/
+ * Build the production run-end episode-extraction seam over AI SDK `generateText`.
+ * Unlike the graph extractor this needs no structured schema — an episode is a
+ * single natural-language summary — so it returns the trimmed model text. Wired
+ * by `compileAgentWorkflow` and called inside the loop's memoized
+ * `memory:episode` step.
+ * @experimental
+ */
 declare const createEpisodeExtract: () => AgentEpisodeExtract;
 /**
-* Build the production history-compaction seam over AI SDK `generateText`: it
-* summarizes the older conversation messages under {@link COMPACTION_SYSTEM} and
-* returns the brief. Wired by `compileAgentWorkflow` and called inside the loop's
-* memoized `llm:turn:N` step so the summarization is replay-safe.
-*/
-/** One text/image/… content part of an MCP `CallToolResult`. */
+ * One text/image/… content part of an MCP `CallToolResult`.
+ * @experimental
+ */
 interface McpContentPart {
   [key: string]: unknown;
   text?: string;
   type: string;
 }
-/** The result of an MCP `tools/call` — the structural subset the adapter reads. */
+/**
+ * The result of an MCP `tools/call` — the structural subset the adapter reads.
+ * @experimental
+ */
 interface McpCallResult {
   [key: string]: unknown;
   content?: ReadonlyArray<McpContentPart>;
   isError?: boolean;
   structuredContent?: unknown;
 }
-/** One entry of an MCP `tools/list` — the structural subset the adapter reads. */
+/**
+ * One entry of an MCP `tools/list` — the structural subset the adapter reads.
+ * @experimental
+ */
 interface McpToolInfo {
   description?: string;
   inputSchema: {
@@ -392,10 +453,11 @@ interface McpToolInfo {
   name: string;
 }
 /**
-* Structural subset of `@modelcontextprotocol/sdk`'s `Client` the adapter uses.
-* Declaring it locally lets tests inject a mock without the real SDK (and its
-* transport) and keeps the heavy dependency behind a lazy dynamic import.
-*/
+ * Structural subset of `@modelcontextprotocol/sdk`'s `Client` the adapter uses.
+ * Declaring it locally lets tests inject a mock without the real SDK (and its
+ * transport) and keeps the heavy dependency behind a lazy dynamic import.
+ * @experimental
+ */
 interface McpClientLike {
   callTool: (params: {
     arguments?: Record<string, unknown>;
@@ -407,21 +469,35 @@ interface McpClientLike {
     tools: ReadonlyArray<McpToolInfo>;
   }>;
 }
-/** Options for {@link mcpTools}. */
+/**
+ * Options for {@link mcpTools}.
+ * @experimental
+ */
 interface McpToolsOptions {
   /**
-  * A pre-built (already-connected) MCP client. Takes precedence over `url` —
-  * the seam tests inject, and the escape hatch for a custom transport.
-  */
+   * A pre-built (already-connected) MCP client. Takes precedence over `url` —
+   * the seam tests inject, and the escape hatch for a custom transport.
+   */
   client?: McpClientLike;
   /**
-  * A stdio command. NOT supported in the Workers runtime (stdio transports
-  * cannot run in workerd) — passing it throws unless a `client` is injected.
-  * Present so the intent is explicit rather than silently unsupported.
-  */
+   * A stdio command. NOT supported in the Workers runtime (stdio transports
+   * cannot run in workerd) — passing it throws unless a `client` is injected.
+   * Present so the intent is explicit rather than silently unsupported.
+   */
   command?: string;
   /** Identify this client to the server on connect. Default `"lunora-agent"`. */
   name?: string;
+  /**
+   * Gate an adapted tool's call behind a human approval. Defaults to
+   * **unattended** (no gate) — matching today's behavior. An MCP tool's
+   * result feeds back into the model's context (`adaptMcpResult`), so a
+   * hostile downstream server can pair indirect prompt injection with an
+   * unattended mutating tool call; pass a boolean to gate every adapted
+   * tool the same way, or a predicate `(toolName, input) => boolean` to
+   * gate per tool (evaluated from replay-stable input, so keep it
+   * deterministic).
+   */
+  needsApproval?: ((toolName: string, input: Record<string, unknown>) => boolean) | boolean;
   /** Only adapt these tool names (default: every tool the server lists). */
   only?: ReadonlyArray<string>;
   /** Prefix added to each adapted tool's key (disambiguate multiple servers). */
@@ -434,40 +510,46 @@ interface McpToolsOptions {
   version?: string;
 }
 /**
-* Reduce an MCP tool result to the value persisted as the tool message. A
-* server's `structuredContent` is returned as-is; otherwise the text parts are
-* joined. An `isError` result is returned as an error STRING (not thrown) so
-* the next LLM turn can recover, consistent with the loop's unknown-tool path.
-*/
+ * Reduce an MCP tool result to the value persisted as the tool message. A
+ * server's `structuredContent` is returned as-is; otherwise the text parts are
+ * joined. An `isError` result is returned as an error STRING (not thrown) so
+ * the next LLM turn can recover, consistent with the loop's unknown-tool path.
+ * @experimental
+ */
 declare const adaptMcpResult: (result: McpCallResult) => unknown;
 /**
-* Connect to an external MCP server, list its tools, and adapt each into an
-* {@link AgentToolDefinition} — a record you spread into an agent's `tools`.
-* Each adapted tool's `execute` calls the MCP tool through the client, and runs
-* inside the loop's named durable step like any other tool (so a completed call
-* is never re-run on a workflow replay).
-*
-* ```ts
-* export const support = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: {
-*         ...(await mcpTools({ url: "https://mcp.example.com/mcp" })),
-*     },
-* });
-* ```
-*
-* The connection is made at build time (listing tools needs it), then reused by
-* every call. In the Workers runtime only the HTTP/SSE transports run (stdio
-* does not) — pass `url`, or inject an already-connected `client` for a custom
-* transport (also the test seam).
-*/
+ * Connect to an external MCP server, list its tools, and adapt each into an
+ * {@link AgentToolDefinition} — a record you spread into an agent's `tools`.
+ * Each adapted tool's `execute` calls the MCP tool through the client, and runs
+ * inside the loop's named durable step like any other tool (so a completed call
+ * is never re-run on a workflow replay).
+ *
+ * ```ts
+ * export const support = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: {
+ *         ...(await mcpTools({ url: "https://mcp.example.com/mcp" })),
+ *     },
+ * });
+ * ```
+ *
+ * The connection is made at build time (listing tools needs it), then reused by
+ * every call. In the Workers runtime only the HTTP/SSE transports run (stdio
+ * does not) — pass `url`, or inject an already-connected `client` for a custom
+ * transport (also the test seam).
+ *
+ * Every adapted tool runs UNATTENDED by default (no approval gate) — pass
+ * `opts.needsApproval` to change that; see {@link McpToolsOptions.needsApproval}.
+ * @experimental
+ */
 declare const mcpTools: (options: McpToolsOptions) => Promise<Record<string, AgentToolDefinition<Record<string, unknown>>>>;
 /**
-* Assemble the AI SDK conversation for one LLM turn: instructions, then the
-* retrieved memory context (when any), then the persisted thread history with
-* tool calls/results correlated the way providers expect (assistant tool-call
-* parts answered by tool-result parts sharing the `toolCallId`).
-*/
+ * Assemble the AI SDK conversation for one LLM turn: instructions, then the
+ * retrieved memory context (when any), then the persisted thread history with
+ * tool calls/results correlated the way providers expect (assistant tool-call
+ * parts answered by tool-result parts sharing the `toolCallId`).
+ * @experimental
+ */
 declare const buildModelMessages: (options: {
   history: ReadonlyArray<AgentMessageRow>;
   instructions?: string;
@@ -475,63 +557,79 @@ declare const buildModelMessages: (options: {
   summary?: string;
 }) => ModelMessage[];
 /**
-* The namespace the agent runtime functions register under. Codegen
-* auto-registers `agentComponent().functions` here whenever `lunora/agents.ts`
-* declares an agent, so the loop's dispatch paths below hold by construction.
-*/
+ * The namespace the agent runtime functions register under. Codegen
+ * auto-registers `agentComponent().functions` here whenever `lunora/agents.ts`
+ * declares an agent, so the loop's dispatch paths below hold by construction.
+ * @experimental
+ */
 declare const AGENT_MODULE = "agents";
 /**
-* The namespace + name the batteries-included sandbox dispatcher registers
-* under. Codegen auto-registers `sandboxComponent().invoke` here whenever
-* `lunora/` imports a sandbox tool (`browserTool`/`containerTool`), so the
-* tools' `execute` can dispatch to it through the loop's `run` seam.
-*/
+ * The namespace + name the batteries-included sandbox dispatcher registers
+ * under. Codegen auto-registers `sandboxComponent().invoke` here whenever
+ * `lunora/` imports a sandbox tool (`browserTool`/`containerTool`), so the
+ * tools' `execute` can dispatch to it through the loop's `run` seam.
+ * @experimental
+ */
 declare const SANDBOX_MODULE = "sandbox";
-/** The dispatch path of the sandbox runtime action (an internal action). */
+/**
+ * The dispatch path of the sandbox runtime action (an internal action).
+ * @experimental
+ */
 declare const SANDBOX_INVOKE_PATH: "sandbox:invoke";
-/** Default dispatch paths of the agent runtime functions. */
+/**
+ * Default dispatch paths of the agent runtime functions.
+ * @experimental
+ */
 declare const DEFAULT_AGENT_FUNCTION_PATHS: AgentFunctionPaths;
-/** Mint a dispatchable function reference from a path (or pass one through). */
+/**
+ * Mint a dispatchable function reference from a path (or pass one through).
+ * @experimental
+ */
 declare const toFunctionReference: (source: AgentFunctionReference | string) => AgentFunctionReference;
 /**
-* Declare a reusable skill: a bundle of expertise — an instruction fragment,
-* tools, and retrieval `knowledge` — an agent composes in via
-* `defineAgent({ skills: [...] })`. Reuse-first: a skill's `tools` carry the
-* SAME `AnyAgentTool` shape agents already use (`functionTool` / `mcpTools` /
-* `agentAsTool`), and `knowledge` reuses `memory`'s `AgentMemoryOptions`
-* retrieval verbatim.
-*
-* ```ts
-* import { defineSkill, functionTool } from "@lunora/agent";
-*
-* export const billing = defineSkill({
-*     name: "billing",
-*     instructions: "When asked about invoices, cite the invoice id.",
-*     knowledge: { source: "rag:searchBillingDocs", topK: 4 },
-*     tools: {
-*         lookupInvoice: functionTool(api.billing.invoiceById, {
-*             description: "Look up an invoice by id.",
-*             inputSchema: jsonSchema({ properties: { id: { type: "string" } }, required: ["id"], type: "object" }),
-*         }),
-*     },
-* });
-* ```
-*
-* The merge into the agent's flat namespace (tool-name collisions, instruction
-* ordering, per-skill knowledge retrieval) happens in `defineAgent` — a skill
-* only validates its own `name`; tool-name validation is deferred to the merge,
-* which owns the flat model-facing namespace.
-*/
+ * Declare a reusable skill: a bundle of expertise — an instruction fragment,
+ * tools, and retrieval `knowledge` — an agent composes in via
+ * `defineAgent({ skills: [...] })`. Reuse-first: a skill's `tools` carry the
+ * SAME `AnyAgentTool` shape agents already use (`functionTool` / `mcpTools` /
+ * `agentAsTool`), and `knowledge` reuses `memory`'s `AgentMemoryOptions`
+ * retrieval verbatim.
+ *
+ * ```ts
+ * import { defineSkill, functionTool } from "@lunora/agent";
+ *
+ * export const billing = defineSkill({
+ *     name: "billing",
+ *     instructions: "When asked about invoices, cite the invoice id.",
+ *     knowledge: { source: "rag:searchBillingDocs", topK: 4 },
+ *     tools: {
+ *         lookupInvoice: functionTool(api.billing.invoiceById, {
+ *             description: "Look up an invoice by id.",
+ *             inputSchema: jsonSchema({ properties: { id: { type: "string" } }, required: ["id"], type: "object" }),
+ *         }),
+ *     },
+ * });
+ * ```
+ *
+ * The merge into the agent's flat namespace (tool-name collisions, instruction
+ * ordering, per-skill knowledge retrieval) happens in `defineAgent` — a skill
+ * only validates its own `name`; tool-name validation is deferred to the merge,
+ * which owns the flat model-facing namespace.
+ * @experimental
+ */
 declare const defineSkill: (config: SkillConfig) => SkillDefinition;
-/** Runtime brand check for a {@link SkillDefinition}. */
+/**
+ * Runtime brand check for a {@link SkillDefinition}.
+ * @experimental
+ */
 declare const isSkillDefinition: (value: unknown) => value is SkillDefinition;
 /**
-* A control frame the server sends the client as a JSON text message (audio
-* rides separate binary frames). `ready` announces the negotiated codec on
-* connect; `user_transcript` carries the STT result; `assistant_delta` streams
-* the live LLM text; `assistant_done` is the final turn text; `interrupted`
-* acks a barge-in; `error` reports a non-fatal turn failure.
-*/
+ * A control frame the server sends the client as a JSON text message (audio
+ * rides separate binary frames). `ready` announces the negotiated codec on
+ * connect; `user_transcript` carries the STT result; `assistant_delta` streams
+ * the live LLM text; `assistant_done` is the final turn text; `interrupted`
+ * acks a barge-in; `error` reports a non-fatal turn failure.
+ * @experimental
+ */
 type VoiceServerFrame = {
   audioFormat: "mp3" | "wav";
   type: "ready";
@@ -550,7 +648,10 @@ type VoiceServerFrame = {
 } | {
   type: "interrupted";
 };
-/** A control frame the client sends the server (audio rides separate binary frames). */
+/**
+ * A control frame the client sends the server (audio rides separate binary frames).
+ * @experimental
+ */
 type VoiceClientFrame = {
   text: string;
   type: "text";
@@ -559,17 +660,35 @@ type VoiceClientFrame = {
 } | {
   type: "interrupt";
 };
-/** A synthesized-audio source the TTS seam yields — normalized to bytes by {@link toByteIterable}. */
+/**
+ * A synthesized-audio source the TTS seam yields — normalized to bytes by {@link toByteIterable}.
+ * @experimental
+ */
 type VoiceAudioSource = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | Uint8Array;
-/** Transcribe one buffered utterance (16kHz mono 16-bit PCM) to text. */
+/**
+ * Transcribe one buffered utterance (16kHz mono 16-bit PCM) to text.
+ * @experimental
+ */
 type VoiceTranscribe = (pcm: Uint8Array) => Promise<string>;
-/** Synthesize one sentence to an audio byte stream; honors `signal` for barge-in. */
+/**
+ * Synthesize one sentence to an audio byte stream; honors `signal` for barge-in.
+ * @experimental
+ */
 type VoiceSynthesize = (text: string, signal: AbortSignal) => Promise<VoiceAudioSource>;
-/** Send a JSON control frame to the client. */
+/**
+ * Send a JSON control frame to the client.
+ * @experimental
+ */
 type VoiceSend = (frame: VoiceServerFrame) => void;
-/** Send a binary audio frame to the client. */
+/**
+ * Send a binary audio frame to the client.
+ * @experimental
+ */
 type VoiceSendAudio = (bytes: Uint8Array) => void;
-/** The outcome of one voice turn. */
+/**
+ * The outcome of one voice turn.
+ * @experimental
+ */
 interface VoiceTurnResult {
   /** The final assistant text (may be partial if `interrupted`). */
   assistantText: string;
@@ -578,10 +697,20 @@ interface VoiceTurnResult {
   /** The transcribed (or typed) user text — empty when the utterance was silence. */
   userText: string;
 }
-/** Options for one {@link runVoiceTurn}. */
+/**
+ * Options for one {@link runVoiceTurn}.
+ * @experimental
+ */
 interface RunVoiceTurnOptions {
   /** The agent whose thread + models back this session. */
   agent: AgentDefinition;
+  /**
+   * History-compaction seam — the SAME one the durable loop uses. Voice and
+   * text turns share one thread, so an agent that declares `compaction` must
+   * get it here too; absent (or with no `compaction` config) the turn takes
+   * the byte-identical uncompacted path.
+   */
+  compact?: AgentCompact;
   /** Stable per-socket id — the message-key prefix that keeps persisted rows idempotent. */
   connectionId: string;
   /** The Worker env (resolves a dynamic `instructions` thunk). */
@@ -617,23 +746,21 @@ interface RunVoiceTurnOptions {
   /** Optional outbound-audio backpressure: awaited before each audio frame so a slow client can't balloon DO memory. Never throws. */
   waitForDrain?: () => Promise<void>;
 }
-/** Normalize a {@link VoiceAudioSource} to an async iterable of byte chunks. */
-
-/**
-* Run one conversational voice turn IN-DO: transcribe the utterance (or take the
-* typed text), persist the user turn onto the SHARED agent thread, stream the
-* assistant reply, and synthesize it sentence-by-sentence back to the client —
-* TTS overlapping generation, both cancellable by a barge-in `signal`.
-*
-* This is NOT the replay-durable Workflow tool-loop: a voice turn is
-* conversational only (no tools in v1) and not replay-safe. Persistence stays
-* idempotent by `voice:{connectionId}:{turn}:{role}` message keys so a resent
-* frame never duplicates a row; the thread tables are the same ones the durable
-* agent loop and `useAgentChat` read, so a voice session and a text session on
-* the same `threadKey` share one history.
-*/
+/**
+ * Run one conversational voice turn IN-DO: transcribe the utterance (or take the
+ * typed text), persist the user turn onto the SHARED agent thread, stream the
+ * assistant reply, and synthesize it sentence-by-sentence back to the client —
+ * TTS overlapping generation, both cancellable by a barge-in `signal`.
+ *
+ * This is NOT the replay-durable Workflow tool-loop: a voice turn is
+ * conversational only (no tools in v1) and not replay-safe. Persistence stays
+ * idempotent by `voice:{connectionId}:{turn}:{role}` message keys so a resent
+ * frame never duplicates a row; the thread tables are the same ones the durable
+ * agent loop and `useAgentChat` read, so a voice session and a text session on
+ * the same `threadKey` share one history.
+ * @experimental
+ */
 declare const runVoiceTurn: (options: RunVoiceTurnOptions) => Promise<VoiceTurnResult>;
-/** Parse the JSON identity envelope forwarded on the `x-lunora-identity` upgrade header. */
 /** Structural subset of `DurableObjectState` the voice DO needs (typed locally for unit doubles). */
 interface VoiceSessionState {
   acceptWebSocket: (ws: WebSocket, tags?: string[]) => void;
@@ -641,20 +768,21 @@ interface VoiceSessionState {
   waitUntil?: (promise: Promise<unknown>) => void;
 }
 /**
-* A hibernatable-WebSocket Durable Object that runs an agent's real-time VOICE
-* session. One instance per `threadKey`: the client opens a WebSocket, streams
-* 16kHz mono PCM as binary frames, and marks utterance boundaries with a JSON
-* `{ type: "commit" }` control frame; the DO transcribes the utterance, streams
-* the agent's reply through the LLM, and synthesizes it back as MP3 binary
-* frames — all IN-DO. It SHARES the agent's `agent_threads`/`agent_messages`
-* tables through the same runtime dispatch seam the durable loop uses, so voice
-* and text turns interleave on one history.
-*
-* Codegen emits a thin subclass per voice-enabled agent (e.g.
-* `SupportVoiceDO extends VoiceSessionDO`, constructed with the agent
-* definition + its export name) bound under the agent's `VOICE_...` Durable
-* Object binding.
-*/
+ * A hibernatable-WebSocket Durable Object that runs an agent's real-time VOICE
+ * session. One instance per `threadKey`: the client opens a WebSocket, streams
+ * 16kHz mono PCM as binary frames, and marks utterance boundaries with a JSON
+ * `{ type: "commit" }` control frame; the DO transcribes the utterance, streams
+ * the agent's reply through the LLM, and synthesizes it back as MP3 binary
+ * frames — all IN-DO. It SHARES the agent's `agent_threads`/`agent_messages`
+ * tables through the same runtime dispatch seam the durable loop uses, so voice
+ * and text turns interleave on one history.
+ *
+ * Codegen emits a thin subclass per voice-enabled agent (e.g.
+ * `SupportVoiceDO extends VoiceSessionDO`, constructed with the agent
+ * definition + its export name) bound under the agent's `VOICE_...` Durable
+ * Object binding.
+ * @experimental
+ */
 declare class VoiceSessionDO {
   protected readonly agent: AgentDefinition;
   protected readonly ai: ReturnType<typeof createAi>;
@@ -664,6 +792,8 @@ declare class VoiceSessionDO {
   protected readonly streamGenerate: AgentStreamGenerate;
   protected readonly sttModel: string;
   protected readonly ttsModel: string;
+  /** Turn budget for one socket — see {@link DEFAULT_MAX_SESSION_TURNS}. */
+  private readonly maxSessionTurns;
   private readonly audioBuffers;
   private readonly bufferedBytes;
   private readonly controllers;
@@ -678,11 +808,11 @@ declare class VoiceSessionDO {
   /** Abort any in-flight turn + free the socket's buffers on error. Never throws. */
   webSocketError(ws: WebSocket): void;
   /**
-  * The runtime dispatch seam reaching the shared agent thread functions. When
-  * the socket carries a verified identity it is forwarded so the `agents:*`
-  * thread writes are attributed to the caller (RLS / row ownership) rather
-  * than the anonymous system dispatch.
-  */
+   * The runtime dispatch seam reaching the shared agent thread functions. When
+   * the socket carries a verified identity it is forwarded so the `agents:*`
+   * thread writes are attributed to the caller (RLS / row ownership) rather
+   * than the anonymous system dispatch.
+   */
   protected resolveRun(userId?: string, claims?: Record<string, unknown>): AgentRunFunction;
   /** Production STT seam: WAV-wrap the utterance and run the batch transcription model. */
   protected transcribe(pcm: Uint8Array): Promise<string>;
@@ -702,38 +832,41 @@ declare class VoiceSessionDO {
   private synthesizeWithSignal;
   /** Abort an in-flight turn and free a socket's transient buffers. */
   private cleanupSocket;
+  /** Close a socket that broke a session bound, swallowing an already-closed error (never throw from a handler). */
+  private closeSocket;
   /** Send a JSON control frame, swallowing a closed-socket error (never throw from a handler). */
   private send;
   /** Send a binary audio frame, swallowing a closed-socket error. */
   private sendAudio;
   /**
-  * Outbound backpressure: if the socket exposes `bufferedAmount`, yield in
-  * short polls until the send buffer drains below the cap so a slow client
-  * can't balloon DO memory. Bounded by {@link MAX_DRAIN_WAIT_MS} so a stuck
-  * socket never blocks a turn forever, and never throws (a socket without
-  * `bufferedAmount` resolves immediately).
-  */
+   * Outbound backpressure: if the socket exposes `bufferedAmount`, yield in
+   * short polls until the send buffer drains below the cap so a slow client
+   * can't balloon DO memory. Bounded by {@link MAX_DRAIN_WAIT_MS} so a stuck
+   * socket never blocks a turn forever, and never throws (a socket without
+   * `bufferedAmount` resolves immediately).
+   */
   private waitForSocketDrain;
 }
 /**
-* Compile a `defineAgent` definition into the workflow the generated
-* `&lt;Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
-*
-* ```ts
-* import LunoraWorkflow from "@lunora/workflow/do";
-* import { compileAgentWorkflow } from "@lunora/agent";
-* import { support } from "../agents.js";
-*
-* export class SupportAgentWorkflow extends LunoraWorkflow&lt;AgentRunInput, AgentRunResult> {
-*     public constructor(ctx: ConstructorParameters&lt;typeof LunoraWorkflow>[0], env: Record&lt;string, unknown>) {
-*         super(ctx, env, compileAgentWorkflow(support, "support"), "support");
-*     }
-* }
-* ```
-*
-* The workflow ctx supplies durability (`step.do`) and the Lunora dispatcher
-* (`run`); the loop supplies determinism (step naming + idempotent persists).
-*/
+ * Compile a `defineAgent` definition into the workflow the generated
+ * `<Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
+ *
+ * ```ts
+ * import LunoraWorkflow from "@lunora/workflow/do";
+ * import { compileAgentWorkflow } from "@lunora/agent";
+ * import { support } from "../agents.js";
+ *
+ * export class SupportAgentWorkflow extends LunoraWorkflow<AgentRunInput, AgentRunResult> {
+ *     public constructor(ctx: ConstructorParameters<typeof LunoraWorkflow>[0], env: Record<string, unknown>) {
+ *         super(ctx, env, compileAgentWorkflow(support, "support"), "support");
+ *     }
+ * }
+ * ```
+ *
+ * The workflow ctx supplies durability (`step.do`) and the Lunora dispatcher
+ * (`run`); the loop supplies determinism (step naming + idempotent persists).
+ * @experimental
+ */
 declare const compileAgentWorkflow: (agent: AgentDefinition, exportName: string, options?: {
   paths?: AgentFunctionPaths;
 }) => WorkflowDefinition<AgentRunInput, AgentRunResult>;