@theokit/sdk 5.11.1 → 5.12.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 5.12.0
+
+### Minor Changes
+
+- [#763](https://github.com/usetheokit/theokit-sdk/pull/763) [`473616d`](https://github.com/usetheokit/theokit-sdk/commit/473616d2585f11c9c2878a47e17665111279388a) Thanks [@usetheodev](https://github.com/usetheodev)! - `@theokit/acp` and `@theokit/sdk-handoff` keep answering in their protocol when the consumer's agent was created with `throwOnError: true`. When a failed run's `run.wait()` rejects, the ACP handler picks the stop reason from the rejected error's own canonical code (`metadata.code`, else `code`), and the handoff dispatcher replies with `(Handoff target <id> returned status=error: <message>)` using the error's message. This is close to what a resolved error run produces, but not identical: when the run's detail code came from another writer (`agent_loop_failed`, for instance), the error's own code and message are used instead. Any rejection from a run whose status is not `"error"`, such as an abort or an output-processor failure on a finished run, propagates unchanged.
+  
+  `@theokit/sdk`: a failed run's `result.error.cause` is now always a `TheokitAgentError`, and `RunErrorDetail.cause` is typed that way. A failure with no SDK error behind it (a budget denial, the iteration limit, a hook, a cloud run failure, a non-SDK exception) carries an `UnknownAgentError` with the run's message and code, holding the original value at its own `cause`. `result.error.message` and `result.error.code` are unchanged.
+  
+  `AgentOptions.throwOnError` now reaches the run itself, as its doc comment promised. `run.wait()` rejects with `result.error.cause`, and so do `agent.generate`, `agent.fork` and `agent.runToCompletion`. `agent.runUntil` and `agent.streamToCompletion` throw it from their iterator, and `Agent.batch` returns it as the failed item's `error`. A workflow `agentStep`, a cron task and an `Eval` row keep recording the failure, now with the typed error's class name, code or message. `Agent.prompt` still rejects with `AgentRunError`, whose `cause` is the typed error. Cancelled and finished runs still resolve, the `postRun` hook still fires on a failed run, and a run nobody awaits raises no unhandled rejection.
+
+### Patch Changes
+
+- [#751](https://github.com/usetheokit/theokit-sdk/pull/751) [`eb80ccd`](https://github.com/usetheokit/theokit-sdk/commit/eb80ccda362b0783e21b3ac24ccab4aa262985b5) Thanks [@usetheodev](https://github.com/usetheodev)! - A `BudgetTracker` whose `track()` throws no longer loses the turn's other event, and the failure is
+  reported. The agent loop used to call `track()` for the input and the output events inside one `try`
+  with an empty `catch`. An input event that threw skipped the output event, and nothing said so, so a
+  `maxTokens` or USD ceiling counted less than the run spent. Each event now gets its own call, and a
+  throw is reported through the diagnostics sink, or on stderr when no sink is installed. The message
+  names the event type, the model id, the token count and the error. The turn still finishes.
+
+- [#751](https://github.com/usetheokit/theokit-sdk/pull/751) [`3547789`](https://github.com/usetheokit/theokit-sdk/commit/35477896d43d8e61f75f0a797556af8bba6bde88) Thanks [@usetheodev](https://github.com/usetheodev)! - A chat-completions stream whose usage carries a negative, non-finite or non-numeric `prompt_tokens`, `cached_tokens` or cache-write count no longer reports that count as 0. The field is left out of the turn's usage and the SDK writes `provider reported an unusable inputTokens (…)` (or `cacheReadTokens`, `cacheWriteTokens`) to the diagnostics sink, as it already did for every other malformed count, so a proxy sending a broken usage object is no longer billed and budgeted as a turn with no input. `normalizeUsage` still reads such a count as 0. (B-412)
+
+- [#764](https://github.com/usetheokit/theokit-sdk/pull/764) [`cc5c001`](https://github.com/usetheokit/theokit-sdk/commit/cc5c0011555b56857c1f75f521d2883b470ce0af) Thanks [@usetheodev](https://github.com/usetheodev)! - A `thinking` entry in `model.params` with an empty value is now refused instead of silently
+  turning reasoning off. `Agent.create` and a `send` model override throw a `ConfigurationError` with
+  code `invalid_model_param` before any request when the `thinking` value is empty, whitespace only,
+  missing or not a string, and the message names the param. It used to be accepted, and the chat
+  request went out with neither `reasoning_effort` nor `reasoning`, so a UI filling the value from an
+  unset setting lost reasoning with no signal. To request no reasoning, leave the `thinking` param
+  out. A non-empty value such as `"high"` is forwarded as before.
+
+- [#765](https://github.com/usetheokit/theokit-sdk/pull/765) [`6bb4105`](https://github.com/usetheokit/theokit-sdk/commit/6bb410578b631d8db9fb1caf68fab8952f588091) Thanks [@usetheodev](https://github.com/usetheodev)! - A provider error's `metadata.raw` no longer carries the start of a credential that sat across the
+  2048-character cut. The body used to be cut first and redacted after, so a key cut short of the
+  length its pattern needs matched nothing: 12 characters of an `sk-` key, or the key lines of a PEM
+  block before the cut, reached `metadata.raw` in clear. The whole body is now redacted and the
+  redacted text is cut. Two visible differences follow. A body that redaction shrinks to 2048
+  characters or fewer comes back whole, with no `…`. And when the text is still longer, the cut can
+  fall inside a mask such as `sk-V2w...y5Z6`, which leaves part of the mask and never more of the key
+  than the mask itself shows. Redaction reads the whole body, however long, because any bound on
+  what it reads would leave a credential cut by that bound in clear. A pattern registered with
+  `Security.addPattern` now sees the whole error body, not the first 2048 characters, so it should
+  stay linear in its input. The cut also no longer splits a surrogate pair, such as an emoji, at the
+  2048th character.
+
+- [#752](https://github.com/usetheokit/theokit-sdk/pull/752) [`cd6dc55`](https://github.com/usetheokit/theokit-sdk/commit/cd6dc555272002965e620267472a09d12d6d49f0) Thanks [@usetheodev](https://github.com/usetheodev)! - An OpenAI-compatible provider's HTTP 400 now ends the run with a `ConfigurationError` whose message says what the provider rejected. OpenRouter answers a model id it does not know with `nosuchvendor/nosuch-model-xyz is not a valid model ID`, and until now the message was only `openrouter API error: invalid_request (HTTP 400)`, so neither the error nor `result.error.message` named the model or the parameter. The 400 message now ends with the provider's `error.message`, for example `openrouter API error: invalid_request (HTTP 400): Expected max_tokens to be at least 1`. The class, the error `code` and `isRetryable` do not change.
+  
+  The provider's text goes through the same secret redaction as `metadata.raw` and is cut at 512 characters, ending with `…` when it is longer. The missing-model 404 message, which already carried the provider's text, gets the same redaction and cap. Every other status (401, 403, 408, 429, 5xx and the rest) keeps its message as it was. Code that compared a 400 message by equality will now see a longer string.
+
+- [#753](https://github.com/usetheokit/theokit-sdk/pull/753) [`38ad578`](https://github.com/usetheokit/theokit-sdk/commit/38ad578a4025c66c6b250810164a27c10563ba4b) Thanks [@usetheodev](https://github.com/usetheodev)! - `Security.redact` (and `redactSecrets` on the `@theokit/sdk/internal/security` subpath) no longer
+  blocks the event loop on a long run of `eyJ` it cannot complete as a JWT. The JWT pattern was a regex
+  that retried from every `eyJ` of such a run, so its time grew with the square of the run: 224000
+  characters of `eyJa` took over two minutes, and a string half filled by that run 20 to 40 seconds.
+  Callers that redact unbounded text, such as the session transcript, span attributes or a provider
+  error body, stalled for that long. JWTs are now found by a scan that reads each run of characters at
+  most three times, and the same inputs return in under 100 ms. What gets masked, and how, is
+  unchanged.
+
+- [#754](https://github.com/usetheokit/theokit-sdk/pull/754) [`c46f6a4`](https://github.com/usetheokit/theokit-sdk/commit/c46f6a40e700d154ea10dc7c820ee7a33f2c3fb4) Thanks [@usetheodev](https://github.com/usetheodev)! - `redactSecrets` no longer stalls on text that holds many PEM `BEGIN ... PRIVATE KEY` headers with no matching `END` header. Such input used to take seconds for a few hundred KB, because the PEM pattern searched to the end of the string once per header; PEM blocks are now found in one linear pass, so the same input takes milliseconds. What gets masked is unchanged.
+
+- [#751](https://github.com/usetheokit/theokit-sdk/pull/751) [`eb80ccd`](https://github.com/usetheokit/theokit-sdk/commit/eb80ccda362b0783e21b3ac24ccab4aa262985b5) Thanks [@usetheodev](https://github.com/usetheodev)! - On the OpenAI Responses API, `usage.inputTokens` is now the uncached part of the prompt, as it
+  already was on the Anthropic and Chat Completions clients. The client used to pass `input_tokens`
+  through as it came, and that total already includes the cache read and cache write buckets. A turn
+  that hit the prompt cache therefore counted its cached tokens twice: once in `inputTokens` and once
+  in `cacheReadTokens` / `cacheWriteTokens`.
+  
+  Things a caller can observe on a cached turn through a provider whose `apiMode` is
+  `"responses_api"`, the built-in `openai-chatgpt` (Codex) provider among them:
+  
+  - `RunResult.usage.inputTokens`, the `inputTokens` attribute of the `llm.call` span and the
+    `theokit_llm_tokens` histogram are lower by the cached tokens.
+  - The run's computed cost no longer bills the cached tokens a second time at the full input
+    price.
+  - A `BudgetTracker` input event carries the prompt once, so a `maxTokens` ceiling no longer trips
+    early. A USD tracker still prices the cached tokens of that event at the input rate, so it trips
+    less early than before but still early. For a prompt of 11 tokens with 3 read from the cache and
+    5 written to it, the event reports 11, where it reported 19 before.
+
+- [#767](https://github.com/usetheokit/theokit-sdk/pull/767) [`5696d56`](https://github.com/usetheokit/theokit-sdk/commit/5696d567fe34229a70ebf9f1c6df82e1dc289ae1) Thanks [@usetheodev](https://github.com/usetheodev)! - The unknown-provider error lists the registered provider names in locale order instead of UTF-16 code
+  unit order, so a mixed-case name such as `alpha` is no longer listed after `Zeta`. Builtin names are
+  lowercase ASCII, so their order does not change.
+
+- [#764](https://github.com/usetheokit/theokit-sdk/pull/764) [`ce11001`](https://github.com/usetheokit/theokit-sdk/commit/ce110011cbff61ac4381ae4b040af295debc9989) Thanks [@usetheodev](https://github.com/usetheodev)! - A `model.params` entry with id `reasoning` or `reasoning_effort` no longer switches off
+  `reasoning: true`. Only `thinking` is sent to the provider as a reasoning effort, so these two ids
+  used to count as native reasoning without being forwarded: the run got neither the provider effort
+  nor the reasoning preamble and `think` tool, and no error. `reasoning: true` now applies to such a
+  model. To request native reasoning, use `{ id: "thinking", value: "high" }`.
+
+- [#760](https://github.com/usetheokit/theokit-sdk/pull/760) [`67390b6`](https://github.com/usetheokit/theokit-sdk/commit/67390b65bc3af25082dabc02d8d53a9f5c286349) Thanks [@usetheodev](https://github.com/usetheodev)! - When a route's provider names no registered profile and no fallback provider resolves, the run now fails with a message that says so. With `providers.routes: [{ capability: "chat", provider: "no-such-provider" }]`, the run used to end with a `ConfigurationError` telling you to set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` / `OPENROUTER_API_KEY`, even when a key was set. The message now reads `No provider client could be resolved: "no-such-provider" is not a known provider. Registered providers: …`, with the registered names sorted. A provider that a plugin registered is listed too. A provider registered with uppercase letters (for example `AcmeAI`) cannot be routed to, because routes look provider names up in lowercase; the message now says that and names the lowercase spelling to register, instead of calling the name unknown while listing it. An alias registered with uppercase letters gets the same message, naming the provider it belongs to. The class (`ConfigurationError`), the code (`provider_unresolved`) and the opening phrase `No provider client could be resolved` are unchanged, and a registered provider with no key still gets the credentials message, word for word. An unregistered provider next to a fallback that resolves still runs on the fallback, as before.
+
 ## 5.11.1
 
 ### Patch Changes

package/dist/a2a/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkJW3GVLM6_cjs = require('../chunk-JW3GVLM6.cjs');
+var chunkH7HD6RXO_cjs = require('../chunk-H7HD6RXO.cjs');
 require('../chunk-NINIJCHU.cjs');
-var chunkUNFBHV46_cjs = require('../chunk-UNFBHV46.cjs');
-var chunk6LHQPOMI_cjs = require('../chunk-6LHQPOMI.cjs');
+var chunkCEGU5AVD_cjs = require('../chunk-CEGU5AVD.cjs');
+var chunkRNXXYF22_cjs = require('../chunk-RNXXYF22.cjs');
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {
@@ -35,7 +35,7 @@ var AgentMailbox = class {
 };
 
 // src/a2a/message-bus.ts
-var A2APeerNotRegisteredError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
+var A2APeerNotRegisteredError = class extends chunkCEGU5AVD_cjs.TheokitAgentError {
   constructor(to) {
     super(`Agent "${to}" not registered on MessageBus`, {
       code: "a2a_peer_not_registered",
@@ -47,7 +47,7 @@ var A2APeerNotRegisteredError = class extends chunkUNFBHV46_cjs.TheokitAgentErro
   name = "A2APeerNotRegisteredError";
   code = "a2a_peer_not_registered";
 };
-var A2ARequestTimeoutError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
+var A2ARequestTimeoutError = class extends chunkCEGU5AVD_cjs.TheokitAgentError {
   constructor(to, timeoutMs) {
     super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {
       code: "a2a_request_timeout",
@@ -84,7 +84,7 @@ var MessageBus = class {
     };
     void Promise.resolve(handler(message)).catch((cause) => {
       const reason = cause instanceof Error ? cause.message : String(cause);
-      chunk6LHQPOMI_cjs.diag(`[theokit-sdk] a2a: handler for "${to}" failed on a fire-and-forget send: ${reason}
+      chunkRNXXYF22_cjs.diag(`[theokit-sdk] a2a: handler for "${to}" failed on a fire-and-forget send: ${reason}
 `);
     });
   }
@@ -124,11 +124,11 @@ var MessageBus = class {
 
 Object.defineProperty(exports, "MaxDelegationDepthError", {
   enumerable: true,
-  get: function () { return chunkJW3GVLM6_cjs.MaxDelegationDepthError; }
+  get: function () { return chunkH7HD6RXO_cjs.MaxDelegationDepthError; }
 });
 Object.defineProperty(exports, "SubAgent", {
   enumerable: true,
-  get: function () { return chunkJW3GVLM6_cjs.SubAgent; }
+  get: function () { return chunkH7HD6RXO_cjs.SubAgent; }
 });
 exports.A2APeerNotRegisteredError = A2APeerNotRegisteredError;
 exports.A2ARequestTimeoutError = A2ARequestTimeoutError;

package/dist/a2a/index.js

@@ -1,7 +1,7 @@
-export { MaxDelegationDepthError, SubAgent } from '../chunk-XCQ432OX.js';
+export { MaxDelegationDepthError, SubAgent } from '../chunk-VZGE7NAI.js';
 import '../chunk-6X6ID4MO.js';
-import { TheokitAgentError } from '../chunk-B5MHRQJZ.js';
-import { diag } from '../chunk-CZJ6Q7CW.js';
+import { TheokitAgentError } from '../chunk-TNFOU6SB.js';
+import { diag } from '../chunk-3OY6H3I7.js';
 
 // src/a2a/agent-mailbox.ts
 var AgentMailbox = class {

package/dist/agent-BVKIUP7F.cjs

@@ -0,0 +1,71 @@
+'use strict';
+
+var chunkQ6WT5535_cjs = require('./chunk-Q6WT5535.cjs');
+require('./chunk-L7JPXZ2C.cjs');
+require('./chunk-YOVZMN4P.cjs');
+require('./chunk-BUUUWQMB.cjs');
+require('./chunk-CWQPQTUZ.cjs');
+require('./chunk-7YUPSBDV.cjs');
+require('./chunk-BV2MWEMV.cjs');
+require('./chunk-CGH4BCIY.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-RS7YQR4X.cjs');
+require('./chunk-SDZ4XDWS.cjs');
+require('./chunk-6OCJWGVD.cjs');
+require('./chunk-LSWHDOCL.cjs');
+require('./chunk-SXH37C7X.cjs');
+require('./chunk-YJNYDJ2T.cjs');
+require('./chunk-NP362THY.cjs');
+require('./chunk-QOGNZMHD.cjs');
+require('./chunk-MSW7LB2V.cjs');
+require('./chunk-2ZPEDVLM.cjs');
+require('./chunk-QG4SXZ2A.cjs');
+require('./chunk-UDAKAE4Z.cjs');
+require('./chunk-KRD3GQAA.cjs');
+require('./chunk-3HA7N2BB.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-YSTXFWQE.cjs');
+require('./chunk-FRITRLZQ.cjs');
+require('./chunk-H7HD6RXO.cjs');
+require('./chunk-NINIJCHU.cjs');
+require('./chunk-7WARNHWW.cjs');
+require('./chunk-SWALPLFQ.cjs');
+require('./chunk-IJ7M6GOG.cjs');
+require('./chunk-3KIUY67P.cjs');
+require('./chunk-SA6K24NB.cjs');
+require('./chunk-27V5I2WW.cjs');
+require('./chunk-FLDMPVUC.cjs');
+require('./chunk-EQ5IDL6W.cjs');
+require('./chunk-3WKWBYPO.cjs');
+require('./chunk-A4RAL2ER.cjs');
+require('./chunk-AT2PESXB.cjs');
+require('./chunk-POBZXULR.cjs');
+require('./chunk-G7XBVM3T.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-BWYC7RZG.cjs');
+require('./chunk-ZOFRNNZD.cjs');
+require('./chunk-WDVG5R2Q.cjs');
+require('./chunk-YQ3XC6C2.cjs');
+require('./chunk-6XQLTQB6.cjs');
+require('./chunk-KX5QXLBS.cjs');
+require('./chunk-NWWTYBD3.cjs');
+require('./chunk-3EE6LVWT.cjs');
+require('./chunk-LO6LIUZ6.cjs');
+require('./chunk-S46WJTDL.cjs');
+require('./chunk-NVXXWAU7.cjs');
+require('./chunk-5A4UFBHW.cjs');
+require('./chunk-QISSETTG.cjs');
+require('./chunk-IOFMRS6T.cjs');
+require('./chunk-EHD25JBZ.cjs');
+require('./chunk-CEGU5AVD.cjs');
+require('./chunk-RNXXYF22.cjs');
+
+
+
+Object.defineProperty(exports, "Agent", {
+  enumerable: true,
+  get: function () { return chunkQ6WT5535_cjs.Agent; }
+});
+//# sourceMappingURL=agent-BVKIUP7F.cjs.map
+//# sourceMappingURL=agent-BVKIUP7F.cjs.map

package/dist/{agent-OKP4LHG2.cjs.map → agent-BVKIUP7F.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-OKP4LHG2.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-BVKIUP7F.cjs"}

package/dist/{agent-CmKwSyyD.d.ts → agent-CVzDy_Oj.d.ts}

@@ -1,5 +1,5 @@
-import { o as MemoryFact, l as MemoryAdapter, n as MemoryContext, H as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-wEOLXD3F.js';
-import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-DsA5Ip2i.js';
+import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aU as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-CTOJlWA_.js';
+import { M as ModelSelection, C as CustomTool, P as PermissionMode } from './agent-prims-CZyxfCmS.js';
 
 /**
  * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
@@ -1559,11 +1559,20 @@ 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).
      *
@@ -1678,7 +1687,7 @@ 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/{agent-XMkGzff_.d.cts → agent-Cn0sphpA.d.cts}

@@ -1,5 +1,5 @@
-import { o as MemoryFact, l as MemoryAdapter, n as MemoryContext, H as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-dNwjwCt5.cjs';
-import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-DsA5Ip2i.cjs';
+import { W as MemoryFact, T as MemoryAdapter, V as MemoryContext, aU as SystemPromptSkillRef, M as McpServerConfig, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, c as Processor, S as SDKAgent } from './sdk-agent-4-dXI2GS.cjs';
+import { M as ModelSelection, C as CustomTool, P as PermissionMode } from './agent-prims-CZyxfCmS.cjs';
 
 /**
  * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
@@ -1559,11 +1559,20 @@ 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).
      *
@@ -1678,7 +1687,7 @@ 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/agent-IG7BP6GN.js

@@ -0,0 +1,62 @@
+export { Agent } from './chunk-BJ7BPLQK.js';
+import './chunk-HWMGR3HA.js';
+import './chunk-4GUFNDZR.js';
+import './chunk-K2BQQ445.js';
+import './chunk-2C24NSNV.js';
+import './chunk-HJ2LV464.js';
+import './chunk-2SFBB54R.js';
+import './chunk-H7G65PNI.js';
+import './chunk-H73MEMQB.js';
+import './chunk-QK2ERTO3.js';
+import './chunk-DF77RBF4.js';
+import './chunk-AB4OPJLD.js';
+import './chunk-XJ4C4NFX.js';
+import './chunk-5AR6O7GW.js';
+import './chunk-2XC6KDJM.js';
+import './chunk-ZJAYFSVI.js';
+import './chunk-24MGQDK3.js';
+import './chunk-AGO5S5WD.js';
+import './chunk-HKCKOAIO.js';
+import './chunk-KCM3RMKR.js';
+import './chunk-XJ3WU5CZ.js';
+import './chunk-KVNWIAO4.js';
+import './chunk-OLJOI4LK.js';
+import './chunk-FD2UT76F.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-FJWQP6EE.js';
+import './chunk-NAF4L3T6.js';
+import './chunk-VZGE7NAI.js';
+import './chunk-6X6ID4MO.js';
+import './chunk-NHOEXFZT.js';
+import './chunk-4QCJAJAG.js';
+import './chunk-SAGRF4IB.js';
+import './chunk-PKRPV3R7.js';
+import './chunk-UKMBRMGT.js';
+import './chunk-ORLTGPOS.js';
+import './chunk-AHKS3DKI.js';
+import './chunk-5IRDK5BC.js';
+import './chunk-XESYJ4JC.js';
+import './chunk-WE22OXQA.js';
+import './chunk-MLJDW2YK.js';
+import './chunk-KU5O7WPK.js';
+import './chunk-354F3OF5.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-MLGETTYX.js';
+import './chunk-M4U24U6G.js';
+import './chunk-RN3XDZGS.js';
+import './chunk-YMVTUV5K.js';
+import './chunk-Q7UG242V.js';
+import './chunk-SZQFCHU6.js';
+import './chunk-2SFLLOMN.js';
+import './chunk-R7WIIPUR.js';
+import './chunk-NKQVLWDF.js';
+import './chunk-5HSMH2ZZ.js';
+import './chunk-AGACYRJ2.js';
+import './chunk-3FSBE4PS.js';
+import './chunk-MS3TQSXU.js';
+import './chunk-5IUDICRK.js';
+import './chunk-Q7GYMXVC.js';
+import './chunk-TNFOU6SB.js';
+import './chunk-3OY6H3I7.js';
+//# sourceMappingURL=agent-IG7BP6GN.js.map
+//# sourceMappingURL=agent-IG7BP6GN.js.map

package/dist/{agent-DFV52V6E.js.map → agent-IG7BP6GN.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-DFV52V6E.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-IG7BP6GN.js"}

package/dist/agent-prims-CZyxfCmS.d.cts

@@ -0,0 +1,206 @@
+/**
+ * Owner: `src/` (2 of 7 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Leaf module for content-block types shared by `messages.ts` (assistant/user
+ * content) and `agent-prims.ts` (`CustomTool` handler results). Kept
+ * import-free so both can depend on it WITHOUT the `agent-prims ↔ messages`
+ * cycle (#7).
+ *
+ * @public
+ */
+/**
+ * Plain text content block emitted by the assistant or user, or returned by a
+ * tool.
+ *
+ * @public
+ */
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+/**
+ * SE7 — a base64-encoded image block a tool can hand back as (part of) its
+ * result or its `ToolError`. `media_type` is a MIME type (e.g. `"image/png"`);
+ * `data` is the base64 payload without a data-URL prefix.
+ *
+ * Note: when a tool builds this from model- or user-influenced input, treat
+ * `media_type` as UNTRUSTED — validate/allow-list it before rendering it in a
+ * log or UI (it could carry newlines / control chars). The SDK only forwards it
+ * (JSON-serialized onto the wire) and never executes or path-joins it.
+ *
+ * @public
+ */
+interface ImageBlock {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+}
+/**
+ * SE7 — structured content a tool result may carry: text and/or images. A tool
+ * `handler` may return this (success) and a `ToolError` may carry it (failure).
+ * Block-capable provider wires forward it natively; string-only provider wires
+ * flatten text and fail fast on an image.
+ *
+ * @public
+ */
+type ToolResultContentBlock = TextBlock | ImageBlock;
+
+/**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
+ * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
+ * (audit `architecture-output/final_report.md`) per plan
+ * arch-review-fixes-2026-06-06 § Phase 4 / T4.1 (D438).
+ *
+ * Public surface unchanged — `types/agent.ts` re-exports these from this
+ * leaf so `import type { ModelSelection, CustomTool } from "@theokit/sdk"`
+ * keeps resolving.
+ *
+ * @public
+ */
+/**
+ * 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
+ */
+interface ModelParameterValue {
+    id: string;
+    value: string;
+}
+/**
+ * Identifies a model plus optional per-model parameters (e.g. reasoning effort).
+ *
+ * Use `Theokit.models.list()` to discover valid ids and parameter definitions.
+ *
+ * @public
+ */
+interface ModelSelection {
+    id: string;
+    params?: ModelParameterValue[];
+    /**
+     * M94 — the model's context window, in tokens. Becomes the window resolver's `override`.
+     *
+     * It exists for models with NO catalog entry: without it, a 400k model was budgeted against the
+     * 128k floor and compacted ~3x more than it needed to. A value above what the catalog knows is
+     * clamped — declaring 10M does not blow past the provider.
+     */
+    contextWindow?: number;
+    /**
+     * #332 — the endpoint THIS model should reach, for OpenAI-compatible and local servers.
+     *
+     * Without it the base URL came only from a process-wide env var (`OLLAMA_HOST`) or the provider
+     * profile's shipped default, so every `ollama/*` model in a process shared one host — an app
+     * could not run a small model on localhost and a large one on a GPU box.
+     *
+     * It outranks the env var deliberately: with the env var winning, whoever set it for one model
+     * would keep hijacking every other one, which is the same bug wearing a hat.
+     *
+     * Leaving it unset keeps the zero-config path exactly as it was — `ollama/qwen2.5:3b` still
+     * resolves to `http://localhost:11434` from the profile, with no key and no setup.
+     */
+    url?: string;
+}
+/**
+ * SE12 — a read-only, text-only projection of one turn of the run's conversation,
+ * exposed to a tool handler via `ctx.messages`. Content is flattened to text; tool
+ * calls / results and non-text parts are dropped, and turns that project to empty
+ * text are omitted. Consumed by `defineSubAgent`'s `messageFilter` to forward
+ * (a subset of) the supervisor transcript to a subagent.
+ *
+ * `role` includes `"system"` for type-completeness with the wire message shape,
+ * but the system prompt travels on a separate request field — a `"system"` entry
+ * does NOT appear in the current projection.
+ *
+ * @public
+ */
+interface ToolContextMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * Local function tool declared per-agent via {@link AgentOptions.tools}. The
+ * handler runs in-process; no MCP server is involved. The SDK serializes
+ * `name`, `description`, and `inputSchema` into the model's tool catalog.
+ *
+ * Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
+ * persisted. The tool catalog (name + description + schema) is NOT serialized.
+ *
+ * @public
+ */
+interface CustomTool {
+    /**
+     * Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`
+     * and must not collide with `shell`, `memory_search`, `memory_get`, or any
+     * `mcp_*` prefix (reserved for the SDK's built-in tools).
+     */
+    name: string;
+    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
+    description: string;
+    /** JSON Schema (Draft-7 subset) describing the `input` argument. Must be `type: "object"`. */
+    inputSchema: Record<string, unknown>;
+    /**
+     * Local handler invoked when the model emits `tool_use` for this tool.
+     * Returns a string OR structured content blocks (SE7 — text + image, e.g. a
+     * screenshot) that become the `tool_result.content` surfaced back to the
+     * model. Throws → SDK converts to `tool_result` with `isError: true` and the
+     * error `message` as content; throw a `ToolError` to carry a clean message or
+     * multimodal error content. #65 — an optional 2nd `ToolContext` argument
+     * carries the run's `AbortSignal`; single-argument handlers are unaffected. M7
+     * — the same `ctx` also carries an optional user `context` (provided once via
+     * `SendOptions.context`), so shared config like a `projectRoot` is read by
+     * every tool instead of baked into each factory. SE12 — `ctx.messages` is a
+     * read-only, text-only projection of the current turn's transcript (see
+     * {@link ToolContextMessage}); `defineSubAgent`'s `messageFilter` consumes it.
+     * #119 — `ctx.threadId` is the run's session identity (the key passed to
+     * `Agent.getOrCreate(sessionId, …)`, or the agent's own id), so a stateful tool
+     * shared across sessions can scope its state per session instead of leaking it.
+     */
+    handler: (input: Record<string, unknown>, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        messages?: readonly ToolContextMessage[];
+        threadId?: string;
+    }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
+}
+/**
+ * How the permission engine treats the UNMATCHED verdict.
+ *
+ * - `default` — ask.
+ * - `plan` — read-only.
+ * - `acceptEdits` — auto-approve the unmatched verdict, but still honour an explicit `ask` rule.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything allowed EXCEPT an
+ *   explicit `deny`. Never asks.
+ *
+ * G7 / DIP — defined in this type leaf rather than in `permission-engine.ts`, which is a RUNTIME
+ * module. `types/agent.ts`, `types/run.ts` and `types/plugin.ts` all need the union, and each one
+ * used to reach into the engine for it: three of the nine violations the `types-dont-import-runtime`
+ * rule reported the moment it was able to see type-only edges at all. The engine re-exports it, so
+ * `import type { PermissionMode } from "@theokit/sdk"` is unchanged.
+ *
+ * @public
+ */
+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
+ */
+type RunOperation = "stream" | "wait" | "cancel" | "conversation" | "listArtifacts" | "downloadArtifact" | "runUntil" | "runToCompletion" | "streamToCompletion" | "fork" | "usePersonality" | "workflow";
+
+export type { CustomTool as C, ImageBlock as I, ModelSelection as M, PermissionMode as P, RunOperation as R, ToolResultContentBlock as T, ModelParameterValue as a, TextBlock as b, ToolContextMessage as c };