@theokit/sdk 2.19.0 → 2.21.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-5lj1EWgs.js';
-export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-5lj1EWgs.js';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, B as BudgetTracker, p as MemoryProvider, q as MemoryId, r as PreToolCallDecision, s as SDKProvider } from './cron-Cep07kTz.js';
-export { t as ActiveMemoryPassArgs, u as ActiveMemoryPassResult, v as AgentMemory, w as BudgetCheck, x as BudgetTotal, y as BudgetUsageEvent, z as CloudEnv, D as CloudRepo, E as ContextBudget, F as ContextManagerKind, H as ContextSnapshot, I as ContextSource, J as ContextSourceStatus, K as Cron, N as CronCreateOptions, O as CronGetOptions, Q as CronJob, R as CronJobStatus, T as CronListOptions, U as CronOperationOptions, V as CronRunOptions, W as CronRuntime, X as CronSchedulerStatus, Y as CronStartOptions, Z as GoalEvent, _ as GoalOptions, $ as GoalResult, a0 as HookName, a1 as InvalidateCacheOptions, a2 as MemoryAdapter, a3 as MemoryAdapterCapabilities, a4 as MemoryContext, a5 as MemoryFact, a6 as MemoryProviderHandle, a7 as MemoryProviderInitOptions, a8 as MemoryRevision, a9 as MemoryToolSchema, aa as MemoryTurnMessage, ab as PersonalityPreset, ac as PluginContext, ad as PostAssistantReplyContext, ae as PreToolCallContext, af as PreUserSendContext, ag as PreUserSendResult, ah as ProviderCapability, ai as ProviderRoute, aj as RecordSessionSummaryArgs, ak as ResolvedProviderRoute, al as RunUntilIterator, am as SDKAgentPlugins, an as SDKAgentSkills, ao as SDKArtifact, ap as SDKContextManager, aq as SDKPluginMetadata, ar as SDKProvidersManager, as as SettingSource, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as definePlugin } from './cron-Cep07kTz.js';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-BgfBWX-z.js';
-export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, D as DoomLoopThresholds, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, E as SDKThinkingMessage, F as SDKToolUseMessage, G as SDKUserMessage, H as SDKUserMessageEvent, J as SendOptions, K as ShellCommand, L as ShellConversationTurn, N as ShellOutput, O as ShellOutputDeltaUpdate, Q as StepCompletedUpdate, T as StepStartedUpdate, U as StreamToCompletionResult, V as SummaryCompletedUpdate, W as SummaryStartedUpdate, X as SummaryUpdate, Y as TextBlock, Z as TextDeltaUpdate, _ as ThinkingCompletedUpdate, $ as ThinkingDeltaUpdate, a0 as ThinkingMessage, a1 as TokenDeltaUpdate, a2 as TokenUsage, a3 as ToolCall, a4 as ToolCallCompletedUpdate, a5 as ToolCallStartedUpdate, a6 as ToolResult, a7 as ToolResultGuardOptions, a8 as ToolUseBlock, a9 as TurnEndedUpdate, aa as UserMessage, ab as UserMessageAppendedUpdate } from './run-BgfBWX-z.js';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-C4vZPqXf.js';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-C4vZPqXf.js';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, p as SessionMeta, q as SessionMetaPatch, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './cron-dpvtRoro.js';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, I as ContextManagerKind, J as ContextSnapshot, K as ContextSource, N as ContextSourceStatus, O as CreateSkillSpec, Q as Cron, R as CronCreateOptions, T as CronGetOptions, U as CronJob, V as CronJobStatus, W as CronListOptions, X as CronOperationOptions, Y as CronRunOptions, Z as CronRuntime, _ as CronSchedulerStatus, $ as CronStartOptions, a0 as GoalEvent, a1 as GoalOptions, a2 as GoalResult, a3 as HookName, a4 as InlineSkill, a5 as InvalidateCacheOptions, a6 as MemoryAdapter, a7 as MemoryAdapterCapabilities, a8 as MemoryContext, a9 as MemoryFact, aa as MemoryProviderHandle, ab as MemoryProviderInitOptions, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as PersonalityPreset, ag as PluginContext, ah as PostAssistantReplyContext, ai as PreToolCallContext, aj as PreUserSendContext, ak as PreUserSendResult, al as ProviderCapability, am as ProviderRoute, an as RecordSessionSummaryArgs, ao as ResolvedProviderRoute, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SettingSource, ax as SystemPromptContext, ay as SystemPromptMemoryFact, az as SystemPromptSkillRef, aA as TelemetrySettings, aB as createSkill, aC as definePlugin } from './cron-dpvtRoro.js';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage, c as MessageOrigin, T as ToolResultContentBlock } from './run-BMo8yRwK.js';
+export { A as AgentConversationTurn, d as AssistantMessage, e as ConversationStep, f as ConversationTurn, g as CostBreakdown, h as CostSource, i as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, j as GenerateRunResult, I as ImageBlock, k as InteractionUpdate, l as McpAuthConfig, m as McpHttpServerConfig, n as McpOAuthConfig, o as McpStdioServerConfig, p as ModelParameterValue, P as PartialToolCallUpdate, q as RunCompactBoundaryEvent, r as RunErrorDetail, s as RunEvent, t as RunEventSink, u as RunGitInfo, v as RunOperation, w as RunPermissionDeniedEvent, x as RunRateLimitEvent, y as RunStatus, z as RunTaskCompletedEvent, B as RunTaskStartedEvent, E as RunTaskUpdatedEvent, F as RunToCompletionOptions, H as RunToCompletionResult, J as RunToolProgressEvent, K as SDKAssistantMessage, L as SDKImage, N as SDKImageDimension, O as SDKObjectDelta, Q as SDKRequestMessage, U as SDKStatusMessage, V as SDKSystemMessage, W as SDKTaskMessage, X as SDKThinkingMessage, Y as SDKToolUseMessage, Z as SDKUserMessage, _ as SDKUserMessageEvent, $ as SendOptions, a0 as ShellCommand, a1 as ShellConversationTurn, a2 as ShellOutput, a3 as ShellOutputDeltaUpdate, a4 as StepCompletedUpdate, a5 as StepStartedUpdate, a6 as StreamToCompletionResult, a7 as SummaryCompletedUpdate, a8 as SummaryStartedUpdate, a9 as SummaryUpdate, aa as TextBlock, ab as TextDeltaUpdate, ac as ThinkingCompletedUpdate, ad as ThinkingDeltaUpdate, ae as ThinkingMessage, af as TokenDeltaUpdate, ag as TokenUsage, ah as ToolCall, ai as ToolCallCompletedUpdate, aj as ToolCallStartedUpdate, ak as ToolResult, al as ToolResultGuardOptions, am as ToolUseBlock, an as TurnEndedUpdate, ao as UserMessage, ap as UserMessageAppendedUpdate, aq as emitRunEvent } from './run-BMo8yRwK.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 
@@ -129,7 +129,8 @@ 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;
@@ -203,8 +204,16 @@ interface GenerateObjectOptions<T extends ZodType> {
     prompt: string;
     /** Optional system prompt steering the model. */
     systemPrompt?: string;
-    /** Model selection. Required (transient agents need a model). */
-    model: ModelSelection;
+    /** Model selection. Required (transient agents need a model). SE8 — accepts a
+     *  bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model: string | ModelSelection;
+    /**
+     * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a
+     * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the
+     * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large
+     * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.
+     */
+    structuringModel?: string | ModelSelection;
     /** API key. Falls back to env (THEOKIT_API_KEY etc). */
     apiKey?: string;
     /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */
@@ -282,7 +291,8 @@ declare class AgentBuilder {
     private opts;
     private readonly deps;
     constructor(deps?: AgentBuilderDeps);
-    model(m: ModelSelection): this;
+    /** SE8 — accepts a bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
+    model(m: string | ModelSelection): this;
     apiKey(k: string): this;
     name(n: string): this;
     systemPrompt(p: string | SystemPromptResolver): this;
@@ -1018,6 +1028,8 @@ declare class FileSystemConversationStorage implements ConversationStorageAdapte
         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>;
 }
 
@@ -1049,6 +1061,8 @@ declare class InMemoryConversationStorage implements ConversationStorageAdapter
     listConversationIds(opts?: {
         limit?: number;
     }): Promise<readonly string[]>;
+    getSessionMeta(conversationId: string): Promise<SessionMeta | undefined>;
+    setSessionMeta(conversationId: string, patch: SessionMetaPatch): Promise<void>;
     dispose(): Promise<void>;
 }
 
@@ -1412,6 +1426,37 @@ declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateR
  * 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 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`.
+ */
+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.
+ */
+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
@@ -1454,7 +1499,7 @@ 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;
 }
 
 /**
@@ -1468,22 +1513,75 @@ declare class PermissionEngine {
  * @public
  */
 
+/**
+ * SE1 — context passed to the {@link PermissionGate}. Intentionally minimal for
+ * SE1; `agentId`/`runId` (for audit logging) are a documented follow-up — they are
+ * available on the raw `pre_tool_call` context and can be threaded in a later slice.
+ */
+interface PermissionGateContext {
+    /** The tool being gated. */
+    readonly toolName: string;
+    /** The active permission mode for this run. */
+    readonly mode: PermissionMode;
+}
+/**
+ * SE1 — the resolution of an `"ask"` verdict by the host gate. Fail-closed: an
+ * absent gate, a throwing gate, and a `"deny"` decision all block. Arg rewrite
+ * (`updatedInput`) is intentionally NOT supported yet — the `pre_tool_call` seam
+ * is veto-only (`{ block, message }`); a future enhancement can extend it.
+ */
+type PermissionGateDecision = {
+    readonly behavior: "allow";
+} | {
+    readonly behavior: "deny";
+    readonly message?: string;
+};
+/**
+ * SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY
+ * on an `"ask"` verdict, it receives the tool name, its input args, and the run
+ * {@link PermissionGateContext}, and resolves to allow/deny. May be async (a real
+ * gate can prompt a human — the `pre_tool_call` seam awaits it).
+ */
+type PermissionGate = (toolName: string, input: Record<string, unknown>, ctx: PermissionGateContext) => PermissionGateDecision | Promise<PermissionGateDecision>;
 /** Options for {@link createPermissionPlugin}. */
 interface PermissionPluginOptions {
     /** Plugin name (default `"permission-engine"`). */
     readonly name?: string;
     /**
-     * Resolver for the `"ask"` verdict. Returns a veto (`{block,message}`) to deny
-     * or `undefined` to allow. Default: fail-closed (block with "requires approval").
+     * SE1 — the per-run {@link PermissionMode}. Threaded into `engine.evaluate`, so
+     * `bypass` auto-allows the ask verdict (gate never consulted), `plan` blocks
+     * mutations, etc. An explicit `deny` rule is immune to every mode. Default
+     * `"default"` (rules decide; unmatched ⇒ fail-closed ask).
+     */
+    readonly mode?: PermissionMode;
+    /**
+     * SE1 — the enriched gate for the `"ask"` verdict. Preferred over {@link onAsk}.
+     * Absent gate on an `ask` verdict ⇒ fail-closed block.
+     */
+    readonly canUseTool?: PermissionGate;
+    /**
+     * @deprecated since SE1 — use {@link canUseTool}, which receives `(toolName,
+     * input, ctx)` and returns a typed decision. Honored only when `canUseTool` is
+     * absent. Returns a veto (`{block,message}`) to deny or `undefined` to allow.
      */
     readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
 }
 /**
- * Build a `general` plugin that vetoes tool calls per the engine's verdict.
- * Register it on an agent's plugin manager (same as the ACP permission plugin).
+ * Build a `general` plugin that vetoes tool calls per the engine's verdict, under
+ * the configured {@link PermissionMode}, resolving `ask` via the {@link canUseTool}
+ * gate. Register it on an agent's plugin manager (same as the ACP permission plugin).
  */
 declare function createPermissionPlugin(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
 
+/** The internal JSON-Schema shape the synthetic `output` tool consumes. */
+type NormalizedJsonSchema = Record<string, unknown>;
+/**
+ * Normalize any supported schema to the internal JSON Schema. Async because the Valibot path
+ * dynamically imports its optional converter. Throws a clear, typed-message error for an unsupported
+ * schema or a missing Valibot peer (error-handling.md).
+ */
+declare function normalizeSchema(schema: unknown): Promise<NormalizedJsonSchema>;
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -1552,6 +1650,130 @@ declare class Security {
     static addPattern(re: RegExp): void;
 }
 
+/**
+ * SE4 — public types for the session-management surface (`createSessionManager`).
+ *
+ * A "session" is one conversation in a {@link ConversationStorageAdapter}. These
+ * DTOs are deliberately LIGHT — derived display metadata, not raw store rows — so
+ * a host (TheoKit) can build a session list/UI without reaching into storage
+ * internals.
+ *
+ * @public
+ */
+
+/**
+ * Light, display-oriented metadata for one session, derived from its transcript
+ * plus any host-set title/tag. All fields except `id`/`messageCount` are optional
+ * because a fresh or empty session may lack them.
+ *
+ * @public
+ */
+interface SessionSummary {
+    /** The conversation id (verbatim — includes any scope prefix like `user__`). */
+    readonly id: string;
+    /** Number of stored messages in the transcript. */
+    readonly messageCount: number;
+    /** Content of the first `user` message, when present — the opening prompt. */
+    readonly firstPrompt?: string;
+    /** Largest message timestamp (`StoredMessage.at`) seen, when any is stamped. */
+    readonly lastModified?: number;
+    /** Host-set title (via `renameSession`), when set. */
+    readonly title?: string;
+    /** Host-set tag (via `tagSession`), when set. */
+    readonly tag?: string;
+    /**
+     * A short display preview: the `title` when set, otherwise the `firstPrompt`
+     * (truncated). Undefined only when the session has neither a title nor a first
+     * user prompt.
+     */
+    readonly summary?: string;
+}
+/**
+ * Windowing for {@link SessionManager.listSessions}. `offset` counts from the
+ * first listed session; `limit` bounds the returned count. Omitting both lists
+ * all sessions (bounded only by the adapter's own `listConversationIds` limit).
+ *
+ * @public
+ */
+interface SessionListOptions {
+    readonly offset?: number;
+    readonly limit?: number;
+}
+/**
+ * Typed capability result — the graceful-degradation signal for operations an
+ * adapter cannot perform (listing, or writing session metadata). Prefer this over
+ * throwing on every call: a host inspects `supported` once and hides the
+ * corresponding UI affordance. Mirrors the SDK's existing degradation precedent
+ * (`ConversationStorageAdapter.listConversationIds` returning `undefined`,
+ * `Run.unsupportedReason`).
+ *
+ * @public
+ */
+type SessionCapabilityResult<T> = {
+    readonly supported: true;
+    readonly value: T;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+/**
+ * The session-management surface returned by `createSessionManager`. Bound to a
+ * single {@link ConversationStorageAdapter} instance (the same one a host passed
+ * to `Agent.create({ conversationStorage })`).
+ *
+ * @public
+ */
+interface SessionManager {
+    /**
+     * List sessions with light derived metadata. Returns an unsupported result
+     * when the adapter cannot enumerate conversations (`listConversationIds`
+     * absent or returning `undefined`).
+     */
+    listSessions(opts?: SessionListOptions): Promise<SessionCapabilityResult<readonly SessionSummary[]>>;
+    /**
+     * Read a session's stored transcript (passthrough to the adapter's mandatory
+     * `getMessages`). Always supported. `{ offset, limit }` windows the result.
+     */
+    getSessionMessages(id: string, opts?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<readonly StoredMessage[]>;
+    /**
+     * Set a session's title. Unsupported when the adapter cannot write session
+     * metadata (`setSessionMeta` absent).
+     */
+    renameSession(id: string, title: string): Promise<SessionCapabilityResult<void>>;
+    /**
+     * Set (`tag`) or clear (`null`) a session's tag. Unsupported when the adapter
+     * cannot write session metadata (`setSessionMeta` absent).
+     */
+    tagSession(id: string, tag: string | null): Promise<SessionCapabilityResult<void>>;
+}
+
+/**
+ * SE4 — session-management surface over {@link ConversationStorageAdapter}.
+ *
+ * `createSessionManager(storage)` binds the four session operations
+ * (list / get / rename / tag) to a storage adapter — the same instance a host
+ * passed to `Agent.create({ conversationStorage })`. It derives LIGHT metadata
+ * (firstPrompt, lastModified, messageCount) from the transcript, persists
+ * title/tag via the adapter's optional `setSessionMeta`, and degrades to a typed
+ * `{ supported: false }` result for adapters that cannot list or write metadata —
+ * never a throw-on-every-call.
+ *
+ * Composition-LEGO precedent: mirrors `createSquad` / `createAgentFactory` — a
+ * thin factory over an existing primitive, no new orchestration.
+ *
+ * @public
+ */
+
+/**
+ * Build a {@link SessionManager} bound to `storage`.
+ *
+ * @public
+ */
+declare function createSessionManager(storage: ConversationStorageAdapter): SessionManager;
+
 /**
  * M3 #62 — scoped session state.
  *
@@ -1608,6 +1830,12 @@ interface AgentStep {
     readonly agent: SDKAgent;
     readonly promptTemplate: string | ((input: unknown) => string);
     readonly retry?: RetryPolicy;
+    /**
+     * SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
+     * `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
+     * every step after the first so a peer-driven turn is attributable.
+     */
+    readonly origin?: MessageOrigin;
 }
 /** N concurrent branches, each its own mini-step-list. */
 interface ParallelStep {
@@ -2134,6 +2362,36 @@ declare class Theokit {
     };
 }
 
+/**
+ * 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
+ */
+
+/**
+ * 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
+ */
+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;
+    });
+}
+
 /**
  * Public types for ShareGPT trajectory export (ADR D139).
  *
@@ -2214,4 +2472,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, InMemoryConversationStorage, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, InMemoryConversationStorage, JobQueue, type JobQueueOptions, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, MessageOrigin, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type NormalizedJsonSchema, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, type PermissionMode, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionCapabilityResult, type SessionListOptions, type SessionManager, SessionMeta, SessionMetaPatch, type SessionScope, type SessionSummary, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, ToolError, ToolResultContentBlock, UsageAccumulator, applyMode, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSessionManager, createSquad, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };