@theokit/agents 13.0.0-next.9 → 13.1.0

package/dist/setting-sources-gate-DFu51i50.d.ts

@@ -0,0 +1,278 @@
+import { TrustPosture, SettingSource } from '@theokit/sdk';
+import { TheokitAgentError } from '@theokit/sdk/errors';
+
+/**
+ * M68 — the trust gate for `settingSources`.
+ *
+ * ## The defect this module closes
+ *
+ * `settingSources` enables on-disk config discovery. `'user'` reads `~/.theokit/` — the operator's
+ * own machine, which no third party controls. `'project'` reads `<cwd>/.theokit/`, **including
+ * `hooks.json`, which executes shell**.
+ *
+ * The previous API took `readonly SettingSource[]`, and its JSDoc justified the risk this way:
+ * *"it is opt-in because `.theokit/` is the app's own repo (informed consent)"*. That premise holds
+ * for a web app whose `cwd` is its own deploy. It does **not** hold for the class of product this
+ * framework addresses — an agent whose `cwd` is a repository the user just cloned. There `.theokit/`
+ * is attacker-controlled content, and enabling `'project'` is remote code execution on the first
+ * `build()`.
+ *
+ * Documenting it did not prevent it. The measured consumer (TheoCode) did not trust the API: it
+ * gated from the outside, with a `posture.allows` of its own (`chat.ts:386`, comment B-008). It
+ * already **had** the right decision and could not pass it through, because the API only accepted
+ * strings. The gate existed on its side and evaporated at the boundary.
+ *
+ * ## The evidence is the SDK's, not one invented here
+ *
+ * `TrustPosture` is `@theokit/sdk`'s own trust primitive, and `recordWiring`'s doc says *"a posture
+ * is the only thing in this package that retains a capability"*. A bespoke type would make two trust
+ * grammars coexist and drift apart (ADR 0063).
+ */
+/**
+ * The framework's capability vocabulary — deliberately a single name (ADR 0065).
+ *
+ * `allows` is all-or-nothing in the SDK: every declared `K` gets the same boolean. A finer
+ * vocabulary (`hooks`, `skills`, `subagents`, `mcp`) would promise the consumer it can gate one
+ * without gating the other, and the primitive does not deliver that. An API that suggests a
+ * distinction the runtime does not make teaches the wrong thing, and the error only surfaces when
+ * somebody depends on the distinction.
+ */
+type SettingSourceCapability = 'projectSettings';
+/** Authorization to read config from the working directory. Requires the posture, never a claim. */
+interface ProjectSettingsGrant {
+    /**
+     * Typically the output of `resolveTrustPosture` — which is what gives it `source` (`'env' |
+     * 'store' | 'default'`) and therefore a refusal that says WHERE the decision came from instead of
+     * merely denying.
+     */
+    readonly trustedBy: TrustPosture<SettingSourceCapability>;
+}
+/**
+ * Which on-disk config roots the agent may read.
+ *
+ * The asymmetry is the design: `user` is a boolean because `~/.theokit/` belongs to the operator;
+ * `project` requires evidence because `<cwd>/.theokit/` may not. Omitting a root is not enabling it
+ * — never "enabling without a gate". The asymmetry is inherited from the SDK itself, whose
+ * `TrustPostureInput.envOverride` documents that `false` and `undefined` both mean "the operator did
+ * not turn it on", not "turned it off".
+ */
+interface SettingSourcesSelection {
+    /** `~/.theokit/` — the operator's machine. No gate: no third party controls it. */
+    readonly user?: boolean;
+    /** `<cwd>/.theokit/` — controlled by whoever wrote the open repository. Requires evidence. */
+    readonly project?: ProjectSettingsGrant;
+    /**
+     * `<cwd>/.theokit/plugins` and any declared foreign dialect's plugin root — executable bundles.
+     *
+     * Same grant as `project`, deliberately: `PluginsManager.refresh` loads code out of the same
+     * cwd-controlled tree, and the tree usually arrived with the clone.
+     *
+     * Absent from this interface until 2026-09-10, while `includesSetting` reads it
+     * (`local-agent.ts:175`) — so a consumer wanting plugins had to bypass this facade, which is the
+     * door it exists to close. `team` and `mdm` remain absent for the opposite reason: the SDK never
+     * reads them.
+     */
+    readonly plugins?: ProjectSettingsGrant;
+    /**
+     * `<cwd>/.claude/` — a FOREIGN configuration dialect, read only once declared
+     * (`usetheokit/theokit-sdk#524`).
+     *
+     * ## Two questions, and which half of this field answers each
+     *
+     * The SDK's docblock separates them, and the separation is the whole point of `compatSources`:
+     * a trust gate answers *"do I trust the code in this directory?"*; importing another product's
+     * configuration answers *"do I want it imported into this one?"*. They come apart in the ordinary
+     * case, because `.claude/` is populated in exactly the repository one trusts most — for a
+     * different tool, by a teammate who never heard of this runtime.
+     *
+     * So the two are answered by two different things here, and it matters which:
+     *
+     * | Question | Answered by |
+     * |---|---|
+     * | do I want the foreign dialect imported? | **declaring this field at all** — omitting is not enabling |
+     * | do I trust this directory's code to run? | the `TrustPosture` inside the grant |
+     *
+     * ## Why the grant is `ProjectSettingsGrant` and not a vocabulary of its own
+     *
+     * Not because the two questions are the same — they are not. Because a separate grant could not
+     * carry the distinction even if it existed: `TrustPosture.allows` is `Record<K, boolean>` and the
+     * SDK documents every value as moving together with the level, so a `'foreignDialects'` capability
+     * beside `'projectSettings'` would promise an operator they can grant one and withhold the other,
+     * and `resolveTrustPosture` would hand back the same boolean for both. That is precisely the
+     * failure ADR 0065 exists to prevent, and inventing the second name would commit it while looking
+     * like rigour.
+     *
+     * The consent half is therefore carried by the declaration, which is a real and sufficient
+     * boundary: an operator who trusts a repository completely still reads no `.claude/` until they
+     * write this field. What the grant adds on top is stricter than the SDK — there, listing a dialect
+     * is enough — and the extra strictness is deliberate: this reads a `hooks.json` that executes
+     * shell out of a directory that usually arrived with the clone.
+     */
+    readonly claudeCode?: ProjectSettingsGrant & {
+        /**
+         * #686 — WHICH surfaces of the foreign root to import. Absent means all of them, which is what
+         * every caller before this meant and still means.
+         *
+         * The distinction is the reason the grant exists. `.claude/` usually arrives with the clone and
+         * its `hooks.json` executes shell, so "take the skills, refuse the hooks" is the ordinary thing
+         * to want — and before this the only choices were all of it or none of it.
+         *
+         * Requires `@theokit/sdk >= 5.4.0`, which is where the narrowed form landed. On an older SDK the
+         * runtime drops an unrecognised shape in SILENCE, so declaring it there would import nothing at
+         * all rather than importing less — refused at resolve time instead.
+         */
+        readonly import?: readonly CompatSurface[];
+    };
+}
+/**
+ * The surfaces a foreign configuration root can contribute.
+ *
+ * Written out rather than imported, for the same reason as the `claude-code` literal below:
+ * `CompatSurface` does not exist in `@theokit/sdk@4.52.1`, this package's declared floor, and a gate
+ * that cannot build against its own minimum dependency is worse than a constant that has been
+ * checked. Verified against the published 5.4.0 `.d.ts`, where the union is
+ * `"hooks" | "plugins" | "skills" | "subagents"` — note `subagents`, not `agents`.
+ *
+ * The two unions therefore DIVERGE by one name, on purpose: the SDK has four, and `commands` is
+ * this layer's, because `<projectDir>/.claude/commands/*.md` is read here and never by the SDK.
+ * A caller who builds SDK `local` options directly cannot pass a value of this type — `TS2345`,
+ * with a compiler message that names the mismatch and not the reason. Derive the SDK's list from
+ * this one minus `commands` rather than writing four names beside five; a hand-copied list goes
+ * stale the day a surface is added, which is the divergence #704 existed to remove.
+ */
+type CompatSurface = 'commands' | 'hooks' | 'plugins' | 'skills' | 'subagents';
+/** What `resolveCompatSources` returns: the whole root, or the root narrowed to some surfaces. */
+type ResolvedCompatSource = 'claude-code' | {
+    readonly kind: 'claude-code';
+    readonly import: readonly CompatSurface[];
+};
+/**
+ * Refusal to read the working directory for lack of trust.
+ *
+ * Descends from `TheokitAgentError` because typed errors are an unbreakable rule here — and because
+ * `isTransientError` only sees this hierarchy. A class extending plain `Error` would be invisible to
+ * the predicate that separates recoverable from unrecoverable (the defect M67 fixed in five
+ * classes).
+ */
+declare class UntrustedSettingSourceError extends TheokitAgentError {
+    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
+    readonly trustSource: string;
+    /** The refused capability. */
+    readonly capability: SettingSourceCapability;
+    readonly name = "UntrustedSettingSourceError";
+    constructor(message: string, 
+    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
+    trustSource: string, 
+    /** The refused capability. */
+    capability: SettingSourceCapability);
+}
+/**
+ * Translate the declared selection into the `SettingSource`s the SDK accepts, refusing what the
+ * posture does not authorize.
+ *
+ * Refuses rather than ignores (ADR 0064). Ignoring would leave the product running in the belief
+ * that the repository's hooks are active — a silent failure mode, on the wrong side. The SDK already
+ * picked that side for the same problem: `recordWiring` throws `UngatedCapabilityError` when
+ * somebody registers a capability the posture does not gate.
+ *
+ * @throws {UntrustedSettingSourceError} when `project` is requested and the posture does not grant it.
+ */
+declare const GATED: unique symbol;
+/**
+ * A root that some `TrustPosture` authorised — mintable ONLY by {@link resolveSettingSources}.
+ *
+ * ## Why a brand rather than a check
+ *
+ * `define-agent.ts` claimed `CompiledAgentOptions.settingSources` "can only ever hold roots that
+ * some posture authorized". Measured 2026-09-10 against the emitted `.d.ts`:
+ * `setOnce(draft, 'settingSources', ['mdm','team','user','plugins'], 'cap')` typechecked CAST-FREE.
+ * A consumer writing a `Capability` — the documented way to extend the builder — reached the field
+ * directly, and `project`, the root this gate exists to protect, is one of the two the SDK reads.
+ *
+ * The obvious fix was to read `draft.provenance` and refuse a write from a capability. It does not
+ * work, measured: the LEGITIMATE builder path also writes through `setOnce`
+ * (`capability/agent-capabilities.ts:155`), so provenance names a capability either way. What
+ * actually differs is where the VALUE came from, and a brand is a value's provenance carried in its
+ * type.
+ *
+ * ## What it does not do
+ *
+ * `as never` defeats it, like every brand — and so does ANY REFLECTIVE WRITE: `Object.assign`,
+ * `Reflect.set`, `Object.defineProperty`. All three typecheck cast-free, measured, including from
+ * inside a `Capability.apply`. That is a TypeScript-wide hole rather than a design choice here —
+ * those APIs type their value as `any` or return `T & U` without checking `T`'s existing fields.
+ *
+ * Stated as a CLASS and not a list, after two rounds of naming one instance and calling it "the one
+ * named exception". A list of escapes is a list somebody adds to; the property is that reflection
+ * bypasses the type system, and enumerating members of that class understates it every time.
+ *
+ * TEN other routes are refused, and they are refused by a TEST rather than by this sentence:
+ * `tests/type/setting-sources-brand-escapes.test-d.ts` guards each one with a `@ts-expect-error`,
+ * so weakening the brand reports which route reopened instead of passing quietly. `setOnce` with a
+ * raw array, `setOnce` through a generic wrapper, a direct `draft.settingSources =`, a spread of an
+ * array literal, an object literal with `as`, `.concat`, `.map`, spread-widening, `satisfies`,
+ * and `.push`.
+ *
+ * The count said "nine" while the list held ten — the same off-by-one this branch has now made
+ * three times in a docblock. Counting them in a file that fails when the count is wrong is the
+ * point of moving the claim into a test.
+ *
+ * So this refuses the accident — a capability author reaching for the field because it is there —
+ * with the named exceptions above, and not a caller who has decided to bypass the gate. Naming them
+ * exception is the point: the comment this replaced claimed an invariant nothing enforced, and a
+ * replacement that overstated its own coverage would be the same defect one size smaller.
+ *
+ * ## Which roots the SDK actually READS
+ *
+ * `includesSetting` is called with exactly `"project"` and `"plugins"`
+ * (`theokit-sdk/packages/sdk/src/internal/local-agent/local-agent.ts:174-175`). `user`, `team` and
+ * `mdm` are accepted by the option and never consulted, so forwarding them would be a name the
+ * runtime discards. `user` is still resolved here because it costs nothing and the SDK may start
+ * reading it; `team` and `mdm` are deliberately absent from {@link SettingSourcesSelection} rather
+ * than plumbed through to be ignored.
+ */
+type GatedSettingSource = SettingSource & {
+    readonly [GATED]: true;
+};
+/**
+ * A compat source some `TrustPosture` authorised — mintable ONLY by {@link resolveCompatSources}.
+ *
+ * The twin of {@link GatedSettingSource}, and it exists because B-004 branded one of the two fields
+ * one `SettingSourcesSelection` feeds and left the other bare. Measured 2026-09-11, with the
+ * `settingSources` route as the control: the control errored, and
+ * `setOnce(draft, 'compatSources', ['claude-code'], 'cap')` compiled CAST-FREE — while
+ * `agent-compiler.ts` told the reader that field "can only hold a source some posture granted".
+ *
+ * It carries more authority than its twin, not less: `applyLocalSources` forwards it to
+ * `Agent.create({ local: { compatSources } })`, which reads `<cwd>/.claude/` — `hooks.json`
+ * included, and that executes shell. The refusal thrown below spells that out; the brand is what
+ * stops a caller reaching the field without meeting the refusal at all.
+ *
+ * Same `GATED` symbol as the twin, so there is one brand in this module rather than two that must
+ * be kept in step. The escapes are the same CLASS the twin documents — `as never` and any
+ * reflective write — and are not re-listed here.
+ */
+type GatedCompatSource = ResolvedCompatSource & {
+    readonly [GATED]: true;
+};
+declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly GatedSettingSource[];
+/**
+ * The foreign configuration dialects this layer forwards, once the posture authorises them.
+ *
+ * ## Why it is a separate function and the same vocabulary
+ *
+ * Separate because the SDK takes them on a separate option (`local.compatSources`); the same
+ * `ProjectSettingsGrant` because the thing being authorised is identical — reading a `hooks.json`
+ * that executes shell out of a directory the operator does not necessarily control.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * Validate the source NAME. The SDK DROPS an unrecognised name rather than turning it into
+ * `<cwd>/<name>`, so a typo fails closed there; turning that into a throw here would convert a safe
+ * default into a crash. This gate decides authorisation, never vocabulary.
+ *
+ * @throws {UntrustedSettingSourceError} when a source is requested and the posture does not grant it.
+ */
+declare function resolveCompatSources(selection: SettingSourcesSelection | undefined): readonly GatedCompatSource[];
+
+export { type CompatSurface as C, type GatedSettingSource as G, type ProjectSettingsGrant as P, type ResolvedCompatSource as R, type SettingSourcesSelection as S, UntrustedSettingSourceError as U, type GatedCompatSource as a, type SettingSourceCapability as b, resolveSettingSources as c, resolveCompatSources as r };

package/dist/testing.d.ts

@@ -1,11 +1,14 @@
 import { AgentOutputEvent } from '@theokit/presenter';
+export { AgentOutputEvent } from '@theokit/presenter';
 import { WireChunk } from '@theokit/presenter/wire';
-import { A as AgentDefinition } from './define-agent-D9b3h3VU.js';
+import { A as AgentDefinition } from './define-agent-Cm7UGHx-.js';
 import '@theokit/sdk';
 import 'zod';
-import './agent-compiler-DZorqtK2.js';
+import './agent-compiler-B_Z3OZel.js';
+import '@theokit/sdk/subagents-loader';
 import '@theokit/sdk/errors';
 import './types-C16Wuh9E.js';
+import './setting-sources-gate-DFu51i50.js';
 import './hook-handlers-Cw2FsnE5.js';
 
 /**

package/dist/testing.js

@@ -1,6 +1,6 @@
 import {
   compileAgentDefinition
-} from "./chunk-LPS65NGG.js";
+} from "./chunk-PMMOOXR6.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";

package/dist/tools.d.ts

@@ -1,11 +1,13 @@
 export { CatastrophicCommandError, CommandPolicy, ContextMatchError, ContextMatchReason, CreateApplyPatchToolOptions, CreateBraveWebSearchAdapterOptions, CreateCurrentTimeToolOptions, CreateEditFileToolOptions, CreateGenericHttpSearchAdapterOptions, CreateGitDiffToolOptions, CreateGitStatusToolOptions, CreateGlobToolOptions, CreateInteractiveShellToolOptions, CreateListDirToolOptions, CreateReadFileToolOptions, CreateRunVitestToolOptions, CreateSearchTextToolOptions, CreateShellToolOptions, CreateViewImageToolOptions, CreateWebFetchToolOptions, CreateWebSearchToolOptions, CreateWriteFileToolOptions, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_TOOL_GUIDANCE, EnvContextOptions, PlanModeTool, PlanModeToolOptions, PlanModeToolWithStore, PlanNode, QuestionTool, QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, RepoMapOptions, ResolveAndScreenOptions, ScreenedFetchOptions, SessionArtifactStore, SessionArtifactStoreOptions, SsrfBlockedError, TodoItem, TodolistTool, ToolGuidanceMap, TruncationMode, TruncationOptions, TruncationResult, VitestSummary, WebSearchCallback, WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance } from '@theokit/sdk-tools';
 import * as _theokit_sdk from '@theokit/sdk';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-import { D as DelegationTarget, a as DelegateOptions } from './delegation-scoring-MbnqL68u.js';
+import { D as DelegationTarget, a as DelegateOptions } from './delegation-scoring-195_ROT3.js';
 import '@theokit/sdk/retry';
-import './agent-compiler-DZorqtK2.js';
+import './agent-compiler-B_Z3OZel.js';
+import '@theokit/sdk/subagents-loader';
 import './types-C16Wuh9E.js';
 import 'zod';
+import './setting-sources-gate-DFu51i50.js';
 import '@theokit/presenter/wire';
 import './hook-handlers-Cw2FsnE5.js';
 

package/dist/tools.js

@@ -2,11 +2,15 @@ import {
   DelegationBudgetExceededError,
   DelegationError,
   DelegationTimeoutError,
+  GuardrailError,
+  GuardrailViolationError,
   delegate,
   isPort
-} from "./chunk-6WFRR24F.js";
-import "./chunk-RKWCXVYG.js";
-import "./chunk-LPS65NGG.js";
+} from "./chunk-HBHZV3KL.js";
+import "./chunk-MJ6FRILJ.js";
+import "./chunk-PMMOOXR6.js";
+import "./chunk-M5J3Q6YC.js";
+import "./chunk-U72XTMYB.js";
 import "./chunk-OXNDJSAJ.js";
 import {
   __name
@@ -50,9 +54,23 @@ function errorCodeOf(error) {
   if (error instanceof DelegationBudgetExceededError) return "delegation_budget_exceeded";
   if (error instanceof DelegationTimeoutError) return "delegation_timeout";
   if (error instanceof DelegationError) return "delegation_failed";
+  if (error instanceof GuardrailViolationError) return "guardrail_violation";
+  if (error instanceof GuardrailError) return "guardrail_error";
   return void 0;
 }
 __name(errorCodeOf, "errorCodeOf");
+var REFUSED_BY_POLICY = "the delegated task was refused by a policy guard";
+var MESSAGE_MAY_CROSS = /* @__PURE__ */ new Set([
+  // A budget or a timeout is a fact about the WORK, and the number in it is what the model acts on.
+  "delegation_budget_exceeded",
+  "delegation_timeout",
+  "delegation_failed"
+]);
+function messageForModel(code, error) {
+  if (!MESSAGE_MAY_CROSS.has(code)) return REFUSED_BY_POLICY;
+  return error instanceof Error ? error.message : String(error);
+}
+__name(messageForModel, "messageForModel");
 function describeRoster(roster) {
   return roster.map((entry) => entry.name).join(", ");
 }
@@ -93,7 +111,7 @@ function createDelegateTool(options) {
         return JSON.stringify({
           ok: false,
           error: code,
-          message: error instanceof Error ? error.message : String(error)
+          message: messageForModel(code, error)
         });
       }
     }, "handler")

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tools-entry.ts","../src/tools/delegate-tool.ts"],"mappings":"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","names":["buildEnvContext","buildRepoMap","CatastrophicCommandError","catastrophicShellReason","commandDenialReason","ContextMatchError","createApplyPatchTool","createBraveWebSearchAdapter","createCurrentTimeTool","createEditFileTool","createGenericHttpSearchAdapter","createGitDiffTool","createGitStatusTool","createGlobTool","createInteractiveShellTool","createListDirTool","createPlanModeTool","createQuestionTool","createReadFileTool","createRunVitestTool","createSearchTextTool","createSessionArtifactStore","createShellTool","createTodolistTool","createUpdatePlanTool","createViewImageTool","createWebFetchTool","createWebSearchTool","createWriteFileTool","createWriteStdinTool","DEFAULT_MAX_IMAGE_BYTES","DEFAULT_TOOL_GUIDANCE","denyCatastrophicCommands","formatCode","formatDiff","formatError","formatFileList","injectGuidance","isBlockedIp","isCommandAllowed","ReadTracker","ReasoningTools","RedirectBlockedError","renderToolList","replaceUnique","resolveAndScreen","screenedFetch","SsrfBlockedError","todoItemsToPlanNodes","truncateOutput","withDefaultGuidance","withDescription","withName","withShellExitGuidance","withToolResultGuidance","Tool","TheokitAgentError","z","DelegateToolConfigError","TheokitAgentError","name","message","code","assertUsableRoster","roster","defaults","length","seen","Set","has","JSON","stringify","add","needsCredential","some","entry","isPort","target","apiKey","errorCodeOf","error","DelegationBudgetExceededError","DelegationTimeoutError","DelegationError","undefined","describeRoster","map","join","createDelegateTool","options","description","byName","Map","names","inputSchema","z","object","agent","enum","describe","task","string","min","Tool","create","handler","raw","parse","get","result","run","delegate","ok","response","Error","String"]}
+{"version":3,"sources":["../src/tools-entry.ts","../src/tools/delegate-tool.ts"],"mappings":";;;;;;;;;;;;;;;;;;;AAuBA,SACEA,iBACAC,cACAC,0BACAC,yBACAC,qBACAC,mBACAC,sBACAC,6BACAC,uBACAC,oBACAC,gCACAC,mBACAC,qBACAC,gBACAC,4BACAC,mBACAC,oBACAC,oBACAC,oBACAC,qBACAC,sBACAC,4BACAC,iBACAC,oBACAC,sBACAC,qBACAC,oBACAC,qBACAC,qBACAC,sBACAC,yBACAC,uBACAC,0BACAC,YACAC,YACAC,aACAC,gBACAC,gBACAC,aACAC,kBACAC,aACAC,gBACAC,sBACAC,gBACAC,eACAC,kBACAC,eACAC,kBACAC,sBACAC,gBACAC,qBACAC,iBACAC,UACAC,uBACAC,8BACK;;;AC7DP,SAASC,YAAY;AACrB,SAASC,yBAAyB;AAClC,SAASC,SAAS;AAoBX,IAAMC,0BAAN,cAAsCC,kBAAAA;EAxC7C,OAwC6CA;;;;EACzBC,OAAO;EAEzB,YACEC,SACSC,MACT;AACA,UAAMD,OAAAA,GAAAA,KAFGC,OAAAA;EAGX;AACF;AAwBA,SAASC,mBACPC,QACAC,UAAqC;AAErC,MAAID,OAAOE,WAAW,GAAG;AACvB,UAAM,IAAIR,wBACR,6HACA,cAAA;EAEJ;AAEA,QAAMS,OAAO,oBAAIC,IAAAA;AACjB,aAAW,EAAER,KAAI,KAAMI,QAAQ;AAC7B,QAAIG,KAAKE,IAAIT,IAAAA,GAAO;AAGlB,YAAM,IAAIF,wBACR,6CAA6CY,KAAKC,UAAUX,IAAAA,CAAAA,qDAC5D,gBAAA;IAEJ;AACAO,SAAKK,IAAIZ,IAAAA;EACX;AAEA,QAAMa,kBAAkBT,OAAOU,KAAK,CAACC,UAAU,CAACC,OAAOD,MAAME,MAAM,CAAA;AAKnE,MAAIJ,mBAAmBR,UAAUa,WAAW,QAAQ,CAACb,UAAUa,QAAQ;AACrE,UAAM,IAAIpB,wBACR,2QAGA,iBAAA;EAEJ;AACF;AArCSK;AAwCT,SAASgB,YAAYC,OAAc;AACjC,MAAIA,iBAAiBC,8BAA+B,QAAO;AAC3D,MAAID,iBAAiBE,uBAAwB,QAAO;AACpD,MAAIF,iBAAiBG,gBAAiB,QAAO;AAK7C,MAAIH,iBAAiBI,wBAAyB,QAAO;AAarD,MAAIJ,iBAAiBK,eAAgB,QAAO;AAC5C,SAAOC;AACT;AAvBSP;AA0BT,IAAMQ,oBAAoB;AAwC1B,IAAMC,oBAAyC,oBAAIpB,IAAI;;EAErD;EACA;EACA;CACD;AAED,SAASqB,gBAAgB3B,MAAckB,OAAc;AACnD,MAAI,CAACQ,kBAAkBnB,IAAIP,IAAAA,EAAO,QAAOyB;AACzC,SAAOP,iBAAiBU,QAAQV,MAAMnB,UAAU8B,OAAOX,KAAAA;AACzD;AAHSS;AAKT,SAASG,eAAe5B,QAAsC;AAC5D,SAAOA,OAAO6B,IAAI,CAAClB,UAAUA,MAAMf,IAAI,EAAEkC,KAAK,IAAA;AAChD;AAFSF;AAcF,SAASG,mBAAmBC,SAAkC;AACnE,QAAM,EAAEhC,QAAQC,UAAUL,OAAO,YAAYqC,YAAW,IAAKD;AAE7DjC,qBAAmBC,QAAQC,QAAAA;AAE3B,QAAMiC,SAAS,IAAIC,IAAInC,OAAO6B,IAAI,CAAClB,UAAU;IAACA,MAAMf;IAAMe,MAAME;GAAO,CAAA;AACvE,QAAMuB,QAAQpC,OAAO6B,IAAI,CAAClB,UAAUA,MAAMf,IAAI;AAE9C,QAAMyC,cAAcC,EAAEC,OAAO;IAC3BC,OAAOF,EACJG,KAAKL,KAAAA,EACLM,SAAS,0CAA0Cd,eAAe5B,MAAAA,CAAAA,GAAU;IAC/E2C,MAAML,EACHM,OAAM,EACNC,IAAI,CAAA,EACJH,SACC,qFAAA;EAEN,CAAA;AAEA,SAAOI,KAAKC,OAAO;IACjBnD;IACAqC,aACEA,eACA,oDAAoDL,eAAe5B,MAAAA,CAAAA;IAIrEqC;IACAW,SAAS,8BAAOC,QAAAA;AAMd,YAAM,EAAET,OAAOG,KAAI,IAAKN,YAAYa,MAAMD,GAAAA;AAE1C,YAAMpC,SAASqB,OAAOiB,IAAIX,KAAAA;AAC1B,UAAI,CAAC3B,QAAQ;AAQX,cAAM,IAAInB,wBACR,2BAA2BY,KAAKC,UAAUiC,KAAAA,CAAAA,4BAA6BZ,eAAe5B,MAAAA,CAAAA,KACtF,eAAA;MAEJ;AAEA,UAAI;AACF,cAAMoD,SAA2BxC,OAAOC,MAAAA,IACpC,MAAMA,OAAOwC,IAAIV,IAAAA,IACjB,MAAMW,SAASzC,QAAQ8B,MAAM1C,YAAY,CAAC,CAAA;AAE9C,eAAOK,KAAKC,UAAU;UAAEgD,IAAI;UAAMC,UAAUJ,OAAOI;QAAS,CAAA;MAC9D,SAASxC,OAAO;AACd,cAAMlB,OAAOiB,YAAYC,KAAAA;AACzB,YAAIlB,SAASwB,QAAW;AAGtB,gBAAMN;QACR;AAKA,eAAOV,KAAKC,UAAU;UAAEgD,IAAI;UAAOvC,OAAOlB;UAAMD,SAAS4B,gBAAgB3B,MAAMkB,KAAAA;QAAO,CAAA;MACxF;IACF,GA1CS;EA2CX,CAAA;AACF;AAzEgBe;","names":["buildEnvContext","buildRepoMap","CatastrophicCommandError","catastrophicShellReason","commandDenialReason","ContextMatchError","createApplyPatchTool","createBraveWebSearchAdapter","createCurrentTimeTool","createEditFileTool","createGenericHttpSearchAdapter","createGitDiffTool","createGitStatusTool","createGlobTool","createInteractiveShellTool","createListDirTool","createPlanModeTool","createQuestionTool","createReadFileTool","createRunVitestTool","createSearchTextTool","createSessionArtifactStore","createShellTool","createTodolistTool","createUpdatePlanTool","createViewImageTool","createWebFetchTool","createWebSearchTool","createWriteFileTool","createWriteStdinTool","DEFAULT_MAX_IMAGE_BYTES","DEFAULT_TOOL_GUIDANCE","denyCatastrophicCommands","formatCode","formatDiff","formatError","formatFileList","injectGuidance","isBlockedIp","isCommandAllowed","ReadTracker","ReasoningTools","RedirectBlockedError","renderToolList","replaceUnique","resolveAndScreen","screenedFetch","SsrfBlockedError","todoItemsToPlanNodes","truncateOutput","withDefaultGuidance","withDescription","withName","withShellExitGuidance","withToolResultGuidance","Tool","TheokitAgentError","z","DelegateToolConfigError","TheokitAgentError","name","message","code","assertUsableRoster","roster","defaults","length","seen","Set","has","JSON","stringify","add","needsCredential","some","entry","isPort","target","apiKey","errorCodeOf","error","DelegationBudgetExceededError","DelegationTimeoutError","DelegationError","GuardrailViolationError","GuardrailError","undefined","REFUSED_BY_POLICY","MESSAGE_MAY_CROSS","messageForModel","Error","String","describeRoster","map","join","createDelegateTool","options","description","byName","Map","names","inputSchema","z","object","agent","enum","describe","task","string","min","Tool","create","handler","raw","parse","get","result","run","delegate","ok","response"]}

package/dist/usage.d.ts

@@ -27,9 +27,28 @@ interface UsageRecord {
     userId?: string;
     /** Model id (`claude-sonnet-4-5-20250929`). */
     model: string;
+    /**
+     * The token split this cost is for.
+     *
+     * `cacheRead` and `cacheWrite` are OPTIONAL and absent by default. Cached reads are billed at a
+     * fraction of input tokens, so two runs with identical `input` totals and different cache ratios
+     * cost different amounts — and a record that carried only the totals stated a number it could not
+     * explain. The audit trail showed the figure and not the reason.
+     *
+     * ABSENT, never `0`, when a provider does not report cache usage. "Not reported" and "reported as
+     * zero" are different facts, and defaulting would claim a measurement nobody made — the same
+     * strictness `RunUsageSnapshot` keeps by returning `undefined` before a provider has spoken.
+     *
+     * The spellings are this layer's own (`cacheRead`/`cacheWrite`), matching `DoneEvent.usage`'s
+     * `cacheReadTokens`/`cacheWriteTokens` rather than the wire's
+     * `cache_read_input_tokens`. A survey looking for the wire spellings measured zero here and
+     * concluded the concept was absent; it has been carried on the stream since V4-O.
+     */
     tokens: {
         input: number;
         output: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
     /** USD in fractional dollars. */
     costUsd: number;
@@ -56,6 +75,17 @@ interface UsageQuery {
         from: Date;
         to: Date;
     };
+    /**
+     * Narrow to one model — what a per-model cost breakdown is.
+     *
+     * It is a QUERY rather than a second shape on {@link UsageResult}, because a breakdown returned
+     * alongside a total is two numbers that can disagree. One source, asked a different question,
+     * cannot.
+     *
+     * A TOOL record has no model and is already excluded from the LLM totals; narrowing by model
+     * cannot resurrect one.
+     */
+    model?: string;
 }
 interface UsageResult {
     totalTokens: number;

package/dist/usage.js

@@ -48,6 +48,9 @@ var InMemoryUsageStorage = class {
 };
 function matches(record, query) {
   if (query.userId !== void 0 && record.userId !== query.userId) return false;
+  if (query.model !== void 0 && record.kind !== "tool" && record.model !== query.model) {
+    return false;
+  }
   if (query.period === void 0) return true;
   return record.timestamp >= query.period.from && record.timestamp <= query.period.to;
 }

package/dist/usage.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/usage/in-memory-usage.ts"],"mappings":";;;;;;;;AAmBO,IAAMA,uBAAN,MAAMA;EAXb,OAWaA;;;EACFC,OAAO;EACP,WAA8C,CAAA;EAEvDC,OAAOC,OAAqD;AAG1D,UAAMC,aACJ,UAAUD,SAASA,MAAME,SAAS,SAAS;MAAE,GAAGF;IAAM,IAAI;MAAE,GAAGA;MAAOE,MAAM;IAAe;AAC7F,SAAK,SAASC,KAAKF,UAAAA;AACnB,WAAOG,QAAQC,QAAO;EACxB;EAEAC,SAASC,QAAoB,CAAC,GAAyB;AACrD,UAAMC,WAAW,KAAK,SAASC,OAAO,CAACV,WAAWW,QAAQX,QAAQQ,KAAAA,CAAAA;AAClE,UAAMI,MAAMH,SAASC,OAAO,CAACV,WAAkCA,OAAOG,SAAS,MAAA;AAC/E,WAAOE,QAAQC,QAAQ;MACrBO,aAAaD,IAAIE,OAAO,CAACC,KAAKC,MAAMD,MAAMC,EAAEC,OAAOhB,QAAQe,EAAEC,OAAOC,QAAQ,CAAA;MAC5EC,cAAcP,IAAIE,OAAO,CAACC,KAAKC,MAAMD,MAAMC,EAAEI,SAAS,CAAA;MACtDC,MAAMT,IAAIU;IACZ,CAAA;EACF;;;;;;;;EASAC,cAAuC;AACrC,aAASC,IAAI,KAAK,SAASF,SAAS,GAAGE,KAAK,GAAGA,KAAK,GAAG;AACrD,YAAMxB,SAAS,KAAK,SAASwB,CAAAA;AAC7B,UAAIxB,OAAOG,SAAS,OAAQ,QAAOH;IACrC;AACA,WAAOyB;EACT;AACF;AAEA,SAASd,QAAQX,QAAuCQ,OAAiB;AAGvE,MAAIA,MAAMkB,WAAWD,UAAazB,OAAO0B,WAAWlB,MAAMkB,OAAQ,QAAO;AACzE,MAAIlB,MAAMmB,WAAWF,OAAW,QAAO;AACvC,SAAOzB,OAAO4B,aAAapB,MAAMmB,OAAOE,QAAQ7B,OAAO4B,aAAapB,MAAMmB,OAAOG;AACnF;AANSnB;","names":["InMemoryUsageStorage","name","record","input","normalised","kind","push","Promise","resolve","getUsage","query","matching","filter","matches","llm","totalTokens","reduce","sum","r","tokens","output","totalCostUsd","costUsd","runs","length","latestUsage","i","undefined","userId","period","timestamp","from","to"]}
+{"version":3,"sources":["../src/usage/in-memory-usage.ts"],"mappings":";;;;;;;;AAmBO,IAAMA,uBAAN,MAAMA;EAXb,OAWaA;;;EACFC,OAAO;EACP,WAA8C,CAAA;EAEvDC,OAAOC,OAAqD;AAG1D,UAAMC,aACJ,UAAUD,SAASA,MAAME,SAAS,SAAS;MAAE,GAAGF;IAAM,IAAI;MAAE,GAAGA;MAAOE,MAAM;IAAe;AAC7F,SAAK,SAASC,KAAKF,UAAAA;AACnB,WAAOG,QAAQC,QAAO;EACxB;EAEAC,SAASC,QAAoB,CAAC,GAAyB;AACrD,UAAMC,WAAW,KAAK,SAASC,OAAO,CAACV,WAAWW,QAAQX,QAAQQ,KAAAA,CAAAA;AAClE,UAAMI,MAAMH,SAASC,OAAO,CAACV,WAAkCA,OAAOG,SAAS,MAAA;AAC/E,WAAOE,QAAQC,QAAQ;MACrBO,aAAaD,IAAIE,OAAO,CAACC,KAAKC,MAAMD,MAAMC,EAAEC,OAAOhB,QAAQe,EAAEC,OAAOC,QAAQ,CAAA;MAC5EC,cAAcP,IAAIE,OAAO,CAACC,KAAKC,MAAMD,MAAMC,EAAEI,SAAS,CAAA;MACtDC,MAAMT,IAAIU;IACZ,CAAA;EACF;;;;;;;;EASAC,cAAuC;AACrC,aAASC,IAAI,KAAK,SAASF,SAAS,GAAGE,KAAK,GAAGA,KAAK,GAAG;AACrD,YAAMxB,SAAS,KAAK,SAASwB,CAAAA;AAC7B,UAAIxB,OAAOG,SAAS,OAAQ,QAAOH;IACrC;AACA,WAAOyB;EACT;AACF;AAEA,SAASd,QAAQX,QAAuCQ,OAAiB;AAGvE,MAAIA,MAAMkB,WAAWD,UAAazB,OAAO0B,WAAWlB,MAAMkB,OAAQ,QAAO;AAMzE,MAAIlB,MAAMmB,UAAUF,UAAazB,OAAOG,SAAS,UAAUH,OAAO2B,UAAUnB,MAAMmB,OAAO;AACvF,WAAO;EACT;AACA,MAAInB,MAAMoB,WAAWH,OAAW,QAAO;AACvC,SAAOzB,OAAO6B,aAAarB,MAAMoB,OAAOE,QAAQ9B,OAAO6B,aAAarB,MAAMoB,OAAOG;AACnF;AAdSpB;","names":["InMemoryUsageStorage","name","record","input","normalised","kind","push","Promise","resolve","getUsage","query","matching","filter","matches","llm","totalTokens","reduce","sum","r","tokens","output","totalCostUsd","costUsd","runs","length","latestUsage","i","undefined","userId","model","period","timestamp","from","to"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "13.0.0-next.9",
+  "version": "13.1.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The AgentBuilder.create() authoring chain compiles to the @theokit/sdk runtime.",
   "repository": {
     "type": "git",
@@ -121,7 +121,7 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.9",
     "zod": "^4.4.3",
-    "@theokit/http": "2.1.0-next.0"
+    "@theokit/http": "2.1.0"
   },
   "engines": {
     "node": ">=22.12.0"
@@ -129,7 +129,7 @@
   "dependencies": {
     "@theokit/sdk": "^4.52.1 || ^5.0.0",
     "@theokit/sdk-tools": "^0.27.1",
-    "@theokit/presenter": "0.9.0-next.0"
+    "@theokit/presenter": "0.9.0"
   },
   "publishConfig": {
     "access": "public",