@alvin0/ai-agent-sdk-core 0.1.0

package/dist/agent/tool/errors.d.ts

@@ -0,0 +1,82 @@
+import { AgentSdkError } from "../../errors/agent-sdk-error.js";
+//#region src/agent/tool/errors.d.ts
+/** What the loop should do with a tool failure. */
+type ToolErrorDisposition =
+/** Feed the message back as the tool's result and let the model try again. */
+'respond-to-model' |
+/** End the turn. A contract violation the model cannot recover from. */
+'fatal';
+/** Codes the tool layer itself produces. */
+declare const TOOL_ERROR_CODES: Readonly<{
+  /** The model named a tool that is not registered or not visible to it. */
+  readonly UNKNOWN_TOOL: 'UNKNOWN_TOOL';
+  /** Arguments failed the tool's own validation. */
+  readonly INVALID_ARGUMENTS: 'INVALID_ARGUMENTS';
+  /** The model emitted arguments that are not valid JSON. */
+  readonly MALFORMED_ARGUMENTS: 'MALFORMED_ARGUMENTS';
+  /** The tool exceeded its declared `timeoutMs`. */
+  readonly TIMEOUT: 'TOOL_TIMEOUT';
+  /** Cancelled after the tool body started. */
+  readonly ABORTED: 'TOOL_ABORTED';
+  /** Cancelled before the tool body was entered. */
+  readonly ABORTED_BEFORE_DISPATCH: 'TOOL_ABORTED_BEFORE_DISPATCH';
+  /** An interceptor refused the call. */
+  readonly DENIED: 'TOOL_DENIED';
+  /** The tool returned a value that is not losslessly JSON. */
+  readonly INVALID_RESULT: 'INVALID_TOOL_RESULT';
+  /** The tool threw something that carried no useful classification. */
+  readonly FAILED: 'TOOL_FAILED';
+  /** The turn had no remaining tool-call allowance. */
+  readonly BUDGET_EXHAUSTED: 'TOOL_BUDGET_EXHAUSTED';
+  /** Caller-owned durability failed before the tool side effect. */
+  readonly CHECKPOINT_FAILED: 'CHECKPOINT_FAILED';
+  /** In-process tool/interceptor ignored cancellation beyond the teardown budget. */
+  readonly TEARDOWN_TIMEOUT: 'TOOL_TEARDOWN_TIMEOUT';
+}>;
+/**
+ * A tool failure, carrying its disposition.
+ *
+ * Construct through {@link ToolError.respondToModel} or {@link ToolError.fatal}
+ * rather than the constructor, so the disposition is always a deliberate choice
+ * at the throw site instead of a default nobody looked at.
+ */
+declare class ToolError extends AgentSdkError {
+  /** Whether this ends the turn or becomes the tool's result. */
+  readonly disposition: ToolErrorDisposition;
+  constructor(message: string, disposition: ToolErrorDisposition, code?: string, options?: ErrorOptions);
+  /**
+   * The normal case: report the failure to the model and continue the turn.
+   *
+   * Write the message FOR THE MODEL. It is the only thing the model will see, so
+   * "file not found: /tmp/x.txt" is useful and "ENOENT" is not.
+   * @param message - model-facing explanation of what went wrong.
+   * @param code - stable code for routing and metrics.
+   * @param options - optional cause.
+   */
+  static respondToModel(message: string, code?: string, options?: ErrorOptions): ToolError;
+  /**
+   * The rare case: end the turn.
+   *
+   * Reserve this for a broken contract — a tool registered with the wrong shape,
+   * a host invariant violated — where letting the model retry would just produce
+   * the same failure with more tokens spent.
+   * @param message - operator-facing explanation.
+   * @param code - stable code for routing.
+   * @param options - optional cause.
+   */
+  static fatal(message: string, code?: string, options?: ErrorOptions): ToolError;
+}
+/**
+ * Read the disposition of an arbitrary thrown value.
+ *
+ * Anything that is not an explicitly fatal {@link ToolError} is treated as
+ * `respond-to-model`. That default is the point: an ordinary `TypeError` from
+ * inside a tool body should reach the model as a failed tool result, not kill the
+ * user's turn.
+ * @param value - the caught value.
+ * @returns the disposition to apply.
+ */
+declare function toolErrorDisposition(value: unknown): ToolErrorDisposition;
+//#endregion
+export { TOOL_ERROR_CODES, ToolError, ToolErrorDisposition, toolErrorDisposition };
+//# sourceMappingURL=errors.d.ts.map

package/dist/agent/tool/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../../src/agent/tool/errors.ts"],"mappings":";;;KAuBY;;;;;;cAOC,kBAAgB;;WAEb;;WAEK;;WAEE;;WAEZ;;WAEA;;WAEgB;;WAEjB;;WAEQ;;WAER;;WAEU;;WAEC;;WAED;;;;;;;;;cAUP,kBAAkB;;WAEpB,aAAa;EAEtB,YACE,iBACA,aAAa,sBACb,eACA,UAAU;;;;;;;;;;SAgBL,eACL,iBACA,eACA,UAAU,eACT;;;;;;;;;;;SAcI,MACL,iBACA,eACA,UAAU,eACT;;;;;;;;;;;;iBAeW,qBAAqB,iBAAiB"}

package/dist/agent/tool/errors.js

@@ -0,0 +1,2 @@
+import{AgentSdkError as e}from"../../errors/agent-sdk-error.js";const t=Object.freeze({UNKNOWN_TOOL:`UNKNOWN_TOOL`,INVALID_ARGUMENTS:`INVALID_ARGUMENTS`,MALFORMED_ARGUMENTS:`MALFORMED_ARGUMENTS`,TIMEOUT:`TOOL_TIMEOUT`,ABORTED:`TOOL_ABORTED`,ABORTED_BEFORE_DISPATCH:`TOOL_ABORTED_BEFORE_DISPATCH`,DENIED:`TOOL_DENIED`,INVALID_RESULT:`INVALID_TOOL_RESULT`,FAILED:`TOOL_FAILED`,BUDGET_EXHAUSTED:`TOOL_BUDGET_EXHAUSTED`,CHECKPOINT_FAILED:`CHECKPOINT_FAILED`,TEARDOWN_TIMEOUT:`TOOL_TEARDOWN_TIMEOUT`});var n=class n extends e{disposition;constructor(e,n,r=t.FAILED,i){super(e,r,i),this.name=`ToolError`,this.disposition=n}static respondToModel(e,r=t.FAILED,i){return new n(e,`respond-to-model`,r,i)}static fatal(e,r=t.FAILED,i){return new n(e,`fatal`,r,i)}};function r(e){return e instanceof n&&e.disposition===`fatal`?`fatal`:`respond-to-model`}export{t as TOOL_ERROR_CODES,n as ToolError,r as toolErrorDisposition};
+//# sourceMappingURL=errors.js.map

package/dist/agent/tool/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../../src/agent/tool/errors.ts"],"sourcesContent":["/**\n * The tool error taxonomy, and the single most important decision in the whole\n * tool layer: **a tool failure is normally INPUT FOR THE MODEL, not an exception\n * that ends the turn.**\n *\n * Both reference implementations converged on this independently. Codex spells it\n * as a two-variant enum (`FunctionCallError::{RespondToModel, Fatal}`) and\n * deepseek-harness spells it as a registry that normalizes any throw into an\n * `isError: true` result. The reasoning is the same: a model that asked for a\n * file that does not exist, or passed a malformed argument, has made a mistake it\n * can recover from — if it is told. Aborting the turn throws away everything the\n * model has already accomplished and gives the user nothing.\n *\n * So a thrown tool error becomes a tool result by default. `fatal` is the narrow\n * exception, reserved for a violated contract that the model cannot fix by trying\n * something else.\n *\n * @module ai-agent-sdk/agent/tool/errors\n */\n\nimport { AgentSdkError } from '../../errors/index.ts'\n\n/** What the loop should do with a tool failure. */\nexport type ToolErrorDisposition =\n  /** Feed the message back as the tool's result and let the model try again. */\n  | 'respond-to-model'\n  /** End the turn. A contract violation the model cannot recover from. */\n  | 'fatal'\n\n/** Codes the tool layer itself produces. */\nexport const TOOL_ERROR_CODES = Object.freeze({\n  /** The model named a tool that is not registered or not visible to it. */\n  UNKNOWN_TOOL: 'UNKNOWN_TOOL',\n  /** Arguments failed the tool's own validation. */\n  INVALID_ARGUMENTS: 'INVALID_ARGUMENTS',\n  /** The model emitted arguments that are not valid JSON. */\n  MALFORMED_ARGUMENTS: 'MALFORMED_ARGUMENTS',\n  /** The tool exceeded its declared `timeoutMs`. */\n  TIMEOUT: 'TOOL_TIMEOUT',\n  /** Cancelled after the tool body started. */\n  ABORTED: 'TOOL_ABORTED',\n  /** Cancelled before the tool body was entered. */\n  ABORTED_BEFORE_DISPATCH: 'TOOL_ABORTED_BEFORE_DISPATCH',\n  /** An interceptor refused the call. */\n  DENIED: 'TOOL_DENIED',\n  /** The tool returned a value that is not losslessly JSON. */\n  INVALID_RESULT: 'INVALID_TOOL_RESULT',\n  /** The tool threw something that carried no useful classification. */\n  FAILED: 'TOOL_FAILED',\n  /** The turn had no remaining tool-call allowance. */\n  BUDGET_EXHAUSTED: 'TOOL_BUDGET_EXHAUSTED',\n  /** Caller-owned durability failed before the tool side effect. */\n  CHECKPOINT_FAILED: 'CHECKPOINT_FAILED',\n  /** In-process tool/interceptor ignored cancellation beyond the teardown budget. */\n  TEARDOWN_TIMEOUT: 'TOOL_TEARDOWN_TIMEOUT',\n} as const)\n\n/**\n * A tool failure, carrying its disposition.\n *\n * Construct through {@link ToolError.respondToModel} or {@link ToolError.fatal}\n * rather than the constructor, so the disposition is always a deliberate choice\n * at the throw site instead of a default nobody looked at.\n */\nexport class ToolError extends AgentSdkError {\n  /** Whether this ends the turn or becomes the tool's result. */\n  readonly disposition: ToolErrorDisposition\n\n  constructor(\n    message: string,\n    disposition: ToolErrorDisposition,\n    code: string = TOOL_ERROR_CODES.FAILED,\n    options?: ErrorOptions,\n  ) {\n    super(message, code, options)\n    this.name = 'ToolError'\n    this.disposition = disposition\n  }\n\n  /**\n   * The normal case: report the failure to the model and continue the turn.\n   *\n   * Write the message FOR THE MODEL. It is the only thing the model will see, so\n   * \"file not found: /tmp/x.txt\" is useful and \"ENOENT\" is not.\n   * @param message - model-facing explanation of what went wrong.\n   * @param code - stable code for routing and metrics.\n   * @param options - optional cause.\n   */\n  static respondToModel(\n    message: string,\n    code: string = TOOL_ERROR_CODES.FAILED,\n    options?: ErrorOptions,\n  ): ToolError {\n    return new ToolError(message, 'respond-to-model', code, options)\n  }\n\n  /**\n   * The rare case: end the turn.\n   *\n   * Reserve this for a broken contract — a tool registered with the wrong shape,\n   * a host invariant violated — where letting the model retry would just produce\n   * the same failure with more tokens spent.\n   * @param message - operator-facing explanation.\n   * @param code - stable code for routing.\n   * @param options - optional cause.\n   */\n  static fatal(\n    message: string,\n    code: string = TOOL_ERROR_CODES.FAILED,\n    options?: ErrorOptions,\n  ): ToolError {\n    return new ToolError(message, 'fatal', code, options)\n  }\n}\n\n/**\n * Read the disposition of an arbitrary thrown value.\n *\n * Anything that is not an explicitly fatal {@link ToolError} is treated as\n * `respond-to-model`. That default is the point: an ordinary `TypeError` from\n * inside a tool body should reach the model as a failed tool result, not kill the\n * user's turn.\n * @param value - the caught value.\n * @returns the disposition to apply.\n */\nexport function toolErrorDisposition(value: unknown): ToolErrorDisposition {\n  return value instanceof ToolError && value.disposition === 'fatal'\n    ? 'fatal'\n    : 'respond-to-model'\n}\n"],"mappings":"gEA8BA,MAAa,EAAmB,OAAO,OAAO,CAE5C,aAAc,eAEd,kBAAmB,oBAEnB,oBAAqB,sBAErB,QAAS,eAET,QAAS,eAET,wBAAyB,+BAEzB,OAAQ,cAER,eAAgB,sBAEhB,OAAQ,cAER,iBAAkB,wBAElB,kBAAmB,oBAEnB,iBAAkB,uBACpB,CAAU,EASV,IAAa,EAAb,MAAa,UAAkB,CAAc,CAE3C,YAEA,YACE,EACA,EACA,EAAe,EAAiB,OAChC,EACA,CACA,MAAM,EAAS,EAAM,CAAO,EAC5B,KAAK,KAAO,YACZ,KAAK,YAAc,CACrB,CAWA,OAAO,eACL,EACA,EAAe,EAAiB,OAChC,EACW,CACX,OAAO,IAAI,EAAU,EAAS,mBAAoB,EAAM,CAAO,CACjE,CAYA,OAAO,MACL,EACA,EAAe,EAAiB,OAChC,EACW,CACX,OAAO,IAAI,EAAU,EAAS,QAAS,EAAM,CAAO,CACtD,CACF,EAYA,SAAgB,EAAqB,EAAsC,CACzE,OAAO,aAAiB,GAAa,EAAM,cAAgB,QACvD,QACA,kBACN"}

package/dist/agent/tool/execution.d.ts

@@ -0,0 +1,60 @@
+import { JsonObject } from "../../primitives/json.js";
+import { ToolExecutionResult } from "./definition.js";
+import { ToolCallContext, ToolInterceptor } from "./pipeline.js";
+//#region src/agent/tool/execution.d.ts
+/** Claims describe what a backend actually enforces, not permissions granted by policy. */
+interface ToolExecutionCapabilities {
+  readonly cancellation: 'cooperative' | 'forced';
+  readonly filesystem: 'host' | 'restricted' | 'none';
+  readonly network: 'host' | 'restricted' | 'none';
+  readonly cleanup: 'best-effort' | 'guaranteed';
+}
+interface ToolExecutionRequest {
+  readonly operationId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  /** Trusted host identity; never sourced from model arguments. */
+  readonly identity: JsonObject;
+  readonly signal: AbortSignal;
+}
+interface ToolExecutionBackend {
+  readonly id: string;
+  readonly capabilities: ToolExecutionCapabilities;
+  execute(request: ToolExecutionRequest, local: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>;
+}
+declare const localToolExecutionBackend: ToolExecutionBackend;
+interface ToolOperation {
+  readonly operationId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly identity: JsonObject;
+}
+type ToolOperationClaim = {
+  readonly status: 'claimed';
+} | {
+  readonly status: 'completed';
+  readonly operation: ToolOperation;
+  readonly result: ToolExecutionResult;
+} | {
+  readonly status: 'unknown';
+  readonly operation: ToolOperation;
+};
+/** Separate from conversation memory. The host adapter must durably and atomically claim an ID.
+ * An existing in-progress claim is unknown after restart, never implicitly retryable.
+ * complete must persist before resolving. Reconciliation is host-owned. */
+interface ToolExecutionStore {
+  claim(operation: ToolOperation, signal: AbortSignal): Promise<ToolOperationClaim>;
+  complete(operation: ToolOperation, result: ToolExecutionResult, signal: AbortSignal): Promise<void>;
+}
+/** Attach via session.interceptors. Policy and approval still run before this adapter,
+ * and post-policy still sanitizes both fresh and recovered results. No automatic retry. */
+declare function createToolExecutionInterceptor(options: {
+  readonly backend?: ToolExecutionBackend;
+  readonly identity: JsonObject;
+  /** Stable across recovery, scoped to tenant/session by the authenticated host. */
+  readonly operationId: (call: ToolCallContext) => string;
+  readonly store?: ToolExecutionStore;
+}): ToolInterceptor;
+//#endregion
+export { ToolExecutionBackend, ToolExecutionCapabilities, ToolExecutionRequest, ToolExecutionStore, ToolOperation, ToolOperationClaim, createToolExecutionInterceptor, localToolExecutionBackend };
+//# sourceMappingURL=execution.d.ts.map

package/dist/agent/tool/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","names":[],"sources":["../../../src/agent/tool/execution.ts"],"mappings":";;;;;UAMiB;WACN;WACA;WACA;WACA;;UAEM;WACN;WACA;WACA;;WAEA,UAAU;WACV,QAAQ;;UAEF;WACN;WACA,cAAc;EACvB,QAAQ,SAAS,sBAAsB,aAAa,QAAQ,uBAAuB,QAAQ;;cAEhF,2BAA2B;UAMvB;WACN;WACA;WACA;WACA,UAAU;;KAET;WACG;;WACA;WAA8B,WAAW;WAAwB,QAAQ;;WACzE;WAA4B,WAAW;;;;;UAKrC;EACf,MAAM,WAAW,eAAe,QAAQ,cAAc,QAAQ;EAC9D,SAAS,WAAW,eAAe,QAAQ,qBAAqB,QAAQ,cAAc;;;;iBAKxE,+BAA+B;WACpC,UAAU;WACV,UAAU;;WAEV,cAAc,MAAM;WACpB,QAAQ;IACf"}

package/dist/agent/tool/execution.js

@@ -0,0 +1,2 @@
+import{isJsonValue as e}from"../../primitives/json.js";import{detachedFrozen as t}from"../../primitives/snapshot.js";import{ToolError as n}from"./errors.js";const r=Object.freeze({id:`local`,capabilities:Object.freeze({cancellation:`cooperative`,filesystem:`host`,network:`host`,cleanup:`best-effort`}),execute:(e,t)=>t()});function i(i){let o=i.backend??r,s=o.execute.bind(o),c=t(i.identity),l=i.operationId,u=i.store,d=u?.claim.bind(u),f=u?.complete.bind(u);return Object.freeze({name:`execution:${o.id}`,around:async(r,i)=>{let o=l(r);if(typeof o!=`string`||o.length===0||o.length>512)throw n.fatal(`invalid operation identity`,`INVALID_OPERATION_ID`);let u=t({operationId:o,toolName:r.toolName,args:r.args,identity:c});if(r.signal.aborted)throw n.fatal(`execution cancelled`,`TOOL_ABORTED`);if(d!==void 0){if(!e(u.args)||!e(u.identity))throw n.fatal(`durable operation input must be lossless JSON`,`INVALID_OPERATION_INPUT`);let i=await d(u,r.signal);if(i.status!==`claimed`){if(a(i.operation)!==a(u))throw n.fatal(`operation identity conflicts with saved input`,`OPERATION_ID_CONFLICT`);if(i.status===`unknown`)throw n.fatal(`operation outcome is unknown; reconcile before retrying`,`OPERATION_OUTCOME_UNKNOWN`);return t(i.result)}}if(r.signal.aborted)throw n.fatal(`execution cancelled after claim; reconcile operation`,`OPERATION_OUTCOME_UNKNOWN`);let p=await s({...u,signal:r.signal},i);return await f?.(u,p,r.signal),p}})}function a(e){return e===void 0?`undefined`:typeof e!=`object`||!e?JSON.stringify(e):Array.isArray(e)?`[${e.map(a).join(`,`)}]`:`{${Object.keys(e).sort().map(t=>`${JSON.stringify(t)}:${a(e[t])}`).join(`,`)}}`}export{i as createToolExecutionInterceptor,r as localToolExecutionBackend};
+//# sourceMappingURL=execution.js.map

package/dist/agent/tool/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","names":[],"sources":["../../../src/agent/tool/execution.ts"],"sourcesContent":["import { isJsonValue, detachedFrozen, type JsonObject } from '../../primitives/index.ts'\nimport type { ToolExecutionResult } from './definition.ts'\nimport { ToolError } from './errors.ts'\nimport type { ToolCallContext, ToolInterceptor } from './pipeline.ts'\n\n/** Claims describe what a backend actually enforces, not permissions granted by policy. */\nexport interface ToolExecutionCapabilities {\n  readonly cancellation: 'cooperative' | 'forced'\n  readonly filesystem: 'host' | 'restricted' | 'none'\n  readonly network: 'host' | 'restricted' | 'none'\n  readonly cleanup: 'best-effort' | 'guaranteed'\n}\nexport interface ToolExecutionRequest {\n  readonly operationId: string\n  readonly toolName: string\n  readonly args: unknown\n  /** Trusted host identity; never sourced from model arguments. */\n  readonly identity: JsonObject\n  readonly signal: AbortSignal\n}\nexport interface ToolExecutionBackend {\n  readonly id: string\n  readonly capabilities: ToolExecutionCapabilities\n  execute(request: ToolExecutionRequest, local: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>\n}\nexport const localToolExecutionBackend: ToolExecutionBackend = Object.freeze({\n  id: 'local',\n  capabilities: Object.freeze({ cancellation: 'cooperative', filesystem: 'host', network: 'host', cleanup: 'best-effort' }),\n  execute: (_request: ToolExecutionRequest, local: () => Promise<ToolExecutionResult>) => local(),\n})\n\nexport interface ToolOperation {\n  readonly operationId: string\n  readonly toolName: string\n  readonly args: unknown\n  readonly identity: JsonObject\n}\nexport type ToolOperationClaim =\n  | { readonly status: 'claimed' }\n  | { readonly status: 'completed'; readonly operation: ToolOperation; readonly result: ToolExecutionResult }\n  | { readonly status: 'unknown'; readonly operation: ToolOperation }\n\n/** Separate from conversation memory. The host adapter must durably and atomically claim an ID.\n * An existing in-progress claim is unknown after restart, never implicitly retryable.\n * complete must persist before resolving. Reconciliation is host-owned. */\nexport interface ToolExecutionStore {\n  claim(operation: ToolOperation, signal: AbortSignal): Promise<ToolOperationClaim>\n  complete(operation: ToolOperation, result: ToolExecutionResult, signal: AbortSignal): Promise<void>\n}\n\n/** Attach via session.interceptors. Policy and approval still run before this adapter,\n * and post-policy still sanitizes both fresh and recovered results. No automatic retry. */\nexport function createToolExecutionInterceptor(options: {\n  readonly backend?: ToolExecutionBackend\n  readonly identity: JsonObject\n  /** Stable across recovery, scoped to tenant/session by the authenticated host. */\n  readonly operationId: (call: ToolCallContext) => string\n  readonly store?: ToolExecutionStore\n}): ToolInterceptor {\n  const backend = options.backend ?? localToolExecutionBackend\n  const execute = backend.execute.bind(backend)\n  const identity = detachedFrozen(options.identity)\n  const operationId = options.operationId\n  const store = options.store\n  const claim = store?.claim.bind(store), complete = store?.complete.bind(store)\n  return Object.freeze({\n    name: `execution:${backend.id}`,\n    around: async (call: ToolCallContext, local: () => Promise<ToolExecutionResult>) => {\n      const id = operationId(call)\n      if (typeof id !== 'string' || id.length === 0 || id.length > 512) throw ToolError.fatal('invalid operation identity', 'INVALID_OPERATION_ID')\n      const operation = detachedFrozen({ operationId: id, toolName: call.toolName, args: call.args, identity })\n      if (call.signal.aborted) throw ToolError.fatal('execution cancelled', 'TOOL_ABORTED')\n      if (claim !== undefined) {\n        if (!isJsonValue(operation.args) || !isJsonValue(operation.identity)) throw ToolError.fatal('durable operation input must be lossless JSON', 'INVALID_OPERATION_INPUT')\n        const previous = await claim(operation, call.signal)\n        if (previous.status !== 'claimed') {\n          if (canonical(previous.operation) !== canonical(operation)) throw ToolError.fatal('operation identity conflicts with saved input', 'OPERATION_ID_CONFLICT')\n          if (previous.status === 'unknown') throw ToolError.fatal('operation outcome is unknown; reconcile before retrying', 'OPERATION_OUTCOME_UNKNOWN')\n          return detachedFrozen(previous.result)\n        }\n      }\n      if (call.signal.aborted) throw ToolError.fatal('execution cancelled after claim; reconcile operation', 'OPERATION_OUTCOME_UNKNOWN')\n      // A throw, cancellation, or failed completion write leaves the durable claim\n      // unresolved. A subsequent attempt must reconcile; it cannot execute again.\n      const result = await execute({ ...operation, signal: call.signal }, local)\n      await complete?.(operation, result, call.signal)\n      return result\n    },\n  })\n}\n\nfunction canonical(value: unknown): string {\n  if (value === undefined) return 'undefined'\n  if (value === null || typeof value !== 'object') return JSON.stringify(value)\n  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`\n  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`).join(',')}}`\n}\n"],"mappings":"6JAyBA,MAAa,EAAkD,OAAO,OAAO,CAC3E,GAAI,QACJ,aAAc,OAAO,OAAO,CAAE,aAAc,cAAe,WAAY,OAAQ,QAAS,OAAQ,QAAS,aAAc,CAAC,EACxH,SAAU,EAAgC,IAA8C,EAAM,CAChG,CAAC,EAuBD,SAAgB,EAA+B,EAM3B,CAClB,IAAM,EAAU,EAAQ,SAAW,EAC7B,EAAU,EAAQ,QAAQ,KAAK,CAAO,EACtC,EAAW,EAAe,EAAQ,QAAQ,EAC1C,EAAc,EAAQ,YACtB,EAAQ,EAAQ,MAChB,EAAQ,GAAO,MAAM,KAAK,CAAK,EAAG,EAAW,GAAO,SAAS,KAAK,CAAK,EAC7E,OAAO,OAAO,OAAO,CACnB,KAAM,aAAa,EAAQ,KAC3B,OAAQ,MAAO,EAAuB,IAA8C,CAClF,IAAM,EAAK,EAAY,CAAI,EAC3B,GAAI,OAAO,GAAO,UAAY,EAAG,SAAW,GAAK,EAAG,OAAS,IAAK,MAAM,EAAU,MAAM,6BAA8B,sBAAsB,EAC5I,IAAM,EAAY,EAAe,CAAE,YAAa,EAAI,SAAU,EAAK,SAAU,KAAM,EAAK,KAAM,UAAS,CAAC,EACxG,GAAI,EAAK,OAAO,QAAS,MAAM,EAAU,MAAM,sBAAuB,cAAc,EACpF,GAAI,IAAU,IAAA,GAAW,CACvB,GAAI,CAAC,EAAY,EAAU,IAAI,GAAK,CAAC,EAAY,EAAU,QAAQ,EAAG,MAAM,EAAU,MAAM,gDAAiD,yBAAyB,EACtK,IAAM,EAAW,MAAM,EAAM,EAAW,EAAK,MAAM,EACnD,GAAI,EAAS,SAAW,UAAW,CACjC,GAAI,EAAU,EAAS,SAAS,IAAM,EAAU,CAAS,EAAG,MAAM,EAAU,MAAM,gDAAiD,uBAAuB,EAC1J,GAAI,EAAS,SAAW,UAAW,MAAM,EAAU,MAAM,0DAA2D,2BAA2B,EAC/I,OAAO,EAAe,EAAS,MAAM,CACvC,CACF,CACA,GAAI,EAAK,OAAO,QAAS,MAAM,EAAU,MAAM,uDAAwD,2BAA2B,EAGlI,IAAM,EAAS,MAAM,EAAQ,CAAE,GAAG,EAAW,OAAQ,EAAK,MAAO,EAAG,CAAK,EAEzE,OADA,MAAM,IAAW,EAAW,EAAQ,EAAK,MAAM,EACxC,CACT,CACF,CAAC,CACH,CAEA,SAAS,EAAU,EAAwB,CAIzC,OAHI,IAAU,IAAA,GAAkB,YACV,OAAO,GAAU,WAAnC,EAAoD,KAAK,UAAU,CAAK,EACxE,MAAM,QAAQ,CAAK,EAAU,IAAI,EAAM,IAAI,CAAS,CAAC,CAAC,KAAK,GAAG,EAAE,GAC7D,IAAI,OAAO,KAAK,CAAK,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAO,GAAG,KAAK,UAAU,CAAG,EAAE,GAAG,EAAW,EAAkC,EAAI,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,EAC5I"}

package/dist/agent/tool/output-budget.d.ts

@@ -0,0 +1,159 @@
+import { ContentBlock } from "../../message/content.js";
+import { ToolDefinition } from "./definition.js";
+//#region src/agent/tool/output-budget.d.ts
+/**
+ * What happens to output that exceeds its budget.
+ *
+ * - `auto` — spill when a store is mounted, otherwise truncate.
+ * - `truncate` — always cut the middle; never needs a store.
+ * - `spill` — save the full text and show a preview; falls back to truncating
+ *   when no store is mounted or the store fails, because losing the result
+ *   entirely is worse than shortening it.
+ */
+type ToolOutputOverflowPolicy = 'auto' | 'truncate' | 'spill';
+/** A saved copy of one oversized tool result. */
+interface SpillRecord {
+  /** Opaque handle the retrieval tool resolves; also shown to the model. */
+  readonly locator: string;
+  /** Exact size of the saved text. */
+  readonly bytes: number;
+  /**
+   * One sentence telling the model how to get the rest.
+   *
+   * Written by the backend, because only it knows what the locator IS — a file
+   * a shell can grep, or a handle only the built-in retrieval tool resolves.
+   */
+  readonly retrieval: string;
+}
+/** A slice of a saved tool result. */
+interface SpillSlice {
+  readonly text: string;
+  /** Total code points in the saved text, so a reader can page through it. */
+  readonly totalChars: number;
+  /** Where this slice starts. */
+  readonly offset: number;
+}
+/**
+ * Where oversized tool output goes when the policy spills it.
+ *
+ * The port is deliberately tiny: core is a universal package and cannot open a
+ * file, so a host that wants durable spill implements this over its own
+ * storage. {@link createMemorySpillStore} covers the common case.
+ */
+interface SpillStore {
+  /**
+   * Save one oversized result.
+   * @param text - The complete model-facing text.
+   * @param context - What produced it, for naming and diagnostics.
+   * @returns The locator the model can retrieve it by.
+   */
+  save(text: string, context: {
+    readonly toolName: string;
+    readonly callId: string;
+  }): Promise<SpillRecord> | SpillRecord;
+  /**
+   * Read part of a saved result.
+   * @param locator - A locator returned by {@link SpillStore.save}.
+   * @param range - Where to start and how much to read, in code points.
+   * @returns The slice, or undefined when the locator is unknown or expired.
+   */
+  read(locator: string, range: {
+    readonly offset: number;
+    readonly limit: number;
+  }): Promise<SpillSlice | undefined> | SpillSlice | undefined;
+  /**
+   * Find matching lines in a saved result.
+   * @param locator - A locator returned by {@link SpillStore.save}.
+   * @param pattern - A regular expression source, matched per line.
+   * @param limit - Maximum lines returned.
+   * @returns Matching `line-number: text` entries, or undefined when unknown.
+   */
+  search(locator: string, pattern: string, limit: number): Promise<readonly string[] | undefined> | readonly string[] | undefined;
+}
+/** Bounds for the built-in in-process store. */
+interface MemorySpillStoreLimits {
+  /** Saved results kept before the oldest is evicted. Defaults to 64. */
+  readonly maxEntries?: number;
+  /** Total characters kept across all entries. Defaults to 32,000,000. */
+  readonly maxChars?: number;
+}
+/**
+ * A spill store that keeps text in this process.
+ *
+ * Universal, so it works in a browser and in a worker as well as on a server,
+ * and enough for the case the policy exists for: the text leaves the model's
+ * context immediately and is read back through the retrieval tool. It is not
+ * durable — a restart loses it, and the locators in an old transcript stop
+ * resolving. A host that needs durability implements {@link SpillStore} over
+ * its own filesystem or object storage.
+ * @param limits - Retention bounds.
+ * @returns The store.
+ */
+declare function createMemorySpillStore(limits?: MemorySpillStoreLimits): SpillStore;
+/**
+ * Deterministic token estimate for text.
+ *
+ * Four characters per token, the same heuristic compaction uses, and the same
+ * order of magnitude as Codex's `approx_token_count`. It is an estimate: a real
+ * tokenizer differs, and dense scripts differ more. It is used to decide when
+ * to shorten output, never to bill anything.
+ * @param text - The text to measure.
+ * @returns The estimated token count.
+ */
+declare function estimateTextTokens(text: string): number;
+/**
+ * Estimated tokens for the text a tool result puts in front of the model.
+ *
+ * Only text is counted. An image block is left alone — shortening it produces a
+ * corrupt image rather than a smaller one.
+ * @param content - The result's content blocks.
+ * @returns The estimated token count of the text blocks.
+ */
+declare function estimateTextBlockTokens(content: readonly ContentBlock[]): number;
+/** The result of shortening one oversized text. */
+interface TruncatedText {
+  readonly text: string;
+  /** Estimated tokens the original held. */
+  readonly originalTokens: number;
+}
+/**
+ * Cut the middle out of a text to fit a token budget.
+ *
+ * The middle goes because the two ends carry the most: a command's invocation
+ * and its verdict, a file's header and its tail. Codex splits its budget the
+ * same way. The marker states how much left, so the model can see that it is
+ * reading a fragment rather than a short result.
+ * @param text - The full text.
+ * @param maxTokens - Estimated tokens the model may read.
+ * @returns The shortened text and what the original held.
+ */
+declare function truncateMiddleToTokens(text: string, maxTokens: number): TruncatedText;
+/**
+ * The head/tail preview shown in place of a spilled result.
+ * @param text - The full text.
+ * @param maxTokens - Estimated tokens the preview may hold.
+ * @returns The preview.
+ */
+declare function previewForSpill(text: string, maxTokens: number): string;
+/** The name the retrieval tool is registered under. */
+declare const SPILL_TOOL_NAME = "read_tool_output";
+interface ReadSpillArgs {
+  readonly locator: string;
+  readonly offset?: number;
+  readonly limit?: number;
+  readonly pattern?: string;
+}
+/**
+ * The tool that reads back what a spill took out of the context.
+ *
+ * Spilling without this would be worse than truncating: the model would be
+ * told its output exists somewhere and given no way to reach it. Registered
+ * automatically wherever a store is mounted.
+ * @param store - The mounted store.
+ * @param defaultLimit - Characters one read returns when none is asked for.
+ * @returns The tool definition.
+ */
+declare function readSpillTool(store: SpillStore, defaultLimit?: number): ToolDefinition<ReadSpillArgs>;
+//#endregion
+export { MemorySpillStoreLimits, SPILL_TOOL_NAME, SpillRecord, SpillSlice, SpillStore, ToolOutputOverflowPolicy, TruncatedText, createMemorySpillStore, estimateTextBlockTokens, estimateTextTokens, previewForSpill, readSpillTool, truncateMiddleToTokens };
+//# sourceMappingURL=output-budget.d.ts.map

package/dist/agent/tool/output-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-budget.d.ts","names":[],"sources":["../../../src/agent/tool/output-budget.ts"],"mappings":";;;;;;;;;;;;KAqCY;;UAGK;;WAEN;;WAEA;;;;;;;WAOA;;;UAIM;WACN;;WAEA;;WAEA;;;;;;;;;UAUM;;;;;;;EAOf,KAAK,cAAc;aAAoB;aAA2B;MAClE,QAAQ,eAAe;;;;;;;EAOvB,KAAK,iBAAiB;aAAkB;aAAyB;MACjE,QAAQ,0BAA0B;;;;;;;;EAQlC,OAAO,iBAAiB,iBAAiB,gBACzC;;;UAIe;;WAEN;;WAEA;;;;;;;;;;;;;;iBAeK,uBAAuB,SAAQ,yBAA8B;;;;;;;;;;;iBAiF7D,mBAAmB;;;;;;;;;iBAYnB,wBAAwB,kBAAkB;;UAQzC;WACN;;WAEA;;;;;;;;;;;;;iBAcK,uBAAuB,cAAc,oBAAoB;;;;;;;iBAyBzD,gBAAgB,cAAc;;cAKjC;UAEH;WACC;WACA;WACA;WACA;;;;;;;;;;;;iBAaK,cAAc,OAAO,YAAY,wBAAuB,eAAe"}

package/dist/agent/tool/output-budget.js

@@ -0,0 +1,3 @@
+import{defineTool as e}from"./definition.js";function t(e={}){let t=n(e.maxEntries??64,`maxEntries`),r=n(e.maxChars??32e6,`maxChars`),i=new Map,a=0,o=0,s=e=>{for(;(i.size>=t||a+e>r)&&i.size>0;){let e=i.keys().next().value;if(e===void 0)break;a-=[...i.get(e)??``].length,i.delete(e)}};return{save(e,t){let n=[...e].length;s(n),o+=1;let r=`spill:${t.toolName}:${String(o)}`;return i.set(r,e),a+=n,{locator:r,bytes:new TextEncoder().encode(e).byteLength,retrieval:`Call read_tool_output with locator "${r}" to read the rest, or with a pattern to search it.`}},read(e,t){let n=i.get(e);if(n===void 0)return;let r=[...n],a=Math.min(Math.max(0,t.offset),r.length);return{text:r.slice(a,a+Math.max(1,t.limit)).join(``),totalChars:r.length,offset:a}},search(e,t,n){let r=i.get(e);if(r===void 0)return;let a=new RegExp(t),o=[],s=r.split(`
+`);for(let e=0;e<s.length&&o.length<n;e++){let t=s[e]??``;a.test(t)&&o.push(`${String(e+1)}: ${t}`)}return Object.freeze(o)}}}function n(e,t){if(!Number.isSafeInteger(e)||e<1)throw RangeError(`spill store ${t} must be a positive safe integer`);return e}function r(e){return Math.ceil(e.length/4)}function i(e){return e.reduce((e,t)=>t.type===`text`?e+r(t.text):e,0)}function a(e,t){let n=r(e);if(n<=t)return{text:e,originalTokens:n};let i=Math.max(1,t*4),a=Math.max(1,Math.floor(i*.66)),o=Math.max(0,i-a),s=[...e],c=n-t,l=`\n\n[... ${String(c)} estimated tokens omitted from the middle ...]\n\n`;return{text:s.slice(0,a).join(``)+l+(o===0?``:s.slice(s.length-o).join(``)),originalTokens:n}}function o(e,t){return a(e,t).text}const s=`read_tool_output`;function c(t,n=8e3){return e({name:s,description:`Read or search the full output of an earlier tool call that was too large to show in full. Pass the locator from that result. Use pattern to find matching lines, or offset/limit to page through it.`,parameters:{type:`object`,properties:{locator:{type:`string`,description:`The locator printed with the shortened result.`},offset:{type:`number`,description:`Character offset to start reading from.`},limit:{type:`number`,description:`Characters to read; defaults to ${String(n)}.`},pattern:{type:`string`,description:`Regular expression matched per line; returns matching lines with numbers.`}},required:[`locator`],additionalProperties:!1},budgetExempt:!0,parse:u,isConcurrencySafe:()=>!0,execute:async e=>{if(e.pattern!==void 0){let n=await t.search(e.locator,e.pattern,200);return n===void 0?l(e.locator):{locator:e.locator,matches:[...n]}}let r=await t.read(e.locator,{offset:e.offset??0,limit:e.limit??n});if(r===void 0)return l(e.locator);let i=r.offset+[...r.text].length;return{locator:e.locator,offset:r.offset,nextOffset:i<r.totalChars?i:null,totalChars:r.totalChars,text:r.text}}})}function l(e){return{locator:e,error:`no saved output for this locator; it may have expired. Re-run the original call more narrowly if you still need it.`}}function u(e){if(typeof e!=`object`||!e)throw TypeError(`arguments must be an object`);let t=e,n=t.locator;if(typeof n!=`string`||n.length===0)throw TypeError(`locator must be a non-empty string`);let r=d(t.offset,`offset`),i=d(t.limit,`limit`),a=t.pattern;if(a!==void 0&&typeof a!=`string`)throw TypeError(`pattern must be a string`);return{locator:n,...r===void 0?{}:{offset:r},...i===void 0?{}:{limit:i},...a===void 0||a===``?{}:{pattern:a}}}function d(e,t){if(e!==void 0){if(typeof e!=`number`||!Number.isFinite(e)||e<0)throw TypeError(`${t} must be a non-negative number`);return Math.floor(e)}}export{s as SPILL_TOOL_NAME,t as createMemorySpillStore,i as estimateTextBlockTokens,r as estimateTextTokens,o as previewForSpill,c as readSpillTool,a as truncateMiddleToTokens};
+//# sourceMappingURL=output-budget.js.map

package/dist/agent/tool/output-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-budget.js","names":[],"sources":["../../../src/agent/tool/output-budget.ts"],"sourcesContent":["/**\n * How much of a tool's output the model is allowed to read.\n *\n * A tool result enters the model's context unchanged, so one `cat` of a\n * generated bundle can spend a context window that the turn then has no way to\n * recover — the provider rejects the next request, and everything already paid\n * for is lost. Both reference harnesses stop this at the RESULT boundary rather\n * than waiting for the request to be assembled, and they differ only in where\n * the removed text goes:\n *\n * - **Codex** truncates the middle to a token budget and tells the model how\n *   much was dropped (`truncate_middle_with_token_budget`). Cheap and needs no\n *   storage; the model recovers by re-running a narrower command.\n * - **The DeepSeek harness** spills the full text to a store, and hands the\n *   model a bounded preview plus a locator to read or search (`dsh-spill`).\n *   Nothing is lost, but it needs somewhere to put the text.\n *\n * Both are offered here. `auto` — the default — takes the second when a store\n * is mounted and the first when none is, so the cheap path works everywhere and\n * the lossless one turns itself on the moment it can.\n *\n * @module ai-agent-sdk/agent/tool/output-budget\n */\n\nimport type { ContentBlock } from '../../message/index.ts'\nimport type { JsonObject } from '../../primitives/index.ts'\nimport { defineTool, type ToolDefinition } from './definition.ts'\n\n/**\n * What happens to output that exceeds its budget.\n *\n * - `auto` — spill when a store is mounted, otherwise truncate.\n * - `truncate` — always cut the middle; never needs a store.\n * - `spill` — save the full text and show a preview; falls back to truncating\n *   when no store is mounted or the store fails, because losing the result\n *   entirely is worse than shortening it.\n */\nexport type ToolOutputOverflowPolicy = 'auto' | 'truncate' | 'spill'\n\n/** A saved copy of one oversized tool result. */\nexport interface SpillRecord {\n  /** Opaque handle the retrieval tool resolves; also shown to the model. */\n  readonly locator: string\n  /** Exact size of the saved text. */\n  readonly bytes: number\n  /**\n   * One sentence telling the model how to get the rest.\n   *\n   * Written by the backend, because only it knows what the locator IS — a file\n   * a shell can grep, or a handle only the built-in retrieval tool resolves.\n   */\n  readonly retrieval: string\n}\n\n/** A slice of a saved tool result. */\nexport interface SpillSlice {\n  readonly text: string\n  /** Total code points in the saved text, so a reader can page through it. */\n  readonly totalChars: number\n  /** Where this slice starts. */\n  readonly offset: number\n}\n\n/**\n * Where oversized tool output goes when the policy spills it.\n *\n * The port is deliberately tiny: core is a universal package and cannot open a\n * file, so a host that wants durable spill implements this over its own\n * storage. {@link createMemorySpillStore} covers the common case.\n */\nexport interface SpillStore {\n  /**\n   * Save one oversized result.\n   * @param text - The complete model-facing text.\n   * @param context - What produced it, for naming and diagnostics.\n   * @returns The locator the model can retrieve it by.\n   */\n  save(text: string, context: { readonly toolName: string; readonly callId: string }):\n  Promise<SpillRecord> | SpillRecord\n  /**\n   * Read part of a saved result.\n   * @param locator - A locator returned by {@link SpillStore.save}.\n   * @param range - Where to start and how much to read, in code points.\n   * @returns The slice, or undefined when the locator is unknown or expired.\n   */\n  read(locator: string, range: { readonly offset: number; readonly limit: number }):\n  Promise<SpillSlice | undefined> | SpillSlice | undefined\n  /**\n   * Find matching lines in a saved result.\n   * @param locator - A locator returned by {@link SpillStore.save}.\n   * @param pattern - A regular expression source, matched per line.\n   * @param limit - Maximum lines returned.\n   * @returns Matching `line-number: text` entries, or undefined when unknown.\n   */\n  search(locator: string, pattern: string, limit: number):\n  Promise<readonly string[] | undefined> | readonly string[] | undefined\n}\n\n/** Bounds for the built-in in-process store. */\nexport interface MemorySpillStoreLimits {\n  /** Saved results kept before the oldest is evicted. Defaults to 64. */\n  readonly maxEntries?: number\n  /** Total characters kept across all entries. Defaults to 32,000,000. */\n  readonly maxChars?: number\n}\n\n/**\n * A spill store that keeps text in this process.\n *\n * Universal, so it works in a browser and in a worker as well as on a server,\n * and enough for the case the policy exists for: the text leaves the model's\n * context immediately and is read back through the retrieval tool. It is not\n * durable — a restart loses it, and the locators in an old transcript stop\n * resolving. A host that needs durability implements {@link SpillStore} over\n * its own filesystem or object storage.\n * @param limits - Retention bounds.\n * @returns The store.\n */\nexport function createMemorySpillStore(limits: MemorySpillStoreLimits = {}): SpillStore {\n  const maxEntries = positive(limits.maxEntries ?? 64, 'maxEntries')\n  const maxChars = positive(limits.maxChars ?? 32_000_000, 'maxChars')\n  // Insertion-ordered, which makes the oldest entry the first key.\n  const entries = new Map<string, string>()\n  let held = 0\n  let counter = 0\n\n  // One text larger than the whole allowance evicts everything and is still\n  // kept: dropping the save would leave the model a locator that resolves to\n  // nothing, which is worse than briefly exceeding a soft retention bound. The\n  // next save evicts it.\n  const evictUntil = (room: number): void => {\n    while ((entries.size >= maxEntries || held + room > maxChars) && entries.size > 0) {\n      const oldest = entries.keys().next().value\n      if (oldest === undefined) break\n      held -= [...entries.get(oldest) ?? ''].length\n      entries.delete(oldest)\n    }\n  }\n\n  return {\n    save(text, context) {\n      const chars = [...text].length\n      evictUntil(chars)\n      counter += 1\n      const locator = `spill:${context.toolName}:${String(counter)}`\n      entries.set(locator, text)\n      held += chars\n      return {\n        locator,\n        bytes: new TextEncoder().encode(text).byteLength,\n        retrieval: `Call read_tool_output with locator \"${locator}\" to read the rest,`\n          + ' or with a pattern to search it.',\n      }\n    },\n    read(locator, range) {\n      const text = entries.get(locator)\n      if (text === undefined) return undefined\n      const points = [...text]\n      const offset = Math.min(Math.max(0, range.offset), points.length)\n      return {\n        text: points.slice(offset, offset + Math.max(1, range.limit)).join(''),\n        totalChars: points.length,\n        offset,\n      }\n    },\n    search(locator, pattern, limit) {\n      const text = entries.get(locator)\n      if (text === undefined) return undefined\n      // An invalid pattern is the model's mistake to correct, so it surfaces as\n      // a thrown tool error rather than as silently zero matches.\n      const expression = new RegExp(pattern)\n      const found: string[] = []\n      const lines = text.split('\\n')\n      for (let index = 0; index < lines.length && found.length < limit; index++) {\n        const line = lines[index] ?? ''\n        if (expression.test(line)) found.push(`${String(index + 1)}: ${line}`)\n      }\n      return Object.freeze(found)\n    },\n  }\n}\n\nfunction positive(value: number, name: string): number {\n  if (!Number.isSafeInteger(value) || value < 1) {\n    throw new RangeError(`spill store ${name} must be a positive safe integer`)\n  }\n  return value\n}\n\n/**\n * Deterministic token estimate for text.\n *\n * Four characters per token, the same heuristic compaction uses, and the same\n * order of magnitude as Codex's `approx_token_count`. It is an estimate: a real\n * tokenizer differs, and dense scripts differ more. It is used to decide when\n * to shorten output, never to bill anything.\n * @param text - The text to measure.\n * @returns The estimated token count.\n */\nexport function estimateTextTokens(text: string): number {\n  return Math.ceil(text.length / 4)\n}\n\n/**\n * Estimated tokens for the text a tool result puts in front of the model.\n *\n * Only text is counted. An image block is left alone — shortening it produces a\n * corrupt image rather than a smaller one.\n * @param content - The result's content blocks.\n * @returns The estimated token count of the text blocks.\n */\nexport function estimateTextBlockTokens(content: readonly ContentBlock[]): number {\n  return content.reduce(\n    (total, block) => block.type === 'text' ? total + estimateTextTokens(block.text) : total,\n    0,\n  )\n}\n\n/** The result of shortening one oversized text. */\nexport interface TruncatedText {\n  readonly text: string\n  /** Estimated tokens the original held. */\n  readonly originalTokens: number\n}\n\n/**\n * Cut the middle out of a text to fit a token budget.\n *\n * The middle goes because the two ends carry the most: a command's invocation\n * and its verdict, a file's header and its tail. Codex splits its budget the\n * same way. The marker states how much left, so the model can see that it is\n * reading a fragment rather than a short result.\n * @param text - The full text.\n * @param maxTokens - Estimated tokens the model may read.\n * @returns The shortened text and what the original held.\n */\nexport function truncateMiddleToTokens(text: string, maxTokens: number): TruncatedText {\n  const originalTokens = estimateTextTokens(text)\n  if (originalTokens <= maxTokens) return { text, originalTokens }\n  const budget = Math.max(1, maxTokens * 4)\n  // Two thirds to the head: a command's own output usually leads with what it\n  // did, and the tail is mostly the verdict.\n  const head = Math.max(1, Math.floor(budget * 0.66))\n  const tail = Math.max(0, budget - head)\n  const points = [...text]\n  const removed = originalTokens - maxTokens\n  const marker = `\\n\\n[... ${String(removed)} estimated tokens omitted from the middle ...]\\n\\n`\n  return {\n    text: points.slice(0, head).join('')\n      + marker\n      + (tail === 0 ? '' : points.slice(points.length - tail).join('')),\n    originalTokens,\n  }\n}\n\n/**\n * The head/tail preview shown in place of a spilled result.\n * @param text - The full text.\n * @param maxTokens - Estimated tokens the preview may hold.\n * @returns The preview.\n */\nexport function previewForSpill(text: string, maxTokens: number): string {\n  return truncateMiddleToTokens(text, maxTokens).text\n}\n\n/** The name the retrieval tool is registered under. */\nexport const SPILL_TOOL_NAME = 'read_tool_output'\n\ninterface ReadSpillArgs {\n  readonly locator: string\n  readonly offset?: number\n  readonly limit?: number\n  readonly pattern?: string\n}\n\n/**\n * The tool that reads back what a spill took out of the context.\n *\n * Spilling without this would be worse than truncating: the model would be\n * told its output exists somewhere and given no way to reach it. Registered\n * automatically wherever a store is mounted.\n * @param store - The mounted store.\n * @param defaultLimit - Characters one read returns when none is asked for.\n * @returns The tool definition.\n */\nexport function readSpillTool(store: SpillStore, defaultLimit = 8_000): ToolDefinition<ReadSpillArgs> {\n  return defineTool({\n    name: SPILL_TOOL_NAME,\n    description: 'Read or search the full output of an earlier tool call that was too large to'\n      + ' show in full. Pass the locator from that result. Use pattern to find matching lines,'\n      + ' or offset/limit to page through it.',\n    parameters: {\n      type: 'object',\n      properties: {\n        locator: { type: 'string', description: 'The locator printed with the shortened result.' },\n        offset: { type: 'number', description: 'Character offset to start reading from.' },\n        limit: { type: 'number', description: `Characters to read; defaults to ${String(defaultLimit)}.` },\n        pattern: {\n          type: 'string',\n          description: 'Regular expression matched per line; returns matching lines with numbers.',\n        },\n      },\n      required: ['locator'],\n      additionalProperties: false,\n    },\n    // Reading back is not exploration, and a model that cannot reach its own\n    // spilled output is worse off than one whose output was simply cut.\n    budgetExempt: true,\n    parse: parseReadSpill,\n    isConcurrencySafe: () => true,\n    execute: async (args) => {\n      if (args.pattern !== undefined) {\n        const matches = await store.search(args.locator, args.pattern, 200)\n        if (matches === undefined) return unknownLocator(args.locator)\n        return { locator: args.locator, matches: [...matches] }\n      }\n      const slice = await store.read(args.locator, {\n        offset: args.offset ?? 0,\n        limit: args.limit ?? defaultLimit,\n      })\n      if (slice === undefined) return unknownLocator(args.locator)\n      const end = slice.offset + [...slice.text].length\n      return {\n        locator: args.locator,\n        offset: slice.offset,\n        nextOffset: end < slice.totalChars ? end : null,\n        totalChars: slice.totalChars,\n        text: slice.text,\n      }\n    },\n  })\n}\n\nfunction unknownLocator(locator: string): JsonObject {\n  // A store that has evicted or lost the entry is a normal outcome, not a\n  // crash: the model needs to know to re-run the original call instead.\n  return {\n    locator,\n    error: 'no saved output for this locator; it may have expired. Re-run the original call'\n      + ' more narrowly if you still need it.',\n  }\n}\n\nfunction parseReadSpill(raw: unknown): ReadSpillArgs {\n  if (typeof raw !== 'object' || raw === null) throw new TypeError('arguments must be an object')\n  const value = raw as Record<string, unknown>\n  const locator = value['locator']\n  if (typeof locator !== 'string' || locator.length === 0) {\n    throw new TypeError('locator must be a non-empty string')\n  }\n  const offset = optionalCount(value['offset'], 'offset')\n  const limit = optionalCount(value['limit'], 'limit')\n  const pattern = value['pattern']\n  if (pattern !== undefined && typeof pattern !== 'string') {\n    throw new TypeError('pattern must be a string')\n  }\n  return {\n    locator,\n    ...offset === undefined ? {} : { offset },\n    ...limit === undefined ? {} : { limit },\n    ...pattern === undefined || pattern === '' ? {} : { pattern },\n  }\n}\n\nfunction optionalCount(value: unknown, name: string): number | undefined {\n  if (value === undefined) return undefined\n  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {\n    throw new TypeError(`${name} must be a non-negative number`)\n  }\n  return Math.floor(value)\n}\n"],"mappings":"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"}

package/dist/agent/tool/pipeline.d.ts

@@ -0,0 +1,98 @@
+import { ToolCallId } from "../../primitives/brand.js";
+import { JsonObject } from "../../primitives/json.js";
+import { ContentBlock } from "../../message/content.js";
+import { SdkLogger } from "../../logging/types.js";
+import { ToolCallPosition, ToolDefinition, ToolExecutionMode, ToolExecutionResult, ToolFailure } from "./definition.js";
+import { ApprovalBroker, ApprovalRequest } from "./approval.js";
+import { ToolCatalog } from "./registry.js";
+//#region src/agent/tool/pipeline.d.ts
+interface ToolCallRequest {
+  readonly callId: ToolCallId;
+  readonly toolName: string;
+  readonly rawArguments: string;
+}
+interface ToolCallContext extends ToolCallPosition {
+  readonly callId: ToolCallId;
+  readonly toolName: string;
+  readonly tool: ToolDefinition | undefined;
+  readonly rawArguments: string;
+  readonly args: unknown;
+  readonly signal: AbortSignal;
+  readonly logger?: SdkLogger;
+}
+type PreToolDecision = {
+  kind: 'allow';
+} | {
+  kind: 'deny';
+  reason: string;
+} | {
+  kind: 'ask';
+  reason?: string;
+};
+type PostToolDecision = {
+  kind: 'accept';
+} | {
+  kind: 'replace';
+  content: readonly ContentBlock[];
+  meta?: JsonObject;
+} | {
+  kind: 'block';
+  feedback: readonly ContentBlock[];
+  code?: string;
+};
+interface ToolInterceptor {
+  readonly name: string;
+  readonly before?: (call: ToolCallContext, next: () => Promise<PreToolDecision>) => Promise<PreToolDecision>;
+  readonly around?: (call: ToolCallContext, next: () => Promise<ToolExecutionResult>) => Promise<ToolExecutionResult>;
+  readonly after?: (call: ToolCallContext, result: ToolExecutionResult, next: () => Promise<PostToolDecision>) => Promise<PostToolDecision>;
+}
+interface DispatchToolCallOptions {
+  readonly catalog: ToolCatalog;
+  readonly call: ToolCallRequest;
+  readonly position: ToolCallPosition;
+  readonly signal: AbortSignal;
+  readonly logger?: SdkLogger;
+  readonly interceptors?: readonly ToolInterceptor[];
+  readonly approvals?: ApprovalBroker;
+  /** Maximum wait after a timed-out in-process tool ignores cancellation. */
+  readonly teardownTimeoutMs?: number;
+  /** Timeout used when the tool definition does not declare one. */
+  readonly defaultTimeoutMs?: number;
+  /** Called immediately before an approval broker is awaited. */
+  readonly onApprovalRequest?: (request: ApprovalRequest) => Promise<void> | void;
+  /** Called exactly once after an approval wait settles or fails. */
+  readonly onApprovalSettled?: (status: 'success' | 'error' | 'aborted', error?: unknown) => void;
+}
+interface PreparedToolCall {
+  readonly options: DispatchToolCallOptions;
+  readonly context: ToolCallContext;
+  readonly argumentFailure?: ToolFailure;
+  readonly mode: ToolExecutionMode;
+}
+interface AuthorizedToolCall extends PreparedToolCall {
+  readonly tool: ToolDefinition;
+}
+type AuthorizationOutcome = {
+  readonly kind: 'authorized';
+  readonly call: AuthorizedToolCall;
+} | {
+  readonly kind: 'final';
+  readonly result: ToolExecutionResult;
+};
+declare function toolFailure(message: string, code: string, extra?: {
+  meta?: JsonObject;
+  additionalContext?: readonly ContentBlock[];
+}): ToolFailure;
+/** Resolve, parse exactly once, validate and classify one call. */
+declare function prepareToolCall(options: DispatchToolCallOptions): PreparedToolCall;
+/** Ordered pre-policy and approval stage. */
+declare function authorizeToolCall(prepared: PreparedToolCall): Promise<AuthorizationOutcome>;
+/** Body/around stage; this is the only stage the scheduler overlaps. */
+declare function dispatchAuthorizedToolCall(call: AuthorizedToolCall): Promise<ToolExecutionResult>;
+/** Ordered post-policy stage. */
+declare function finalizeToolCall(call: AuthorizedToolCall, executed: ToolExecutionResult): Promise<ToolExecutionResult>;
+/** Compatibility facade for callers that do not need scheduling. */
+declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolExecutionResult>;
+//#endregion
+export { AuthorizationOutcome, AuthorizedToolCall, DispatchToolCallOptions, PostToolDecision, PreToolDecision, PreparedToolCall, ToolCallContext, ToolCallRequest, ToolInterceptor, authorizeToolCall, dispatchAuthorizedToolCall, dispatchToolCall, finalizeToolCall, prepareToolCall, toolFailure };
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/agent/tool/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","names":[],"sources":["../../../src/agent/tool/pipeline.ts"],"mappings":";;;;;;;;UAeiB;WACN,QAAQ;WACR;WACA;;UAEM,wBAAwB;WAC9B,QAAQ;WACR;WACA,MAAM;WACN;WACA;WACA,QAAQ;WACR,SAAS;;KAER;EACN;;EACA;EAAc;;EACd;EAAa;;KACP;EACN;;EACA;EAAiB,kBAAkB;EAAgB,OAAO;;EAC1D;EAAe,mBAAmB;EAAgB;;UACvC;WACN;WACA,UAAU,MAAM,iBAAiB,YAAY,QAAQ,qBAAqB,QAAQ;WAClF,UAAU,MAAM,iBAAiB,YAAY,QAAQ,yBAAyB,QAAQ;WACtF,SACP,MAAM,iBACN,QAAQ,qBACR,YAAY,QAAQ,sBACjB,QAAQ;;UAEE;WACN,SAAS;WACT,MAAM;WACN,UAAU;WACV,QAAQ;WACR,SAAS;WACT,wBAAwB;WACxB,YAAY;;WAEZ;;WAEA;;WAEA,qBAAqB,SAAS,oBAAoB;;WAElD,qBAAqB,yCAAyC;;UAExD;WACN,SAAS;WACT,SAAS;WACT,kBAAkB;WAClB,MAAM;;UAEA,2BAA2B;WAA4B,MAAM;;KAClE;WACG;WAA6B,MAAM;;WACnC;WAAwB,QAAQ;;iBAE/B,YACd,iBACA,cACA;EAAS,OAAO;EAAY,6BAA6B;IACxD;;iBAWa,gBAAgB,SAAS,0BAA0B;;iBA+B7C,kBAAkB,UAAU,mBAAmB,QAAQ;;iBA8DvD,2BAA2B,MAAM,qBAAqB,QAAQ;;iBA8E9D,iBAAiB,MAAM,oBAAoB,UAAU,sBAAsB,QAAQ;;iBAqCnF,iBAAiB,SAAS,0BAA0B,QAAQ"}

package/dist/agent/tool/pipeline.js

@@ -0,0 +1,4 @@
+import{isJsonValue as e}from"../../primitives/json.js";import{waitForSettlement as t}from"../../async/settlement.js";import{executionModeOf as n,renderJsonValue as r}from"./definition.js";import{TOOL_ERROR_CODES as i,ToolError as a,toolErrorDisposition as o}from"./errors.js";import{createApprovalRequest as s}from"./approval.js";function c(e,t,n={}){return{isError:!0,error:{message:e,code:t},content:[{type:`text`,text:`Error: ${e}`}],...n.meta===void 0?{}:{meta:n.meta},...n.additionalContext===void 0?{}:{additionalContext:n.additionalContext}}}function l(e){let{catalog:t,call:r,position:a,signal:o}=e,s=t.get(r.toolName),l,u;if(s===void 0)u=c(`no tool named "${r.toolName}" is available`,i.UNKNOWN_TOOL);else{let e=h(r.rawArguments);if(!e.ok)u=c(e.message,i.MALFORMED_ARGUMENTS);else if(s.parse===void 0)l=e.value;else try{l=s.parse(e.value)}catch(e){u=c(`invalid arguments: ${g(e)}`,i.INVALID_ARGUMENTS)}}return{options:e,context:{...a,callId:r.callId,toolName:r.toolName,tool:s,rawArguments:r.rawArguments,args:l,signal:o,...e.logger===void 0?{}:{logger:e.logger}},...u===void 0?{}:{argumentFailure:u},mode:u===void 0?n(s,l):`exclusive`}}async function u(e){if(e.argumentFailure!==void 0)return{kind:`final`,result:e.argumentFailure};let t=await v(e.options.interceptors??[],t=>t.before?.bind(t,e.context),()=>Promise.resolve({kind:`allow`}))();if(t.kind===`deny`)return{kind:`final`,result:c(t.reason,i.DENIED)};if(t.kind===`ask`){let n=e.options.approvals;if(n===void 0)return{kind:`final`,result:c(t.reason??`this tool requires approval, and no approver is configured`,i.DENIED)};let r=s({...e.options.position,callId:e.context.callId,toolName:e.context.toolName,args:e.context.args,turn:e.context.turn,step:e.context.step,...t.reason===void 0?{}:{reason:t.reason}}),o=new AbortController,l=AbortSignal.any([e.context.signal,o.signal]),u=n.request(r,l);try{await e.options.onApprovalRequest?.(r)}catch(t){throw o.abort(t),await u.catch(()=>void 0),e.options.onApprovalSettled?.(`error`,t),t}let d;try{d=await u,e.options.onApprovalSettled?.(d===`abort`||e.context.signal.aborted?`aborted`:`success`)}catch(t){throw e.options.onApprovalSettled?.(e.context.signal.aborted?`aborted`:`error`,t),t}if(d!==`allow`&&d!==`deny`&&d!==`abort`)throw a.fatal(`invalid approval decision`,`INVALID_APPROVAL_DECISION`);if(d===`abort`)throw a.fatal(`the turn was withdrawn while awaiting approval`,i.ABORTED);if(d===`deny`)return{kind:`final`,result:c(t.reason??`the call to "${e.context.toolName}" was not approved`,i.DENIED)}}let n=e.context.tool;return n===void 0?{kind:`final`,result:c(`no tool named "${e.context.toolName}" is available`,i.UNKNOWN_TOOL)}:{kind:`authorized`,call:{...e,tool:n}}}async function d(t){let{context:n,tool:s}=t;if(n.signal.aborted)return c(`the call was cancelled before it started`,i.ABORTED_BEFORE_DISPATCH);let l=async l=>{let u=[],d=!1,f={...t.options.position,turn:n.turn,step:n.step,callId:n.callId,toolName:n.toolName,signal:l,...n.logger===void 0?{}:{logger:n.logger},concludeTurn:()=>{d=!0},addContext:e=>{typeof e==`string`?u.push({type:`text`,text:e}):u.push(...e)}},p;try{let e=await s.execute(n.args,f);p=e===void 0?void 0:e}catch(e){if(o(e)===`fatal`)throw e;return l.aborted&&!(e instanceof a)?c(`the call was cancelled`,i.ABORTED):c(g(e),e instanceof a?e.code:i.FAILED,{additionalContext:u})}if(p!==void 0&&!e(p))return c(`tool "${s.name}" returned a value that is not lossless JSON; return plain objects, arrays, strings, finite numbers, booleans, or null`,i.INVALID_RESULT);let m,h;try{m=s.render===void 0?r(p):s.render(p,n.args),h=s.meta?.(p,n.args)}catch(e){return{isError:!1,value:p,content:r(p),...u.length===0?{}:{additionalContext:u},...d?{concludesTurn:!0}:{},meta:{renderError:g(e)}}}return{isError:!1,value:p,content:m,...h===void 0?{}:{meta:h},...u.length===0?{}:{additionalContext:u},...d?{concludesTurn:!0}:{}}},u=await v(t.options.interceptors??[],e=>e.around?.bind(e,n),()=>y(s.timeoutMs??t.options.defaultTimeoutMs,n.signal,l,t.options.teardownTimeoutMs??3e4))();if(!u.isError||u.meta!==void 0||s.meta===void 0)return u;try{let e=s.meta(void 0,n.args);return e===void 0?u:{...u,meta:e}}catch{return u}}async function f(e,t){let n=await v(e.options.interceptors??[],n=>n.after?.bind(n,e.context,t),()=>Promise.resolve({kind:`accept`}))();return n.kind===`accept`?t:n.kind===`replace`?t.isError?{isError:!0,error:{message:n.content.map(e=>e.type===`text`?e.text:``).filter(Boolean).join(`
+`)||`the tool result was replaced by policy`,code:i.DENIED},content:n.content,...n.meta===void 0?{}:{meta:n.meta}}:{isError:!1,value:void 0,content:n.content,...n.meta===void 0?{}:{meta:n.meta},...t.concludesTurn===!0?{concludesTurn:!0}:{}}:{isError:!0,error:{message:n.feedback.map(e=>e.type===`text`?e.text:``).filter(Boolean).join(`
+`)||`the result was blocked by policy`,code:n.code??i.DENIED},content:n.feedback}}async function p(e){if(e.signal.aborted)return c(`the call was cancelled before it started`,i.ABORTED_BEFORE_DISPATCH);let n=_(e.defaultTimeoutMs??6e5,`defaultTimeoutMs`),r=_(e.teardownTimeoutMs??3e4,`teardownTimeoutMs`),o=AbortSignal.timeout(n),s=AbortSignal.any([e.signal,o]),l=m({...e,signal:s,defaultTimeoutMs:n,teardownTimeoutMs:r});try{return await b(l,s)}catch(u){if(!s.aborted)throw u;if(!await t(l,r))throw a.fatal(`tool pipeline ignored cancellation for more than ${r}ms; the in-process operation may still be running`,i.TEARDOWN_TIMEOUT,{cause:u});return o.aborted&&!e.signal.aborted?c(`the tool pipeline exceeded its ${n}ms time limit`,i.TIMEOUT):await l}}async function m(e){let t=await u(l(e));return t.kind===`final`?t.result:await f(t.call,await d(t.call))}function h(e){let t=e.trim();if(t.length===0)return{ok:!0,value:{}};try{return{ok:!0,value:JSON.parse(t)}}catch(e){return{ok:!1,message:`arguments were not valid JSON: ${g(e)}`}}}function g(e){if(e instanceof Error&&e.message.length>0)return e.message;let t=String(e);return t.length>0?t:`the tool failed without a message`}function _(e,t){if(!Number.isSafeInteger(e)||e<1)throw RangeError(`${t} must be a positive safe integer`);return e}function v(e,t,n){let r=n;for(let n=e.length-1;n>=0;n--){let i=e[n];if(i===void 0)continue;let a=t(i);if(a===void 0)continue;let o=r;r=()=>a(o)}return r}async function y(e,n,r,o){if(e===void 0)return await r(n);let s=new AbortController,l=!1,u=setTimeout(()=>{l=!0,s.abort(Error(`tool timed out after ${e}ms`))},e),d=r(AbortSignal.any([n,s.signal]));try{let t=await b(d,s.signal);return l?c(`the tool exceeded its ${e}ms time limit`,i.TIMEOUT):t}catch(n){if(!l)throw n;if(!await t(d,o))throw a.fatal(`tool ignored timeout cancellation for more than ${o}ms; the in-process operation may still be running`,i.TEARDOWN_TIMEOUT,{cause:n});return c(`the tool exceeded its ${e}ms time limit`,i.TIMEOUT)}finally{clearTimeout(u)}}async function b(e,t){if(t.aborted)throw t.reason??Error(`tool timed out`);return await new Promise((n,r)=>{let i=()=>{t.removeEventListener(`abort`,i),r(t.reason??Error(`tool timed out`))};t.addEventListener(`abort`,i,{once:!0}),e.then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}export{u as authorizeToolCall,d as dispatchAuthorizedToolCall,p as dispatchToolCall,f as finalizeToolCall,l as prepareToolCall,c as toolFailure};
+//# sourceMappingURL=pipeline.js.map

package/dist/agent/tool/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","names":[],"sources":["../../../src/agent/tool/pipeline.ts"],"sourcesContent":["/** Staged tool dispatch: prepare/authorize/dispatch/finalize. */\nimport type { ContentBlock } from '../../message/index.ts'\nimport type { ToolCallId } from '../../primitives/index.ts'\nimport { isJsonValue, type JsonObject, type JsonValue } from '../../primitives/index.ts'\nimport { waitForSettlement } from '../../async/index.ts'\nimport { createApprovalRequest, type ApprovalBroker, type ApprovalRequest } from './approval.ts'\nimport {\n  executionModeOf, renderJsonValue, type ToolCallPosition, type ToolDefinition,\n  type ToolExecutionMode, type ToolExecutionResult, type ToolFailure, type ToolRunContext,\n  type ToolSuccess,\n} from './definition.ts'\nimport { TOOL_ERROR_CODES, ToolError, toolErrorDisposition } from './errors.ts'\nimport type { ToolCatalog } from './registry.ts'\nimport type { SdkLogger } from '../../logging/types.ts'\n\nexport interface ToolCallRequest {\n  readonly callId: ToolCallId\n  readonly toolName: string\n  readonly rawArguments: string\n}\nexport interface ToolCallContext extends ToolCallPosition {\n  readonly callId: ToolCallId\n  readonly toolName: string\n  readonly tool: ToolDefinition | undefined\n  readonly rawArguments: string\n  readonly args: unknown\n  readonly signal: AbortSignal\n  readonly logger?: SdkLogger\n}\nexport type PreToolDecision =\n  | { kind: 'allow' }\n  | { kind: 'deny'; reason: string }\n  | { kind: 'ask'; reason?: string }\nexport type PostToolDecision =\n  | { kind: 'accept' }\n  | { kind: 'replace'; content: readonly ContentBlock[]; meta?: JsonObject }\n  | { kind: 'block'; feedback: readonly ContentBlock[]; code?: string }\nexport interface ToolInterceptor {\n  readonly name: string\n  readonly before?: (call: ToolCallContext, next: () => Promise<PreToolDecision>) => Promise<PreToolDecision>\n  readonly around?: (call: ToolCallContext, next: () => Promise<ToolExecutionResult>) => Promise<ToolExecutionResult>\n  readonly after?: (\n    call: ToolCallContext,\n    result: ToolExecutionResult,\n    next: () => Promise<PostToolDecision>,\n  ) => Promise<PostToolDecision>\n}\nexport interface DispatchToolCallOptions {\n  readonly catalog: ToolCatalog\n  readonly call: ToolCallRequest\n  readonly position: ToolCallPosition\n  readonly signal: AbortSignal\n  readonly logger?: SdkLogger\n  readonly interceptors?: readonly ToolInterceptor[]\n  readonly approvals?: ApprovalBroker\n  /** Maximum wait after a timed-out in-process tool ignores cancellation. */\n  readonly teardownTimeoutMs?: number\n  /** Timeout used when the tool definition does not declare one. */\n  readonly defaultTimeoutMs?: number\n  /** Called immediately before an approval broker is awaited. */\n  readonly onApprovalRequest?: (request: ApprovalRequest) => Promise<void> | void\n  /** Called exactly once after an approval wait settles or fails. */\n  readonly onApprovalSettled?: (status: 'success' | 'error' | 'aborted', error?: unknown) => void\n}\nexport interface PreparedToolCall {\n  readonly options: DispatchToolCallOptions\n  readonly context: ToolCallContext\n  readonly argumentFailure?: ToolFailure\n  readonly mode: ToolExecutionMode\n}\nexport interface AuthorizedToolCall extends PreparedToolCall { readonly tool: ToolDefinition }\nexport type AuthorizationOutcome =\n  | { readonly kind: 'authorized'; readonly call: AuthorizedToolCall }\n  | { readonly kind: 'final'; readonly result: ToolExecutionResult }\n\nexport function toolFailure(\n  message: string,\n  code: string,\n  extra: { meta?: JsonObject; additionalContext?: readonly ContentBlock[] } = {},\n): ToolFailure {\n  return {\n    isError: true,\n    error: { message, code },\n    content: [{ type: 'text', text: `Error: ${message}` }],\n    ...extra.meta === undefined ? {} : { meta: extra.meta },\n    ...extra.additionalContext === undefined ? {} : { additionalContext: extra.additionalContext },\n  }\n}\n\n/** Resolve, parse exactly once, validate and classify one call. */\nexport function prepareToolCall(options: DispatchToolCallOptions): PreparedToolCall {\n  const { catalog, call, position, signal } = options\n  const tool = catalog.get(call.toolName)\n  let args: unknown\n  let argumentFailure: ToolFailure | undefined\n  if (tool === undefined) {\n    argumentFailure = toolFailure(`no tool named \"${call.toolName}\" is available`, TOOL_ERROR_CODES.UNKNOWN_TOOL)\n  } else {\n    const parsed = parseRawArguments(call.rawArguments)\n    if (!parsed.ok) argumentFailure = toolFailure(parsed.message, TOOL_ERROR_CODES.MALFORMED_ARGUMENTS)\n    else if (tool.parse === undefined) args = parsed.value\n    else {\n      try { args = tool.parse(parsed.value) }\n      catch (error: unknown) {\n        argumentFailure = toolFailure(`invalid arguments: ${messageOf(error)}`, TOOL_ERROR_CODES.INVALID_ARGUMENTS)\n      }\n    }\n  }\n  const context: ToolCallContext = {\n    ...position, callId: call.callId, toolName: call.toolName, tool,\n    rawArguments: call.rawArguments, args, signal,\n    ...(options.logger === undefined ? {} : { logger: options.logger }),\n  }\n  return {\n    options, context,\n    ...argumentFailure === undefined ? {} : { argumentFailure },\n    mode: argumentFailure === undefined ? executionModeOf(tool, args) : 'exclusive',\n  }\n}\n\n/** Ordered pre-policy and approval stage. */\nexport async function authorizeToolCall(prepared: PreparedToolCall): Promise<AuthorizationOutcome> {\n  if (prepared.argumentFailure !== undefined) return { kind: 'final', result: prepared.argumentFailure }\n  const interceptors = prepared.options.interceptors ?? []\n  const decision = await chain<PreToolDecision>(\n    interceptors,\n    interceptor => interceptor.before?.bind(interceptor, prepared.context),\n    () => Promise.resolve({ kind: 'allow' } as const),\n  )()\n  if (decision.kind === 'deny') return { kind: 'final', result: toolFailure(decision.reason, TOOL_ERROR_CODES.DENIED) }\n  if (decision.kind === 'ask') {\n    const broker = prepared.options.approvals\n    if (broker === undefined) {\n      return { kind: 'final', result: toolFailure(\n        decision.reason ?? 'this tool requires approval, and no approver is configured',\n        TOOL_ERROR_CODES.DENIED,\n      ) }\n    }\n    const request = createApprovalRequest({\n      ...prepared.options.position,\n      callId: prepared.context.callId, toolName: prepared.context.toolName,\n      args: prepared.context.args, turn: prepared.context.turn, step: prepared.context.step,\n      ...decision.reason === undefined ? {} : { reason: decision.reason },\n    })\n    // Start the broker first. The streamed approval event is backpressured, and\n    // a UI is allowed to answer synchronously while handling it. Publishing\n    // before request() installs its waiter loses that answer and parks forever.\n    const publication = new AbortController()\n    const signal = AbortSignal.any([prepared.context.signal, publication.signal])\n    const pending = broker.request(request, signal)\n    try {\n      await prepared.options.onApprovalRequest?.(request)\n    } catch (error: unknown) {\n      publication.abort(error)\n      await pending.catch(() => undefined)\n      prepared.options.onApprovalSettled?.('error', error)\n      throw error\n    }\n    let answer: Awaited<typeof pending>\n    try {\n      answer = await pending\n      prepared.options.onApprovalSettled?.(\n        answer === 'abort' || prepared.context.signal.aborted ? 'aborted' : 'success',\n      )\n    } catch (error) {\n      prepared.options.onApprovalSettled?.(prepared.context.signal.aborted ? 'aborted' : 'error', error)\n      throw error\n    }\n    if (answer !== 'allow' && answer !== 'deny' && answer !== 'abort') throw ToolError.fatal('invalid approval decision', 'INVALID_APPROVAL_DECISION')\n    if (answer === 'abort') throw ToolError.fatal('the turn was withdrawn while awaiting approval', TOOL_ERROR_CODES.ABORTED)\n    if (answer === 'deny') return { kind: 'final', result: toolFailure(\n      decision.reason ?? `the call to \"${prepared.context.toolName}\" was not approved`,\n      TOOL_ERROR_CODES.DENIED,\n    ) }\n  }\n  const tool = prepared.context.tool\n  if (tool === undefined) return { kind: 'final', result: toolFailure(\n    `no tool named \"${prepared.context.toolName}\" is available`, TOOL_ERROR_CODES.UNKNOWN_TOOL,\n  ) }\n  return { kind: 'authorized', call: { ...prepared, tool } }\n}\n\n/** Body/around stage; this is the only stage the scheduler overlaps. */\nexport async function dispatchAuthorizedToolCall(call: AuthorizedToolCall): Promise<ToolExecutionResult> {\n  const { context, tool } = call\n  if (context.signal.aborted) return toolFailure(\n    'the call was cancelled before it started', TOOL_ERROR_CODES.ABORTED_BEFORE_DISPATCH,\n  )\n  const body = async (signal: AbortSignal): Promise<ToolExecutionResult> => {\n    const extraContext: ContentBlock[] = []\n    let concludes = false\n    const runContext: ToolRunContext = {\n      ...call.options.position,\n      turn: context.turn, step: context.step, callId: context.callId,\n      toolName: context.toolName, signal,\n      ...(context.logger === undefined ? {} : { logger: context.logger }),\n      concludeTurn: () => { concludes = true },\n      addContext: content => {\n        if (typeof content === 'string') extraContext.push({ type: 'text', text: content })\n        else extraContext.push(...content)\n      },\n    }\n    let value: JsonValue | undefined\n    try {\n      const returned = await tool.execute(context.args as never, runContext)\n      value = returned === undefined ? undefined : returned\n    } catch (error: unknown) {\n      if (toolErrorDisposition(error) === 'fatal') throw error\n      if (signal.aborted && !(error instanceof ToolError)) return toolFailure('the call was cancelled', TOOL_ERROR_CODES.ABORTED)\n      return toolFailure(messageOf(error), error instanceof ToolError ? error.code : TOOL_ERROR_CODES.FAILED, {\n        additionalContext: extraContext,\n      })\n    }\n    if (value !== undefined && !isJsonValue(value)) return toolFailure(\n      `tool \"${tool.name}\" returned a value that is not lossless JSON; return plain objects, arrays, strings, finite numbers, booleans, or null`,\n      TOOL_ERROR_CODES.INVALID_RESULT,\n    )\n    let content: readonly ContentBlock[]\n    let meta: JsonObject | undefined\n    try {\n      content = tool.render === undefined ? renderJsonValue(value) : tool.render(value, context.args as never)\n      meta = tool.meta?.(value, context.args as never)\n    } catch (error: unknown) {\n      return {\n        isError: false, value, content: renderJsonValue(value),\n        ...extraContext.length === 0 ? {} : { additionalContext: extraContext },\n        ...concludes ? { concludesTurn: true as const } : {},\n        meta: { renderError: messageOf(error) },\n      } satisfies ToolSuccess\n    }\n    return {\n      isError: false, value, content,\n      ...meta === undefined ? {} : { meta },\n      ...extraContext.length === 0 ? {} : { additionalContext: extraContext },\n      ...concludes ? { concludesTurn: true as const } : {},\n    } satisfies ToolSuccess\n  }\n  const executed = await chain<ToolExecutionResult>(\n    call.options.interceptors ?? [],\n    interceptor => interceptor.around?.bind(interceptor, context),\n    () => withTimeout(\n      tool.timeoutMs ?? call.options.defaultTimeoutMs,\n      context.signal,\n      body,\n      call.options.teardownTimeoutMs ?? 30_000,\n    ),\n  )()\n  if (!executed.isError || executed.meta !== undefined || tool.meta === undefined) return executed\n  // Provenance and UI metadata are just as important for a failed call as for a\n  // successful one. In particular, remote bridges use this to identify which\n  // integration produced the error. Metadata is a side channel, so a buggy\n  // metadata callback must never replace the original tool failure.\n  try {\n    const meta = tool.meta(undefined, context.args as never)\n    return meta === undefined ? executed : { ...executed, meta }\n  } catch {\n    return executed\n  }\n}\n\n/** Ordered post-policy stage. */\nexport async function finalizeToolCall(call: AuthorizedToolCall, executed: ToolExecutionResult): Promise<ToolExecutionResult> {\n  const verdict = await chain<PostToolDecision>(\n    call.options.interceptors ?? [],\n    interceptor => interceptor.after?.bind(interceptor, call.context, executed),\n    () => Promise.resolve({ kind: 'accept' } as const),\n  )()\n  if (verdict.kind === 'accept') return executed\n  if (verdict.kind === 'replace') {\n    // Replacement is a sanitization boundary, not a model-content-only edit.\n    // Rebuild the envelope so raw value, metadata, errors, and additional\n    // context cannot escape through public events, history, or telemetry.\n    if (executed.isError) {\n      const text = verdict.content.map(block => block.type === 'text' ? block.text : '').filter(Boolean).join('\\n')\n      return {\n        isError: true,\n        error: { message: text || 'the tool result was replaced by policy', code: TOOL_ERROR_CODES.DENIED },\n        content: verdict.content,\n        ...verdict.meta === undefined ? {} : { meta: verdict.meta },\n      }\n    }\n    return {\n      isError: false,\n      value: undefined,\n      content: verdict.content,\n      ...verdict.meta === undefined ? {} : { meta: verdict.meta },\n      ...executed.concludesTurn === true ? { concludesTurn: true as const } : {},\n    }\n  }\n  const text = verdict.feedback.map(block => block.type === 'text' ? block.text : '').filter(Boolean).join('\\n')\n  return {\n    isError: true,\n    error: { message: text || 'the result was blocked by policy', code: verdict.code ?? TOOL_ERROR_CODES.DENIED },\n    content: verdict.feedback,\n  }\n}\n\n/** Compatibility facade for callers that do not need scheduling. */\nexport async function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolExecutionResult> {\n  if (options.signal.aborted) {\n    return toolFailure('the call was cancelled before it started', TOOL_ERROR_CODES.ABORTED_BEFORE_DISPATCH)\n  }\n  const timeoutMs = positiveSafeInteger(options.defaultTimeoutMs ?? 10 * 60_000, 'defaultTimeoutMs')\n  const teardownTimeoutMs = positiveSafeInteger(options.teardownTimeoutMs ?? 30_000, 'teardownTimeoutMs')\n  const deadline = AbortSignal.timeout(timeoutMs)\n  const signal = AbortSignal.any([options.signal, deadline])\n  const pending = dispatchToolCallInternal({\n    ...options, signal, defaultTimeoutMs: timeoutMs, teardownTimeoutMs,\n  })\n  try {\n    return await raceWithSignal(pending, signal)\n  } catch (error: unknown) {\n    if (!signal.aborted) throw error\n    const settled = await waitForSettlement(pending, teardownTimeoutMs)\n    if (!settled) {\n      throw ToolError.fatal(\n        `tool pipeline ignored cancellation for more than ${teardownTimeoutMs}ms; the in-process operation may still be running`,\n        TOOL_ERROR_CODES.TEARDOWN_TIMEOUT,\n        { cause: error },\n      )\n    }\n    if (deadline.aborted && !options.signal.aborted) {\n      return toolFailure(`the tool pipeline exceeded its ${timeoutMs}ms time limit`, TOOL_ERROR_CODES.TIMEOUT)\n    }\n    return await pending\n  }\n}\n\nasync function dispatchToolCallInternal(options: DispatchToolCallOptions): Promise<ToolExecutionResult> {\n  const authorization = await authorizeToolCall(prepareToolCall(options))\n  if (authorization.kind === 'final') return authorization.result\n  return await finalizeToolCall(authorization.call, await dispatchAuthorizedToolCall(authorization.call))\n}\n\nfunction parseRawArguments(raw: string): { ok: true; value: unknown } | { ok: false; message: string } {\n  const trimmed = raw.trim()\n  if (trimmed.length === 0) return { ok: true, value: {} }\n  try { return { ok: true, value: JSON.parse(trimmed) as unknown } }\n  catch (error: unknown) { return { ok: false, message: `arguments were not valid JSON: ${messageOf(error)}` } }\n}\nfunction messageOf(value: unknown): string {\n  if (value instanceof Error && value.message.length > 0) return value.message\n  const rendered = String(value)\n  return rendered.length > 0 ? rendered : 'the tool failed without a message'\n}\nfunction positiveSafeInteger(value: number, field: string): number {\n  if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${field} must be a positive safe integer`)\n  return value\n}\nfunction chain<T>(\n  interceptors: readonly ToolInterceptor[],\n  pick: (interceptor: ToolInterceptor) => ((next: () => Promise<T>) => Promise<T>) | undefined,\n  terminal: () => Promise<T>,\n): () => Promise<T> {\n  let next = terminal\n  for (let index = interceptors.length - 1; index >= 0; index--) {\n    const interceptor = interceptors[index]\n    if (interceptor === undefined) continue\n    const hook = pick(interceptor)\n    if (hook === undefined) continue\n    const inner = next\n    next = () => hook(inner)\n  }\n  return next\n}\nasync function withTimeout(\n  timeoutMs: number | undefined,\n  outer: AbortSignal,\n  run: (signal: AbortSignal) => Promise<ToolExecutionResult>,\n  teardownTimeoutMs: number,\n): Promise<ToolExecutionResult> {\n  if (timeoutMs === undefined) return await run(outer)\n  const expiry = new AbortController()\n  let expired = false\n  const timer = setTimeout(() => {\n    expired = true\n    expiry.abort(new Error(`tool timed out after ${timeoutMs}ms`))\n  }, timeoutMs)\n  const pending = run(AbortSignal.any([outer, expiry.signal]))\n  try {\n    const result = await raceWithSignal(pending, expiry.signal)\n    return expired\n      ? toolFailure(`the tool exceeded its ${timeoutMs}ms time limit`, TOOL_ERROR_CODES.TIMEOUT)\n      : result\n  } catch (error: unknown) {\n    if (!expired) throw error\n    const settled = await waitForSettlement(pending, teardownTimeoutMs)\n    if (!settled) {\n      throw ToolError.fatal(\n        `tool ignored timeout cancellation for more than ${teardownTimeoutMs}ms; the in-process operation may still be running`,\n        TOOL_ERROR_CODES.TEARDOWN_TIMEOUT,\n        { cause: error },\n      )\n    }\n    return toolFailure(`the tool exceeded its ${timeoutMs}ms time limit`, TOOL_ERROR_CODES.TIMEOUT)\n  } finally { clearTimeout(timer) }\n}\n\nasync function raceWithSignal<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {\n  if (signal.aborted) throw signal.reason ?? new Error('tool timed out')\n  return await new Promise<T>((resolve, reject) => {\n    const abort = () => {\n      signal.removeEventListener('abort', abort)\n      reject(signal.reason ?? new Error('tool timed out'))\n    }\n    signal.addEventListener('abort', abort, { once: true })\n    void pending.then(\n      value => { signal.removeEventListener('abort', abort); resolve(value) },\n      error => { signal.removeEventListener('abort', abort); reject(error) },\n    )\n  })\n}\n"],"mappings":"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"}