@theokit/sdk 5.13.0 → 5.15.0

package/dist/sqlite-session-store-TKXtT4ON.d.cts

@@ -0,0 +1,64 @@
+import { a as SessionStore, S as SessionRecord } from './session-store-Dh07jr9N.cjs';
+
+/**
+ * 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 };

package/dist/subagents-loader-KLWF4QPD.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkAUH2EVWY_cjs = require('./chunk-AUH2EVWY.cjs');
+require('./chunk-YQ3XC6C2.cjs');
+require('./chunk-6XQLTQB6.cjs');
+require('./chunk-CEGU5AVD.cjs');
+require('./chunk-RNXXYF22.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkAUH2EVWY_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-KLWF4QPD.cjs.map
+//# sourceMappingURL=subagents-loader-KLWF4QPD.cjs.map

package/dist/{subagents-loader-TXOA5EJJ.cjs.map → subagents-loader-KLWF4QPD.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-TXOA5EJJ.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-KLWF4QPD.cjs"}

package/dist/subagents-loader-SXETS2F2.js

@@ -0,0 +1,7 @@
+export { loadSubagents } from './chunk-WM646HEN.js';
+import './chunk-YMVTUV5K.js';
+import './chunk-Q7UG242V.js';
+import './chunk-TNFOU6SB.js';
+import './chunk-3OY6H3I7.js';
+//# sourceMappingURL=subagents-loader-SXETS2F2.js.map
+//# sourceMappingURL=subagents-loader-SXETS2F2.js.map

package/dist/{subagents-loader-Z744TAKD.js.map → subagents-loader-SXETS2F2.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-Z744TAKD.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-SXETS2F2.js"}

package/dist/subagents-loader.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkWDVG5R2Q_cjs = require('./chunk-WDVG5R2Q.cjs');
+var chunkAUH2EVWY_cjs = require('./chunk-AUH2EVWY.cjs');
 require('./chunk-YQ3XC6C2.cjs');
 require('./chunk-6XQLTQB6.cjs');
 var chunkCEGU5AVD_cjs = require('./chunk-CEGU5AVD.cjs');
@@ -23,7 +23,7 @@ function resolveSources(options) {
 }
 async function discoverSubagents(cwd, options) {
   const sources = resolveSources(options);
-  return chunkWDVG5R2Q_cjs.loadSubagents(cwd, sources.includes("project"), void 0, options?.compatSources ?? []);
+  return chunkAUH2EVWY_cjs.loadSubagents(cwd, sources.includes("project"), void 0, options?.compatSources ?? []);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.d.cts

@@ -1,8 +1,9 @@
-import { a as AgentDefinition } from './agent-iW5kPpfT.cjs';
-import './sdk-agent-4-dXI2GS.cjs';
+import { a as AgentDefinition } from './agent-B6FQad6P.cjs';
+import './sdk-agent-BA_6_wtc.cjs';
 import './agent-prims-CZyxfCmS.cjs';
 import 'zod';
 import './errors-base-B5g01neU.cjs';
+import './session-store-Dh07jr9N.cjs';
 
 /**
  * A declared foreign source: a bare kind, or a kind with the surfaces it may be read for.

package/dist/subagents-loader.d.ts

@@ -1,8 +1,9 @@
-import { a as AgentDefinition } from './agent-DSMuwADp.js';
-import './sdk-agent-CTOJlWA_.js';
+import { a as AgentDefinition } from './agent-B6C9i_qu.js';
+import './sdk-agent-CnwPODYH.js';
 import './agent-prims-CZyxfCmS.js';
 import 'zod';
 import './errors-base-B5g01neU.js';
+import './session-store-Dh07jr9N.js';
 
 /**
  * A declared foreign source: a bare kind, or a kind with the surfaces it may be read for.

package/dist/subagents-loader.js

@@ -1,4 +1,4 @@
-import { loadSubagents } from './chunk-RN3XDZGS.js';
+import { loadSubagents } from './chunk-WM646HEN.js';
 import './chunk-YMVTUV5K.js';
 import './chunk-Q7UG242V.js';
 import { ConfigurationError } from './chunk-TNFOU6SB.js';

package/dist/types/agent.d.ts

@@ -327,7 +327,8 @@ export type SystemPromptResolver = (ctx: SystemPromptContext) => string | Promis
  */
 export interface SkillsSettings {
     /**
-     * Names of skills the parent agent may invoke. When omitted, every
+     * Names of skills the local runtime loads: a skill not named here cannot be listed or read.
+     * When omitted, every
      * discovered skill is enabled.
      */
     enabled?: string[];
@@ -344,6 +345,12 @@ export interface SkillsSettings {
      * default `<cwd>/.theokit/skills`. Absent ⇒ the default root.
      */
     skillsDir?: string;
+    /**
+     * B-546 — directories (each containing `<name>/SKILL.md`) an application ships inside its own
+     * package. They are read AFTER the project roots and plugin bundles, so a workspace skill of the
+     * same name always wins, and they are kept even when `skillsDir` replaces the default roots.
+     */
+    bundledDirs?: string[];
     /**
      * M22 — code-defined skills (from `createSkill`) merged with the discovered ones. An inline skill
      * overrides a discovered file skill of the same name.
@@ -737,6 +744,18 @@ export interface AgentOptions {
         conversationId: string;
         userId?: string;
     }) => Promise<void> | void;
+    /**
+     * Start a fresh conversation when the agent has been idle this many minutes.
+     *
+     * Checked at the start of a local `send`: when more than this long has passed since the previous
+     * `send` on the same agent began, the in-memory conversation is cleared first, so the model
+     * receives no prior messages and `onBeforeSend` reports `previousMessageCount: 0`. Absent (the
+     * default), or not a positive finite number, never resets. The first send of a process has no
+     * previous send, so it never resets. The on-disk transcript is not deleted.
+     *
+     * @public
+     */
+    sessionIdleResetMinutes?: number;
     /**
      * Fires before each `agent.send`. `previousMessageCount` is the count of
      * messages already persisted BEFORE the current send adds the user

package/dist/types/budget-tracker.d.ts

@@ -24,8 +24,12 @@ export interface BudgetUsageEvent {
     readonly tokens: number;
     /** Provider/model identifier (e.g., `"openai/gpt-4o-mini"`). */
     readonly model: string;
-    /** Whether this is an input (prompt) or output (completion) measurement. */
-    readonly type: "input" | "output";
+    /**
+     * Whether this is an input (uncached prompt), output (completion), `cache_read` (prompt tokens
+     * served from the provider's cache) or `cache_write` (prompt tokens written to it) measurement.
+     * A tracker that has no separate rate for the cache types should treat them as input.
+     */
+    readonly type: "input" | "output" | "cache_read" | "cache_write";
     /** Optional ISO 8601 timestamp; defaults to now() if omitted. */
     readonly at?: string;
 }

package/dist/types/mcp.d.ts

@@ -30,6 +30,13 @@ export 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.
@@ -81,6 +88,13 @@ export 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.

package/dist/types/run.d.ts

@@ -24,6 +24,17 @@ export 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
+ */
+export interface PruneToolResultsOptions {
+    /** Keep the newest `olderThanRounds` tool rounds whole; an integer of at least 1. */
+    olderThanRounds: number;
+}
 /**
  * Lifecycle status of a {@link Run}.
  *
@@ -300,6 +311,8 @@ export type SDKImage = {
     mimeType: string;
     dimension?: SDKImageDimension;
 };
+/** How a message sent during a running turn is queued. See {@link SendOptions.queueMode}. @public */
+export type QueueMode = "followup" | "steer" | "collect";
 /**
  * Structured form of `agent.send()`'s message argument. Use it to send images
  * alongside text.
@@ -315,7 +328,7 @@ export 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
@@ -325,9 +338,9 @@ export 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
@@ -338,6 +351,18 @@ export interface SDKUserMessage {
  * @public
  */
 export 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}
@@ -470,6 +495,20 @@ export 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 —

package/dist/workflow.d.cts

@@ -1,5 +1,5 @@
 import { ZodType, z } from 'zod';
-import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-4-dXI2GS.cjs';
+import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-BA_6_wtc.cjs';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.cjs';
 import { C as CustomTool } from './agent-prims-CZyxfCmS.cjs';
 

package/dist/workflow.d.ts

@@ -1,5 +1,5 @@
 import { ZodType, z } from 'zod';
-import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-CTOJlWA_.js';
+import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-CnwPODYH.js';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
 import { C as CustomTool } from './agent-prims-CZyxfCmS.js';
 

package/docs/adr/mutation-testing-scope.md

@@ -0,0 +1,66 @@
+# Mutation testing covers only the B-026 spike over `src/internal/llm`
+
+- Status: superseded by B-445 (Stryker scope extended to `packages/sdk/src`, see below)
+- Date: 2026-10-17
+- Decided by: human/paulo
+- Soft cap dismissed: `auditor_unavailable_d4` (code-quality D4, mutation testing), for B-380
+  (`sdk-memory-ceiling`) and for any item whose files sit outside the Stryker scope below
+
+## Context
+
+`stryker.config.json` at the repository root came in with adeba4b1 as a measurement spike for
+B-026. It was never wired into a gate. Its scope is narrow on purpose:
+
+- `mutate` is `src/internal/llm/**/*.ts`, nothing else;
+- it is meant to run from `packages/sdk` (`pnpm --filter exec`), so `jsonReporter.fileName` is
+  `../../reports/mutation/slice.json` (now `reports/mutation/mutation.json`);
+- `inPlace: true` is required because `packages/sdk/vitest.setup.ts` imports
+  `../../tools/preflight-native-bindings.mjs`, which escapes the package, so a sandbox copy fails
+  before it collects a test. The same commit records that `inPlace` restores file content but not
+  file mode, which strips the executable bit from `bin/*.mjs` entry points.
+
+The kit's code-quality detector D4 looks for a Stryker config in the manifest directory (the
+repository root here), runs `stryker run --reporters json` from there, and reads
+`reports/mutation/mutation.json`. With this config that file is never written, so D4 reports
+`auditor_unavailable_d4` ("stryker ran but wrote no report"). B-380 was the first item in this
+repository to reach the code-quality audit, and none of its files is under `src/internal/llm`.
+Nothing in B-380 touched the config.
+
+## Decision
+
+Mutation testing in theokit-sdk is the B-026 spike over `src/internal/llm` and nothing more, until
+a separate backlog item extends it. D4 cannot measure code outside that scope today, so an item
+whose files are outside it carries no mutation measurement, and its audit's
+`auditor_unavailable_d4` soft cap is dismissed by this record. Extending Stryker is registered as
+its own backlog item (`repo: theokit-sdk`).
+
+This dismisses the cap. It does not claim the uncovered code is well tested: the unit and
+integration suites are still the only evidence for it.
+
+## Alternatives rejected
+
+- Extend the Stryker config inside B-380, writing the report to `reports/mutation/mutation.json`
+  and mutating the memory files. Rejected because it widens an item that is already executing.
+  Runs over `packages/sdk` took minutes per file set, surviving mutants could need new tests, and
+  the `inPlace` file-mode risk above would come with it, all for work B-380 never scoped.
+- Treat the mismatch as a kit defect (D4 runs from the repository root while the config expects
+  `packages/sdk`), report it to the kit and hold B-380 until it is fixed. Rejected because the
+  config is a spike that was never adopted as a gate. A kit fix would run Stryker against the same
+  `src/internal/llm` glob and still measure nothing B-380 changed.
+
+## Consequences
+
+- Every item outside `src/internal/llm` reaches review with D4 unmeasured and FAIL_SOFT, admitted
+  only through this record.
+- The record stops applying once the backlog item that extends Stryker lands. At that point it
+  should be marked superseded.
+
+## Superseded (B-445)
+
+This record is superseded by the record of the new scope: `stryker.config.json` now mutates
+`packages/sdk/src/**/*.ts`, runs from the repository root and writes
+`reports/mutation/mutation.json`, which is where the D4 detector reads it. So D4 reports a score for
+items under `packages/sdk/src`, and the `auditor_unavailable_d4` dismissal above no longer applies.
+`inPlace` still drops file modes, so `pnpm run mutation` snapshots the mode of every
+`packages/*/bin/*.mjs` first and `tools/check-bin-modes.mjs verify` fails the run if any changed.
+The full-scope run was not executed where this was written (no dependencies installed).