@theokit/sdk 4.53.1 → 4.55.0

package/dist/index.d.cts

@@ -1,13 +1,16 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-BSoXcl3F.cjs';
-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-BSoXcl3F.cjs';
-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 AgentDescription, m as Plugin$1, n as ProviderProfile, I as InlineSkill, J as JudgeResult, o as GoalOptions, p as GoalEvent, q as GoalResult, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './agent-nLqeXKIX.cjs';
-export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as AgentSubagentDescription, z as AgentToolDescription, D as BudgetCheck, E as BudgetTotal, F as BudgetUsageEvent, H as CloudEnv, K as CloudRepo, N as ContextBudget, O as ContextManagerKind, Q as ContextSnapshot, R as ContextSource, T as ContextSourceStatus, U as CreateSkillSpec, V as HookName, W as InvalidateCacheOptions, X as MemoryAdapter, Y as MemoryAdapterCapabilities, Z as MemoryContext, _ as MemoryFact, $ as MemoryProviderHandle, a0 as MemoryProviderInitOptions, a1 as MemoryRevision, a2 as MemoryToolSchema, a3 as MemoryTurnMessage, a4 as PersonalityPreset, a5 as PluginContext, a6 as PostAssistantReplyContext, a7 as PostToolCallContext, a8 as PreToolCallContext, a9 as PreUserSendContext, aa as PreUserSendResult, ab as ProviderCapability, ac as ProviderRoute, ad as ProviderTransform, ae as ProviderTransformContext, af as RecordSessionSummaryArgs, ag as ResolvedProviderRoute, ah as RunUntilIterator, ai as SDKAgentPlugins, aj as SDKAgentSkillDetail, ak as SDKAgentSkills, al as SDKArtifact, am as SDKContextManager, an as SDKPluginMetadata, ao as SDKProvidersManager, ap as SessionLifecycleContext, aq as SessionRecord, ar as SessionStore, as as SettingSource, at as Skill, au as SkillsResolver, av as SkillsResolverContext, aw as SystemPromptContext, ax as SystemPromptMemoryFact, ay as SystemPromptSkillRef, az as TelemetrySettings, aA as ToolCallSummary, aB as ToolResultTransformContext, aC as TransformContext, aD as Verdict } from './agent-nLqeXKIX.cjs';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-C8FBAC8o.cjs';
-export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunTimelineEvent, $ as RunToCompletionOptions, a0 as RunToCompletionResult, a1 as RunToolProgressEvent, a2 as RunTripwireEvent, a3 as SDKAssistantMessage, a4 as SDKImage, a5 as SDKImageDimension, a6 as SDKObjectDelta, a7 as SDKRequestMessage, a8 as SDKStatusMessage, a9 as SDKSystemMessage, aa as SDKTaskMessage, ab as SDKThinkingMessage, ac as SDKToolUseMessage, ad as SDKUserMessage, ae as SDKUserMessageEvent, af as SendOptions, ag as ShellCommand, ah as ShellConversationTurn, ai as ShellOutput, aj as ShellOutputDeltaUpdate, ak as StepCompletedUpdate, al as StepStartedUpdate, am as StreamToCompletionResult, an as SummaryCompletedUpdate, ao as SummaryStartedUpdate, ap as SummaryUpdate, aq as TextBlock, ar as TextDeltaUpdate, as as ThinkingCompletedUpdate, at as ThinkingDeltaUpdate, au as ThinkingMessage, av as TokenDeltaUpdate, aw as TokenUsage, ax as ToolCall, ay as ToolCallCompletedUpdate, az as ToolCallStartedUpdate, aA as ToolContextMessage, aB as ToolResult, aC as ToolResultGuardOptions, aD as ToolUseBlock, aE as TurnEndedUpdate, aF as UserMessage, aG as UserMessageAppendedUpdate, aH as applyMode, aI as emitRunEvent } from './run-C8FBAC8o.cjs';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-BgJH9PHi.cjs';
+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-BgJH9PHi.cjs';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-D3Xr_-6Z.cjs';
+export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CreateSkillSpec, H as HookName, x as MemoryProviderFactory, y as MemoryProviderHandle, z as MemoryProviderInitOptions, D as PluginContext, E as PostAssistantReplyContext, F as PostToolCallContext, J as PreToolCallContext, K as PreUserSendContext, N as PreUserSendResult, O as ProviderTransform, Q as ProviderTransformContext, R as RecordSessionSummaryArgs, T as SessionLifecycleContext, U as SessionRecord, V as SessionStore, W as SettingSource, X as Skill, Y as SkillsResolver, Z as SkillsResolverContext, _ as SystemPromptContext, $ as SystemPromptMemoryFact, a0 as TelemetrySettings, a1 as ToolCallSummary, a2 as ToolResultTransformContext, a3 as TransformContext } from './agent-D3Xr_-6Z.cjs';
+import { k as CostBreakdown, aw as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-BYSHf58D.cjs';
+export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunTimelineEvent, $ as RunToCompletionOptions, a0 as RunToCompletionResult, a1 as RunToolProgressEvent, a2 as RunTripwireEvent, a3 as SDKAssistantMessage, a4 as SDKImage, a5 as SDKImageDimension, a6 as SDKObjectDelta, a7 as SDKRequestMessage, a8 as SDKStatusMessage, a9 as SDKSystemMessage, aa as SDKTaskMessage, ab as SDKThinkingMessage, ac as SDKToolUseMessage, ad as SDKUserMessage, ae as SDKUserMessageEvent, af as SendOptions, ag as ShellCommand, ah as ShellConversationTurn, ai as ShellOutput, aj as ShellOutputDeltaUpdate, ak as StepCompletedUpdate, al as StepStartedUpdate, am as StreamToCompletionResult, an as SummaryCompletedUpdate, ao as SummaryStartedUpdate, ap as SummaryUpdate, aq as TextBlock, ar as TextDeltaUpdate, as as ThinkingCompletedUpdate, at as ThinkingDeltaUpdate, au as ThinkingMessage, av as TokenDeltaUpdate, aw as TokenUsage, ax as ToolCall, ay as ToolCallCompletedUpdate, az as ToolCallStartedUpdate, aA as ToolContextMessage, aB as ToolResult, aC as ToolResultGuardOptions, aD as ToolUseBlock, aE as TurnEndedUpdate, aF as UserMessage, aG as UserMessageAppendedUpdate, aH as applyMode, aI as emitRunEvent } from './run-BYSHf58D.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
-import { S as StepResult } from './cron-DFDdCdMM.cjs';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-DFDdCdMM.cjs';
+import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-DEoKhA8a.cjs';
+export { A as AgentMemory, e as ContextBudget, f as ContextManagerKind, g as ContextSnapshot, h as ContextSource, i as ContextSourceStatus, I as InvalidateCacheOptions, j as MemoryAdapter, k as MemoryAdapterCapabilities, l as MemoryContext, m as MemoryFact, n as MemoryRevision, o as MemoryToolSchema, p as MemoryTurnMessage, q as PersonalityPreset, r as ProviderCapability, s as ProviderRoute, R as ResolvedProviderRoute, t as RunUntilIterator, u as SDKAgentPlugins, v as SDKAgentSkillDetail, w as SDKAgentSkills, x as SDKArtifact, y as SDKContextManager, z as SDKPluginMetadata, B as SDKProvidersManager, D as SystemPromptSkillRef, V as Verdict } from './sdk-agent-DEoKhA8a.cjs';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-BcWmzWzT.cjs';
+import { StepResult } from './workflow.cjs';
+export { Workflow, agentStep, fn } from './workflow.cjs';
 
 /**
  * Public compaction / context-management helpers (M2-1, extended V3-3).
@@ -101,6 +104,12 @@ 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. */
@@ -108,7 +117,7 @@ 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. */
@@ -332,6 +341,25 @@ declare class GenerateObjectError extends Error {
     constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
 }
 
+/**
+ * Terminal-method callbacks injected by `Agent.builder()` so that
+ * `agent-builder.ts` does NOT need a static import of `Agent` — keeps the
+ * dependency graph acyclic (G6).
+ *
+ * Exported, and NOT carrying the internal-visibility JSDoc tag, because
+ * `AgentBuilder` is `@public` and so is its constructor: `new AgentBuilder(deps)`
+ * is callable by anyone, which makes this parameter's type part of the published
+ * contract whether or not we intended it. Hiding it did not make it private — it
+ * made the emitted `.d.ts` say `constructor(deps?: AgentBuilderDeps)` with no such
+ * type in the file (#335). Prefer `Agent.builder()`, which injects these for you;
+ * this is the seam it uses, not an argument callers are expected to construct.
+ *
+ * @public
+ */
+interface AgentBuilderDeps {
+    create: (options: AgentOptions) => Promise<SDKAgent>;
+    getOrCreate: (agentId: string, options: AgentOptions) => Promise<SDKAgent>;
+}
 /**
  * Fluent builder for {@link AgentOptions}. Chainable setters mutate internal
  * state and return `this`. Three terminals:
@@ -403,6 +431,20 @@ declare class AgentBuilder {
  */
 
 type EvictReason = "lru" | "idle" | "explicit";
+/**
+ * Knobs for {@link LiveAgentRegistry.configure}.
+ *
+ * The three numeric fields are a partial reconfigure — one left out keeps its current value.
+ * `onEvict` is NOT: it is assigned on every call, so `configure({ maxAgents: 200 })` clears a
+ * listener registered earlier. Re-pass the listener whenever you reconfigure.
+ *
+ * Two values are load-bearing zeroes. `maxAgents: 0` disables caching entirely, so every lookup
+ * misses and every agent is rebuilt; `idleTimeoutMs: 0` keeps the cache but leaves LRU as the only
+ * eviction, because the sweep is not started at all below that threshold. Negative numbers are
+ * clamped rather than rejected — up to 1000ms for `sweepIntervalMs`, up to 0 for the other two.
+ *
+ * @public
+ */
 interface AgentRegistryOptions {
     /**
      * Maximum number of agents kept alive simultaneously. LRU eviction when
@@ -429,6 +471,29 @@ interface AgentRegistryOptions {
      */
     onEvict?: (id: string, reason: EvictReason) => void;
 }
+/**
+ * An LRU-plus-idle cache of live `SDKAgent` instances, reached through `Agent.registry`.
+ *
+ * It exists for long-running servers that would otherwise build a fresh agent per conversation and
+ * never release one. Do not confuse it with the metadata registry in `agent-registry.ts`, which
+ * persists `RegisteredAgent` records to disk: that one is the address book, this one is the live
+ * cache, and they share nothing.
+ *
+ * The lifecycle rule that matters to callers: eviction — by LRU, by idle timeout, or by an explicit
+ * `evict` — calls `dispose()` on the agent. A reference you held onto before eviction is a disposed
+ * agent, not a detached one. `get` counts as a use and refreshes the entry's timestamp, so polling
+ * for an agent keeps it alive indefinitely.
+ *
+ * Idle eviction depends on a background sweep that only `configure` starts. A registry nobody
+ * configured caches with the documented defaults but evicts by LRU alone, so entries can sit past
+ * `idleTimeoutMs` indefinitely; call `configure` — even with no changes — to arm the sweep.
+ *
+ * Failures on the eviction path are swallowed and reported to the diagnostics channel — a throwing
+ * `dispose()` or a throwing `onEvict` listener must not stop the sweep. Configuration is
+ * process-wide and last-call-wins.
+ *
+ * @public
+ */
 declare class LiveAgentRegistry {
     #private;
     /**
@@ -685,24 +750,27 @@ declare class Agent {
      */
     static getOrCreate(agentId: string, options: AgentOptions): Promise<SDKAgent>;
     /**
-     * List agents (local or cloud). M107 — `cwd` is READ now, not ignored;
-     * `limit`/`cursor` still are not (see `tests/agent-list-cwd.test.ts`).
+     * List agents (local or cloud). M107 — `cwd` is READ, not ignored. B-115 (2026-08-19) —
+     * `includeArchived` and `limit`/`cursor` are READ too now; see `ListAgentsOptions`'s doc for the
+     * pagination contract and why the unlimited (no `limit`) case is unaffected.
      *
      * @public
      */
     static list(options?: ListAgentsOptions): Promise<ListResult<SDKAgentInfo>>;
     /**
-     * Get metadata for a single agent.
+     * Get metadata for a single agent. B-115 (2026-08-19) — `cwd` is READ now (see
+     * `GetAgentOptions`'s doc); it used to be accepted and silently ignored.
      *
      * @public
      */
-    static get(agentId: string, _options?: GetAgentOptions): Promise<SDKAgentInfo>;
+    static get(agentId: string, options?: GetAgentOptions): Promise<SDKAgentInfo>;
     /**
-     * List runs for an agent.
+     * List runs for an agent. B-115 (2026-08-19) — `cwd` and `limit`/`cursor` are READ now (see
+     * `ListRunsOptions`'s doc); they used to be accepted and silently ignored.
      *
      * @public
      */
-    static listRuns(agentId: string, _options?: ListRunsOptions): Promise<ListResult<Run>>;
+    static listRuns(agentId: string, options?: ListRunsOptions): Promise<ListResult<Run>>;
     /**
      * Get a single run.
      *
@@ -843,11 +911,35 @@ declare class AgentFactory {
  */
 /** What the operator chose for everything not decided per tool. @public */
 type ApprovalMode = "ask" | "never-ask" | "refuse-all";
-/** @public */
+/**
+ * The three answers a policy can give: proceed, put the call in front of a human, or stop it.
+ *
+ * `ask` is not a softer `deny`. A surface with no way to reach a human must treat it as a refusal,
+ * because treating it as permission is how an unattended run approves everything it was meant to
+ * pause on.
+ *
+ * @public
+ */
 type ApprovalOutcome = "allow" | "ask" | "deny";
-/** @public */
+/**
+ * Which rule produced the outcome.
+ *
+ * The `explicitly-` pair means a per-tool list decided it; the `mode-` triple means no list named
+ * the tool and the operator's mode decided instead. Worth rendering alongside the outcome: "you
+ * denied this tool" and "your mode refuses everything" send the operator to different settings.
+ *
+ * @public
+ */
 type ApprovalReason = "explicitly-allowed" | "explicitly-denied" | "mode-ask" | "mode-never-ask" | "mode-refuse-all";
-/** @public */
+/**
+ * One tool call to decide on, plus the operator's configuration.
+ *
+ * `tool` is matched against `denied` and `allowed` by exact string equality — there is no pattern
+ * or prefix rule. Both lists default to empty, so with neither supplied every call is decided by
+ * `mode` alone.
+ *
+ * @public
+ */
 interface ApprovalInput {
     readonly tool: string;
     readonly mode: ApprovalMode;
@@ -856,7 +948,11 @@ interface ApprovalInput {
     /** Tools the operator refused. Outranks `allowed` and every mode. */
     readonly denied?: readonly string[];
 }
-/** @public */
+/**
+ * The answer, the rule that produced it, and the tool it was about.
+ *
+ * @public
+ */
 interface ApprovalDecision {
     readonly outcome: ApprovalOutcome;
     readonly reason: ApprovalReason;
@@ -864,6 +960,17 @@ interface ApprovalDecision {
     readonly tool: string;
 }
 /**
+ * Decide one tool call against the operator's lists and mode.
+ *
+ * The precedence is fixed and each step short-circuits: `denied` is consulted first, then
+ * `allowed`, then `mode`. A tool named in BOTH lists is therefore denied — a contradictory config
+ * is read restrictively, because the usual cause is an allow-entry that outlived the denial meant
+ * to replace it.
+ *
+ * This answers only who said yes. What the call REACHES is a separate question with a separate
+ * policy — `evaluateBlastRadius` — and neither consults the other, so a product that wants both
+ * gates calls both and combines the outcomes itself.
+ *
  * @returns the outcome, why it was reached, and the tool it was about.
  * @public
  */
@@ -912,7 +1019,18 @@ interface DeclaredAction {
      */
     readonly reversible: boolean;
 }
-/** @public */
+/**
+ * The action to decide on, plus what the operator granted.
+ *
+ * `granted` is matched against `action.scope` by exact string equality: there is no prefix or
+ * wildcard rule, so granting `cluster:prod` does not grant `cluster:prod:kube-system`. A product
+ * that wants hierarchical scopes expands them itself before calling.
+ *
+ * `irreversibleAllowed` defaults to empty, so an irreversible action inside a granted scope asks
+ * for approval unless its scope was pre-approved for destruction as well.
+ *
+ * @public
+ */
 interface BlastRadiusInput {
     readonly action: DeclaredAction;
     /** Scopes the operator granted reach to. Empty grants nothing — never everything. */
@@ -920,11 +1038,27 @@ interface BlastRadiusInput {
     /** Scopes where the operator pre-approved irreversible actions, so an unattended run can work. */
     readonly irreversibleAllowed?: readonly string[];
 }
-/** @public */
+/**
+ * What the policy decided.
+ *
+ * `require-approval` means a human has to say yes before the action runs; a caller with no way to
+ * ask must treat it as a refusal. `refuse` is not appealable through this policy at all — the
+ * operator has to grant the scope first, which is deliberately a configuration change rather than
+ * a prompt.
+ *
+ * @public
+ */
 type BlastRadiusOutcome = "allow" | "require-approval" | "refuse";
 /** Why the decision came out that way. Rendered to the operator and read by an audit. @public */
 type BlastRadiusReason = "within-granted-scope" | "irreversible" | "scope-not-granted" | "scope-undeclared";
-/** @public */
+/**
+ * The outcome, the rule that produced it, and the scope it was decided about.
+ *
+ * `scope` echoes what the action declared, so it is the empty string when the reason is
+ * `scope-undeclared` — the decision names what it saw rather than substituting a placeholder.
+ *
+ * @public
+ */
 interface BlastRadiusDecision {
     readonly outcome: BlastRadiusOutcome;
     readonly reason: BlastRadiusReason;
@@ -932,6 +1066,19 @@ interface BlastRadiusDecision {
     readonly scope: string;
 }
 /**
+ * Decide one declared action against the scopes the operator granted.
+ *
+ * Four checks, in this order, each short-circuiting: an empty `scope` is refused as undeclared
+ * before any comparison happens; a scope absent from `granted` is refused; an irreversible action
+ * whose scope is not in `irreversibleAllowed` escalates to approval; anything left is allowed.
+ *
+ * Refusal outranking escalation is a decision, not an accident. Asking a human to approve a scope
+ * the operator never granted trains them to approve by reflex, which is how an approval prompt
+ * stops being a control.
+ *
+ * This decides reach only. Whether the operator permitted the tool at all is `decideApproval`, and
+ * the two are independent.
+ *
  * @returns the outcome with the reason and the scope it was decided on.
  * @public
  */
@@ -1020,7 +1167,52 @@ declare function chargeAndCheckThresholds(name: string, actualUsd: number): Prom
  * @internal
  */
 type ApiMode = "anthropic_messages" | "openai_chat_completions" | "openai_responses";
+/**
+ * Guess which usage shape a provider reports, from its name alone.
+ *
+ * Matching is case-insensitive and exact — `"anthropic"`, `"claude"` and `"bedrock_anthropic"`
+ * give `"anthropic_messages"`; `"openai-codex"` and `"codex"` give `"openai_responses"`. Every
+ * other name, including ones this SDK has never seen, falls through to
+ * `"openai_chat_completions"`. There is no unknown result, so a wrong guess is silent: it is
+ * read as a Chat Completions payload, whose fields are absent, and the tokens come back as 0.
+ *
+ * The default is right for the OpenAI-compatible majority (openai, openrouter, deepseek, and the
+ * compat endpoints of google, ollama and lmstudio). When it is not, pass `apiMode` to
+ * `normalizeUsage` explicitly instead of relying on the name.
+ */
 declare function inferApiMode(provider: string): ApiMode;
+/**
+ * Convert a provider's raw `usage` object into the SDK's canonical `TokenUsage`.
+ *
+ * Never throws and never reports failure. `null`, `undefined` and any non-object argument return
+ * all-zero usage, which is indistinguishable from a real response that used no tokens — so this
+ * is not the place to detect a malformed payload.
+ *
+ * `opts.apiMode` selects the reader; when omitted it is derived from `opts.provider` via
+ * `inferApiMode`, whose fallback is Chat Completions. Pass it explicitly for any provider whose
+ * name does not identify its wire shape.
+ *
+ * The shapes differ in one way that matters: Anthropic reports cache tokens in buckets separate
+ * from `input_tokens`, while both OpenAI shapes report a prompt total that already includes
+ * them. For the OpenAI readers the cache buckets are subtracted, so `inputTokens` is always the
+ * uncached portion and `inputTokens + cacheReadTokens + cacheWriteTokens` reconstructs the
+ * provider's prompt total. The subtraction is floored at 0, so a payload whose cache counts
+ * exceed its prompt total yields 0 rather than a negative.
+ *
+ * Every field is coerced: numbers are truncated toward zero, numeric strings are parsed, negative
+ * and non-finite values become 0, and anything else becomes 0.
+ *
+ * `totalTokens` is computed here as input + output + both cache buckets; a `total_tokens` the
+ * provider sent is ignored. Reasoning tokens are reported separately but are NOT added again —
+ * providers already count them inside output. `cacheReadTokens`, `cacheWriteTokens` and
+ * `reasoningTokens` are omitted from the result when they are 0, so absent means zero, not
+ * unknown.
+ *
+ * Chat Completions also accepts Anthropic-style top-level `cache_read_input_tokens` /
+ * `cache_creation_input_tokens`, which OpenAI-compatible proxies emit when they route Claude.
+ * The nested `prompt_tokens_details` values win; the top-level fields are consulted only when
+ * those are 0 or missing.
+ */
 declare function normalizeUsage(rawUsage: unknown, opts: {
     provider: string;
     apiMode?: ApiMode;
@@ -1080,6 +1272,21 @@ interface StepUsage {
     cacheWriteTokens?: number;
     reasoningTokens?: number;
 }
+/**
+ * Sums the per-step token counts of a multi-step run into one `TokenUsage`.
+ *
+ * Call `add` once per LLM finish, in any order, then `toTokenUsage` to read the total. The instance
+ * is a running sum, not a snapshot: `toTokenUsage` may be called repeatedly and reflects everything
+ * added so far, and there is no reset — start a new accumulator per run.
+ *
+ * Two shaping rules to expect in the output. The optional counters (cache read, cache write,
+ * reasoning) are omitted entirely when they sum to zero rather than reported as `0`. And the
+ * per-step `requests` array appears only when at least TWO steps were added, so a single-step run
+ * carries totals alone.
+ *
+ * `totalTokens` is input plus output only — cache and reasoning counts are reported separately and
+ * are not folded into it.
+ */
 declare class UsageAccumulator {
     private input;
     private output;
@@ -1217,7 +1424,14 @@ declare class UnicodeNormalizer {
  *
  * @public
  */
-/** @public */
+/**
+ * One provider's credential lookup, as the product resolved it.
+ *
+ * `value` is the secret itself. It is hashed and dropped inside `describeCredential` — it never
+ * reaches the report, and nothing here stores it.
+ *
+ * @public
+ */
 interface CredentialInput {
     /** The product's name for the provider. This module never knows one of its own. */
     readonly provider: string;
@@ -1226,7 +1440,15 @@ interface CredentialInput {
     /** Where it came from, in the product's vocabulary — `env`, `file`, `keychain`, `oauth`. */
     readonly source: string;
 }
-/** @public */
+/**
+ * A presence-only view of one credential, safe to print, log, or attach to a support bundle.
+ *
+ * `fingerprint` is the first eight hex characters of the SHA-256 of the trimmed secret: enough for
+ * two people to agree they are holding the same key, and not a substring of it. It is absent
+ * whenever `present` is false.
+ *
+ * @public
+ */
 interface CredentialReport {
     readonly provider: string;
     readonly present: boolean;
@@ -1235,6 +1457,13 @@ interface CredentialReport {
     readonly fingerprint?: string;
 }
 /**
+ * Turn a resolved credential into something you can show a user.
+ *
+ * The value is trimmed before the emptiness test, so `undefined`, `""` and whitespace all report
+ * `present: false` with no fingerprint. That matters because an environment variable that expanded
+ * to nothing arrives as an empty string, and calling that "present" sends whoever is debugging to
+ * hunt for a routing bug instead of a missing secret.
+ *
  * @returns a report safe to log, render and attach to a support bundle.
  * @public
  */
@@ -1362,12 +1591,6 @@ interface SanitizeOptions {
     maxDepth?: number;
 }
 
-/**
- * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
- * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
- *
- * @public
- */
 /**
  * SE16 — the handler's return type. With no `outputSchema` the tool returns a
  * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
@@ -1375,6 +1598,20 @@ interface SanitizeOptions {
  * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
  */
 type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : z.infer<O>;
+/**
+ * Spec accepted by {@link Tool.create}. `inputSchema` is a Zod schema; the `handler` argument type
+ * is inferred via `z.infer<T>` — no `as` casts.
+ *
+ * The two optional output fields do different jobs and compose. `outputSchema` changes what the
+ * handler must RETURN (a structured value instead of a string) and validates it; `toModelOutput`
+ * changes only what the MODEL sees in the tool result, while observability still receives the full
+ * handler output. Set neither and the handler returns a plain string that goes to both.
+ *
+ * `zod` is referenced as a type only, so a consumer that never calls `Tool.create` does not need it
+ * installed.
+ *
+ * @public
+ */
 interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
     /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
     name: string;
@@ -1470,7 +1707,16 @@ interface EnvOptOut {
     /** What would make this opt-out obsolete. An opt-out with no exit is a permanent excuse. */
     readonly exitCriterion: string;
 }
-/** @public */
+/**
+ * The three lists the audit compares: every key the product declares, the subset an environment
+ * variable can set, and the documented exemptions.
+ *
+ * All three are matched by exact string equality, and `reachable` and `optOuts` are read as subsets
+ * of `keys` — an entry in either that is not in `keys` is what makes an opt-out stale, and an entry
+ * in `reachable` that is not in `keys` is simply ignored.
+ *
+ * @public
+ */
 interface EnvReachabilityInput {
     /** Every configuration key the product declares. */
     readonly keys: readonly string[];
@@ -1479,7 +1725,15 @@ interface EnvReachabilityInput {
     /** Documented exemptions for keys that deliberately have no environment path. */
     readonly optOuts: readonly EnvOptOut[];
 }
-/** @public */
+/**
+ * The two failures, reported separately because they have opposite fixes.
+ *
+ * A key in `unreachable` needs either an environment path or a documented opt-out. A key in
+ * `staleOptOuts` needs its opt-out DELETED — it exempts nothing, either because the key gained an
+ * environment path or because the key no longer exists. Both lists empty is the passing state.
+ *
+ * @public
+ */
 interface EnvReachabilityAudit {
     /** Keys with neither an environment path nor a documented opt-out. */
     readonly unreachable: readonly string[];
@@ -1487,6 +1741,15 @@ interface EnvReachabilityAudit {
     readonly staleOptOuts: readonly string[];
 }
 /**
+ * Answer both halves of the reachability question in one call.
+ *
+ * A key counts as covered when it is in `reachable` OR carries an opt-out, so an opt-out silences
+ * the gap it was written for and nothing else. Assert on both returned lists: a suite that checks
+ * only `unreachable` still passes while the opt-outs rot, which is the half everyone forgets.
+ *
+ * This performs no I/O and reads no environment. The caller supplies its own key vocabulary,
+ * because a framework cannot enumerate a consumer's configuration keys.
+ *
  * @returns both axes, in the order the caller declared them — a stable order so a failure message
  *   does not change between runs for reasons unrelated to the code.
  * @public
@@ -1500,6 +1763,22 @@ declare function auditEnvReachability(input: EnvReachabilityInput): EnvReachabil
  * Each handler is try-caught (EC-2) so one failing handler cannot break others.
  */
 type EventHandler<T> = (payload: T) => void;
+/**
+ * A typed publish/subscribe bus, parameterised by a map of event name to payload type.
+ *
+ * `publish` is SYNCHRONOUS: handlers run in subscription order before it returns, so a slow handler
+ * blocks the publisher. Each handler is invoked inside its own try/catch, so one that throws cannot
+ * stop the others — the error is written to the diagnostics channel and counted on
+ * `handlerErrorCount`. Assert on that counter in tests; a subscriber failing on every event is
+ * otherwise invisible.
+ *
+ * `subscribe` returns the unsubscribe function, which is the only way to detach a handler — there
+ * is no `off` taking the handler back. Handlers are held in a `Set` per event, so subscribing the
+ * same function reference twice registers it once.
+ *
+ * Payload objects are passed by reference to every handler; nothing here copies them, so a handler
+ * that mutates a payload mutates it for the handlers after it.
+ */
 declare class EventBus<Events extends Record<string, unknown>> {
     #private;
     private handlers;
@@ -1727,6 +2006,40 @@ type DiagnosticsSink = (message: string) => void;
  */
 declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
 
+/**
+ * Run `fn` after every earlier `withCwdMutex` call for the same `key` has settled, and return
+ * what `fn` returns.
+ *
+ * Calls with the same key run strictly in the order they were made — FIFO, never concurrent.
+ * Calls with different keys never wait on each other. The key is an opaque string: two callers
+ * serialize against each other exactly when they pass equal keys, so a shared key IS the
+ * contract, and a mismatched one silently buys no protection at all.
+ *
+ * A rejection does not poison the queue. The next waiter runs whether the previous `fn` fulfilled
+ * or rejected, and the rejection is delivered only to the caller whose `fn` threw. This function
+ * neither retries nor swallows: the returned promise rejects with whatever `fn` rejected with.
+ *
+ * There is no timeout and no cancellation. An `fn` that never settles blocks that key for the
+ * lifetime of the process.
+ *
+ * **Scope — this is an in-process lock only.** State is a module-scoped Map, so it serializes
+ * callers that share one module instance and nothing else. Two processes, two worker threads, or
+ * two copies of the SDK resolved into the same tree do not see each other's queue. When the
+ * resource is a file that other processes can also write, use `withFileLock` from
+ * `./file-lock.ts` instead — it takes an OS-level lock and layers this mutex underneath, so it
+ * gives both guarantees. Reach for `withCwdMutex` directly when the shared state is in memory, or
+ * when the file is one only this process touches.
+ *
+ * Extracted packages (`@theokit/sdk-budget`, `@theokit/sdk-memory`) import this from
+ * `@theokit/sdk` rather than reimplementing it, precisely so the Map is the same one: a per-package
+ * copy would give each package its own queue and let their writes race.
+ *
+ * The Map is module-scoped, so nothing survives a process restart or a fresh module instance, and
+ * its entries are never removed — pass keys from a bounded set rather than from arbitrary input.
+ * Signature and semantics will not change before sdk-core v3.0.
+ *
+ * @public
+ */
 declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
 
 /**
@@ -1758,6 +2071,20 @@ declare class NoopMemoryProvider {
     static create(): MemoryProvider;
 }
 
+/**
+ * The subset of the OpenTelemetry `Span` API this SDK calls.
+ *
+ * Structural, not nominal: a real `@opentelemetry/api` span satisfies it, and so does a test double
+ * or a no-op. That is why it is exported — `@theokit/sdk-memory` previously kept a hand-written
+ * mirror of this shape, and the two had already drifted (the mirror rejected `undefined` attribute
+ * values this one accepts, and declared `end()` without its `endTime` parameter). Import this
+ * instead of re-declaring it.
+ *
+ * Erased at build time, so importing it adds nothing to a bundle and does not require
+ * `@opentelemetry/api` to be installed.
+ *
+ * @public
+ */
 interface OTelSpan {
     setAttribute(key: string, value: string | number | boolean): void;
     setAttributes(attrs: Record<string, string | number | boolean | undefined>): void;
@@ -1825,6 +2152,24 @@ interface JobQueueOptions {
      */
     maxConcurrency?: number;
 }
+/**
+ * An in-process queue of background jobs with status tracking, cancellation, and an optional
+ * concurrency bound.
+ *
+ * `enqueue` returns a job id immediately and never throws for the job's own failure: a synchronous
+ * throw inside the function becomes a rejection, and a rejection becomes `status: "failed"` with
+ * the message on `job.error`. Poll `getJob(id)` or `list()` for outcomes — there is no completion
+ * event and no promise to await.
+ *
+ * Cancellation is COOPERATIVE. `cancel` aborts the `AbortSignal` handed to the job function and
+ * flips the status, but a function that ignores the signal keeps running to completion; its result
+ * is then discarded, because a cancelled job never leaves the cancelled state. The concurrency slot
+ * of a running job is freed at cancel time rather than when it eventually settles, so a job that
+ * never settles cannot deadlock a bounded queue.
+ *
+ * State lives entirely in memory and grows without bound — nothing evicts finished jobs. This is a
+ * queue for one process, not a durable one.
+ */
 declare class JobQueue {
     #private;
     private jobs;
@@ -1870,13 +2215,30 @@ declare class JobQueue {
 declare class LayerOrderError extends TheokitAgentError {
     readonly name = "LayerOrderError";
 }
-/** @public */
+/**
+ * One named layer in a precedence chain.
+ *
+ * `precedence` is optional and the two usages do not mix well: omit it everywhere to say "this
+ * array is already in order", or supply it everywhere you want `verifyLayerOrdering` to check.
+ * Entries without it are SKIPPED by that check rather than treated as zero, so a chain where only
+ * some entries declare a number is verified only between those.
+ *
+ * @public
+ */
 interface DeclaredLayer {
     readonly layer: string;
     /** Higher wins. Optional — omit it to mean "this array is already the order". */
     readonly precedence?: number;
 }
-/** @public */
+/**
+ * A declared layer together with the values it supplies.
+ *
+ * `foldLayers` consumes these in array order, so a later entry wins for the keys it mentions. A key
+ * a layer does not mention — or mentions with `undefined` — leaves the earlier value standing;
+ * there is no way for a layer to erase a key another layer set.
+ *
+ * @public
+ */
 interface LayerValues extends DeclaredLayer {
     readonly values: Readonly<Record<string, unknown>>;
 }
@@ -1950,10 +2312,13 @@ interface MemoryIndexHandle {
     close(): Promise<void> | void;
 }
 /**
- * Public `Memory` namespace.
+ * Inputs for {@link Memory.runDreamingSweep}.
  *
- * Exposes operations users can run outside of `agent.send()` — most notably
- * the dreaming sweep (consolidation of facts via dedup + clustering).
+ * `embedding` is required and has no default: the sweep scores cosine similarity between facts, so
+ * without real embeddings there is nothing to dedup or cluster on. Both thresholds are cosine
+ * similarity in [0, 1] and default to `0.95` for dedup and `0.75` for clustering — dedup is the
+ * stricter of the two because merging two facts that were merely related is a data loss, while
+ * failing to cluster them only costs a note.
  *
  * @public
  */
@@ -1975,6 +2340,18 @@ interface DreamingSweepOptions {
     /** Cosine-similarity threshold for the clustering phase. Default `0.75`. */
     clusterThreshold?: number;
 }
+/**
+ * What one dreaming sweep did.
+ *
+ * `status` is `"skipped"` when the workspace held no facts to work on and `"error"` when the sweep
+ * failed; both come back with every counter at zero, so check `status` before reading a zero as
+ * "there was nothing to consolidate". A failure is reported through this field rather than as a
+ * rejection, which means a caller that only awaits the promise never learns the sweep did nothing.
+ * `factsBefore` and `factsAfter` bracket the run, which is the pair to compare when you want to
+ * know whether the sweep was worth running rather than how many operations it performed.
+ *
+ * @public
+ */
 interface DreamingSweepResult {
     status: "ok" | "skipped" | "error";
     factsBefore: number;
@@ -2006,6 +2383,19 @@ interface OpenMemoryIndexOptions {
     /** Default `"sqlite-vec"`. Set to `"lance"` to opt into LanceDB (peer dep). */
     backend?: "sqlite-vec" | "lance";
 }
+/**
+ * Memory operations that run OUTSIDE an agent turn.
+ *
+ * Everything here is reachable without `Agent.create({ memory: ... })`, which is the point: opening
+ * an index directly is how a CLI or a maintenance job inspects or rebuilds what the agent will
+ * later read, and the dreaming sweep is maintenance that no `send()` triggers.
+ *
+ * Both operations route through the `@theokit/sdk-memory` peer package when it is installed and
+ * fall back to the in-tree implementation when it is not. The fallback is not a degraded mode —
+ * behaviour and thrown errors match — so consumers do not branch on which path ran.
+ *
+ * @public
+ */
 declare const Memory: {
     /**
      * Open a memory index. Dispatches to SQLite-vec (default, zero deps) or
@@ -2214,7 +2604,16 @@ declare class PermissionPlugin {
  * @public
  */
 declare const SOVEREIGN_ENV_KEYS: readonly ["THEOKIT_HOME", "THEOKIT_AUTH_HOME", "THEOKIT_DIR_NAME", "THEOKIT_TRUSTED_PROVIDERS", "THEOKIT_REDACT_SECRETS", "THEOKIT_OAUTH_TX_SALT"];
-/** @public */
+/**
+ * The union of {@link SOVEREIGN_ENV_KEYS} entries — the variables a project-scoped `.env` may never
+ * set.
+ *
+ * Derived from the array rather than written out, so adding a key in one place cannot leave the
+ * type behind. Use it where a caller must name one of the protected variables and a plain `string`
+ * would let a typo through silently.
+ *
+ * @public
+ */
 type SovereignEnvKey = (typeof SOVEREIGN_ENV_KEYS)[number];
 /** The mutable shape of `process.env`, narrowed so a caller can pass a plain object in tests. */
 type MutableEnv = Record<string, string | undefined>;
@@ -2264,7 +2663,16 @@ declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefine
 declare class RetentionPolicyError extends TheokitAgentError {
     readonly name = "RetentionPolicyError";
 }
-/** @public */
+/**
+ * One artifact the caller is considering deleting, described well enough to decide about.
+ *
+ * `id` is only ever compared for equality, so any stable identity works — a path, a session id, an
+ * inode. `live` is the tri-state that carries the whole safety property: `"unknown"` means the
+ * caller could not establish liveness, and it is honoured as a third answer rather than folded into
+ * `false`.
+ *
+ * @public
+ */
 interface ReapableArtifact {
     readonly id: string;
     /** Epoch milliseconds. Compared against an injected `nowMs`, never against a read clock. */
@@ -2276,7 +2684,16 @@ interface ReapableArtifact {
      */
     readonly live: boolean | "unknown";
 }
-/** @public */
+/**
+ * How long artifacts are kept and how many always survive.
+ *
+ * The two interact as a window plus a FLOOR, not as two independent allowances: `keepLast` rescues
+ * artifacts only when the window and liveness together spared fewer than that many, and rescues
+ * exactly enough to reach the count. Both are refused by `planReaping` rather than clamped when
+ * they are not expressible — see its `@throws`.
+ *
+ * @public
+ */
 interface RetentionPolicy {
     /** Artifacts strictly older than this are candidates. The boundary itself is kept. */
     readonly maxAgeMs: number;
@@ -2293,11 +2710,27 @@ interface RetentionPolicy {
 }
 /** Why an artifact survived. @public */
 type KeepReason = "live" | "within-retention" | "keep-last";
-/** @public */
+/**
+ * An artifact that survived, carrying the reason it did.
+ *
+ * The reason is the one that spared it FIRST, in the order liveness, then the retention window,
+ * then the floor — so a live artifact inside the window reports `"live"`, and `"keep-last"` only
+ * appears on artifacts that had no reason of their own.
+ *
+ * @public
+ */
 interface KeptArtifact extends ReapableArtifact {
     readonly reason: KeepReason;
 }
-/** @public */
+/**
+ * The decision, as three disjoint buckets whose union is exactly the input.
+ *
+ * Nothing is deleted by producing one of these — the plan IS the dry run, and executing it is a
+ * separate act on a value you can read first. Delete only what is in `reap`; `undetermined` is not
+ * a smaller `reap`, it is the set nobody could decide about.
+ *
+ * @public
+ */
 interface ReapPlan {
     /** Safe to delete. Everything here was decided, not defaulted. */
     readonly reap: readonly ReapableArtifact[];
@@ -2305,13 +2738,39 @@ interface ReapPlan {
     /** Liveness could not be established. Never deleted, never counted as kept. */
     readonly undetermined: readonly ReapableArtifact[];
 }
-/** @public */
+/**
+ * Everything `planReaping` needs: the candidates, the policy, and the current time.
+ *
+ * `nowMs` is a parameter rather than a clock read so the same input always produces the same plan —
+ * which is what lets a caller compute a plan, show it, and execute it later against the same
+ * decision instead of a freshly re-derived one.
+ *
+ * @public
+ */
 interface ReapPlanInput {
     readonly artifacts: readonly ReapableArtifact[];
     readonly retention: RetentionPolicy;
     /** Injected so the plan is reproducible and testable; this module never reads a clock. */
     readonly nowMs: number;
 }
+/**
+ * Sort artifacts into keep, reap, and undetermined — and delete nothing.
+ *
+ * The order of decision is liveness, then the retention window, then the floor. An artifact whose
+ * `live` is `"unknown"` leaves at the first step and is never considered again: it is not counted
+ * toward `keepLast`, so a transient mount failure cannot satisfy "keep my last two" with artifacts
+ * nobody confirmed while the confirmed ones are deleted.
+ *
+ * The window boundary belongs to the safe side. An artifact exactly `maxAgeMs` old is kept, so a
+ * 30-day retention never means 29 depending on clock granularity.
+ *
+ * @returns the three buckets. Their union is exactly the input, each artifact counted once — the
+ *   invariant an operator reads the totals against.
+ * @throws RetentionPolicyError when `maxAgeMs` is negative or not finite, or `keepLast` is negative
+ *   or not an integer. Nonsense is refused rather than clamped, because a clamped window on this
+ *   path deletes data the operator meant to keep.
+ * @public
+ */
 declare function planReaping(input: ReapPlanInput): ReapPlan;
 
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
@@ -2426,7 +2885,19 @@ declare class Security {
  *
  * @public
  */
-/** @public */
+/**
+ * The vocabulary, the layer names, and the values to resolve.
+ *
+ * Two orders matter and they are not the same one. The UNRESTRICTED layers — every key of `layers`
+ * that is neither `override` nor listed in `restricted` — are resolved last-wins in the enumeration
+ * order of the `layers` object. The RESTRICTED layers are applied in the order of the `restricted`
+ * array, regardless of where they sit in `layers`. Put a layer in `restricted` and its position in
+ * that array is what decides when it gets to tighten.
+ *
+ * A layer named in `restricted` but absent from `layers`, or present with `undefined`, is skipped.
+ *
+ * @public
+ */
 interface SecurityFloorInput {
     /**
      * The vocabulary, ordered from most confined to least. Index is permissiveness, so
@@ -2444,6 +2915,23 @@ interface SecurityFloorInput {
     readonly layers: Readonly<Record<string, string | undefined>>;
 }
 /**
+ * Resolve a security-relevant setting so that a lower-trust layer can only tighten it.
+ *
+ * Two paths. When `layers[override]` holds a value, that value is returned VERBATIM and nothing
+ * else is consulted — it is not checked against `permissiveness`, because validating the operator's
+ * own flag belongs to the consumer that owns the vocabulary and the error message. Otherwise a
+ * baseline is taken from the unrestricted layers, and each restricted layer in turn may lower it
+ * and never raise it.
+ *
+ * Two consequences worth knowing before wiring this up. A value in a restricted layer that is not
+ * in `permissiveness` is IGNORED rather than trusted, so a typo in a repository's config leaves the
+ * baseline standing instead of becoming the effective setting. And the ceiling only ever descends:
+ * once one restricted layer tightens, a later one cannot return to the baseline, even though it
+ * could have chosen that value had it come first.
+ *
+ * When no layer supplied a value at all, the answer is `undefined` — the absence is reported rather
+ * than filled in with the most confined member of the vocabulary.
+ *
  * @returns the resolved value, or `undefined` when no layer supplied one.
  * @public
  */
@@ -2474,7 +2962,16 @@ declare function applySecurityFloor(input: SecurityFloorInput): string | undefin
 
 /** Why the destruction was refused. @public */
 type LiveSessionReason = "session-is-live" | "liveness-undetermined";
-/** @public */
+/**
+ * Raised by `guardSessionDestruction` instead of letting a session be destroyed.
+ *
+ * Read `reason` rather than the message when deciding what to do: `"session-is-live"` is fixed by
+ * closing the other session, `"liveness-undetermined"` is fixed by making the liveness check work
+ * again, and telling a user to close a session when nothing could be read sends them to close
+ * nothing. `sessionId` carries the session the refusal was about.
+ *
+ * @public
+ */
 declare class LiveSessionError extends TheokitAgentError {
     readonly name = "LiveSessionError";
     readonly sessionId: string;
@@ -2670,6 +3167,16 @@ 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`. */
 interface TaskFilter {
@@ -2677,7 +3184,11 @@ 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`. */
@@ -2746,6 +3257,15 @@ interface TaskWorkContext {
     readonly signal: AbortSignal;
     emit(payload: unknown): void;
 }
+/**
+ * The unit of work handed to {@link Task.submit}.
+ *
+ * It receives the context rather than raw arguments: `ctx.signal` aborts on cancel and should be
+ * observed by anything long-running, and `ctx.emit(payload)` produces a `progress` event for
+ * subscribers. May be synchronous — the return type allows a plain value as well as a promise.
+ *
+ * @public
+ */
 type TaskWorkFn<T> = (ctx: TaskWorkContext) => Promise<T> | T;
 /**
  * Registry-level configuration. May only be applied BEFORE the first
@@ -2757,6 +3277,22 @@ interface TaskConfigureOptions {
     readonly maxConcurrent?: number;
     readonly retentionMs?: number;
 }
+/**
+ * Static facade over the process-wide task registry — the observability layer for asynchronous
+ * work.
+ *
+ * Not instantiable: the constructor throws, and every operation is a static that delegates to one
+ * in-process singleton. Tasks are an OPT-IN wrapper. `Agent.send`, `Agent.batch`, `Workflow.run`
+ * and `Cron` fires only appear here when submitted with `{ task: true }`; work you submit yourself
+ * goes through `Task.submit`.
+ *
+ * Two ordering constraints bite in practice. `Task.configure` must run before the first `submit` of
+ * the process — a later call logs one line and is otherwise a no-op. And `Task.get` returning
+ * `undefined` does not mean the id never existed: retention evicts terminal tasks, so an id can go
+ * from known to unknown over time.
+ *
+ * @public
+ */
 declare class Task {
     private constructor();
     /**
@@ -2887,7 +3423,16 @@ 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
+ */
 type SDKModel = ModelListItem;
 /**
  * GitHub repository connected to the team. Cloud-only.
@@ -2999,17 +3544,56 @@ declare class Theokit {
  * @public
  */
 
-/** @public */
+/**
+ * Symbol-keyed on purpose. THAT is what keeps the declaration out of a prompt: `Object.keys` and
+ * `JSON.stringify` both ignore symbol keys, so a tool serialised on its way to the model carries
+ * none of it. A string key would also risk colliding with a property the tool already has.
+ *
+ * Exported because the `@public` `WithBlastRadius<T>` below uses it as a COMPUTED
+ * KEY. A computed key is part of the type it keys, so the emitted declaration
+ * names this const — and a name the declaration file does not carry is a broken
+ * reference (#335). `Symbol.for` keeps it a registry symbol, so an exported
+ * binding does not weaken the property-hiding this comment describes: the value
+ * was always retrievable by any code that knows the string.
+ *
+ * @public
+ */
+declare const DECLARED: unique symbol;
+/**
+ * A tool that may carry a blast-radius declaration under {@link DECLARED}.
+ *
+ * The property is OPTIONAL in the type, so a plain tool is assignable to it and the type alone
+ * never proves a declaration was made. `describeAction` is what tells the two apart at runtime.
+ *
+ * @public
+ */
 type WithBlastRadius<T> = T & {
     readonly [DECLARED]?: DeclaredAction;
 };
 /**
+ * Declare what a tool reaches, for the approval layer rather than for the model.
+ *
+ * This MUTATES `tool` — it defines a symbol-keyed property on the object it was given and hands
+ * the same reference back, so every existing reference to that tool sees the declaration too.
+ * Calling it again on the same tool replaces the previous declaration; the property is
+ * `configurable`, so re-declaring never throws.
+ *
+ * The declaration is invisible to `Object.keys` and `JSON.stringify` because the key is a symbol,
+ * which is what keeps it out of anything serialised into a prompt.
+ *
  * @returns the same tool, with its action declared. The tool is not otherwise altered — the model
  *   must see exactly what it saw before.
  * @public
  */
 declare function withBlastRadius<T extends object>(tool: T, action: DeclaredAction): WithBlastRadius<T>;
 /**
+ * Read back the action a tool declared, if any.
+ *
+ * This is how an approval layer obtains the `action` for `evaluateBlastRadius`. An `undefined`
+ * result means nobody has reviewed this tool's reach, which is a different fact from a tool that
+ * declared a narrow scope — decide what to do with the unreviewed case explicitly rather than
+ * treating it as harmless.
+ *
  * @returns the declared action, or `undefined` when the tool never declared one — NOT an empty
  *   action. "Never declared" and "declared as reaching nothing" are different facts, and collapsing
  *   them is how an unreviewed tool passes as harmless.
@@ -3158,11 +3742,27 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
  *
  * @public
  */
-/** @public */
+/**
+ * Whether a project directory may switch anything on.
+ *
+ * There is no middle level on purpose: `untrusted` means every declared capability is off, not
+ * "some are off". A product that wants a partial grant expresses it by declaring fewer capabilities
+ * for that call, not by inventing a third level here.
+ *
+ * @public
+ */
 type TrustLevel = "trusted" | "untrusted";
 /** Where the decision came from. @public */
 type TrustSource = "env" | "store" | "default";
-/** @public */
+/**
+ * What the decision is made from: the capability vocabulary, a way to read the operator's record,
+ * and an optional blanket override.
+ *
+ * `capabilities` is load-bearing rather than descriptive — the returned `allows` is built from
+ * exactly this list, so a capability missing from it is a capability nothing gates.
+ *
+ * @public
+ */
 interface TrustPostureInput<K extends string> {
     /**
      * Every capability a repository could switch on. `allows` is built from exactly this list — the
@@ -3181,14 +3781,36 @@ interface TrustPostureInput<K extends string> {
      */
     readonly envOverride?: boolean;
 }
-/** @public */
+/**
+ * The decision: the level, where it came from, and one boolean per declared capability.
+ *
+ * `allows` has exactly the keys of the `capabilities` list it was built from, so reading a
+ * capability the caller never declared is a type error rather than a silent `undefined` that a
+ * consumer would read as "not allowed".
+ *
+ * @public
+ */
 interface TrustPosture<K extends string> {
     readonly level: TrustLevel;
     readonly source: TrustSource;
     /** One entry per declared capability. Every value is `false` when the level is untrusted. */
     readonly allows: Readonly<Record<K, boolean>>;
 }
-/** @public */
+/**
+ * Decide what a project directory is allowed to switch on.
+ *
+ * Precedence: `envOverride === true` grants trust and SHORT-CIRCUITS — `isTrusted` is not called at
+ * all, which matters because it may touch the filesystem. Otherwise `isTrusted()` is called exactly
+ * once and its answer decides. `envOverride === false` is not a denial: it falls through to the
+ * store like `undefined` does, so an unset or explicitly-off environment switch can never revoke a
+ * directory the operator recorded as trusted.
+ *
+ * Every entry of `allows` is `false` whenever the level is untrusted, and the entries are generated
+ * from `capabilities` rather than supplied per capability — that is what makes "nothing was left
+ * ungated" a property of the call instead of a habit of the caller.
+ *
+ * @public
+ */
 declare function resolveTrustPosture<K extends string>(input: TrustPostureInput<K>): TrustPosture<K>;
 
 /**
@@ -3243,7 +3865,19 @@ interface WiredEntity {
      */
     readonly suppressedByTrust: boolean;
 }
-/** @public */
+/**
+ * The two halves of the observation: the gate that was applied, and what was handed to the builder.
+ *
+ * `requested` drives the shape of the record — the result has exactly its keys — while `posture`
+ * only has to contain a gate for each of them. A posture that gates MORE than `requested` covers is
+ * fine and normal; a posture that gates FEWER is refused, see `recordWiring`.
+ *
+ * Pass the values at the moment they go to the builder. Re-deriving them from configuration
+ * afterwards would defeat the point: config is what was asked for, and the disagreement with what
+ * was wired is the only thing this records.
+ *
+ * @public
+ */
 interface WiringRecordInput<K extends string> {
     /**
      * The gate. Typically the output of `resolveTrustPosture`, which is what makes the name
@@ -3260,11 +3894,25 @@ interface WiringRecordInput<K extends string> {
     readonly requested: Readonly<Record<K, readonly string[]>>;
 }
 /**
+ * Record what a build actually wired, per capability.
+ *
+ * For each key of `requested`: `active` is a copy of the requested names when the posture allows
+ * that capability and an empty array when it does not, `requested` is always a copy of what was
+ * asked for, and `suppressedByTrust` is true only when the gate emptied a NON-EMPTY request. A
+ * withheld capability that requested nothing reports `false`, because a flag that fires when
+ * nothing happened is a flag readers learn to ignore.
+ *
+ * Pure and synchronous — it performs no I/O, which is what makes "this is not a second read of the
+ * configuration" checkable rather than promised.
+ *
  * @returns one entry per key of `requested`, each a snapshot rather than a view of the caller's
  *   arrays — the record is read long after the build, and aliasing would make it answer with what
  *   the process holds now instead of with what was wired.
+ * @throws UngatedCapabilityError when a key of `requested` has no entry in `posture.allows`. Absent
+ *   is not read as denied: reporting a capability nobody gates as suppressed would send the reader
+ *   looking for a trust setting that does not exist.
  * @public
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, 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, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, 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, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };