@theokit/sdk 4.53.1 → 4.55.0

package/dist/types/batch.d.ts

@@ -37,6 +37,12 @@ export interface BatchOptions extends AgentOptions {
     /**
      * Maximum parallel agents. Default 4 (ADR D136). Must be a positive
      * integer. Capped to `prompts.length` to avoid spinning idle workers.
+     *
+     * Bounds the WHOLE per-item lifecycle, including `onResult`: a prompt's
+     * concurrency slot is not released until its `onResult` callback (if any)
+     * has finished (B-110). A caller doing anything stateful in `onResult` —
+     * writing a file, appending to a shared buffer, rate-limiting an API — can
+     * rely on at most `concurrency` such callbacks running at once.
      */
     concurrency?: number;
     /** Optional filter applied post-collection. Return `false` to discard. */
@@ -44,7 +50,7 @@ export interface BatchOptions extends AgentOptions {
     /**
      * Streaming callback fired once per completed prompt (success OR failure).
      * Caller exceptions are caught + logged to stderr without poisoning
-     * the batch (EC-5).
+     * the batch (EC-5). Bounded by `concurrency` — see its doc.
      */
     onResult?: (result: BatchResult) => void | Promise<void>;
     /** Progress callback fired after each result. */

package/dist/types/conversation.d.ts

@@ -44,11 +44,6 @@ export interface ShellOutput {
     stderr: string;
     exitCode: number;
 }
-/**
- * Single step inside an agent turn.
- *
- * @public
- */
 /**
  * Result of a tool invocation. Pairs with the preceding `toolCall` step
  * by `callId`. `isError: true` when the tool returned a failure result.
@@ -64,6 +59,24 @@ export interface ToolResult {
     result: string;
     isError: boolean;
 }
+/**
+ * A single step inside an agent turn, discriminated by `type`: an assistant message, a tool call, the
+ * tool result that pairs with it, or a thinking block.
+ *
+ * It reaches a caller by two routes that are NOT the same set. `Run.conversation()` returns the
+ * accumulated steps of a finished turn and includes `thinkingMessage`. `SendOptions.onStep` fires
+ * live while the turn runs and emits `assistantMessage`, `toolCall` and `toolResult` — but never
+ * `thinkingMessage`, which the loop builds only into the accumulated conversation. A UI that wants
+ * reasoning as it happens should read the `thinking-delta` / `thinking-completed` variants of
+ * `InteractionUpdate` through `onDelta` instead.
+ *
+ * `toolCall` and its `toolResult` arrive as an ordered pair matched by `callId`; a call whose result
+ * never came back has no `toolResult` step, so do not assume they alternate. Where a
+ * `thinkingMessage` exists it precedes the `assistantMessage` of the same turn — that is the order
+ * the provider requires of the message the block belongs to, not a presentation choice.
+ *
+ * @public
+ */
 export type ConversationStep = {
     type: "assistantMessage";
     message: AssistantMessage;

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

@@ -31,16 +31,12 @@ export interface JudgeResult {
     parseFailed: boolean;
 }
 /**
- * Public event types emitted by {@link SDKAgent.runUntil} (ADRs D115-D117).
- *
- * Discriminated union by `type` field so consumers can `switch (event.type)`
- * with full TypeScript exhaustiveness. Mirrors the
+ * Single event emitted while iterating a goal-driven loop — the public event type of
+ * {@link SDKAgent.runUntil} (ADRs D115-D117). Discriminated union by the `type` field so
+ * consumers can `switch (event.type)` with full TypeScript exhaustiveness; mirrors the
  * {@link import("../stream-object.js").StreamObjectEvent} pattern (ADR D39).
  *
- * @public
- */
-/**
- * Single event emitted while iterating a goal-driven loop. Five variants:
+ * Five variants:
  *
  * - `turn_start` — the agent is about to invoke `send()`. Emitted once
  *   per turn.

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

@@ -121,7 +121,18 @@ 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. */
+    /**
+     * 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>;

package/dist/types/plugin.d.ts

@@ -18,8 +18,45 @@
  * @public
  */
 import type { CustomTool } from "./agent-prims.js";
+import type { MemoryAdapter } from "./memory-adapter.js";
 import type { ProviderProfile } from "./provider-profile.js";
+/**
+ * The fixed set of points a `"general"` plugin may attach to through `PluginContext.on`. A closed
+ * enum rather than an open string, so a plugin cannot register for a hook the loop never fires.
+ *
+ * What separates them is what the SDK does with the handler's return value, and that is the thing to
+ * settle before writing one:
+ *
+ * - `pre_tool_call` is the only VETO point. Return `{ block: true, message }` to stop the call; the
+ *   first handler that blocks wins and the remaining handlers are not consulted.
+ * - `transform_tool_result` and `transform_llm_output` are CHAINED. Each handler receives what the
+ *   previous one returned; `undefined` keeps the current value and anything else — `null` included —
+ *   replaces it.
+ * - `pre_user_send` returns `{ recalledContext }`, which the loop concatenates across handlers and
+ *   injects ahead of the user prompt.
+ * - Everything else (`post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`,
+ *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
+ *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
+ *   `post_tool_call` and it quietly degrades to observation.
+ *
+ * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
+ * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
+ * dispatcher, so its exception escapes into the tool-dispatch path — a permission-style handler
+ * should resolve its own errors to an explicit block rather than relying on that.
+ */
 export type HookName = "pre_tool_call" | "post_tool_call" | "pre_llm_call" | "post_llm_call" | "on_session_start" | "on_session_end" | "transform_tool_result" | "transform_llm_output" | "pre_user_send" | "post_assistant_reply";
+/**
+ * What a `pre_tool_call` handler is given: the tool about to run, the arguments the model produced
+ * for it, and the identity of the run asking.
+ *
+ * `args` came from the model, not from a validated caller. A handler that gates on argument values
+ * must treat every field as untrusted and survive one that is missing or of the wrong type.
+ *
+ * `permissionMode` is the run's resolved mode — `SendOptions.permissionMode` falling back to
+ * `AgentOptions.permissionMode` — threaded here so a permission-style plugin can gate per run rather
+ * than at construction time. Absent means neither was set, and the plugin's own default applies;
+ * plugins that are not about permissions ignore it.
+ */
 export interface PreToolCallContext {
     name: string;
     args: Record<string, unknown>;
@@ -33,6 +70,19 @@ export interface PreToolCallContext {
      */
     permissionMode?: import("../permission-engine.js").PermissionMode;
 }
+/**
+ * The veto a `pre_tool_call` handler returns to stop a tool call. Returning `undefined` allows it —
+ * there is no approval value, and `block` is the literal `true`, so `{ block: false }` is not
+ * expressible and cannot be used to force a call through.
+ *
+ * The first blocking handler decides; later `pre_tool_call` handlers never run.
+ *
+ * `message` is not a log line. The loop turns the veto into a `tool_result` reading "Plugin blocked
+ * this tool call: <message>", deliberately NOT flagged as an error, so the model reads it and can
+ * choose another route instead of the run failing. Write it for the model: say what was refused and
+ * what it might do instead. It also reaches observability — as the `stderr` of a tool-completed event
+ * with exit code 126, and as the message on a `permission_denied` run event.
+ */
 export interface PreToolCallDecision {
     block: true;
     message: string;
@@ -145,6 +195,18 @@ export interface PostAssistantReplyContext {
     reply: string;
     agentId: string;
     runId: string;
+    /**
+     * `true` when the run that produced `reply` called at least one tool (#358).
+     *
+     * A reply produced by a tool call is not safely replayable: re-serving the text hands a later
+     * caller the RESULT of a `write_file` / HTTP POST / payment without the side effect having
+     * happened. A semantic cache must skip storing such a reply, and before this field existed it
+     * had nothing to key on and assumed `false`.
+     *
+     * Derived from the run's replayed event stream, so it counts tool calls the run actually made,
+     * not tools the agent merely has.
+     */
+    usedTools: boolean;
     memoryContext?: import("./memory-adapter.js").MemoryContext;
 }
 export type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;
@@ -152,6 +214,21 @@ export type CommandHandler = (args: Record<string, unknown>) => Promise<string>
 export interface CommandOptions {
     description?: string;
 }
+/**
+ * The registration surface passed to a `"general"` plugin's `register(ctx)`, and the plugin's only
+ * route into the agent. Outside production it is a sealed Proxy that throws when a plugin assigns a
+ * property of its own, so smuggling state onto the context fails loudly in development.
+ *
+ * `register` runs ONCE, when the plugin is registered — never per run. Anything the plugin wants to
+ * do during a turn has to be attached here as a hook; there is no later entry point. Each plugin gets
+ * its own context, so registrations stay attributable to the plugin that made them.
+ *
+ * Two things worth knowing before writing one. Commands registered here are consumed by CLI and bot
+ * wrappers only — the agent loop never dispatches them, so a plugin that ships nothing but commands
+ * has no effect on a programmatic run. And `on` drops a handler that is not a function, with a
+ * warning on stderr rather than an error at registration: the gentler failure, and the easier one to
+ * miss.
+ */
 export interface PluginContext {
     /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
     registerTool(tool: CustomTool): void;
@@ -166,6 +243,30 @@ interface BasePlugin {
     name: string;
     version: string;
 }
+/**
+ * Memory provider factory shape (ADR D141). Returns a `MemoryAdapter`
+ * (sync) or a Promise resolving to one (lazy HTTP probe / config load).
+ *
+ * Adapters live in `@theokit-memory-*` packages; the SDK never imports
+ * them. Factory rejection is caught by the plugin manager and surfaced
+ * as `ConfigurationError(code: "plugin_factory_failed")` (EC-F) — never
+ * an unhandled rejection.
+ *
+ * PUBLIC, deliberately (#335). This type is the shape a consumer must satisfy
+ * to write a memory plugin: it is named by the PUBLIC `Plugin` union below, in
+ * the `createProvider` position. It used to carry the internal-visibility JSDoc
+ * tag, which made `stripInternal` delete the declaration while the union went
+ * on referencing it — so the published `.d.ts` named a type it did not declare.
+ * Invisible under `skipLibCheck`, and an `error`-typed graph for any consumer
+ * running type-aware lint. A type reachable from a public signature is public
+ * whatever the tag says; the tag was the thing that was wrong.
+ *
+ * Do NOT write that tag's literal spelling anywhere in this comment. It is
+ * matched as text, so a JSDoc block that merely MENTIONS it is stripped exactly
+ * as if it had declared it — which is how the first attempt at this fix failed,
+ * with a build error naming a symbol whose own explanation had re-hidden it.
+ */
+export type MemoryProviderFactory = (cwd: string) => MemoryAdapter | Promise<MemoryAdapter>;
 export type Plugin = (BasePlugin & {
     kind: "general";
     register: (ctx: PluginContext) => void | Promise<void>;

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

@@ -44,6 +44,25 @@ export interface ProviderTransform {
     /** A fetch to use for this provider's requests (refresh-aware / fully provider-controlled). */
     fetch?(ctx: ProviderTransformContext): typeof fetch;
 }
+/**
+ * A data-only declaration of an LLM provider: its name, HTTP dialect, auth style, base URL and
+ * fallback models. There is nothing to implement — the router selects the transport from `apiMode` —
+ * so any OpenAI- or Anthropic-compatible endpoint (Groq, Together, Fireworks, a private gateway)
+ * becomes a provider without new code.
+ *
+ * A profile does nothing by itself. Wrap it with `Provider.create(profile)` and pass the resulting
+ * plugin to `Agent.create({ plugins: [...] })`; from there you route to it with the `provider/model`
+ * id prefix or through `providers.routes`.
+ *
+ * `name` is the routing prefix and `aliases` adds alternatives to it. `envVars` lists the environment
+ * variables that may supply the credential, and `authType` says what kind of credential that is.
+ *
+ * Reach for `transform` only when static data genuinely is not enough — a provider that computes
+ * headers per request or refreshes its own token. Leaving it absent keeps the profile on the pure
+ * data path. If you do supply `headers`, note that they are spread AFTER the transport's own
+ * `authorization` and `content-type`, so returning either key replaces the base header rather than
+ * adding to it.
+ */
 export interface ProviderProfile {
     name: string;
     apiMode: ApiMode;
@@ -78,4 +97,17 @@ export interface ProviderProfile {
      * Default off — only enable for routes/models known to leak (e.g. a qwen3-coder profile variant).
      */
     extractToolCallsFromContent?: boolean;
+    /**
+     * Opt-in encrypted-reasoning carry for `apiMode: "responses_api"` (usetheokit/theokit-sdk#383).
+     * When `true`, the request adds `include: ["reasoning.encrypted_content"]` and
+     * `reasoning.context: "all_turns"`, and the transport replays the ciphertext the provider returned
+     * so the model does not re-derive its chain of thought on every round of a turn.
+     *
+     * Default off, and deliberately per-profile rather than per-`apiMode`: `include` is a documented
+     * Responses-API field but `reasoning.context` is not, so a provider that validates strictly
+     * answers it with `400`. Enable it only for a backend measured to accept both — the builtin
+     * `openai-chatgpt` profile is one, because issue #383 captured OpenAI Codex sending exactly these
+     * fields to that endpoint. Ignored by every other `apiMode`.
+     */
+    encryptedReasoning?: boolean;
 }

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

@@ -16,7 +16,7 @@
  *
  * @public
  */
-export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent;
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent;
 /**
  * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
  * tools exist for this run.
@@ -36,6 +36,33 @@ export interface RunMcpServerFailedEvent {
     /** Why listing failed — a spawn error, a handshake timeout, a protocol error. */
     readonly message: string;
 }
+/**
+ * usetheokit/theokit#426 — an MCP server came up, and these are the tools it delivered.
+ *
+ * The sibling of {@link RunMcpServerFailedEvent}, emitted from the same function, on the other
+ * branch. Without it a consumer could see what was CONFIGURED and what BROKE, and could not tell a
+ * server that came up with twelve tools from one that came up with none — which is exactly the case
+ * an operator opens a server-status panel to find. `tools: []` on a healthy server is a real and
+ * previously unreportable state.
+ *
+ * An EVENT rather than a getter, because the state is scoped to the run: with
+ * `mcpLifecycle: "run"` a server may not exist by the time anyone asks, so a getter would have to
+ * answer about something already gone. This says what was true when the run started.
+ *
+ * Emitted once per successfully-listed server per run.
+ */
+export interface RunMcpServerReadyEvent {
+    readonly type: "mcp_server_ready";
+    /** The server as named in the MCP configuration — the key a consumer already lists it under. */
+    readonly serverName: string;
+    /**
+     * The tool names the server reported, as IT names them.
+     *
+     * Not the `mcp_<server>_<tool>` form the model sees: that spelling is sanitized for the provider,
+     * and a consumer matching it back to a server's own documentation would have to undo the mangling.
+     */
+    readonly tools: readonly string[];
+}
 /**
  * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
  * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`

package/dist/types/run.d.ts

@@ -46,11 +46,16 @@ export interface RunGitInfo {
     }>;
 }
 /**
- * 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.
+ * SE3 — provenance of the turn that produced a run: WHO triggered it. Metadata-only —
+ * it never changes routing or dispatch. 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; discriminate on `kind`. Mirrors
+ * the Anthropic Agent SDK's `origin` shape.
+ *
+ * Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent delegation) and
+ * `auto-continuation` (the run-to-completion / stream-to-completion driver's continuation
+ * rounds) are stamped BY the SDK. `human` and `task-notification` are positive markers a
+ * HOST stamps (e.g. re-sending an agent after a background task completed).
  *
  * Encoding note (distinct from absence): an ABSENT origin (`undefined`) means the
  * provenance was NOT stamped — the default for a plain `agent.send()`. The explicit
@@ -63,16 +68,6 @@ export interface RunGitInfo {
  *
  * @public
  */
-/**
- * SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).
- * Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent
- * delegation), `auto-continuation` (the run-to-completion / stream-to-completion
- * driver's continuation rounds) are stamped BY the SDK. `human` and
- * `task-notification` are positive markers a HOST stamps (e.g. re-sending an
- * agent after a background task completed). Absent origin ⇒ `undefined`.
- *
- * @public
- */
 export type MessageOrigin = 
 /** Explicitly a human-triggered turn — a positive marker a host stamps (NOT the
  *  same as an absent/unstamped origin, which is `undefined`). */
@@ -143,9 +138,13 @@ export interface RunResult {
     error?: RunErrorDetail;
     /**
      * Token usage observed for this run (ADR D376). Populated in every
-     * status where ≥1 LLM call completed — including partial-failure
-     * runs (EC-5). `undefined` only when zero LLM calls executed (e.g.,
-     * abort before send).
+     * status where ≥1 LLM call COMPLETED — including partial-failure
+     * runs (EC-5). `undefined` when zero LLM calls executed (e.g. an
+     * abort before send) and, for the same reason, when the only call was
+     * cut mid-stream: the counts arrive with the provider's terminating
+     * frame, which a severed connection never delivers. Such a run can
+     * therefore return partial text (#371) with no usage to bill it
+     * against — the tokens were generated and are not reported here.
      *
      * @public
      */
@@ -517,11 +516,6 @@ export interface CompletionCheckResult {
     /** `true` when the judge output could not be parsed — fail-safe `complete: false`. */
     parseFailed: boolean;
 }
-/**
- * Handle to a single prompt submission.
- *
- * @public
- */
 /**
  * theokit#140 - one element of {@link Run.events}: either a structural SDK message or a live delta.
  *
@@ -552,6 +546,24 @@ export type RunTimelineEvent = {
     kind: "delta";
     update: import("./updates.js").InteractionUpdate;
 };
+/**
+ * Handle to a single prompt submission, returned by `agent.send()` before the model has answered.
+ *
+ * It is a live handle rather than a result — `status` is `"running"` when you receive it — and how
+ * you consume the turn is the decision it asks of you. Call `wait()` when only the final answer
+ * matters. Call `events()` when you want the whole timeline: structural messages and token/tool
+ * deltas interleaved in true order, from one source. That is the one to reach for instead of fusing
+ * `stream()` with `SendOptions.onDelta` yourself, which is what produced the ordering and
+ * duplicate-text bugs it replaces. `stream()` remains the SDKMessage-only view, and
+ * `conversation()` returns the finished turn grouped per turn instead of as a stream.
+ *
+ * `cancel()` moves the run to `"cancelled"`, aborts the stream and stops in-flight tool calls.
+ *
+ * Not every method is available on every runtime — see {@link RunOperation}. Ask `supports(op)`
+ * before calling an optional one and surface `unsupportedReason(op)`, rather than calling it and
+ * catching. The optional fields (`result`, `model`, `durationMs`, `git`, `createdAt`) fill in as the
+ * run progresses, so treat their absence as "not yet", not as an error.
+ */
 export interface Run {
     readonly id: string;
     readonly agentId: string;

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

@@ -26,6 +26,20 @@ export interface SDKAgentSkillDetail {
     /** SE21 — supporting documents bundled with the skill (filename → content), when present. */
     references?: Record<string, string>;
 }
+/**
+ * The skill handle exposed as `agent.skills`, present only when project-scoped skills are enabled
+ * (`settingSources: ["project"]`) or `skills.enabled` is set. The property is optional on the agent,
+ * and `undefined` there means skills were never turned on — not that none were found.
+ *
+ * The split between its two methods is the choice it asks of a caller. `list()` returns name and
+ * description only, which is what belongs in a system prompt: it stays cheap and it keeps skill
+ * bodies out of the context window. `get(name)` resolves one skill WITH its `instructions` — the
+ * SKILL.md body for a filesystem skill, the inline body for one built with `createSkill` — and
+ * returns `undefined` when no enabled skill matches that name. Ask for a body only when you are
+ * about to use it.
+ *
+ * @public
+ */
 export interface SDKAgentSkills {
     list(): Promise<ReadonlyArray<SystemPromptSkillRef>>;
     /**

package/dist/types/session-record.d.ts

@@ -12,7 +12,6 @@
  *
  * @public
  */
-/** One transcript record (one JSONL line). `message` absent on `system` (compact_boundary) records. */
 /** A content block inside {@link TranscriptMessage}. */
 export type TranscriptBlock = {
     type: "text";
@@ -57,6 +56,24 @@ export interface TranscriptMessage {
     type?: "message";
     model?: string;
 }
+/**
+ * One transcript record — a single line of the session JSONL file, and the unit the pluggable
+ * `SessionStore` seam reads and writes.
+ *
+ * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
+ * and is `null` at the root. Thread a session by following those links; a reader that assumes file
+ * order is linear will mis-thread one that branched.
+ *
+ * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
+ * so it is optional even on records you would expect to be conversational, and `type` is what tells
+ * you which you are holding.
+ *
+ * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
+ * Every record you receive is well-formed, but the file may have contained more than you got back,
+ * so this is not the type to use for an exact-count audit of what was written.
+ *
+ * @public
+ */
 export interface SessionRecord {
     type: "user" | "assistant" | "system";
     uuid: string;

package/dist/types/task.d.ts

@@ -80,6 +80,16 @@ export interface TaskHandle {
      * AbortController).
      */
     readonly cancelRequested?: boolean;
+    /**
+     * Why the task was cancelled, when whoever cancelled it said. Free text, written alongside
+     * `cancelledAt` for a `queued` task and alongside `cancelRequested` for a `running` one.
+     *
+     * Absent when no reason was given — an empty string is not a reason, and a default like
+     * "cancelled" would put words in the operator's mouth. `theokit tasks cancel --reason` is what
+     * writes it (#351); nothing in the runtime reads it, because it exists for the human reading the
+     * registry later.
+     */
+    readonly cancelReason?: string;
 }
 /** Query filter for `Task.list`. */
 export interface TaskFilter {
@@ -87,7 +97,11 @@ export interface TaskFilter {
     readonly kind?: TaskKind | readonly TaskKind[];
     readonly submittedAfter?: number;
     readonly submittedBefore?: number;
-    /** Defaults to 100. JsonFileTaskStore hard-caps loaded entries at 256 (D364). */
+    /**
+     * Defaults to 100. `JsonFileTaskStore` returns the newest matching tasks first and reads its
+     * whole directory to find them (256 files at a time); page past this limit with
+     * `submittedBefore` (#362).
+     */
     readonly limit?: number;
 }
 /** Options for `Task.submit`. */

package/dist/types/theokit.d.ts

@@ -49,7 +49,16 @@ export interface ModelListItem {
     parameters?: ModelParameterDefinition[];
     variants?: ModelVariant[];
 }
-/** @public */
+/**
+ * Alias of {@link ModelListItem}, used where a model comes back from the Theokit platform rather
+ * than from a catalog listing.
+ *
+ * It is the SAME type, not a narrowed one — the alias exists so platform-facing signatures read in
+ * platform vocabulary alongside `SDKRepository` and `SDKUser`, and a value of either name is
+ * assignable to the other.
+ *
+ * @public
+ */
 export type SDKModel = ModelListItem;
 /**
  * GitHub repository connected to the team. Cloud-only.

package/dist/types/updates.d.ts

@@ -121,20 +121,51 @@ export interface UserMessageAppendedUpdate {
     type: "user-message-appended";
     userMessage: UserMessage;
 }
-/** @public */
+/**
+ * A conversation summary produced during a run, delivered through `SendOptions.onDelta`.
+ *
+ * Nothing in this package emits it. It is declared so an exhaustive `switch` over
+ * {@link InteractionUpdate} compiles, and so a runtime that does produce summaries has a typed
+ * channel — do not build a feature that waits on it against the local runtime.
+ *
+ * @public
+ */
 export interface SummaryUpdate {
     type: "summary";
     summary: string;
 }
-/** @public */
+/**
+ * Opens the bracket around a {@link SummaryUpdate}, for a UI that wants to show a pending state
+ * before the summary text exists. Paired with {@link SummaryCompletedUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
 export interface SummaryStartedUpdate {
     type: "summary-started";
 }
-/** @public */
+/**
+ * Closes the bracket opened by {@link SummaryStartedUpdate}. Carries no payload — the summary text
+ * itself arrives as {@link SummaryUpdate}.
+ *
+ * Like the summary variants around it, nothing in this package emits it.
+ *
+ * @public
+ */
 export interface SummaryCompletedUpdate {
     type: "summary-completed";
 }
-/** @public */
+/**
+ * Incremental output from a shell command running inside a run.
+ *
+ * `event` is an untyped bag on purpose: this package neither produces nor narrows it, so a consumer
+ * that receives one should treat it as unvalidated input and check for the fields it needs rather
+ * than casting. As with the summary variants, nothing here emits this — it exists so the
+ * {@link InteractionUpdate} union covers a runtime that does.
+ *
+ * @public
+ */
 export interface ShellOutputDeltaUpdate {
     type: "shell-output-delta";
     event: Record<string, unknown>;