@theokit/sdk 4.63.3 → 5.0.0-next.1

package/dist/types/env-policy.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `sandbox/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Child-process environment policy contract (#54).
  *
  * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`

package/dist/types/eval.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/eval/` (5 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for `Eval.create / .run` and the `Scorers` namespace
  * (Adoption Roadmap #2; ADRs D202-D213).
  *

package/dist/types/fork.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/runtime/lifecycle/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
  *
  * Extracted into a leaf type module (arch-review ADR 0001) so the public

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/judge/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * M80 — the terminal verdicts a judge can return.
  *
  * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the

package/dist/types/mcp.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { EnvPolicy } from "./env-policy.js";
 /**
  * MCP server configuration accepted by `Agent.create()` and `agent.send()`.

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/local-agent/` (2 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
  * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/memory/storage/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `MemoryProvider` — kernel-facing port for the memory subsystem
  * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
  * SOLID Dependency Inversion).
@@ -10,7 +13,7 @@
  *
  * DIP-correct home (SE46): the port + companion contract types live in the
  * domain `types/` layer; the application-layer module
- * (`internal/runtime/memory/memory-provider.ts`) re-exports them for
+ * (`internal/runtime/memory-glue/memory-provider.ts`) re-exports them for
  * back-compat while the concrete providers live under `internal/`.
  *
  * Layered model (mirrors Budget):
@@ -21,9 +24,26 @@
  *
  * @public — surface-level interface; impls are internal-but-replaceable.
  */
-import type { CustomTool } from "./agent-prims.js";
+import type { CustomTool, ModelSelection } from "./agent-prims.js";
 import type { MemoryAdapter, MemoryFact } from "./memory-adapter.js";
-import type { SDKAgent } from "./sdk-agent.js";
+/**
+ * The agent identity a `MemoryProvider` is given — the whole of it.
+ *
+ * `buildTools` used to declare `agent: SDKAgent`, a 33-member interface, and the agent loop satisfied
+ * it with `{ agentId, model } as SDKAgent`. The cast is what made it compile, and it suppressed
+ * exactly the check that mattered: an implementation reaching for any of the other 31 members —
+ * `send()`, `fork()`, `dispose()` — gets `undefined is not a function` at runtime with no
+ * compile-time signal.
+ *
+ * Two fields is what the port actually offers, so two fields is what it declares. `SDKAgent`
+ * structurally satisfies this, so a caller holding a real agent still passes it, and TypeScript's
+ * bivariant method parameters mean an existing implementation typed `agent: SDKAgent` still compiles.
+ * What changes is that the fabricated ref no longer needs a cast to exist.
+ */
+export interface MemoryProviderAgentRef {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+}
 /** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
 export interface ActiveMemoryPassResult {
     /** Compressed memory facts to seed the LLM's context window for this turn. */
@@ -73,7 +93,7 @@ export interface RecordSessionSummaryArgs {
      * rather than optional. An implementation that recomputed it from `cwd` would write the summary
      * into a different directory than the one the rest of the subsystem uses (#463).
      */
-    readonly memoryRoot: import("../internal/memory/storage/memory-root.js").MemoryRoot;
+    readonly memoryRoot: MemoryRoot;
     /** Run id used as the filename key. */
     readonly runId: string;
     /** Agent identity for scope (foldering). */
@@ -121,7 +141,7 @@ export interface MemoryProvider {
     /** Construct or fetch the per-agent handle. Lazy + idempotent. */
     init(opts: MemoryProviderInitOptions): Promise<MemoryProviderHandle>;
     /** Build the LLM-facing tool catalog (memory_search, memory_get, …). */
-    buildTools(handle: MemoryProviderHandle, agent: SDKAgent): ReadonlyArray<CustomTool>;
+    buildTools(handle: MemoryProviderHandle, agent: MemoryProviderAgentRef): ReadonlyArray<CustomTool>;
     /** Run the active-memory pre-LLM pass — recall + compress + format. */
     runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
     /**
@@ -165,3 +185,22 @@ export interface MemoryProvider {
     /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
     dispose(handle: MemoryProviderHandle): Promise<void> | void;
 }
+/**
+ * A directory that has been RESOLVED as a memory root, distinguished from a bare `cwd`.
+ *
+ * Structural rather than a `unique symbol` brand: a `unique symbol` is identity-based and the d.ts
+ * bundler inlines the declaration into each package that re-exports it, so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ *
+ * G7 / DIP — defined HERE, in the domain types layer, rather than in
+ * `internal/memory/storage/memory-root.ts`. It was defined in the adapter and reached for from this
+ * file, which made the port depend on the adapter for a field of its own argument type; the runtime
+ * helpers (`resolveMemoryRoot`, `asMemoryRoot`) stay in the adapter and import it from here.
+ *
+ * @public
+ */
+export type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};

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

@@ -1,4 +1,8 @@
 /**
+ * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
+ * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
+ * pointing it at a subsystem would name something that does not use it.
+ *
  * Type-leaf — base message types shared between `conversation.ts` and
  * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
  * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06

package/dist/types/messages.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { ModelSelection } from "./agent-prims.js";
 import type { TextBlock } from "./content-blocks.js";
 export type { ImageBlock, TextBlock, ToolResultContentBlock } from "./content-blocks.js";

package/dist/types/plugin.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/plugins/` (3 of 3 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Plugin contract types (T1.1, ADRs D97-D101).
  *
  * Discriminated union by `kind`:
@@ -17,7 +20,7 @@
  *
  * @public
  */
-import type { CustomTool } from "./agent-prims.js";
+import type { CustomTool, PermissionMode } from "./agent-prims.js";
 import type { MemoryAdapter } from "./memory-adapter.js";
 import type { ProviderProfile } from "./provider-profile.js";
 /**
@@ -68,7 +71,7 @@ export interface PreToolCallContext {
      * gate per-run rather than at construction time. Absent ⇒ the plugin's own
      * default applies. Ignored by non-permission plugins.
      */
-    permissionMode?: import("../permission-engine.js").PermissionMode;
+    permissionMode?: PermissionMode;
 }
 /**
  * The veto a `pre_tool_call` handler returns to stop a tool call. Returning `undefined` allows it —
@@ -214,6 +217,12 @@ export type CommandHandler = (args: Record<string, unknown>) => Promise<string>
 export interface CommandOptions {
     description?: string;
 }
+/**
+ * Detaches a hook handler attached with {@link PluginContext.on}. Idempotent.
+ *
+ * @public
+ */
+export type PluginHookDisposer = () => void;
 /**
  * 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
@@ -228,14 +237,33 @@ export interface CommandOptions {
  * 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.
+ *
+ * `on` returns a {@link PluginHookDisposer}: calling it detaches that one handler, and calling it
+ * again is a no-op. A plugin that registers a hook per run and never detaches is the leak this
+ * exists to make fixable.
+ *
+ * @public
  */
 export interface PluginContext {
     /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
     registerTool(tool: CustomTool): void;
     /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
     registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
-    /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */
-    on(hook: HookName, handler: HookHandler): void;
+    /**
+     * Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`.
+     *
+     * Returns a disposer that detaches THIS handler. Calling it twice is a no-op, and a handler the
+     * SDK refused (a non-function, which is warned and ignored) returns a disposer that does nothing —
+     * so the caller never has to branch on whether the registration took.
+     *
+     * It used to return `void`, which made this a one-way door: a plugin registered through
+     * `initialize()` had no removal path and its handlers ran for the life of the process. The one
+     * documented dynamic case — the ACP permission plugin, re-installed on every prompt — worked only
+     * because `#byName` keys the replacement, so re-registering the WHOLE plugin was the only way to
+     * detach one hook. Two observers in this package already return their own disposer
+     * (`FixtureRunBase.onDidChangeStatus`) or offer an explicit removal (`MessageBus.unregister`).
+     */
+    on(hook: HookName, handler: HookHandler): PluginHookDisposer;
     /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
     injectMessage(content: string, role?: "user" | "system"): void;
 }

package/dist/types/processors.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/runtime/processors/` (3 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
  * the user message (input) or the model's final text (output). Processors run in
  * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/providers/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * ProviderProfile + ApiMode + AuthType contract types (T3.1, ADR D105).
  *
  * Profile is **data-only** — no methods. Adding a provider is declaring an

package/dist/types/providers.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (4 of 9 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Capability slot a provider can fulfill.
  *
  * @public

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
  *
  * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
@@ -16,7 +19,7 @@
  *
  * @public
  */
-export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent;
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent | RunMemoryDegradedEvent;
 /**
  * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
  * tools exist for this run.
@@ -157,14 +160,38 @@ export interface RunCompactionFallbackEvent {
     readonly window: number;
 }
 /**
- * SE2 — the opt-in sink for {@link RunEvent}s. Supplied via `SendOptions.onRunEvent`.
- * Synchronous + best-effort: a throwing sink must never break the run (the emitter
- * try-catches it), so keep it fast (push to a queue, don't await).
+ * A memory stage failed and the run continued without it.
+ *
+ * The same shape of gap {@link RunMcpServerFailedEvent} closed for MCP, in the module next door.
+ * `initLoopContext` had three bare `catch { <field> = <empty> }` blocks: an init failure meant no
+ * memory tool was registered, a `buildTools` failure meant no provider tools, and a `runActivePass`
+ * failure meant no recalled context in the system prompt. The agent then answered without the memory
+ * it was configured with, and nothing recorded it — not stderr, not this sink, not the span in scope.
+ *
+ * Degrading to a working agent is the right BEHAVIOUR. This event exists because the degradation was
+ * unobservable, so a host UI showed a healthy run.
+ *
+ * Emitted once per failing stage per run.
+ *
+ * @public
  */
-export type RunEventSink = (event: RunEvent) => void;
+export interface RunMemoryDegradedEvent {
+    readonly type: "memory_degraded";
+    /** Which stage failed: `init`, `buildTools`, or `activePass`. */
+    readonly stage: string;
+    /** Why it failed, as the provider reported it. */
+    readonly message: string;
+}
 /**
- * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
- * observability can never break the run (fail-safe, mirrors the EventBus EC-2
- * contract). No-op when the sink is absent.
+ * Receives every {@link RunEvent} a run emits, in emission order.
+ *
+ * Wired through `onRunEvent` on the run options. The sink is observability, never control flow: it
+ * cannot cancel, alter, or delay the run, and {@link emitRunEvent} swallows anything it throws — a
+ * broken sink degrades what you can see, never what the agent does.
+ *
+ * Synchronous by signature, so a slow sink slows the run. Hand work off rather than awaiting inside
+ * it; returning a promise here would be ignored, not awaited.
+ *
+ * @public
  */
-export declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
+export type RunEventSink = (event: RunEvent) => void;

package/dist/types/run.d.ts

@@ -1,4 +1,9 @@
-import type { CustomTool, ModelSelection } from "./agent-prims.js";
+/**
+ * Owner: `internal/local-agent/` (8 of 34 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+import type { CustomTool, ModelSelection, PermissionMode } from "./agent-prims.js";
 import type { ConversationStep, ConversationTurn } from "./conversation.js";
 import type { McpServerConfig } from "./mcp.js";
 import type { SDKMessage } from "./messages.js";
@@ -308,6 +313,28 @@ export interface SDKUserMessage {
 /**
  * Per-send overrides and callbacks.
  *
+ * ## Which options do I need?
+ *
+ * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
+ * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
+ * have added surface to remove surface, and the harm here is the READING cost, not a representable
+ * illegal state. There is no measured defect behind this grouping and no consumer census; the fields
+ * and the audiences are what was measured.
+ *
+ * | If you are… | you want |
+ * |---|---|
+ * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
+ * | orchestrating agents | `origin`, `task`, `context` |
+ * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
+ *
+ * Every field appears in exactly one row, and
+ * `tests/lint/send-options-audience-table.test.ts` fails when one is added without a row — a table
+ * that silently stops covering the type is worse than none, because a reader trusts it and stops
+ * looking.
+ *
  * @public
  */
 export interface SendOptions {
@@ -374,7 +401,7 @@ export interface SendOptions {
      * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
      * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
      */
-    permissionMode?: import("../permission-engine.js").PermissionMode;
+    permissionMode?: PermissionMode;
     onStep?: (args: {
         step: ConversationStep;
     }) => void | Promise<void>;

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

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/local-agent/` (1 of 2 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { ModelSelection } from "./agent-prims.js";
 import type { SDKContextManager } from "./context.js";
 import type { SDKProvidersManager } from "./providers.js";
@@ -80,6 +85,16 @@ export interface SDKArtifact {
     sizeBytes: number;
     updatedAt: string;
 }
+/**
+ * An operation a consumer may ask an {@link SDKAgent} about via `supports()`.
+ *
+ * Deliberately the members whose availability DIFFERS between runtimes, plus the core ones a caller
+ * may want to assert positively. A union rather than `string` so a typo is a compile error instead
+ * of a silent `false`.
+ *
+ * @public
+ */
+export type AgentOperation = "send" | "generate" | "listArtifacts" | "downloadArtifact" | "runUntil" | "fork" | "runToCompletion" | "streamToCompletion" | "usePersonality" | "invalidateCache";
 /**
  * Handle returned by `Agent.create()` and `Agent.resume()`.
  *
@@ -133,6 +148,34 @@ export interface SDKAgent {
      * idempotent across both surfaces.
      */
     [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Which operations this agent's runtime actually performs.
+     *
+     * `SDKAgent` is one handle over two runtimes that do not offer the same operations, and the type
+     * does not model the difference: `downloadArtifact` is a REQUIRED member that rejects for every
+     * input on a local agent, and five optional members are present-but-throwing on a cloud one, so
+     * `typeof agent.fork === "function"` is true and calling it throws. Neither requiredness nor
+     * optionality expresses "exists here, not there".
+     *
+     * Ask before calling. Mirrors `Run.supports(op)` / `Run.unsupportedReason(op)`, which solved the
+     * same problem one layer down over the `RunOperation` union.
+     *
+     * This is a MITIGATION. The structural fix is to split this interface into a common core plus
+     * `LocalCapableAgent` / `CloudCapableAgent`, so the compiler refuses the call instead of the
+     * runtime and a consumer narrows once instead of asking per call. That is breaking on a published
+     * surface and is deliberately not done here.
+     *
+     * @public
+     */
+    supports(operation: AgentOperation): boolean;
+    /**
+     * Human-readable reason `supports(operation)` returned `false`, or `undefined` when it returned
+     * `true`. The message names the runtime, so an operator reading a log knows which half of the
+     * union they are holding.
+     *
+     * @public
+     */
+    unsupportedReason(operation: AgentOperation): string | undefined;
     /** Cloud-only. Local returns an empty array. */
     listArtifacts(): Promise<SDKArtifact[]>;
     /** Cloud-only. Local throws `UnsupportedRunOperationError`. */

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * The shape of a persisted session turn, as a HOST reads it.
  *
  * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `SessionRecord` — the native on-disk transcript record shape (SE40).
  *
  * The theokit session format IS the Claude Code record shape: a

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

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/session/` (4 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE41 — the pluggable `SessionStore` seam over the NATIVE session transcript.
  *
  * A minimal, two-method port so an external store (Postgres / Redis / KV /
@@ -14,6 +17,19 @@
  * `local.sessionStore` yields byte-identical current behavior (back-compat, zero
  * consumer change). Injected via `local.sessionStore` for external stores.
  *
+ * THIS SEAM DOES NOT HIDE THE STORAGE, AND IS NOT MEANT TO. A Repository
+ * abstracts a persistence model away; this one is defined in terms of the
+ * native one — the port speaks {@link SessionRecord}, "the exact SessionRecord
+ * the SDK writes", and the on-disk layout's path helpers (`encodeProjectDir`,
+ * `transcriptPath`, `transcriptRoot`) are published on purpose at
+ * `@theokit/sdk/persistence` so a consumer can locate a transcript file.
+ *
+ * That is the whole design and the reason the seam is two methods rather than
+ * ten: the format is the contract, and a store implements read/append over it.
+ * A consumer supplying `local.sessionStore` is NOT bound by those paths — they
+ * describe where the DEFAULT `FsSessionStore` puts files, not where an external
+ * store must.
+ *
  * Consistency contract: `appendRecords` is append-only and ordering-preserving.
  * The FS default serializes appends per agent with a cross-process file lock;
  * external implementations own (and MUST document) their own concurrency
@@ -56,4 +72,33 @@ export interface SessionStore {
      * which MUST throw on failure (a resume cannot proceed on a silent partial history).
      */
     appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    /**
+     * Claim the single-writer lease for `agentId`, if this store has one. OPTIONAL.
+     *
+     * The SDK calls it when an agent starts and skips it when absent, so a two-method store keeps
+     * working unchanged — declaring it here does not require it, which is the whole reason it is
+     * optional. What declaring it DOES is make the capability discoverable: the SDK probed for this
+     * method through an `as unknown` cast against an interface that never mentioned it, so a
+     * third-party store author — the serverless / multi-pod case this port exists to serve — read a
+     * two-method interface, implemented two methods, and never learned the hook was there.
+     *
+     * CONTRACT, and the half that matters: a rejection whose `name` is `"SessionBusyError"` PROPAGATES
+     * to the caller, because another process holding the session is a decision the caller has to make
+     * (`exec` forks to a new id). Any other rejection is treated as "no lease available here" —
+     * logged, and the turn proceeds without single-writer protection, since the write is best-effort
+     * by contract anyway.
+     */
+    acquire?(agentId: string): Promise<void>;
+    /**
+     * Release the lease `acquire` claimed, if this store has one. OPTIONAL.
+     *
+     * Called on agent disposal. A rejection is not handled specially.
+     */
+    release?(agentId: string): Promise<void>;
+    /**
+     * Release store-level resources — a connection pool, a file handle. OPTIONAL.
+     *
+     * Called once, on agent disposal, after {@link SessionStore.release}.
+     */
+    dispose?(): Promise<void>;
 }

package/dist/types/task.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/task/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Task observability registry (ADRs D361-D374).
  *
  * Tasks are an opt-in observability layer over async work in the SDK
@@ -141,14 +144,3 @@ export interface TaskCancelResult {
     readonly cancelled: boolean;
     readonly alreadyTerminal: boolean;
 }
-/**
- * Validates a task ID against the public grammar + reserved prefixes.
- * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
- *
- * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
- * to register their own IDs; user-facing surfaces (`Task.submit`,
- * `agent.send({ task: { id } })`) leave it false.
- */
-export declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
-/** Re-exported for adapter implementations + tests. */
-export declare const TASK_RESERVED_PREFIXES: readonly string[];

package/dist/types/theokit.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/catalog/` (2 of 3 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Account-level user info returned by `Theokit.me()`.
  *
  * @public

package/dist/types/trajectory.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public types for ShareGPT trajectory export (ADR D139).
  *
  * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,

package/dist/types/updates.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { UserMessage } from "./messages-base.js";
 /**
  * Single tool call event. The internal `args` and `result` shapes are NOT stable.

package/dist/types/usage.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/budget/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for token usage + cost tracking (ADRs D376-D379).
  *
  * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
@@ -41,7 +44,7 @@ export type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override"
 /**
  * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
  * `amountUsd` is `undefined` — DO NOT default to 0 (a lie). The UI shows
- * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
+ * `n/a` for unknown, `~$1.23` for estimated, `$1.23` for actual.
  */
 export interface CostBreakdown {
     readonly amountUsd: number | undefined;