@theokit/sdk 5.12.1 → 5.14.0

package/dist/workflow.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkZWLFHSON_cjs = require('./chunk-ZWLFHSON.cjs');
-var chunkTLVI2OQK_cjs = require('./chunk-TLVI2OQK.cjs');
+var chunkR35ZJAYT_cjs = require('./chunk-R35ZJAYT.cjs');
+var chunkSETHRLQS_cjs = require('./chunk-SETHRLQS.cjs');
 require('./chunk-VTYY7XL5.cjs');
 require('./chunk-AA27GEYS.cjs');
 require('./chunk-3KIUY67P.cjs');
@@ -14,87 +14,95 @@ require('./chunk-RNXXYF22.cjs');
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.Workflow; }
+  get: function () { return chunkR35ZJAYT_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.WorkflowBuilder; }
+  get: function () { return chunkR35ZJAYT_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.WorkflowToolError; }
+  get: function () { return chunkR35ZJAYT_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.agentStep; }
+  get: function () { return chunkR35ZJAYT_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.cloneWorkflow; }
+  get: function () { return chunkR35ZJAYT_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.fn; }
+  get: function () { return chunkR35ZJAYT_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.workflowAsTool; }
+  get: function () { return chunkR35ZJAYT_cjs.workflowAsTool; }
+});
+Object.defineProperty(exports, "workflowResumeTool", {
+  enumerable: true,
+  get: function () { return chunkR35ZJAYT_cjs.workflowResumeTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkZWLFHSON_cjs.workflowStep; }
+  get: function () { return chunkR35ZJAYT_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowInputError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowNestedError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowOutputError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowParallelError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowResumeStepNotFoundError; }
+});
+Object.defineProperty(exports, "WorkflowResumeWorkflowMismatchError", {
+  enumerable: true,
+  get: function () { return chunkSETHRLQS_cjs.WorkflowResumeWorkflowMismatchError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.WorkflowStateError; }
+  get: function () { return chunkSETHRLQS_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunkTLVI2OQK_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkSETHRLQS_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

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-DwzHcuxy.cjs';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.cjs';
 import { C as CustomTool } from './agent-prims-CZyxfCmS.cjs';
 
@@ -459,8 +459,9 @@ declare function __resetSnapshotStoresForTests(): void;
  */
 
 /**
- * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
- * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
+ * Raised by a {@link workflowAsTool} or {@link workflowResumeTool} tool when the
+ * run does not reach `status: "completed"` (a step failed, the run was cancelled,
+ * or it suspended without `reportSuspended`, which returns a report instead).
  * The dispatch converts it to a `tool_result(isError)`.
  *
  * @public
@@ -487,6 +488,22 @@ interface WorkflowAsToolSpec<T extends ZodType> {
     description: string;
     /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
     inputSchema: T;
+    /**
+     * When `true`, a run that suspends returns `{"status":"suspended","runId":…,"stepId":…}` instead of
+     * raising {@link WorkflowToolError}, so the model can hand the run id to a
+     * {@link workflowResumeTool}. The report carries ids only, never the suspended payload; `stepId` is
+     * `null` for a run that carries no step result. Default `false`.
+     */
+    reportSuspended?: boolean;
+}
+/** Spec for {@link workflowResumeTool}. */
+interface WorkflowResumeToolSpec {
+    /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
+    name: string;
+    /** Description surfaced to the LLM — when the agent should resume a suspended run. */
+    description: string;
+    /** Report a run that suspends again instead of raising, as in {@link WorkflowAsToolSpec}. */
+    reportSuspended?: boolean;
 }
 /**
  * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
@@ -494,7 +511,8 @@ interface WorkflowAsToolSpec<T extends ZodType> {
  * The handler validates the model's args against `spec.inputSchema`, runs the
  * workflow, and returns its output (a string as-is, else JSON). A run that does not
  * reach `status: "completed"` raises a typed {@link WorkflowToolError} (workflow
- * step errors do NOT throw — they surface via `run.status === "failed"`).
+ * step errors do NOT throw — they surface via `run.status === "failed"`), except a
+ * suspended run with `spec.reportSuspended`, which returns the suspended report.
  *
  * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
  * `Workflow` class directly.
@@ -504,6 +522,22 @@ interface WorkflowAsToolSpec<T extends ZodType> {
 declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
     run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
 }, spec: WorkflowAsToolSpec<T>): CustomTool;
+/**
+ * B-677 — a {@link CustomTool} that resumes a suspended run of `workflow` by its run id, with an
+ * optional payload validated against the suspend step's schema. It returns the run's output like
+ * {@link workflowAsTool}; a run that suspends again keeps the same run id and is reported or raised
+ * per `spec.reportSuspended`. Snapshot errors (`WorkflowSnapshotNotFoundError` for an unknown or
+ * already-resumed id, `WorkflowResumeWorkflowMismatchError` for a run another workflow suspended,
+ * `WorkflowResumeStepNotFoundError` when `workflow` lacks the suspended step) and payload validation
+ * errors propagate to the dispatch.
+ *
+ * `workflow` must be the committed instance from `Workflow.create().commit()`. The default snapshot
+ * store is in memory and process-local: a host that resumes across processes configures a persistent
+ * backend. This tool resumes any run id it is given; deciding who may approve a run is the host's job.
+ *
+ * @public
+ */
+declare function workflowResumeTool(workflow: WorkflowResumeOptions["workflow"], spec: WorkflowResumeToolSpec): CustomTool;
 
 /**
  * The workflow error hierarchy — runtime classes, deliberately NOT in `types/`.
@@ -643,6 +677,22 @@ declare class WorkflowResumeStepNotFoundError extends TheokitAgentError {
     readonly name = "WorkflowResumeStepNotFoundError";
     constructor(stepId: string, workflowName: string);
 }
+/**
+ * Thrown by `Workflow.resume()` (and so by a `workflowResumeTool` tool) when the snapshot for the run
+ * id was written by a workflow of another name. The snapshot is left in the store, so the workflow
+ * that suspended the run can still resume it.
+ *
+ * Without this check the default store, one process-global memory store, would let workflow B run
+ * its own tail on workflow A's accumulated input whenever both declare a step with the suspended id.
+ * `name` is a label, not an identity: two workflows that share a name are not told apart here.
+ */
+declare class WorkflowResumeWorkflowMismatchError extends TheokitAgentError {
+    readonly runId: string;
+    readonly snapshotWorkflowName: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeWorkflowMismatchError";
+    constructor(runId: string, snapshotWorkflowName: string, workflowName: string);
+}
 /**
  * Aggregate failure from parallel branches.
  *
@@ -908,4 +958,4 @@ declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>,
     id: string;
 }): Workflow<TI, TO>;
 
-export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep };
+export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowResumeToolSpec, WorkflowResumeWorkflowMismatchError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowResumeTool, workflowStep };

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-a3fW1xUK.js';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
 import { C as CustomTool } from './agent-prims-CZyxfCmS.js';
 
@@ -459,8 +459,9 @@ declare function __resetSnapshotStoresForTests(): void;
  */
 
 /**
- * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
- * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
+ * Raised by a {@link workflowAsTool} or {@link workflowResumeTool} tool when the
+ * run does not reach `status: "completed"` (a step failed, the run was cancelled,
+ * or it suspended without `reportSuspended`, which returns a report instead).
  * The dispatch converts it to a `tool_result(isError)`.
  *
  * @public
@@ -487,6 +488,22 @@ interface WorkflowAsToolSpec<T extends ZodType> {
     description: string;
     /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
     inputSchema: T;
+    /**
+     * When `true`, a run that suspends returns `{"status":"suspended","runId":…,"stepId":…}` instead of
+     * raising {@link WorkflowToolError}, so the model can hand the run id to a
+     * {@link workflowResumeTool}. The report carries ids only, never the suspended payload; `stepId` is
+     * `null` for a run that carries no step result. Default `false`.
+     */
+    reportSuspended?: boolean;
+}
+/** Spec for {@link workflowResumeTool}. */
+interface WorkflowResumeToolSpec {
+    /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
+    name: string;
+    /** Description surfaced to the LLM — when the agent should resume a suspended run. */
+    description: string;
+    /** Report a run that suspends again instead of raising, as in {@link WorkflowAsToolSpec}. */
+    reportSuspended?: boolean;
 }
 /**
  * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
@@ -494,7 +511,8 @@ interface WorkflowAsToolSpec<T extends ZodType> {
  * The handler validates the model's args against `spec.inputSchema`, runs the
  * workflow, and returns its output (a string as-is, else JSON). A run that does not
  * reach `status: "completed"` raises a typed {@link WorkflowToolError} (workflow
- * step errors do NOT throw — they surface via `run.status === "failed"`).
+ * step errors do NOT throw — they surface via `run.status === "failed"`), except a
+ * suspended run with `spec.reportSuspended`, which returns the suspended report.
  *
  * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
  * `Workflow` class directly.
@@ -504,6 +522,22 @@ interface WorkflowAsToolSpec<T extends ZodType> {
 declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
     run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
 }, spec: WorkflowAsToolSpec<T>): CustomTool;
+/**
+ * B-677 — a {@link CustomTool} that resumes a suspended run of `workflow` by its run id, with an
+ * optional payload validated against the suspend step's schema. It returns the run's output like
+ * {@link workflowAsTool}; a run that suspends again keeps the same run id and is reported or raised
+ * per `spec.reportSuspended`. Snapshot errors (`WorkflowSnapshotNotFoundError` for an unknown or
+ * already-resumed id, `WorkflowResumeWorkflowMismatchError` for a run another workflow suspended,
+ * `WorkflowResumeStepNotFoundError` when `workflow` lacks the suspended step) and payload validation
+ * errors propagate to the dispatch.
+ *
+ * `workflow` must be the committed instance from `Workflow.create().commit()`. The default snapshot
+ * store is in memory and process-local: a host that resumes across processes configures a persistent
+ * backend. This tool resumes any run id it is given; deciding who may approve a run is the host's job.
+ *
+ * @public
+ */
+declare function workflowResumeTool(workflow: WorkflowResumeOptions["workflow"], spec: WorkflowResumeToolSpec): CustomTool;
 
 /**
  * The workflow error hierarchy — runtime classes, deliberately NOT in `types/`.
@@ -643,6 +677,22 @@ declare class WorkflowResumeStepNotFoundError extends TheokitAgentError {
     readonly name = "WorkflowResumeStepNotFoundError";
     constructor(stepId: string, workflowName: string);
 }
+/**
+ * Thrown by `Workflow.resume()` (and so by a `workflowResumeTool` tool) when the snapshot for the run
+ * id was written by a workflow of another name. The snapshot is left in the store, so the workflow
+ * that suspended the run can still resume it.
+ *
+ * Without this check the default store, one process-global memory store, would let workflow B run
+ * its own tail on workflow A's accumulated input whenever both declare a step with the suspended id.
+ * `name` is a label, not an identity: two workflows that share a name are not told apart here.
+ */
+declare class WorkflowResumeWorkflowMismatchError extends TheokitAgentError {
+    readonly runId: string;
+    readonly snapshotWorkflowName: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeWorkflowMismatchError";
+    constructor(runId: string, snapshotWorkflowName: string, workflowName: string);
+}
 /**
  * Aggregate failure from parallel branches.
  *
@@ -908,4 +958,4 @@ declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>,
     id: string;
 }): Workflow<TI, TO>;
 
-export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep };
+export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowResumeToolSpec, WorkflowResumeWorkflowMismatchError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowResumeTool, workflowStep };

package/dist/workflow.js

@@ -1,5 +1,5 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-ZLFFDPXC.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-BO3PV3OP.js';
+export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowResumeTool, workflowStep } from './chunk-73IITAF7.js';
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowResumeWorkflowMismatchError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-TDED5XES.js';
 import './chunk-HY66GLM6.js';
 import './chunk-7I5Z3UBJ.js';
 import './chunk-PKRPV3R7.js';

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

@@ -0,0 +1,56 @@
+# Mutation testing covers only the B-026 spike over `src/internal/llm`
+
+- Status: accepted
+- 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`;
+- `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.

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.
 
-251 distinct code(s).
+256 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -40,7 +40,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cloud_custom_tools_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:154` +1 |
 | `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:159` +1 |
+| `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 |
@@ -60,7 +60,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cron_missing_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:233` +1 |
 | `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:155` |
+| `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` |
 | `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 |
@@ -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:455` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:467` |
 | `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` |
@@ -100,7 +100,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `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 |
-| `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:73` |
+| `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:94` |
 | `invalid_memory_backend` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:24` +1 |
 | `invalid_memory_ceiling` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/fact-ceiling.ts:23` +1 |
 | `invalid_memory_directory` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/memory-root.ts:151` |
@@ -108,6 +108,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_model_param` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:43` +1 |
 | `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:25` |
 | `invalid_processor_options` | domain | ConfigurationError | `packages/sdk/src/built-in-processors.ts:86` |
+| `invalid_prune_tool_results` | domain | ConfigurationError | `packages/sdk/src/internal/agent-loop/prune-tool-results.ts:78` |
 | `invalid_redaction_pattern` | domain | ConfigurationError | `packages/sdk/src/security.ts:84` |
 | `invalid_request` | domain | — | `packages/sdk/src/internal/error-mappers/vertex.ts:53` +1 |
 | `invalid_retry_config` | domain | ConfigurationError | `packages/sdk/src/internal/retry/with-retry.ts:67` |
@@ -142,12 +143,13 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:159` +1 |
 | `missing_api_key` | domain | AuthenticationError, ConfigurationError | `packages/sdk/src/internal/agent/helpers.ts:222` +2 |
 | `missing_credential` | domain | AuthenticationError | `packages/sdk/src/internal/providers/builtin/openai-chatgpt.ts:72` |
-| `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:88` |
+| `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:93` |
 | `missing_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:37` |
 | `model_unavailable` | domain | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:75` +2 |
 | `network` | domain | MemoryAdapterError, buildErrorMetadata | `packages/memory-honcho/src/adapter.ts:258` +5 |
 | `network_error` | domain | NetworkError | `packages/sdk/src/internal/http.ts:99` |
-| `no_api_key` | domain | ConfigurationError | `packages/sdk-tools/src/web-search-brave.ts:50` |
+| `no_api_key` | domain | ConfigurationError | `packages/sdk-tools/src/web-search-brave.ts:50` +1 |
+| `no_base_url` | domain | ConfigurationError | `packages/sdk-tools/src/web-search-searxng.ts:35` |
 | `no_memory_adapter` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent-memory-direct.ts:141` +2 |
 | `no_such_session` | domain | NoSuchSessionError | `packages/sdk/src/interactive/types.ts:41` +1 |
 | `no_text_answer` | domain | — | `packages/sdk/src/errors.ts:656` |
@@ -172,12 +174,14 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `personality_not_found` | domain | ConfigurationError | `packages/sdk/src/internal/personality/switch.ts:60` |
 | `personality_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/personality/registry.ts:110` |
 | `pipeline_duplicate_provider` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/system-prompt/pipeline.ts:33` |
-| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:134` |
+| `plugin_entry_import_failed` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/manifest-entry-import.ts:78` |
+| `plugin_entry_missing` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:170` |
+| `plugin_entry_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/manifest-entry-import.ts:85` |
 | `plugin_frontmatter_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugin-frontmatter.ts:39` |
 | `plugin_late_register_kind` | domain | ConfigurationError | `packages/sdk/src/internal/plugins/manager.ts:103` |
-| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:185` |
-| `plugin_manifest_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:191` |
-| `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:176` +2 |
+| `plugin_manifest_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:221` |
+| `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` |
@@ -189,10 +193,10 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `run_cancelled` | domain | — | `packages/sdk/src/errors.ts:656` |
 | `run_not_found` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:426` |
 | `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:185` +1 |
-| `sandbox_not_available` | domain | SandboxNotAvailableError | `packages/sdk/src/sandbox/types.ts:92` +1 |
-| `sandbox_security` | domain | SandboxSecurityError | `packages/sdk/src/sandbox/types.ts:73` +1 |
-| `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:99` +5 |
+| `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 |
+| `sandbox_security` | domain | SandboxSecurityError | `packages/sdk/src/sandbox/types.ts:89` +1 |
+| `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:104` +5 |
 | `server_error` | domain | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:92` +1 |
 | `session_busy` | domain | — | `packages/sdk/src/internal/persistence/session-writer.ts:56` +1 |
 | `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:256` +3 |
@@ -246,7 +250,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `work_threw` | domain | — | `packages/sdk/src/internal/task/registry.ts:295` |
 | `workflow_already_committed` | domain | ConfigurationError | `packages/sdk/src/workflow.ts:269` |
 | `workflow_already_running` | domain | — | `packages/sdk/src/workflow-errors.ts:141` |
-| `workflow_compensate_not_implemented` | domain | — | `packages/sdk/src/workflow-errors.ts:246` +1 |
+| `workflow_compensate_not_implemented` | domain | — | `packages/sdk/src/workflow-errors.ts:270` +1 |
 | `workflow_duplicate_step_id` | domain | — | `packages/sdk/src/workflow-errors.ts:31` |
 | `workflow_input_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:48` |
 | `workflow_max_iterations_exceeded` | domain | — | `packages/sdk/src/workflow-errors.ts:181` |
@@ -254,11 +258,12 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `workflow_not_serializable` | domain | — | `packages/sdk/src/workflow-errors.ts:195` +1 |
 | `workflow_output_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:65` |
 | `workflow_resume_step_not_found` | domain | — | `packages/sdk/src/workflow-errors.ts:210` +1 |
+| `workflow_resume_workflow_mismatch` | domain | — | `packages/sdk/src/workflow-errors.ts:234` +1 |
 | `workflow_snapshot_not_found` | domain | — | `packages/sdk/src/workflow-errors.ts:159` |
 | `workflow_state_invalid` | domain | — | `packages/sdk/src/workflow-errors.ts:82` |
-| `workflow_tool_failed` | domain | WorkflowToolError | `packages/sdk/src/workflow-as-tool.ts:40` +2 |
+| `workflow_tool_failed` | domain | WorkflowToolError | `packages/sdk/src/workflow-as-tool.ts:41` +2 |
 | `ws_global_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:184` |
 | `ws_peer_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/internal/ws-adapter-node.ts:48` |
 | `ws_transport_mismatch` | domain | SubscriptionError | `packages/sdk/src/subscription/internal/server-integration.ts:351` |
-| `zod_not_installed` | domain | ConfigurationError | `packages/sdk/src/internal/structured-output-helpers.ts:33` +1 |
+| `zod_not_installed` | domain | ConfigurationError | `packages/sdk/src/internal/structured-output-helpers.ts:40` +1 |