@theokit/sdk 2.19.0 → 2.21.0

package/dist/internal/agent-loop/loop-types.d.ts

@@ -1,6 +1,8 @@
 import type { ConversationTurn } from "../../types/conversation.js";
 import type { SDKMessage } from "../../types/messages.js";
 import type { RunStatus } from "../../types/run.js";
+/** SE7 — what a custom tool handler may return: a string or structured content blocks. */
+export type ToolHandlerResult = string | import("../../types/content-blocks.js").ToolResultContentBlock[];
 export interface AgentLoopOutput {
     events: SDKMessage[];
     finalStatus: RunStatus;

package/dist/internal/agent-loop/tool-result-guard.d.ts

@@ -11,6 +11,7 @@
  *
  * @internal
  */
+import type { LlmContentPart } from "../llm/types.js";
 export interface ToolResultGuardOptions {
     /** Wrap tool-result content in explicit data boundaries (spotlighting). */
     delimit?: boolean;

package/dist/internal/llm/tool-result-content.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SE7 — provider-agnostic helpers for structured tool-result content
+ * ({@link ToolResultContentBlock}). Named by CAPABILITY, not by provider:
+ *
+ * - `toBlockToolResultContent` — for a wire that ACCEPTS content blocks.
+ * - `toStringToolResultContent` — for a string-only wire (fail-fast on an image).
+ * - `renderToolResultContentText` — map the text parts through a fn (for the guard).
+ *
+ * @internal
+ */
+import type { ToolResultContentBlock } from "../../types/content-blocks.js";
+/**
+ * For a block-capable provider wire: pass a string through unchanged, or forward
+ * the structured blocks as-is (text + image).
+ *
+ * This is an INTENTIONAL identity: `ToolResultContentBlock` is defined to be
+ * exactly the on-wire content-block shape that block-capable providers accept
+ * for a tool result — `{ type: "text", text }` and
+ * `{ type: "image", source: { type: "base64", media_type, data } }`. Because the
+ * SDK type already IS the wire shape, no transformation is needed; this function
+ * names that contract at the call site (and is the single seam to add a mapping
+ * later, if a block-capable wire ever diverges from this shape). Do NOT add
+ * SDK-internal fields to `ToolResultContentBlock` without updating this seam —
+ * they would otherwise be forwarded verbatim onto the wire.
+ */
+export declare function toBlockToolResultContent(content: string | ToolResultContentBlock[]): string | ToolResultContentBlock[];
+/**
+ * For a string-only provider wire: pass a string through; flatten text-only
+ * blocks to a newline-joined string; **fail fast** with a typed
+ * {@link ConfigurationError} when an image block is present — that provider
+ * cannot carry an image in a tool result, and silently dropping it would hand
+ * the model a lie (per error-handling policy).
+ */
+export declare function toStringToolResultContent(content: string | ToolResultContentBlock[], providerName: string): string;
+/**
+ * Apply `fn` to the text of a tool-result content (both the string form and the
+ * text blocks of the structured form); image blocks pass through untouched.
+ * Used by the tool-result guard so redaction/delimiting still covers text.
+ */
+export declare function renderToolResultContentText(content: string | ToolResultContentBlock[], fn: (text: string) => string): string | ToolResultContentBlock[];

package/dist/internal/llm/types.d.ts

@@ -19,7 +19,12 @@ export interface LlmToolCallPart {
 export interface LlmToolResultPart {
     type: "tool_result";
     toolUseId: string;
-    content: string;
+    /**
+     * SE7 — a string (the common case) OR structured content blocks (text +
+     * image). Block-capable provider wires forward blocks natively; string-only
+     * wires flatten text and fail fast on an image (`toStringToolResultContent`).
+     */
+    content: string | import("../../types/content-blocks.js").ToolResultContentBlock[];
     isError?: boolean;
 }
 export type LlmContentPart = LlmTextPart | LlmToolCallPart | LlmToolResultPart;

package/dist/internal/persistence/conversation-storage-fs.d.cts

@@ -16,7 +16,7 @@
  *
  * @public
  */
-import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
 export interface FileSystemConversationStorageOptions {
     /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
     root?: string;
@@ -39,5 +39,7 @@ export declare class FileSystemConversationStorage implements ConversationStorag
         limit?: number;
     }): Promise<readonly string[]>;
     compact(conversationId: string, maxTurns: number): Promise<void>;
+    getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
+    setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-fs.d.ts

@@ -16,7 +16,7 @@
  *
  * @public
  */
-import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
 export interface FileSystemConversationStorageOptions {
     /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
     root?: string;
@@ -39,5 +39,7 @@ export declare class FileSystemConversationStorage implements ConversationStorag
         limit?: number;
     }): Promise<readonly string[]>;
     compact(conversationId: string, maxTurns: number): Promise<void>;
+    getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
+    setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-memory.d.cts

@@ -11,7 +11,7 @@
  *
  * @public
  */
-import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
 export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
     #private;
     getMessages(conversationId: string, opts?: {
@@ -26,5 +26,7 @@ export declare class InMemoryConversationStorage implements ConversationStorageA
     listConversationIds(opts?: {
         limit?: number;
     }): Promise<readonly string[]>;
+    getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
+    setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/conversation-storage-memory.d.ts

@@ -11,7 +11,7 @@
  *
  * @public
  */
-import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+import type { ConversationStorageAdapter, SessionMeta, SessionMetaPatch, StoredMessage } from "../../types/conversation-storage.js";
 export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
     #private;
     getMessages(conversationId: string, opts?: {
@@ -26,5 +26,7 @@ export declare class InMemoryConversationStorage implements ConversationStorageA
     listConversationIds(opts?: {
         limit?: number;
     }): Promise<readonly string[]>;
+    getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
+    setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/internal/persistence/session-meta.d.cts

@@ -0,0 +1,13 @@
+/**
+ * SE4 — shared merge logic for {@link SessionMeta} + {@link SessionMetaPatch},
+ * used identically by every {@link ConversationStorageAdapter} that persists
+ * session metadata (FS sidecar + in-memory). Single source of truth for the
+ * patch semantics: an omitted field is unchanged; a `null` field CLEARS it; a
+ * string SETS it.
+ *
+ * @internal
+ */
+/** Apply a patch to session metadata, returning a fresh object. */
+export declare function applyMetaPatch(current: SessionMeta, patch: SessionMetaPatch): SessionMeta;
+/** Read a raw parsed sidecar object into a validated {@link SessionMeta} (string fields only). */
+export declare function coerceSessionMeta(raw: unknown): SessionMeta | undefined;

package/dist/internal/persistence/session-meta.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SE4 — shared merge logic for {@link SessionMeta} + {@link SessionMetaPatch},
+ * used identically by every {@link ConversationStorageAdapter} that persists
+ * session metadata (FS sidecar + in-memory). Single source of truth for the
+ * patch semantics: an omitted field is unchanged; a `null` field CLEARS it; a
+ * string SETS it.
+ *
+ * @internal
+ */
+/** Apply a patch to session metadata, returning a fresh object. */
+export declare function applyMetaPatch(current: SessionMeta, patch: SessionMetaPatch): SessionMeta;
+/** Read a raw parsed sidecar object into a validated {@link SessionMeta} (string fields only). */
+export declare function coerceSessionMeta(raw: unknown): SessionMeta | undefined;

package/dist/internal/runtime/model-selection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SE8 — boundary normalizer for the model bare-string shorthand.
+ *
+ * `AgentOptions.model` and `SendOptions.model` accept `string | ModelSelection`
+ * (matching every peer SDK's `"provider/model"` shorthand). This is the ONE seam
+ * that maps a bare string to `{ id }`, so all downstream code keeps seeing a
+ * `ModelSelection`. `"inherit"` is an `AgentOptions`-only sentinel handled inline
+ * at the create seam — NOT here — so this helper stays `string | ModelSelection`.
+ *
+ * @internal
+ */
+import type { ModelSelection } from "../../types/agent-prims.js";
+/** Normalize a model selection: a bare string id → `{ id }`; object/undefined pass through. */
+export declare function normalizeModel(m: string | ModelSelection | undefined): ModelSelection | undefined;

package/dist/internal/structured-output-helpers.d.ts

@@ -18,7 +18,7 @@ export declare function makeOutputTool(jsonSchema: Record<string, unknown>, onCa
  * model + local + tools[output] + systemPrompt + apiKey.
  */
 export declare function buildTransientAgentOptions(params: {
-    model: ModelSelection;
+    model: string | ModelSelection;
     local: LocalOptions;
     outputTool: CustomTool;
     systemPrompt?: string;

package/dist/permission-engine.d.ts

@@ -8,6 +8,37 @@
  * the previous fail-open behavior with `{ defaultAction: "allow" }`.
  */
 export 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 OpenCode (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` — everything ⇒ `allow` EXCEPT an explicit `deny` rule. Never asks.
+ *   OpenCode `dangerously-skip-permissions` / Codex `Never`.
+ */
+export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass";
+/**
+ * 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 OpenCode + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+export 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
@@ -50,5 +81,5 @@ export declare class PermissionEngine {
      * 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>): PermissionAction;
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
 }

package/dist/{run-BgfBWX-z.d.cts → run-BMo8yRwK.d.cts}

@@ -1,3 +1,53 @@
+import * as zod from 'zod';
+
+/**
+ * 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;
+
 /**
  * #57 — content-level defense for tool results before they reach the LLM.
  *
@@ -11,6 +61,7 @@
  *
  * @internal
  */
+
 interface ToolResultGuardOptions {
     /** Wrap tool-result content in explicit data boundaries (spotlighting). */
     delimit?: boolean;
@@ -18,6 +69,91 @@ interface ToolResultGuardOptions {
     redactPii?: boolean;
 }
 
+/**
+ * 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). As of
+ * SE2 the runtime EMITS `tool_progress` and `permission_denied` end-to-end (from
+ * the agent-loop tool-dispatch seam). `rate_limit`, `task_*`, and `compact_boundary`
+ * are part of the contract; their emission is wired incrementally as the sink is
+ * threaded into the LLM-client retry / task / session-compaction subsystems (they
+ * live below the loop). A consumer switching on `type` is future-proof either way.
+ *
+ * @public
+ */
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+/** 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";
+}
+/** 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;
+
 /**
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
@@ -73,18 +209,20 @@ interface CustomTool {
     inputSchema: Record<string, unknown>;
     /**
      * Local handler invoked when the model emits `tool_use` for this tool.
-     * Returns a string (becomes the `tool_result.content` surfaced back to the
-     * model). Throws → SDK converts to `tool_result` with `isError: true` and
-     * the error `message` as 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.
+     * 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.
      */
     handler: (input: Record<string, unknown>, ctx?: {
         signal?: AbortSignal;
         context?: unknown;
-    }) => string | Promise<string>;
+    }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
 }
 
 /**
@@ -441,15 +579,6 @@ type McpHttpServerConfig = {
  */
 type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
 
-/**
- * Plain text content block emitted by the assistant or user.
- *
- * @public
- */
-interface TextBlock {
-    type: "text";
-    text: string;
-}
 /**
  * Tool invocation block emitted by the assistant.
  *
@@ -685,6 +814,49 @@ interface RunGitInfo {
         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
+ */
+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}.
  *
@@ -697,6 +869,15 @@ interface RunResult {
     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
@@ -871,7 +1052,27 @@ interface SDKUserMessage {
  * @public
  */
 interface SendOptions {
-    model?: ModelSelection;
+    /**
+     * 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
@@ -1009,5 +1210,47 @@ interface Run {
     /** 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 { ThinkingDeltaUpdate as $, AgentConversationTurn as A, SDKTaskMessage as B, CustomTool as C, DoomLoopThresholds as D, SDKThinkingMessage as E, SDKToolUseMessage as F, SDKUserMessage as G, SDKUserMessageEvent as H, InteractionUpdate as I, SendOptions as J, ShellCommand as K, ShellConversationTurn as L, ModelSelection as M, ShellOutput as N, ShellOutputDeltaUpdate as O, PartialToolCallUpdate as P, StepCompletedUpdate as Q, RunResult as R, SDKMessage as S, StepStartedUpdate as T, StreamToCompletionResult as U, SummaryCompletedUpdate as V, SummaryStartedUpdate as W, SummaryUpdate as X, TextBlock as Y, TextDeltaUpdate as Z, ThinkingCompletedUpdate as _, McpServerConfig as a, ThinkingMessage as a0, TokenDeltaUpdate as a1, TokenUsage as a2, ToolCall as a3, ToolCallCompletedUpdate as a4, ToolCallStartedUpdate as a5, ToolResult as a6, ToolResultGuardOptions as a7, ToolUseBlock as a8, TurnEndedUpdate as a9, UserMessage as aa, UserMessageAppendedUpdate as ab, Run as b, AssistantMessage as c, ConversationStep as d, ConversationTurn as e, CostBreakdown as f, CostSource as g, CostStatus as h, McpAuthConfig as i, McpHttpServerConfig as j, McpOAuthConfig as k, McpStdioServerConfig as l, ModelParameterValue as m, RunErrorDetail as n, RunGitInfo as o, RunOperation as p, RunStatus as q, RunToCompletionOptions as r, RunToCompletionResult as s, SDKAssistantMessage as t, SDKImage as u, SDKImageDimension as v, SDKObjectDelta as w, SDKRequestMessage as x, SDKStatusMessage as y, SDKSystemMessage as z };
+export { type SendOptions as $, type AgentConversationTurn as A, type RunTaskStartedEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunTaskUpdatedEvent as E, type RunToCompletionOptions as F, type GenerateOptions as G, type RunToCompletionResult as H, type ImageBlock as I, type RunToolProgressEvent as J, type SDKAssistantMessage as K, type SDKImage as L, type ModelSelection as M, type SDKImageDimension as N, type SDKObjectDelta as O, type PartialToolCallUpdate as P, type SDKRequestMessage as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type SDKStatusMessage as U, type SDKSystemMessage as V, type SDKTaskMessage as W, type SDKThinkingMessage as X, type SDKToolUseMessage as Y, type SDKUserMessage as Z, type SDKUserMessageEvent as _, type McpServerConfig as a, type ShellCommand as a0, type ShellConversationTurn as a1, type ShellOutput as a2, type ShellOutputDeltaUpdate as a3, type StepCompletedUpdate as a4, type StepStartedUpdate as a5, type StreamToCompletionResult as a6, type SummaryCompletedUpdate as a7, type SummaryStartedUpdate as a8, type SummaryUpdate as a9, type TextBlock as aa, type TextDeltaUpdate as ab, type ThinkingCompletedUpdate as ac, type ThinkingDeltaUpdate as ad, type ThinkingMessage as ae, type TokenDeltaUpdate as af, type TokenUsage as ag, type ToolCall as ah, type ToolCallCompletedUpdate as ai, type ToolCallStartedUpdate as aj, type ToolResult as ak, type ToolResultGuardOptions as al, type ToolUseBlock as am, type TurnEndedUpdate as an, type UserMessage as ao, type UserMessageAppendedUpdate as ap, emitRunEvent as aq, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InteractionUpdate as k, type McpAuthConfig as l, type McpHttpServerConfig as m, type McpOAuthConfig as n, type McpStdioServerConfig as o, type ModelParameterValue as p, type RunCompactBoundaryEvent as q, type RunErrorDetail as r, type RunEvent as s, type RunEventSink as t, type RunGitInfo as u, type RunOperation as v, type RunPermissionDeniedEvent as w, type RunRateLimitEvent as x, type RunStatus as y, type RunTaskCompletedEvent as z };