@theokit/sdk 5.14.0 → 5.15.1

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-DExqjqYy.cjs';
-import './sdk-agent-DwzHcuxy.cjs';
+import { a as AgentDefinition } from './agent-BL4kxgwq.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-Dfw3VsIX.js';
-import './sdk-agent-a3fW1xUK.js';
+import { a as AgentDefinition } from './agent-ByDx7K30.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[];
@@ -743,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/hooks.d.ts

@@ -18,7 +18,13 @@
  *
  * @public
  */
-/** The five lifecycle events the runtime actually fires. */
+/**
+ * The five lifecycle events the runtime actually fires.
+ *
+ * `postRun` (once per run, including a failed run) is internal-only: it is reachable from the
+ * SDK's own hook config and spies, but `.theokit/hooks.json` (Claude Code event names) cannot
+ * register it, because no Claude Code event means "end of a run". `Stop` fires only on a finished run.
+ */
 export type HookEvent = "preRun" | "postRun" | "preToolUse" | "postToolUse" | "stop";
 /**
  * #631 — what the consumer is shown when asked to approve a hook.

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

@@ -311,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.
@@ -338,7 +340,7 @@ export interface SDKUserMessage {
  * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
  * | 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
@@ -349,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}

package/dist/workflow.d.cts

@@ -1,5 +1,5 @@
 import { ZodType, z } from 'zod';
-import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-DwzHcuxy.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-a3fW1xUK.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

@@ -1,6 +1,6 @@
 # Mutation testing covers only the B-026 spike over `src/internal/llm`
 
-- Status: accepted
+- 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
@@ -13,7 +13,7 @@ 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`;
+  `../../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
@@ -54,3 +54,13 @@ integration suites are still the only evidence for it.
   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).

package/docs/error-codes.md

@@ -6,7 +6,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 
 **Transport codes vs the rest.** `ErrorCode` in `errors.ts` is the small canonical union a provider failure maps onto — the codes marked *transport* below. Everything else is raised by a specific subsystem at a specific place, and a `catch` that only handles the union will meet them anyway.
 
-256 distinct code(s).
+257 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -17,11 +17,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `agent_id_already_exists` | domain | ConfigurationError | `packages/sdk/src/internal/agent/helpers.ts:59` |
 | `agent_not_registered` | domain | UnknownAgentError | `packages/sdk/src/internal/cron/run-job.ts:61` |
 | `agent_rehydration_failed` | domain | UnknownAgentError | `packages/sdk/src/internal/agent/helpers.ts:362` +1 |
-| `anthropic_auth_failed` | domain | AuthenticationError | `packages/sdk/src/internal/error-mappers/anthropic.ts:56` |
-| `anthropic_rate_limit` | domain | RateLimitError | `packages/sdk/src/internal/error-mappers/anthropic.ts:59` |
-| `anthropic_server_error` | domain | NetworkError | `packages/sdk/src/internal/error-mappers/anthropic.ts:71` |
-| `anthropic_timeout` | domain | NetworkError | `packages/sdk/src/internal/error-mappers/anthropic.ts:68` |
-| `anthropic_unknown` | domain | UnknownAgentError | `packages/sdk/src/internal/error-mappers/anthropic.ts:73` |
+| `anthropic_auth_failed` | domain | AuthenticationError | `packages/sdk/src/internal/error-mappers/anthropic.ts:59` |
+| `anthropic_rate_limit` | domain | RateLimitError | `packages/sdk/src/internal/error-mappers/anthropic.ts:62` |
+| `anthropic_server_error` | domain | NetworkError | `packages/sdk/src/internal/error-mappers/anthropic.ts:74` |
+| `anthropic_timeout` | domain | NetworkError | `packages/sdk/src/internal/error-mappers/anthropic.ts:71` |
+| `anthropic_unknown` | domain | UnknownAgentError | `packages/sdk/src/internal/error-mappers/anthropic.ts:76` |
 | `artifact_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:294` |
 | `auth_failed` | domain | ConfigurationError, MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:237` +10 |
 | `auth_permission` | domain | — | `packages/sdk/src/internal/error-mappers/vertex.ts:49` |
@@ -41,19 +41,19 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cloud_incompatible_function_resolver` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:43` +2 |
 | `cloud_incompatible_mcp_stdio_local` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-tool-parity.ts:74` |
 | `cloud_plugin_path_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:195` +1 |
-| `cloud_run_http_error` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:156` |
-| `cloud_run_unknown_status` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:285` +1 |
-| `cloud_runtime_pre_release` | domain | ConfigurationError | `packages/sdk/src/agent.ts:419` +2 |
+| `cloud_run_http_error` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:159` |
+| `cloud_run_unknown_status` | domain | NetworkError | `packages/sdk/src/internal/cloud-agent/real-cloud-run.ts:292` +1 |
+| `cloud_runtime_pre_release` | domain | ConfigurationError | `packages/sdk/src/agent.ts:435` +2 |
 | `cloud_stdio_cwd_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:123` |
 | `compression_failed` | domain | — | `packages/sdk/src/errors.ts:703` |
 | `compression_model_unresolved` | domain | — | `packages/sdk/src/internal/runtime/compression/compression-model-registry.ts:102` +1 |
-| `content_filtered` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:139` |
+| `content_filtered` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:135` |
 | `context_config_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:288` |
 | `context_frontmatter_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-frontmatter.ts:38` |
 | `context_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:282` |
 | `context_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:269` |
 | `context_sources_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:309` |
-| `context_too_long` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:137` |
+| `context_too_long` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:133` |
 | `credential_pool_ambiguous` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:70` +1 |
 | `credential_pool_empty` | domain | ConfigurationError | `packages/sdk/src/internal/llm/credential-pool.ts:91` |
 | `cron_ambiguous_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:215` |
@@ -61,7 +61,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cron_no_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:221` +1 |
 | `cron_workflow_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:227` |
 | `duplicate_skill_name` | domain | ConfigurationError | `packages/sdk/src/define-skill-read-tool.ts:166` |
-| `duplicate_tool_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:203` |
+| `duplicate_tool_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:225` |
 | `effective_tools_expected_options` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/effective-tools.ts:102` +1 |
 | `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:146` +1 |
 | `embedding_invalid_response` | domain | NetworkError | `packages/sdk/src/internal/memory/adapters/openai-compatible.ts:400` |
@@ -80,7 +80,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_invalid` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:116` |
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:42` +1 |
-| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:467` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:551` |
 | `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:415` |
 | `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:252` +2 |
 | `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:243` |
@@ -96,7 +96,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_concurrency` | domain | ConfigurationError | `packages/sdk/src/internal/agent/batch.ts:58` +1 |
 | `invalid_context_window_margin` | domain | — | `packages/sdk/src/compaction.ts:278` +1 |
 | `invalid_cron` | domain | ConfigurationError | `packages/sdk/src/internal/cron/validate.ts:35` +3 |
-| `invalid_doom_loop_threshold` | domain | ConfigurationError | `packages/sdk/src/internal/agent-loop/doom-loop-tracker.ts:47` |
+| `invalid_doom_loop_threshold` | domain | ConfigurationError | `packages/sdk/src/internal/agent-loop/doom-loop-tracker.ts:51` |
 | `invalid_filename_id` | domain | ConfigurationError | `packages/sdk/src/internal/security/path-guard.ts:486` |
 | `invalid_identifier` | domain | ConfigurationError | `packages/sdk/src/internal/security/path-guard.ts:434` +2 |
 | `invalid_input` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:98` +9 |
@@ -127,17 +127,18 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `local_provider_unreachable` | domain | ConfigurationError | `packages/sdk/src/internal/catalog/local-models.ts:46` |
 | `malformed_api_key` | domain | AuthenticationError | `packages/sdk/src/internal/agent/helpers.ts:231` +1 |
 | `max_delegation_depth` | domain | MaxDelegationDepthError | `packages/sdk/src/a2a/subagent.ts:239` +1 |
-| `mcp_buffer_overflow` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:332` |
-| `mcp_closed` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:307` |
-| `mcp_crashed` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:222` |
-| `mcp_disconnected` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:235` +2 |
-| `mcp_http_error` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:497` +1 |
-| `mcp_not_init` | domain | ConfigurationError | `packages/sdk/src/internal/mcp/client.ts:265` +2 |
-| `mcp_timeout` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:69` |
+| `mcp_auth_unsupported` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:140` +1 |
+| `mcp_buffer_overflow` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:338` |
+| `mcp_closed` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:313` |
+| `mcp_crashed` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:228` |
+| `mcp_disconnected` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:241` +2 |
+| `mcp_http_error` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:510` +1 |
+| `mcp_not_init` | domain | ConfigurationError | `packages/sdk/src/internal/mcp/client.ts:271` +2 |
+| `mcp_timeout` | domain | NetworkError | `packages/sdk/src/internal/mcp/client.ts:71` |
 | `memory_ceiling_reached` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/fact-ceiling.ts:43` +1 |
 | `memory_context_missing_user_id` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent-memory-direct.ts:128` |
 | `memory_path_escapes_root` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:115` +1 |
-| `memory_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:285` |
+| `memory_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:307` |
 | `memory_threat_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:283` |
 | `memory_tool_bad_args` | domain | ConfigurationError | `packages/sdk/src/internal/memory/tools.ts:138` +1 |
 | `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:159` +1 |
@@ -183,15 +184,15 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:227` |
 | `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:212` +2 |
 | `programmatic_hooks_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:99` |
-| `provider_unresolved` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:107` +2 |
-| `quota_exceeded` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:148` |
+| `provider_unresolved` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:110` +2 |
+| `quota_exceeded` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:144` |
 | `rate_limit` | domain | — | `packages/sdk/src/internal/error-mappers/vertex.ts:47` |
 | `rate_limited` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:244` +3 |
 | `redirect_blocked` | domain | — | `packages/sdk-tools/src/internal/network-guard.ts:38` |
 | `repo_provision_failed` | domain | — | `packages/sdk/src/sandbox/provision.ts:33` |
 | `reserved_env_prefix` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:110` |
 | `run_cancelled` | domain | — | `packages/sdk/src/errors.ts:656` |
-| `run_not_found` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:426` |
+| `run_not_found` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:442` |
 | `runtime_exclusive` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:90` |
 | `sandbox_derived_helper_failed` | domain | ConfigurationError | `packages/sdk/src/sandbox/types.ts:223` +1 |
 | `sandbox_not_available` | domain | SandboxNotAvailableError | `packages/sdk/src/sandbox/types.ts:108` +1 |
@@ -207,15 +208,15 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `sse_server_error` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:155` |
 | `ssrf_blocked` | domain | — | `packages/sdk-tools/src/internal/network-guard.ts:23` |
 | `stream_idle_timeout` | domain | NetworkError | `packages/sdk/src/internal/llm/sse.ts:95` |
-| `stream_malformed_frame` | domain | NetworkError | `packages/sdk/src/internal/llm/anthropic.ts:221` |
+| `stream_malformed_frame` | domain | NetworkError | `packages/sdk/src/internal/llm/anthropic.ts:229` |
 | `stream_truncated` | domain | NetworkError | `packages/sdk/src/internal/llm/anthropic.ts:189` +1 |
 | `subagent_foreign_runtime_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:245` |
 | `subagent_mcp_unsupported_local` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:272` |
-| `subagent_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:144` |
-| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:349` |
-| `subagent_missing_prompt` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:149` |
-| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:292` |
-| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:312` |
+| `subagent_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:166` |
+| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:352` |
+| `subagent_missing_prompt` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:171` |
+| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:295` |
+| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:315` |
 | `subagent_unknown_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:249` |
 | `subagent_unknown_setting_source` | domain | ConfigurationError | `packages/sdk/src/subagents-loader.ts:96` |
 | `subscribe_baseUrl_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:78` |
@@ -228,18 +229,18 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `task_not_found` | domain | — | `packages/sdk/src/task-errors.ts:53` +1 |
 | `task_op_unsupported` | domain | — | `packages/sdk/src/task-errors.ts:73` +1 |
 | `timeout` | domain | — | `packages/sdk/src/internal/error-mappers/vertex.ts:55` |
-| `tool_invalid_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:241` |
-| `tool_invalid_schema_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:270` |
-| `tool_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:256` |
-| `tool_missing_handler` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:228` |
-| `tool_missing_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:236` |
-| `tool_missing_schema` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:265` |
-| `tool_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:247` |
+| `tool_invalid_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:263` |
+| `tool_invalid_schema_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:292` |
+| `tool_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:278` |
+| `tool_missing_handler` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:250` |
+| `tool_missing_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:258` |
+| `tool_missing_schema` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:287` |
+| `tool_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:269` |
 | `transport_failure` | domain | NetworkError | `packages/sdk/src/internal/llm/transport-error.ts:48` |
-| `transport_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:589` +1 |
+| `transport_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:603` +1 |
 | `unimplemented_budget_scope` | domain | ConfigurationError | `packages/sdk/src/internal/budget/registry.ts:58` +1 |
 | `unknown` | domain | AgentRunError, MemoryAdapterError, TheokitAgentError | `packages/memory-honcho/src/adapter.ts:264` +5 |
-| `unknown_agent` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:209` +1 |
+| `unknown_agent` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:212` +1 |
 | `unknown_artifact` | domain | UnknownAgentError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:313` |
 | `unknown_category` | domain | ConfigurationError | `packages/sdk-memory/src/internal/categorized-memory.ts:76` |
 | `unknown_cron_job` | domain | UnknownAgentError | `packages/sdk/src/cron.ts:80` +2 |

package/docs/harness-capability-map.md

@@ -4,7 +4,7 @@ Every public symbol the TheoKit workspace publishes, and the exact specifier to
 
 A symbol listed under two specifiers is reachable from both, but that does NOT make the two interchangeable: a class emitted separately into a subpath entry is a distinct nominal type from the one in the root bundle, so passing one where the other is expected fails on a private field. When a symbol appears twice, import it and everything it is passed to from the SAME specifier.
 
-1272 export(s) across 53 entry point(s).
+1293 export(s) across 54 entry point(s).
 
 ## `@theokit/acp`
 
@@ -309,6 +309,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `ProviderTransform` | interface | M41 — the one OPTIONAL behavior seam on a provider profile.  |
 | `ProviderTransformContext` | interface | M41 (agent-builder provider framework) — the context a provider's `transform` receives per request.  |
 | `PruneToolResultsOptions` | interface | B-564 — how old a tool result may get, in tool rounds, before its content is pruned from the next LLM request (`SendOptions.pruneToolResults`).  |
+| `QueueMode` | type | How a message sent during a running turn is queued.  |
 | `RateLimitError` | class | Too many requests or usage limits exceeded. |
 | `readManagedSettings` | function | Read the deployed policy, or `{}` when none is.  |
 | `readSessionMessages` | function | Read the messages a session already contains, for a surface that needs to re-render it.  |
@@ -397,6 +398,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `SkillsSettings` | interface | Skills configuration accepted by `Agent.create()` via {@link AgentOptions.skills } .  |
 | `SOVEREIGN_ENV_KEYS` | const | Variables a project-scoped source may never set.  |
 | `SovereignEnvKey` | type | The union of {@link SOVEREIGN_ENV_KEYS } entries — the variables a project-scoped `.env` may never set.  |
+| `SqliteSessionStore` | class | A {@link SessionStore } that keeps the native session records in one SQLite file instead of per-agent JSONL transcripts.  |
+| `SqliteSessionStoreOptions` | interface | Options for {@link SqliteSessionStore } . |
 | `Squad` | class | A sequential agent team produced by {@link createSquad } .  |
 | `SquadOptions` | interface | Options for {@link createSquad } . |
 | `SquadRun` | interface | Result of a {@link Squad.run } .  |
@@ -572,8 +575,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `CircuitBreaker` | class | Stops calling a recall path that keeps timing out.  |
 | `CircuitBreakerOptions` | interface | Consecutive-timeout circuit breaker for Active Memory recall.  |
 | `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
-| `Cluster` | interface | A group of facts the REM phase judged related.  |
-| `ClusterResult` | interface | What {@link remPhase } produced.  |
+| `Cluster` | interface | A group of semantically similar facts, with the text chosen to represent them. |
+| `ClusterResult` | interface | What clustering produced: the clusters and how many facts the per-sweep cap left out. |
 | `cohereMemoryEmbeddingProviderAdapter` | const | Cohere embeddings.  |
 | `collectMarkdownFiles` | function | Every markdown file the memory corpus holds: the index, the per-memory files, `notes/`, `wiki/` and `sessions/`, each tagged with the bucket `memory_search`'s `corpus` filters on.  |
 | `CreateAdapterOptions` | interface | Per-call overrides handed to {@link MemoryEmbeddingProviderAdapter.create } .  |
@@ -605,7 +608,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
 | `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
 | `DreamingOptions` | interface | Dreaming sweep orchestrator (ADR D7 of memory-system-peer-project-parity).  |
-| `DreamingResult` | interface | What one sweep did.  |
+| `DreamingResult` | interface | Outcome of one dreaming sweep: counts before and after, and the note written. |
 | `dropVectorIndex` | function | Drop the `embeddings` table, discarding every stored vector.  |
 | `EmbedAllArgs` | interface | Inputs for {@link embedMissingChunks } : the open database and the embedding runtime to call. |
 | `EmbeddingCache` | interface | The cache contract the shared runtime writes through.  |
@@ -631,7 +634,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LanceSearchOptions` | interface | Filters for `LanceIndex.search`.  |
 | `lanceStoragePath` | function | `<memory root>/lance`.  |
 | `legacyMemoryJsonPath` | function | Resolve the legacy JSON memory path used pre-ADR-D8 (kept for migration helpers + tests).  |
-| `lightPhase` | function | Light phase — drop facts whose embedding is too similar to one already kept. |
+| `lightPhase` | function | Light phase — drop facts whose embedding is too similar to one already kept.  |
 | `listNotes` | function | List the `.md` files directly under `notes/`.  |
 | `loadSqliteVecExtension` | function | Load the `sqlite-vec` extension into an opened SQLite connection.  |
 | `mapOpenAICompatibleError` | function | Turn a failed OpenAI-shaped HTTP response into the typed error the SDK throws.  |
@@ -697,7 +700,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
 | `runActiveMemory` | function | Run one blocking recall before the system prompt is assembled, and report what happened.  |
 | `RunActiveMemoryArgs` | interface | Everything {@link runActiveMemory } needs for one attempt.  |
-| `runDreamingSweep` | function | Run one consolidation sweep over `MEMORY.md`: drop near-duplicate facts, cluster what is left, write a consolidated note under `notes/`, and append a diary entry.  |
+| `runDreamingSweep` | function | Run one dreaming sweep (dedupe, cluster, write a consolidated note), serialised per `cwd`. |
 | `SCHEMA_STATEMENTS` | const | SQLite schema for the memory index.  |
 | `SearchOptions` | interface | Search tuning.  |
 | `SessionFile` | interface | Session summary discovery (ADR D20).  |
@@ -880,6 +883,14 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LogbookEntry` | type | One line of the log.  |
 | `ScreenshotLogbookResult` | type | The tool's result, before it is serialised to the JSON string the handler returns. |
 
+## `@theokit/sdk-tools/secrets`
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `createSecretsTool` | function | Create a tool that resolves `{{secret:NAME}}` references and masks secret values in output. |
+| `CreateSecretsToolOptions` | interface | `secrets` — lets an agent USE a stored secret without the value reaching the model.  |
+| `SecretsTool` | interface | A secrets tool: a custom tool that can also wrap other tools with secret resolution. |
+
 ## `@theokit/sdk-tools/structured-output`
 
 | Symbol | Kind | Summary |
@@ -1139,16 +1150,23 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `asMemoryRoot` | function | Treat a directory as a memory root without resolving one.  |
 | `ceilingReachedError` | function | The refusal of a new fact at a store's declared ceiling: where the store is, how many facts it holds, the ceiling, and what to consolidate.  |
 | `claudeProjectMemoryDir` | function | Where the Claude Code CLI keeps THIS project's memories.  |
+| `Cluster` | interface | A group of semantically similar facts, with the text chosen to represent them. |
+| `ClusterResult` | interface | What clustering produced: the clusters and how many facts the per-sweep cap left out. |
 | `collectMarkdownFiles` | function | Every markdown file the memory corpus holds: the index, the per-memory files, `notes/`, `wiki/` and `sessions/`, each tagged with the bucket `memory_search`'s `corpus` filters on.  |
+| `DedupResult` | interface | Dreaming/REM phase logic.  |
+| `deepPhase` | function | Deep phase — render consolidated markdown for the dreamed note. |
 | `defaultIndexPath` | function | `<index root>/.index/memory.sqlite`.  |
 | `DiaryEntry` | interface | Dream-diary append (ADR D7).  |
 | `diaryPath` | function | `<memory root>/dream-diary.md`.  |
 | `DiscoveredFile` | interface | One markdown file the corpus walk found, with the source bucket the indexer tags it with.  |
 | `discoverSessionFiles` | function | Every session summary under `<memory root>/sessions`, as `{ absolutePath, relPath }` records.  |
 | `discoverWikiFiles` | function | Every wiki supplement under `<memory root>/wiki`, as `{ absolutePath, relPath }` records.  |
+| `DreamingOptions` | interface | Dreaming sweep orchestrator (ADR D7 of memory-system-peer-project-parity).  |
+| `DreamingResult` | interface | Outcome of one dreaming sweep: counts before and after, and the note written. |
 | `entryHash` | function | A stable hash of one entry's counts, so two sweeps that did the same work read as the same work.  |
 | `indexBudgetWarning` | function | What to say about an index that the interop partner will truncate, or `undefined` when there is nothing true to say.  |
 | `lanceStoragePath` | function | `<memory root>/lance`.  |
+| `lightPhase` | function | Light phase — drop facts whose embedding is too similar to one already kept.  |
 | `MEMORY_INDEX_MAX_BYTES` | const | The byte limit the Claude Code CLI applies when it loads a `MEMORY.md`, whichever it reaches first.  |
 | `MEMORY_INDEX_MAX_LINES` | const | The line limit the Claude Code CLI applies when it loads a `MEMORY.md`.  |
 | `memoryIndexRoot` | function | Where the search index belongs for this configuration (theokit-sdk#554).  |
@@ -1162,9 +1180,11 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `readAllSqliteFacts` | function | Read all facts from the SQLite memory index.  |
 | `readFacts` | function | Every memory in the store, honouring the `enabled` gate on {@link MemoryConfig } : when memory is disabled the call resolves to `[]` without touching disk.  |
 | `readFactsFromMarkdown` | function | Every memory in the store: the per-memory files, plus any legacy `## Facts` bullets still in `MEMORY.md`.  |
+| `remPhase` | function | REM phase — single-link agglomerative clustering by cosine similarity. |
 | `renderDiaryEntry` | function | One diary entry as the markdown that gets appended: a timestamp heading, the short entry hash, and the counts the sweep produced.  |
 | `resolveMaxFacts` | function | The ceiling a caller declared, or `undefined` when none was declared.  |
 | `resolveMemoryRoot` | function | The memory root for this agent: `memory.directory` when set, the project store otherwise.  |
+| `runDreamingSweep` | function | Run one dreaming sweep (dedupe, cluster, write a consolidated note), serialised per `cwd`. |
 | `SessionFile` | interface | Session summary discovery (ADR D20).  |
 | `sessionsDir` | function | `<memory root>/sessions`.  |
 | `SessionSummaryInput` | interface | Per-run session summary writer (ADR D20).  |
@@ -1320,6 +1340,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `SessionListing` | interface | One session found on disk. |
 | `sessionUuidFor` | function | The transcript filename for an agent id — always a UUID.  |
 | `SessionWriterLease` | interface | A held writer lease.  |
+| `SqliteSessionStore` | class | A {@link SessionStore } that keeps the native session records in one SQLite file instead of per-agent JSONL transcripts.  |
+| `SqliteSessionStoreOptions` | interface | Options for {@link SqliteSessionStore } . |
 | `TranscriptBlock` | type | A content block inside {@link TranscriptMessage } . |
 | `TranscriptMessage` | interface | The message body of a {@link SessionRecord } .  |
 | `transcriptPath` | function | The `.jsonl` path for a session: `<baseDir>/projects/<encoded-cwd>/<session-uuid>.jsonl`. |
@@ -1368,6 +1390,10 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `CreateSandboxBackendOptions` | interface | Options for `createSandboxBackend`, which probes for bubblewrap and returns a {@link LinuxSandbox } when confinement is genuinely available or a `LocalSandbox` when it is not — warning once when th... |
 | `detectBwrap` | function | Honest detection — fail-closed on every probe; NEVER throws (callers WARN + fall back). |
 | `detectBwrapMemoized` | function | `detectBwrap` with memoization — what production should call.  |
+| `DockerRunner` | type | Seam for tests: runs `docker <args>`, optionally feeding `input` to stdin. |
+| `DockerRunResult` | interface | Result of one `docker` invocation: captured output, exit code and whether it timed out. |
+| `DockerSandbox` | class | Sandbox backend that runs each command in a throwaway Docker container. |
+| `DockerSandboxConfig` | interface | Configuration for {@link DockerSandbox } . |
 | `ExecuteResult` | interface | What a {@link SandboxBackend } returns for one command.  |
 | `interactiveWrapCommand` | function | The composition the interactive path needs — the counterpart of `createSandboxBackend`.  |
 | `InteractiveWrapOptions` | interface | Options for `interactiveWrapCommand`, the PTY counterpart of `createSandboxBackend`.  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.14.0",
+  "version": "5.15.1",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",