@openrouter/agent 0.7.2 → 0.9.0

package/esm/lib/tool-context.d.ts

@@ -30,6 +30,38 @@ export declare class ToolContextStore {
     mergeToolContext(toolName: string, partial: Record<string, unknown>): void;
     private notifyListeners;
 }
+/**
+ * Per-execution extras threaded into the ToolExecuteContext: the composed
+ * abort signal for this call, the call id, the conversation id, and (for
+ * unified `run` tools) the async-task affordances.
+ */
+export interface ToolExecutionExtras {
+    signal?: AbortSignal;
+    callId?: string;
+    conversationId?: string;
+    /** The parent run's client — agent tools use it to start child runs. */
+    client?: unknown;
+    /**
+     * Unified-run affordances, wired by the engine per call:
+     * - `defer` — create a DeferredHandle (deferred lifecycle only)
+     * - `log` — append a task log entry (same pipeline as a yield)
+     * - `onMessage` — register the steering-inbox handler
+     * - `taskId` — the task id once assigned
+     */
+    runExtras?: {
+        defer?: (taskId: string, options?: Record<string, unknown>) => unknown;
+        log?: (entry: unknown) => void;
+        onMessage?: (handler: (message: unknown) => void) => void;
+        taskId?: string;
+        /**
+         * Transcript-source slot (agent tools attach their live transcript
+         * here). Deliberately NOT named `task`: `TurnContext.task` is typed
+         * `ToolTaskHandle` (check calls only) and must not be shadowed by a
+         * transcript-only object in run bodies.
+         */
+        taskTranscript?: unknown;
+    };
+}
 /**
  * Build a flat ToolExecuteContext for a specific tool.
  * Returns a merged object with TurnContext fields, a `local` getter
@@ -43,9 +75,21 @@ export declare class ToolContextStore {
  * @param toolName - The tool's name
  * @param schema - The tool's contextSchema (for validation)
  * @param sharedSchema - The shared contextSchema (for validation)
+ * @param extras - Per-execution extras (abort signal, call id, conversation id)
  * @returns A flat ToolExecuteContext
  */
-export declare function buildToolExecuteContext<TName extends string, TContext extends Record<string, unknown>, TShared extends Record<string, unknown> = Record<string, unknown>>(turnContext: TurnContext, store: ToolContextStore | undefined, toolName: TName, schema: $ZodObject<$ZodShape> | undefined, sharedSchema?: $ZodObject<$ZodShape> | undefined): ToolExecuteContext<TName, TContext, TShared>;
+export declare function buildToolExecuteContext<TName extends string, TContext extends Record<string, unknown>, TShared extends Record<string, unknown> = Record<string, unknown>>(turnContext: TurnContext, store: ToolContextStore | undefined, toolName: TName, schema: $ZodObject<$ZodShape> | undefined, sharedSchema?: $ZodObject<$ZodShape> | undefined, extras?: ToolExecutionExtras): ToolExecuteContext<TName, TContext, TShared>;
+/**
+ * Build a ToolRunContext for a unified `run` tool: the base execute context
+ * plus the async-task affordances (`defer`, `log`, `onMessage`, `taskId`,
+ * `client`). Attached onto the built object (not via spread) because
+ * `local`/`shared` are live getters a spread would flatten.
+ */
+export declare function buildToolRunContext<TName extends string, TContext extends Record<string, unknown>, TShared extends Record<string, unknown> = Record<string, unknown>>(turnContext: TurnContext, store: ToolContextStore | undefined, toolName: TName, schema: $ZodObject<$ZodShape> | undefined, sharedSchema?: $ZodObject<$ZodShape> | undefined, extras?: ToolExecutionExtras): ToolExecuteContext<TName, TContext, TShared> & {
+    defer: (taskId: string, options?: Record<string, unknown>) => unknown;
+    log: (entry: unknown) => void;
+    onMessage: (handler: (message: unknown) => void) => void;
+};
 /**
  * Resolve a context input (static value, sync function, or async function) to a plain object.
  *

package/esm/lib/tool-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../src/lib/tool-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKvE;;;GAGG;AACH,KAAK,qBAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IACtE,CAAC,GACD,CAAC,CAAC,IAAI,EAAE,WAAW,KAAK,CAAC,CAAC,GAC1B,CAAC,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAMxC;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,SAAS,CAAyC;gBAE9C,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IASvE,qEAAqE;IACrE,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOtD,8DAA8D;IAC9D,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAUtD,wDAAwD;IACxD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUzD,2DAA2D;IAC3D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOvE,+EAA+E;IAC/E,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS1E,OAAO,CAAC,eAAe;CAWxB;AAiCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,SAAS,MAAM,EACpB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjE,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,QAAQ,EAAE,KAAK,EACf,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,SAAS,EACzC,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,SAAS,GAC/C,kBAAkB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CA8C9C;AAMD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACpF,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EACzC,WAAW,EAAE,WAAW,GACvB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,SAAS,GACxC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB"}
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../src/lib/tool-context.ts"],"names":[],"mappings":"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"}

package/esm/lib/tool-context.js

@@ -95,6 +95,21 @@ function validatePartialAgainstSchema(partial, schema) {
     }
     return filteredPartial;
 }
+/*
+ * A never-aborting signal for contexts built without cancellation sources —
+ * keeps `ctx.signal` always present so tool bodies can pass it to fetch/etc.
+ * unconditionally.
+ *
+ * Deliberately a FACTORY, not one shared module-level signal. A tool body may
+ * `signal.addEventListener('abort', …)` and, since this signal never fires,
+ * nothing ever removes that listener. Sharing one object across every such call
+ * accumulated listeners on it for the lifetime of the process — unbounded in a
+ * long-lived server, and eventually a MaxListenersExceededWarning. A fresh
+ * signal per context is garbage-collected with the context that owns it.
+ */
+function neverAbortSignal() {
+    return new AbortController().signal;
+}
 /**
  * Build a flat ToolExecuteContext for a specific tool.
  * Returns a merged object with TurnContext fields, a `local` getter
@@ -108,9 +123,10 @@ function validatePartialAgainstSchema(partial, schema) {
  * @param toolName - The tool's name
  * @param schema - The tool's contextSchema (for validation)
  * @param sharedSchema - The shared contextSchema (for validation)
+ * @param extras - Per-execution extras (abort signal, call id, conversation id)
  * @returns A flat ToolExecuteContext
  */
-export function buildToolExecuteContext(turnContext, store, toolName, schema, sharedSchema) {
+export function buildToolExecuteContext(turnContext, store, toolName, schema, sharedSchema, extras) {
     // Validate initial context eagerly (throws on bad data)
     if (store && schema) {
         extractToolContext(store, toolName, schema);
@@ -120,6 +136,13 @@ export function buildToolExecuteContext(turnContext, store, toolName, schema, sh
     }
     const ctx = {
         ...turnContext,
+        signal: extras?.signal ?? neverAbortSignal(),
+        ...(extras?.callId !== undefined && {
+            callId: extras.callId,
+        }),
+        ...(extras?.conversationId !== undefined && {
+            conversationId: extras.conversationId,
+        }),
         get local() {
             const data = store ? store.getToolContext(toolName) : {};
             return Object.freeze(data);
@@ -145,6 +168,42 @@ export function buildToolExecuteContext(turnContext, store, toolName, schema, sh
     };
     return ctx;
 }
+/**
+ * Build a ToolRunContext for a unified `run` tool: the base execute context
+ * plus the async-task affordances (`defer`, `log`, `onMessage`, `taskId`,
+ * `client`). Attached onto the built object (not via spread) because
+ * `local`/`shared` are live getters a spread would flatten.
+ */
+export function buildToolRunContext(turnContext, store, toolName, schema, sharedSchema, extras) {
+    const base = buildToolExecuteContext(turnContext, store, toolName, schema, sharedSchema, extras);
+    const runExtras = extras?.runExtras;
+    const ctx = Object.assign(base, {
+        defer: runExtras?.defer ??
+            (() => {
+                throw new Error(`Tool "${toolName}": ctx.defer() is only available on lifecycle: 'deferred' tools`);
+            }),
+        log: runExtras?.log ?? (() => undefined),
+        onMessage: runExtras?.onMessage ?? (() => undefined),
+        ...(runExtras?.taskTranscript !== undefined && {
+            taskTranscript: runExtras.taskTranscript,
+        }),
+        ...(extras?.client !== undefined && {
+            client: extras.client,
+        }),
+    });
+    // Live delegation: the engine's runExtras exposes taskId as a getter
+    // backed by the run binding, because the ToolTask (and its id) is only
+    // created after the call escapes the round — a static copy taken here
+    // would always be undefined.
+    if (runExtras && 'taskId' in runExtras) {
+        Object.defineProperty(ctx, 'taskId', {
+            get: () => runExtras.taskId,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return ctx;
+}
 //#endregion
 //#region resolveContext
 /**

package/esm/lib/tool-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/lib/tool-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/lib/tool-context.ts"],"names":[],"mappings":"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"}

package/esm/lib/tool-executor.d.ts

@@ -1,7 +1,7 @@
 import type * as models from '@openrouter/sdk/models';
 import * as z4 from 'zod/v4';
 import type { $ZodObject, $ZodShape, $ZodType } from 'zod/v4/core';
-import type { ToolContextStore } from './tool-context.js';
+import type { ToolContextStore, ToolExecutionExtras } from './tool-context.js';
 import type { ClientTool, ParsedToolCall, Tool, ToolExecutionResult, TurnContext } from './tool-types.js';
 export declare const ZodError: z4.z.core.$constructor<z4.ZodError<unknown>, z4.z.core.$ZodIssue[]>;
 /**
@@ -25,8 +25,12 @@ export declare function convertZodToJsonSchema(zodSchema: $ZodType): Record<stri
 /**
  * Convert tools to OpenRouter API format. Server tools pass their SDK-shaped
  * config through untouched; client tools are packaged into the function-call
- * shape. Return type widens to the SDK's full request-tool union so any new
- * server-tool variant added upstream flows through automatically.
+ * shape — their wire definitions are NEVER augmented per tool (interacting
+ * with long-running tasks goes through the single universal `task` tool,
+ * appended by callModel when warranted, so the per-tool context cost stays
+ * constant no matter how many async tools are registered). Return type
+ * widens to the SDK's full request-tool union so any new server-tool
+ * variant added upstream flows through automatically.
  */
 export declare function convertToolsToAPIFormat(tools: readonly Tool[]): Array<models.ResponsesRequestToolUnion>;
 /**
@@ -48,14 +52,14 @@ export declare function parseToolCallArguments(argumentsString: string): unknown
 /**
  * Execute a regular (non-generator) tool
  */
-export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): Promise<ToolExecutionResult<Tool>>;
+export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>, extras?: ToolExecutionExtras): Promise<ToolExecutionResult<Tool>>;
 /**
  * Execute a generator tool and collect preliminary and final results
  * - Intermediate yields are validated against eventSchema (preliminary events)
  * - Last yield is validated against outputSchema (final result sent to model)
  * - Generator must emit at least one value
  */
-export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): Promise<ToolExecutionResult<Tool>>;
+export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>, extras?: ToolExecutionExtras): Promise<ToolExecutionResult<Tool>>;
 /**
  * Execute a HITL tool's `onToolCalled` hook.
  *
@@ -64,16 +68,55 @@ export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCal
  * - `null` if the hook returned `null` (pause — treat as manual tool)
  * - `ToolExecutionResult` with `error` set if the hook threw
  */
-export declare function executeHITLTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): Promise<ToolExecutionResult<Tool> | null>;
+export declare function executeHITLTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>, extras?: ToolExecutionExtras): Promise<ToolExecutionResult<Tool> | null>;
+/**
+ * Tagged result for tools whose work escapes the synchronous round.
+ *
+ * - `'background'`: `run()` starts the tool's `execute` (input already
+ *   validated, context built) and resolves with the OUTPUT-VALIDATED final
+ *   value. The engine decides when to invoke it (under the background pool)
+ *   and whether its settlement lands in-round (grace window) or later.
+ * - `'defer'`: the tool's `start` returned a durable task handle; the run
+ *   should pause until the task is resolved externally.
+ */
+export type AsyncToolInvocation = {
+    asyncMode: 'background';
+    run: () => Promise<unknown>;
+    ack?: string | Record<string, unknown> | undefined;
+    graceMs: number;
+} | {
+    asyncMode: 'defer';
+    taskId: string;
+    ack?: string | Record<string, unknown> | undefined;
+    pollAfterMs?: number | undefined;
+    expiresAt?: number | undefined;
+};
+/** Type guard for {@link AsyncToolInvocation} in executeTool results. */
+export declare function isAsyncToolInvocation(value: unknown): value is AsyncToolInvocation;
+/**
+ * Prepare a unified tool invocation. Validates input eagerly; builds the
+ * ToolRunContext (defer/log/onMessage/client wired by the engine through
+ * `extras.runExtras`); then per lifecycle:
+ *
+ * - `'sync'`: runs to completion inline — a plain `ToolExecutionResult`,
+ *   zero async overhead, behaviorally identical to `execute`.
+ * - `'background'` (and agent tools): returns a `'background'`
+ *   {@link AsyncToolInvocation} thunk for the engine's grace-window race.
+ * - `'deferred'`: awaits the run — a plain value is the typed fast path; a
+ *   `DeferredHandle` becomes a `'defer'` invocation.
+ */
+export declare function prepareUnifiedInvocation(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>, extras?: ToolExecutionExtras): Promise<ToolExecutionResult<Tool> | AsyncToolInvocation>;
 /**
  * Execute a tool call.
- * Automatically detects if it's a regular, generator, or HITL tool.
+ * Automatically detects if it's a regular, generator, HITL, or unified
+ * `run` tool.
  *
  * Returns `null` only for HITL tools whose `onToolCalled` returned `null`
- * (signaling a manual-style pause). All other tools always return a
+ * (signaling a manual-style pause). Unified background/deferred tools may
+ * return an {@link AsyncToolInvocation}. All other tools always return a
  * `ToolExecutionResult` (with `error` set on failure).
  */
-export declare function executeTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): Promise<ToolExecutionResult<Tool> | null>;
+export declare function executeTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>, extras?: ToolExecutionExtras): Promise<ToolExecutionResult<Tool> | AsyncToolInvocation | null>;
 /**
  * Find a client tool by name in the tools array. Server tools have no
  * client-side name to match against and are skipped.

package/esm/lib/tool-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../src/lib/tool-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,KAAK,EAEV,UAAU,EAEV,cAAc,EACd,IAAI,EAEJ,mBAAmB,EACnB,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAUzB,eAAO,MAAM,QAAQ,qEAAc,CAAC;AASpC;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;AAwC1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWnF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,IAAI,EAAE,GACrB,KAAK,CAAC,MAAM,CAAC,yBAAyB,CAAC,CAczC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAE1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,CAAC,CAE7E;AAWD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAcvE;AAqBD;;GAEG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAC9B,OAAO,EAAE,WAAW,EACpB,YAAY,CAAC,EAAE,gBAAgB,EAC/B,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAsCpC;AAED;;;;;GAKG;AAEH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAC9B,OAAO,EAAE,WAAW,EACpB,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,EACnE,YAAY,CAAC,EAAE,gBAAgB,EAC/B,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAoEpC;AAED;;;;;;;GAOG;AAEH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAC9B,OAAO,EAAE,WAAW,EACpB,YAAY,CAAC,EAAE,gBAAgB,EAC/B,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAiC3C;AAED;;;;;;;GAOG;AAEH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,EAC9B,OAAO,EAAE,WAAW,EACpB,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,EACnE,YAAY,CAAC,EAAE,gBAAgB,EAC/B,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAqB3C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAIlF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,MAAM,CASlF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,MAAM,CAW7F;AAsKD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,CAAC,WAAW,EACzB,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAClC,OAAO,EAAE,WAAW,EACpB,YAAY,CAAC,EAAE,gBAAgB,EAC/B,YAAY,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAyC7B"}
+{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../src/lib/tool-executor.ts"],"names":[],"mappings":"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"}