@theokit/sdk 5.13.0 → 5.15.0

package/dist/{sdk-agent-CTOJlWA_.d.ts → sdk-agent-CnwPODYH.d.ts}

@@ -431,6 +431,13 @@ type McpStdioServerConfig = {
      * policy and always wins. Pass `"all"` to restore full inheritance.
      */
     envPolicy?: EnvPolicy;
+    /**
+     * Run the calls a model makes to this server's tools in ONE step one at a time, in the order the
+     * model listed them, instead of at once. Set it for a stateful server whose tools act on shared
+     * state, such as a browser MCP server where a snapshot must wait for the navigation before it.
+     * Calls to other servers or non-MCP tools in the same step are not held behind it. Default `false`.
+     */
+    sequential?: boolean;
 };
 /**
  * OAuth-style auth bundle for HTTP/SSE MCP servers.
@@ -482,6 +489,13 @@ type McpHttpServerConfig = {
      * `NetworkError` (`code: "mcp_timeout"`). Default 30_000.
      */
     requestTimeoutMs?: number;
+    /**
+     * Run the calls a model makes to this server's tools in ONE step one at a time, in the order the
+     * model listed them, instead of at once. Set it for a stateful server whose tools act on shared
+     * state, such as a browser MCP server where a snapshot must wait for the navigation before it.
+     * Calls to other servers or non-MCP tools in the same step are not held behind it. Default `false`.
+     */
+    sequential?: boolean;
 };
 /**
  * Union of MCP server configs.
@@ -1577,6 +1591,17 @@ interface ToolResultGuardOptions {
     /** Redact common PII patterns (email, phone) in tool-result content. */
     redactPii?: boolean;
 }
+/**
+ * B-564 — how old a tool result may get, in tool rounds, before its content is pruned from the
+ * next LLM request (`SendOptions.pruneToolResults`). Contract type owned by `types/`; the
+ * implementation lives in `internal/agent-loop/prune-tool-results.ts`, which re-exports this.
+ *
+ * @public
+ */
+interface PruneToolResultsOptions {
+    /** Keep the newest `olderThanRounds` tool rounds whole; an integer of at least 1. */
+    olderThanRounds: number;
+}
 /**
  * Lifecycle status of a {@link Run}.
  *
@@ -1853,6 +1878,8 @@ type SDKImage = {
     mimeType: string;
     dimension?: SDKImageDimension;
 };
+/** How a message sent during a running turn is queued. See {@link SendOptions.queueMode}. @public */
+type QueueMode = "followup" | "steer" | "collect";
 /**
  * Structured form of `agent.send()`'s message argument. Use it to send images
  * alongside text.
@@ -1868,7 +1895,7 @@ interface SDKUserMessage {
  *
  * ## Which options do I need?
  *
- * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * Twenty-two 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
@@ -1878,9 +1905,9 @@ interface SDKUserMessage {
  * | If you are… | you want |
  * |---|---|
  * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
- * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `pruneToolResults`, `perToolTimeoutMs` |
  * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
- * | orchestrating agents | `origin`, `task`, `context` |
+ * | orchestrating agents | `origin`, `task`, `context`, `queueMode` |
  * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
  *
  * Every field appears in exactly one row, and
@@ -1891,6 +1918,18 @@ interface SDKUserMessage {
  * @public
  */
 interface SendOptions {
+    /**
+     * What to do with this message when the agent is ALREADY running a turn (local runtime only; a
+     * cloud agent always queues as `"followup"`). With no turn running, every mode just starts one.
+     *
+     * - `"followup"` (default) — wait for the running turn, then run as its own turn.
+     * - `"steer"` — inject the text into the RUNNING turn as a user message, picked up before the
+     *   model's next call (after the current tool round). Resolves to the running turn's `Run`. If
+     *   the turn ends before it can pick the message up, it runs as a followup turn instead.
+     * - `"collect"` — batch every `"collect"` message sent while a turn runs into ONE followup turn
+     *   (texts joined by a blank line). Every collecting caller resolves to that same batched `Run`.
+     */
+    queueMode?: QueueMode;
     /**
      * Per-send model override. SE8 — accepts a bare-string id shorthand
      * (`"openai/gpt-4o-mini"`, normalized to `{ id }`) OR a {@link ModelSelection}
@@ -2023,6 +2062,20 @@ interface SendOptions {
      * @public
      */
     toolResultGuard?: ToolResultGuardOptions;
+    /**
+     * B-564 — opt-in pruning of aged tool results. With `{ olderThanRounds: n }`, the content of
+     * every tool result older than `n` tool rounds is replaced by a short stub in each request the
+     * run's agent loop sends (its `toolUseId` and `isError` kept; session compaction is not pruned); the transcript the run keeps, persists and resumes
+     * from stays whole. `olderThanRounds` must be an integer of at least 1, else the send fails
+     * with `ConfigurationError` code `invalid_prune_tool_results` before any provider call.
+     * Undefined = no pruning (the request is unchanged). Pruning trades request size against
+     * prefix-cache reuse: each new round turns one more previously sent result into a stub, so the
+     * request prefix changes from that message onward on providers that cache message prefixes.
+     * The cache-hit cost was not measured.
+     *
+     * @public
+     */
+    pruneToolResults?: PruneToolResultsOptions;
     /**
      * Opt-in task wrapping (ADRs D363, D374). When truthy, the entire
      * run is registered as a `Task` in the SDK's observable registry —
@@ -2557,4 +2610,4 @@ interface InvalidateCacheOptions {
     applyNow?: boolean;
 }
 
-export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, ToolCall as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, ResolvedProviderRoute as a7, RunCompactBoundaryEvent as a8, RunCompletionCheckEvent as a9, SDKProvidersManager as aA, SDKRequestMessage as aB, SDKStatusMessage as aC, SDKSystemMessage as aD, SDKTaskMessage as aE, SDKThinkingMessage as aF, SDKToolUseMessage as aG, SDKUserMessage as aH, SDKUserMessageEvent as aI, SendOptions as aJ, ShellCommand as aK, ShellConversationTurn as aL, ShellOutput as aM, ShellOutputDeltaUpdate as aN, StepCompletedUpdate as aO, StepStartedUpdate as aP, StreamToCompletionResult as aQ, SummaryCompletedUpdate as aR, SummaryStartedUpdate as aS, SummaryUpdate as aT, SystemPromptSkillRef as aU, TextDeltaUpdate as aV, ThinkingCompletedUpdate as aW, ThinkingDeltaUpdate as aX, ThinkingMessage as aY, TokenDeltaUpdate as aZ, TokenUsage as a_, RunErrorDetail as aa, RunEvent as ab, RunGitInfo as ac, RunMemoryDegradedEvent as ad, RunPermissionDeniedEvent as ae, RunRateLimitEvent as af, RunStatus as ag, RunTaskCompletedEvent as ah, RunTaskStartedEvent as ai, RunTaskUpdatedEvent as aj, RunTimelineEvent as ak, RunToCompletionOptions as al, RunToCompletionResult as am, RunToolProgressEvent as an, RunTripwireEvent as ao, RunUntilIterator as ap, SDKAgentPlugins as aq, SDKAgentSkillDetail as ar, SDKAgentSkills as as, SDKArtifact as at, SDKAssistantMessage as au, SDKContextManager as av, SDKImage as aw, SDKImageDimension as ax, SDKObjectDelta as ay, SDKPluginMetadata as az, Run as b, ToolCallCompletedUpdate as b0, ToolCallStartedUpdate as b1, ToolResult as b2, ToolResultGuardOptions as b3, ToolUseBlock as b4, TurnEndedUpdate as b5, UserMessage as b6, UserMessageAppendedUpdate as b7, Verdict as b8, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };
+export type { OutputProcessorContext as $, AgentConversationTurn as A, GenerateRunResult as B, ContextSettings as C, DoomLoopThresholds as D, EnvPolicy as E, ForkOptions as F, GoalOptions as G, InteractionUpdate as H, InputProcessorContext as I, JudgeResult as J, InvalidateCacheOptions as K, McpAuthConfig as L, McpServerConfig as M, McpHttpServerConfig as N, McpOAuthConfig as O, ProviderRoutingSettings as P, McpStdioServerConfig as Q, RunResult as R, SDKAgent as S, MemoryAdapter as T, MemoryAdapterCapabilities as U, MemoryContext as V, MemoryFact as W, MemoryRevision as X, MemoryToolSchema as Y, MemoryTurnMessage as Z, MessageOrigin as _, PluginsSettings as a, TokenDeltaUpdate as a$, PartialToolCallUpdate as a0, PersonalityPreset as a1, ProcessorControls as a2, ProcessorTripwire as a3, ProcessorViolation as a4, ProviderCapability as a5, ProviderRoute as a6, PruneToolResultsOptions as a7, QueueMode as a8, ResolvedProviderRoute as a9, SDKObjectDelta as aA, SDKPluginMetadata as aB, SDKProvidersManager as aC, SDKRequestMessage as aD, SDKStatusMessage as aE, SDKSystemMessage as aF, SDKTaskMessage as aG, SDKThinkingMessage as aH, SDKToolUseMessage as aI, SDKUserMessage as aJ, SDKUserMessageEvent as aK, SendOptions as aL, ShellCommand as aM, ShellConversationTurn as aN, ShellOutput as aO, ShellOutputDeltaUpdate as aP, StepCompletedUpdate as aQ, StepStartedUpdate as aR, StreamToCompletionResult as aS, SummaryCompletedUpdate as aT, SummaryStartedUpdate as aU, SummaryUpdate as aV, SystemPromptSkillRef as aW, TextDeltaUpdate as aX, ThinkingCompletedUpdate as aY, ThinkingDeltaUpdate as aZ, ThinkingMessage as a_, RunCompactBoundaryEvent as aa, RunCompletionCheckEvent as ab, RunErrorDetail as ac, RunEvent as ad, RunGitInfo as ae, RunMemoryDegradedEvent as af, RunPermissionDeniedEvent as ag, RunRateLimitEvent as ah, RunStatus as ai, RunTaskCompletedEvent as aj, RunTaskStartedEvent as ak, RunTaskUpdatedEvent as al, RunTimelineEvent as am, RunToCompletionOptions as an, RunToCompletionResult as ao, RunToolProgressEvent as ap, RunTripwireEvent as aq, RunUntilIterator as ar, SDKAgentPlugins as as, SDKAgentSkillDetail as at, SDKAgentSkills as au, SDKArtifact as av, SDKAssistantMessage as aw, SDKContextManager as ax, SDKImage as ay, SDKImageDimension as az, Run as b, TokenUsage as b0, ToolCall as b1, ToolCallCompletedUpdate as b2, ToolCallStartedUpdate as b3, ToolResult as b4, ToolResultGuardOptions as b5, ToolUseBlock as b6, TurnEndedUpdate as b7, UserMessage as b8, UserMessageAppendedUpdate as b9, Verdict as ba, Processor as c, GoalEvent as d, GoalResult as e, MemoryId as f, RunEventSink as g, SDKProvider as h, SDKMessage as i, AgentMemory as j, AgentOperation as k, AssistantMessage as l, CompletionCheck as m, CompletionCheckResult as n, ContextBudget as o, ContextManagerKind as p, ContextSnapshot as q, ContextSource as r, ContextSourceStatus as s, ConversationStep as t, ConversationTurn as u, CostBreakdown as v, CostSource as w, CostStatus as x, ForkResult as y, GenerateOptions as z };

package/dist/session-store-Dh07jr9N.d.cts

@@ -0,0 +1,209 @@
+/**
+ * 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
+ * `uuid`/`parentUuid` DAG of records with structured
+ * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
+ * pluggable {@link SessionStore} seam operates over.
+ *
+ * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
+ * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
+ * re-exports it for back-compat while owning the record builders + reader.
+ *
+ * @public
+ */
+/** A content block inside {@link TranscriptMessage}. */
+type TranscriptBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking?: string;
+    signature?: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+};
+/**
+ * The message body of a {@link SessionRecord}.
+ *
+ * **It is NOT called `SessionMessage`** — that name already exists in
+ * `internal/session/session-types.ts` with the shape `{role, text}`, incompatible with this one.
+ * Reusing an exported name for a new shape is
+ * precisely the silent break M91 cost two patches to undo.
+ *
+ * Parsing from disk stays **tolerant** (`readTranscript` skips a malformed line): what changes here
+ * is the **type**, not leniency — records written by earlier versions stay readable.
+ *
+ * @public
+ */
+interface TranscriptMessage {
+    role: "user" | "assistant";
+    content: TranscriptBlock[];
+    /**
+     * The three fields below appear **only** on the assistant record, and come from the writer
+     * (`SessionTranscript.appendAssistant`). Declared optional because the user record does not carry
+     * them — measured in the writer itself, not assumed.
+     */
+    id?: string;
+    type?: "message";
+    model?: string;
+}
+/**
+ * One transcript record — a single line of the session JSONL file, and the unit the pluggable
+ * `SessionStore` seam reads and writes.
+ *
+ * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
+ * and is `null` at the root. Thread a session by following those links; a reader that assumes file
+ * order is linear will mis-thread one that branched.
+ *
+ * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
+ * so it is optional even on records you would expect to be conversational, and `type` is what tells
+ * you which you are holding.
+ *
+ * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
+ * Every record you receive is well-formed, but the file may have contained more than you got back,
+ * so this is not the type to use for an exact-count audit of what was written.
+ *
+ * @public
+ */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    /**
+     * The message body, in the shape the transcript writer actually writes.
+     *
+     * M94 — it was `Record<string, unknown>`, and the consumer recovered the type with a cast on every read.
+     * The shape **has always been fixed** (`SessionTranscript.appendToolResults` / `#push` produce
+     * it); it simply was not declared. It stays optional because system records carry no message.
+     */
+    message?: TranscriptMessage;
+}
+
+/**
+ * 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 /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `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
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * 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>;
+}
+
+export type { SessionRecord as S, TranscriptBlock as T, SessionStore as a, TranscriptMessage as b };

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

@@ -0,0 +1,209 @@
+/**
+ * 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
+ * `uuid`/`parentUuid` DAG of records with structured
+ * `text`/`tool_use`/`tool_result`/`thinking` blocks. This is the contract the
+ * pluggable {@link SessionStore} seam operates over.
+ *
+ * DIP-correct home (SE46): the contract lives in the domain `types/` layer;
+ * the application-layer DAG core (`internal/persistence/session-transcript.ts`)
+ * re-exports it for back-compat while owning the record builders + reader.
+ *
+ * @public
+ */
+/** A content block inside {@link TranscriptMessage}. */
+type TranscriptBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking?: string;
+    signature?: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+};
+/**
+ * The message body of a {@link SessionRecord}.
+ *
+ * **It is NOT called `SessionMessage`** — that name already exists in
+ * `internal/session/session-types.ts` with the shape `{role, text}`, incompatible with this one.
+ * Reusing an exported name for a new shape is
+ * precisely the silent break M91 cost two patches to undo.
+ *
+ * Parsing from disk stays **tolerant** (`readTranscript` skips a malformed line): what changes here
+ * is the **type**, not leniency — records written by earlier versions stay readable.
+ *
+ * @public
+ */
+interface TranscriptMessage {
+    role: "user" | "assistant";
+    content: TranscriptBlock[];
+    /**
+     * The three fields below appear **only** on the assistant record, and come from the writer
+     * (`SessionTranscript.appendAssistant`). Declared optional because the user record does not carry
+     * them — measured in the writer itself, not assumed.
+     */
+    id?: string;
+    type?: "message";
+    model?: string;
+}
+/**
+ * One transcript record — a single line of the session JSONL file, and the unit the pluggable
+ * `SessionStore` seam reads and writes.
+ *
+ * Records form a `uuid`/`parentUuid` DAG, not a flat list: `parentUuid` names the preceding record
+ * and is `null` at the root. Thread a session by following those links; a reader that assumes file
+ * order is linear will mis-thread one that branched.
+ *
+ * `message` is absent on `system` records — a compaction boundary carries `compactMetadata` instead —
+ * so it is optional even on records you would expect to be conversational, and `type` is what tells
+ * you which you are holding.
+ *
+ * Reading is deliberately tolerant: a malformed line is skipped rather than failing the whole read.
+ * Every record you receive is well-formed, but the file may have contained more than you got back,
+ * so this is not the type to use for an exact-count audit of what was written.
+ *
+ * @public
+ */
+interface SessionRecord {
+    type: "user" | "assistant" | "system";
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    isSidechain?: boolean;
+    userType?: string;
+    cwd?: string;
+    version?: string;
+    subtype?: string;
+    compactMetadata?: {
+        preTokens: number;
+        trigger: string;
+    };
+    /**
+     * The message body, in the shape the transcript writer actually writes.
+     *
+     * M94 — it was `Record<string, unknown>`, and the consumer recovered the type with a cast on every read.
+     * The shape **has always been fixed** (`SessionTranscript.appendToolResults` / `#push` produce
+     * it); it simply was not declared. It stays optional because system records carry no message.
+     */
+    message?: TranscriptMessage;
+}
+
+/**
+ * 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 /
+ * durable object) can be the **primary store AND resume source** — the
+ * serverless (ephemeral FS) and multi-host / multi-pod use case that SE40
+ * dropped when it removed the `ConversationStorageAdapter`. This is deliberately
+ * NOT that removed ~10-method adapter: the seam is JUST record read/append over
+ * the native {@link SessionRecord} shape (no getMessages / getSessionMeta /
+ * delete / objective methods).
+ *
+ * The SDK ships a real default implementation, `FsSessionStore`, that reads and
+ * append-writes the native Claude-shaped `.jsonl` transcript — omitting
+ * `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
+ * guarantees for two hosts appending to the same `agentId`.
+ *
+ * @public
+ */
+
+/**
+ * The pluggable session-store seam. Exactly two methods over the native
+ * {@link SessionRecord} shape.
+ *
+ * @public
+ */
+interface SessionStore {
+    /**
+     * Return every persisted record for `agentId`, in append order. A session
+     * that was never written MUST resolve to `[]` (not throw) — a fresh agent has
+     * no history. The SDK reconstructs the resumable `LlmMessage[]` from these
+     * records via the native DAG reader, so the shape MUST be the exact
+     * {@link SessionRecord} the SDK writes.
+     *
+     * A store that cannot READ (e.g. the backing DB is unreachable on resume)
+     * MUST throw a typed error rather than silently returning `[]` — a silent
+     * empty read would masquerade as "no history" and drop the conversation.
+     */
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    /**
+     * Append `records` (the new-turn delta) to `agentId`'s session, append-only.
+     * MUST preserve order and MUST NOT drop or rewrite prior records — the native
+     * format is an append-only `parentUuid` DAG (compaction is a new-root
+     * `compact_boundary` record, still an append).
+     *
+     * Note on the write path: per-turn persistence is fire-and-forget so `send()`
+     * is never blocked by store I/O — an `appendRecords` rejection is logged to
+     * stderr, NOT thrown to the caller (best-effort write). An external store that
+     * must guarantee durability should make `appendRecords` resilient (retry /
+     * durable write) internally. This differs from {@link SessionStore.readRecords},
+     * 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>;
+}
+
+export type { SessionRecord as S, TranscriptBlock as T, SessionStore as a, TranscriptMessage as b };

package/dist/skills.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk7WARNHWW_cjs = require('./chunk-7WARNHWW.cjs');
+var chunk3UMPP553_cjs = require('./chunk-3UMPP553.cjs');
 require('./chunk-3KIUY67P.cjs');
 require('./chunk-SA6K24NB.cjs');
 require('./chunk-6XQLTQB6.cjs');
@@ -11,15 +11,15 @@ require('./chunk-RNXXYF22.cjs');
 
 Object.defineProperty(exports, "buildSkillsBlock", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.buildSkillsBlock; }
+  get: function () { return chunk3UMPP553_cjs.buildSkillsBlock; }
 });
 Object.defineProperty(exports, "discoverSkills", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.discoverSkills; }
+  get: function () { return chunk3UMPP553_cjs.discoverSkills; }
 });
 Object.defineProperty(exports, "loadSkillInstructions", {
   enumerable: true,
-  get: function () { return chunk7WARNHWW_cjs.loadSkillInstructions; }
+  get: function () { return chunk3UMPP553_cjs.loadSkillInstructions; }
 });
 //# sourceMappingURL=skills.cjs.map
 //# sourceMappingURL=skills.cjs.map

package/dist/skills.js

@@ -1,4 +1,4 @@
-export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-NHOEXFZT.js';
+export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-2HXTNVLM.js';
 import './chunk-PKRPV3R7.js';
 import './chunk-UKMBRMGT.js';
 import './chunk-Q7UG242V.js';

package/dist/sqlite-session-store-BbcpKY1L.d.ts

@@ -0,0 +1,64 @@
+import { a as SessionStore, S as SessionRecord } from './session-store-Dh07jr9N.js';
+
+/**
+ * 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.
+ * An entry is dropped as soon as its key has no call pending.
+ * Signature and semantics will not change before sdk-core v3.0.
+ *
+ * @public
+ */
+declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
+
+/** Options for {@link SqliteSessionStore}. */
+interface SqliteSessionStoreOptions {
+    /** Absolute path of the SQLite file. Parent directories are created. */
+    filePath: string;
+}
+/**
+ * A {@link SessionStore} that keeps the native session records in one SQLite file instead of
+ * per-agent JSONL transcripts. Pass it as `local.sessionStore`.
+ *
+ * Uses `better-sqlite3` when installed, else the built-in `node:sqlite` (Node 22.5+).
+ * Appends are one transaction, so a batch lands whole or not at all; order is the
+ * autoincrement `seq`. Corruption is NOT silently rebuilt: opening a corrupt file throws.
+ *
+ * @public
+ */
+declare class SqliteSessionStore implements SessionStore {
+    private readonly filePath;
+    private dbPromise;
+    constructor(options: SqliteSessionStoreOptions);
+    private db;
+    readRecords(agentId: string): Promise<SessionRecord[]>;
+    appendRecords(agentId: string, records: readonly SessionRecord[]): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+export { SqliteSessionStore as S, type SqliteSessionStoreOptions as a, withCwdMutex as w };