@theokit/sdk 5.11.1 → 5.12.0

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

@@ -16,6 +16,11 @@
 /**
  * One slot in a {@link ModelSelection.params} array.
  *
+ * The `thinking` param sets the reasoning effort and takes a non-empty value, for example
+ * `{ id: "thinking", value: "high" }`. An empty or whitespace-only value is refused with a
+ * `ConfigurationError` (code `invalid_model_param`) at `Agent.create` and at a `send` override,
+ * before any request. To request no reasoning, leave the `thinking` param out.
+ *
  * @public
  */
 export interface ModelParameterValue {
@@ -135,3 +140,14 @@ export interface CustomTool {
  * @public
  */
 export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+/**
+ * Operations that may or may not be supported on a given `Run`, or on
+ * its parent agent. Kept in this leaf so `errors.ts` can name it without
+ * importing `types/run.ts`, which imports `errors.ts`.
+ *
+ * Runtime-specific availability — query at runtime with `run.supports(op)` and
+ * read the human reason via `run.unsupportedReason(op)`.
+ *
+ * @public
+ */
+export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";

package/dist/types/agent.d.ts

@@ -526,11 +526,20 @@ export interface AgentOptions {
     apiKey?: string;
     name?: string;
     /**
-     * When `true`, `Agent.prompt` (and any helper that goes through `run.wait()`)
-     * rejects with `AgentRunError` instead of resolving with `{ status: 'error' }`.
-     * Cancelled runs (`status: 'cancelled'`) still resolve — cancel ≠ error.
-     * If `result.error` is undefined despite `status: 'error'` (malformed RunResult),
-     * the defensive guard resolves normally (no throw).
+     * When `true`, a failed run is surfaced as an error instead of resolving with
+     * `{ status: 'error' }`. The error is `result.error.cause`, the typed
+     * {@link TheokitAgentError} behind the failure:
+     *
+     * - `run.wait()`, `agent.generate`, `agent.fork` and `agent.runToCompletion`
+     *   reject with it.
+     * - `agent.runUntil` and `agent.streamToCompletion` throw it from their iterator.
+     * - `Agent.batch` returns it as the failed item's `error`.
+     * - A workflow `agentStep`, a cron task and an `Eval` row keep recording the
+     *   failure, with its class name, code or message.
+     * - `Agent.prompt` alone wraps it in `AgentRunError`, whose `cause` is the typed error.
+     *
+     * Cancelled and finished runs still resolve. A run with `status: 'error'` but no
+     * `result.error` (malformed RunResult) also resolves.
      *
      * Default `false` (backwards-compatible).
      *
@@ -645,7 +654,7 @@ export interface AgentOptions {
      * auto-attached, turning a non-reasoning model into a reason -> act ->
      * observe loop (same model; reuses the existing tool loop). Default `false` —
      * byte-identical behaviour when unset. Inert (with a one-time warn) when a
-     * native reasoning model is configured (`model.params: [{ id: "thinking" }]`),
+     * native reasoning model is configured (`model.params: [{ id: "thinking", value: "high" }]`),
      * so native and prompt-based reasoning never stack. See `ReasoningTools` in `@theokit/sdk-tools`.
      */
     reasoning?: boolean;

package/dist/types/run.d.ts

@@ -3,12 +3,14 @@
  * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
  */
-import type { CustomTool, ModelSelection, PermissionMode } from "./agent-prims.js";
+import type { TheokitAgentError } from "../errors.js";
+import type { CustomTool, ModelSelection, PermissionMode, RunOperation } from "./agent-prims.js";
 import type { ConversationStep, ConversationTurn } from "./conversation.js";
 import type { McpServerConfig } from "./mcp.js";
 import type { SDKMessage } from "./messages.js";
 import type { InteractionUpdate } from "./updates.js";
 import type { CostBreakdown, TokenUsage } from "./usage.js";
+export type { RunOperation } from "./agent-prims.js";
 /**
  * Options for the tool-result guard (spotlighting + PII redaction on tool
  * output). Contract type owned by `types/` (SE45 / D435) — the implementation
@@ -28,16 +30,6 @@ export interface ToolResultGuardOptions {
  * @public
  */
 export type RunStatus = "running" | "finished" | "error" | "cancelled";
-/**
- * Operations that may or may not be supported on a given {@link Run}, or on
- * its parent agent.
- *
- * Runtime-specific availability — query at runtime with `run.supports(op)` and
- * read the human reason via `run.unsupportedReason(op)`.
- *
- * @public
- */
-export type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
 /**
  * Git metadata attached to cloud runs.
  *
@@ -268,15 +260,23 @@ export type StreamToCompletionResult = RunToCompletionResult;
  * Structured error attached to a {@link RunResult} when the underlying run
  * transitioned to `"error"` status. `message` is always present; `code` is
  * a stable identifier suitable for branching (e.g. `"llm_4xx"`,
- * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
- * for further inspection when available.
+ * `"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the typed
+ * {@link TheokitAgentError} behind the failure, so `instanceof` works on it
+ * directly (e.g. `result.error?.cause instanceof AuthenticationError`).
+ *
+ * A failure whose original cause was missing or not an SDK error carries an
+ * `UnknownAgentError` with the same message and code, holding the original
+ * value at its own `cause`.
+ *
+ * With `AgentOptions.throwOnError`, `run.wait()` rejects with this same `cause`
+ * instead of resolving.
  *
  * @public
  */
 export interface RunErrorDetail {
     message: string;
     code?: string;
-    cause?: unknown;
+    cause?: TheokitAgentError;
 }
 /**
  * Dimensions of an inline image attachment.

package/dist/workflow.cjs

@@ -1,100 +1,100 @@
 'use strict';
 
-var chunkMPQJE3G4_cjs = require('./chunk-MPQJE3G4.cjs');
-var chunk6PB5AQCY_cjs = require('./chunk-6PB5AQCY.cjs');
+var chunkZWLFHSON_cjs = require('./chunk-ZWLFHSON.cjs');
+var chunkTLVI2OQK_cjs = require('./chunk-TLVI2OQK.cjs');
 require('./chunk-VTYY7XL5.cjs');
 require('./chunk-AA27GEYS.cjs');
-require('./chunk-GM54F4FE.cjs');
+require('./chunk-3KIUY67P.cjs');
 require('./chunk-SA6K24NB.cjs');
-require('./chunk-JLRLCBJ4.cjs');
-require('./chunk-UNFBHV46.cjs');
-require('./chunk-6LHQPOMI.cjs');
+require('./chunk-ZOFRNNZD.cjs');
+require('./chunk-CEGU5AVD.cjs');
+require('./chunk-RNXXYF22.cjs');
 
 
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.Workflow; }
+  get: function () { return chunkZWLFHSON_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.WorkflowBuilder; }
+  get: function () { return chunkZWLFHSON_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.WorkflowToolError; }
+  get: function () { return chunkZWLFHSON_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.agentStep; }
+  get: function () { return chunkZWLFHSON_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.cloneWorkflow; }
+  get: function () { return chunkZWLFHSON_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.fn; }
+  get: function () { return chunkZWLFHSON_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.workflowAsTool; }
+  get: function () { return chunkZWLFHSON_cjs.workflowAsTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkMPQJE3G4_cjs.workflowStep; }
+  get: function () { return chunkZWLFHSON_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowInputError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowNestedError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowOutputError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowParallelError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowResumeStepNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.WorkflowStateError; }
+  get: function () { return chunkTLVI2OQK_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunk6PB5AQCY_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkTLVI2OQK_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, z } from 'zod';
-import { S as SDKAgent } from './sdk-agent-dNwjwCt5.cjs';
-import { t as MessageOrigin, C as CustomTool } from './run-DsA5Ip2i.cjs';
+import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-4-dXI2GS.cjs';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.cjs';
+import { C as CustomTool } from './agent-prims-CZyxfCmS.cjs';
 
 /**
  * Owner: `internal/workflow/` (15 of 19 importers). Derived from the import graph, not declared —

package/dist/workflow.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, z } from 'zod';
-import { S as SDKAgent } from './sdk-agent-wEOLXD3F.js';
-import { t as MessageOrigin, C as CustomTool } from './run-DsA5Ip2i.js';
+import { S as SDKAgent, _ as MessageOrigin } from './sdk-agent-CTOJlWA_.js';
 import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
+import { C as CustomTool } from './agent-prims-CZyxfCmS.js';
 
 /**
  * Owner: `internal/workflow/` (15 of 19 importers). Derived from the import graph, not declared —

package/dist/workflow.js

@@ -1,11 +1,11 @@
-export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep } from './chunk-MU7IAA7G.js';
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-HV4V63CO.js';
+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';
 import './chunk-HY66GLM6.js';
 import './chunk-7I5Z3UBJ.js';
-import './chunk-5DD4NJN3.js';
+import './chunk-PKRPV3R7.js';
 import './chunk-UKMBRMGT.js';
-import './chunk-3JHIFQ4I.js';
-import './chunk-B5MHRQJZ.js';
-import './chunk-CZJ6Q7CW.js';
+import './chunk-M4U24U6G.js';
+import './chunk-TNFOU6SB.js';
+import './chunk-3OY6H3I7.js';
 //# sourceMappingURL=workflow.js.map
 //# sourceMappingURL=workflow.js.map

package/docs/error-codes.md

@@ -6,14 +6,14 @@ 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.
 
-250 distinct code(s).
+251 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
 | `a2a_peer_not_registered` | domain | A2APeerNotRegisteredError | `packages/sdk/src/a2a/message-bus.ts:28` +1 |
 | `a2a_request_timeout` | domain | A2ARequestTimeoutError | `packages/sdk/src/a2a/message-bus.ts:62` +1 |
 | `aborted` | domain | TheokitAgentError | `packages/sdk/src/internal/agent/batch.ts:358` +1 |
-| `agent_disposed` | domain | — | `packages/sdk/src/errors.ts:544` |
+| `agent_disposed` | domain | — | `packages/sdk/src/errors.ts:547` |
 | `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 |
@@ -22,7 +22,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `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` |
-| `artifact_path_traversal` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:287` |
+| `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` |
 | `auth_provider_not_found` | domain | — | `packages/sdk/src/server/auth/errors.ts:34` |
@@ -33,27 +33,27 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `batch_task_failed` | domain | TheokitAgentError | `packages/sdk/src/internal/agent/batch.ts:123` |
 | `batch_task_no_terminal_event` | domain | TheokitAgentError | `packages/sdk/src/internal/agent/batch.ts:185` |
 | `before_complete_failed` | domain | — | `packages/sdk/src/internal/local-agent/local-run.ts:111` |
-| `budget_exceeded` | domain | — | `packages/sdk/src/errors.ts:515` +1 |
-| `budget_op_unsupported` | domain | — | `packages/sdk/src/errors.ts:571` +1 |
+| `budget_exceeded` | domain | — | `packages/sdk/src/errors.ts:518` +1 |
+| `budget_op_unsupported` | domain | — | `packages/sdk/src/errors.ts:574` +1 |
 | `catastrophic_command` | domain | — | `packages/sdk-tools/src/internal/shell-guard.ts:32` |
 | `circuit_open` | domain | NetworkError | `packages/sdk/src/internal/llm/pool-aware-client.ts:106` |
-| `cloud_custom_tools_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:150` +1 |
+| `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_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:417` +2 |
+| `cloud_runtime_pre_release` | domain | ConfigurationError | `packages/sdk/src/agent.ts:419` +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:700` |
+| `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:118` |
+| `content_filtered` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:139` |
 | `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:116` |
+| `context_too_long` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:137` |
 | `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` |
@@ -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:454` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:455` |
 | `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` |
@@ -105,7 +105,8 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `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` |
 | `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:266` |
-| `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:21` |
+| `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_redaction_pattern` | domain | ConfigurationError | `packages/sdk/src/security.ts:84` |
 | `invalid_request` | domain | — | `packages/sdk/src/internal/error-mappers/vertex.ts:53` +1 |
@@ -149,8 +150,8 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `no_api_key` | domain | ConfigurationError | `packages/sdk-tools/src/web-search-brave.ts:50` |
 | `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:653` |
-| `no_tool_call` | domain | — | `packages/sdk/src/errors.ts:653` |
+| `no_text_answer` | domain | — | `packages/sdk/src/errors.ts:656` |
+| `no_tool_call` | domain | — | `packages/sdk/src/errors.ts:656` |
 | `node_ws_invalid_raw` | domain | SubscriptionError | `packages/sdk/src/subscription/internal/ws-adapter-node.ts:107` |
 | `not_found` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:251` +2 |
 | `oauth_bind_failed` | domain | ConfigurationError | `packages/sdk/src/internal/mcp/oauth.ts:226` |
@@ -163,7 +164,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `ollama_model_not_pulled` | domain | ConfigurationError | `packages/sdk/src/internal/error-mappers/ollama.ts:84` |
 | `ollama_unreachable` | domain | ConfigurationError | `packages/sdk/src/internal/error-mappers/ollama.ts:55` +1 |
 | `pagination_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/persistence/pagination.ts:34` |
-| `parse_failed` | domain | — | `packages/sdk/src/errors.ts:653` |
+| `parse_failed` | domain | — | `packages/sdk/src/errors.ts:656` |
 | `path_traversal` | domain | — | `packages/sdk/src/internal/security/path-guard.ts:37` |
 | `permission_enforcement_unavailable` | domain | ConfigurationError | `packages/acp/src/permission-plugin.ts:138` +1 |
 | `permission_rule_invalid` | domain | ConfigurationError | `packages/sdk/src/permission-rules.ts:82` +2 |
@@ -178,15 +179,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:191` |
 | `plugin_missing_manifest` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/plugin-loader/plugins-manager.ts:176` +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:99` +1 |
-| `quota_exceeded` | domain | — | `packages/sdk/src/internal/error-mappers/openai-compatible.ts:127` |
+| `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` |
 | `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:653` |
-| `run_not_found` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:424` |
+| `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 |
@@ -231,16 +232,16 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `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` |
 | `transport_failure` | domain | NetworkError | `packages/sdk/src/internal/llm/transport-error.ts:48` |
-| `transport_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:525` +1 |
+| `transport_unavailable` | domain | ConfigurationError | `packages/sdk/src/internal/llm/router.ts:589` +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:207` +1 |
-| `unknown_artifact` | domain | UnknownAgentError | `packages/sdk/src/internal/cloud-agent/cloud-agent.ts:306` |
+| `unknown_agent` | domain | UnknownAgentError | `packages/sdk/src/agent.ts:209` +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 |
 | `unsafe_filename` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/project-instructions.ts:120` |
 | `unsupported_schema` | domain | ConfigurationError | `packages/sdk/src/schema-normalizer.ts:110` +1 |
-| `upstream_run_failed` | domain | — | `packages/sdk/src/errors.ts:653` |
+| `upstream_run_failed` | domain | — | `packages/sdk/src/errors.ts:656` |
 | `valibot_converter_missing` | domain | ConfigurationError | `packages/sdk/src/schema-normalizer.ts:81` +1 |
 | `work_threw` | domain | — | `packages/sdk/src/internal/task/registry.ts:295` |
 | `workflow_already_committed` | domain | ConfigurationError | `packages/sdk/src/workflow.ts:269` |

package/docs/harness-capability-map.md

@@ -73,7 +73,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `AgentOptions` | interface | Top-level options accepted by `Agent.create()`.  |
 | `AgentPromptResult` | type | Result of a one-shot {@link Agent.prompt } call. |
 | `AgentRegistryOptions` | interface | Knobs for {@link LiveAgentRegistry.configure } .  |
-| `AgentRunError` | class | Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when the option `{ throwOnError: true }` is set and the run terminates with `status: 'error'`.  |
+| `AgentRunError` | class | Thrown by `Agent.prompt` alone when the option `{ throwOnError: true }` is set and the run terminates with `status: 'error'`.  |
 | `AgentRunErrorCode` | type | Back-compat alias of {@link KnownAgentRunErrorCode } .  |
 | `agentStep` | function | Build an `AgentStep`.  |
 | `AgentSubagentDescription` | interface | theokit#123 — one subagent of a registered agent (what theokit-studio calls a workflow).  |
@@ -259,7 +259,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `mkMemoryId` | function | Construct a branded `MemoryId` for an adapter.  |
 | `ModelListItem` | interface | Single model entry in the catalog. |
 | `ModelParameterDefinition` | interface | Per-model parameter definition discovered from `Theokit.models.list()`. |
-| `ModelParameterValue` | interface | One slot in a {@link ModelSelection.params } array. |
+| `ModelParameterValue` | interface | One slot in a {@link ModelSelection.params } array.  |
 | `ModelSelection` | interface | Identifies a model plus optional per-model parameters (e.g.  |
 | `ModelVariant` | interface | Preset variant for a model — pre-filled parameter combinations. |
 | `NetworkError` | class | Service unavailable, timeout, transport-level failure. |
@@ -330,7 +330,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `RunGitInfo` | interface | Git metadata attached to cloud runs. |
 | `runGoalLoop` | function | Run the goal-driven loop (`send → judge → continuation`) over ANY `send → wait` surface.  |
 | `RunMemoryDegradedEvent` | interface | A memory stage failed and the run continued without it.  |
-| `RunOperation` | type | Operations that may or may not be supported on a given {@link Run } , or on its parent agent.  |
+| `RunOperation` | type | Operations that may or may not be supported on a given `Run`, or on its parent agent.  |
 | `RunPermissionDeniedEvent` | interface | A tool call was DENIED before dispatch — by the permission gate/plugin (SE1), an operator file-hook `preToolUse`, or the fork tool-whitelist.  |
 | `RunRateLimitEvent` | interface | The provider returned a rate-limit (HTTP 429); the loop will back off + retry. |
 | `RunResult` | interface | Terminal result of a {@link Run } . |
@@ -961,7 +961,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | Symbol | Kind | Summary |
 |---|---|---|
 | `AgentDisposedError` | class | T1.6 — Thrown when a consumer calls `agent.send()` or any method on an agent that has already been `dispose()`d.  |
-| `AgentRunError` | class | Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when the option `{ throwOnError: true }` is set and the run terminates with `status: 'error'`.  |
+| `AgentRunError` | class | Thrown by `Agent.prompt` alone when the option `{ throwOnError: true }` is set and the run terminates with `status: 'error'`.  |
 | `AgentRunErrorCode` | type | Back-compat alias of {@link KnownAgentRunErrorCode } .  |
 | `AuthenticationError` | class | Invalid API key, not logged in, insufficient permissions. |
 | `BudgetExceededError` | class | Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"` budget would be exceeded by the upcoming LLM call.  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.11.1",
+  "version": "5.12.0",
   "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",

package/dist/agent-DFV52V6E.js

@@ -1,62 +0,0 @@
-export { Agent } from './chunk-MHIBYKWA.js';
-import './chunk-XKMVJ443.js';
-import './chunk-Q34EBNYG.js';
-import './chunk-K2BQQ445.js';
-import './chunk-DPY2M74T.js';
-import './chunk-ZHWKT2NI.js';
-import './chunk-2SFBB54R.js';
-import './chunk-U27XHOEF.js';
-import './chunk-H73MEMQB.js';
-import './chunk-OR6XIWLB.js';
-import './chunk-X3LOJJMO.js';
-import './chunk-IZDDSLL2.js';
-import './chunk-BBJ77S62.js';
-import './chunk-SUVCHX4L.js';
-import './chunk-2XC6KDJM.js';
-import './chunk-JLIRFWUG.js';
-import './chunk-24MGQDK3.js';
-import './chunk-XERM7PDQ.js';
-import './chunk-HKCKOAIO.js';
-import './chunk-7QJYKVP6.js';
-import './chunk-OPAKPEPG.js';
-import './chunk-KVNWIAO4.js';
-import './chunk-SVQIW5RJ.js';
-import './chunk-FD2UT76F.js';
-import './chunk-7I5Z3UBJ.js';
-import './chunk-FJWQP6EE.js';
-import './chunk-NAF4L3T6.js';
-import './chunk-XCQ432OX.js';
-import './chunk-6X6ID4MO.js';
-import './chunk-7HUCU3KK.js';
-import './chunk-4QCJAJAG.js';
-import './chunk-SAGRF4IB.js';
-import './chunk-5DD4NJN3.js';
-import './chunk-UKMBRMGT.js';
-import './chunk-7JAKO3NM.js';
-import './chunk-ZWFTECOE.js';
-import './chunk-GTX6FEDP.js';
-import './chunk-FTZTZBCU.js';
-import './chunk-WE22OXQA.js';
-import './chunk-XZHJYSPB.js';
-import './chunk-7KIN3L2S.js';
-import './chunk-RGQICWFU.js';
-import './chunk-Q5EWJPRY.js';
-import './chunk-GGRPAQ3B.js';
-import './chunk-3JHIFQ4I.js';
-import './chunk-ZDYDBXSD.js';
-import './chunk-X7EUUHXU.js';
-import './chunk-MQGSOKR3.js';
-import './chunk-GMRFAX4I.js';
-import './chunk-LZJXEPEQ.js';
-import './chunk-R7WIIPUR.js';
-import './chunk-I2ORT6QD.js';
-import './chunk-SVCPJRUB.js';
-import './chunk-AGACYRJ2.js';
-import './chunk-TX56N7FR.js';
-import './chunk-5Q4RTLMP.js';
-import './chunk-H3CVJSFC.js';
-import './chunk-Q7GYMXVC.js';
-import './chunk-B5MHRQJZ.js';
-import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-DFV52V6E.js.map
-//# sourceMappingURL=agent-DFV52V6E.js.map

package/dist/agent-OKP4LHG2.cjs

@@ -1,71 +0,0 @@
-'use strict';
-
-var chunk35KBC4BX_cjs = require('./chunk-35KBC4BX.cjs');
-require('./chunk-J6GXS5A2.cjs');
-require('./chunk-3JANYJYS.cjs');
-require('./chunk-BUUUWQMB.cjs');
-require('./chunk-L3C6CCBG.cjs');
-require('./chunk-KIKKTW5O.cjs');
-require('./chunk-BV2MWEMV.cjs');
-require('./chunk-JV7JA7BM.cjs');
-require('./chunk-GHX4P3V2.cjs');
-require('./chunk-TMKTSYDS.cjs');
-require('./chunk-ZD66GFH5.cjs');
-require('./chunk-NQVWSSX2.cjs');
-require('./chunk-P5N3Q2NH.cjs');
-require('./chunk-CQYBJOB2.cjs');
-require('./chunk-YJNYDJ2T.cjs');
-require('./chunk-N7KS3TIR.cjs');
-require('./chunk-QOGNZMHD.cjs');
-require('./chunk-ZAM7BJXJ.cjs');
-require('./chunk-2ZPEDVLM.cjs');
-require('./chunk-XKZFIP7Z.cjs');
-require('./chunk-N6OEX5TN.cjs');
-require('./chunk-KRD3GQAA.cjs');
-require('./chunk-RQMCOFAI.cjs');
-require('./chunk-MUUQ2WFJ.cjs');
-require('./chunk-AA27GEYS.cjs');
-require('./chunk-YSTXFWQE.cjs');
-require('./chunk-FRITRLZQ.cjs');
-require('./chunk-JW3GVLM6.cjs');
-require('./chunk-NINIJCHU.cjs');
-require('./chunk-HG5LKFG7.cjs');
-require('./chunk-SWALPLFQ.cjs');
-require('./chunk-IJ7M6GOG.cjs');
-require('./chunk-GM54F4FE.cjs');
-require('./chunk-SA6K24NB.cjs');
-require('./chunk-IIYJMXYW.cjs');
-require('./chunk-NJSIAJEK.cjs');
-require('./chunk-NKIQTLFA.cjs');
-require('./chunk-ZWACQM5U.cjs');
-require('./chunk-A4RAL2ER.cjs');
-require('./chunk-P22BZE7G.cjs');
-require('./chunk-R5YPDAKD.cjs');
-require('./chunk-ASK2OQM5.cjs');
-require('./chunk-ZF2LDKQQ.cjs');
-require('./chunk-GHHIJEFX.cjs');
-require('./chunk-JLRLCBJ4.cjs');
-require('./chunk-C7GKRGKN.cjs');
-require('./chunk-TY56BKSK.cjs');
-require('./chunk-MPR2ISL2.cjs');
-require('./chunk-J5623RIV.cjs');
-require('./chunk-NWS2CS3Y.cjs');
-require('./chunk-3EE6LVWT.cjs');
-require('./chunk-SGC7LSHF.cjs');
-require('./chunk-HU666T3Q.cjs');
-require('./chunk-NVXXWAU7.cjs');
-require('./chunk-SKDNCTXG.cjs');
-require('./chunk-NAGPKWOD.cjs');
-require('./chunk-OLSEWLK5.cjs');
-require('./chunk-EHD25JBZ.cjs');
-require('./chunk-UNFBHV46.cjs');
-require('./chunk-6LHQPOMI.cjs');
-
-
-
-Object.defineProperty(exports, "Agent", {
-  enumerable: true,
-  get: function () { return chunk35KBC4BX_cjs.Agent; }
-});
-//# sourceMappingURL=agent-OKP4LHG2.cjs.map
-//# sourceMappingURL=agent-OKP4LHG2.cjs.map

package/dist/agent-session-store-ODD3IZCW.js

@@ -1,6 +0,0 @@
-export { appendCompactBoundaryRecord, persistTurn, readSessionMessages } from './chunk-XERM7PDQ.js';
-import './chunk-FTZTZBCU.js';
-import './chunk-3JHIFQ4I.js';
-import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-session-store-ODD3IZCW.js.map
-//# sourceMappingURL=agent-session-store-ODD3IZCW.js.map