@theokit/agents 10.1.0 → 11.1.0

package/dist/{agent-handle-Dgi4ZGbg.d.ts → agent-handle-rEWdERuv.d.ts}

@@ -168,6 +168,83 @@ declare class ChannelTransport implements AgentTransport {
 }
 
 type UseAgentStatus = 'idle' | 'streaming' | 'done' | 'error';
+/**
+ * The stream ended before the run did — theokit#384.
+ *
+ * ## Why the status is `'error'` and not a new `'interrupted'` member
+ *
+ * `UseAgentStatus` is published, and every surface in and out of this repo switches on it. Adding a
+ * member fixes the lie only for the consumers who then update their switch; for everyone else the
+ * new value falls through to the same "not streaming, not an error" branch that shows a finished
+ * turn — the exact symptom, preserved. Reusing `'error'` fixes it for all of them at once, and it
+ * is already the value the rest of this store treats correctly: `send()` refuses to commit a turn
+ * that did not settle on `'done'`, so a half-answer stops being written into history as complete,
+ * and the reconnect wiring the issue found disabled (`status === 'error'` → `reconnect()`) starts
+ * firing without the consumer changing a line.
+ *
+ * ## Why the discrimination is a typed error rather than a status
+ *
+ * "The provider refused" and "the connection died" want opposite reactions — one is a failure to
+ * report, the other is a turn that can be resumed — and this framework already has a place for that
+ * difference: `TheokitAgentError`'s `code` + `isRetryable`, which `isTransientError` reads. A class
+ * outside that hierarchy is invisible to it and leaves the consumer matching on message text (M80).
+ *
+ * ## Why this is NOT a `stopReason` (theokit#379)
+ *
+ * The two are orthogonal, and collapsing them would be a category error. `stopReason` says why the
+ * RUN stopped and rides the `finish` chunk's metadata — it exists only when a terminal frame
+ * arrived. An interruption is the ABSENCE of that frame: the run may still be going, and this
+ * client cannot know why it stopped, because it never heard. Spelling it as a third `stopReason`
+ * member would put a value on a `done` turn that no producer produced, and would reintroduce the
+ * defect it fixes — a truncated run reported through the field that means "the agent finished".
+ * Transport termination and execution termination are separate axes; this is the transport one.
+ */
+declare class AgentStreamInterruptedError extends TheokitAgentError {
+    readonly chunksReceived: number;
+    readonly name = "AgentStreamInterruptedError";
+    constructor(chunksReceived: number);
+}
+/**
+ * One HITL decision the run is parked on, flattened for the surface that renders it
+ * (usetheokit/theokit#392).
+ *
+ * ## Why the store publishes this at all, when the part already carries it
+ *
+ * `approve()` needs an id. Before this field the snapshot had four keys and none of them was that
+ * id, so an application had two options: scan every part of every message for `state ===
+ * 'approval-requested'`, or poll `GET /api/agents/<name>/approvals` out of band — which is what the
+ * measured J2 client did, at twelve lines and two React primitives, through an endpoint under a
+ * security advisory. Publishing the id is what removes the reason to reach for either.
+ *
+ * ## Why it is DERIVED and not accumulated
+ *
+ * It is computed from the current turn's parts on each emit, never written by a second reducer. A
+ * separate list would need its own settle path and could then disagree with the transcript about
+ * whether a decision is outstanding — and the transcript is what renders. Deriving makes the two
+ * unable to drift: a settled gate leaves `approval-requested` on the same chunk that fills in the
+ * output, so it leaves this array in the same step.
+ *
+ * ## Why plural
+ *
+ * The SDK dispatches a round's calls concurrently (`mapWithConcurrency`), so two gated calls of the
+ * same tool can be outstanding at once — pinned by
+ * `tests/integration/hitl-call-correlation.test.ts`. A singular field would have to pick one and
+ * would be silently wrong exactly when a human has two things to decide.
+ */
+interface PendingApproval {
+    /** The id `approve()` settles. */
+    readonly approvalId: string;
+    /** The call this gate holds — the same id `tool-input-available` announced. */
+    readonly toolCallId: string;
+    /** The gated tool's name, off the part. `undefined` only if the producer announced none. */
+    readonly toolName: string | undefined;
+    /** The resolved arguments the human is authorising, off the part. */
+    readonly input: unknown;
+    /** The question declared on the gate, when the producer sent one. */
+    readonly question?: string;
+    /** The window before the gate settles itself, in ms, when the producer sent one. */
+    readonly timeoutMs?: number;
+}
 /** The observable state the store exposes (stable reference between emits — `useSyncExternalStore` contract). */
 interface AgentClientState {
     /** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat — unchanged since M41. */
@@ -180,6 +257,11 @@ interface AgentClientState {
     thread: WireMessage[];
     status: UseAgentStatus;
     error: Error | undefined;
+    /**
+     * The HITL decisions this turn is parked on, newest last. Empty whenever nothing is outstanding.
+     * Each entry carries the id `approve()` takes plus what the prompt needs to name the action.
+     */
+    pendingApprovals: PendingApproval[];
 }
 /**
  * M41 (ADR-0050 D6) — the framework-agnostic agent client store.
@@ -201,10 +283,31 @@ interface AgentClientOptions {
      * change the observable behaviour of anyone counting emits or depending on first-token latency.
      */
     readonly emitIntervalMs?: number;
+    /**
+     * The conversation this client continues. Absent = a fresh one is drawn.
+     *
+     * The id is not decorative: the HTTP transport sends it as the top-level `id`, which the server
+     * reads as the session id (`client/http-transport.ts:88-92`). It used to be drawn in the field
+     * declaration with no way to supply or read it, so every `new AgentClient(...)` was a new
+     * conversation and a page reload silently abandoned the thread the server still held
+     * (usetheokit/theokit#364).
+     *
+     * Supply it to resume; read `client.chatId` to persist it. Both halves are needed: reading without
+     * supplying lets an application store an id it can never restore, and supplying without reading
+     * leaves it nothing to store.
+     */
+    readonly chatId?: string;
 }
 declare class AgentClient<TInput = unknown> {
     #private;
     constructor(transport: AgentTransport, contextResolver?: () => RequestContext | undefined, options?: AgentClientOptions);
+    /**
+     * The conversation this client is on — the id the server keys the session by.
+     *
+     * Readable so an application can persist it and pass it back through
+     * {@link AgentClientOptions.chatId} after a reload (usetheokit/theokit#364).
+     */
+    get chatId(): string;
     /** Subscribe to state changes; returns an unsubscribe fn. */
     subscribe: (listener: () => void) => (() => void);
     /** The current immutable snapshot (stable reference until the next emit). */
@@ -217,7 +320,15 @@ declare class AgentClient<TInput = unknown> {
     abort: () => void;
     /** Clear messages + error, back to idle. */
     reset: () => void;
-    /** Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback). */
+    /**
+     * Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback).
+     *
+     * The signature is unchanged by usetheokit/theokit#392, deliberately. What that issue reported was
+     * not that `approve` takes an id — it was that nothing HANDED the caller one, so the id had to be
+     * mined out of band. `pendingApprovals` hands it over, and taking the entry instead of its
+     * `approvalId` would save no line while adding a second accepted shape to a published method that
+     * surfaces outside this repository (`@theokit/tui`, `@theokit/ui`).
+     */
     approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
 }
 
@@ -258,4 +369,4 @@ declare function agentHandle<TInput = unknown, TToolNames extends string = strin
 /** Narrow an unknown binding to an {@link AgentHandle} (has a string `path`, is not a transport). */
 declare function isAgentHandle(value: unknown): value is AgentHandle;
 
-export { type ApprovalDecision as A, type ChannelPushSource as C, type InProcessApprovalRequestLike as I, type RequestContext as R, type UseAgentStatus as U, type AgentHandle as a, type AgentTransport as b, AgentClient as c, type AgentClientOptions as d, type AgentClientState as e, ApprovalAbortedError as f, ChannelTransport as g, type ChannelTransportOptions as h, type ChannelTurnHandlers as i, type InProcessAwaitApproval as j, type InProcessRunInput as k, type InProcessRunner as l, InProcessTransport as m, type InProcessTransportOptions as n, agentHandle as o, isAgentHandle as p };
+export { type ApprovalDecision as A, type ChannelPushSource as C, type InProcessApprovalRequestLike as I, type PendingApproval as P, type RequestContext as R, type UseAgentStatus as U, type AgentHandle as a, type AgentTransport as b, AgentClient as c, type AgentClientOptions as d, type AgentClientState as e, AgentStreamInterruptedError as f, ApprovalAbortedError as g, ChannelTransport as h, type ChannelTransportOptions as i, type ChannelTurnHandlers as j, type InProcessAwaitApproval as k, type InProcessRunInput as l, type InProcessRunner as m, InProcessTransport as n, type InProcessTransportOptions as o, agentHandle as p, isAgentHandle as q };

package/dist/auth.js

@@ -1,7 +1,7 @@
 import {
   readSecureJson,
   writeSecureJson
-} from "./chunk-QXGSF6WX.js";
+} from "./chunk-D2EFYZBV.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";

package/dist/{bridge-entry-emr2PSXC.d.ts → bridge-entry-DPm1C5li.d.ts}

@@ -1,12 +1,14 @@
 import { ExecutionContext } from '@theokit/http';
-import { c as AgentOptions, T as ToolOptions, p as ProjectContextOptions, C as CompiledAgentOptions, H as HumanInTheLoopOptions, b as CompiledTool, R as ReasoningEffort, G as Guardrail, S as SkillsSelection, M as McpServersMap } from './agent-compiler-CIPQkehU.js';
+import { c as AgentOptions, T as ToolOptions, P as ProjectContextOptions, H as HumanInTheLoopOptions, R as ReasoningEffort, M as McpServersMap } from './types-C16Wuh9E.js';
+import { C as CompiledAgentOptions, a as CompiledTool, G as Guardrail, S as SkillsSelection } from './agent-compiler-tetgj6zR.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings } from '@theokit/sdk';
-import { S as StreamEvent } from './delegation-scoring-CDvtrYKd.js';
+import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-CQtF2Zaf.js';
+import { RetryOptions } from '@theokit/sdk/retry';
 import { SandboxPosture } from '@theokit/sdk/sandbox';
-import { A as AgentDefinition, S as SettingSourcesSelection } from './define-agent-BO5QSjV8.js';
-import { WireChunk } from '@theokit/presenter/wire';
+import { A as AgentDefinition, S as SettingSourcesSelection } from './define-agent-BnH1MBxs.js';
 import { z } from 'zod';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
+import { WireChunk } from '@theokit/presenter/wire';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 
 /**
@@ -120,197 +122,6 @@ declare function projectContextMetadataOnlyKnobs(options: ProjectContextOptions)
  */
 declare function compileProjectContext(options: ProjectContextOptions, base?: string | SystemPromptResolver): SystemPromptResolver;
 
-/**
- * Typed discriminated union for agent SSE stream events.
- *
- * 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;
-}
-/** 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;
-}
-/**
- * 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;
-}
-/** 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;
-
 /**
  * Auto-generate HTTP routes from @Agent metadata — Web Standard.
  *
@@ -370,6 +181,14 @@ interface HitlDecision {
     approved: boolean;
     reason?: string;
     payload?: unknown;
+    /**
+     * What settled this, when it was not a person (usetheokit/theokit#393).
+     *
+     * Mirrors `ApprovalDecision.settledBy` in `theokit`, for the reason the comment above this
+     * interface gives: this package must not import from `theokit`. Absent means the decision came
+     * through the approve route; `'timeout'` means the window closed with nobody deciding.
+     */
+    settledBy?: 'timeout';
 }
 /** Injected wiring — the harness (mount-agent) supplies these; the plugin stays pure. */
 interface HitlWiring {
@@ -590,6 +409,32 @@ interface RuntimeOverrides {
      * why the key is omitted entirely rather than set to `undefined` when absent.
      */
     onRunEvent?: RunEventSink;
+    /**
+     * theokit#474 — per-turn transient retry, opt-in.
+     *
+     * When set, the START of the turn (the SDK handshake plus its first event, before anything is
+     * yielded) is wrapped in the SDK `Retry`, so a 429/5xx/network blip that kills the turn before it
+     * produced anything is recovered instead of ending it. Absent ⇒ a single attempt, and the key is
+     * omitted from every downstream call, so the stream is byte-identical to before.
+     *
+     * See `turn-retry.ts` for why a rejection-shaped retry would have been inert on this path, and
+     * for the invariant that closes the retry window on the first event.
+     */
+    retry?: RetryOptions;
+    /**
+     * theokit#475 — expose the run's REAL token usage to tool handlers as `ctx.usage`, opt-in.
+     *
+     * When true, the adapter installs a {@link RunUsageMeter} as the run's `budgetTracker` (wrapping
+     * the caller's own, when there is one) and hands every tool handler a snapshot of what the
+     * provider has reported so far. A tool can then answer "how much context is left?" from a
+     * measurement instead of a character-count estimate. See `usage/run-usage.ts`.
+     *
+     * Opt-in rather than always-on because installing a `budgetTracker` changes what `Agent.create`
+     * receives for every run that never asked for it, and the back-compat floor here is a floor, not
+     * a preference. Absent ⇒ handlers are wrapped exactly as before (`ctx.usage` does not exist) and
+     * the SDK receives no tracker it was not already given.
+     */
+    exposeUsageToTools?: boolean;
 }
 declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string | (() => string | Promise<string>), overrides?: RuntimeOverrides): ((message: string, sessionId: string, factoryOpts?: {
     disableTools?: boolean;
@@ -838,10 +683,6 @@ interface SdkMessage {
  */
 declare function translateSdkEvent(msg: SdkMessage, runId: string): StreamEvent[];
 
-declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>, opts: {
-    textId: string;
-}): AsyncGenerator<WireChunk, void, unknown>;
-
 /**
  * M8 — `AgentBuilder.create()`, the fluent agent builder with accumulative **type-state**.
  *
@@ -949,6 +790,15 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
     system(prompt: string): AgentBuilder<TInput, TModel, TContext, TTools>;
     /** Set the extended-thinking effort. */
     reasoningEffort(effort: ReasoningEffort): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /**
+     * theokit#363 — cap the agent's tool-calling turns within ONE run. A positive integer; throws at
+     * `.build()` otherwise. Unset ⇒ the SDK's own ceiling (8) applies, unchanged.
+     *
+     * This is the chain the scaffold writes, and until now it had no way to say "stop after N steps":
+     * the declaration existed on the decorator path only, and even there nothing on the served path
+     * read it. See {@link DefineAgentConfig.maxIterations} for why the name is `maxIterations`.
+     */
+    maxIterations(limit: number): AgentBuilder<TInput, TModel, TContext, TTools>;
     /** Set the run-context (M7) — the object every tool handler receives as `ctx.context`. */
     context<C extends Record<string, unknown>>(value: C): AgentBuilder<TInput, TModel, C, TTools>;
     /**
@@ -1110,6 +960,15 @@ interface StreamHitlOptions {
 interface StreamAgentOptions {
     message: string;
     sessionId: string;
+    /**
+     * What the browser is told a failure was (usetheokit/theokit#390).
+     *
+     * Absent ⇒ masked to a fixed string. The server's raw error text — a driver's message, an HTTP
+     * client's, a filesystem call's — used to reach the client verbatim, and `ai@7` on the same
+     * protocol masks by default for the reason its own comment gives. The full text still reaches
+     * the logs and the `agent.run` span; what stops is it reaching a browser unless a host decides.
+     */
+    onError?: MaskError;
     /** M35 (multimodal) — images to send alongside the text. Absent ⇒ the string send path is unchanged. */
     images?: RuntimeOverrides['images'];
     /** Enable human-in-the-loop tool approval (M4). Absent ⇒ the M2 non-HITL path, byte-unchanged. */
@@ -1146,6 +1005,30 @@ interface StreamAgentOptions {
      * the stream is byte-identical to before.
      */
     onRunEvent?: RuntimeOverrides['onRunEvent'];
+    /**
+     * theokit#474 — per-turn transient retry.
+     *
+     * `AgentRunnerRunOptions.retry` has existed since V4-P, and it belongs to the OTHER runtime: the
+     * reflective loop, whose round factory is allowed to throw. This entry point runs one SDK turn,
+     * and the SDK reports a provider failure as the run's terminal `error` EVENT rather than as a
+     * rejection — so the option could not simply be forwarded, and a wrapper that only caught throws
+     * would have been inert. See `turn-retry.ts`.
+     *
+     * Absent ⇒ the key is omitted from the SDK call entirely and the turn is a single attempt, exactly
+     * as before.
+     */
+    retry?: RuntimeOverrides['retry'];
+    /**
+     * theokit#475 — expose the run's REAL token usage to tool handlers as `ctx.usage`.
+     *
+     * The seam a `get_context_remaining`-style tool needs: without it the only figure reachable from
+     * inside a handler is a character-count estimate over `ctx.messages`. Read it with `readRunUsage`
+     * from `@theokit/agents/usage`.
+     *
+     * Absent ⇒ handlers receive exactly the ctx they did before and the SDK receives no tracker it
+     * was not already given.
+     */
+    exposeUsageToTools?: RuntimeOverrides['exposeUsageToTools'];
 }
 /**
  * Run a compiled agent and yield the M0/M1 `UIMessageStream` chunks. `apiKey` is resolved by the
@@ -1594,4 +1477,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type StateUpdateEvent as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, DelegationTimeoutError as E, type DoneEvent as F, type EphemeralAgent as G, type HitlDecision as H, type ErrorEvent as I, type FileEditEvent as J, type IterationEvent as K, type LLMCallContext as L, type McpApprovalSpec as M, McpFileError as N, type McpRegistryConfig as O, type McpRequestContext as P, type McpSelection as Q, type PartialToolCallEvent as R, type SkillsOptions as S, type ProcessInputContext as T, type RunStartedEvent as U, type SdkAgentHandle as V, type SdkMessage as W, type SdkSendOptions as X, type SdkTurnHandle as Y, type Segment as Z, type ShouldAutoApproveOptions as _, type ApprovalPosture as a, type TextDeltaEvent as a0, type ThinkingEvent as a1, type ToolCallEvent as a2, type ToolCallVeto as a3, type ToolHooks as a4, type ToolHooksPlugin as a5, type ToolResultEvent as a6, WRITE_SCOPED_TOOLS as a7, agentsPlugin as a8, applyPosture as a9, reasoningEffortOf as aA, resolveMcpServers as aB, runWithApiErrorHandling as aC, shouldAutoApprove as aD, toAgentFactory as aE, translateSdkEvent as aF, withClockCap as aG, withEphemeralAgent as aH, buildModelSelection as aa, compileAgentModule as ab, compileContextWindow as ac, compileProjectContext as ad, compileSkills as ae, createAgentExecutionContext as af, createApiErrorHandler as ag, createSdkAgentStream as ah, createThinkTagExtractor as ai, createToolHooksPlugin as aj, extractThinkTagStream as ak, generateAgentManifest as al, generateAgentRoutes as am, isAgentContext as an, isApprovalRequired as ao, isDone as ap, isError as aq, isPartialToolCall as ar, isTextDelta as as, isToolCall as at, isToolResult as au, loadMcpJson as av, mcpRegistry as aw, mcpToolApprovals as ax, presentUIMessageStream as ay, projectContextMetadataOnlyKnobs as az, APPROVAL_MODES as b, type AfterToolCallContext as c, AgentBuilder as d, AgentDefinitionError as e, type AgentExecutionContext as f, type AgentManifest as g, type AgentManifestSource as h, type AgentManifestTool as i, type AgentRoute as j, type AgentRouteContext as k, type AgentRunInfo as l, type AgentStreamEvent as m, type AgentTurnMetadata as n, type AgentsPluginOptions as o, type ApiErrorContext as p, type ApiErrorDecision as q, type ApiErrorPolicy as r, streamAgentUIMessages as s, type ApprovalMode as t, type ApprovalRequiredEvent as u, type ArtifactChunkEvent as v, type ArtifactStartEvent as w, type CheckpointSavedEvent as x, type CompiledContextWindow as y, ContextualTool as z };
+export { createApiErrorHandler as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, type EphemeralAgent as E, type SdkMessage as F, type SdkSendOptions as G, type HitlDecision as H, type SdkTurnHandle as I, type Segment as J, type ShouldAutoApproveOptions as K, type LLMCallContext as L, type McpApprovalSpec as M, type ToolHooks as N, type ToolHooksPlugin as O, type ProcessInputContext as P, agentsPlugin as Q, applyPosture as R, type SkillsOptions as S, type ToolCallVeto as T, buildModelSelection as U, compileAgentModule as V, WRITE_SCOPED_TOOLS as W, compileContextWindow as X, compileProjectContext as Y, compileSkills as Z, createAgentExecutionContext as _, type ApprovalPosture as a, createSdkAgentStream as a0, createThinkTagExtractor as a1, createToolHooksPlugin as a2, extractThinkTagStream as a3, generateAgentManifest as a4, generateAgentRoutes as a5, isAgentContext as a6, loadMcpJson as a7, mcpRegistry as a8, mcpToolApprovals as a9, projectContextMetadataOnlyKnobs as aa, reasoningEffortOf as ab, resolveMcpServers as ac, runWithApiErrorHandling as ad, shouldAutoApprove as ae, toAgentFactory as af, translateSdkEvent as ag, withClockCap as ah, withEphemeralAgent as ai, APPROVAL_MODES as b, type AfterToolCallContext as c, AgentBuilder as d, AgentDefinitionError as e, type AgentExecutionContext as f, type AgentManifest as g, type AgentManifestSource as h, type AgentManifestTool as i, type AgentRoute as j, type AgentRouteContext as k, type AgentRunInfo as l, type AgentsPluginOptions as m, type ApiErrorContext as n, type ApiErrorDecision as o, type ApiErrorPolicy as p, type ApprovalMode as q, type CompiledContextWindow as r, streamAgentUIMessages as s, ContextualTool as t, DelegationTimeoutError as u, McpFileError as v, type McpRegistryConfig as w, type McpRequestContext as x, type McpSelection as y, type SdkAgentHandle as z };

package/dist/bridge.d.ts

@@ -1,12 +1,13 @@
-export { b as APPROVAL_MODES, c as AfterToolCallContext, d as AgentBuilder, e as AgentDefinitionError, f as AgentExecutionContext, g as AgentManifest, A as AgentManifestEntry, h as AgentManifestSource, i as AgentManifestTool, j as AgentRoute, k as AgentRouteContext, l as AgentRunInfo, m as AgentStreamEvent, n as AgentTurnMetadata, o as AgentsPluginOptions, p as ApiErrorContext, q as ApiErrorDecision, r as ApiErrorPolicy, t as ApprovalMode, a as ApprovalPosture, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BeforeToolCallContext, x as CheckpointSavedEvent, y as CompiledContextWindow, z as ContextualTool, D as DefinitionOrThunk, E as DelegationTimeoutError, F as DoneEvent, G as EphemeralAgent, I as ErrorEvent, J as FileEditEvent, K as IterationEvent, L as LLMCallContext, M as McpApprovalSpec, N as McpFileError, O as McpRegistryConfig, P as McpRequestContext, Q as McpSelection, R as PartialToolCallEvent, T as ProcessInputContext, U as RunStartedEvent, V as SdkAgentHandle, W as SdkMessage, X as SdkSendOptions, Y as SdkTurnHandle, Z as Segment, _ as ShouldAutoApproveOptions, $ as StateUpdateEvent, a0 as TextDeltaEvent, a1 as ThinkingEvent, a2 as ToolCallEvent, a3 as ToolCallVeto, a4 as ToolHooks, a5 as ToolHooksPlugin, a6 as ToolResultEvent, a7 as WRITE_SCOPED_TOOLS, a8 as agentsPlugin, a9 as applyPosture, aa as buildModelSelection, ab as compileAgentModule, ac as compileContextWindow, ad as compileProjectContext, ae as compileSkills, af as createAgentExecutionContext, ag as createApiErrorHandler, ah as createSdkAgentStream, ai as createThinkTagExtractor, aj as createToolHooksPlugin, ak as extractThinkTagStream, al as generateAgentManifest, am as generateAgentRoutes, an as isAgentContext, ao as isApprovalRequired, ap as isDone, aq as isError, ar as isPartialToolCall, as as isTextDelta, at as isToolCall, au as isToolResult, av as loadMcpJson, aw as mcpRegistry, ax as mcpToolApprovals, ay as presentUIMessageStream, az as projectContextMetadataOnlyKnobs, aA as reasoningEffortOf, aB as resolveMcpServers, aC as runWithApiErrorHandling, aD as shouldAutoApprove, s as streamAgentUIMessages, aE as toAgentFactory, aF as translateSdkEvent, aG as withClockCap, aH as withEphemeralAgent } from './bridge-entry-emr2PSXC.js';
-export { C as CompiledAgentOptions, b as CompiledTool, l as ToolWalkResult, n as ToolboxWalkResult, o as compileTools } from './agent-compiler-CIPQkehU.js';
-export { B as BackgroundDelegation, d as BudgetExceededError, f as DelegateFn, a as DelegateOptions, g as DelegationBudgetExceededError, h as DelegationError, i as DelegationPort, c as DelegationResult, D as DelegationTarget, p as ScoreVerdict, q as ScoredDelegation, r as Scorer, S as StreamEvent, s as delegate, t as delegateBackground, u as delegateWithScoring, A as streamAgentResponse } from './delegation-scoring-CDvtrYKd.js';
-export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, P as ProjectSettingsGrant, c as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, d as compileAgentDefinition, i as isAgentDefinition, r as resolveSettingSources } from './define-agent-BO5QSjV8.js';
+export { b as APPROVAL_MODES, c as AfterToolCallContext, d as AgentBuilder, e as AgentDefinitionError, f as AgentExecutionContext, g as AgentManifest, A as AgentManifestEntry, h as AgentManifestSource, i as AgentManifestTool, j as AgentRoute, k as AgentRouteContext, l as AgentRunInfo, m as AgentsPluginOptions, n as ApiErrorContext, o as ApiErrorDecision, p as ApiErrorPolicy, q as ApprovalMode, a as ApprovalPosture, B as BeforeToolCallContext, r as CompiledContextWindow, t as ContextualTool, D as DefinitionOrThunk, u as DelegationTimeoutError, E as EphemeralAgent, L as LLMCallContext, M as McpApprovalSpec, v as McpFileError, w as McpRegistryConfig, x as McpRequestContext, y as McpSelection, P as ProcessInputContext, z as SdkAgentHandle, F as SdkMessage, G as SdkSendOptions, I as SdkTurnHandle, J as Segment, K as ShouldAutoApproveOptions, T as ToolCallVeto, N as ToolHooks, O as ToolHooksPlugin, W as WRITE_SCOPED_TOOLS, Q as agentsPlugin, R as applyPosture, U as buildModelSelection, V as compileAgentModule, X as compileContextWindow, Y as compileProjectContext, Z as compileSkills, _ as createAgentExecutionContext, $ as createApiErrorHandler, a0 as createSdkAgentStream, a1 as createThinkTagExtractor, a2 as createToolHooksPlugin, a3 as extractThinkTagStream, a4 as generateAgentManifest, a5 as generateAgentRoutes, a6 as isAgentContext, a7 as loadMcpJson, a8 as mcpRegistry, a9 as mcpToolApprovals, aa as projectContextMetadataOnlyKnobs, ab as reasoningEffortOf, ac as resolveMcpServers, ad as runWithApiErrorHandling, ae as shouldAutoApprove, s as streamAgentUIMessages, af as toAgentFactory, ag as translateSdkEvent, ah as withClockCap, ai as withEphemeralAgent } from './bridge-entry-DPm1C5li.js';
+export { C as CompiledAgentOptions, a as CompiledTool, T as ToolWalkResult, h as ToolboxWalkResult, i as compileTools } from './agent-compiler-tetgj6zR.js';
+export { A as AgentStopReason, d as AgentStreamEvent, e as AgentTurnMetadata, f as ApprovalRequiredEvent, g as ArtifactChunkEvent, h as ArtifactStartEvent, B as BackgroundDelegation, i as BudgetExceededError, C as CheckpointSavedEvent, k as DelegateFn, a as DelegateOptions, l as DelegationBudgetExceededError, m as DelegationError, n as DelegationPort, c as DelegationResult, D as DelegationTarget, o as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, P as PartialToolCallEvent, v as RunStartedEvent, w as ScoreVerdict, x as ScoredDelegation, y as Scorer, z as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, G as ThinkingEvent, H as ToolCallEvent, J as ToolResultEvent, K as delegate, M as delegateBackground, N as delegateWithScoring, O as isApprovalRequired, Q as isDone, U as isError, V as isPartialToolCall, W as isTextDelta, X as isToolCall, Y as isToolResult, a0 as presentUIMessageStream, a3 as streamAgentResponse } from './delegation-scoring-CQtF2Zaf.js';
+export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, P as ProjectSettingsGrant, c as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, d as compileAgentDefinition, i as isAgentDefinition, r as resolveSettingSources } from './define-agent-BnH1MBxs.js';
 import '@theokit/http';
+import './types-C16Wuh9E.js';
 import '@theokit/sdk';
-import '@theokit/sdk/sandbox';
-import '@theokit/presenter/wire';
 import 'zod';
+import '@theokit/sdk/retry';
+import '@theokit/sdk/sandbox';
 import './hook-handlers-Cw2FsnE5.js';
+import '@theokit/presenter/wire';
 import '@theokit/sdk/errors';
-import '@theokit/sdk/retry';

package/dist/bridge.js

@@ -28,7 +28,7 @@ import {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages
-} from "./chunk-QJN2LLPF.js";
+} from "./chunk-ZQOKIZCI.js";
 import {
   APPROVAL_MODES,
   BudgetExceededError,
@@ -53,7 +53,7 @@ import {
   translateSdkEvent,
   withClockCap,
   withEphemeralAgent
-} from "./chunk-CKRM5Q2K.js";
+} from "./chunk-2I6DQUJP.js";
 import "./chunk-RKWCXVYG.js";
 import {
   AGENT_BRAND,
@@ -61,7 +61,8 @@ import {
   compileAgentDefinition,
   isAgentDefinition,
   resolveSettingSources
-} from "./chunk-4VHCH6IZ.js";
+} from "./chunk-LLIERPF3.js";
+import "./chunk-OXNDJSAJ.js";
 import "./chunk-Z4QWC7IK.js";
 export {
   AGENT_BRAND,