@theokit/sdk 2.20.0 → 2.21.0

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

@@ -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 };

package/dist/stream-object.d.ts

@@ -12,7 +12,8 @@ export interface StreamObjectOptions<T extends ZodType> {
     schema: T;
     prompt: string;
     systemPrompt?: string;
-    model: ModelSelection;
+    /** SE8 — accepts a bare-string id shorthand or a {@link ModelSelection}. */
+    model: string | ModelSelection;
     apiKey?: string;
     local: LocalOptions;
     maxRetries?: number;

package/dist/tool-error.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SE7 — `ToolError`: thrown FROM a tool `handler` to report a failure back to
+ * the model with structured content (text and/or an image), not just a string.
+ * Kept in its own module (not `errors.ts`) so the error taxonomy file stays
+ * under the G8 LoC budget and this tool-shaped error lives next to the tool
+ * surface it serves.
+ *
+ * @public
+ */
+import { type ErrorMetadata, TheokitAgentError } from "./errors.js";
+import type { ToolResultContentBlock } from "./types/content-blocks.js";
+/**
+ * Thrown from a tool `handler` to surface a failure to the model. The SDK turns
+ * it into a `tool_result` with `isError: true` carrying the content. A plain
+ * `Error` thrown from a handler still works (its message becomes text);
+ * `ToolError` is the opt-in for a clean message or a multimodal error (e.g. an
+ * error screenshot).
+ *
+ * @public
+ */
+export declare class ToolError extends TheokitAgentError {
+    readonly name: string;
+    /** The error content surfaced to the model: a string, or text/image blocks. */
+    readonly content: string | ToolResultContentBlock[];
+    constructor(content: string | ToolResultContentBlock[], options?: {
+        code?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}

package/dist/types/agent-prims.d.ts

@@ -53,16 +53,18 @@ export 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 | import("./content-blocks.js").ToolResultContentBlock[] | Promise<string | import("./content-blocks.js").ToolResultContentBlock[]>;
 }

package/dist/types/agent.d.ts

@@ -284,7 +284,12 @@ export interface TelemetrySettings {
  * @public
  */
 export interface AgentOptions {
-    model?: ModelSelection;
+    /**
+     * The model to run. 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;
     /** Falls back to `THEOKIT_API_KEY`. */
     apiKey?: string;
     name?: string;
@@ -576,6 +581,12 @@ export interface SDKAgent {
      */
     readonly plugins?: SDKAgentPlugins;
     send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run>;
+    /**
+     * SE9 — integrated structured output. Runs the normal tool loop (the tools run
+     * first) then coerces the final answer into the `output` Zod schema, returning a
+     * validated, inferred-typed object. Sugar over `Agent.generateObject` (ADR D33).
+     */
+    generate<T extends import("zod").ZodType>(message: string | SDKUserMessage, options: import("./run.js").GenerateOptions<T>): Promise<import("./run.js").GenerateRunResult<import("zod").z.infer<T>>>;
     /** Fire-and-forget disposal. */
     close(): void;
     /** Re-read filesystem config (context, hooks, project MCP, subagents) without disposing. */

package/dist/types/content-blocks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export type ToolResultContentBlock = TextBlock | ImageBlock;

package/dist/types/conversation-storage.d.ts

@@ -31,6 +31,31 @@ export interface StoredMessage {
     /** Optional epoch-ms timestamp. Implementations MAY default to `Date.now()` on append. */
     at?: number;
 }
+/**
+ * SE4 — light, session-level metadata stored ALONGSIDE the transcript (title +
+ * tag). Distinct from {@link StoredMessage} (which is per-turn content): this is
+ * per-conversation display metadata a host sets to build a session UI.
+ *
+ * @public
+ */
+export interface SessionMeta {
+    /** Human-facing title set via `renameSession`. Absent = untitled. */
+    readonly title?: string;
+    /** Single free-form tag set via `tagSession`. Absent = untagged. */
+    readonly tag?: string;
+}
+/**
+ * SE4 — a partial update to {@link SessionMeta}. An omitted field is left
+ * unchanged; `tag: null` explicitly CLEARS the tag (distinct from omitting it).
+ *
+ * @public
+ */
+export interface SessionMetaPatch {
+    /** Set the title; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly title?: string | null;
+    /** Set the tag; `null` explicitly CLEARS it (distinct from omitting it). */
+    readonly tag?: string | null;
+}
 /**
  * Pluggable conversation persistence contract.
  *
@@ -102,6 +127,19 @@ export interface ConversationStorageAdapter {
      * trims old turns past a soft cap; other backends typically no-op.
      */
     compact?(conversationId: string, maxTurns: number): Promise<void>;
+    /**
+     * SE4 — optional: read the session-level metadata (title/tag) for a
+     * conversation. MUST return `undefined` when none was set (NOT throw).
+     * Adapters that cannot store side metadata MAY omit this — the session
+     * manager then reports rename/tag as unsupported rather than throwing.
+     */
+    getSessionMeta?(conversationId: string): Promise<SessionMeta | undefined>;
+    /**
+     * SE4 — optional: apply a {@link SessionMetaPatch} to a conversation's
+     * session metadata (set title, set/clear tag). MUST create the metadata
+     * lazily. Adapters that cannot store side metadata MAY omit this.
+     */
+    setSessionMeta?(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     /**
      * Optional: dispose underlying handles (close DB pool, etc.).
      * MUST be safe to call multiple times.

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export type * from "./memory-adapter.js";
 export type * from "./messages.js";
 export type * from "./providers.js";
 export type * from "./run.js";
+export type * from "./session.js";
 export type * from "./task.js";
 export type * from "./theokit.js";
 export type * from "./trajectory.js";

package/dist/types/messages.d.ts

@@ -1,13 +1,6 @@
 import type { ModelSelection } from "./agent-prims.js";
-/**
- * Plain text content block emitted by the assistant or user.
- *
- * @public
- */
-export interface TextBlock {
-    type: "text";
-    text: string;
-}
+import type { TextBlock } from "./content-blocks.js";
+export type { ImageBlock, TextBlock, ToolResultContentBlock } from "./content-blocks.js";
 /**
  * Tool invocation block emitted by the assistant.
  *

package/dist/types/run-events.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+/** A tool call is being dispatched (before its result). */
+export 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. */
+export 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.
+ */
+export 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. */
+export interface RunTaskStartedEvent {
+    readonly type: "task_started";
+    readonly taskId: string;
+    readonly description?: string;
+}
+/** A background task/subagent changed state. */
+export interface RunTaskUpdatedEvent {
+    readonly type: "task_updated";
+    readonly taskId: string;
+    readonly status: string;
+}
+/** A background task/subagent finished. */
+export interface RunTaskCompletedEvent {
+    readonly type: "task_completed";
+    readonly taskId: string;
+    readonly status: "completed" | "failed" | "stopped";
+}
+/** The conversation crossed a compaction boundary (history was summarized). */
+export 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).
+ */
+export 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.
+ */
+export declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;