@theokit/sdk 4.53.1 → 4.55.0

package/dist/{chunk-RP5HQVLD.js → chunk-RNB4APBZ.js}

@@ -2,6 +2,13 @@ import { getAgentFacade } from './chunk-6X6ID4MO.js';
 import { z } from 'zod';
 import { AsyncLocalStorage } from 'async_hooks';
 
+var depthStore = new AsyncLocalStorage();
+async function withDelegationDepth(depth, fn) {
+  return depthStore.run(depth, fn);
+}
+function currentDelegationDepth() {
+  return depthStore.getStore() ?? 0;
+}
 var credentialsStore = new AsyncLocalStorage();
 async function withInheritedSubAgentCredentials(credentials, fn) {
   return credentialsStore.run(credentials, fn);
@@ -60,7 +67,13 @@ function buildChildCreateOptions(spec, inherited) {
     tools: spec.tools ?? []
   };
 }
-async function runChildAgent(spec, input, signal, maxSteps, inherited) {
+async function runChildAgent(spec, input, signal, maxSteps, inherited, depth) {
+  return withDelegationDepth(
+    depth,
+    () => runChildAgentInScope(spec, input, signal, maxSteps, inherited)
+  );
+}
+async function runChildAgentInScope(spec, input, signal, maxSteps, inherited) {
   const agent = await getAgentFacade().create(buildChildCreateOptions(spec, inherited));
   try {
     const sendOptions = {
@@ -108,10 +121,9 @@ async function applyDelegationComplete(spec, input, result, iteration) {
   return completion?.feedback !== void 0 ? result + completion.feedback : result;
 }
 function defineSubAgent(spec, _parentDepth = 0) {
-  const currentDepth = _parentDepth + 1;
   const maxDepth = spec.maxDelegationDepth ?? 3;
-  if (currentDepth > maxDepth) {
-    throw new MaxDelegationDepthError(currentDepth, maxDepth);
+  if (_parentDepth + 1 > maxDepth) {
+    throw new MaxDelegationDepthError(_parentDepth + 1, maxDepth);
   }
   const inputZod = z.object({
     input: z.string().describe("Task for the subagent")
@@ -132,6 +144,10 @@ function defineSubAgent(spec, _parentDepth = 0) {
     handler: async (rawInput, ctx) => {
       const { input: parsed } = inputZod.parse(rawInput);
       const inherited = currentInheritedSubAgentCredentials();
+      const currentDepth = _parentDepth + currentDelegationDepth() + 1;
+      if (currentDepth > maxDepth) {
+        throw new MaxDelegationDepthError(currentDepth, maxDepth);
+      }
       iteration += 1;
       const capturedIteration = iteration;
       const start = await applyDelegationStart(spec, parsed, capturedIteration);
@@ -139,7 +155,14 @@ function defineSubAgent(spec, _parentDepth = 0) {
       const input = applyMessageFilter(spec, start.input, ctx?.messages);
       let result;
       try {
-        result = await runChildAgent(spec, input, ctx?.signal, start.maxSteps, inherited);
+        result = await runChildAgent(
+          spec,
+          input,
+          ctx?.signal,
+          start.maxSteps,
+          inherited,
+          currentDepth
+        );
       } catch (error) {
         await notifyDelegationError(spec, input, error, capturedIteration);
         throw error;
@@ -174,5 +197,5 @@ function subAgentToolsFromDefinitions(agents, parentTools) {
 }
 
 export { MaxDelegationDepthError, SubAgent, subAgentToolsFromDefinitions, withInheritedSubAgentCredentials };
-//# sourceMappingURL=chunk-RP5HQVLD.js.map
-//# sourceMappingURL=chunk-RP5HQVLD.js.map
+//# sourceMappingURL=chunk-RNB4APBZ.js.map
+//# sourceMappingURL=chunk-RNB4APBZ.js.map

package/dist/chunk-RNB4APBZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/concurrency/delegation-depth.ts","../src/internal/runtime/concurrency/subagent-credentials.ts","../src/a2a/subagent.ts"],"names":["AsyncLocalStorage"],"mappings":"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","file":"chunk-RNB4APBZ.js","sourcesContent":["/**\n * #364 — how deep the current delegation chain already is, delivered through the CALL.\n *\n * ## The bug this replaces\n *\n * `maxDelegationDepth` was checked once, at tool-CONSTRUCTION time, against a `_parentDepth`\n * argument that nothing in the SDK ever incremented. Constructing a tool says nothing about how\n * deep it will later be invoked, so with the documented call — `SubAgent.create(spec)` — the test\n * was `1 > maxDepth`, false for every spec that did not ask for depth 0. A subagent whose tools\n * include another subagent recursed unbounded, which is precisely what the guard exists to stop.\n * The only path that ever tripped it was a caller threading the number by hand.\n *\n * ## Why the async scope closes it\n *\n * Depth is a property of the RUN, not of the object. A child's run loop — and therefore every tool\n * it dispatches — executes inside the async continuation of its parent's handler, so a value\n * published on that context is exactly what a nested dispatch needs to read. This is the same seam\n * `subagent-credentials.ts` uses, and for the same reason: what survives every layer that rebuilds\n * a tool object is the call, never the object.\n *\n * It is kept in its own module rather than folded into the credentials payload because depth is a\n * separate concern with a separate lifetime — the credentials scope is opened once per run by the\n * run loop, while depth is opened per delegation by the dispatching tool.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nconst depthStore = new AsyncLocalStorage<number>();\n\n/**\n * Run `fn` with `depth` published as the delegation depth of the current chain.\n *\n * Nested scopes shadow the outer one and the outer is restored on return, so two sibling\n * delegations from the same parent each start from the parent's depth rather than from each\n * other's.\n *\n * @internal\n */\nexport async function withDelegationDepth<T>(depth: number, fn: () => Promise<T>): Promise<T> {\n  return depthStore.run(depth, fn);\n}\n\n/**\n * The delegation depth of the current chain — `0` outside any delegation.\n *\n * `0` is the honest default rather than a fallback to some previous chain's value: a subagent\n * dispatched with no parent delegation IS at depth zero.\n *\n * @internal\n */\nexport function currentDelegationDepth(): number {\n  return depthStore.getStore() ?? 0;\n}\n","/**\n * theokit#148 — the parent's credentials, delivered through the CALL, not through the tool object.\n *\n * ## The class of bug this replaces\n *\n * Credential inheritance used to ride a property installed on the subagent tool object — first a\n * unique `Symbol()`, then `Symbol.for` after #143. Both are the same shape of contract: \"this\n * object will reach the dispatcher with an extra property intact\". Nothing enforces that, and it\n * broke twice for two different reasons:\n *\n *  - **Module duplication** (#142/#143): `tsup splitting: false` inlined a separate copy of the\n *    module into each public entry, so the two copies disagreed on a unique `Symbol()` key. Fixed at\n *    the build level by M78's `splitting: true`, but the fragile contract remained.\n *  - **Object normalization** (#148): any layer that rebuilds the tool from its known fields drops\n *    the property. `@theokit/agents`' `toCompiledTool` does exactly that, and had to add an explicit\n *    `Object.getOwnPropertySymbols` copy loop to compensate — a band-aid the SDK's contract forced\n *    onto a consumer. A named field would have been dropped by the same four-field rebuild, which is\n *    why \"make it a typed field\" alone does not close this.\n *\n * ## Why the async scope closes it\n *\n * What survives a rebuild is not the object — it is the CALL. A normalizing wrapper builds a new\n * object but still invokes the original handler, inside the parent run's async context. So\n * credentials published on that context reach the handler regardless of what the tool object looks\n * like by then. There is no property left for a layer to drop.\n *\n * It also fixes a defect the per-object slot could not: credentials were stored per tool INSTANCE,\n * so one subagent tool shared by two agents got last-writer-wins. The scope is per run.\n *\n * Nothing is exposed to third-party tool code: the store is module-private, credentials never touch\n * a handler's `ctx`, and `currentInheritedSubAgentCredentials` is `@internal`.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { ModelSelection } from \"../../../types/agent-prims.js\";\nimport type { Plugin } from \"../../plugins/types.js\";\n\n/**\n * Credentials a parent agent hands down to its subagent tools so the child inherits the parent's\n * auth (and, absent an explicit `spec.model`, its model).\n *\n * Declared here rather than in `a2a/subagent.ts` so the delivery mechanism owns the payload shape\n * and the dependency runs one way (`a2a/subagent` -> this module). `a2a/subagent.ts` briefly\n * re-exported it \"for back-compat\"; knip proved there was no back-compat surface to preserve — the\n * type was never in the public barrel nor the exports map — so the re-export was deleted.\n *\n * Emitted rather than erased: `a2a/subagent.d.ts` imports it by name, and that entry IS published,\n * so erasing this declaration ships a `.d.ts` that does not compile. Not being in the exports map\n * is what keeps it out of the semver contract; erasure is not what does that.\n */\nexport interface InheritedCredentials {\n  readonly apiKey?: string;\n  readonly model?: ModelSelection;\n  /**\n   * The parent's shell-sandbox posture (`local.sandboxOptions.enabled`), handed down so a delegated\n   * child of a sandboxed parent stays sandboxed unless its role explicitly opts out. Without this a\n   * child ran unsandboxed whenever its role omitted `sandbox` — a default-open the sandbox wiring\n   * exists to prevent.\n   */\n  readonly sandbox?: boolean;\n  /**\n   * #55 — the parent's code-registered plugins (e.g. a `PermissionPlugin`) handed down so the child\n   * runs under the SAME policy. Without this, a delegated child's inner tool calls escape the\n   * parent's argument-level permission gate. First-party delegation path only — never exposed to\n   * third-party tool `ctx`.\n   */\n  readonly plugins?: readonly Plugin[];\n}\n\nconst credentialsStore = new AsyncLocalStorage<InheritedCredentials>();\n\n/**\n * Run `fn` with `credentials` published as the delegation credentials of the current run.\n *\n * Nested scopes shadow the outer one and the outer is restored on return, so a delegated child that\n * itself delegates hands down ITS credentials, not its parent's.\n *\n * @internal\n */\nexport async function withInheritedSubAgentCredentials<T>(\n  credentials: InheritedCredentials,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return credentialsStore.run(credentials, fn);\n}\n\n/**\n * The delegation credentials of the current run, or `undefined` outside a run scope.\n *\n * `undefined` is deliberately NOT a fallback to some previous run's value: a subagent dispatched\n * with no parent context must create its child without an inherited key rather than reuse a\n * credential that belonged to someone else.\n *\n * @internal\n */\nexport function currentInheritedSubAgentCredentials(): InheritedCredentials | undefined {\n  return credentialsStore.getStore();\n}\n","/**\n * Subagent delegation — declarative child agent invocable as a tool.\n *\n * Per ADR D2: `defineSubAgent(spec)` returns a `CustomTool` that, when\n * invoked by the LLM, creates a child agent and sends the input as a\n * message. EC-2: delegation depth is tracked across the RUN (#364) — each\n * delegation publishes its depth on the async scope its child executes in, so a\n * subagent that delegates to a subagent is bounded by `maxDelegationDepth`\n * without the caller threading a counter by hand.\n *\n * SE10 — the handler forwards the parent run's `AbortSignal` to the child.\n * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks\n * let the caller reject, rewrite, observe, or annotate a delegation.\n *\n * @public\n */\n\nimport { z } from \"zod\";\nimport {\n  currentDelegationDepth,\n  withDelegationDepth,\n} from \"../internal/runtime/concurrency/delegation-depth.js\";\nimport {\n  currentInheritedSubAgentCredentials,\n  type InheritedCredentials,\n} from \"../internal/runtime/concurrency/subagent-credentials.js\";\nimport { getAgentFacade } from \"../internal/runtime/registry/agent-factory-registry.js\";\nimport type {\n  AgentDefinition,\n  AgentOptions,\n  CustomTool,\n  ToolContextMessage,\n} from \"../types/agent.js\";\nimport type { ModelSelection } from \"../types/agent-prims.js\";\nimport type { Run } from \"../types/run.js\";\n\n/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */\nexport interface MessageFilterArgs {\n  /** The supervisor transcript (read-only text projection) available to this delegation. */\n  messages: readonly ToolContextMessage[];\n  /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */\n  input: string;\n  /** The subagent's name. */\n  name: string;\n}\n\n/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */\nexport interface DelegationStartContext {\n  input: string;\n  name: string;\n  /**\n   * SE15 — 1-based count of times THIS subagent tool has been invoked (a\n   * per-`defineSubAgent`-instance counter). Incremented before this hook runs;\n   * a rejected delegation still counts. Enables reject-after-N patterns.\n   */\n  iteration: number;\n}\n\n/**\n * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on\n * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval\n * (`modifiedInput`) cannot be mixed into one nonsensical object.\n */\nexport type DelegationStartDecision =\n  | { proceed: false; rejectionReason?: string }\n  | {\n      proceed?: true;\n      modifiedInput?: string;\n      /** SE13 — cap the child's iteration count (forwarded as `SendOptions.maxIterations`). */\n      modifiedMaxSteps?: number;\n    };\n\n/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */\nexport interface DelegationCompleteContext {\n  input: string;\n  name: string;\n  /** The child's text result (present on success). */\n  result?: string;\n  /** The error the child threw (present on failure); the error is still re-thrown. */\n  error?: unknown;\n  /** SE15 — the same 1-based iteration this delegation's `onDelegationStart` saw. */\n  iteration: number;\n}\n\n/**\n * The return of a delegation hook: a decision, a promise of one, or nothing —\n * `void` lets a side-effect-only callback (`(ctx) => { log(ctx) }`) type-check,\n * which is the common case (mirrors a peer framework's `async ctx => { ... }` hooks).\n */\n// biome-ignore lint/suspicious/noConfusingVoidType: `void` is the idiomatic return for an optional-return callback; the rule false-positives on callback return unions.\ntype DelegationHookResult<T> = T | void | Promise<T | void>;\n\n/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */\nexport interface DelegationCompleteDecision {\n  /** Appended to the child's result string. */\n  feedback?: string;\n}\n\n/**\n * The declaration of a delegating child agent, handed to `SubAgent.create(spec)`.\n *\n * `name`, `description` and `instructions` are the only required fields: the first\n * two become the tool the supervisor's model sees, the third becomes the child's\n * system prompt. Everything else narrows what the child inherits.\n *\n *   const research = SubAgent.create({\n *     name: \"research\",\n *     description: \"Look a fact up\",\n *     instructions: \"You answer with one sentence.\",\n *   });\n *   const agent = await Agent.create({ tools: [research] });\n *\n * The tool's own input schema is fixed — one required string property, `input`.\n * It is not derived from this spec and cannot be widened here.\n *\n * What the child inherits from the parent AT DISPATCH TIME, not from this object:\n * the API key, the model (unless `model` is set), the parent's plugins, and the\n * parent's sandbox posture (unless `sandbox` is set). An absent `sandbox` inherits;\n * an explicit `sandbox: false` turns confinement OFF for a child of a confined\n * parent, which is not the same thing.\n *\n * How it fails: the child's failure is re-thrown to the supervisor as a tool error\n * — a run ending in `status: \"error\"` becomes\n * `subagent \"<name>\" run failed: <cause>`. `onDelegationStart` and `messageFilter`\n * propagate their own throws; only a throw from `onDelegationComplete` ON THE\n * ERROR PATH is suppressed, so it cannot mask the real cause.\n *\n * Traps:\n *  - `model` as a bare string drops reasoning parameters. Pass the\n *    {@link ModelSelection} object form when the child needs `params`.\n *  - `maxDelegationDepth` (default 3) bounds the delegation CHAIN, counted at\n *    dispatch across the run (#364) — the depth is not something you thread. The\n *    `parentDepth` argument of `SubAgent.create` still offsets it, for a supervisor\n *    that wants a lower ceiling than the chain it sits in.\n *  - Context isolation is the DEFAULT. Without `messageFilter` the child sees only\n *    the delegated string; without `includeToolResults` the supervisor gets only\n *    the child's final text.\n */\nexport interface SubAgentSpec {\n  name: string;\n  description: string;\n  instructions: string;\n  /**\n   * A bare id string (back-compat) OR a full {@link ModelSelection} carrying\n   * `params` (e.g. `[{ id: \"thinking\", value: \"low\" }]` for reasoning effort). The\n   * object form is required for per-subagent reasoning effort to survive to the child\n   * — the pre-M33 path took only `.id` and dropped params.\n   */\n  model?: string | ModelSelection;\n  tools?: CustomTool[];\n  /** Per-subagent shell sandbox toggle (M33). `true` ⇒ child `local.sandboxOptions.enabled`. */\n  sandbox?: boolean;\n  /**\n   * Maximum length of the delegation CHAIN rooted at this tool, counted at dispatch\n   * (default 3). Depth 1 is this subagent; a subagent it delegates to is depth 2.\n   * Exceeding it throws {@link MaxDelegationDepthError} from the tool handler.\n   */\n  maxDelegationDepth?: number;\n  /**\n   * SE11 — called before the supervisor delegates. Return `{ proceed: false }`\n   * to reject (the child never runs and `rejectionReason` becomes the tool\n   * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing\n   * hook surfaces (never silently swallowed).\n   */\n  onDelegationStart?: (\n    ctx: DelegationStartContext,\n  ) => DelegationHookResult<DelegationStartDecision>;\n  /**\n   * SE11 — called after the delegation settles. On success `ctx.result` is set\n   * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is\n   * set and the original error is ALWAYS re-thrown after this hook runs — a throw\n   * from this hook on the error path is suppressed so it cannot mask the\n   * delegation's real failure (on the success path a throw does propagate).\n   */\n  onDelegationComplete?: (\n    ctx: DelegationCompleteContext,\n  ) => DelegationHookResult<DelegationCompleteDecision>;\n  /**\n   * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript\n   * (`ctx.messages`, a read-only text projection) is passed to this filter and the\n   * returned subset is forwarded to the child as a role-tagged context preamble\n   * prepended to the delegated input. When ABSENT the child runs input-only —\n   * memory isolation stays the default. A filter returning `[]` forwards nothing.\n   * A throwing filter propagates (fail-fast, never swallowed — same contract as\n   * `onDelegationStart`); the delegation surfaces as a tool error.\n   */\n  messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];\n  /**\n   * SE14 — opt-in subagent result-context control. When `true`, the child's\n   * completed tool-call results (name + result) are appended to the delegation\n   * payload returned to the supervisor, inside a `<subagent-tool-results>` block.\n   * When absent/`false` the delegation returns the child's final text only —\n   * text-only stays the default (a peer framework's scoped posture). See ADR 0006.\n   */\n  includeToolResults?: boolean;\n}\n\n/**\n * Raised by `SubAgent.create(spec, parentDepth)` when `parentDepth + 1` exceeds\n * `spec.maxDelegationDepth` (default 3). Carries `currentDepth`, `maxDepth` and a\n * stable `code: \"max_delegation_depth\"`.\n *\n * Thrown from the subagent tool's handler when a delegation would exceed\n * `maxDelegationDepth` (default 3), so it surfaces as the tool call's failure —\n * catching it around the dispatching `agent.send()` works.\n *\n * Also thrown eagerly at TOOL-CONSTRUCTION time when a caller threads its own\n * `parentDepth` that is already past the limit; such a tool could never be\n * dispatched, so refusing to build it fails earlier and clearer.\n *\n * Before #364 the construction-time check was the ONLY one, against a depth\n * nothing in the SDK incremented — so under the documented `SubAgent.create(spec)`\n * call this error could not fire at all and nested delegation was unbounded. The\n * chain length now travels with the run (`internal/runtime/concurrency/delegation-depth.ts`),\n * and a caller-threaded `parentDepth` still adds to it.\n */\nexport class MaxDelegationDepthError extends Error {\n  readonly code = \"max_delegation_depth\" as const;\n  constructor(\n    public readonly currentDepth: number,\n    public readonly maxDepth: number,\n  ) {\n    super(`Max delegation depth ${maxDepth} exceeded (current: ${currentDepth})`);\n    this.name = \"MaxDelegationDepthError\";\n  }\n}\n\n/**\n * Run the `onDelegationStart` hook; returns either a rejection or the (possibly\n * rewritten) input plus the optional SE13 `maxSteps` cap.\n */\nasync function applyDelegationStart(\n  spec: SubAgentSpec,\n  input: string,\n  iteration: number,\n): Promise<{ reject: string } | { input: string; maxSteps?: number }> {\n  if (spec.onDelegationStart === undefined) return { input };\n  const decision = await spec.onDelegationStart({ input, name: spec.name, iteration });\n  if (decision === undefined) return { input };\n  if (decision.proceed === false)\n    return { reject: decision.rejectionReason ?? \"(delegation rejected)\" };\n  return {\n    input: decision.modifiedInput ?? input,\n    ...(decision.modifiedMaxSteps !== undefined ? { maxSteps: decision.modifiedMaxSteps } : {}),\n  };\n}\n\n/**\n * SE14 — replay the child run's stream (a safe post-`wait()` idiom — the run buffers\n * events, `stream()` replays them) and collect every completed tool-call result into\n * a delimited block. Returns `\"\"` when the child ran no completed tool calls. See ADR 0006.\n */\nasync function collectChildToolResults(run: Run): Promise<string> {\n  const lines: string[] = [];\n  for await (const event of run.stream()) {\n    if (event.type === \"tool_call\" && event.status === \"completed\") {\n      const rendered =\n        typeof event.result === \"string\" ? event.result : JSON.stringify(event.result ?? null);\n      lines.push(`${event.name}: ${rendered}`);\n    }\n  }\n  if (lines.length === 0) return \"\";\n  return `\\n\\n<subagent-tool-results>\\n${lines.join(\"\\n\")}\\n</subagent-tool-results>`;\n}\n\n/**\n * Build the child agent's `Agent.create` options: the child inherits the parent's\n * apiKey (else `Agent.create` throws \"Missing API key\"), its model (unless the spec\n * overrides it), and — #55 — the parent's plugins (permission gate/guards) so the\n * child's inner tool calls run under the same policy.\n */\nexport function buildChildCreateOptions(\n  spec: SubAgentSpec,\n  inherited: InheritedCredentials | undefined,\n): AgentOptions {\n  // M33 — carry the WHOLE model (a bare id becomes `{ id }`; a ModelSelection with\n  // `params` keeps its reasoning effort). The pre-M33 path wrapped `spec.model` as\n  // `{ id: spec.model }`, which only worked because spec.model was a string and\n  // silently dropped reasoning params.\n  const model: string | ModelSelection | undefined =\n    spec.model !== undefined\n      ? typeof spec.model === \"string\"\n        ? { id: spec.model }\n        : spec.model\n      : inherited?.model;\n  // M33 — the role's own `sandbox` wins; when it omits the field, inherit the parent's posture. A role's\n  // explicit `sandbox: false` therefore confines-OFF a child of a sandboxed parent (distinct from absent).\n  const sandbox = spec.sandbox ?? inherited?.sandbox;\n  return {\n    ...(inherited?.apiKey !== undefined ? { apiKey: inherited.apiKey } : {}),\n    ...(model !== undefined ? { model } : {}),\n    ...(sandbox !== undefined ? { local: { sandboxOptions: { enabled: sandbox } } } : {}),\n    ...(inherited?.plugins !== undefined ? { plugins: inherited.plugins } : {}),\n    systemPrompt: spec.instructions,\n    tools: spec.tools ?? [],\n  };\n}\n\n/**\n * Create the transient child agent and send the input, composing every forwarded\n * `SendOptions` onto ONE `send` call — SE10 `signal` + SE13 `maxIterations`. Absent\n * every option ⇒ the pre-SE10 single-arg `send(input)` shape. SE14 — when\n * `includeToolResults` is set, append the child's completed tool results. Dispose in `finally`.\n */\nasync function runChildAgent(\n  spec: SubAgentSpec,\n  input: string,\n  signal: AbortSignal | undefined,\n  maxSteps: number | undefined,\n  inherited: InheritedCredentials | undefined,\n  depth: number,\n): Promise<string> {\n  // #364 — publish THIS delegation's depth for the whole child run. The child's loop, and every\n  // tool it dispatches, runs inside this scope, so a nested subagent reads the real chain length\n  // instead of the 0 every construction-time check saw.\n  return withDelegationDepth(depth, () =>\n    runChildAgentInScope(spec, input, signal, maxSteps, inherited),\n  );\n}\n\nasync function runChildAgentInScope(\n  spec: SubAgentSpec,\n  input: string,\n  signal: AbortSignal | undefined,\n  maxSteps: number | undefined,\n  inherited: InheritedCredentials | undefined,\n): Promise<string> {\n  // SE45 cycle 3 — use the registered Agent facade via the DIP seam\n  // (agent-factory-registry) instead of a dynamic `import(\"../agent.js\")`.\n  // This removes the last madge cycle (a2a/subagent -> agent -> ... -> real-local-run-tools\n  // -> a2a/subagent): the facade registers itself at module-init via setAgentFacade,\n  // so subagent depends only on the registry port, never on the facade module.\n  const agent = await getAgentFacade().create(buildChildCreateOptions(spec, inherited));\n  try {\n    const sendOptions: {\n      signal?: AbortSignal;\n      maxIterations?: number;\n      origin?: import(\"../types/run.js\").MessageOrigin;\n    } = {\n      ...(signal !== undefined ? { signal } : {}),\n      ...(maxSteps !== undefined ? { maxIterations: maxSteps } : {}),\n      // SE3 — a delegated child's turn is initiated by the coordinating parent.\n      origin: { kind: \"coordinator\" },\n    };\n    const run = await agent.send(input, sendOptions);\n    const result = await run.wait();\n    // Fail-fast, don't swallow (Rule 8): a child that ended in error must surface — otherwise a real\n    // failure (e.g. `provider_unresolved`) is hidden behind \"(no response)\" and the parent loops on it.\n    if (result.status === \"error\") {\n      const cause = (result as { error?: { message?: string } }).error;\n      throw new Error(\n        `subagent \"${spec.name}\" run failed: ${cause?.message ?? \"unknown error\"}`,\n        cause !== undefined ? { cause } : undefined,\n      );\n    }\n    const text = result.result ?? \"(no response)\";\n    // SE14 — text-only by default; opt-in appends the child's tool results.\n    return spec.includeToolResults === true ? text + (await collectChildToolResults(run)) : text;\n  } finally {\n    agent.dispose();\n  }\n}\n\n/**\n * Best-effort error-path notification: run `onDelegationComplete` with the child's\n * error so the caller can observe the failure. The observer's own throw (sync or\n * async) is suppressed here so it cannot mask the delegation's real error, which the\n * handler re-throws next.\n */\nasync function notifyDelegationError(\n  spec: SubAgentSpec,\n  input: string,\n  error: unknown,\n  iteration: number,\n): Promise<void> {\n  if (spec.onDelegationComplete === undefined) return;\n  try {\n    await spec.onDelegationComplete({ input, name: spec.name, error, iteration });\n  } catch {\n    // Subordinate to `error`; the child's real cause wins.\n  }\n}\n\n/**\n * SE12 — apply `messageFilter` (if set) and prepend the filtered supervisor\n * transcript to the delegated input as a role-tagged context preamble. Absent\n * filter OR no messages OR an empty filtered subset ⇒ the original input\n * (isolation-by-default preserved).\n */\nfunction applyMessageFilter(\n  spec: SubAgentSpec,\n  input: string,\n  messages: readonly ToolContextMessage[] | undefined,\n): string {\n  if (spec.messageFilter === undefined || messages === undefined) return input;\n  const filtered = spec.messageFilter({ messages, input, name: spec.name });\n  if (filtered.length === 0) return input;\n  const preamble = filtered.map((m) => `${m.role}: ${m.content}`).join(\"\\n\");\n  return `Prior conversation:\\n${preamble}\\n\\nTask:\\n${input}`;\n}\n\n/** Run the success-path `onDelegationComplete` hook; appends its `feedback` to the result. */\nasync function applyDelegationComplete(\n  spec: SubAgentSpec,\n  input: string,\n  result: string,\n  iteration: number,\n): Promise<string> {\n  if (spec.onDelegationComplete === undefined) return result;\n  const completion = await spec.onDelegationComplete({ input, name: spec.name, result, iteration });\n  return completion?.feedback !== undefined ? result + completion.feedback : result;\n}\n\nfunction defineSubAgent(spec: SubAgentSpec, _parentDepth = 0): CustomTool {\n  const maxDepth = spec.maxDelegationDepth ?? 3;\n\n  // A caller that threads its own depth still gets the eager failure it always got: a spec that is\n  // already too deep to ever be dispatchable is worth refusing at construction. What this check\n  // CANNOT see is the runtime chain — constructing a tool says nothing about how deep it will later\n  // be invoked — which is why the guard that actually bounds recursion lives at dispatch (#364).\n  if (_parentDepth + 1 > maxDepth) {\n    throw new MaxDelegationDepthError(_parentDepth + 1, maxDepth);\n  }\n\n  // Zod for RUNTIME validation of the tool_use input …\n  const inputZod = z.object({\n    input: z.string().describe(\"Task for the subagent\"),\n  });\n  // … and a real Draft-7 JSON Schema for the LLM. `CustomTool.inputSchema` is sent\n  // to the model verbatim; a raw Zod object would serialize to garbage, so the\n  // model emits malformed input that fails `inputZod.parse` and the delegation\n  // never runs (the previous bug — the schema and the validator are now distinct).\n  const inputSchema: Record<string, unknown> = {\n    type: \"object\",\n    properties: {\n      input: { type: \"string\", description: \"Task for the subagent\" },\n    },\n    required: [\"input\"],\n    additionalProperties: false,\n  };\n\n  // SE15 — per-instance delegation counter, surfaced as `iteration` on the hook\n  // contexts. Incremented once per handler invocation before onDelegationStart.\n  let iteration = 0;\n\n  const tool: CustomTool = {\n    name: spec.name,\n    description: spec.description,\n    inputSchema,\n    handler: async (\n      rawInput: Record<string, unknown>,\n      ctx?: {\n        signal?: AbortSignal;\n        context?: unknown;\n        messages?: readonly ToolContextMessage[];\n      },\n    ): Promise<string> => {\n      const { input: parsed } = inputZod.parse(rawInput);\n      // theokit#148 — read the parent's credentials from the RUN's async scope, at dispatch time.\n      // They used to be stashed on this tool object by the runtime, which meant any layer that\n      // rebuilt the object (e.g. `@theokit/agents`' `toCompiledTool`) silently dropped them and the\n      // child failed with `provider_unresolved`. The scope travels with the call, so nothing about\n      // the object's shape matters — and two concurrent runs sharing one tool each read their own.\n      const inherited = currentInheritedSubAgentCredentials();\n      // #364 — the real bound. `currentDelegationDepth()` is the length of the chain that led here,\n      // published by each ancestor's `runChildAgent`; a caller-threaded `_parentDepth` still adds to\n      // it, so the pre-#364 hand-threaded behaviour is unchanged when the ambient depth is 0.\n      const currentDepth = _parentDepth + currentDelegationDepth() + 1;\n      if (currentDepth > maxDepth) {\n        throw new MaxDelegationDepthError(currentDepth, maxDepth);\n      }\n      iteration += 1; // SE15 — before onDelegationStart; a rejected delegation still counts.\n      // Pin THIS invocation's iteration before any await so a concurrent invocation\n      // bumping the shared counter cannot change the value onDelegationComplete /\n      // notifyDelegationError observe — they see the same iteration onDelegationStart did.\n      const capturedIteration = iteration;\n\n      const start = await applyDelegationStart(spec, parsed, capturedIteration);\n      if (\"reject\" in start) return start.reject;\n      // SE12 — opt-in: forward the filtered supervisor transcript as a preamble.\n      const input = applyMessageFilter(spec, start.input, ctx?.messages);\n\n      let result: string;\n      try {\n        // SE13 — apply the optional onDelegationStart maxSteps cap on the child send.\n        result = await runChildAgent(\n          spec,\n          input,\n          ctx?.signal,\n          start.maxSteps,\n          inherited,\n          currentDepth,\n        );\n      } catch (error) {\n        // SE11 — notify the completion hook of the failure (best-effort observer),\n        // then re-throw the ORIGINAL error (Rule 8: never swallow the delegation's\n        // own failure).\n        await notifyDelegationError(spec, input, error, capturedIteration);\n        throw error;\n      }\n      return applyDelegationComplete(spec, input, result, capturedIteration);\n    },\n  };\n\n  // theokit#148 — nothing is installed on the tool. The credentials arrive through the run's async\n  // scope (see `internal/runtime/concurrency/subagent-credentials.ts`), so there is no extra\n  // property for a normalizing layer to drop.\n  return tool;\n}\n\n/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public */\nexport class SubAgent {\n  private constructor() {}\n  static create(spec: SubAgentSpec, parentDepth = 0): CustomTool {\n    return defineSubAgent(spec, parentDepth);\n  }\n}\n\n/**\n * Convert a parent's declarative `agents` map ({@link AgentDefinition} per key)\n * into delegation tools for the LOCAL runtime — the counterpart of the\n * cloud/fixture subagent wiring. Each child inherits the parent's `apiKey`/model\n * from the CALL, not from the tool object: `inheritSubAgentCredentials` used to\n * attach them to the tool, and any layer that rebuilt that object dropped them —\n * including the SDK's own rebuild (theokit#148). Credentials now ride the\n * dispatch, so a rebuilt tool cannot lose them. `def.model` overrides the model\n * (`\"inherit\"` keeps the parent's), and `def.tools` scopes the child to that\n * subset of the parent's tools (absent → the parent's full toolset, per the\n * `AgentDefinition.tools` contract).\n *\n * M33 — per-subagent `model` (with reasoning `params`) and `sandbox` are now wired\n * into local delegation: each is carried onto the {@link SubAgentSpec} and applied to\n * the child in {@link buildChildCreateOptions}. `\"inherit\"` (or an absent field) keeps\n * the parent's value. Per-subagent `mcp` is rejected at load (see subagents-loader) —\n * resolving server names→config on the local path is a follow-up.\n *\n * @internal\n */\nexport function subAgentToolsFromDefinitions(\n  agents: Record<string, AgentDefinition>,\n  parentTools: readonly CustomTool[],\n): CustomTool[] {\n  return Object.entries(agents).map(([name, def]) => {\n    const whitelist =\n      Array.isArray(def.tools) && def.tools.length > 0 ? new Set(def.tools) : undefined;\n    const childTools = whitelist ? parentTools.filter((t) => whitelist.has(t.name)) : parentTools;\n    return defineSubAgent({\n      name,\n      description: def.description,\n      instructions: def.prompt,\n      // Carry the FULL ModelSelection (id + reasoning params), not just the id, so\n      // per-subagent reasoning effort survives to buildChildCreateOptions.\n      ...(def.model !== undefined && def.model !== \"inherit\" ? { model: def.model } : {}),\n      ...(def.sandbox !== undefined ? { sandbox: def.sandbox } : {}),\n      tools: [...childTools],\n    });\n  });\n}\n"]}

package/dist/{chunk-GD63JPGC.cjs → chunk-ROYPRJH4.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkCZ2GKKYL_cjs = require('./chunk-CZ2GKKYL.cjs');
+var chunkQDED6YO6_cjs = require('./chunk-QDED6YO6.cjs');
 
 // src/stream-object.ts
 var StreamObjectError = class extends Error {
@@ -14,19 +14,19 @@ var StreamObjectError = class extends Error {
   }
 };
 async function* streamObjectImpl(options, deps) {
-  const { jsonSchema, maxRetries, initialUsage } = chunkCZ2GKKYL_cjs.setupStructuredOutput(
+  const { jsonSchema, maxRetries, initialUsage } = chunkQDED6YO6_cjs.setupStructuredOutput(
     options.schema,
     options.maxRetries
   );
   let capturedRaw;
   let lastUsage = initialUsage;
-  const outputTool = chunkCZ2GKKYL_cjs.makeOutputTool(jsonSchema, (input) => {
+  const outputTool = chunkQDED6YO6_cjs.makeOutputTool(jsonSchema, (input) => {
     if (capturedRaw === void 0) {
       capturedRaw = input;
     }
     return JSON.stringify({ ok: true });
   });
-  const agentOptions = chunkCZ2GKKYL_cjs.buildTransientAgentOptions({
+  const agentOptions = chunkQDED6YO6_cjs.buildTransientAgentOptions({
     model: options.model,
     local: options.local,
     outputTool,
@@ -35,7 +35,7 @@ async function* streamObjectImpl(options, deps) {
     ...options.providers !== void 0 ? { providers: options.providers } : {}
   });
   const agent = await deps.create(agentOptions);
-  const userMessage = chunkCZ2GKKYL_cjs.buildToolPrompt(options.prompt);
+  const userMessage = chunkQDED6YO6_cjs.buildToolPrompt(options.prompt);
   try {
     let lastParseError;
     let attemptCounter = 0;
@@ -61,7 +61,7 @@ async function* streamObjectImpl(options, deps) {
         }
       }
       const result = await run.wait();
-      lastUsage = chunkCZ2GKKYL_cjs.extractUsage(result);
+      lastUsage = chunkQDED6YO6_cjs.extractUsage(result);
       if (capturedRaw === void 0) {
         if (result.status === "error" && result.error !== void 0) {
           throw new StreamObjectError(
@@ -97,7 +97,7 @@ async function* streamObjectImpl(options, deps) {
       lastParseError
     );
   } finally {
-    await chunkCZ2GKKYL_cjs.disposeAndDeleteTransient(agent, deps.delete);
+    await chunkQDED6YO6_cjs.disposeAndDeleteTransient(agent, deps.delete);
   }
 }
 function bestEffortPartialParse(text, schema) {
@@ -144,5 +144,5 @@ function bestEffortPartialParse(text, schema) {
 
 exports.StreamObjectError = StreamObjectError;
 exports.streamObjectImpl = streamObjectImpl;
-//# sourceMappingURL=chunk-GD63JPGC.cjs.map
-//# sourceMappingURL=chunk-GD63JPGC.cjs.map
+//# sourceMappingURL=chunk-ROYPRJH4.cjs.map
+//# sourceMappingURL=chunk-ROYPRJH4.cjs.map

package/dist/{chunk-GD63JPGC.cjs.map → chunk-ROYPRJH4.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/stream-object.ts"],"names":["setupStructuredOutput","makeOutputTool","buildTransientAgentOptions","buildToolPrompt","extractUsage","disposeAndDeleteTransient"],"mappings":"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","file":"chunk-GD63JPGC.cjs","sourcesContent":["import type { z as ZodNamespace, ZodType } from \"zod\";\n\nimport {\n  buildToolPrompt,\n  buildTransientAgentOptions,\n  disposeAndDeleteTransient,\n  extractUsage,\n  makeOutputTool,\n  setupStructuredOutput,\n} from \"./internal/structured-output-helpers.js\";\nimport type { AgentOptions, LocalOptions, ModelSelection, SDKAgent } from \"./types/agent.js\";\nimport type { ProviderRoutingSettings } from \"./types/providers.js\";\n\n/**\n * Options accepted by {@link Agent.streamObject}. Same shape as\n * `Agent.generateObject` with the addition that the result is an\n * `AsyncIterator<StreamObjectEvent<T>>` rather than a single Promise. See ADR D39.\n *\n * @public\n */\nexport interface StreamObjectOptions<T extends ZodType> {\n  schema: T;\n  prompt: string;\n  systemPrompt?: string;\n  /** SE8 — accepts a bare-string id shorthand or a {@link ModelSelection}. */\n  model: string | ModelSelection;\n  apiKey?: string;\n  local: LocalOptions;\n  maxRetries?: number;\n  /**\n   * Optional provider routing forwarded to the transient agent. Required when\n   * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is\n   * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers\n   * provider from the prefix and may fail with `provider_unresolved` even\n   * when the right env key is set under a different provider name.\n   */\n  providers?: ProviderRoutingSettings;\n}\n\n/**\n * Recursive partial — `T` where every nested field becomes optional.\n *\n * @public\n */\nexport type DeepPartial<T> = T extends (infer U)[]\n  ? Array<DeepPartial<U>>\n  : T extends object\n    ? { [K in keyof T]?: DeepPartial<T[K]> }\n    : T;\n\n/**\n * Event emitted by {@link Agent.streamObject}. Discriminate on `type`.\n *\n * - `partial` events fire zero or more times with monotonically increasing\n *   `attempt`, carrying best-effort schema-parsed snapshots of the model's\n *   accumulating output.\n * - `complete` fires exactly once at the end, carrying the fully Zod-parsed\n *   object alongside usage and finishReason — semantically identical to a\n *   successful `Agent.generateObject()` return.\n *\n * @public\n */\nexport type StreamObjectEvent<T> =\n  | { type: \"partial\"; partial: DeepPartial<T>; attempt: number }\n  | {\n      type: \"complete\";\n      object: T;\n      raw: unknown;\n      usage: { inputTokens: number; outputTokens: number };\n      finishReason: \"tool_use\" | \"error\";\n    };\n\n/**\n * Error thrown by {@link Agent.streamObject} when the model refuses to call\n * the synthetic `output` tool or when all retries fail to produce a\n * schema-valid object. Same code taxonomy as `GenerateObjectError`.\n *\n * @public\n */\nexport class StreamObjectError extends Error {\n  override readonly name = \"StreamObjectError\";\n  readonly code: \"no_tool_call\" | \"parse_failed\";\n  override readonly cause?: unknown;\n  constructor(code: \"no_tool_call\" | \"parse_failed\", message: string, cause?: unknown) {\n    super(message);\n    this.code = code;\n    if (cause !== undefined) this.cause = cause;\n  }\n}\n\ninterface StreamObjectDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n  delete: (agentId: string) => Promise<void>;\n}\n\n/**\n * Implementation of `Agent.streamObject` as an async generator. Mirrors the\n * synthetic-forced-tool pattern from `generate-object.ts` (ADR D33) with the\n * addition of intermediate `partial` events emitted from incremental parsing\n * of accumulating text deltas during the agent loop.\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: streaming loop interleaves text-delta accumulation, partial-parse attempts, retries, and final dispose — splitting harms locality of the iterator contract.\nexport async function* streamObjectImpl<T extends ZodType>(\n  options: StreamObjectOptions<T>,\n  deps: StreamObjectDeps,\n): AsyncGenerator<StreamObjectEvent<ZodNamespace.infer<T>>, void, void> {\n  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(\n    options.schema,\n    options.maxRetries,\n  );\n  let capturedRaw: unknown;\n  let lastUsage = initialUsage;\n\n  const outputTool = makeOutputTool(jsonSchema, (input) => {\n    // EC-6: first capture wins (parallel tool use in Claude 3.5+).\n    if (capturedRaw === undefined) {\n      capturedRaw = input;\n    }\n    return JSON.stringify({ ok: true });\n  });\n\n  const agentOptions: AgentOptions = buildTransientAgentOptions({\n    model: options.model,\n    local: options.local,\n    outputTool,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n  });\n  const agent = await deps.create(agentOptions);\n  const userMessage = buildToolPrompt(options.prompt);\n\n  try {\n    let lastParseError: unknown;\n    let attemptCounter = 0;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {\n      capturedRaw = undefined;\n      const run = await agent.send(userMessage);\n\n      // Buffer text deltas during streaming; try partial-parse on each.\n      let textBuffer = \"\";\n      for await (const msg of run.stream()) {\n        if (msg.type === \"assistant\") {\n          const newText = msg.message.content\n            .filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n            .map((c) => c.text)\n            .join(\"\");\n          if (newText.length > 0) {\n            textBuffer += newText;\n            const partial = bestEffortPartialParse(textBuffer, options.schema);\n            if (partial !== undefined) {\n              attemptCounter += 1;\n              yield {\n                type: \"partial\",\n                partial: partial as DeepPartial<ZodNamespace.infer<T>>,\n                attempt: attemptCounter,\n              };\n            }\n          }\n        }\n      }\n      const result = await run.wait();\n      lastUsage = extractUsage(result);\n\n      if (capturedRaw === undefined) {\n        // EC: when the underlying run errored (e.g. provider_unresolved),\n        // surface the original cause instead of the misleading \"model\n        // returned text\" message — there was no model call at all.\n        if (result.status === \"error\" && result.error !== undefined) {\n          throw new StreamObjectError(\n            \"no_tool_call\",\n            `Agent run failed before the model could reply: ${result.error.message ?? \"unknown error\"} [${result.error.code ?? \"?\"}]`,\n            result.error,\n          );\n        }\n        if (attempt === maxRetries) {\n          throw new StreamObjectError(\n            \"no_tool_call\",\n            \"The model returned text instead of calling the `output` tool.\",\n          );\n        }\n        continue;\n      }\n\n      const parsed = options.schema.safeParse(capturedRaw);\n      if (parsed.success) {\n        yield {\n          type: \"complete\",\n          object: parsed.data,\n          raw: capturedRaw,\n          usage: lastUsage,\n          finishReason: \"tool_use\",\n        };\n        return;\n      }\n      lastParseError = parsed.error;\n    }\n\n    throw new StreamObjectError(\n      \"parse_failed\",\n      \"Schema parse failed after all retries.\",\n      lastParseError,\n    );\n  } finally {\n    // EC-4: even if consumer calls iter.return() mid-stream, this finally\n    // runs — transient agent is disposed AND removed from registry.\n    await disposeAndDeleteTransient(agent, deps.delete);\n  }\n}\n\n/**\n * Try to extract a partial JSON object from a possibly-incomplete text\n * buffer and parse it via the schema in lenient mode. Returns `undefined`\n * if nothing parseable is found yet.\n *\n * Strategy: find the first `{`, find the LAST balanced `}` (greedy), parse\n * the substring as JSON, then `safeParse` against `schema.partial()` if the\n * schema supports it, else against the original schema.\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: stateful JSON-balancing scanner — string/brace/escape state must be co-located for the parser to remain correct.\nfunction bestEffortPartialParse<T extends ZodType>(text: string, schema: T): unknown | undefined {\n  const start = text.indexOf(\"{\");\n  if (start < 0) return undefined;\n  // Find the longest balanced JSON object from `start`.\n  let depth = 0;\n  let inString = false;\n  let isEscaped = false;\n  let end = -1;\n  for (let i = start; i < text.length; i += 1) {\n    const ch = text[i];\n    if (isEscaped) {\n      isEscaped = false;\n      continue;\n    }\n    if (ch === \"\\\\\" && inString) {\n      isEscaped = true;\n      continue;\n    }\n    if (ch === '\"') {\n      inString = !inString;\n      continue;\n    }\n    if (inString) continue;\n    if (ch === \"{\") depth += 1;\n    else if (ch === \"}\") {\n      depth -= 1;\n      if (depth === 0) end = i;\n    }\n  }\n  if (end < 0) return undefined;\n  const candidate = text.slice(start, end + 1);\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(candidate);\n  } catch {\n    return undefined;\n  }\n  // Try schema.partial() if available (Zod objects support it); else fall\n  // back to the original schema (loose match).\n  const maybePartial = (schema as unknown as { partial?: () => ZodType }).partial;\n  const looseSchema = typeof maybePartial === \"function\" ? maybePartial.call(schema) : schema;\n  const result = looseSchema.safeParse(parsed);\n  return result.success ? result.data : undefined;\n}\n"]}
+{"version":3,"sources":["../src/stream-object.ts"],"names":["setupStructuredOutput","makeOutputTool","buildTransientAgentOptions","buildToolPrompt","extractUsage","disposeAndDeleteTransient"],"mappings":";;;;;AA+EO,IAAM,iBAAA,GAAN,cAAgC,KAAA,CAAM;AAAA,EACzB,IAAA,GAAO,mBAAA;AAAA,EAChB,IAAA;AAAA,EACS,KAAA;AAAA,EAClB,WAAA,CAAY,IAAA,EAAuC,OAAA,EAAiB,KAAA,EAAiB;AACnF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AACZ,IAAA,IAAI,KAAA,KAAU,MAAA,EAAW,IAAA,CAAK,KAAA,GAAQ,KAAA;AAAA,EACxC;AACF;AA6BA,gBAAuB,gBAAA,CACrB,SACA,IAAA,EACsE;AACtE,EAAA,MAAM,EAAE,UAAA,EAAY,UAAA,EAAY,YAAA,EAAa,GAAIA,uCAAA;AAAA,IAC/C,OAAA,CAAQ,MAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,IAAI,WAAA;AACJ,EAAA,IAAI,SAAA,GAAY,YAAA;AAEhB,EAAA,MAAM,UAAA,GAAaC,gCAAA,CAAe,UAAA,EAAY,CAAC,KAAA,KAAU;AAEvD,IAAA,IAAI,gBAAgB,MAAA,EAAW;AAC7B,MAAA,WAAA,GAAc,KAAA;AAAA,IAChB;AACA,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,EAAE,EAAA,EAAI,MAAM,CAAA;AAAA,EACpC,CAAC,CAAA;AAED,EAAA,MAAM,eAA6BC,4CAAA,CAA2B;AAAA,IAC5D,OAAO,OAAA,CAAQ,KAAA;AAAA,IACf,OAAO,OAAA,CAAQ,KAAA;AAAA,IACf,UAAA;AAAA,IACA,GAAI,QAAQ,YAAA,KAAiB,MAAA,GAAY,EAAE,YAAA,EAAc,OAAA,CAAQ,YAAA,EAAa,GAAI,EAAC;AAAA,IACnF,GAAI,QAAQ,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,OAAA,CAAQ,MAAA,EAAO,GAAI,EAAC;AAAA,IACjE,GAAI,QAAQ,SAAA,KAAc,MAAA,GAAY,EAAE,SAAA,EAAW,OAAA,CAAQ,SAAA,EAAU,GAAI;AAAC,GAC3E,CAAA;AACD,EAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,YAAY,CAAA;AAC5C,EAAA,MAAM,WAAA,GAAcC,iCAAA,CAAgB,OAAA,CAAQ,MAAM,CAAA;AAElD,EAAA,IAAI;AACF,IAAA,IAAI,cAAA;AACJ,IAAA,IAAI,cAAA,GAAiB,CAAA;AAErB,IAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,UAAA,EAAY,WAAW,CAAA,EAAG;AACzD,MAAA,WAAA,GAAc,KAAA,CAAA;AACd,MAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,IAAA,CAAK,WAAW,CAAA;AAGxC,MAAA,IAAI,UAAA,GAAa,EAAA;AACjB,MAAA,WAAA,MAAiB,GAAA,IAAO,GAAA,CAAI,MAAA,EAAO,EAAG;AACpC,QAAA,IAAI,GAAA,CAAI,SAAS,WAAA,EAAa;AAC5B,UAAA,MAAM,UAAU,GAAA,CAAI,OAAA,CAAQ,QACzB,MAAA,CAAO,CAAC,MAA2C,CAAA,CAAE,IAAA,KAAS,MAAM,CAAA,CACpE,IAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA,CACjB,KAAK,EAAE,CAAA;AACV,UAAA,IAAI,OAAA,CAAQ,SAAS,CAAA,EAAG;AACtB,YAAA,UAAA,IAAc,OAAA;AACd,YAAA,MAAM,OAAA,GAAU,sBAAA,CAAuB,UAAA,EAAY,OAAA,CAAQ,MAAM,CAAA;AACjE,YAAA,IAAI,YAAY,KAAA,CAAA,EAAW;AACzB,cAAA,cAAA,IAAkB,CAAA;AAClB,cAAA,MAAM;AAAA,gBACJ,IAAA,EAAM,SAAA;AAAA,gBACN,OAAA;AAAA,gBACA,OAAA,EAAS;AAAA,eACX;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAAA,MACF;AACA,MAAA,MAAM,MAAA,GAAS,MAAM,GAAA,CAAI,IAAA,EAAK;AAC9B,MAAA,SAAA,GAAYC,+BAAa,MAAM,CAAA;AAE/B,MAAA,IAAI,gBAAgB,KAAA,CAAA,EAAW;AAI7B,QAAA,IAAI,MAAA,CAAO,MAAA,KAAW,OAAA,IAAW,MAAA,CAAO,UAAU,KAAA,CAAA,EAAW;AAC3D,UAAA,MAAM,IAAI,iBAAA;AAAA,YACR,cAAA;AAAA,YACA,CAAA,+CAAA,EAAkD,OAAO,KAAA,CAAM,OAAA,IAAW,eAAe,CAAA,EAAA,EAAK,MAAA,CAAO,KAAA,CAAM,IAAA,IAAQ,GAAG,CAAA,CAAA,CAAA;AAAA,YACtH,MAAA,CAAO;AAAA,WACT;AAAA,QACF;AACA,QAAA,IAAI,YAAY,UAAA,EAAY;AAC1B,UAAA,MAAM,IAAI,iBAAA;AAAA,YACR,cAAA;AAAA,YACA;AAAA,WACF;AAAA,QACF;AACA,QAAA;AAAA,MACF;AAEA,MAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,MAAA,CAAO,SAAA,CAAU,WAAW,CAAA;AACnD,MAAA,IAAI,OAAO,OAAA,EAAS;AAClB,QAAA,MAAM;AAAA,UACJ,IAAA,EAAM,UAAA;AAAA,UACN,QAAQ,MAAA,CAAO,IAAA;AAAA,UACf,GAAA,EAAK,WAAA;AAAA,UACL,KAAA,EAAO,SAAA;AAAA,UACP,YAAA,EAAc;AAAA,SAChB;AACA,QAAA;AAAA,MACF;AACA,MAAA,cAAA,GAAiB,MAAA,CAAO,KAAA;AAAA,IAC1B;AAEA,IAAA,MAAM,IAAI,iBAAA;AAAA,MACR,cAAA;AAAA,MACA,wCAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF,CAAA,SAAE;AAGA,IAAA,MAAMC,2CAAA,CAA0B,KAAA,EAAO,IAAA,CAAK,MAAM,CAAA;AAAA,EACpD;AACF;AAcA,SAAS,sBAAA,CAA0C,MAAc,MAAA,EAAgC;AAC/F,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AAC9B,EAAA,IAAI,KAAA,GAAQ,GAAG,OAAO,MAAA;AAEtB,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,IAAI,QAAA,GAAW,KAAA;AACf,EAAA,IAAI,SAAA,GAAY,KAAA;AAChB,EAAA,IAAI,GAAA,GAAM,EAAA;AACV,EAAA,KAAA,IAAS,IAAI,KAAA,EAAO,CAAA,GAAI,IAAA,CAAK,MAAA,EAAQ,KAAK,CAAA,EAAG;AAC3C,IAAA,MAAM,EAAA,GAAK,KAAK,CAAC,CAAA;AACjB,IAAA,IAAI,SAAA,EAAW;AACb,MAAA,SAAA,GAAY,KAAA;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI,EAAA,KAAO,QAAQ,QAAA,EAAU;AAC3B,MAAA,SAAA,GAAY,IAAA;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAO,GAAA,EAAK;AACd,MAAA,QAAA,GAAW,CAAC,QAAA;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI,QAAA,EAAU;AACd,IAAA,IAAI,EAAA,KAAO,KAAK,KAAA,IAAS,CAAA;AAAA,SAAA,IAChB,OAAO,GAAA,EAAK;AACnB,MAAA,KAAA,IAAS,CAAA;AACT,MAAA,IAAI,KAAA,KAAU,GAAG,GAAA,GAAM,CAAA;AAAA,IACzB;AAAA,EACF;AACA,EAAA,IAAI,GAAA,GAAM,GAAG,OAAO,MAAA;AACpB,EAAA,MAAM,SAAA,GAAY,IAAA,CAAK,KAAA,CAAM,KAAA,EAAO,MAAM,CAAC,CAAA;AAC3C,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,SAAS,CAAA;AAAA,EAC/B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AAGA,EAAA,MAAM,eAAgB,MAAA,CAAkD,OAAA;AACxE,EAAA,MAAM,cAAc,OAAO,YAAA,KAAiB,aAAa,YAAA,CAAa,IAAA,CAAK,MAAM,CAAA,GAAI,MAAA;AACrF,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,SAAA,CAAU,MAAM,CAAA;AAC3C,EAAA,OAAO,MAAA,CAAO,OAAA,GAAU,MAAA,CAAO,IAAA,GAAO,MAAA;AACxC","file":"chunk-ROYPRJH4.cjs","sourcesContent":["import type { z as ZodNamespace, ZodType } from \"zod\";\n\nimport {\n  buildToolPrompt,\n  buildTransientAgentOptions,\n  disposeAndDeleteTransient,\n  extractUsage,\n  makeOutputTool,\n  setupStructuredOutput,\n} from \"./internal/structured-output-helpers.js\";\nimport type { AgentOptions, LocalOptions, ModelSelection, SDKAgent } from \"./types/agent.js\";\nimport type { ProviderRoutingSettings } from \"./types/providers.js\";\n\n/**\n * Options accepted by {@link Agent.streamObject}. Same shape as\n * `Agent.generateObject` with the addition that the result is an\n * `AsyncIterator<StreamObjectEvent<T>>` rather than a single Promise. See ADR D39.\n *\n * @public\n */\nexport interface StreamObjectOptions<T extends ZodType> {\n  schema: T;\n  prompt: string;\n  systemPrompt?: string;\n  /** SE8 — accepts a bare-string id shorthand or a {@link ModelSelection}. */\n  model: string | ModelSelection;\n  apiKey?: string;\n  local: LocalOptions;\n  maxRetries?: number;\n  /**\n   * Optional provider routing forwarded to the transient agent. Required when\n   * `model.id` uses a prefix (e.g. `openai/gpt-4o-mini`) but the credential is\n   * for a unified gateway (e.g. OpenRouter). Without this, the SDK infers\n   * provider from the prefix and may fail with `provider_unresolved` even\n   * when the right env key is set under a different provider name.\n   */\n  providers?: ProviderRoutingSettings;\n}\n\n/**\n * Recursive partial — `T` where every nested field becomes optional.\n *\n * @public\n */\nexport type DeepPartial<T> = T extends (infer U)[]\n  ? Array<DeepPartial<U>>\n  : T extends object\n    ? { [K in keyof T]?: DeepPartial<T[K]> }\n    : T;\n\n/**\n * Event emitted by {@link Agent.streamObject}. Discriminate on `type`.\n *\n * - `partial` events fire zero or more times with monotonically increasing\n *   `attempt`, carrying best-effort schema-parsed snapshots of the model's\n *   accumulating output.\n * - `complete` fires exactly once at the end, carrying the fully Zod-parsed\n *   object alongside usage and finishReason — semantically identical to a\n *   successful `Agent.generateObject()` return.\n *\n * @public\n */\nexport type StreamObjectEvent<T> =\n  | { type: \"partial\"; partial: DeepPartial<T>; attempt: number }\n  | {\n      type: \"complete\";\n      object: T;\n      raw: unknown;\n      usage: { inputTokens: number; outputTokens: number };\n      finishReason: \"tool_use\" | \"error\";\n    };\n\n/**\n * Error thrown by {@link Agent.streamObject} when the model refuses to call\n * the synthetic `output` tool or when all retries fail to produce a\n * schema-valid object. Same code taxonomy as `GenerateObjectError`.\n *\n * @public\n */\nexport class StreamObjectError extends Error {\n  override readonly name = \"StreamObjectError\";\n  readonly code: \"no_tool_call\" | \"parse_failed\";\n  override readonly cause?: unknown;\n  constructor(code: \"no_tool_call\" | \"parse_failed\", message: string, cause?: unknown) {\n    super(message);\n    this.code = code;\n    if (cause !== undefined) this.cause = cause;\n  }\n}\n\ninterface StreamObjectDeps {\n  create: (options: AgentOptions) => Promise<SDKAgent>;\n  delete: (agentId: string) => Promise<void>;\n}\n\n/**\n * Implementation of `Agent.streamObject` as an async generator. Mirrors the\n * synthetic-forced-tool pattern from `generate-object.ts` (ADR D33) with the\n * addition of intermediate `partial` events emitted from incremental parsing\n * of accumulating text deltas during the agent loop.\n *\n * REACHED BY DYNAMIC IMPORT — do not delete on a dead-code report (B-140).\n * `agent.ts` loads this module lazily to keep it off the eager path:\n *\n *     streamObjectImport ??= import(\"./stream-object.js\");\n *     const { streamObjectImpl } = await streamObjectImport;\n *\n * `knip` resolves imports statically and does not follow a destructure off a\n * dynamic-import promise, so it reports this export as unused on every run. It\n * is not: removing it breaks `Agent.streamObject`. That is why this file is\n * named in `knip.json`'s ignore list rather than cleaned up — the entry is a\n * tool limitation, not a suppression of a real finding, and the difference is\n * the whole reason this comment exists.\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: streaming loop interleaves text-delta accumulation, partial-parse attempts, retries, and final dispose — splitting harms locality of the iterator contract.\nexport async function* streamObjectImpl<T extends ZodType>(\n  options: StreamObjectOptions<T>,\n  deps: StreamObjectDeps,\n): AsyncGenerator<StreamObjectEvent<ZodNamespace.infer<T>>, void, void> {\n  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(\n    options.schema,\n    options.maxRetries,\n  );\n  let capturedRaw: unknown;\n  let lastUsage = initialUsage;\n\n  const outputTool = makeOutputTool(jsonSchema, (input) => {\n    // EC-6: first capture wins (parallel tool use in Claude 3.5+).\n    if (capturedRaw === undefined) {\n      capturedRaw = input;\n    }\n    return JSON.stringify({ ok: true });\n  });\n\n  const agentOptions: AgentOptions = buildTransientAgentOptions({\n    model: options.model,\n    local: options.local,\n    outputTool,\n    ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),\n    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n    ...(options.providers !== undefined ? { providers: options.providers } : {}),\n  });\n  const agent = await deps.create(agentOptions);\n  const userMessage = buildToolPrompt(options.prompt);\n\n  try {\n    let lastParseError: unknown;\n    let attemptCounter = 0;\n\n    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {\n      capturedRaw = undefined;\n      const run = await agent.send(userMessage);\n\n      // Buffer text deltas during streaming; try partial-parse on each.\n      let textBuffer = \"\";\n      for await (const msg of run.stream()) {\n        if (msg.type === \"assistant\") {\n          const newText = msg.message.content\n            .filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n            .map((c) => c.text)\n            .join(\"\");\n          if (newText.length > 0) {\n            textBuffer += newText;\n            const partial = bestEffortPartialParse(textBuffer, options.schema);\n            if (partial !== undefined) {\n              attemptCounter += 1;\n              yield {\n                type: \"partial\",\n                partial: partial as DeepPartial<ZodNamespace.infer<T>>,\n                attempt: attemptCounter,\n              };\n            }\n          }\n        }\n      }\n      const result = await run.wait();\n      lastUsage = extractUsage(result);\n\n      if (capturedRaw === undefined) {\n        // EC: when the underlying run errored (e.g. provider_unresolved),\n        // surface the original cause instead of the misleading \"model\n        // returned text\" message — there was no model call at all.\n        if (result.status === \"error\" && result.error !== undefined) {\n          throw new StreamObjectError(\n            \"no_tool_call\",\n            `Agent run failed before the model could reply: ${result.error.message ?? \"unknown error\"} [${result.error.code ?? \"?\"}]`,\n            result.error,\n          );\n        }\n        if (attempt === maxRetries) {\n          throw new StreamObjectError(\n            \"no_tool_call\",\n            \"The model returned text instead of calling the `output` tool.\",\n          );\n        }\n        continue;\n      }\n\n      const parsed = options.schema.safeParse(capturedRaw);\n      if (parsed.success) {\n        yield {\n          type: \"complete\",\n          object: parsed.data,\n          raw: capturedRaw,\n          usage: lastUsage,\n          finishReason: \"tool_use\",\n        };\n        return;\n      }\n      lastParseError = parsed.error;\n    }\n\n    throw new StreamObjectError(\n      \"parse_failed\",\n      \"Schema parse failed after all retries.\",\n      lastParseError,\n    );\n  } finally {\n    // EC-4: even if consumer calls iter.return() mid-stream, this finally\n    // runs — transient agent is disposed AND removed from registry.\n    await disposeAndDeleteTransient(agent, deps.delete);\n  }\n}\n\n/**\n * Try to extract a partial JSON object from a possibly-incomplete text\n * buffer and parse it via the schema in lenient mode. Returns `undefined`\n * if nothing parseable is found yet.\n *\n * Strategy: find the first `{`, find the LAST balanced `}` (greedy), parse\n * the substring as JSON, then `safeParse` against `schema.partial()` if the\n * schema supports it, else against the original schema.\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: stateful JSON-balancing scanner — string/brace/escape state must be co-located for the parser to remain correct.\nfunction bestEffortPartialParse<T extends ZodType>(text: string, schema: T): unknown | undefined {\n  const start = text.indexOf(\"{\");\n  if (start < 0) return undefined;\n  // Find the longest balanced JSON object from `start`.\n  let depth = 0;\n  let inString = false;\n  let isEscaped = false;\n  let end = -1;\n  for (let i = start; i < text.length; i += 1) {\n    const ch = text[i];\n    if (isEscaped) {\n      isEscaped = false;\n      continue;\n    }\n    if (ch === \"\\\\\" && inString) {\n      isEscaped = true;\n      continue;\n    }\n    if (ch === '\"') {\n      inString = !inString;\n      continue;\n    }\n    if (inString) continue;\n    if (ch === \"{\") depth += 1;\n    else if (ch === \"}\") {\n      depth -= 1;\n      if (depth === 0) end = i;\n    }\n  }\n  if (end < 0) return undefined;\n  const candidate = text.slice(start, end + 1);\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(candidate);\n  } catch {\n    return undefined;\n  }\n  // Try schema.partial() if available (Zod objects support it); else fall\n  // back to the original schema (loose match).\n  const maybePartial = (schema as unknown as { partial?: () => ZodType }).partial;\n  const looseSchema = typeof maybePartial === \"function\" ? maybePartial.call(schema) : schema;\n  const result = looseSchema.safeParse(parsed);\n  return result.success ? result.data : undefined;\n}\n"]}

package/dist/{chunk-V26QVGUG.js → chunk-RUDY2GTT.js}

@@ -1,6 +1,6 @@
-import { atomicWriteText } from './chunk-6AZDM6LK.js';
-import { InvalidTaskIdError } from './chunk-U4UJHOSH.js';
-import { diag } from './chunk-5F5NWKPN.js';
+import { atomicWriteText } from './chunk-VF7EWVDG.js';
+import { InvalidTaskIdError } from './chunk-IDCKSLYH.js';
+import { diag } from './chunk-T7O6K6PX.js';
 import { mkdirSync, readdirSync } from 'fs';
 import { readFile, unlink } from 'fs/promises';
 import { join } from 'path';
@@ -55,6 +55,14 @@ function matchesTime(h, filter) {
 function matchesFilter(h, filter) {
   return matchesState(h, filter) && matchesKind(h, filter) && matchesTime(h, filter);
 }
+var TERMINAL_STATES = ["finished", "error", "cancelled"];
+function insertionIndex(newestFirst, submittedAt) {
+  for (let i = 0; i < newestFirst.length; i++) {
+    const entry = newestFirst[i];
+    if (entry !== void 0 && entry.submittedAt < submittedAt) return i;
+  }
+  return newestFirst.length;
+}
 function applyFilter(values, filter) {
   const limit = filter.limit ?? DEFAULT_LIST_LIMIT;
   const out = [];
@@ -142,7 +150,14 @@ var JsonFileTaskStore = class {
       return void 0;
     }
   }
-  async list(filter) {
+  /**
+   * Task ids backed by a file in `dir`, in readdir order.
+   *
+   * EC-8: orphan `.tmp` files left by an interrupted atomic write are skipped, as is any name
+   * outside the id grammar. EC-6: a missing directory lists as empty; any other `readdir` failure
+   * (a permission error, say) throws rather than being reported as "no tasks".
+   */
+  candidateIds() {
     let entries;
     try {
       entries = readdirSync(this.dir);
@@ -150,16 +165,38 @@ var JsonFileTaskStore = class {
       if (err.code === "ENOENT") return [];
       throw err;
     }
-    const candidates = entries.filter((name) => name.endsWith(".json") && !name.includes(".tmp")).slice(0, JSON_LOAD_CAP);
-    const loaded = await Promise.all(
-      candidates.map(async (name) => {
-        const id = name.slice(0, -".json".length);
-        if (!isValidTaskId(id, true)) return void 0;
-        return this.get(id);
-      })
-    );
-    const handles = loaded.filter((h) => h !== void 0);
-    return applyFilter(handles, filter);
+    return entries.filter((name) => name.endsWith(".json") && !name.includes(".tmp")).map((name) => name.slice(0, -".json".length)).filter((id) => isValidTaskId(id, true));
+  }
+  /**
+   * Read every task in `ids`, handing each loaded handle to `visit`, at most `JSON_LOAD_CAP` file
+   * reads in flight.
+   *
+   * #362 — the cap used to be applied to the directory listing, which made it a bound on WHICH
+   * tasks were visible rather than on how much I/O ran at once. Every filter then ran on that
+   * arbitrary readdir-ordered prefix. As a concurrency bound it does the job it was named for
+   * without deciding what the caller gets to see; the caller's own bound on memory is whatever
+   * `visit` chooses to retain.
+   */
+  async forEachHandle(ids, visit) {
+    for (let start = 0; start < ids.length; start += JSON_LOAD_CAP) {
+      const batch = ids.slice(start, start + JSON_LOAD_CAP);
+      const loaded = await Promise.all(batch.map(async (id) => this.get(id)));
+      for (const handle of loaded) {
+        if (handle !== void 0) await visit(handle);
+      }
+    }
+  }
+  async list(filter) {
+    const limit = filter.limit ?? DEFAULT_LIST_LIMIT;
+    const newest = [];
+    await this.forEachHandle(this.candidateIds(), (handle) => {
+      if (!matchesFilter(handle, filter)) return;
+      const at = insertionIndex(newest, handle.submittedAt);
+      if (at >= limit) return;
+      newest.splice(at, 0, handle);
+      if (newest.length > limit) newest.pop();
+    });
+    return newest;
   }
   async delete(id) {
     assertValidIdForStore(id);
@@ -172,14 +209,13 @@ var JsonFileTaskStore = class {
     }
   }
   async evictTerminalOlderThan(epochMs) {
-    const handles = await this.list({ state: ["finished", "error", "cancelled"], limit: 256 });
     let count = 0;
-    for (const h of handles) {
-      const ts = terminalTimestamp(h);
-      if (ts !== void 0 && ts < epochMs) {
-        if (await this.delete(h.id)) count++;
-      }
-    }
+    await this.forEachHandle(this.candidateIds(), async (handle) => {
+      if (!TERMINAL_STATES.includes(handle.state)) return;
+      const ts = terminalTimestamp(handle);
+      if (ts === void 0 || ts >= epochMs) return;
+      if (await this.delete(handle.id)) count++;
+    });
     return count;
   }
 };
@@ -189,5 +225,5 @@ function getTaskStoreFor(options) {
 }
 
 export { InMemoryTaskStore, JsonFileTaskStore, TASK_RESERVED_PREFIXES, getTaskStoreFor, isValidTaskId };
-//# sourceMappingURL=chunk-V26QVGUG.js.map
-//# sourceMappingURL=chunk-V26QVGUG.js.map
+//# sourceMappingURL=chunk-RUDY2GTT.js.map
+//# sourceMappingURL=chunk-RUDY2GTT.js.map

package/dist/chunk-RUDY2GTT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/task.ts","../src/internal/task/store.ts"],"names":[],"mappings":"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","file":"chunk-RUDY2GTT.js","sourcesContent":["/**\n * Public type contract for the Task observability registry (ADRs D361-D374).\n *\n * Tasks are an opt-in observability layer over async work in the SDK\n * (`Agent.send`, `Agent.batch`, `Workflow.run`, `Cron` fires). They have\n * a closed 5-state lifecycle (D362), discriminated events (D366), and a\n * pluggable store (D364). The `Task` facade in `task.ts` is the public\n * surface; consumers import these types from `@theokit/sdk`.\n *\n * @public\n */\n\n/**\n * Closed enum of the 5 lifecycle states (D362).\n *\n * Transitions are acyclic:\n *   queued → running → (finished | error | cancelled)\n *   queued → cancelled (direct, no run started)\n */\nexport type TaskState = \"queued\" | \"running\" | \"finished\" | \"error\" | \"cancelled\";\n\n/** Discriminator of the runtime that produced a task (D374). */\nexport type TaskKind = \"run\" | \"batch\" | \"workflow\" | \"cron\" | \"custom\";\n\n/** Discriminated union of task lifecycle events (D366). */\nexport type TaskEvent =\n  | {\n      readonly type: \"submitted\";\n      readonly taskId: string;\n      readonly kind: TaskKind;\n      readonly submittedAt: number;\n      readonly meta?: Record<string, unknown>;\n      /** D372 — flag set on the first yielded event when the ring buffer was at cap. */\n      readonly truncated?: boolean;\n    }\n  | { readonly type: \"started\"; readonly taskId: string; readonly startedAt: number }\n  | {\n      readonly type: \"progress\";\n      readonly taskId: string;\n      readonly at: number;\n      readonly payload: unknown;\n    }\n  | {\n      readonly type: \"finished\";\n      readonly taskId: string;\n      readonly finishedAt: number;\n      readonly result: unknown;\n    }\n  | {\n      readonly type: \"errored\";\n      readonly taskId: string;\n      readonly erroredAt: number;\n      readonly error: { readonly code: string; readonly message: string };\n    }\n  | {\n      readonly type: \"cancelled\";\n      readonly taskId: string;\n      readonly cancelledAt: number;\n      readonly reason?: string;\n    };\n\n/** Public read-only view of a task entry in the registry. */\nexport interface TaskHandle {\n  readonly id: string;\n  readonly kind: TaskKind;\n  readonly state: TaskState;\n  readonly submittedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly cancelledAt?: number;\n  readonly erroredAt?: number;\n  readonly result?: unknown;\n  readonly error?: { readonly code: string; readonly message: string };\n  readonly meta?: Record<string, unknown>;\n  /**\n   * EC-7 — cross-process best-effort cancel flag. Set by CLI\n   * `theokit tasks cancel` via JsonFileTaskStore. The owning process\n   * polls at checkpoints and honors via AbortController. Always\n   * `undefined` for in-process cancel paths (which go directly through\n   * AbortController).\n   */\n  readonly cancelRequested?: boolean;\n  /**\n   * Why the task was cancelled, when whoever cancelled it said. Free text, written alongside\n   * `cancelledAt` for a `queued` task and alongside `cancelRequested` for a `running` one.\n   *\n   * Absent when no reason was given — an empty string is not a reason, and a default like\n   * \"cancelled\" would put words in the operator's mouth. `theokit tasks cancel --reason` is what\n   * writes it (#351); nothing in the runtime reads it, because it exists for the human reading the\n   * registry later.\n   */\n  readonly cancelReason?: string;\n}\n\n/** Query filter for `Task.list`. */\nexport interface TaskFilter {\n  readonly state?: TaskState | readonly TaskState[];\n  readonly kind?: TaskKind | readonly TaskKind[];\n  readonly submittedAfter?: number;\n  readonly submittedBefore?: number;\n  /**\n   * Defaults to 100. `JsonFileTaskStore` returns the newest matching tasks first and reads its\n   * whole directory to find them (256 files at a time); page past this limit with\n   * `submittedBefore` (#362).\n   */\n  readonly limit?: number;\n}\n\n/** Options for `Task.submit`. */\nexport interface TaskSubmitOptions {\n  /**\n   * Optional user-supplied ID. Must match grammar `^[a-z0-9][a-z0-9_-]*$`\n   * and MUST NOT start with the reserved prefixes `wf-` / `b-` / `cron-`\n   * (D368, EC-5). When omitted, `crypto.randomUUID()` is used.\n   */\n  readonly id?: string;\n  readonly meta?: Record<string, unknown>;\n  /**\n   * Optional caller-provided AbortSignal. If already aborted at submit\n   * time, the registry short-circuits to `cancelled` without acquiring\n   * a semaphore slot (EC-4).\n   */\n  readonly signal?: AbortSignal;\n  /**\n   * SE2 — an opt-in {@link import(\"./run-events.js\").RunEventSink}. The task's\n   * lifecycle is forwarded to it as typed `task_started` / `task_updated` /\n   * `task_completed` RunEvents, so a caller that spawned the task can observe it\n   * through the same `onRunEvent` channel as the rest of the run. Best-effort (a\n   * throwing sink never breaks the task). The dedicated `Task.subscribe(id)`\n   * channel is unaffected.\n   */\n  readonly onRunEvent?: import(\"./run-events.js\").RunEventSink;\n}\n\n/** Options shape for `TaskStore` factory (D364). */\nexport type TaskStoreOptions =\n  | { readonly backend: \"memory\" }\n  | { readonly backend: \"json\"; readonly dir: string };\n\n/** Result of `Task.cancel` (D365 — idempotent). */\nexport interface TaskCancelResult {\n  readonly cancelled: boolean;\n  readonly alreadyTerminal: boolean;\n}\n\n/**\n * Grammar for user-supplied task IDs (D368).\n * `crypto.randomUUID()` outputs do NOT match this (UUIDs have dashes\n * AND uppercase letters in their canonical form on some Node versions),\n * but the registry normalizes auto-generated IDs to lowercase before\n * insertion, so they pass the same regex.\n */\nconst TASK_ID_GRAMMAR = /^[a-z0-9][a-z0-9_-]*$/;\n\n/** Reserved prefixes for adapter-generated IDs (D368, EC-5). */\nconst RESERVED_PREFIXES = [\"wf-\", \"b-\", \"cron-\"] as const;\n\n/**\n * Validates a task ID against the public grammar + reserved prefixes.\n * Throws `InvalidTaskIdError` from `../errors.js` on rejection.\n *\n * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`\n * to register their own IDs; user-facing surfaces (`Task.submit`,\n * `agent.send({ task: { id } })`) leave it false.\n */\nexport function isValidTaskId(id: string, allowReserved: boolean): boolean {\n  if (!TASK_ID_GRAMMAR.test(id)) return false;\n  if (allowReserved) return true;\n  for (const prefix of RESERVED_PREFIXES) {\n    if (id.startsWith(prefix)) return false;\n  }\n  return true;\n}\n\n/** Re-exported for adapter implementations + tests. */\nexport const TASK_RESERVED_PREFIXES: readonly string[] = RESERVED_PREFIXES;\n","/**\n * `TaskStore` interface + 2 implementations (ADR D364).\n *\n *   - `InMemoryTaskStore` — default, transient, single-process.\n *   - `JsonFileTaskStore` — opt-in, one JSON file per task under a\n *     dedicated dir; single-process invariant (EC-15 documented).\n *\n * Edge cases absorbed:\n *   - EC-1: constructor auto-creates dir (mkdirSync recursive idempotent).\n *   - EC-2: every method validates the task id against the public\n *     grammar (D368) BEFORE doing any path I/O — path-traversal defense.\n *   - EC-6: `list()` returns `[]` on ENOENT (fresh install path).\n *   - EC-8: `list()` skips `.tmp.*` orphan files left by interrupted\n *     atomic writes.\n *   - EC-14 (DOCUMENT): `list()` JSDoc documents the 256-row hard cap.\n *     It no longer advertises `submittedBefore` as a way to page past it:\n *     the cap is applied to the raw directory listing before any filter, so\n *     paging beyond 256 files is not reachable through this interface.\n *   - EC-15 (DOCUMENT): `JsonFileTaskStore` JSDoc documents the\n *     single-process invariant; v0.2 SQLite covers cross-process.\n *\n * @internal\n */\n\nimport { mkdirSync, readdirSync } from \"node:fs\";\nimport { readFile, unlink } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { InvalidTaskIdError } from \"../../errors.js\";\nimport {\n  isValidTaskId,\n  type TaskFilter,\n  type TaskHandle,\n  type TaskState,\n  type TaskStoreOptions,\n} from \"../../types/task.js\";\nimport { diag } from \"../diagnostics.js\";\nimport { atomicWriteText } from \"../persistence/atomic-write.js\";\n\nconst JSON_LOAD_CAP = 256;\nconst DEFAULT_LIST_LIMIT = 100;\n\n/** Storage interface used by `TaskRegistry`. */\nexport interface TaskStore {\n  insert(handle: TaskHandle): Promise<void>;\n  update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined>;\n  get(id: string): Promise<TaskHandle | undefined>;\n  /**\n   * Returns at most `filter.limit ?? 100` matching handles.\n   *\n   * `JsonFileTaskStore` returns them newest-first and considers every task in its\n   * directory, reading at most 256 files concurrently (#362 — that number bounds\n   * I/O, not which tasks are visible). Walk past `limit` by passing the oldest\n   * `submittedAt` of a page as the next call's `submittedBefore`; the ordering is\n   * what makes that a cursor rather than a re-roll of an arbitrary subset.\n   * `InMemoryTaskStore` applies the same filters but does not order its result.\n   */\n  list(filter: TaskFilter): Promise<TaskHandle[]>;\n  delete(id: string): Promise<boolean>;\n  /** Removes terminal handles whose terminal-timestamp is older than `epochMs`. */\n  evictTerminalOlderThan(epochMs: number): Promise<number>;\n}\n\nfunction assertValidIdForStore(id: string): void {\n  if (!isValidTaskId(id, /* allowReserved */ true)) {\n    throw new InvalidTaskIdError(`store rejects invalid task id: ${id}`, id);\n  }\n}\n\nfunction terminalTimestamp(h: TaskHandle): number | undefined {\n  if (h.state === \"finished\") return h.finishedAt;\n  if (h.state === \"error\") return h.erroredAt;\n  if (h.state === \"cancelled\") return h.cancelledAt;\n  return undefined;\n}\n\nfunction isTerminal(state: TaskState): boolean {\n  return state === \"finished\" || state === \"error\" || state === \"cancelled\";\n}\n\nfunction matchesState(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.state === undefined) return true;\n  const states = Array.isArray(filter.state) ? filter.state : [filter.state];\n  return states.includes(h.state);\n}\nfunction matchesKind(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.kind === undefined) return true;\n  const kinds = Array.isArray(filter.kind) ? filter.kind : [filter.kind];\n  return kinds.includes(h.kind);\n}\nfunction matchesTime(h: TaskHandle, filter: TaskFilter): boolean {\n  if (filter.submittedAfter !== undefined && h.submittedAt <= filter.submittedAfter) return false;\n  if (filter.submittedBefore !== undefined && h.submittedAt >= filter.submittedBefore) return false;\n  return true;\n}\nfunction matchesFilter(h: TaskHandle, filter: TaskFilter): boolean {\n  return matchesState(h, filter) && matchesKind(h, filter) && matchesTime(h, filter);\n}\n\n/** The states `evictTerminalOlderThan` considers terminal. */\nconst TERMINAL_STATES: readonly TaskState[] = [\"finished\", \"error\", \"cancelled\"];\n\n/**\n * Where `submittedAt` belongs in a newest-first list — the first index whose entry is older.\n *\n * Linear rather than binary: the list is bounded by the caller's `limit` (100 by default) and the\n * scan runs once per MATCHING handle, so the comparison count is dwarfed by the file read that\n * produced the handle. A binary search here would trade a real cost for an imagined one.\n */\nfunction insertionIndex(newestFirst: readonly TaskHandle[], submittedAt: number): number {\n  for (let i = 0; i < newestFirst.length; i++) {\n    const entry = newestFirst[i];\n    if (entry !== undefined && entry.submittedAt < submittedAt) return i;\n  }\n  return newestFirst.length;\n}\n\nfunction applyFilter(values: Iterable<TaskHandle>, filter: TaskFilter): TaskHandle[] {\n  const limit = filter.limit ?? DEFAULT_LIST_LIMIT;\n  const out: TaskHandle[] = [];\n  for (const h of values) {\n    if (matchesFilter(h, filter)) {\n      out.push(h);\n      if (out.length >= limit) break;\n    }\n  }\n  return out;\n}\n\n/* ─── InMemory ─── */\n\n/**\n * Default `TaskStore` — a plain `Map` living in the current process.\n *\n * Nothing reaches disk and nothing survives the process, so a task recorded here\n * is invisible to a reader in another process (`theokit tasks`). Select it with\n * `getTaskStoreFor({ backend: \"memory\" })`.\n *\n * How it fails: every id-taking method validates against the task-id grammar\n * (`^[a-z0-9][a-z0-9_-]*$`; reserved `wf-`/`b-`/`cron-` prefixes are permitted\n * here) and throws `InvalidTaskIdError` before touching the map. A missing id is\n * reported by returning `undefined` (`get`, `update`) or `false` (`delete`), never\n * by throwing.\n *\n * Traps:\n *  - `insert()` is a `Map.set`: an existing id is overwritten silently, not\n *    rejected.\n *  - `list()` walks in INSERTION order and stops as soon as `filter.limit ?? 100`\n *    matches are collected. It never sorts, so the limit truncates an\n *    oldest-first scan rather than returning the most recent tasks.\n *  - Nothing evicts on its own; terminal handles accumulate until a caller invokes\n *    `evictTerminalOlderThan`.\n */\nexport class InMemoryTaskStore implements TaskStore {\n  private readonly map = new Map<string, TaskHandle>();\n\n  async insert(handle: TaskHandle): Promise<void> {\n    assertValidIdForStore(handle.id);\n    this.map.set(handle.id, handle);\n  }\n\n  async update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    const existing = this.map.get(id);\n    if (existing === undefined) return undefined;\n    const next = mutate(existing);\n    this.map.set(id, next);\n    return next;\n  }\n\n  async get(id: string): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    return this.map.get(id);\n  }\n\n  async list(filter: TaskFilter): Promise<TaskHandle[]> {\n    return applyFilter(this.map.values(), filter);\n  }\n\n  async delete(id: string): Promise<boolean> {\n    assertValidIdForStore(id);\n    return this.map.delete(id);\n  }\n\n  async evictTerminalOlderThan(epochMs: number): Promise<number> {\n    let count = 0;\n    for (const [id, h] of this.map.entries()) {\n      if (!isTerminal(h.state)) continue;\n      const ts = terminalTimestamp(h);\n      if (ts !== undefined && ts < epochMs) {\n        this.map.delete(id);\n        count++;\n      }\n    }\n    return count;\n  }\n}\n\n/* ─── JsonFile (opt-in) ───\n *\n * IMPORTANT (EC-15): `JsonFileTaskStore` is **single-process**.\n * Concurrent writers from multiple Node processes against the same\n * directory may corrupt entries (atomic-write protects per-file, but\n * the `list()` scan + `update()` read-modify-write cycle is not\n * serialised across processes). Use only when the `TaskRegistry`\n * runs in exactly one process. v0.2 will add a SQLite backend with\n * the same interface for cross-process scenarios (D364 + D61).\n */\n/**\n * Opt-in `TaskStore` that keeps one JSON file per task under `dir`, so another\n * process can read the registry off disk.\n *\n *   const store = new JsonFileTaskStore(\"/var/lib/theokit/tasks\");\n *\n * Two calls are synchronous, and both are deliberate: the constructor creates `dir`\n * recursively (`mkdirSync`), and `list()` scans it with `readdirSync` before awaiting\n * anything. Every other operation is async — `get` uses `readFile`, `delete` uses\n * `unlink`, and every write goes through an atomic temp-file-plus-rename.\n *\n * SINGLE-PROCESS ONLY — see the note above. Per-file atomicity does not make\n * `update()` safe: it is a read-modify-write, so two writers that both `get`\n * before either writes lose one of the two mutations. That is true within one\n * process as well as across processes.\n *\n * How it fails:\n *  - An invalid id throws `InvalidTaskIdError` BEFORE any path is constructed.\n *    That ordering is the path-traversal defence, and it is why ids are validated\n *    rather than escaped.\n *  - A missing task is `undefined` from `get` and `false` from `delete`.\n *  - A file that exists but does not parse is NOT surfaced as an error: `get`\n *    writes to the diagnostics channel and returns `undefined`, so a corrupted\n *    task also silently vanishes from `list()`.\n *  - `list()` returns `[]` when `dir` does not exist; any other `readdir` failure\n *    (for example a permission error) throws.\n *\n * Traps:\n *  - `list()` reads every task file in the directory (256 at a time) to apply the\n *    filter, because `state`, `kind` and `submittedAt` live inside the files. On a\n *    large directory that is a lot of I/O for one call; the memory it holds is\n *    bounded by `limit`, the time is not.\n *  - `list()` is `async`, but its directory scan is not: `readdirSync` blocks the event\n *    loop for the whole listing before the first `await`. Only the per-file reads that\n *    follow it are concurrent.\n *  - Files whose name contains `.tmp` are skipped as orphans of an interrupted\n *    write, and nothing ever removes them.\n */\nexport class JsonFileTaskStore implements TaskStore {\n  constructor(private readonly dir: string) {\n    // EC-1: idempotent mkdir; ignore EEXIST.\n    try {\n      mkdirSync(dir, { recursive: true });\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code !== \"EEXIST\") throw err;\n    }\n  }\n\n  private filePath(id: string): string {\n    return join(this.dir, `${id}.json`);\n  }\n\n  async insert(handle: TaskHandle): Promise<void> {\n    assertValidIdForStore(handle.id);\n    await atomicWriteText(this.filePath(handle.id), JSON.stringify(handle));\n  }\n\n  async update(id: string, mutate: (h: TaskHandle) => TaskHandle): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    const existing = await this.get(id);\n    if (existing === undefined) return undefined;\n    const next = mutate(existing);\n    await atomicWriteText(this.filePath(id), JSON.stringify(next));\n    return next;\n  }\n\n  async get(id: string): Promise<TaskHandle | undefined> {\n    assertValidIdForStore(id);\n    try {\n      const raw = await readFile(this.filePath(id), \"utf8\");\n      return JSON.parse(raw) as TaskHandle;\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code === \"ENOENT\") return undefined;\n      // Corrupt JSON or other I/O error — log + degrade gracefully (D50/EC-7 cache pattern).\n      diag(`[task-store] failed to read ${id}: ${(err as Error).message}\\n`);\n      return undefined;\n    }\n  }\n\n  /**\n   * Task ids backed by a file in `dir`, in readdir order.\n   *\n   * EC-8: orphan `.tmp` files left by an interrupted atomic write are skipped, as is any name\n   * outside the id grammar. EC-6: a missing directory lists as empty; any other `readdir` failure\n   * (a permission error, say) throws rather than being reported as \"no tasks\".\n   */\n  private candidateIds(): string[] {\n    let entries: string[];\n    try {\n      entries = readdirSync(this.dir);\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return []; // EC-6\n      throw err;\n    }\n    return entries\n      .filter((name) => name.endsWith(\".json\") && !name.includes(\".tmp\"))\n      .map((name) => name.slice(0, -\".json\".length))\n      .filter((id) => isValidTaskId(id, true));\n  }\n\n  /**\n   * Read every task in `ids`, handing each loaded handle to `visit`, at most `JSON_LOAD_CAP` file\n   * reads in flight.\n   *\n   * #362 — the cap used to be applied to the directory listing, which made it a bound on WHICH\n   * tasks were visible rather than on how much I/O ran at once. Every filter then ran on that\n   * arbitrary readdir-ordered prefix. As a concurrency bound it does the job it was named for\n   * without deciding what the caller gets to see; the caller's own bound on memory is whatever\n   * `visit` chooses to retain.\n   */\n  private async forEachHandle(\n    ids: readonly string[],\n    visit: (handle: TaskHandle) => void | Promise<void>,\n  ): Promise<void> {\n    for (let start = 0; start < ids.length; start += JSON_LOAD_CAP) {\n      const batch = ids.slice(start, start + JSON_LOAD_CAP);\n      const loaded = await Promise.all(batch.map(async (id) => this.get(id)));\n      for (const handle of loaded) {\n        if (handle !== undefined) await visit(handle);\n      }\n    }\n  }\n\n  async list(filter: TaskFilter): Promise<TaskHandle[]> {\n    const limit = filter.limit ?? DEFAULT_LIST_LIMIT;\n    // Newest-first, keeping at most `limit` handles in memory regardless of how many match. The\n    // order is what makes `submittedBefore` a real cursor: with the previous readdir order, a page\n    // was an arbitrary subset, so a caller walking the timeline skipped every task that happened\n    // to fall outside its window and could never come back for them.\n    const newest: TaskHandle[] = [];\n    await this.forEachHandle(this.candidateIds(), (handle) => {\n      if (!matchesFilter(handle, filter)) return;\n      const at = insertionIndex(newest, handle.submittedAt);\n      if (at >= limit) return; // older than everything already held, and the page is full\n      newest.splice(at, 0, handle);\n      if (newest.length > limit) newest.pop();\n    });\n    return newest;\n  }\n\n  async delete(id: string): Promise<boolean> {\n    assertValidIdForStore(id);\n    try {\n      await unlink(this.filePath(id));\n      return true;\n    } catch (err) {\n      if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return false;\n      throw err;\n    }\n  }\n\n  async evictTerminalOlderThan(epochMs: number): Promise<number> {\n    // #362 — eviction scans the directory itself rather than borrowing `list()`. Sharing that path\n    // made one call incomplete twice over: it saw only a 256-file window, and it wanted the OLDEST\n    // handles while `list()` is ordered newest-first — so on a large directory it could delete\n    // nothing while thousands of eligible handles sat just outside the page. Sweeping every\n    // candidate is what lets one call mean \"everything eligible is gone\".\n    let count = 0;\n    await this.forEachHandle(this.candidateIds(), async (handle) => {\n      if (!TERMINAL_STATES.includes(handle.state)) return;\n      const ts = terminalTimestamp(handle);\n      if (ts === undefined || ts >= epochMs) return;\n      if (await this.delete(handle.id)) count++;\n    });\n    return count;\n  }\n}\n\n/** Factory used by `TaskRegistry.configure` (D364). */\nexport function getTaskStoreFor(options: TaskStoreOptions): TaskStore {\n  if (options.backend === \"memory\") return new InMemoryTaskStore();\n  return new JsonFileTaskStore(options.dir);\n}\n"]}

package/dist/{chunk-JIQRXKTA.cjs → chunk-SKXBJ2NU.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkLPVIRJVF_cjs = require('./chunk-LPVIRJVF.cjs');
-var chunkBM6N4KHO_cjs = require('./chunk-BM6N4KHO.cjs');
+var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
+var chunkNUKRL3I6_cjs = require('./chunk-NUKRL3I6.cjs');
 var promises = require('fs/promises');
 var path = require('path');
 
@@ -69,7 +69,7 @@ function applyWalWithFallback(db, label) {
 function logFallback(label, reason) {
   if (warnedLabels.has(label)) return;
   warnedLabels.add(label);
-  chunkBM6N4KHO_cjs.diag(
+  chunkNUKRL3I6_cjs.diag(
     `[theokit-sdk] ${label}: WAL unavailable (${reason}); using DELETE journal mode. This is normal on NFS/SMB/FUSE; expect slightly slower concurrent access.
 `
   );
@@ -141,7 +141,7 @@ async function loadDriver(filePath) {
   } catch (nodeSqliteCause) {
     const b = betterSqliteCause instanceof Error ? betterSqliteCause.message : String(betterSqliteCause);
     const n = nodeSqliteCause instanceof Error ? nodeSqliteCause.message : String(nodeSqliteCause);
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Failed to load SQLite driver. Install \`better-sqlite3\` or run on Node 22.5+ for built-in \`node:sqlite\`. better-sqlite3: ${b}; node:sqlite: ${n}`,
       { code: "sqlite_driver_unavailable", cause: nodeSqliteCause }
     );
@@ -157,7 +157,7 @@ async function renameAside(filePath, label) {
   await promises.rename(filePath, asidePath).catch(() => void 0);
   await promises.rename(`${filePath}-wal`, `${asidePath}-wal`).catch(() => void 0);
   await promises.rename(`${filePath}-shm`, `${asidePath}-shm`).catch(() => void 0);
-  chunkBM6N4KHO_cjs.diag(
+  chunkNUKRL3I6_cjs.diag(
     `[theokit-sdk] ${label} database corrupt; renamed aside to ${asidePath} and rebuilt schema
 `
   );
@@ -168,5 +168,5 @@ exports.containsCjk = containsCjk;
 exports.isCorruptionError = isCorruptionError;
 exports.openSqliteResilient = openSqliteResilient;
 exports.sanitizeFts5Query = sanitizeFts5Query;
-//# sourceMappingURL=chunk-JIQRXKTA.cjs.map
-//# sourceMappingURL=chunk-JIQRXKTA.cjs.map
+//# sourceMappingURL=chunk-SKXBJ2NU.cjs.map
+//# sourceMappingURL=chunk-SKXBJ2NU.cjs.map

package/dist/chunk-SKXBJ2NU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/persistence/fts5-sanitize.ts","../src/internal/persistence/sqlite-wal.ts","../src/internal/persistence/sqlite-open.ts"],"names":["diag","mkdir","dirname","ConfigurationError","rename"],"mappings":"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","file":"chunk-SKXBJ2NU.cjs","sourcesContent":["/**\n * FTS5 query sanitization + CJK detection (ADR D64).\n *\n * Port of Hermes' 6-step sanitizer (`hermes_state.py:1797-1847`). Prevents\n * crashes on user inputs with hyphens, dots, underscores, and unmatched\n * specials. Auto-quotes identifier-shaped tokens so `error-code` finds\n * literal `error-code` instead of `error AND code`.\n *\n * CJK detection returns true for inputs containing characters in the main\n * CJK Unicode ranges (Chinese, Japanese, Korean). CJK trigram routing is\n * deferred to v1.4 — callers receiving `containsCjk === true` should\n * short-circuit to an empty result or LIKE fallback for v1.3.\n *\n * @internal\n */\n\n// Control-char sentinels for the phrase-preservation placeholder. U+0001\n// and U+0002 are essentially never present in real user queries, and\n// crucially do NOT form word boundaries / `\\w` characters, so Step 5's\n// auto-quote regex (`\\b\\w+[-._]\\w[\\w\\-._]*\\b`) cannot match them.\n// Choosing `__PHRASE_N__` instead would re-trigger Step 5 on the second\n// sanitize pass and break idempotence.\nconst PHRASE_OPEN = \"\u0001\";\nconst PHRASE_CLOSE = \"\u0002\";\n\n/**\n * Six-step FTS5 query sanitizer. Returns a query string safe for passing\n * to `WHERE <fts5_table> MATCH ?` as a parameter.\n *\n * Returns empty string when the input contains only specials (caller MUST\n * short-circuit to avoid runtime SQL error — EC-3).\n *\n */\nexport function sanitizeFts5Query(query: string): string {\n  if (query.length === 0) return query;\n\n  // Step 1: preserve \"quoted phrases\" via control-char placeholders.\n  const phrases: string[] = [];\n  let text = query.replace(/\"[^\"]+\"/g, (match) => {\n    phrases.push(match);\n    return `${PHRASE_OPEN}${phrases.length - 1}${PHRASE_CLOSE}`;\n  });\n\n  // Step 2: strip unmatched specials (brackets, braces, parens, double quotes, caret).\n  text = text.replace(/[[\\]{}()\"^]/g, \" \");\n\n  // Step 3: collapse repeated asterisks (FTS5 prefix operator is single `*`).\n  text = text.replace(/\\*+/g, \"*\");\n\n  // Step 4: strip dangling boolean operators (AND/OR/NOT) at start/end.\n  text = text.replace(/^\\s*(AND|OR|NOT)\\s+/i, \"\");\n  text = text.replace(/\\s+(AND|OR|NOT)\\s*$/i, \"\");\n\n  // Step 5: auto-quote identifier-shaped tokens that contain `-`, `.`, or `_`.\n  // FTS5 tokenizer would otherwise split them as boolean conjunctions.\n  text = text.replace(/\\b\\w+[-._]\\w[\\w\\-._]*\\b/g, (match) => `\"${match}\"`);\n\n  // Step 6: restore preserved phrases.\n  for (let i = 0; i < phrases.length; i += 1) {\n    text = text.replace(`${PHRASE_OPEN}${i}${PHRASE_CLOSE}`, phrases[i] ?? \"\");\n  }\n\n  return text.trim();\n}\n\n// CJK code-point ranges. Coverage matches Hermes' coarse detection for v1.3;\n// fine-grained trigram routing comes in v1.4.\nconst CJK_RANGES: ReadonlyArray<readonly [number, number]> = [\n  [0x3000, 0x303f], // CJK Symbols and Punctuation\n  [0x3040, 0x309f], // Hiragana\n  [0x30a0, 0x30ff], // Katakana\n  [0x3400, 0x4dbf], // CJK Unified Ideographs Extension A\n  [0x4e00, 0x9fff], // CJK Unified Ideographs\n  [0xac00, 0xd7af], // Hangul Syllables\n];\n\n/**\n * Report whether `text` holds at least one Chinese, Japanese or Korean character.\n *\n * Iterates by code point, so surrogate pairs are handled correctly, and returns on the first hit.\n * An empty string is `false`.\n *\n * Coverage is deliberately coarse: CJK Symbols and Punctuation, Hiragana, Katakana, Hangul\n * Syllables, and CJK Unified Ideographs including Extension A. Everything beyond that — the\n * higher ideograph extensions, Halfwidth and Fullwidth Forms, Hangul Jamo — reads as `false`, so\n * a `false` is not proof that the text is CJK-free.\n *\n * The reason to ask is FTS5: the default tokenizer splits on whitespace, which CJK text does not\n * use, so a matching query against it returns nothing rather than failing. A caller seeing `true`\n * should short-circuit to an empty result or a LIKE fallback instead of running the search and\n * reporting no matches.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function containsCjk(text: string): boolean {\n  for (const char of text) {\n    const cp = char.codePointAt(0);\n    if (cp === undefined) continue;\n    for (const [lo, hi] of CJK_RANGES) {\n      if (cp >= lo && cp <= hi) return true;\n    }\n  }\n  return false;\n}\n","/**\n * SQLite WAL mode helper with NFS/SMB/FUSE fallback to DELETE (ADR D63).\n *\n * WAL is faster (concurrent readers + one writer) but unsupported on some\n * network/FUSE filesystems. Try WAL; if the pragma returns something else\n * or throws, fall back to DELETE journal mode. Warn one time per label.\n *\n * This block is the MODULE header and must stay at offset 0. Sitting below the import it became a\n * leading comment of the first declaration instead, which is how its tag deleted `PragmaCapable`\n * from the emitted `.d.ts` while `applyWalWithFallback` — which names it — survived.\n */\n\nimport { diag } from \"../diagnostics.js\";\n\n/**\n * The narrow slice of a SQLite handle this module needs: anything with a `pragma()` method, which\n * `better-sqlite3` satisfies without being named here.\n *\n * Not exported, but it appears in the signature of `applyWalWithFallback`, so it is emitted into\n * the published declarations and a consumer can structurally satisfy it.\n */\ninterface PragmaCapable {\n  pragma: (statement: string, options?: { simple?: boolean }) => unknown;\n}\n\n/**\n * What journal mode a connection ended up in after `applyWalWithFallback`.\n *\n * `mode` is the mode actually in effect, never the one that was requested. `fellBack` is `true`\n * only when WAL was attempted and refused — either the pragma threw or it reported a mode other\n * than `wal` — and the connection was put into DELETE instead.\n *\n * `fellBack: true` is normal on NFS, SMB and FUSE, where WAL needs shared memory the filesystem\n * does not provide. It is not an error and nothing further is required of the caller; the\n * consequence is slower concurrent access, since DELETE mode does not allow readers alongside a\n * writer. Treat it as a signal about the storage, not about the database.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface WalApplyResult {\n  /** Final journal_mode actually in effect. */\n  mode: \"wal\" | \"delete\";\n  /** True if we wanted WAL but the filesystem refused. */\n  fellBack: boolean;\n}\n\nconst warnedLabels = new Set<string>();\n\n/**\n * Apply WAL mode with DELETE fallback. Idempotent — safe to call multiple\n * times on the same connection.\n *\n * @param db   any `pragma()`-capable SQLite handle (e.g., `better-sqlite3`)\n * @param label short identifier used in the warning (e.g., \"memory-index\")\n *\n */\nexport function applyWalWithFallback(db: PragmaCapable, label: string): WalApplyResult {\n  try {\n    const result = db.pragma(\"journal_mode = WAL\", { simple: true });\n    if (typeof result === \"string\" && result.toLowerCase() === \"wal\") {\n      return { mode: \"wal\", fellBack: false };\n    }\n    logFallback(label, `got \"${String(result)}\" instead of \"wal\"`);\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    logFallback(label, msg);\n  }\n\n  db.pragma(\"journal_mode = DELETE\");\n  return { mode: \"delete\", fellBack: true };\n}\n\nfunction logFallback(label: string, reason: string): void {\n  if (warnedLabels.has(label)) return;\n  warnedLabels.add(label);\n  diag(\n    `[theokit-sdk] ${label}: WAL unavailable (${reason}); using DELETE journal mode. ` +\n      \"This is normal on NFS/SMB/FUSE; expect slightly slower concurrent access.\\n\",\n  );\n}\n\n/**\n * Test helper — clears the warn-once registry.\n *\n * @internal\n */\nexport function _resetWalWarnings(): void {\n  warnedLabels.clear();\n}\n","/**\n * Resilient SQLite open (plan m0-foundation-expose-primitives, M0-5).\n *\n * Generalizes the driver-load + WAL-apply + corruption-recovery logic that was\n * duplicated (byte-identical) across `sdk/internal/memory/index-db.ts` and\n * `sdk-memory/internal/index/index-db.ts`. Schema-agnostic: the caller applies\n * its own PRAGMA/SCHEMA via the `onOpen` callback.\n *\n * Corruption recovery (EC-7): when opening fails with a \"malformed\" / \"not a\n * database\" / \"encrypted\" error and `recoverCorrupt` is not false, the file is\n * renamed aside to `<path>.corrupt-<ts>` (plus its WAL/SHM siblings) and a fresh\n * DB is opened. The corrupt file is renamed, NOT backed up — the timestamped\n * `.corrupt-*` file is kept for manual recovery.\n *\n * @internal — public via `@theokit/sdk/internal/persistence` (semver-exempt)\n */\n\nimport { mkdir, rename } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\nimport { diag } from \"../diagnostics.js\";\nimport { applyWalWithFallback } from \"./sqlite-wal.js\";\n\n/** Minimal SQLite handle surface every driver (`better-sqlite3`) exposes. */\nexport interface ResilientSqliteDb {\n  /** SQLite `pragma()` access (used by `applyWalWithFallback`). */\n  pragma(statement: string, options?: { simple?: boolean }): unknown;\n  exec(sql: string): void;\n  close(): void;\n}\n\n/**\n * Input to {@link openSqliteResilient}.\n *\n * The trap is `recoverCorrupt`, whose default is ON. When the driver reports a corrupt or encrypted\n * database, the file is renamed aside and a FRESH one is opened — so the call SUCCEEDS and hands\n * back an EMPTY database. The old bytes survive on disk under the renamed path, but a caller that\n * treats a resolved promise as \"my data is here\" is wrong exactly when it matters. Pass\n * `recoverCorrupt: false` to get the corruption error thrown instead.\n *\n * Semver-exempt: reachable via the '@theokit/sdk/internal/persistence' sub-path, which the package\n * declares in 'exports' but does NOT cover with its semver contract.\n *\n * @typeParam T - the concrete DB handle the driver returns; defaults to {@link ResilientSqliteDb}\n */\nexport interface OpenSqliteResilientOptions<T extends ResilientSqliteDb> {\n  /** Absolute path to the SQLite file. Parent directories are created. */\n  filePath: string;\n  /**\n   * Called after the driver is open and WAL is applied, before the handle is\n   * returned. Apply PRAGMA/SCHEMA statements here. Errors propagate.\n   */\n  onOpen?: (db: T) => void | Promise<void>;\n  /** Label used in the WAL-fallback warning and corruption-recovery log. Default \"sqlite\". */\n  label?: string;\n  /** When true (default) a corruption error renames the file aside and rebuilds. */\n  recoverCorrupt?: boolean;\n}\n\n/**\n * Open a SQLite file with WAL (+ DELETE fallback) and corruption recovery.\n *\n * @typeParam T - the concrete DB handle type the driver returns (defaults to the\n *   minimal {@link ResilientSqliteDb} surface)\n */\nexport async function openSqliteResilient<T extends ResilientSqliteDb = ResilientSqliteDb>(\n  options: OpenSqliteResilientOptions<T>,\n): Promise<T> {\n  await mkdir(dirname(options.filePath), { recursive: true });\n  try {\n    return await openConcrete(options);\n  } catch (cause) {\n    if (options.recoverCorrupt !== false && isCorruptionError(cause)) {\n      await renameAside(options.filePath, options.label ?? \"sqlite\");\n      return await openConcrete(options);\n    }\n    throw cause;\n  }\n}\n\nasync function openConcrete<T extends ResilientSqliteDb>(\n  options: OpenSqliteResilientOptions<T>,\n): Promise<T> {\n  const db = await loadDriver<T>(options.filePath);\n  // Apply WAL with NFS/SMB/FUSE fallback BEFORE schema so the journal mode is\n  // set for the whole session.\n  applyWalWithFallback(db, options.label ?? \"sqlite\");\n  await options.onOpen?.(db);\n  return db;\n}\n\n/** Injectable driver loaders (tests simulate a consumer env without better-sqlite3). */\ninterface DriverLoaders {\n  betterSqlite3?: () => Promise<unknown>;\n  nodeSqlite?: () => Promise<unknown>;\n}\nlet driverLoaderOverrides: DriverLoaders | undefined;\n\n/** Test-only. @internal */\nexport function _setDriverLoadersForTests(overrides: DriverLoaders | undefined): void {\n  driverLoaderOverrides = overrides;\n}\n\n/**\n * Adapt `node:sqlite`'s `DatabaseSync` to the better-sqlite3 surface this module's callers use\n * (`prepare/get/all/run`, `exec`, `close`, `pragma`, `loadExtension`). The error message below has\n * ALWAYS promised this fallback (\"or run on Node 22.5+ for built-in node:sqlite\") — before the\n * flicker-bug fix the promise was fabricated: only better-sqlite3 was ever tried, so every consumer\n * without the optional native dep lost memory tools AND got a per-turn stderr WARN.\n */\nfunction adaptNodeSqlite(db: {\n  prepare(sql: string): unknown;\n  exec(sql: string): void;\n  close(): void;\n  loadExtension?: (path: string) => void;\n}): ResilientSqliteDb {\n  const pragma = (statement: string, options?: { simple?: boolean }): unknown => {\n    const stmt = db.prepare(`PRAGMA ${statement}`) as {\n      get(): Record<string, unknown> | undefined;\n    };\n    const row = stmt.get();\n    if (options?.simple === true) {\n      return row === undefined ? undefined : Object.values(row)[0];\n    }\n    return row === undefined ? [] : [row];\n  };\n  return new Proxy(db as unknown as ResilientSqliteDb, {\n    get(target, prop, receiver) {\n      if (prop === \"pragma\") return pragma;\n      if (prop === \"loadExtension\" && typeof db.loadExtension !== \"function\") {\n        return () => {\n          throw new Error(\n            \"SQLite extension loading is unavailable on the node:sqlite fallback — install better-sqlite3 for sqlite-vec\",\n          );\n        };\n      }\n      const value = Reflect.get(target, prop, receiver) as unknown;\n      return typeof value === \"function\"\n        ? (value as (...a: unknown[]) => unknown).bind(target)\n        : value;\n    },\n  });\n}\n\n// PRE-EXISTING debt, exposed when M75 fixed the Biome config that used to abort before\n// sweeping these files (a nested root under refactor/). It is not new code and was not touched\n// by M75; refactoring SDK internals without review would trade a visible problem for a diff\n// risky. Tracked in usetheodev/theokit-sdk#151.\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: see the reason just above\nasync function loadDriver<T extends ResilientSqliteDb>(filePath: string): Promise<T> {\n  let betterSqliteCause: unknown;\n  try {\n    const mod = (await (driverLoaderOverrides?.betterSqlite3?.() ?? import(\"better-sqlite3\"))) as {\n      default?: unknown;\n    };\n    const Ctor = mod.default ?? mod;\n    if (typeof Ctor !== \"function\") {\n      throw new Error(`better-sqlite3 export is not a constructor (got ${typeof Ctor})`);\n    }\n    return new (Ctor as new (path: string) => unknown)(filePath) as T;\n  } catch (cause) {\n    betterSqliteCause = cause;\n  }\n  // Fallback: the Node 22.5+ built-in driver (the path the error message documents).\n  // `process.getBuiltinModule` (Node 22.3+) instead of `import(\"node:sqlite\")` — bundlers that\n  // predate the sqlite builtin rewrite the import specifier to a bare \"sqlite\" package (proven in\n  // the published dist: \"Cannot find package 'sqlite'\"), while getBuiltinModule is opaque to them.\n  try {\n    const mod = (await (driverLoaderOverrides?.nodeSqlite?.() ??\n      Promise.resolve(\n        (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule?.(\n          \"node:sqlite\",\n        ) ??\n          (() => {\n            throw new Error(\"node:sqlite built-in unavailable (Node < 22.3)\");\n          })(),\n      ))) as {\n      DatabaseSync: new (\n        path: string,\n      ) => {\n        prepare(sql: string): unknown;\n        exec(sql: string): void;\n        close(): void;\n      };\n    };\n    return adaptNodeSqlite(new mod.DatabaseSync(filePath)) as T;\n  } catch (nodeSqliteCause) {\n    const b =\n      betterSqliteCause instanceof Error ? betterSqliteCause.message : String(betterSqliteCause);\n    const n = nodeSqliteCause instanceof Error ? nodeSqliteCause.message : String(nodeSqliteCause);\n    throw new ConfigurationError(\n      `Failed to load SQLite driver. Install \\`better-sqlite3\\` or run on Node 22.5+ for built-in \\`node:sqlite\\`. better-sqlite3: ${b}; node:sqlite: ${n}`,\n      { code: \"sqlite_driver_unavailable\", cause: nodeSqliteCause },\n    );\n  }\n}\n\n/** True when an open error indicates an unreadable / corrupt database file. */\nexport function isCorruptionError(cause: unknown): boolean {\n  if (!(cause instanceof Error)) return false;\n  const msg = cause.message.toLowerCase();\n  return (\n    msg.includes(\"malformed\") ||\n    msg.includes(\"not a database\") ||\n    msg.includes(\"encrypted\") ||\n    msg.includes(\"disk image is malformed\")\n  );\n}\n\nasync function renameAside(filePath: string, label: string): Promise<void> {\n  const asidePath = `${filePath}.corrupt-${Date.now()}`;\n  await rename(filePath, asidePath).catch(() => undefined);\n  await rename(`${filePath}-wal`, `${asidePath}-wal`).catch(() => undefined);\n  await rename(`${filePath}-shm`, `${asidePath}-shm`).catch(() => undefined);\n  diag(\n    `[theokit-sdk] ${label} database corrupt; renamed aside to ${asidePath} and rebuilt schema\\n`,\n  );\n}\n"]}