@theokit/agents 10.0.0 → 11.0.0

package/dist/client-react.js

@@ -2,7 +2,7 @@ import {
   AgentClient,
   HttpTransport,
   isAgentHandle
-} from "./chunk-M6HMASZC.js";
+} from "./chunk-7PNUTDBQ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -41,6 +41,7 @@ function useAgent(binding, options = {}) {
     thread: state.thread,
     status: state.status,
     error: state.error,
+    pendingApprovals: state.pendingApprovals,
     send: client.send,
     abort: client.abort,
     reset: client.reset,

package/dist/client-react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client/use-agent.ts"],"mappings":";;;;;;;;;;AACA,SAASA,SAASC,QAAQC,4BAA4B;AAyE/C,SAASC,SACdC,SACAC,UAA2B,CAAC,GAAC;AAI7B,QAAMC,aAAaC,OAAOF,OAAAA;AAC1BC,aAAWE,UAAUH;AAIrB,MAAII;AACJ,MAAI,OAAOL,YAAY,SAAUK,OAAML;WAC9BM,cAAcN,OAAAA,EAAUK,OAAML,QAAQO;AAE/C,QAAMC,kBAAkBH,OAAOL;AAE/B,QAAMS,SAASC;IACb,MACE,IAAIC;MACFN,QAAQO,SACJ,IAAIC,cAAc;QAChBR;QACAS,SAAS,6BAAMZ,WAAWE,QAAQU,SAAzB;QACTC,OAAOb,WAAWE,QAAQW;MAC5B,CAAA,IACCf;;MAEL,MAAA;AACE,cAAMgB,MAAMd,WAAWE,QAAQa;AAC/B,eAAO,OAAOD,QAAQ,aAAaA,IAAAA,IAAQA;MAC7C;IAAA;;;IAIJ;MAACR;;EAAgB;AAGnB,QAAMU,QAAQC,qBAAqBV,OAAOW,WAAWX,OAAOY,aAAaZ,OAAOY,WAAW;AAE3F,SAAO;IACLC,UAAUJ,MAAMI;IAChBC,QAAQL,MAAMK;IACdC,QAAQN,MAAMM;IACdC,OAAOP,MAAMO;IACbC,MAAMjB,OAAOiB;IACbC,OAAOlB,OAAOkB;IACdC,OAAOnB,OAAOmB;IACdC,SAASpB,OAAOoB;IAChBC,WAAWrB,OAAOqB;EACpB;AACF;AAnDgB/B;","names":["useMemo","useRef","useSyncExternalStore","useAgent","binding","options","optionsRef","useRef","current","api","isAgentHandle","path","bindingIdentity","client","useMemo","AgentClient","undefined","HttpTransport","headers","fetch","ctx","context","state","useSyncExternalStore","subscribe","getSnapshot","messages","thread","status","error","send","abort","reset","approve","reconnect"]}
+{"version":3,"sources":["../src/client/use-agent.ts"],"mappings":";;;;;;;;;;AACA,SAASA,SAASC,QAAQC,4BAA4B;AA+F/C,SAASC,SACdC,SACAC,UAA2B,CAAC,GAAC;AAI7B,QAAMC,aAAaC,OAAOF,OAAAA;AAC1BC,aAAWE,UAAUH;AAIrB,MAAII;AACJ,MAAI,OAAOL,YAAY,SAAUK,OAAML;WAC9BM,cAAcN,OAAAA,EAAUK,OAAML,QAAQO;AAE/C,QAAMC,kBAAkBH,OAAOL;AAE/B,QAAMS,SAASC;IACb,MACE,IAAIC;MACFN,QAAQO,SACJ,IAAIC,cAAc;QAChBR;QACAS,SAAS,6BAAMZ,WAAWE,QAAQU,SAAzB;QACTC,OAAOb,WAAWE,QAAQW;MAC5B,CAAA,IACCf;;MAEL,MAAA;AACE,cAAMgB,MAAMd,WAAWE,QAAQa;AAC/B,eAAO,OAAOD,QAAQ,aAAaA,IAAAA,IAAQA;MAC7C;IAAA;;;IAIJ;MAACR;;EAAgB;AAGnB,QAAMU,QAAQC,qBAAqBV,OAAOW,WAAWX,OAAOY,aAAaZ,OAAOY,WAAW;AAE3F,SAAO;IACLC,UAAUJ,MAAMI;IAChBC,QAAQL,MAAMK;IACdC,QAAQN,MAAMM;IACdC,OAAOP,MAAMO;IACbC,kBAAkBR,MAAMQ;IACxBC,MAAMlB,OAAOkB;IACbC,OAAOnB,OAAOmB;IACdC,OAAOpB,OAAOoB;IACdC,SAASrB,OAAOqB;IAChBC,WAAWtB,OAAOsB;EACpB;AACF;AApDgBhC;","names":["useMemo","useRef","useSyncExternalStore","useAgent","binding","options","optionsRef","useRef","current","api","isAgentHandle","path","bindingIdentity","client","useMemo","AgentClient","undefined","HttpTransport","headers","fetch","ctx","context","state","useSyncExternalStore","subscribe","getSnapshot","messages","thread","status","error","pendingApprovals","send","abort","reset","approve","reconnect"]}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { b as AgentTransport, A as ApprovalDecision } from './agent-handle-Dgi4ZGbg.js';
-export { c as AgentClient, d as AgentClientOptions, e as AgentClientState, a as AgentHandle, f as ApprovalAbortedError, C as ChannelPushSource, g as ChannelTransport, h as ChannelTransportOptions, i as ChannelTurnHandlers, I as InProcessApprovalRequestLike, j as InProcessAwaitApproval, k as InProcessRunInput, l as InProcessRunner, m as InProcessTransport, n as InProcessTransportOptions, R as RequestContext, U as UseAgentStatus, o as agentHandle, p as isAgentHandle } from './agent-handle-Dgi4ZGbg.js';
+import { b as AgentTransport, A as ApprovalDecision } from './agent-handle-rEWdERuv.js';
+export { c as AgentClient, d as AgentClientOptions, e as AgentClientState, a as AgentHandle, f as AgentStreamInterruptedError, g as ApprovalAbortedError, C as ChannelPushSource, h as ChannelTransport, i as ChannelTransportOptions, j as ChannelTurnHandlers, I as InProcessApprovalRequestLike, k as InProcessAwaitApproval, l as InProcessRunInput, m as InProcessRunner, n as InProcessTransport, o as InProcessTransportOptions, P as PendingApproval, R as RequestContext, U as UseAgentStatus, p as agentHandle, q as isAgentHandle } from './agent-handle-rEWdERuv.js';
 import { WireTransport, WireChunk, WireMessage } from '@theokit/presenter/wire';
 import '@theokit/sdk/errors';
 
@@ -16,6 +16,48 @@ interface HttpTransportOptions {
     headers?: HeadersResolver;
     /** Override fetch (primarily for tests / non-browser hosts) — static; resolved once at construction. */
     fetch?: typeof fetch;
+    /**
+     * Where the server-minted run id lives between requests — the key `reconnectToStream` needs
+     * (usetheokit/theokit#387).
+     *
+     * Defaults to an in-memory cell, which is what this transport always did and what keeps a
+     * reconnect working within one page lifetime. That default is also why a RELOAD could not
+     * reconnect: the new page builds a fresh transport with an empty cell, so `reconnectToStream`
+     * returns `null` before it reaches the network — while the server still holds the run in its
+     * cache and would replay it.
+     *
+     * The medium is the CONSUMER's decision, not this package's. `sessionStorage` matches a run's
+     * lifetime better than `localStorage`, and either would be a client library writing to browser
+     * storage nobody asked it to write to, with privacy and SSR consequences. So the seam is injected
+     * and the package stores nothing it was not handed a place for:
+     *
+     * ```ts
+     * new HttpTransport({
+     *   api: '/api/agents/support',
+     *   runIdStore: {
+     *     get: () => sessionStorage.getItem('theo.runId') ?? undefined,
+     *     set: (id) => {
+     *       if (id === undefined) sessionStorage.removeItem('theo.runId')
+     *       else sessionStorage.setItem('theo.runId', id)
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Deliberately NOT included: reconnecting automatically on load. This makes a cached run
+     * REACHABLE; reaching for it is a product decision nobody has asked for.
+     */
+    runIdStore?: RunIdStore;
+}
+/**
+ * Where the reconnect key is kept.
+ *
+ * Two methods rather than a storage object, so a consumer can back it with `sessionStorage`, a
+ * cookie, a router param, or a test double — the transport never learns which.
+ */
+interface RunIdStore {
+    get: () => string | undefined;
+    set: (runId: string | undefined) => void;
 }
 /**
  * M41 (ADR-0050 D3) — `ChatTransport` over the web agent path.
@@ -68,13 +110,55 @@ type UIMessageChunk = WireChunk;
  * `onMessage` is invoked on every reconstruction step with the latest snapshot of the assistant
  * message, so a caller (the `useAgent` hook) can render streaming updates.
  */
-declare function consumeUIMessageStream(response: Response, onMessage: (message: UIMessage) => void): Promise<void>;
+declare function consumeUIMessageStream(response: Response, onMessage: (message: UIMessage) => void): Promise<ChunkStreamOutcome>;
 /**
  * A UIMessageStream SSE `Response` → `ReadableStream<UIMessageChunk>`. This is precisely what a
  * `ChatTransport.sendMessages` returns, so `HttpTransport` builds on it directly. A body-less
  * response yields an empty stream.
  */
 declare function responseToChunkStream(response: Response): Promise<ReadableStream<UIMessageChunk>>;
+/**
+ * How a chunk stream ENDED — theokit#384.
+ *
+ * ## Why this exists at all
+ *
+ * The reader used to return `void`, which left its caller exactly two outcomes to choose between:
+ * it threw, or it did not. A stream that simply STOPS — a socket closed mid-run — throws nothing,
+ * so `AgentClient` read "did not throw" as "the agent finished" and settled a truncated answer in
+ * `status: 'done'` with no error. The information needed to tell the two apart was on the wire and
+ * nothing carried it out of the reader.
+ *
+ * ## What counts as an ending, and what does not
+ *
+ * The stream's own terminal chunk, `finish`, is the marker — NOT the SSE `[DONE]` sentinel:
+ *
+ *  - `finish` is emitted by `presentUIMessageStream` on EVERY framework path, including the error
+ *    path, so it is the one terminator that exists on all three transports. `[DONE]` is written
+ *    only by the durable SSE encoder, so an in-process or channel stream has none to look for.
+ *  - `[DONE]` is also the WEAKER claim of the two. `durableUiMessageStreamResponse` flushes it from
+ *    a `finally` even when the source aborted mid-run, so a run cut on the SERVER carries `[DONE]`
+ *    and no `finish`. Keying on `finish` reports that case too; keying on `[DONE]` would miss it.
+ *
+ * `finish` also cannot lie in the other direction: nothing can truncate a run after its terminal
+ * chunk has been written, so a stream that carried one carried a complete turn even if the socket
+ * died a byte later.
+ */
+interface ChunkStreamOutcome {
+    /**
+     * `true` iff the terminal `finish` chunk crossed before the stream ended.
+     *
+     * `false` means the producer stopped talking mid-run: a dropped connection, a killed server, a
+     * proxy timeout. It does NOT mean the run failed — a failure arrives as an `error` chunk, which
+     * the reader raises instead of returning.
+     */
+    readonly terminated: boolean;
+    /**
+     * How many chunks crossed. Diagnostic only, and it earns its place: it separates "the server
+     * accepted the request and then said nothing" (`0`) from "the answer was cut mid-sentence"
+     * (`n > 0`), which are different failures with different first suspects.
+     */
+    readonly chunksReceived: number;
+}
 /**
  * Read a `ReadableStream<UIMessageChunk>` into reconstructed assistant messages. Shared by
  * {@link consumeUIMessageStream} (Response path) and the framework-agnostic `AgentClient` store
@@ -84,8 +168,18 @@ declare function responseToChunkStream(response: Response): Promise<ReadableStre
  * A provider failure (401/429/5xx) arrives as a `{ type: 'error', errorText }` chunk rather than a
  * thrown rejection — both the in-process runner and the SSE path emit it as data. The reader
  * rejects on it, so `AgentClient.#drive`'s existing catch surfaces it (`status='error'`).
+ *
+ * theokit#384 — it also RETURNS how the stream ended. See {@link ChunkStreamOutcome}.
+ *
+ * The observation happens in a `TransformStream` rather than inside `readMessageStream`, because a
+ * bare `finish` reconstructs to nothing: the reader yields a snapshot for it only when it carries
+ * `messageMetadata`, so the terminal chunk is invisible at the message level by design (measured
+ * against the ai-sdk oracle — see `read-message-stream.ts`). Watching the CHUNKS is the only place
+ * the terminator is observable without changing what the reader emits. The cost is one queue hop
+ * per chunk on a path that already spends 3.274 ms per emit deriving the timeline (M86) — real,
+ * and three orders of magnitude below the work it sits next to.
  */
-declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<void>;
+declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<ChunkStreamOutcome>;
 
 /**
  * M41/M42 — extract the turn text from the last user message's text parts. Shared by the transports
@@ -94,4 +188,4 @@ declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMe
  */
 declare function extractLastUserText(messages: readonly WireMessage[]): string;
 
-export { AgentTransport, ApprovalDecision, type HeadersResolver, HttpTransport, type HttpTransportOptions, consumeChunkStream, consumeUIMessageStream, extractLastUserText, responseToChunkStream };
+export { AgentTransport, ApprovalDecision, type ChunkStreamOutcome, type HeadersResolver, HttpTransport, type HttpTransportOptions, consumeChunkStream, consumeUIMessageStream, extractLastUserText, responseToChunkStream };

package/dist/client.js

@@ -1,5 +1,6 @@
 import {
   AgentClient,
+  AgentStreamInterruptedError,
   ApprovalAbortedError,
   ChannelTransport,
   HttpTransport,
@@ -10,10 +11,11 @@ import {
   extractLastUserText,
   isAgentHandle,
   responseToChunkStream
-} from "./chunk-M6HMASZC.js";
+} from "./chunk-7PNUTDBQ.js";
 import "./chunk-Z4QWC7IK.js";
 export {
   AgentClient,
+  AgentStreamInterruptedError,
   ApprovalAbortedError,
   ChannelTransport,
   HttpTransport,

package/dist/config.d.ts

@@ -191,7 +191,7 @@ declare class TrustStore {
      * draft called them synchronously and `trust()` returned before the bytes landed, so an immediate
      * `read()` saw an empty store. Same shape as the M71 pointer bug, and same cause — the SDK's
      * `.d.ts` does not declare these, so nothing at compile time says they return a Promise
-     * (usetheodev/theokit-sdk#280).
+     * (usetheokit/theokit-sdk#280).
      */
     trust(record: TrustRecord): Promise<void>;
     /**
@@ -310,7 +310,7 @@ interface LoadInstructionTreeInput {
      * Which files to load. Defaults to the conventional two.
      *
      * A list matches basenames exactly; a predicate answers the question a list cannot. A rules
-     * DIRECTORY — `.claude/rules/`, `.cursor/rules/`, `.theokit/rules/` — holds files the caller
+     * DIRECTORY —, `.cursor/rules/`, `.theokit/rules/` — holds files the caller
      * cannot name in advance, because the user chooses the names. With only a list on offer, the
      * closest consumer wrote its own 112-line walk (budget, depth ceiling, cycle guard and all) to
      * ask `entry.endsWith('.md')`. The walk was ours; only the question was theirs.

package/dist/config.js

@@ -1,6 +1,6 @@
 import {
   ensureSecureDir
-} from "./chunk-QXGSF6WX.js";
+} from "./chunk-D2EFYZBV.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -154,7 +154,7 @@ var TrustStore = class {
   * draft called them synchronously and `trust()` returned before the bytes landed, so an immediate
   * `read()` saw an empty store. Same shape as the M71 pointer bug, and same cause — the SDK's
   * `.d.ts` does not declare these, so nothing at compile time says they return a Promise
-  * (usetheodev/theokit-sdk#280).
+  * (usetheokit/theokit-sdk#280).
   */
   async trust(record) {
     ensureSecureDir(this.file);

package/dist/{define-agent-BO5QSjV8.d.ts → define-agent-BnH1MBxs.d.ts}

@@ -1,6 +1,7 @@
 import { TrustPosture, SettingSource, CustomTool, MemorySettings } from '@theokit/sdk';
 import { z } from 'zod';
-import { R as ReasoningEffort, G as Guardrail, H as HumanInTheLoopOptions, S as SkillsSelection, M as McpServersMap, C as CompiledAgentOptions } from './agent-compiler-CIPQkehU.js';
+import { G as Guardrail, S as SkillsSelection, C as CompiledAgentOptions } from './agent-compiler-tetgj6zR.js';
+import { R as ReasoningEffort, H as HumanInTheLoopOptions, M as McpServersMap } from './types-C16Wuh9E.js';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 
@@ -127,6 +128,20 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
     system?: string;
     /** Extended-thinking effort. */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * theokit#363 — hard ceiling on the agent's tool-calling turns within ONE run. Reaching it ends
+     * the turn instead of letting the model keep calling tools; absent ⇒ the SDK's own ceiling (8).
+     *
+     * Named `maxIterations`, not `maxSteps`, because the concept already has exactly one name here —
+     * `@Agent({ maxIterations })`, `@MainLoop({ maxIterations })`, `AgentRunner.stream({ maxIterations })`,
+     * `delegate({ maxIterations })` — and one name in the SDK it lowers to (`SendOptions.maxIterations`).
+     * A second name would be the only place needing translation, and the translation is invisible where
+     * it costs most: the SDK rejects an invalid value with a message naming `SendOptions.maxIterations`,
+     * which an author who typed `.maxSteps()` has no way to connect to what they wrote. Familiarity
+     * argues for the ai-sdk spelling, but ai-sdk's own name is `stopWhen: stepCountIs(n)` — borrowing
+     * "steps" would buy recognition of a word, not of an API.
+     */
+    maxIterations?: number;
     /**
      * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
      * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are

package/dist/{delegation-scoring-CDvtrYKd.d.ts → delegation-scoring-CQtF2Zaf.d.ts}

@@ -1,27 +1,350 @@
 import { PluginsSettings, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
-import { C as CompiledAgentOptions, a as MainLoopMeta, b as CompiledTool } from './agent-compiler-CIPQkehU.js';
+import { C as CompiledAgentOptions, a as CompiledTool } from './agent-compiler-tetgj6zR.js';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 import { z } from 'zod';
+import { b as MainLoopMeta } from './types-C16Wuh9E.js';
+import { WireChunk } from '@theokit/presenter/wire';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 
 /**
- * SSE streaming handler — Web Standard Response with ReadableStream.
+ * Typed discriminated union for agent SSE stream events.
  *
- * Per ADR D4: SSE is the v1 transport.
- * Per EC-2: uses ReadableStream with controller.enqueue() instead of res.write().
- * Works natively on Node, Bun, Deno, CF Workers.
+ * Every event has a `type` field for discrimination.
+ * Clients narrow via `if (event.type === 'text_delta') event.content`.
  */
+/** Partial text content from the LLM. */
+interface TextDeltaEvent {
+    type: 'text_delta';
+    content: string;
+}
+/** Agent started a tool call. */
+interface ToolCallEvent {
+    type: 'tool_call';
+    callId: string;
+    toolName: string;
+    input: unknown;
+}
+/**
+ * Tool-call arguments streaming in incrementally (theokit-sdk#70). Emitted repeatedly as the
+ * model generates a tool call's args, BEFORE they are committed. The same `callId` correlates to
+ * the later `tool_call` (args committed) and `tool_result`. Consumers opt in to render tool-input
+ * progressively; those that don't simply ignore this variant (it never replaces `tool_call`).
+ */
+interface PartialToolCallEvent {
+    type: 'partial_tool_call';
+    callId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Tool execution completed. */
+interface ToolResultEvent {
+    type: 'tool_result';
+    callId: string;
+    toolName: string;
+    output: string;
+    durationMs: number;
+    isError: boolean;
+}
+/** Extended thinking / reasoning (when model supports it). */
+interface ThinkingEvent {
+    type: 'thinking';
+    content: string;
+}
+/** Agent loop iteration. */
+interface IterationEvent {
+    type: 'iteration';
+    step: number;
+    totalSteps: number | null;
+}
+/** Human approval required before proceeding. */
+interface ApprovalRequiredEvent {
+    type: 'approval_required';
+    callId: string;
+    toolName: string;
+    question: string;
+    input?: unknown;
+    callbackUrl: string;
+    timeoutMs: number;
+    /** M20 — JSON-schema descriptor of the custom payload the approver may attach (optional). */
+    payloadSchema?: Record<string, unknown>;
+}
+/**
+ * The run is blocked awaiting user input or approval — theokit#141.
+ *
+ * The SDK's low-fidelity pause signal (`SDKRequestMessage`), distinct from {@link
+ * ApprovalRequiredEvent}. The latter is the framework's own, produced by `createHitlPlugin`, and
+ * carries everything an approval UI needs to be actionable. This one carries only the request id,
+ * because that is all the SDK provides — and it matters most exactly where the plugin is absent
+ * (the ACP/serving path of theokit#139), which is where a dropped pause reads to the user as a
+ * hang with no explanation.
+ *
+ * A consumer that cannot resolve the request should still SHOW that the run is waiting. Silence is
+ * the one response that is always wrong.
+ */
+interface InputRequestedEvent {
+    type: 'input_requested';
+    requestId: string;
+}
+/** Task-level milestone or summary — theokit#141. Both fields are optional at the source. */
+interface TaskProgressEvent {
+    type: 'task_progress';
+    status?: string;
+    text?: string;
+}
+/**
+ * Live output from a shell command the SDK is running — theokit#141.
+ *
+ * `event` is passed through opaquely because the SDK types it as `Record<string, unknown>`. The
+ * layer deliberately does not interpret or render it: guessing a shape here would be a second,
+ * weaker oracle over a payload whose real contract lives upstream.
+ */
+interface ShellOutputEvent {
+    type: 'shell_output';
+    event: Record<string, unknown>;
+}
+/** Agent encountered an error. */
+interface ErrorEvent {
+    type: 'error';
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Why a run stopped short of finishing on its own — theokit#379.
+ *
+ * ## Why it is an enum and not a `truncated: boolean`
+ *
+ * The two members demand OPPOSITE reactions from the caller, and a boolean cannot carry the
+ * difference:
+ *
+ *  - `'step_limit'` — the loop ran out of tool-calling turns while the model still wanted more.
+ *    The work is unfinished but progressing; re-sending is the sane continuation.
+ *  - `'no_progress'` — the doom-loop guard stopped the model repeating IDENTICAL tool calls. The
+ *    SDK's own wording: "a controlled stop, NOT a truncation to re-send". Re-sending repeats the
+ *    loop that was just cut.
+ *
+ * A caller that reads `truncated: true` and re-sends does the right thing in the first case and
+ * feeds the doom loop in the second.
+ *
+ * ## Why these spellings
+ *
+ * Both sides of the boundary had already agreed on them before this field existed: the framework's
+ * own `LoopFinishReason` (`../loop/loop-strategy.ts`) spells the outer-loop terminals `step_limit`
+ * and `no_progress`, and so does the SDK's continuation driver
+ * (`RunToCompletionResult.terminal: "done" | "step_limit" | "no_progress"`). Inventing a third
+ * vocabulary for the same two outcomes was the only way to get this wrong.
+ *
+ * ## Why there is no `'finished'` member
+ *
+ * A clean run carries NO `stopReason` at all — absence is the finished case. Stamping every
+ * ordinary turn with a new field would change what every existing consumer receives in order to
+ * describe the one case that was already correct. A consumer that has never heard of `stopReason`
+ * therefore keeps receiving byte-identical frames for every run that finishes on its own, and for a
+ * truncated one it receives one extra optional key it ignores — the same degradation the ai-sdk
+ * `finish` chunk already allows, since its `messageMetadata` is `unknown`.
+ */
+type AgentStopReason = 'step_limit' | 'no_progress';
+/** Agent completed with a final result. */
+interface DoneEvent {
+    type: 'done';
+    result: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        /** V4-O: SDK reasoning/cache token buckets (0 when the provider omits them). */
+        reasoningTokens?: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    durationMs: number;
+    /** Total cost in USD for this agent run (EC-2: added for budget tracking). */
+    cost?: number;
+    /**
+     * theokit#379 — why the run stopped, when it did NOT stop because the agent was done.
+     *
+     * ABSENT on a clean finish. Present only when the SDK reports that the run was cut: the terminal
+     * frame is a `done` either way (a reached ceiling is not an error — see `sdk-adapter.ts`'s
+     * `applyStepCeiling`), so without this field a cut run and a finished one are the same event.
+     *
+     * Read from `RunResult.stoppedByDoomLoop` / `RunResult.stoppedAtIterationLimit` at the adapter
+     * boundary. See {@link AgentStopReason} for why the caller needs to tell the two apart.
+     */
+    stopReason?: AgentStopReason;
+    /**
+     * The model this turn actually ran on — the EFFECTIVE id, not the declared one.
+     *
+     * It is resolved at the one place that knows: `createSdkAgentStream`, where
+     * `overrides.model ?? compiled.model ?? 'openai/gpt-4o-mini'` is decided. A consumer reading
+     * `CompiledAgentOptions.model` instead would be wrong twice — it misses a per-run override, and
+     * it reads `undefined` for an agent that declared no model and still ran one.
+     *
+     * Tokens are on this event already, and tokens alone convert to no cost: price is per model.
+     * This is the other half of that question, and the reason it travels rather than staying inside
+     * the adapter (usetheokit/theokit#368's fifth criterion).
+     *
+     * Optional so a producer that predates it — or one building a `done` from a source with no model
+     * to report — degrades to absence rather than to a fabricated id.
+     */
+    model?: string;
+}
+/**
+ * Per-turn usage the translator attaches to the ai-sdk `finish` chunk's `messageMetadata`, so it
+ * lands on the reconstructed assistant `UIMessage.metadata` on the client (via `readUIMessageStream`)
+ * with NO extra header/store wiring. It is the seam that lets a surface (a TUI status bar, a web
+ * cost meter) show real tokens/cost for the turn it just streamed. Mirrors `DoneEvent`'s usage/cost
+ * (the authoritative totals the SDK reports at turn end) plus the wall-clock `durationMs`.
+ */
+interface AgentTurnMetadata {
+    usage: DoneEvent['usage'];
+    /** Total cost in USD for the turn (present iff the SDK reported it). */
+    cost?: number;
+    durationMs: number;
+    /**
+     * theokit#379 — mirrors {@link DoneEvent.stopReason} so a surface that only ever sees the wire
+     * (a web client reading `UIMessage.metadata`, the observability translator reading the `finish`
+     * chunk) can tell a cut turn from a finished one without a second transport. Absent on a clean
+     * finish, exactly as on `DoneEvent`.
+     */
+    stopReason?: AgentStopReason;
+    /**
+     * Mirrors {@link DoneEvent.model} — the model the turn ran on, carried to whoever only ever sees
+     * the wire. The observability translator is the caller that needs it: it reads the `finish`
+     * chunk and records the model beside the token counts, which is what makes a cost answerable
+     * from a trace at all. Absent when the producer reported none.
+     */
+    model?: string;
+}
+/** Agent run started. */
+interface RunStartedEvent {
+    type: 'run_started';
+    runId: string;
+    agentName: string;
+    model?: string;
+}
+/** Artifact generation started (code, document, diagram). */
+interface ArtifactStartEvent {
+    type: 'artifact_start';
+    artifactId: string;
+    mimeType: string;
+    filename?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Artifact content chunk (streamable artifacts). */
+interface ArtifactChunkEvent {
+    type: 'artifact_chunk';
+    artifactId: string;
+    chunk: string;
+    isLast: boolean;
+}
+/** Real-time state update from @Observable channels. */
+interface StateUpdateEvent {
+    type: 'state_update';
+    channel: string;
+    data: unknown;
+}
+/** Checkpoint saved (resumable agents). */
+interface CheckpointSavedEvent {
+    type: 'checkpoint_saved';
+    checkpointId: string;
+    step: number;
+    resumeToken: string;
+}
+/** File edit produced by a code assistant tool. */
+interface FileEditEvent {
+    type: 'file_edit';
+    file: string;
+    format: 'search-replace' | 'unified-diff' | 'full-file' | 'line-range';
+    search?: string;
+    replace?: string;
+    content?: string;
+    diff?: string;
+    startLine?: number;
+    endLine?: number;
+}
+/** Discriminated union of all agent stream events. */
+type AgentStreamEvent = RunStartedEvent | TextDeltaEvent | ToolCallEvent | PartialToolCallEvent | ToolResultEvent | ThinkingEvent | IterationEvent | ApprovalRequiredEvent | InputRequestedEvent | TaskProgressEvent | ShellOutputEvent | ArtifactStartEvent | ArtifactChunkEvent | StateUpdateEvent | CheckpointSavedEvent | FileEditEvent | ErrorEvent | DoneEvent;
+/** Type guard helpers. */
+declare function isTextDelta(e: AgentStreamEvent): e is TextDeltaEvent;
+declare function isToolCall(e: AgentStreamEvent): e is ToolCallEvent;
+declare function isPartialToolCall(e: AgentStreamEvent): e is PartialToolCallEvent;
+declare function isToolResult(e: AgentStreamEvent): e is ToolResultEvent;
+declare function isDone(e: AgentStreamEvent): e is DoneEvent;
+declare function isError(e: AgentStreamEvent): e is ErrorEvent;
+declare function isApprovalRequired(e: AgentStreamEvent): e is ApprovalRequiredEvent;
+
+/**
+ * The failure, as chunks the protocol accepts — theokit#161 (B).
+ *
+ * ## The measured defect
+ *
+ * M95 put the `code` INSIDE the error chunk (`{type:'error', errorText, errorCode}`), for a good
+ * reason: without it a consumer that must DISTINGUISH the failure has only the message, and matching
+ * on error text is the heuristic this ecosystem already paid for once — M93 classified failures as
+ * transient by regex over the message and read `ECONNREFUSED ...:443` as definitive because the PORT
+ * matched its "4xx" pattern.
+ *
+ * But the `error` variant of ai's `uiMessageChunkSchema` is STRICT: any extra key invalidates it.
+ * Measured against `ai@7.0.14` — `{type:'error',errorText:'boom'}` validates; the same chunk with
+ * `errorCode` does NOT. So since M95 this path emitted a chunk outside the protocol it claims to
+ * speak, and a consumer that validates would reject the whole frame — losing the text along with it.
+ *
+ * Nobody saw it because the test written to catch exactly this stopped BEFORE validating: its
+ * precondition (`toContainEqual({type:'error',errorText:'boom'})`) went stale when `errorCode`
+ * appeared, `expect` threw, and the validation loop never ran.
+ *
+ * ## Why a data part, and not one of the easy exits
+ *
+ * Dropping the code returns the consumer to the text matching M95 removed. Embedding it in
+ * `errorText` is the same thing under another name. The protocol already has the right place — a
+ * data part — and this file already uses one for `data-checkpoint`. Measured: it validates.
+ *
+ * `transient: true` because an error code is turn diagnostics, not message content: the SDK does not
+ * persist it in history, which is exactly what we want.
+ *
+ * The data part comes BEFORE the error chunk deliberately: a sequential consumer already holds the
+ * code when the failure arrives. In the other order it would have to handle the error first and only
+ * then learn which one it was.
+ */
+/**
+ * What the browser is told a failure was.
+ *
+ * Masked by default (usetheokit/theokit#390): the server's raw text — a driver's message, an HTTP
+ * client's, a filesystem call's — reached the client verbatim, and `ai@7` on the same protocol
+ * masks by default for the reason its own comment gives, "prevent leaking server error details to
+ * the client by default".
+ *
+ * The full text is NOT lost: it reaches the server's logs and the `agent.run` span, and it reaches
+ * this hook. What stops is it reaching the browser unless a host decides otherwise.
+ */
+type MaskError = (error: {
+    message: string;
+    code?: string;
+}) => string;
+declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>, opts: {
+    textId: string;
+    onError?: MaskError;
+}): AsyncGenerator<WireChunk, void, unknown>;
+
 /** Minimal event shape matching SDK's SDKMessage discriminated union. */
 interface StreamEvent {
     type: string;
     [key: string]: unknown;
 }
 /**
- * Create a Web Standard Response that streams SSE events.
- * Each event becomes: `event: {type}\ndata: {json}\n\n`
+ * Create a Web Standard Response that streams the agent's turn as UIMessage wire chunks.
+ *
+ * The `event:` line carries the chunk's own type. It is informational — `parseWireStream` reads
+ * only `data:` lines, per WHATWG SSE — and kept because an `EventSource` consumer can dispatch on
+ * it.
+ *
+ * @param eventStream - the framework's own run events
+ * @param opts.onError - what a consumer is told a failure was; masked by default (#390)
  */
-declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>): Response;
+declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>, opts?: {
+    onError?: Parameters<typeof presentUIMessageStream>[1]['onError'];
+}): Response;
 
 /**
  * LoopStrategy — the per-round terminal-decision contract that gives runtime to
@@ -160,6 +483,10 @@ declare class DelegationBudgetExceededError extends TheokitAgentError {
  * @deprecated Use {@link DelegationBudgetExceededError}. The alias is kept for one major so anyone
  * catching by the old name is not broken; it is the **same** class, not a copy — `instanceof` still
  * holds in both directions, and a referential-identity test (`toBe`) pins that.
+ *
+ * knip reports the value/type pair as a duplicate export, which is exactly what a deprecation
+ * alias is; `rules.duplicates` is "warn" for that reason. Removing it is the breaking change it
+ * exists to avoid.
  */
 declare const BudgetExceededError: typeof DelegationBudgetExceededError;
 /** @deprecated Use {@link DelegationBudgetExceededError}. */
@@ -316,8 +643,15 @@ interface DelegateOptions {
      * this option exists to remove.
      */
     parentHooks?: HookHandlers;
-    /** LLM API key (inherited from parent). */
-    apiKey?: string;
+    /**
+     * LLM API key (inherited from parent).
+     *
+     * `null` says the provider takes NO credential — a model on the developer's own machine
+     * (usetheokit/theokit#423). It is a distinct value from `''` on purpose: an empty string is what
+     * an unset environment variable produces, and treating the two alike is how a typo becomes an
+     * unauthenticated run. `undefined` still means the caller supplied nothing and is still refused.
+     */
+    apiKey?: string | null;
     /** Session ID override (default: crypto.randomUUID for isolation). */
     sessionId?: string;
     /** Cancellation — aborts stop the reflective loop from re-entering. */
@@ -466,4 +800,4 @@ declare function delegateWithScoring(subAgent: DelegationTarget, message: string
     feedbackTemplate?: (message: string, feedback: string) => string;
 }): Promise<ScoredDelegation>;
 
-export { streamAgentResponse as A, type BackgroundDelegation as B, type DelegationTarget as D, type LoopStrategy as L, type ReflectionStrategy as R, type StreamEvent as S, type DelegateOptions as a, type RoundStreamFactory as b, type DelegationResult as c, BudgetExceededError as d, DEFAULT_MAX_ITERATIONS as e, type DelegateFn as f, DelegationBudgetExceededError as g, DelegationError as h, type DelegationPort as i, type LoopFinishReason as j, type LoopOutcome as k, type LoopStrategyConfig as l, type ReflectionContext as m, type ReflectionResult as n, type ReflectionStrategyConfig as o, type ScoreVerdict as p, type ScoredDelegation as q, type Scorer as r, delegate as s, delegateBackground as t, delegateWithScoring as u, ladderReflectionStrategy as v, loopStrategyConfigSchema as w, noopReflectionStrategy as x, reflectionStrategyConfigSchema as y, resolveLoopStrategy as z };
+export { noopReflectionStrategy as $, type AgentStopReason as A, type BackgroundDelegation as B, type CheckpointSavedEvent as C, type DelegationTarget as D, type ErrorEvent as E, type FileEditEvent as F, type ThinkingEvent as G, type ToolCallEvent as H, type IterationEvent as I, type ToolResultEvent as J, delegate as K, type LoopStrategy as L, delegateBackground as M, delegateWithScoring as N, isApprovalRequired as O, type PartialToolCallEvent as P, isDone as Q, type ReflectionStrategy as R, type StreamEvent as S, type TextDeltaEvent as T, isError as U, isPartialToolCall as V, isTextDelta as W, isToolCall as X, isToolResult as Y, ladderReflectionStrategy as Z, loopStrategyConfigSchema as _, type DelegateOptions as a, presentUIMessageStream as a0, reflectionStrategyConfigSchema as a1, resolveLoopStrategy as a2, streamAgentResponse as a3, type MaskError as a4, type RoundStreamFactory as b, type DelegationResult as c, type AgentStreamEvent as d, type AgentTurnMetadata as e, type ApprovalRequiredEvent as f, type ArtifactChunkEvent as g, type ArtifactStartEvent as h, BudgetExceededError as i, DEFAULT_MAX_ITERATIONS as j, type DelegateFn as k, DelegationBudgetExceededError as l, DelegationError as m, type DelegationPort as n, type DoneEvent as o, type LoopFinishReason as p, type LoopOutcome as q, type LoopStrategyConfig as r, type ReflectionContext as s, type ReflectionResult as t, type ReflectionStrategyConfig as u, type RunStartedEvent as v, type ScoreVerdict as w, type ScoredDelegation as x, type Scorer as y, type StateUpdateEvent as z };