@theokit/sdk 4.19.1 → 4.19.2

package/dist/run-DFM1H2jW.d.ts

@@ -0,0 +1,1589 @@
+import * as zod from 'zod';
+
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+/**
+ * SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
+ * A PURE post-processor of the verdict (no tool-safety metadata needed, so it fits
+ * a bring-your-own-tools runtime). Grounded in a peer project (plan agent = deny-all,
+ * `dangerously-skip-permissions`) + Codex (`AskForApproval`: `OnRequest` default,
+ * `Never`, `UnlessTrusted`). See {@link applyMode} for the exact table.
+ *
+ * - `default` — verdict as-is (rules decide; unmatched ⇒ `ask`, fail-closed).
+ * - `plan` — read-only: `allow` rules pass, everything else ⇒ `deny` (mutations blocked).
+ *   NOTE: `plan` gates on the resolved verdict, so an engine configured with
+ *   `{ defaultAction: "allow" }` still yields `allow` for UNMATCHED calls under
+ *   `plan` — pair `plan` with the default fail-closed engine (`defaultAction: "ask"`)
+ *   for full read-only behavior.
+ * - `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
+ *   `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
+ *   `allow` EXCEPT an explicit `deny` rule. Never asks. a peer project
+ *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
+ */
+type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+/**
+ * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
+ *
+ * `explicit` is `true` when the verdict came from a rule that matched by name (and
+ * args), `false` when it is the fail-closed default for an unmatched call. The flag
+ * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
+ * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
+ *
+ * INVARIANT (both a peer project + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
+    readonly defaultAction?: PermissionAction;
+}
+declare class PermissionEngine {
+    #private;
+    private readonly rules;
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
+    /**
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
+     */
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
+}
+
+/**
+ * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
+ *
+ * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
+ * out-of-band runtime-OBSERVABILITY signals — the model's content is unaffected —
+ * delivered opt-in via `SendOptions.onRunEvent`. Discriminate on `type`. Mirrors
+ * the Anthropic `SDKMessage`-union approach (rate-limit, permission-denied, task
+ * lifecycle, compaction boundary).
+ *
+ * The union is the forward-compatible CONTRACT (discriminate exhaustively). The
+ * runtime EMITS every variant end-to-end: `tool_progress` + `permission_denied`
+ * (agent-loop tool-dispatch seam), `rate_limit` (pool-aware LLM client 429 retry),
+ * `compact_boundary` (session auto-compaction), and `task_*` (opt-in bridge from a
+ * `Task.submit({ onRunEvent })` task's lifecycle). A consumer switching on `type`
+ * sees the real signal.
+ *
+ * @public
+ */
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent | RunCompletionCheckEvent;
+/**
+ * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
+ * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
+ * surfaced on `wait()`).
+ */
+interface RunTripwireEvent {
+    readonly type: "tripwire";
+    readonly reason: string;
+    readonly processorId: string;
+}
+/** A tool call is being dispatched (before its result). */
+interface RunToolProgressEvent {
+    readonly type: "tool_progress";
+    readonly toolName: string;
+    readonly toolCallId: string;
+}
+/** The provider returned a rate-limit (HTTP 429); the loop will back off + retry. */
+interface RunRateLimitEvent {
+    readonly type: "rate_limit";
+    /** Retry attempt number (1-based) about to be delayed. */
+    readonly attempt: number;
+    /** Delay in ms before the retry, when the provider/policy supplied one. */
+    readonly retryAfterMs?: number;
+}
+/**
+ * A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
+ * an operator file-hook `preToolUse`, or the fork tool-whitelist. `source`
+ * discriminates which. `toolCallId` joins the event to the tool-call log.
+ */
+interface RunPermissionDeniedEvent {
+    readonly type: "permission_denied";
+    readonly toolName: string;
+    readonly toolCallId: string;
+    /** Which layer blocked the call. */
+    readonly source: "plugin" | "file_hook" | "fork_whitelist";
+    /** The rejection message surfaced to the model. */
+    readonly message: string;
+}
+/** A background task/subagent started. */
+interface RunTaskStartedEvent {
+    readonly type: "task_started";
+    readonly taskId: string;
+    readonly description?: string;
+}
+/** A background task/subagent changed state. */
+interface RunTaskUpdatedEvent {
+    readonly type: "task_updated";
+    readonly taskId: string;
+    readonly status: string;
+}
+/** A background task/subagent finished. */
+interface RunTaskCompletedEvent {
+    readonly type: "task_completed";
+    readonly taskId: string;
+    readonly status: "completed" | "failed" | "stopped";
+}
+/**
+ * SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
+ * Emitted once, after a finished run's reply is judged against
+ * {@link SendOptions.completionCheck}. Distinct from `task_completed` (which is
+ * background-task/subagent lifecycle). Mirrors {@link RunResult.completionCheck}.
+ */
+interface RunCompletionCheckEvent {
+    readonly type: "completion_check";
+    readonly complete: boolean;
+    readonly reason: string;
+}
+/** The conversation crossed a compaction boundary (history was summarized). */
+interface RunCompactBoundaryEvent {
+    readonly type: "compact_boundary";
+    readonly trigger: "manual" | "auto";
+    /** Token count before compaction, when known. */
+    readonly preTokens?: number;
+}
+/**
+ * SE2 — the opt-in sink for {@link RunEvent}s. Supplied via `SendOptions.onRunEvent`.
+ * Synchronous + best-effort: a throwing sink must never break the run (the emitter
+ * try-catches it), so keep it fast (push to a queue, don't await).
+ */
+type RunEventSink = (event: RunEvent) => void;
+/**
+ * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
+ * observability can never break the run (fail-safe, mirrors the EventBus EC-2
+ * contract). No-op when the sink is absent.
+ */
+declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
+
+/**
+ * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
+ * the user message (input) or the model's final text (output). Processors run in
+ * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
+ * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
+ * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
+ * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
+ * ADR). Mirrors a peer framework's `inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+/**
+ * A policy violation surfaced to a processor's {@link Processor.onViolation}
+ * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
+ *
+ * @public
+ */
+interface ProcessorViolation {
+    processorId: string;
+    message: string;
+    detail?: unknown;
+}
+/**
+ * Controls available to a processor while it runs: `abort()` stops the run with
+ * a tripwire; `warn()` reports a non-blocking violation and continues.
+ *
+ * @public
+ */
+interface ProcessorControls {
+    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
+    abort(reason: string): never;
+    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
+    warn(message: string, detail?: unknown): void;
+}
+/** Context passed to {@link Processor.processInput}. @public */
+interface InputProcessorContext extends ProcessorControls {
+    /** The user message text for this send. */
+    message: string;
+    agentId: string;
+}
+/** Context passed to {@link Processor.processOutput}. @public */
+interface OutputProcessorContext extends ProcessorControls {
+    /** The model's final assistant text for this run. */
+    text: string;
+    agentId: string;
+}
+/**
+ * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
+ * `processOutput` (runs on the final text). A processor's `strategy` (block /
+ * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
+ * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
+ * to report without blocking. The core ships no strategy enum — strategies are a
+ * processor-level convention over these primitives.
+ *
+ * @public
+ */
+interface Processor {
+    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+    id: string;
+    /**
+     * Transform or block the user message before it reaches the model. Return the
+     * (possibly rewritten) text; returning nothing (void) preserves the message
+     * unchanged. May be `async`.
+     */
+    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
+    /**
+     * Transform or block the model's final text before it reaches the caller.
+     * Return the (possibly redacted) text; returning nothing (void) preserves the
+     * text unchanged. May be `async`.
+     */
+    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
+    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
+    onViolation?(violation: ProcessorViolation): void;
+}
+/**
+ * The tripwire detail attached to {@link RunResult.tripwire} when a processor
+ * aborts, and carried by the `tripwire` run-event.
+ *
+ * @public
+ */
+interface ProcessorTripwire {
+    reason: string;
+    processorId: string;
+}
+
+/**
+ * Leaf module for content-block types shared by `messages.ts` (assistant/user
+ * content) and `agent-prims.ts` (`CustomTool` handler results). Kept
+ * import-free so both can depend on it WITHOUT the `agent-prims ↔ messages`
+ * cycle (#7).
+ *
+ * @public
+ */
+/**
+ * Plain text content block emitted by the assistant or user, or returned by a
+ * tool.
+ *
+ * @public
+ */
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+/**
+ * SE7 — a base64-encoded image block a tool can hand back as (part of) its
+ * result or its `ToolError`. `media_type` is a MIME type (e.g. `"image/png"`);
+ * `data` is the base64 payload without a data-URL prefix.
+ *
+ * Note: when a tool builds this from model- or user-influenced input, treat
+ * `media_type` as UNTRUSTED — validate/allow-list it before rendering it in a
+ * log or UI (it could carry newlines / control chars). The SDK only forwards it
+ * (JSON-serialized onto the wire) and never executes or path-joins it.
+ *
+ * @public
+ */
+interface ImageBlock {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+}
+/**
+ * SE7 — structured content a tool result may carry: text and/or images. A tool
+ * `handler` may return this (success) and a `ToolError` may carry it (failure).
+ * Block-capable provider wires forward it natively; string-only provider wires
+ * flatten text and fail fast on an image.
+ *
+ * @public
+ */
+type ToolResultContentBlock = TextBlock | ImageBlock;
+
+/**
+ * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
+ * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
+ * (audit `architecture-output/final_report.md`) per plan
+ * arch-review-fixes-2026-06-06 § Phase 4 / T4.1 (D438).
+ *
+ * Public surface unchanged — `types/agent.ts` re-exports these from this
+ * leaf so `import type { ModelSelection, CustomTool } from "@theokit/sdk"`
+ * keeps resolving.
+ *
+ * @public
+ */
+/**
+ * One slot in a {@link ModelSelection.params} array.
+ *
+ * @public
+ */
+interface ModelParameterValue {
+    id: string;
+    value: string;
+}
+/**
+ * Identifies a model plus optional per-model parameters (e.g. reasoning effort).
+ *
+ * Use `Theokit.models.list()` to discover valid ids and parameter definitions.
+ *
+ * @public
+ */
+interface ModelSelection {
+    id: string;
+    params?: ModelParameterValue[];
+}
+/**
+ * SE12 — a read-only, text-only projection of one turn of the run's conversation,
+ * exposed to a tool handler via `ctx.messages`. Content is flattened to text; tool
+ * calls / results and non-text parts are dropped, and turns that project to empty
+ * text are omitted. Consumed by `defineSubAgent`'s `messageFilter` to forward
+ * (a subset of) the supervisor transcript to a subagent.
+ *
+ * `role` includes `"system"` for type-completeness with the wire message shape,
+ * but the system prompt travels on a separate request field — a `"system"` entry
+ * does NOT appear in the current projection.
+ *
+ * @public
+ */
+interface ToolContextMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * Local function tool declared per-agent via {@link AgentOptions.tools}. The
+ * handler runs in-process; no MCP server is involved. The SDK serializes
+ * `name`, `description`, and `inputSchema` into the model's tool catalog.
+ *
+ * Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
+ * persisted. The tool catalog (name + description + schema) is NOT serialized.
+ *
+ * @public
+ */
+interface CustomTool {
+    /**
+     * Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
+     * and must not collide with `shell`, `memory_search`, `memory_get`, or any
+     * `mcp_*` prefix (reserved for the SDK's built-in tools).
+     */
+    name: string;
+    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
+    description: string;
+    /** JSON Schema (Draft-7 subset) describing the `input` argument. Must be `type: "object"`. */
+    inputSchema: Record<string, unknown>;
+    /**
+     * Local handler invoked when the model emits `tool_use` for this tool.
+     * Returns a string OR structured content blocks (SE7 — text + image, e.g. a
+     * screenshot) that become the `tool_result.content` surfaced back to the
+     * model. Throws → SDK converts to `tool_result` with `isError: true` and the
+     * error `message` as content; throw a `ToolError` to carry a clean message or
+     * multimodal error content. #65 — an optional 2nd `ToolContext` argument
+     * carries the run's `AbortSignal`; single-argument handlers are unaffected. M7
+     * — the same `ctx` also carries an optional user `context` (provided once via
+     * `SendOptions.context`), so shared config like a `projectRoot` is read by
+     * every tool instead of baked into each factory. SE12 — `ctx.messages` is a
+     * read-only, text-only projection of the current turn's transcript (see
+     * {@link ToolContextMessage}); `defineSubAgent`'s `messageFilter` consumes it.
+     * #119 — `ctx.threadId` is the run's session identity (the key passed to
+     * `Agent.getOrCreate(sessionId, …)`, or the agent's own id), so a stateful tool
+     * shared across sessions can scope its state per session instead of leaking it.
+     */
+    handler: (input: Record<string, unknown>, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        messages?: readonly ToolContextMessage[];
+        threadId?: string;
+    }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
+}
+
+/**
+ * Type-leaf — base message types shared between `conversation.ts` and
+ * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
+ * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
+ * § Phase 4 / T4.1 (D438).
+ *
+ * Public surface unchanged — `types/conversation.ts` re-exports `UserMessage`
+ * from this leaf so `import type { UserMessage } from "@theokit/sdk"` keeps
+ * resolving.
+ *
+ * @public
+ */
+/**
+ * User-authored message in a conversation history.
+ *
+ * @public
+ */
+interface UserMessage {
+    text: string;
+}
+
+/**
+ * Single tool call event. The internal `args` and `result` shapes are NOT stable.
+ *
+ * @public
+ */
+interface ToolCall {
+    callId: string;
+    name: string;
+    args?: unknown;
+    result?: unknown;
+}
+/**
+ * Incremental text token from the assistant.
+ *
+ * @public
+ */
+interface TextDeltaUpdate {
+    type: "text-delta";
+    text: string;
+}
+/**
+ * Incremental reasoning token.
+ *
+ * @public
+ */
+interface ThinkingDeltaUpdate {
+    type: "thinking-delta";
+    text: string;
+}
+/**
+ * Emitted when a reasoning block completes.
+ *
+ * @public
+ */
+interface ThinkingCompletedUpdate {
+    type: "thinking-completed";
+    thinkingDurationMs: number;
+}
+/**
+ * Tool call started — args committed.
+ *
+ * @public
+ */
+interface ToolCallStartedUpdate {
+    type: "tool-call-started";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call arguments streaming in incrementally.
+ *
+ * @public
+ */
+interface PartialToolCallUpdate {
+    type: "partial-tool-call";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Tool call completed.
+ *
+ * @public
+ */
+interface ToolCallCompletedUpdate {
+    type: "tool-call-completed";
+    callId: string;
+    toolCall: ToolCall;
+    modelCallId: string;
+}
+/**
+ * Token count delta for usage tracking.
+ *
+ * @public
+ */
+interface TokenDeltaUpdate {
+    type: "token-delta";
+    tokens: number;
+}
+/**
+ * Conversation step started.
+ *
+ * @public
+ */
+interface StepStartedUpdate {
+    type: "step-started";
+    stepId: number;
+}
+/**
+ * Conversation step completed.
+ *
+ * @public
+ */
+interface StepCompletedUpdate {
+    type: "step-completed";
+    stepId: number;
+    stepDurationMs: number;
+}
+/**
+ * Turn ended with usage summary.
+ *
+ * @public
+ */
+interface TurnEndedUpdate {
+    type: "turn-ended";
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+}
+/**
+ * User message appended to the conversation.
+ *
+ * @public
+ */
+interface UserMessageAppendedUpdate {
+    type: "user-message-appended";
+    userMessage: UserMessage;
+}
+/** @public */
+interface SummaryUpdate {
+    type: "summary";
+    summary: string;
+}
+/** @public */
+interface SummaryStartedUpdate {
+    type: "summary-started";
+}
+/** @public */
+interface SummaryCompletedUpdate {
+    type: "summary-completed";
+}
+/** @public */
+interface ShellOutputDeltaUpdate {
+    type: "shell-output-delta";
+    event: Record<string, unknown>;
+}
+/**
+ * Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
+ * consume these. Finer-grained than `SDKMessage` events.
+ *
+ * @public
+ */
+type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
+
+/**
+ * Plain assistant message in a conversation history.
+ *
+ * @public
+ */
+interface AssistantMessage {
+    text: string;
+}
+/**
+ * Reasoning step in a conversation history.
+ *
+ * @public
+ */
+interface ThinkingMessage {
+    text: string;
+    thinkingDurationMs?: number;
+}
+/**
+ * Shell command executed during a run.
+ *
+ * @public
+ */
+interface ShellCommand {
+    command: string;
+    workingDirectory?: string;
+}
+/**
+ * Output of a shell command.
+ *
+ * @public
+ */
+interface ShellOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Single step inside an agent turn.
+ *
+ * @public
+ */
+/**
+ * Result of a tool invocation. Pairs with the preceding `toolCall` step
+ * by `callId`. `isError: true` when the tool returned a failure result.
+ *
+ * T2.3 — added so `Run.conversation()` surfaces the full interaction
+ * including tool results (parity with OpenAI Agents `RunResult.new_items`).
+ *
+ * @public
+ */
+interface ToolResult {
+    callId: string;
+    name: string;
+    result: string;
+    isError: boolean;
+}
+type ConversationStep = {
+    type: "assistantMessage";
+    message: AssistantMessage;
+} | {
+    type: "toolCall";
+    message: ToolCall;
+} | {
+    type: "toolResult";
+    message: ToolResult;
+} | {
+    type: "thinkingMessage";
+    message: ThinkingMessage;
+};
+/**
+ * Agent turn: user message + assistant/tool/thinking steps.
+ *
+ * @public
+ */
+interface AgentConversationTurn {
+    userMessage?: UserMessage;
+    steps: ConversationStep[];
+}
+/**
+ * Shell turn: a command and its output.
+ *
+ * @public
+ */
+interface ShellConversationTurn {
+    shellCommand?: ShellCommand;
+    shellOutput?: ShellOutput;
+}
+/**
+ * Structured per-turn view of a run.
+ *
+ * @public
+ */
+type ConversationTurn = {
+    type: "agentConversationTurn";
+    turn: AgentConversationTurn;
+} | {
+    type: "shellConversationTurn";
+    turn: ShellConversationTurn;
+};
+
+/**
+ * Child-process environment policy contract (#54).
+ *
+ * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`
+ * layer owns the contract, and the application-layer implementation
+ * (`internal/runtime/lifecycle/env-policy.ts`) re-exports it for back-compat
+ * while owning the runtime logic (`resolveChildEnv`, secret patterns, …).
+ *
+ * Modes:
+ *  - `inherit-scrubbed` (DEFAULT) — inherit all parent vars EXCEPT secret-like
+ *    names (`*KEY*`, `*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). Non-breaking:
+ *    existing spawns keep every non-secret var; only secrets stop leaking.
+ *  - `core` — inherit ONLY a safe base allowlist (PATH/HOME/…); strongest scrub.
+ *  - `all` — explicit opt-out: inherit everything, secrets included.
+ *
+ * @public
+ */
+type EnvPolicy = "inherit-scrubbed" | "core" | "all";
+
+/**
+ * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
+ *
+ * @public
+ */
+type McpStdioServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Local agents only. Cloud rejects this field. */
+    cwd?: string;
+    /**
+     * #59 — per-request timeout in ms. A request that gets no reply within this
+     * window rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead
+     * of hanging the agent loop forever. Default 30_000.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * #54 — env inherit/scrub policy for the spawned MCP server process. Defaults
+     * to `"inherit-scrubbed"` (drop secret-like host vars: `*KEY*`/`*SECRET*`/
+     * `*TOKEN*`/`*PASSWORD*`/`*_AUTH*`/…) so a third-party MCP server binary cannot
+     * exfiltrate host secrets via the environment. `env` above is merged AFTER the
+     * policy and always wins. Pass `"all"` to restore full inheritance.
+     */
+    envPolicy?: EnvPolicy;
+};
+/**
+ * OAuth-style auth bundle for HTTP/SSE MCP servers.
+ *
+ * @public
+ */
+interface McpAuthConfig {
+    CLIENT_ID: string;
+    CLIENT_SECRET?: string;
+    scopes?: string[];
+    /**
+     * OAuth 2.1 PKCE flow configuration (ADR D41, v1.2+). When present, the
+     * SDK runs the PKCE flow on first use and stores tokens via keychain or
+     * file. Without this, the SDK relies on `CLIENT_SECRET` + manual headers.
+     */
+    oauth?: McpOAuthConfig;
+}
+/**
+ * OAuth 2.1 PKCE flow descriptor. See ADR D41.
+ *
+ * @public
+ */
+interface McpOAuthConfig {
+    /** Authorization endpoint (e.g. https://api.notion.com/v1/oauth/authorize). */
+    authorizationEndpoint: string;
+    /** Token endpoint (e.g. https://api.notion.com/v1/oauth/token). */
+    tokenEndpoint: string;
+    /** Where the OAuth `code` is received. */
+    redirectMode: "manual" | "localhost";
+    /** Localhost callback port (0 = random free port, default). */
+    localhostPort?: number;
+    /** Flow timeout in ms (default 300_000 = 5min). */
+    timeoutMs?: number;
+}
+/**
+ * HTTP or SSE MCP server.
+ *
+ * @public
+ */
+type McpHttpServerConfig = {
+    type?: "http" | "sse";
+    url: string;
+    /** Passed through. `Authorization` works here. */
+    headers?: Record<string, string>;
+    auth?: McpAuthConfig;
+    /**
+     * #59 — per-request timeout in ms, enforced via `AbortSignal.timeout`. A
+     * fetch that does not respond within this window rejects with a typed
+     * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
+     */
+    requestTimeoutMs?: number;
+};
+/**
+ * Union of MCP server configs.
+ *
+ * @public
+ */
+type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
+
+/**
+ * Tool invocation block emitted by the assistant.
+ *
+ * @public
+ */
+interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    /** Tool args are not part of the stable schema. Treat as unknown and parse defensively. */
+    input: unknown;
+}
+/**
+ * Init metadata. Emitted once at the start of a run.
+ *
+ * @public
+ */
+interface SDKSystemMessage {
+    type: "system";
+    subtype?: "init";
+    agent_id: string;
+    run_id: string;
+    model?: ModelSelection;
+    tools?: string[];
+}
+/**
+ * Echo of the user prompt for this run.
+ *
+ * @public
+ */
+interface SDKUserMessageEvent {
+    type: "user";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "user";
+        content: TextBlock[];
+    };
+}
+/**
+ * Model text output for this run.
+ *
+ * @public
+ */
+interface SDKAssistantMessage {
+    type: "assistant";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "assistant";
+        content: Array<TextBlock | ToolUseBlock>;
+    };
+}
+/**
+ * Reasoning content.
+ *
+ * @public
+ */
+interface SDKThinkingMessage {
+    type: "thinking";
+    agent_id: string;
+    run_id: string;
+    text: string;
+    thinking_duration_ms?: number;
+}
+/**
+ * Tool invocation lifecycle event. Emitted at start with `args`, then again on
+ * completion with `result`.
+ *
+ * Tool `args` and `result` are NOT part of the stable schema — treat as unknown.
+ *
+ * @public
+ */
+interface SDKToolUseMessage {
+    type: "tool_call";
+    agent_id: string;
+    run_id: string;
+    call_id: string;
+    name: string;
+    status: "running" | "completed" | "error";
+    args?: unknown;
+    result?: unknown;
+    truncated?: {
+        args?: boolean;
+        result?: boolean;
+    };
+}
+/**
+ * Cloud run lifecycle transitions.
+ *
+ * @public
+ */
+interface SDKStatusMessage {
+    type: "status";
+    agent_id: string;
+    run_id: string;
+    status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED";
+    message?: string;
+}
+/**
+ * Task-level milestones and summaries.
+ *
+ * @public
+ */
+interface SDKTaskMessage {
+    type: "task";
+    agent_id: string;
+    run_id: string;
+    status?: string;
+    text?: string;
+}
+/**
+ * Awaiting user input or approval.
+ *
+ * @public
+ */
+interface SDKRequestMessage {
+    type: "request";
+    agent_id: string;
+    run_id: string;
+    request_id: string;
+}
+/**
+ * Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
+ * `partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
+ * erased to `unknown` here because SDKMessage union is non-generic.
+ *
+ * @public
+ */
+interface SDKObjectDelta {
+    type: "object_delta";
+    agent_id: string;
+    run_id: string;
+    partial: unknown;
+    attempt: number;
+}
+/**
+ * Discriminated union of all stream events. Discriminate on `type`.
+ *
+ * All events include `agent_id` and `run_id`.
+ *
+ * @public
+ */
+type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
+
+/**
+ * Public type contract for token usage + cost tracking (ADRs D376-D379).
+ *
+ * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
+ * Re-exported through the package barrel; consumers import from
+ * `@theokit/sdk`.
+ *
+ * @public
+ */
+/**
+ * Token usage observed during a Run. 5 closed buckets (D376) cover
+ * 100% of providers in 2026: OpenAI Chat / OpenAI Responses (o-series
+ * with reasoning) / Anthropic Messages (with prompt caching).
+ *
+ * `totalTokens` is derived (`inputTokens + outputTokens`); EC-10
+ * invariant: SDK must never emit `totalTokens !== inputTokens + outputTokens`.
+ *
+ * `requests[]` is the per-request breakdown (mirror a peer SDK)
+ * — populated only when the run made > 1 LLM call.
+ */
+interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+    readonly totalTokens: number;
+    /** Per-request breakdown; absent when the run made a single LLM call. */
+    readonly requests?: ReadonlyArray<Omit<TokenUsage, "requests">>;
+}
+/**
+ * Cost confidence level (D377).
+ * - `actual`: returned by a provider billing API (e.g. OpenRouter `/generation`).
+ * - `estimated`: computed from bundled pricing snapshot.
+ * - `included`: subscription-included route (Codex CLI, Claude Pro).
+ * - `unknown`: pricing data unavailable; `amountUsd` is undefined.
+ */
+type CostStatus = "actual" | "estimated" | "included" | "unknown";
+/** Source of the cost figure for caller-side audit. */
+type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "subscription_included" | "unknown";
+/**
+ * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
+ * `amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
+ * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
+ */
+interface CostBreakdown {
+    readonly amountUsd: number | undefined;
+    readonly status: CostStatus;
+    readonly currency: "USD";
+    readonly source: CostSource;
+    readonly pricingVersion: string | undefined;
+    readonly notes?: ReadonlyArray<string>;
+    /** Per-bucket detail (in USD) for caller analytics. */
+    readonly detail?: {
+        readonly input?: number;
+        readonly output?: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+        readonly reasoning?: number;
+    };
+}
+
+/**
+ * Options for the tool-result guard (spotlighting + PII redaction on tool
+ * output). Contract type owned by `types/` (SE45 / D435) — the implementation
+ * lives in `internal/agent-loop/tool-result-guard.ts`, which re-exports this.
+ *
+ * @public
+ */
+interface ToolResultGuardOptions {
+    /** Wrap tool-result content in explicit data boundaries (spotlighting). */
+    delimit?: boolean;
+    /** Redact common PII patterns (email, phone) in tool-result content. */
+    redactPii?: boolean;
+}
+/**
+ * Lifecycle status of a {@link Run}.
+ *
+ * @public
+ */
+type RunStatus = "running" | "finished" | "error" | "cancelled";
+/**
+ * Operations that may or may not be supported on a given {@link Run}, or on
+ * its parent agent.
+ *
+ * Runtime-specific availability — query at runtime with `run.supports(op)` and
+ * read the human reason via `run.unsupportedReason(op)`.
+ *
+ * @public
+ */
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
+/**
+ * Git metadata attached to cloud runs.
+ *
+ * @public
+ */
+interface RunGitInfo {
+    branches: Array<{
+        repoUrl: string;
+        branch?: string;
+        prUrl?: string;
+    }>;
+}
+/**
+ * SE3 — provenance of the turn that produced a run: WHO triggered it. Stamped in
+ * the multi-agent path (Squad / a2a / handoff / background-delegation) and
+ * forwarded onto {@link RunResult.origin} — so consumers can attribute/route
+ * turns by their trigger. Metadata-only; discriminate on `kind`. Mirrors the
+ * Anthropic Agent SDK's `origin` shape.
+ *
+ * Encoding note (distinct from absence): an ABSENT origin (`undefined`) means the
+ * provenance was NOT stamped — the default for a plain `agent.send()`. The explicit
+ * `{ kind: "human" }` is a positive marker a HOST stamps to say "this turn is
+ * definitely from a human" (e.g. to distinguish a real user message from an
+ * un-attributed one in an audit UI). The two are not interchangeable: `undefined`
+ * = unknown/unstamped; `{ kind: "human" }` = explicitly human. Consumers writing an
+ * exhaustive `switch (origin?.kind)` therefore handle `undefined` (unstamped) and
+ * `"human"` (explicit) as separate, meaningful cases.
+ *
+ * @public
+ */
+/**
+ * SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).
+ * Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent
+ * delegation), `auto-continuation` (the run-to-completion / stream-to-completion
+ * driver's continuation rounds) are stamped BY the SDK. `human` and
+ * `task-notification` are positive markers a HOST stamps (e.g. re-sending an
+ * agent after a background task completed). Absent origin ⇒ `undefined`.
+ *
+ * @public
+ */
+type MessageOrigin = 
+/** Explicitly a human-triggered turn — a positive marker a host stamps (NOT the
+ *  same as an absent/unstamped origin, which is `undefined`). */
+{
+    readonly kind: "human";
+}
+/** Another agent (a Squad peer or an a2a sender) triggered this turn. */
+ | {
+    readonly kind: "peer";
+    readonly from: string;
+}
+/** A background task's completion re-entered the agent as a follow-up turn. */
+ | {
+    readonly kind: "task-notification";
+}
+/** A delegating/handoff coordinator triggered this turn. `from` is the coordinator's
+ *  id when known, omitted for an anonymous coordinator. */
+ | {
+    readonly kind: "coordinator";
+    readonly from?: string;
+}
+/** The loop's continuation driver re-sent to continue truncated work. */
+ | {
+    readonly kind: "auto-continuation";
+};
+/**
+ * Terminal result of a {@link Run}.
+ *
+ * @public
+ */
+interface RunResult {
+    id: string;
+    status: "finished" | "error" | "cancelled";
+    result?: string;
+    /**
+     * SE24 — set when a guardrail processor called `abort()`. The run stops
+     * (`status: "cancelled"`) and `tripwire` carries the blocking reason +
+     * processor id. `undefined` on every non-guardrail outcome. A
+     * `throwOnError: true` agent resolves normally on a tripwire (status is
+     * `"cancelled"`, not `"error"`). On an OUTPUT block the model already ran, so
+     * `usage`/`cost` survive (billing) while `result` is suppressed; an INPUT
+     * block never reaches the model, so `usage` is absent.
+     *
+     * @public
+     */
+    tripwire?: ProcessorTripwire;
+    model?: ModelSelection;
+    durationMs?: number;
+    git?: RunGitInfo;
+    /**
+     * SE3 — provenance forwarded from {@link SendOptions.origin}: who triggered
+     * this turn (human / peer / task-notification / coordinator / auto-continuation).
+     * `undefined` means the provenance was not stamped (a plain `agent.send()`).
+     * Metadata-only — never affects routing.
+     *
+     * @public
+     */
+    origin?: MessageOrigin;
+    /**
+     * Structured error detail, populated when `status === "error"`. Surfaces
+     * the diagnostic that emit-error-event pushes into the stream so callers
+     * that don't drain `run.stream()` still get the cause via `run.wait()`.
+     *
+     * For successful runs (`status: "finished"`) this is undefined.
+     *
+     * @public
+     */
+    error?: RunErrorDetail;
+    /**
+     * Token usage observed for this run (ADR D376). Populated in every
+     * status where ≥1 LLM call completed — including partial-failure
+     * runs (EC-5). `undefined` only when zero LLM calls executed (e.g.,
+     * abort before send).
+     *
+     * @public
+     */
+    usage?: TokenUsage;
+    /**
+     * Estimated/actual USD cost for this run (ADR D377). Always paired
+     * with `usage` when populated. `cost.status` tells caller how to
+     * trust the figure.
+     *
+     * @public
+     */
+    cost?: CostBreakdown;
+    /**
+     * M1-2: `true` when the run stopped because the agent loop hit its iteration
+     * ceiling (`SendOptions.maxIterations` or the default of 8) while the model
+     * still wanted to call tools — i.e. the work was silently truncated rather
+     * than finished. `undefined`/absent on a clean finish. A continuation driver
+     * (or a careful caller) inspects this to decide whether to send again.
+     *
+     * @public
+     */
+    stoppedAtIterationLimit?: boolean;
+    /**
+     * `true` when the run stopped because the **doom-loop guard** detected the model repeating
+     * IDENTICAL tool calls (same name + same input) to the hard threshold — making no progress (e.g.
+     * a tool that keeps failing and is retried unchanged). `undefined`/absent otherwise. Through the
+     * continuation driver this surfaces as `terminal: "no_progress"` (a controlled stop, NOT a
+     * truncation to re-send). Tune or disable via {@link SendOptions.doomLoop}.
+     *
+     * @public
+     */
+    stoppedByDoomLoop?: boolean;
+    /**
+     * SE34 — the per-send completion verdict, populated when
+     * {@link SendOptions.completionCheck} was set AND the run finished. Absent on
+     * non-finished runs and when no completion check was requested. Reuses the
+     * shipped LLM-as-judge (same one `runUntil` drives). @public
+     */
+    completionCheck?: CompletionCheckResult;
+}
+/**
+ * Doom-loop guard thresholds (see {@link SendOptions.doomLoop}). Both are counts of CONSECUTIVE
+ * identical tool calls: `softThreshold` injects a one-time guidance nudge; `hardThreshold` stops.
+ *
+ * @public
+ */
+interface DoomLoopThresholds {
+    /** Consecutive-identical count at which a one-time guidance nudge is injected. Default 3. */
+    softThreshold?: number;
+    /** Consecutive-identical count at which the run stops (`no_progress`). Default 5. */
+    hardThreshold?: number;
+}
+/**
+ * Options for {@link SDKAgent.runToCompletion} (M1 Phase 3 — continuation driver).
+ *
+ * @public
+ */
+interface RunToCompletionOptions {
+    /**
+     * Maximum number of continuation rounds (re-sends) before giving up with
+     * `terminal: "step_limit"`. Default 5. A hard ceiling that prevents a
+     * runaway loop when the model keeps truncating.
+     */
+    maxRounds?: number;
+    /**
+     * The short prompt re-sent after a truncated round to make the (stateful)
+     * agent resume. Defaults to a generic "continue" instruction. The original
+     * conversation is preserved by the agent's session, so this need not repeat
+     * the task.
+     */
+    continuationPrompt?: string;
+    /** Called once per truncated round that triggers a re-send (for metrics/logging). */
+    onTruncated?: (event: {
+        round: number;
+    }) => void | Promise<void>;
+    /** Abort signal; checked between rounds — once aborted, no further round starts. */
+    signal?: AbortSignal;
+    /** Per-send options forwarded to each underlying `send()` (e.g. `maxIterations`). */
+    sendOptions?: SendOptions;
+}
+/**
+ * Result of {@link SDKAgent.runToCompletion}.
+ *
+ * @public
+ */
+interface RunToCompletionResult {
+    /**
+     * Why the driver stopped:
+     * - `"done"` — a round finished without truncating (the model is done).
+     * - `"step_limit"` — `maxRounds` exhausted (or aborted) while still truncating.
+     * - `"no_progress"` — two consecutive rounds produced empty output.
+     */
+    terminal: "done" | "step_limit" | "no_progress";
+    /**
+     * Index of the final round. Round 0 is the initial `send`; rounds ≥ 1 are
+     * continuation re-sends. So `terminal: "done"` with `rounds: 0` means the
+     * first send finished without truncating; `rounds: N` means N continuation
+     * re-sends happened. For `step_limit`, `rounds` equals `maxRounds`.
+     */
+    rounds: number;
+    /** The `RunResult` of the final round. */
+    lastResult: RunResult;
+    /** Token usage summed across all rounds; `undefined` when no round reported usage. */
+    usage?: TokenUsage;
+}
+/**
+ * Result of {@link SDKAgent.streamToCompletion} (V3-4 — the STREAMING continuation
+ * driver). Same shape + terminal semantics as {@link RunToCompletionResult}; it is
+ * the generator's RETURN value (read it via a manual `gen.next()` loop — a plain
+ * `for await...of` consumes the yielded `SDKMessage`s but discards this return value).
+ *
+ * @public
+ */
+type StreamToCompletionResult = RunToCompletionResult;
+/**
+ * Structured error attached to a {@link RunResult} when the underlying run
+ * transitioned to `"error"` status. `message` is always present; `code` is
+ * a stable identifier suitable for branching (e.g. `"llm_4xx"`,
+ * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
+ * for further inspection when available.
+ *
+ * @public
+ */
+interface RunErrorDetail {
+    message: string;
+    code?: string;
+    cause?: unknown;
+}
+/**
+ * Dimensions of an inline image attachment.
+ *
+ * @public
+ */
+interface SDKImageDimension {
+    width: number;
+    height: number;
+}
+/**
+ * Either a remote URL or inline base64 payload.
+ *
+ * @public
+ */
+type SDKImage = {
+    url: string;
+    dimension?: SDKImageDimension;
+} | {
+    data: string;
+    mimeType: string;
+    dimension?: SDKImageDimension;
+};
+/**
+ * Structured form of `agent.send()`'s message argument. Use it to send images
+ * alongside text.
+ *
+ * @public
+ */
+interface SDKUserMessage {
+    text: string;
+    images?: SDKImage[];
+}
+/**
+ * Per-send overrides and callbacks.
+ *
+ * @public
+ */
+interface SendOptions {
+    /**
+     * Per-send model override. SE8 — accepts a bare-string id shorthand
+     * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
+     * object (use the object form to pass `params`).
+     */
+    model?: string | ModelSelection;
+    /**
+     * SE3 — provenance of this turn (who triggered it). Stamped by the multi-agent
+     * path (Squad peer, a2a sender, coordinator/handoff, background task-notification)
+     * and forwarded onto {@link RunResult.origin}. Metadata-only — the value never
+     * changes routing or dispatch. Omit to leave the turn un-attributed; a host may
+     * pass `{ kind: "human" }` to positively mark a human turn.
+     */
+    origin?: MessageOrigin;
+    /**
+     * SE2 — opt-in typed runtime-EVENT sink. Receives out-of-band `RunEvent`s
+     * (permission_denied, tool_progress, rate_limit, task_*, compact_boundary) for
+     * observability, ADDITIVE to the `SDKMessage` content stream. Best-effort: a
+     * throwing sink never breaks the run. Discriminate on `event.type`.
+     */
+    onRunEvent?: RunEventSink;
+    /**
+     * Doom-loop guard config. The loop stops (with `terminal: "no_progress"`, `RunResult.stoppedByDoomLoop`)
+     * when the model repeats IDENTICAL tool calls to the hard threshold. On by default with generous
+     * thresholds (soft 3 / hard 5). Set `false` to disable, or an object to tune the thresholds.
+     */
+    doomLoop?: false | DoomLoopThresholds;
+    /**
+     * Per-call system prompt override. Wins over `AgentOptions.systemPrompt`.
+     * String only — for dynamic resolvers, configure on `AgentOptions`. An
+     * empty string is honoured (it explicitly clears the system context).
+     */
+    systemPrompt?: string;
+    /** Fully replaces creation-time servers for this run (not merged). */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-call inline custom tools. Fully replaces `AgentOptions.tools` for
+     * this run (not merged). Local runtime only — cloud agents reject any
+     * non-empty per-call tools array with the same error code as creation
+     * (`cloud_custom_tools_rejected`). Semantics:
+     * - `undefined` → fall back to `AgentOptions.tools`
+     * - `[]` → explicitly clear (no custom tools for this run)
+     * - `[t1, t2]` → use exactly these tools for this run
+     */
+    tools?: CustomTool[];
+    /**
+     * The set of repo-relative file paths in scope for THIS send (local runtime).
+     * Declares "which files am I working on" so path-scoped rule files
+     * (`.theokit/rules/*.md` with `paths:`/`globs:`, and `.cursor/rules/*.mdc`
+     * globs) activate when a pattern matches one of these paths. `alwaysApply`
+     * rules load regardless. Omit ⇒ only unconditional rules load (the create-time
+     * snapshot is untouched). Matching is glob-based (`**`, `*`, `?`).
+     */
+    contextPaths?: readonly string[];
+    /**
+     * SE1 — the permission mode for THIS run, threaded to a registered
+     * `PermissionPlugin`'s pre-tool gate. Precedence: this per-send value wins over
+     * `AgentOptions.permissionMode` (creation-time default). Modes: `default` (rules
+     * decide; unmatched ⇒ fail-closed ask), `plan` (read-only — allow rules pass,
+     * everything else denied), `acceptEdits` (auto-approve unmatched, honor explicit
+     * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
+     * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
+     */
+    permissionMode?: PermissionMode;
+    onStep?: (args: {
+        step: ConversationStep;
+    }) => void | Promise<void>;
+    onDelta?: (args: {
+        update: InteractionUpdate;
+    }) => void | Promise<void>;
+    /**
+     * Per-call tool gate (OpenAI/OpenRouter `tool_choice`). `"none"` forces a text answer even when
+     * the agent has tools registered — used by an agent loop to force a closing summary at its step
+     * ceiling (a cached agent's tools cannot be un-registered, so the gate is per-send). `"required"`
+     * forces a tool call; `"auto"` (or omitted) is the default. Local runtime; OpenAI-compat providers.
+     */
+    toolChoice?: "auto" | "none" | "required";
+    /**
+     * SE18 — per-send runtime tool subset (**local runtime only**; cloud agents
+     * ignore it). When set, only tools whose name is in this list may be called for
+     * this send; a call to any other registered tool is vetoed at dispatch (the same
+     * `withToolWhitelist` path `Agent.fork`'s `allowedTools` uses — NOT
+     * `PermissionEngine`). Composes with `toolChoice`: `activeTools` narrows the set,
+     * `toolChoice` gates calling within it. Absent ⇒ the full toolset is available.
+     *
+     * Matching is EXACT against the tool's registered name — the same name the
+     * dispatch sees after tool-name repair (mirrors `Agent.fork`'s `allowedTools`;
+     * it is NOT lowercased for you, so a mixed-case registered tool needs its exact
+     * registered name here). An empty list (`[]`) vetoes EVERY tool (fail-closed —
+     * "restrict to the empty set"); pass `undefined` (or omit) for no restriction.
+     * A subagent invoked within this send inherits the whitelist via async-context
+     * propagation unless it declares its own tool scope.
+     */
+    activeTools?: string[];
+    /** Local agents only. Expire a stuck active run before starting this message. */
+    local?: {
+        force?: boolean;
+    };
+    /**
+     * Optional `AbortSignal` propagated to memory adapter `pre_user_send`
+     * hooks (EC-H). Note: the LLM HTTP call itself is NOT cancellable
+     * mid-stream — same constraint as `Agent.batch` (ADR D140).
+     *
+     * @public
+     */
+    signal?: AbortSignal;
+    /**
+     * M7 — an opaque user `context` forwarded to every tool handler's `ctx.context`
+     * for this run. Set shared config (e.g. `projectRoot`) once here instead of
+     * baking it into each tool factory (mirrors a framework `experimental_context`,
+     * a peer framework `RuntimeContext`, a peer SDK `RunContext`).
+     *
+     * @public
+     */
+    context?: unknown;
+    /**
+     * #58 — per-tool execution timeout in ms. Each tool call is bounded by this
+     * deadline (merged with `signal`); a hung tool yields a typed timeout result
+     * (exit 124) instead of wedging the run. Undefined = no per-tool timeout.
+     *
+     * @public
+     */
+    perToolTimeoutMs?: number;
+    /**
+     * #57 — opt-in tool-result content guard applied before tool output reaches
+     * the LLM. `{ delimit: true }` frames untrusted tool output as data
+     * (prompt-injection mitigation); `{ redactPii: true }` redacts email/phone.
+     * Undefined = no guard.
+     *
+     * @public
+     */
+    toolResultGuard?: ToolResultGuardOptions;
+    /**
+     * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
+     * run is registered as a `Task` in the SDK's observable registry —
+     * caller can list / inspect / cancel / subscribe via the `Task`
+     * namespace. Default behavior (no `task` option) is byte-identical
+     * to v1.1 (no Task overhead).
+     *
+     * Accepts:
+     * - `true` — auto-generate task id; no extra metadata.
+     * - `{ id, meta }` — user-supplied id (D368 grammar enforced) and/or
+     *   metadata attached to the handle's `meta` field.
+     *
+     * The work-fn `signal` is **merged** with `options.signal` (whichever
+     * aborts first wins). Local agents only — CloudAgent throws
+     * `UnsupportedTaskOperationError` (D370).
+     *
+     * @public
+     */
+    task?: true | {
+        id?: string;
+        meta?: Record<string, unknown>;
+    };
+    /**
+     * Per-send ceiling on the agent loop's tool-calling turns (M1-2). Raises (or
+     * lowers) the default cap of 8 for this single send — useful when one heavy
+     * task needs more rounds than the agent's default. Must be a positive
+     * integer; invalid values throw `ConfigurationError` at the boundary. When
+     * unset, the loop uses the default of 8.
+     *
+     * @public
+     */
+    maxIterations?: number;
+    /**
+     * SE34 — per-send completion check (`isTaskComplete`). After this single
+     * `send()` reaches a terminal `finished` state, the shipped LLM-as-judge
+     * scores the final reply against `criteria` and surfaces the verdict on
+     * {@link RunResult.completionCheck} + a `completion_check` run-event. This is
+     * the finer-grained, single-`send()` gate (contrast `runUntil`, which judges
+     * the FULL response BETWEEN sends). Opt-in — absent ⇒ the send is byte-identical
+     * to today (no extra judge call). Non-finished runs skip the check. The judge
+     * runs when `wait()` is called on the returned `Run`; a stream-only consumer
+     * must call `wait()` to trigger the verdict + the `completion_check` event.
+     *
+     * @public
+     */
+    completionCheck?: CompletionCheck;
+}
+/**
+ * SE34 — the per-send completion criterion (see {@link SendOptions.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheck {
+    /** What "complete" means for this send — fed to the judge as the goal. */
+    criteria: string;
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"`. */
+    judgeModel?: string;
+    /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * SE34 — the resolved per-send completion verdict (see {@link RunResult.completionCheck}).
+ *
+ * @public
+ */
+interface CompletionCheckResult {
+    /** `true` when the judge ruled the send's reply satisfies the criteria. */
+    complete: boolean;
+    /** The judge's stated reason. */
+    reason: string;
+    /** `true` when the judge output could not be parsed — fail-safe `complete: false`. */
+    parseFailed: boolean;
+}
+/**
+ * Handle to a single prompt submission.
+ *
+ * @public
+ */
+interface Run {
+    readonly id: string;
+    readonly agentId: string;
+    readonly status: RunStatus;
+    readonly result?: string;
+    readonly model?: ModelSelection;
+    readonly durationMs?: number;
+    readonly git?: RunGitInfo;
+    readonly createdAt?: number;
+    /** AsyncGenerator of normalized stream events. Discriminate on `event.type`. */
+    stream(): AsyncGenerator<SDKMessage, void>;
+    /** Resolves to the terminal {@link RunResult}. */
+    wait(): Promise<RunResult>;
+    /** Move status to `"cancelled"`, abort the stream, stop in-flight tool calls. */
+    cancel(): Promise<void>;
+    /** Structured per-turn view of the conversation. */
+    conversation(): Promise<ConversationTurn[]>;
+    /** Whether the given operation is available on this run's runtime. */
+    supports(operation: RunOperation): boolean;
+    /** Human-readable reason that `supports(operation)` returned `false`. */
+    unsupportedReason(operation: RunOperation): string | undefined;
+    /** Subscribe to status changes. Returns an unsubscribe function. */
+    onDidChangeStatus(listener: (status: RunStatus) => void): () => void;
+}
+/**
+ * SE9 — options for the integrated structured-output method `agent.generate`: the
+ * {@link SendOptions} that drive the tool loop (phase 1) plus the required `output`
+ * Zod schema and structuring knobs (phase 2). Co-located with `SendOptions` /
+ * `RunResult` (which they extend/use) so the public `SDKAgent` interface does not
+ * import the runtime `agent-generate` module (breaks the type cycle).
+ *
+ * @public
+ */
+interface GenerateOptions<T extends zod.ZodType> extends SendOptions {
+    /** Zod schema the final answer is coerced into (the structuring contract). */
+    output: T;
+    /** Retry budget on the structuring phase's parse-failures (reused from generateObject). Default 1. */
+    maxRetries?: number;
+    /**
+     * What the STRUCTURING phase (phase 2) does when the model's output still fails
+     * Zod validation after retries. Default `"throw"`. `"return-partial"` / `"return-raw"`
+     * salvage the object; the salvaged/raw value is in {@link GenerateRunResult.raw}
+     * (the pre-parse structuring input) — NOT the phase-1 text answer, which is in
+     * `result.result`.
+     */
+    errorStrategy?: "throw" | "return-partial" | "return-raw";
+}
+/**
+ * SE9 — result of `agent.generate`: the validated typed object plus the underlying
+ * tool-loop {@link RunResult} (status / usage / model) and the raw pre-parse input.
+ *
+ * @public
+ */
+interface GenerateRunResult<O> {
+    /** The validated object — inferred type from the `output` schema. */
+    object: O;
+    /** The underlying tool-loop run (phase 1). */
+    result: RunResult;
+    /** Raw model input to the synthetic `output` tool, before the Zod parse. */
+    raw: unknown;
+    /** Combined token usage of the structuring phase. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+export { type RunToCompletionResult as $, type AgentConversationTurn as A, type ProcessorControls as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorTripwire as E, type ProcessorViolation as F, type GenerateOptions as G, type RunCompactBoundaryEvent as H, type ImageBlock as I, type RunCompletionCheckEvent as J, type RunErrorDetail as K, type RunEvent as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunToCompletionOptions as _, type McpServerConfig as a, type RunToolProgressEvent as a0, type RunTripwireEvent as a1, type SDKAssistantMessage as a2, type SDKImage as a3, type SDKImageDimension as a4, type SDKObjectDelta as a5, type SDKRequestMessage as a6, type SDKStatusMessage as a7, type SDKSystemMessage as a8, type SDKTaskMessage as a9, type ToolResult as aA, type ToolResultGuardOptions as aB, type ToolUseBlock as aC, type TurnEndedUpdate as aD, type UserMessage as aE, type UserMessageAppendedUpdate as aF, applyMode as aG, emitRunEvent as aH, type SDKThinkingMessage as aa, type SDKToolUseMessage as ab, type SDKUserMessage as ac, type SDKUserMessageEvent as ad, type SendOptions as ae, type ShellCommand as af, type ShellConversationTurn as ag, type ShellOutput as ah, type ShellOutputDeltaUpdate as ai, type StepCompletedUpdate as aj, type StepStartedUpdate as ak, type StreamToCompletionResult as al, type SummaryCompletedUpdate as am, type SummaryStartedUpdate as an, type SummaryUpdate as ao, type TextBlock as ap, type TextDeltaUpdate as aq, type ThinkingCompletedUpdate as ar, type ThinkingDeltaUpdate as as, type ThinkingMessage as at, type TokenDeltaUpdate as au, type TokenUsage as av, type ToolCall as aw, type ToolCallCompletedUpdate as ax, type ToolCallStartedUpdate as ay, type ToolContextMessage as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type RunEventSink as e, type AssistantMessage as f, type CompletionCheck as g, type CompletionCheckResult as h, type ConversationStep as i, type ConversationTurn as j, type CostBreakdown as k, type CostSource as l, type CostStatus as m, type GenerateRunResult as n, type InputProcessorContext as o, type InteractionUpdate as p, type McpAuthConfig as q, type McpHttpServerConfig as r, type McpOAuthConfig as s, type McpStdioServerConfig as t, type MessageOrigin as u, type ModelParameterValue as v, type PartialToolCallUpdate as w, type PermissionAction as x, type PermissionEngineOptions as y, type PermissionRule as z };