@theokit/agents 7.5.0 → 8.0.0

package/dist/testing.d.ts

@@ -1,3 +1,11 @@
+import { AgentOutputEvent } from '@theokit/presenter';
+import { WireChunk } from '@theokit/presenter/wire';
+import { A as AgentDefinition } from './define-agent-3Kuf6iKM.js';
+import '@theokit/sdk';
+import 'zod';
+import '@theokit/sdk/errors';
+import './hook-handlers-Cw2FsnE5.js';
+
 /**
  * createMockAgentStream — test agents without an LLM API key.
  *
@@ -44,4 +52,85 @@ interface MockStreamEvent {
 }
 declare function createMockAgentStream(opts: MockAgentStreamOptions): (_message: string, _sessionId: string) => AsyncIterable<MockStreamEvent>;
 
-export { type MockAgentStreamOptions, type MockResponse, type MockStreamEvent, createMockAgentStream };
+/**
+ * Typed builders for the chunks a test needs.
+ *
+ * Not a builder per member of the union — most of the thirteen never appear in a fixture, and
+ * writing them all would be surface nobody asked for (YAGNI). These are the four a consumer's
+ * fixtures actually contained. A test needing another writes the literal and passes it through
+ * {@link createMockWireStream}, which validates all the same.
+ */
+declare const wireChunk: {
+    /** A text fragment. `id` groups deltas into one message; a fixture rarely cares which. */
+    text(delta: string, id?: string): WireChunk;
+    /** The error frame. This is the literal a consumer was writing with `as never` on the end. */
+    error(errorText: string): WireChunk;
+    /** Stream end. */
+    finish(): WireChunk;
+    /** Stream start. `messageId` is optional in the schema and omitted here for the same reason. */
+    start(messageId?: string): WireChunk;
+};
+/**
+ * A stream of wire chunks, for driving anything that consumes the wire.
+ *
+ * Async because every production consumer is: a mock that were synchronous would let a test pass
+ * over code that never awaited, which is the class of bug a stream test exists to catch.
+ */
+declare function createMockWireStream(chunks: readonly WireChunk[]): AsyncGenerator<WireChunk>;
+/**
+ * A stream of presenter output events.
+ *
+ * Published alongside the wire one, deliberately: a test of a presenter surface should not have to
+ * round-trip through the wire to produce a single event. Two vocabularies exist in production, and a
+ * seam that admitted only one would push every test of the other back into casts.
+ */
+declare function createMockOutputEvents(events: readonly AgentOutputEvent[]): AsyncGenerator<AgentOutputEvent>;
+
+/**
+ * M85 — assert at the COMPILATION boundary, which is the one with the widest blast radius.
+ *
+ * The consumer documented this itself: in an agent product, the question that matters is not "did
+ * the stream emit the right frames" but **"does this agent have the tools I think it has, and are
+ * the dangerous ones gated?"**. A wrong answer there is a shell running unapproved, or a tool the
+ * model cannot see and the operator believes it can.
+ *
+ * ## Why a helper and not `compileAgentDefinition` directly
+ *
+ * `CompiledAgentOptions` is the shape the SDK adapter consumes — thirty-odd fields, most of which a
+ * test does not care about. Asserting against it directly is how 90 occurrences of `vi.mock` over
+ * the framework barrel got written: the assertion was too awkward, so the test faked the module
+ * instead, pinning itself to export NAMES and detecting no drift whatsoever.
+ *
+ * ## Capabilities are NOT here, and that is measured
+ *
+ * `capabilities` is a field of the DEFINITION, not of `CompiledAgentOptions` — the compiler resolves
+ * it into tools rather than carrying it through. The DoD named it, and projecting it would have
+ * meant reading the definition instead of the compilation, which is a different assertion wearing
+ * this function's name: it would report what the author WROTE, not what the agent GOT.
+ *
+ * This projects the three facts a test actually asserts. It is a READ over the real compiler — never
+ * a second one — so a compilation change surfaces here rather than in a fixture that agreed with an
+ * older version of the truth.
+ */
+/** The facts a test asserts about a compiled agent. */
+interface CompiledInspection {
+    /** Tool names, sorted, as the model will see them. */
+    readonly toolNames: readonly string[];
+    /** Names of the tools that require human approval before running. */
+    readonly gatedToolNames: readonly string[];
+    /** The model the agent will use, when one is declared. */
+    readonly model: string | undefined;
+}
+/**
+ * Inspect what a definition compiles to.
+ *
+ * ```ts
+ * expect(inspectCompiled(myAgent).gatedToolNames).toContain('run_shell')
+ * ```
+ *
+ * Sorted output, because a list whose order changes with a decorator's position is a list nobody can
+ * diff — and a test that pinned that order would fail on a reordering that changed nothing.
+ */
+declare function inspectCompiled(definition: AgentDefinition): CompiledInspection;
+
+export { type CompiledInspection, type MockAgentStreamOptions, type MockResponse, type MockStreamEvent, createMockAgentStream, createMockOutputEvents, createMockWireStream, inspectCompiled, wireChunk };

package/dist/testing.js

@@ -1,3 +1,6 @@
+import {
+  compileAgentDefinition
+} from "./chunk-4VHCH6IZ.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -67,7 +70,79 @@ function createMockAgentStream(opts) {
   });
 }
 __name(createMockAgentStream, "createMockAgentStream");
+
+// src/testing/mock-wire-stream.ts
+import { wireChunkSchema } from "@theokit/presenter/wire";
+function checked(chunk) {
+  const parsed = wireChunkSchema.safeParse(chunk);
+  if (!parsed.success) {
+    throw new TypeError(`[@theokit/agents/testing] this is not a valid wire chunk: ${parsed.error.message}. A fixture production would reject is a test that proves nothing.`);
+  }
+  return chunk;
+}
+__name(checked, "checked");
+var wireChunk = {
+  /** A text fragment. `id` groups deltas into one message; a fixture rarely cares which. */
+  text(delta, id = "text-1") {
+    return checked({
+      type: "text-delta",
+      id,
+      delta
+    });
+  },
+  /** The error frame. This is the literal a consumer was writing with `as never` on the end. */
+  error(errorText) {
+    return checked({
+      type: "error",
+      errorText
+    });
+  },
+  /** Stream end. */
+  finish() {
+    return checked({
+      type: "finish"
+    });
+  },
+  /** Stream start. `messageId` is optional in the schema and omitted here for the same reason. */
+  start(messageId) {
+    return checked(messageId === void 0 ? {
+      type: "start"
+    } : {
+      type: "start",
+      messageId
+    });
+  }
+};
+async function* createMockWireStream(chunks) {
+  for (const chunk of chunks) {
+    yield checked(chunk);
+  }
+}
+__name(createMockWireStream, "createMockWireStream");
+async function* createMockOutputEvents(events) {
+  for (const event of events) yield event;
+}
+__name(createMockOutputEvents, "createMockOutputEvents");
+
+// src/testing/inspect-compiled.ts
+function inspectCompiled(definition) {
+  const compiled = compileAgentDefinition(definition);
+  const toolNames = compiled.tools.map((tool) => tool.name).sort((a, b) => a.localeCompare(b));
+  const gatedToolNames = [
+    ...compiled.hitl?.keys() ?? []
+  ].sort((a, b) => a.localeCompare(b));
+  return {
+    toolNames,
+    gatedToolNames,
+    model: typeof compiled.model === "string" ? compiled.model : void 0
+  };
+}
+__name(inspectCompiled, "inspectCompiled");
 export {
-  createMockAgentStream
+  createMockAgentStream,
+  createMockOutputEvents,
+  createMockWireStream,
+  inspectCompiled,
+  wireChunk
 };
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/testing/mock-stream.ts"],"mappings":";;;;;AAgDO,SAASA,sBAAsBC,MAA4B;AAChE,SAAO,CAACC,UAAkBC,gBAAwD;IAChF,QAAQC,OAAOC,aAAa,IAAC;AAC3B,YAAMC,QAAQC,QAAO;AACrB,YAAMC,QAAQ,QAAQC,KAAKC,IAAG,CAAA;AAC9B,YAAM;QAAEC,MAAM;QAAeH;QAAOI,WAAWX,KAAKW,aAAa;QAAcC,OAAO;MAAO;AAE7F,UAAIC,cAAc;AAClB,iBAAWC,KAAKd,KAAKe,WAAW;AAC9B,YAAID,EAAEJ,SAAS,UAAUI,EAAEE,SAAS;AAClC,gBAAMC,QAAQH,EAAEE,QAAQE,MAAM,GAAA;AAC9B,qBAAWC,QAAQF,OAAO;AACxB,kBAAM;cAAEP,MAAM;cAAcM,SAASG,OAAO;YAAI;AAChDN,2BAAe;UACjB;QACF,WAAWC,EAAEJ,SAAS,aAAa;AACjC,gBAAMU,SAAS,MAAMZ,KAAKC,IAAG,CAAA,IAAMY,OAAOC,WAAU,EAAGC,MAAM,GAAG,CAAA,CAAA;AAChE,gBAAM;YAAEb,MAAM;YAAaU;YAAQI,UAAUV,EAAEW,QAAQ;YAAWC,OAAOZ,EAAEY,SAAS,CAAC;UAAE;AACvF,gBAAM;YACJhB,MAAM;YACNU;YACAI,UAAUV,EAAEW,QAAQ;YACpBE,QAAQb,EAAEa,UAAU;YACpBC,YAAY;YACZC,SAAS;UACX;AACAhB,yBAAe;QACjB,WAAWC,EAAEJ,SAAS,SAAS;AAC7B,gBAAM;YACJA,MAAM;YACNoB,MAAM;YACNC,SAASjB,EAAEiB,WAAW;YACtBC,WAAW;UACb;AACA;QACF;MACF;AAEA,YAAM;QACJtB,MAAM;QACNuB,QAAQjC,KAAKe,UACVmB,OAAO,CAACpB,MAAMA,EAAEJ,SAAS,MAAA,EACzByB,IAAI,CAACrB,MAAMA,EAAEE,OAAO,EACpBoB,KAAK,GAAA;QACRC,OAAO;UACLC,aAAazB;UACb0B,cAAc1B;UACdA,aAAaA,cAAc;QAC7B;QACAe,YAAY;QACZY,MAAMxC,KAAKwC,QAAQ;MACrB;IACF;EACF;AACF;AAtDgBzC;","names":["createMockAgentStream","opts","_message","_sessionId","Symbol","asyncIterator","Promise","resolve","runId","Date","now","type","agentName","model","totalTokens","r","responses","content","words","split","word","callId","crypto","randomUUID","slice","toolName","name","input","output","durationMs","isError","code","message","retryable","result","filter","map","join","usage","inputTokens","outputTokens","cost"]}
+{"version":3,"sources":["../src/testing/mock-stream.ts","../src/testing/mock-wire-stream.ts","../src/testing/inspect-compiled.ts"],"mappings":"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","names":["createMockAgentStream","opts","_message","_sessionId","Symbol","asyncIterator","Promise","resolve","runId","Date","now","type","agentName","model","totalTokens","r","responses","content","words","split","word","callId","crypto","randomUUID","slice","toolName","name","input","output","durationMs","isError","code","message","retryable","result","filter","map","join","usage","inputTokens","outputTokens","cost","wireChunkSchema","checked","chunk","parsed","wireChunkSchema","safeParse","success","TypeError","error","message","wireChunk","text","delta","id","type","errorText","finish","start","messageId","undefined","createMockWireStream","chunks","createMockOutputEvents","events","event","inspectCompiled","definition","compiled","compileAgentDefinition","toolNames","tools","map","tool","name","sort","a","b","localeCompare","gatedToolNames","hitl","keys","model","undefined"]}

package/dist/tool-scope.d.ts

@@ -0,0 +1,133 @@
+import { SandboxProvider, SandboxMode } from '@theokit/sdk/sandbox';
+
+/**
+ * M78 — the tool scope binder: bind `{ projectRoot, writeRoot, sandbox }` once, so an unconfined
+ * shell is unrepresentable.
+ *
+ * ## The defect this closes
+ *
+ * The framework shipped the ingredients — `createSandboxBackend`, `resolveSandboxPosture` — and no
+ * binder. Measured against `@theokit/sdk-tools@0.26.1`: `projectRoot` is REQUIRED on eleven
+ * factories, while `sandbox` is **optional** on three — `createGitDiffTool`, `createGitStatusTool`
+ * and, the one that matters, `createShellTool`.
+ *
+ * An optional sandbox on a shell factory means a scope assembled without one produces an UNCONFINED
+ * SHELL with no error and no warning. The consumer that prompted this milestone documented exactly
+ * that outcome. And because nothing bound the roots either, every product rediscovered per tool
+ * which root each factory accepts — with silence as the failure mode for getting it wrong.
+ *
+ * ## Why this is framework and not runtime
+ *
+ * It runs nothing. It applies configuration to factories the SDK owns — the boundary/home half of
+ * ADR-0040 § D2, the same category as the approval gate and the ask channel.
+ *
+ * ## Why ONE generic `bind` and not eleven named wrappers
+ *
+ * The milestone wants the consumer's registry to become "the declarative map of ten entries it
+ * should be". A generic `bind` IS that map:
+ *
+ * ```ts
+ * const registry = {
+ *   shell:     scope.bind(createShellTool)(),
+ *   read_file: scope.bind(createReadFileTool)(),
+ * }
+ * ```
+ *
+ * Eleven named wrappers would add nothing to that and cost two things: a twelfth tool in `sdk-tools`
+ * would need a change here (breaking OCP), and each wrapper is one more place to forget the sandbox —
+ * the exact failure being closed. Parsimony rung 1: they do not need to exist.
+ */
+/** What a sandbox mode permits, in the two terms a tool factory actually needs. */
+interface SandboxWritePolicy {
+    /** Whether ANY write is permitted. */
+    readonly writes: boolean;
+    /** Whether a path outside the project root may be honoured. */
+    readonly allowAbsolute: boolean;
+}
+/**
+ * The write policy of a sandbox mode.
+ *
+ * A PROJECTION of the SDK's own `writableRootsFor`, never a second source of truth (G12): products
+ * were re-deriving this by hand, and a function that disagreed with the SDK would be a third
+ * derivation — worse than the two it replaces. `tool-scope.test.ts` asserts the agreement for every
+ * mode.
+ *
+ * The mapping is not guessable, which is why it is measured rather than assumed:
+ *
+ * | mode | `writableRootsFor` | meaning |
+ * |---|---|---|
+ * | `read-only` | `[]` | no writable root |
+ * | `workspace-write` | `[cwd, '/tmp']` | writes, confined |
+ * | `danger-full-access` | `null` | **unrestricted** — not "no writes" |
+ *
+ * Reading `null` as "nothing is writable" would forbid writes exactly where everything is allowed.
+ */
+declare function sandboxWritePolicy(mode: SandboxMode, cwd: string): SandboxWritePolicy;
+/** The scope fields a bound factory receives. Every field is non-optional by the time it is applied. */
+interface ScopeFields {
+    readonly projectRoot: string;
+    readonly writeRoot: string;
+    readonly sandbox: SandboxProvider;
+}
+interface ToolScopeInput {
+    /** Root the tools read from. */
+    readonly projectRoot: string;
+    /**
+     * Root the tools write to. Defaults to `projectRoot` — the conservative reading: a product that
+     * never distinguishes the two should not have to say so twice, and the default must not be broader
+     * than what was asked for.
+     */
+    readonly writeRoot?: string;
+    /**
+     * The confinement. REQUIRED, and that is the entire milestone.
+     *
+     * Making it optional is what let a scope produce an unconfined shell in silence. A caller who
+     * genuinely wants no confinement must say so by passing a `danger-full-access` sandbox — a
+     * decision that appears in the code, in a review, and in a log, rather than an omission that
+     * appears nowhere.
+     */
+    readonly sandbox: SandboxProvider;
+    /**
+     * The mode `policy` is computed from. Optional because the policy is a convenience: a scope whose
+     * product never asks about write policy needs no mode.
+     */
+    readonly mode?: SandboxMode;
+}
+/** Any `sdk-tools` factory: takes an options object, returns a tool. */
+type ToolFactory<TOptions, TTool> = (options: TOptions) => TTool;
+/**
+ * Per-tool overrides.
+ *
+ * The scope fields are optional here — a caller may replace them — but `undefined` is treated as
+ * "not supplied", never as "unset". See {@link ToolScope.bind}.
+ */
+type Overrides<TOptions> = Omit<TOptions, keyof ScopeFields> & Partial<ScopeFields>;
+interface ToolScope extends ScopeFields {
+    /** The write policy of `mode`, when one was supplied. */
+    readonly policy: SandboxWritePolicy;
+    /**
+     * Scope a factory.
+     *
+     * Returns a function taking that tool's own options. Scope fields are injected; an override may
+     * REPLACE one, but an `undefined` override falls back to the scope rather than clearing it.
+     *
+     * That asymmetry is the point. Variation is legitimate — one tool may need stricter confinement
+     * than the rest, which is the risk the milestone flags. Absence is not: `{ sandbox: maybeSandbox }`
+     * with an undefined variable is ordinary code, and honouring it would silently unconfine a shell
+     * through the one door the type system cannot close.
+     */
+    bind<TOptions extends Partial<ScopeFields>, TTool>(factory: ToolFactory<TOptions, TTool>): (overrides?: Overrides<TOptions>) => TTool;
+}
+/**
+ * Bind a tool scope.
+ *
+ * ```ts
+ * const scope = bindToolScope({ projectRoot, sandbox: await resolveSandbox({ mode }) , mode })
+ * const shell = scope.bind(createShellTool)({ name: 'run_shell' })
+ * ```
+ *
+ * Omitting `sandbox` does not compile — see `tests/type/tool-scope.test-d.ts`.
+ */
+declare function bindToolScope(input: ToolScopeInput): ToolScope;
+
+export { type SandboxWritePolicy, type ToolScope, type ToolScopeInput, bindToolScope, sandboxWritePolicy };

package/dist/tool-scope.js

@@ -0,0 +1,61 @@
+import {
+  __name
+} from "./chunk-Z4QWC7IK.js";
+
+// src/tools/tool-scope.ts
+import { writableRootsFor } from "@theokit/sdk/sandbox";
+function sandboxWritePolicy(mode, cwd) {
+  const roots = writableRootsFor(mode, cwd);
+  if (roots === null) return {
+    writes: true,
+    allowAbsolute: true
+  };
+  if (roots === void 0) {
+    throw new TypeError(`[@theokit/agents] unknown sandbox mode ${JSON.stringify(mode)} \u2014 write policy is undefined for it. Expected one of: "read-only", "workspace-write", "danger-full-access". Refusing to guess: guessing permissive would grant writes, and guessing restrictive would silently disable a tool.`);
+  }
+  return {
+    writes: roots.length > 0,
+    allowAbsolute: false
+  };
+}
+__name(sandboxWritePolicy, "sandboxWritePolicy");
+var BoundToolScope = class BoundToolScope2 {
+  static {
+    __name(this, "BoundToolScope");
+  }
+  projectRoot;
+  writeRoot;
+  sandbox;
+  policy;
+  constructor(input) {
+    this.projectRoot = input.projectRoot;
+    this.writeRoot = input.writeRoot ?? input.projectRoot;
+    this.sandbox = input.sandbox;
+    this.policy = input.mode === void 0 ? {
+      writes: false,
+      allowAbsolute: false
+    } : sandboxWritePolicy(input.mode, this.projectRoot);
+  }
+  bind(factory) {
+    return (overrides) => {
+      const merged = {
+        ...overrides,
+        // AFTER the spread, and each with `??`: an override may replace a scope field, but an
+        // explicit `undefined` resolves back to the scope instead of clearing it.
+        projectRoot: overrides?.projectRoot ?? this.projectRoot,
+        writeRoot: overrides?.writeRoot ?? this.writeRoot,
+        sandbox: overrides?.sandbox ?? this.sandbox
+      };
+      return factory(merged);
+    };
+  }
+};
+function bindToolScope(input) {
+  return new BoundToolScope(input);
+}
+__name(bindToolScope, "bindToolScope");
+export {
+  bindToolScope,
+  sandboxWritePolicy
+};
+//# sourceMappingURL=tool-scope.js.map

package/dist/tool-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/tool-scope.ts"],"mappings":";;;;;AAAA,SAASA,wBAAgE;AAkElE,SAASC,mBAAmBC,MAAmBC,KAAW;AAM/D,QAAMC,QAAQC,iBAAiBH,MAAMC,GAAAA;AAGrC,MAAIC,UAAU,KAAM,QAAO;IAAEE,QAAQ;IAAMC,eAAe;EAAK;AAO/D,MAAIH,UAAUI,QAAW;AACvB,UAAM,IAAIC,UACR,0CAA0CC,KAAKC,UAAUT,IAAAA,CAAAA,qOAG7B;EAEhC;AACA,SAAO;IAAEI,QAAQF,MAAMQ,SAAS;IAAGL,eAAe;EAAM;AAC1D;AAzBgBN;AAiGhB,IAAMY,iBAAN,MAAMA,gBAAAA;EAnKN,OAmKMA;;;EACKC;EACAC;EACAC;EACAC;EAET,YAAYC,OAAuB;AACjC,SAAKJ,cAAcI,MAAMJ;AACzB,SAAKC,YAAYG,MAAMH,aAAaG,MAAMJ;AAC1C,SAAKE,UAAUE,MAAMF;AAGrB,SAAKC,SACHC,MAAMhB,SAASM,SACX;MAAEF,QAAQ;MAAOC,eAAe;IAAM,IACtCN,mBAAmBiB,MAAMhB,MAAM,KAAKY,WAAW;EACvD;EAEAK,KACEC,SAC4C;AAC5C,WAAO,CAACC,cAAAA;AACN,YAAMC,SAAS;QACb,GAAGD;;;QAGHP,aAAaO,WAAWP,eAAe,KAAKA;QAC5CC,WAAWM,WAAWN,aAAa,KAAKA;QACxCC,SAASK,WAAWL,WAAW,KAAKA;MACtC;AACA,aAAOI,QAAQE,MAAAA;IACjB;EACF;AACF;AAYO,SAASC,cAAcL,OAAqB;AACjD,SAAO,IAAIL,eAAeK,KAAAA;AAC5B;AAFgBK;","names":["writableRootsFor","sandboxWritePolicy","mode","cwd","roots","writableRootsFor","writes","allowAbsolute","undefined","TypeError","JSON","stringify","length","BoundToolScope","projectRoot","writeRoot","sandbox","policy","input","bind","factory","overrides","merged","bindToolScope"]}

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tools-entry.ts"],"mappings":";;;AAoBA,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,oBACAC,qBACAC,qBACAC,sBACAC,uBACAC,0BACAC,YACAC,YACAC,aACAC,gBACAC,gBACAC,aACAC,kBACAC,aACAC,gBACAC,sBACAC,gBACAC,eACAC,kBACAC,eACAC,kBACAC,sBACAC,gBACAC,qBACAC,iBACAC,UACAC,uBACAC,8BACK;","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","createWebFetchTool","createWebSearchTool","createWriteFileTool","createWriteStdinTool","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"]}
+{"version":3,"sources":["../src/tools-entry.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,oBACAC,qBACAC,qBACAC,sBACAC,uBACAC,0BACAC,YACAC,YACAC,aACAC,gBACAC,gBACAC,aACAC,kBACAC,aACAC,gBACAC,sBACAC,gBACAC,eACAC,kBACAC,eACAC,kBACAC,sBACAC,gBACAC,qBACAC,iBACAC,UACAC,uBACAC,8BACK;","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","createWebFetchTool","createWebSearchTool","createWriteFileTool","createWriteStdinTool","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"]}

package/dist/usage.d.ts

@@ -0,0 +1,98 @@
+/**
+ * M84 — the runtime-neutral half of cost tracking.
+ *
+ * ## Why it moved
+ *
+ * 1 715 LOC of observability and cost lived under `packages/theo/src/server/**`, and `theokit` is
+ * the Vite/React web framework. The only real product built on this stack depends on
+ * `@theokit/agents`, `@theokit/tui` and `@theokit/presenter`, and never on `theokit` — a grep for
+ * `from 'theokit` in it returns zero. So none of it was reachable, and what would have been is
+ * HTTP-shaped.
+ *
+ * What crosses is the vocabulary and the in-memory adapter: a record, a query, a result, and a place
+ * to put them. The HTTP wiring (`trackAgentRun`, spans named `http.request`, keying by `requestId`)
+ * stays in `theokit`, because that is what it is about.
+ *
+ * ## `userId` is optional here, and that is the point
+ *
+ * The HTTP path always has one. A terminal agent has no user — it has a person at a keyboard — and
+ * requiring the field forced every terminal product to invent a constant. An invented identifier is
+ * worse than an absent one: it looks like data.
+ */
+/** Per-LLM-call cost record. */
+interface UsageRecord {
+    /** Discriminator. Optional for backward compatibility; absent ⇒ `'llm'`. */
+    kind?: 'llm';
+    /** Who the cost belongs to. Absent for a single-user surface such as a terminal. */
+    userId?: string;
+    /** Model id (`claude-sonnet-4-5-20250929`). */
+    model: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+    /** USD in fractional dollars. */
+    costUsd: number;
+    timestamp: Date;
+}
+/** Per-tool-invocation record. */
+interface ToolUsageRecord {
+    kind: 'tool';
+    userId?: string;
+    conversationId: string;
+    toolName: string;
+    /** Unique per invocation; correlates start with end/error. */
+    callId: string;
+    success: boolean;
+    durationMs: number;
+    /** Populated only when `success === false`. */
+    errorMessage?: string;
+    timestamp: Date;
+}
+interface UsageQuery {
+    /** Omitted ⇒ every record, which is what a single-user surface wants. */
+    userId?: string;
+    period?: {
+        from: Date;
+        to: Date;
+    };
+}
+interface UsageResult {
+    totalTokens: number;
+    totalCostUsd: number;
+    runs: number;
+}
+/** Where usage goes. The framework owns the vocabulary; the app owns the storage. */
+interface UsageStorageAdapter {
+    readonly name: string;
+    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
+    getUsage(query: UsageQuery): Promise<UsageResult>;
+}
+
+/**
+ * M84 — usage in memory.
+ *
+ * Deliberately does NOT implement `theokit`'s `StorageAdapter`: that is a lifecycle contract of the
+ * web framework, and requiring it here is exactly the coupling that made cost tracking unreachable
+ * from a terminal product. The `theokit` side extends this one and adds the lifecycle.
+ *
+ * Concurrency: Node's event loop makes `Array.push` atomic, so concurrent `record()` calls cannot
+ * lose data. This is single-process by construction — a multi-instance deploy supplies its own
+ * adapter, which is what the interface is for.
+ */
+declare class InMemoryUsageStorage implements UsageStorageAdapter {
+    #private;
+    readonly name = "memory";
+    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
+    getUsage(query?: UsageQuery): Promise<UsageResult>;
+    /**
+     * The most recent LLM record, or `undefined`.
+     *
+     * The question a terminal asks after every turn — "what did that cost?" — and the reason a
+     * consumer wrote a ten-line file to answer it. Tool records are excluded: a tool invocation has no
+     * token cost of its own, and returning one here would make the footer show zero after every tool.
+     */
+    latestUsage(): UsageRecord | undefined;
+}
+
+export { InMemoryUsageStorage, type ToolUsageRecord, type UsageQuery, type UsageRecord, type UsageResult, type UsageStorageAdapter };

package/dist/usage.js

@@ -0,0 +1,55 @@
+import {
+  __name
+} from "./chunk-Z4QWC7IK.js";
+
+// src/usage/in-memory-usage.ts
+var InMemoryUsageStorage = class {
+  static {
+    __name(this, "InMemoryUsageStorage");
+  }
+  name = "memory";
+  #records = [];
+  record(input) {
+    const normalised = "kind" in input && input.kind === "tool" ? {
+      ...input
+    } : {
+      ...input,
+      kind: "llm"
+    };
+    this.#records.push(normalised);
+    return Promise.resolve();
+  }
+  getUsage(query = {}) {
+    const matching = this.#records.filter((record) => matches(record, query));
+    const llm = matching.filter((record) => record.kind !== "tool");
+    return Promise.resolve({
+      totalTokens: llm.reduce((sum, r) => sum + r.tokens.input + r.tokens.output, 0),
+      totalCostUsd: llm.reduce((sum, r) => sum + r.costUsd, 0),
+      runs: llm.length
+    });
+  }
+  /**
+  * The most recent LLM record, or `undefined`.
+  *
+  * The question a terminal asks after every turn — "what did that cost?" — and the reason a
+  * consumer wrote a ten-line file to answer it. Tool records are excluded: a tool invocation has no
+  * token cost of its own, and returning one here would make the footer show zero after every tool.
+  */
+  latestUsage() {
+    for (let i = this.#records.length - 1; i >= 0; i -= 1) {
+      const record = this.#records[i];
+      if (record.kind !== "tool") return record;
+    }
+    return void 0;
+  }
+};
+function matches(record, query) {
+  if (query.userId !== void 0 && record.userId !== query.userId) return false;
+  if (query.period === void 0) return true;
+  return record.timestamp >= query.period.from && record.timestamp <= query.period.to;
+}
+__name(matches, "matches");
+export {
+  InMemoryUsageStorage
+};
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +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"]}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@theokit/agents",
-  "version": "7.5.0",
+  "version": "8.0.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The fluent agent()/tool() builders compile to SDK Agent.create() (M31 builder-only authoring API).",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -50,6 +51,38 @@
     "./client/react": {
       "types": "./dist/client-react.d.ts",
       "import": "./dist/client-react.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
+    },
+    "./ask": {
+      "types": "./dist/ask.d.ts",
+      "import": "./dist/ask.js"
+    },
+    "./tool-scope": {
+      "types": "./dist/tool-scope.d.ts",
+      "import": "./dist/tool-scope.js"
+    },
+    "./mcp-health": {
+      "types": "./dist/mcp-health.d.ts",
+      "import": "./dist/mcp-health.js"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.ts",
+      "import": "./dist/commands.js"
+    },
+    "./doctor": {
+      "types": "./dist/doctor.d.ts",
+      "import": "./dist/doctor.js"
+    },
+    "./usage": {
+      "types": "./dist/usage.d.ts",
+      "import": "./dist/usage.js"
     }
   },
   "files": [
@@ -63,23 +96,15 @@
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
-    "@theokit/sdk-pty": {
-      "optional": true
-    },
-    "@theokit/sdk-tools": {
-      "optional": true
-    },
     "react": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@theokit/sdk-pty": "^0.2.0",
-    "@theokit/sdk-tools": "^0.24.1",
     "ai": "7.0.14",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.6",
+    "vitest": "^4.1.9",
     "zod": "^4.4.3",
     "@theokit/http": "1.0.0"
   },
@@ -87,10 +112,10 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@theokit/sdk": "^4.40.0",
+    "@theokit/sdk": "^4.49.0",
     "@theokit/sdk-pty": ">=0.2.0 <1.0.0",
     "@theokit/sdk-tools": "^0.26.1",
-    "@theokit/presenter": "0.5.1"
+    "@theokit/presenter": "0.7.0"
   },
   "scripts": {
     "build": "tsup",