@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/types/mcp.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+import type { EnvPolicy } from "./env-policy.js";
+/**
+ * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;

package/dist/types/memory-adapter.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Owner: `internal/local-agent/` (2 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
+ *
+ * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a
+ * `createProvider` factory; this file types its return value formally.
+ * Adapters implement `write` / `recall` / `delete` plus optional methods
+ * gated by `capabilities`. `MemoryId` is a branded string prefixed with
+ * the adapter id so cross-adapter use throws on `extractRawId` (EC-B).
+ *
+ * Each provider-specific package (`@theokit-memory-supermemory`, etc)
+ * exports a factory returning a `Plugin { kind: "memory" }` whose
+ * `createProvider` resolves to a `MemoryAdapter` instance.
+ *
+ * @public
+ */
+/**
+ * Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
+ * Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
+ * to construct and unwrap with cross-adapter safety (EC-B).
+ *
+ * @public
+ */
+export type MemoryId = string & {
+    readonly __brand: "MemoryId";
+};
+/**
+ * Portable identity context. `userId` is the only required field —
+ * the lowest common denominator across Supermemory / Honcho / Mem0.
+ * Adapter implementations translate the optional fields to their
+ * provider's native primitives (Honcho session, Mem0 run_id, etc).
+ *
+ * @public
+ */
+export interface MemoryContext {
+    /** End-user identity. */
+    userId: string;
+    /** Agent / persona writing the memory. */
+    agentId?: string;
+    /** Logical conversation / run boundary. */
+    sessionId?: string;
+    /** Tenant / workspace partition. */
+    tenantId?: string;
+    /** Free-form tags for filtering / categorization. */
+    tags?: string[];
+    /** Provider-passthrough metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single memory fact returned by `recall` or `get`.
+ *
+ * @public
+ */
+export interface MemoryFact {
+    id: MemoryId;
+    content: string;
+    /** Semantic relevance score (provider-defined scale) when result of `recall`. */
+    score?: number;
+    /** ISO 8601 timestamp of creation. */
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Versioned snapshot of a memory's history. Only emitted by providers
+ * with `capabilities.history === true` (Mem0 today).
+ *
+ * @public
+ */
+export interface MemoryRevision {
+    id: MemoryId;
+    content: string;
+    version: number;
+    changedAt: string;
+}
+/**
+ * Statically declared adapter feature flags. Consumers feature-detect
+ * at compile time via `if (adapter.capabilities.history)`.
+ *
+ * @public
+ */
+export interface MemoryAdapterCapabilities {
+    /** Returns prior versions of a memory via `history(id)`. */
+    history: boolean;
+    /** First-class `sessionId` scoping. */
+    sessions: boolean;
+    /** First-class `tenantId` scoping. */
+    tenancy: boolean;
+    /** Provider performs reasoning over memory (e.g., Honcho dialectic). */
+    reasoning: boolean;
+    /** Exposes LLM-callable function-calling schemas. */
+    toolSchemas: boolean;
+    /** Supports background prefetch (currently informational). */
+    prefetch: boolean;
+}
+/**
+ * One assistant-turn message in the canonical `{role, content}` shape
+ * an adapter may receive instead of a flat string when writing a turn.
+ *
+ * @public
+ */
+export interface MemoryTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/**
+ * OpenAI-format function-calling schema exposed to the LLM.
+ *
+ * @public
+ */
+export interface MemoryToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Portable third-party memory adapter contract. Implementations live
+ * in `@theokit-memory-*` packages; the SDK never imports them.
+ *
+ * @public
+ */
+export interface MemoryAdapter {
+    /** Short identifier — matches the `${adapterId}` prefix in `MemoryId`. */
+    readonly id: string;
+    readonly capabilities: MemoryAdapterCapabilities;
+    /**
+     * Synchronous availability probe — no network, no I/O. Typically "do I have the credentials I
+     * need".
+     *
+     * `false` DISABLES the adapter: the runtime skips it when building the agent's memory, warns
+     * naming this `id`, and carries on with whatever other adapters said yes. When every registered
+     * adapter declines, a `write` or `recall` fails with `no_memory_adapter` and a message saying so,
+     * rather than resolving without storing anything.
+     *
+     * It was mandatory and consulted by nothing until #360, which made it a contract that read as a
+     * guarantee and provided none — a missing key surfaced mid-conversation as `auth_failed` instead.
+     */
+    isAvailable(): boolean;
+    /** One-shot initialization. Idempotent: safe to call multiple times. */
+    initialize?(): Promise<void>;
+    /**
+     * Persist a fact or full turn to memory. Returns the stored
+     * `MemoryId`. Throws `MemoryAdapterError(code: "invalid_input")` on
+     * empty content or invalid identifiers in `ctx`.
+     */
+    write(content: string | MemoryTurnMessage[], ctx: MemoryContext): Promise<MemoryId>;
+    /**
+     * Semantic recall — top-`k` facts ordered by relevance. Returns
+     * empty array when `k === 0` or no matches.
+     */
+    recall(query: string, ctx: MemoryContext, k?: number): Promise<MemoryFact[]>;
+    /**
+     * Delete a memory by id. Throws `MemoryAdapterError(code:
+     * "invalid_input")` when the id was minted by a different adapter
+     * (EC-B). Throws `code: "not_found"` when the id does not exist.
+     */
+    delete(id: MemoryId): Promise<void>;
+    list?(ctx: MemoryContext, opts?: {
+        cursor?: string;
+        limit?: number;
+    }): AsyncIterable<MemoryFact>;
+    get?(id: MemoryId): Promise<MemoryFact | null>;
+    history?(id: MemoryId): Promise<MemoryRevision[]>;
+    /** Empty array when `capabilities.toolSchemas === false`. */
+    getToolSchemas?(): MemoryToolSchema[];
+    handleToolCall?(name: string, args: Record<string, unknown>, ctx: MemoryContext): Promise<string>;
+    /** Graceful shutdown — flush queues, close connections. */
+    shutdown?(): Promise<void>;
+}
+/**
+ * Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
+ * memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.
+ *
+ * @public
+ */
+export interface AgentMemory {
+    /**
+     * Persist a fact. Returns the first adapter's id; in multi-adapter
+     * setups all adapters receive the write (fan-out).
+     */
+    write(content: string | MemoryTurnMessage[], ctx?: Partial<MemoryContext>): Promise<MemoryId>;
+    /** Semantic recall — merged + deduped across registered adapters. */
+    recall(query: string, ctx?: Partial<MemoryContext>, k?: number): Promise<MemoryFact[]>;
+    /** Delete a memory by id — routes to the owning adapter via prefix. */
+    delete(id: MemoryId): Promise<void>;
+    /** Returns the first registered adapter or `null` when none exists. */
+    adapter(): MemoryAdapter | null;
+}

package/dist/types/memory-provider.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Owner: `internal/memory/storage/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * `MemoryProvider` — kernel-facing port for the memory subsystem
+ * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
+ * SOLID Dependency Inversion).
+ *
+ * The agent loop kernel depends on THIS CONTRACT — not on the concrete
+ * `internal/memory/*` modules. Default adapter ships with `@theokit/sdk`
+ * (no-op for back-compat); rich impl ships in `@theokit/sdk-memory`.
+ * Consumers opt-in via `Agent.create({ memoryProvider: ... })`.
+ *
+ * DIP-correct home (SE46): the port + companion contract types live in the
+ * domain `types/` layer; the application-layer module
+ * (`internal/runtime/memory-glue/memory-provider.ts`) re-exports them for
+ * back-compat while the concrete providers live under `internal/`.
+ *
+ * Layered model (mirrors Budget):
+ *   - `MemoryAdapter` (in `types/memory-adapter.ts`) — LOW-LEVEL data port:
+ *     write / recall / delete primitives.
+ *   - `MemoryProvider` (THIS FILE) — HIGH-LEVEL lifecycle port: init,
+ *     tool factories, active memory pass, embedding runtime selection.
+ *
+ * @public — surface-level interface; impls are internal-but-replaceable.
+ */
+import type { CustomTool, ModelSelection } from "./agent-prims.js";
+import type { MemoryAdapter, MemoryFact } from "./memory-adapter.js";
+/**
+ * The agent identity a `MemoryProvider` is given — the whole of it.
+ *
+ * `buildTools` used to declare `agent: SDKAgent`, a 33-member interface, and the agent loop satisfied
+ * it with `{ agentId, model } as SDKAgent`. The cast is what made it compile, and it suppressed
+ * exactly the check that mattered: an implementation reaching for any of the other 31 members —
+ * `send()`, `fork()`, `dispose()` — gets `undefined is not a function` at runtime with no
+ * compile-time signal.
+ *
+ * Two fields is what the port actually offers, so two fields is what it declares. `SDKAgent`
+ * structurally satisfies this, so a caller holding a real agent still passes it, and TypeScript's
+ * bivariant method parameters mean an existing implementation typed `agent: SDKAgent` still compiles.
+ * What changes is that the fabricated ref no longer needs a cast to exist.
+ */
+export interface MemoryProviderAgentRef {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+}
+/** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
+export interface ActiveMemoryPassResult {
+    /** Compressed memory facts to seed the LLM's context window for this turn. */
+    readonly facts: ReadonlyArray<MemoryFact>;
+    /** Optional system-prompt enrichment derived from the recalled facts. */
+    readonly systemPromptAdditions?: string;
+    /** Whether the active-memory circuit breaker tripped (degraded mode). */
+    readonly breakerTripped?: boolean;
+}
+/** Arguments for `MemoryProvider.runActivePass(...)`. */
+export interface ActiveMemoryPassArgs {
+    /** The current user message — used as the recall query. */
+    readonly userMessage: string;
+    /** Conversation history (most recent first). */
+    readonly history: ReadonlyArray<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    /** Agent identity for scope. */
+    readonly agentId: string;
+}
+/**
+ * Arguments for `MemoryProvider.recordSessionSummary(...)`
+ * (SDK 2.0 Phase 1 physical Stage 3 prep — iter 27).
+ *
+ * The "session summary" is the markdown that gets written to disk
+ * after a finished run + indexed under `corpus="sessions"`. This
+ * port method lets sdk-core's `post-run-lifecycle.ts` delegate the
+ * write to the provider instead of importing
+ * `internal/memory/storage/session-summary-writer.ts` directly.
+ *
+ * @public
+ */
+export interface RecordSessionSummaryArgs {
+    /**
+     * Workspace cwd where on-disk artefacts live. Included on the args
+     * (not on a handle) because `recordSessionSummary` is STATELESS — it
+     * runs AFTER `runAgentLoop`'s `dispose()` releases the per-run handle.
+     * The kernel passes its own `workspaceCwd`; the impl uses it to
+     * compute the markdown file path.
+     */
+    readonly cwd: string;
+    /**
+     * The memory root the kernel resolved for this agent, from `memory.directory` or the default.
+     *
+     * Supplied by the kernel, never constructed by an implementor — which is why it is required
+     * rather than optional. An implementation that recomputed it from `cwd` would write the summary
+     * into a different directory than the one the rest of the subsystem uses (#463).
+     */
+    readonly memoryRoot: MemoryRoot;
+    /** Run id used as the filename key. */
+    readonly runId: string;
+    /** Agent identity for scope (foldering). */
+    readonly agentId: string;
+    /** Verbatim user message that started the run. */
+    readonly userText: string;
+    /** Final assistant text the run produced. */
+    readonly assistantText: string;
+    /** Final run status (only "finished" is recorded today). */
+    readonly status: "finished" | "error" | "cancelled";
+    /** Wall-clock ms at write time. */
+    readonly at: number;
+}
+/** Options for `MemoryProvider.init(...)`. */
+export interface MemoryProviderInitOptions {
+    /** Workspace cwd where on-disk artefacts live (`.theokit/memory/...`). */
+    readonly cwd: string;
+    /** Embedding-provider id (`"openai" | "ollama" | ...`); when omitted the impl picks a default. */
+    readonly embeddingProviderId?: string;
+}
+/**
+ * Opaque handle returned by `init()`. Carried back into other methods so
+ * the impl can stash per-agent state (index, breaker, cache, …) without
+ * exposing it to the kernel.
+ */
+export interface MemoryProviderHandle {
+    /** Adapter interface for direct read/write — matches existing `MemoryAdapter` shape. */
+    readonly adapter: MemoryAdapter;
+    /** Implementation-defined opaque field (private state pointer / index handle). */
+    readonly [implState: symbol]: unknown;
+}
+/**
+ * The kernel-facing contract. Implementations live OUTSIDE the agent loop
+ * (in `@theokit/sdk-memory` after Phase 1; in `internal/memory/` until then).
+ *
+ * Implementations MUST be:
+ *   - **Lazy** — `init()` may be called once per agent; subsequent calls
+ *     return the same handle (impl decides via cache). Heavy work
+ *     (loading the index, opening SQLite) deferred until first use.
+ *   - **Non-throwing on the hot path** — `runActivePass()` returns an
+ *     empty `facts: []` on degradation rather than throwing. Errors
+ *     surface via the breakerTripped flag + telemetry.
+ */
+export interface MemoryProvider {
+    /** Construct or fetch the per-agent handle. Lazy + idempotent. */
+    init(opts: MemoryProviderInitOptions): Promise<MemoryProviderHandle>;
+    /** Build the LLM-facing tool catalog (memory_search, memory_get, …). */
+    buildTools(handle: MemoryProviderHandle, agent: MemoryProviderAgentRef): ReadonlyArray<CustomTool>;
+    /** Run the active-memory pre-LLM pass — recall + compress + format. */
+    runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
+    /**
+     * Optional post-run hook (SDK 2.0 Phase 1 physical Stage 1 — iter 19).
+     * Called by the agent loop AFTER a successful send so the impl can
+     * incorporate the session summary into its index (e.g., re-index the
+     * `sessions` corpus so the next recall sees it).
+     *
+     * Fire-and-forget at the call site; impl MUST be idempotent +
+     * non-throwing. Optional so existing impls (createNoopMemoryProvider,
+     * sdk-memory@0.1.0) keep working without modification.
+     *
+     * Mirrors the role of `LocalAgentMemory.syncIfReady()` in sdk-core's
+     * legacy memory path — exposing it via the port is the seam that
+     * unblocks moving LocalAgentMemory's logic out to sdk-memory.
+     */
+    sync?(handle: MemoryProviderHandle): Promise<void> | void;
+    /**
+     * Optional session-summary write hook (SDK 2.0 Phase 1 physical
+     * Stage 3 prep — iter 27, refined iter 28).
+     *
+     * Called by `post-run-lifecycle.ts` AFTER a finished run to persist
+     * the run's session-summary markdown under `corpus="sessions"`. When
+     * defined, the kernel delegates the write to the provider; when
+     * undefined, post-run-lifecycle falls back to the direct
+     * `writeSessionSummary` import (legacy path, until Stage 3 source
+     * move drops that import entirely).
+     *
+     * STATELESS — does NOT take a `MemoryProviderHandle` because post-run-
+     * lifecycle runs AFTER `runAgentLoop` disposed the per-run handle.
+     * `cwd` lives on `args` instead. Impls that need per-agent state can
+     * cache it via closure inside the provider factory.
+     *
+     * Impl MUST be non-throwing on the hot path. The kernel swallows
+     * any throw + emits a stderr warning.
+     *
+     * Optional so existing impls (createNoopMemoryProvider,
+     * createInMemoryMarkdownProvider) keep working without modification.
+     */
+    recordSessionSummary?(args: RecordSessionSummaryArgs): Promise<void> | void;
+    /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
+    dispose(handle: MemoryProviderHandle): Promise<void> | void;
+}
+/**
+ * A directory that has been RESOLVED as a memory root, distinguished from a bare `cwd`.
+ *
+ * Structural rather than a `unique symbol` brand: a `unique symbol` is identity-based and the d.ts
+ * bundler inlines the declaration into each package that re-exports it, so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ *
+ * G7 / DIP — defined HERE, in the domain types layer, rather than in
+ * `internal/memory/storage/memory-root.ts`. It was defined in the adapter and reached for from this
+ * file, which made the port depend on the adapter for a field of its own argument type; the runtime
+ * helpers (`resolveMemoryRoot`, `asMemoryRoot`) stay in the adapter and import it from here.
+ *
+ * @public
+ */
+export type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};

package/dist/types/messages-base.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
+ * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
+ * pointing it at a subsystem would name something that does not use it.
+ *
+ * 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
+ */
+export interface UserMessage {
+    text: string;
+}

package/dist/types/messages.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+import type { ModelSelection } from "./agent-prims.js";
+import type { TextBlock } from "./content-blocks.js";
+export type { ImageBlock, TextBlock, ToolResultContentBlock } from "./content-blocks.js";
+/**
+ * Tool invocation block emitted by the assistant.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export interface SDKUserMessageEvent {
+    type: "user";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "user";
+        content: TextBlock[];
+    };
+}
+/**
+ * Model text output for this run.
+ *
+ * @public
+ */
+export interface SDKAssistantMessage {
+    type: "assistant";
+    agent_id: string;
+    run_id: string;
+    message: {
+        role: "assistant";
+        content: Array<TextBlock | ToolUseBlock>;
+    };
+}
+/**
+ * Reasoning content.
+ *
+ * @public
+ */
+export interface SDKThinkingMessage {
+    type: "thinking";
+    agent_id: string;
+    run_id: string;
+    text: string;
+    thinking_duration_ms?: number;
+    /**
+     * theokit#122 — the provider's cryptographic signature for this thinking block, when it issued
+     * one. Anthropic requires a resumed conversation to replay each thinking block WITH its
+     * signature; without it the next request fails with `400 "thinking blocks cannot be modified"`,
+     * which made an extended-thinking session unresumable.
+     *
+     * Absent for providers that stream reasoning text unsigned (the OpenAI-compatible wire).
+     */
+    signature?: string;
+}
+/**
+ * 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
+ */
+export 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
+ */
+export 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
+ */
+export interface SDKTaskMessage {
+    type: "task";
+    agent_id: string;
+    run_id: string;
+    status?: string;
+    text?: string;
+}
+/**
+ * Awaiting user input or approval.
+ *
+ * @public
+ */
+export 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
+ */
+export 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
+ */
+export type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;