@lunora/agent 0.0.0 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,740 @@
+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";
+export { type AgentComponent, agentComponent, agentExtension } from "./component.mjs";
+import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
+export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.mjs";
+export { type BrowserToolInput, type BrowserToolOptions, type ContainerToolInput, type ContainerToolOptions, type FsToolInput, type FsToolOptions, browserTool, containerTool, fsTool } from "./sandbox.mjs";
+import { createAi } from '@lunora/ai';
+import { WorkflowDefinition } from '@lunora/workflow';
+import '@lunora/mail/inbound';
+import '@lunora/server';
+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.
+  */
+  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.
+  */
+  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.
+  */
+  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.
+  */
+  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.
+  */
+  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.
+*/
+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.
+*/
+declare const runAgentLoop: (options: AgentLoopOptions) => Promise<AgentRunResult>;
+/** Input the model provides to a minted `searchMemory` tool. */
+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. */
+interface AgentMemoryReadInput {
+  /** The chunk/document id from a `searchMemory` hit. */
+  id: string;
+}
+/** One ranked hit in a {@link AgentMemorySearchResult}. */
+interface AgentMemorySearchHit {
+  id: string;
+  score: number;
+  /** The chunk text, truncated to the source's `snippetChars`. */
+  snippet: string;
+  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.
+*/
+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.
+*/
+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.
+*/
+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.
+*/
+declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<AgentSubToolInput, string>;
+/** One step of a tool-composition script — call `tool` with `input`, bind the result to `id`. */
+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. */
+  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. */
+interface ToolScript {
+  steps: ToolScriptStep[];
+}
+/** The result of running a {@link ToolScript}: each step's output plus the last one. */
+interface ToolScriptResult {
+  final: unknown;
+  results: ReadonlyArray<{
+    id: string;
+    output: unknown;
+  }>;
+}
+/** Author-supplied config for {@link codeTool}. */
+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.
+  */
+  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`.
+* ```
+*/
+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.
+*/
+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 const defineAgent: (config: AgentConfig) => AgentDefinition;
+/** Runtime brand check for a {@link AgentDefinition}. */
+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 const defineAgentTool: <Input, Output>(config: AgentToolConfig<Input, Output>) => AgentToolDefinition<Input, Output>;
+/** Author-supplied config for {@link functionTool}. */
+interface FunctionToolOptions<Input> {
+  /** What the tool does — shown to the model (the model decides from it). */
+  description: string;
+  /** The input schema shown to the model (a zod schema or `jsonSchema(...)`). */
+  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.
+*/
+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`). */
+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.
+*/
+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.
+*/
+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.
+*/
+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.
+*/
+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`. */
+interface McpContentPart {
+  [key: string]: unknown;
+  text?: string;
+  type: string;
+}
+/** The result of an MCP `tools/call` — the structural subset the adapter reads. */
+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. */
+interface McpToolInfo {
+  description?: string;
+  inputSchema: {
+    [key: string]: unknown;
+    properties?: Record<string, object>;
+    required?: string[];
+    type: "object";
+  };
+  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.
+*/
+interface McpClientLike {
+  callTool: (params: {
+    arguments?: Record<string, unknown>;
+    name: string;
+  }) => Promise<McpCallResult>;
+  close?: () => Promise<void>;
+  connect?: (transport: unknown) => Promise<void>;
+  listTools: (params?: unknown) => Promise<{
+    tools: ReadonlyArray<McpToolInfo>;
+  }>;
+}
+/** Options for {@link mcpTools}. */
+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.
+  */
+  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.
+  */
+  command?: string;
+  /** Identify this client to the server on connect. Default `"lunora-agent"`. */
+  name?: string;
+  /** 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). */
+  prefix?: string;
+  /** Transport for an `url`: Streamable HTTP (default) or legacy SSE. */
+  transport?: "http" | "sse";
+  /** The HTTP(S) endpoint of a Streamable-HTTP (or SSE) MCP server. */
+  url?: string;
+  /** Client version reported to the server on connect. Default `"0.0.0"`. */
+  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.
+*/
+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).
+*/
+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`).
+*/
+declare const buildModelMessages: (options: {
+  history: ReadonlyArray<AgentMessageRow>;
+  instructions?: string;
+  memoryContext?: string;
+  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.
+*/
+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.
+*/
+declare const SANDBOX_MODULE = "sandbox";
+/** The dispatch path of the sandbox runtime action (an internal action). */
+declare const SANDBOX_INVOKE_PATH: "sandbox:invoke";
+/** Default dispatch paths of the agent runtime functions. */
+declare const DEFAULT_AGENT_FUNCTION_PATHS: AgentFunctionPaths;
+/** Mint a dispatchable function reference from a path (or pass one through). */
+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 const defineSkill: (config: SkillConfig) => SkillDefinition;
+/** Runtime brand check for a {@link SkillDefinition}. */
+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.
+*/
+type VoiceServerFrame = {
+  audioFormat: "mp3" | "wav";
+  type: "ready";
+} | {
+  message: string;
+  type: "error";
+} | {
+  text: string;
+  type: "assistant_delta";
+} | {
+  text: string;
+  type: "assistant_done";
+} | {
+  text: string;
+  type: "user_transcript";
+} | {
+  type: "interrupted";
+};
+/** A control frame the client sends the server (audio rides separate binary frames). */
+type VoiceClientFrame = {
+  text: string;
+  type: "text";
+} | {
+  type: "commit";
+} | {
+  type: "interrupt";
+};
+/** A synthesized-audio source the TTS seam yields — normalized to bytes by {@link toByteIterable}. */
+type VoiceAudioSource = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | Uint8Array;
+/** Transcribe one buffered utterance (16kHz mono 16-bit PCM) to text. */
+type VoiceTranscribe = (pcm: Uint8Array) => Promise<string>;
+/** Synthesize one sentence to an audio byte stream; honors `signal` for barge-in. */
+type VoiceSynthesize = (text: string, signal: AbortSignal) => Promise<VoiceAudioSource>;
+/** Send a JSON control frame to the client. */
+type VoiceSend = (frame: VoiceServerFrame) => void;
+/** Send a binary audio frame to the client. */
+type VoiceSendAudio = (bytes: Uint8Array) => void;
+/** The outcome of one voice turn. */
+interface VoiceTurnResult {
+  /** The final assistant text (may be partial if `interrupted`). */
+  assistantText: string;
+  /** Whether a barge-in aborted the turn mid-stream. */
+  interrupted: boolean;
+  /** The transcribed (or typed) user text — empty when the utterance was silence. */
+  userText: string;
+}
+/** Options for one {@link runVoiceTurn}. */
+interface RunVoiceTurnOptions {
+  /** The agent whose thread + models back this session. */
+  agent: AgentDefinition;
+  /** Stable per-socket id — the message-key prefix that keeps persisted rows idempotent. */
+  connectionId: string;
+  /** The Worker env (resolves a dynamic `instructions` thunk). */
+  env: Record<string, unknown>;
+  /** The agent's `lunora/agents.ts` export name (thread attribution). */
+  exportName: string;
+  /** Thread owner (the socket's verified identity), passed through to `ensureThread`. */
+  owner?: string;
+  /** Dispatch paths of the shared agent thread functions. */
+  paths: AgentFunctionPaths;
+  /** Buffered utterance PCM — transcribed via `transcribe` unless `text` is set. */
+  pcm?: Uint8Array;
+  /** The runtime dispatch seam reaching the agent's thread functions (`agents:*`). */
+  run: AgentRunFunction;
+  /** Send a JSON control frame. */
+  send: VoiceSend;
+  /** Send a binary audio frame. */
+  sendAudio: VoiceSendAudio;
+  /** Barge-in signal — aborts client output + TTS mid-turn. */
+  signal: AbortSignal;
+  /** The streaming LLM-turn seam (production wires AI SDK `streamText`). */
+  streamGenerate: AgentStreamGenerate;
+  /** Synthesize a sentence to audio. */
+  synthesize: VoiceSynthesize;
+  /** Typed input — when set, STT is skipped and this is the user turn. */
+  text?: string;
+  /** The shared agent thread key. */
+  threadKey: string;
+  /** Transcribe buffered `pcm` (unused when `text` is set). */
+  transcribe: VoiceTranscribe;
+  /** Monotonic per-connection turn index — part of the idempotent message keys. */
+  turn: number;
+  /** 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.
+*/
+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;
+  getWebSockets: (tag?: string) => WebSocket[];
+  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.
+*/
+declare class VoiceSessionDO {
+  protected readonly agent: AgentDefinition;
+  protected readonly ai: ReturnType<typeof createAi>;
+  protected readonly env: Record<string, unknown>;
+  protected readonly exportName: string;
+  protected readonly paths: AgentFunctionPaths;
+  protected readonly streamGenerate: AgentStreamGenerate;
+  protected readonly sttModel: string;
+  protected readonly ttsModel: string;
+  private readonly audioBuffers;
+  private readonly bufferedBytes;
+  private readonly controllers;
+  private readonly state;
+  constructor(state: VoiceSessionState, env: Record<string, unknown>, agent: AgentDefinition, exportName: string);
+  /** HTTP entry — only a WebSocket upgrade carrying a `threadKey` is accepted. */
+  fetch(request: Request): Response;
+  /** Hibernation message handler — never throws (a thrown handler is fatal to the socket). */
+  webSocketMessage(ws: WebSocket, message: ArrayBuffer | string): Promise<void>;
+  /** Abort any in-flight turn + free the socket's buffers on close. Never throws. */
+  webSocketClose(ws: WebSocket): void;
+  /** 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.
+  */
+  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>;
+  /** Production TTS seam: synthesize one sentence to a normalized audio source; `signal` aborts an in-flight barge-in. */
+  protected synthesize(text: string, signal?: AbortSignal): Promise<VoiceAudioSource>;
+  /** Route a JSON control frame (`commit` / `interrupt` / `text`). */
+  private handleControl;
+  /** Append a binary audio frame to the socket's utterance buffer (bounded). */
+  private bufferAudio;
+  /** Concatenate + clear the socket's buffered utterance. */
+  private drainAudio;
+  /** Execute a turn under a fresh abort controller, advancing the socket's turn index. */
+  private runTurn;
+  /** Synthesize a greeting on connect and persist it as the thread's opening assistant turn. */
+  private speakGreeting;
+  /** Bridge the pipeline's `(text, signal)` synthesize seam onto the class TTS method, forwarding the barge-in signal. */
+  private synthesizeWithSignal;
+  /** Abort an in-flight turn and free a socket's transient buffers. */
+  private cleanupSocket;
+  /** 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).
+  */
+  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).
+*/
+declare const compileAgentWorkflow: (agent: AgentDefinition, exportName: string, options?: {
+  paths?: AgentFunctionPaths;
+}) => WorkflowDefinition<AgentRunInput, AgentRunResult>;
+export { AGENT_MODULE, type AgentAsToolOptions, type AgentBindingSpec, type AgentConfig, type AgentDefinition, type AgentFunctionPaths, type AgentFunctionReference, type AgentGenerate, type AgentHandle, type AgentLoopOptions, type AgentMemoryReadInput, type AgentMemorySearchHit, type AgentMemorySearchInput, type AgentMemorySearchResult, type AgentMessageRow, type AgentModelInput, type AgentRunFunction, type AgentRunInput, type AgentRunResult, type AgentStepLike, type AgentStreamGenerate, type AgentSubToolInput, type AgentTokenSink, type AgentToolConfig, type AgentToolDefinition, type AnyAgentTool, type CodeToolOptions, DEFAULT_AGENT_FUNCTION_PATHS, type FunctionToolOptions, type McpCallResult, type McpClientLike, type McpContentPart, type McpToolInfo, type McpToolsOptions, type RunVoiceTurnOptions, SANDBOX_INVOKE_PATH, SANDBOX_MODULE, type SkillConfig, type SkillDefinition, type ToolScript, type ToolScriptResult, type ToolScriptStep, type VoiceAudioSource, type VoiceClientFrame, type VoiceSend, type VoiceSendAudio, type VoiceServerFrame, VoiceSessionDO, type VoiceSynthesize, type VoiceTranscribe, type VoiceTurnResult, adaptMcpResult, agentAsTool, buildModelMessages, codeTool, collectAgenticMemoryTools, compileAgentWorkflow, createAgentContext, createAgentGenerate, createEpisodeExtract, createGraphExtract, createStreamGenerate, defineAgent, defineAgentTool, defineSkill, functionTool, isAgentDefinition, isSkillDefinition, mcpTools, resolveAgentModel, runAgentLoop, runVoiceTurn, splitForCompaction, toFunctionReference, toSearchResults };