@openrouter/agent 0.7.2 → 0.9.0

package/esm/lib/async-params.d.ts

@@ -1,5 +1,8 @@
 import type * as models from '@openrouter/sdk/models';
 import type { OpenResponsesResult } from '@openrouter/sdk/models';
+import type { DoomLoopOption } from './doom-loop.js';
+import type { HooksManager } from './hooks-manager.js';
+import type { InlineHookConfig } from './hooks-types.js';
 import type { Item } from './item-types.js';
 import type { ContextInput } from './tool-context.js';
 import type { ParsedToolCall, StateAccessor, StopWhen, Tool, ToolContextMapWithShared, TurnContext } from './tool-types.js';
@@ -37,13 +40,22 @@ type BaseCallModelInput<TTools extends readonly Tool[] = readonly Tool[], TShare
     /**
      * When the loop exits because `stopWhen` was met and the last response
      * still contained tool calls, execute those pending tool calls (so they
-     * have matching outputs) and then make one more model request with no
-     * tools so the model produces a final text response.
+     * have matching outputs) and then make one more model request with
+     * `toolChoice: 'none'` so the model produces a final text response.
+     * Tools stay in the request — only calling is forbidden — so the
+     * prompt-cache prefix is preserved.
      *
-     * - `true` (or `''`) — re-prompt with the accumulated conversation and no
-     *   tools.
-     * - non-empty string — additionally append that string as a final user
-     *   message (e.g. `"Please summarize what you've learned"`).
+     * **Default: on.** Omitting the option behaves like `true`.
+     *
+     * - `true` / omitted — re-prompt with the accumulated conversation and a
+     *   default final-answer directive appended as a user message
+     *   (`DEFAULT_FINAL_RESPONSE_DIRECTIVE`). Without the directive, models
+     *   that emit tool-call syntax as text may leak an unparsed tool call
+     *   into the final content.
+     * - non-empty string — append that string as the final user message
+     *   instead of the default (e.g. `"Please summarize what you've learned"`).
+     * - `''` — no final user message; tool calls are still forbidden.
+     * - `false` — no final turn; the run ends on the halted tool-call turn.
      *
      * The full accumulated input array and the original `instructions` are
      * sent. Manual (non-executable) tool calls in the halted turn are paired
@@ -52,6 +64,95 @@ type BaseCallModelInput<TTools extends readonly Tool[] = readonly Tool[], TShare
      * (HITL pause, approval pause, interruption, or natural completion).
      */
     allowFinalResponse?: boolean | string;
+    /**
+     * When true, throw if the final response has an empty `output` array even
+     * after completed tool rounds (legacy behavior). Default false: empty
+     * finals after tool work are retried once, then accepted with empty text.
+     */
+    strictFinalResponse?: boolean;
+    /** Hook system for lifecycle events. Accepts inline config or a HooksManager instance. */
+    hooks?: InlineHookConfig | HooksManager;
+    /**
+     * Doom-loop detection: catch runs that repeat the same tool call with
+     * identical arguments (including repeated empty or unparseable calls) or
+     * emit the same text over and over, and respond with a graduated ladder
+     * (observe → steer → block → stop; defaults observe@2, block@3, stop@6
+     * consecutive repetitions). `true` enables recommended defaults; an
+     * object tunes thresholds and text detection. Off by default.
+     *
+     * Tools declare precise call identity via `loopKey`: a computed function
+     * (return the search query, `({ command, cwd }) => ({ command, cwd })`,
+     * ...), a field-name array (`['command', 'cwd']` — serializable, used by
+     * MCP tool caches), or `false` to exempt a tool (legitimate polling);
+     * without one the full arguments object is the identity. Detection is
+     * deterministic: the same transcript always produces the same verdicts.
+     */
+    doomLoop?: DoomLoopOption;
+    /**
+     * Cancel the whole run. Aborting stops the tool-execution loop at the
+     * next turn boundary AND aborts the in-flight API request/stream, so a
+     * stalled provider fails fast instead of hanging until an outer test or
+     * caller timeout kills the process. The run's promises reject with the
+     * signal's abort reason.
+     *
+     * Composes with per-request `RequestOptions.timeoutMs` (the third
+     * `callModel` argument): when both are set, each request is bounded by
+     * whichever fires first. (Passing a raw `signal` through `RequestOptions`
+     * instead would silently disable the SDK's `timeoutMs` wiring.)
+     *
+     * Aborting also fires every in-flight tool's `ctx.signal` and aborts
+     * background tasks, so cooperative tool bodies stop working.
+     */
+    signal?: AbortSignal;
+    /**
+     * Default per-tool execution deadline in milliseconds; a tool-level
+     * `timeoutMs` overrides it. When the deadline elapses the round stops
+     * waiting — the model receives `{ error, code: 'tool_timeout' }`
+     * immediately and the tool's `ctx.signal` aborts. Bounds the round's
+     * WAIT, not the tool body: a body that ignores its signal keeps running
+     * detached and its result is discarded.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Concurrency limits for tool execution. A bare number is shorthand for
+     * `{ round: n }`.
+     * - `round`: max simultaneous tool executions within one tool round.
+     *   Unbounded by default (matching previous behavior).
+     * - `background`: max simultaneous detached background-tool executions
+     *   (`tool.background` work that outlived its grace window). Default 16.
+     *   When full, work queues FIFO; queue wait counts against `timeoutMs`.
+     * Execution order may change under a cap; OUTPUT order never does
+     * (results stay in call order for prompt-cache stability).
+     */
+    toolConcurrency?: number | {
+        round?: number;
+        background?: number;
+    };
+    /**
+     * Behavior for async tools (`tool.background` / `tool.deferred`).
+     *
+     * `onRunEnd` decides what happens when the run would finish while
+     * background tasks are still in flight:
+     * - `'drain'` (default): wait up to `drainTimeoutMs` (default 30s),
+     *   inject settled results, and grant up to `maxDrainTurns` (default 2)
+     *   extra no-tool turns so the final answer incorporates them;
+     * - `'detach'`: return immediately — tasks keep running, results are
+     *   dropped (persisted as `orphaned` when a StateAccessor exists);
+     * - `'cancel'`: abort in-flight tasks and finish.
+     */
+    asyncTools?: {
+        onRunEnd?: 'drain' | 'detach' | 'cancel';
+        drainTimeoutMs?: number;
+        maxDrainTurns?: number;
+        /**
+         * Whether the single universal `task` tool is registered so the model
+         * can check/steer/result/cancel running tasks by taskId. Default true
+         * when any long-running tool is present.
+         */
+        checkins?: boolean;
+        /** Max characters for the `transcript` check view. Default 20_000. */
+        maxTranscriptChars?: number;
+    };
 };
 /**
  * Approval params when state is provided (allows approve/reject)

package/esm/lib/async-params.d.ts.map

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

package/esm/lib/async-params.js

@@ -47,7 +47,14 @@ export async function resolveAsyncFunctions(input, context) {
         'sharedContextSchema', // Client-side schema for shared context validation
         'onTurnStart', // Client-side turn start callback
         'onTurnEnd', // Client-side turn end callback
-        'allowFinalResponse', // Client-side: triggers no-tools final turn when stopWhen breaks the loop
+        'allowFinalResponse', // Client-side: tunes the default toolChoice:'none' final turn when stopWhen breaks the loop
+        'strictFinalResponse', // Client-side: restore throw on empty final after tool rounds
+        'hooks', // Client-side hook system
+        'doomLoop', // Client-side doom-loop detection config
+        'signal', // Client-side run cancellation
+        'toolTimeoutMs', // Client-side per-tool deadline default
+        'toolConcurrency', // Client-side tool concurrency limits
+        'asyncTools', // Client-side async tool (background/deferred) behavior
     ]);
     // Iterate over all keys in the input
     for (const [key, value] of Object.entries(input)) {

package/esm/lib/async-params.js.map

@@ -1 +1 @@
-{"version":3,"file":"async-params.js","sourceRoot":"","sources":["../../src/lib/async-params.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,SAAS,mBAAmB,CAC1B,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAC3B,OAKC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAExC,OAAO,GAAoC,CAAC;AAC9C,CAAC;AAoHD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAA6B,EAC7B,OAAoB;IAEpB,kCAAkC;IAClC,MAAM,eAAe,GAKjB,EAAE,CAAC;IAEP,+DAA+D;IAC/D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;QAC/B,UAAU,EAAE,oCAAoC;QAChD,OAAO,EAAE,+BAA+B;QACxC,iBAAiB,EAAE,sCAAsC;QACzD,kBAAkB,EAAE,iCAAiC;QACrD,iBAAiB,EAAE,kCAAkC;QACrD,SAAS,EAAE,yDAAyD;QACpE,qBAAqB,EAAE,mDAAmD;QAC1E,aAAa,EAAE,kCAAkC;QACjD,WAAW,EAAE,gCAAgC;QAC7C,oBAAoB,EAAE,0EAA0E;KACjG,CAAC,CAAC;IAEH,qCAAqC;IACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,wFAAwF;QACxF,qGAAqG;QACrG,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QAED,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,yDAAyD;gBACzD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBACrD,eAAe,CAAC,IAAI,CAAC;oBACnB,GAAG;oBACH,MAAM;iBACE,CAAC,CAAC;YACd,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,oDAAoD;gBACpD,MAAM,IAAI,KAAK,CACb,+CAA+C,GAAG,MAChD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,CACH,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,eAAe,CAAC,IAAI,CAAC;gBACnB,GAAG;gBACH,KAAK;aACG,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,oBAAoB,CAAC,eAAe,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"async-params.js","sourceRoot":"","sources":["../../src/lib/async-params.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,SAAS,mBAAmB,CAC1B,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAC3B,OAKC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAExC,OAAO,GAAoC,CAAC;AAC9C,CAAC;AAwND;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAA6B,EAC7B,OAAoB;IAEpB,kCAAkC;IAClC,MAAM,eAAe,GAKjB,EAAE,CAAC;IAEP,+DAA+D;IAC/D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;QAC/B,UAAU,EAAE,oCAAoC;QAChD,OAAO,EAAE,+BAA+B;QACxC,iBAAiB,EAAE,sCAAsC;QACzD,kBAAkB,EAAE,iCAAiC;QACrD,iBAAiB,EAAE,kCAAkC;QACrD,SAAS,EAAE,yDAAyD;QACpE,qBAAqB,EAAE,mDAAmD;QAC1E,aAAa,EAAE,kCAAkC;QACjD,WAAW,EAAE,gCAAgC;QAC7C,oBAAoB,EAAE,4FAA4F;QAClH,qBAAqB,EAAE,8DAA8D;QACrF,OAAO,EAAE,0BAA0B;QACnC,UAAU,EAAE,yCAAyC;QACrD,QAAQ,EAAE,+BAA+B;QACzC,eAAe,EAAE,wCAAwC;QACzD,iBAAiB,EAAE,sCAAsC;QACzD,YAAY,EAAE,wDAAwD;KACvE,CAAC,CAAC;IAEH,qCAAqC;IACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,wFAAwF;QACxF,qGAAqG;QACrG,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QAED,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,yDAAyD;gBACzD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBACrD,eAAe,CAAC,IAAI,CAAC;oBACnB,GAAG;oBACH,MAAM;iBACE,CAAC,CAAC;YACd,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,oDAAoD;gBACpD,MAAM,IAAI,KAAK,CACb,+CAA+C,GAAG,MAChD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,CACH,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,eAAe,CAAC,IAAI,CAAC;gBACnB,GAAG;gBACH,KAAK;aACG,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,oBAAoB,CAAC,eAAe,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC;AAC3E,CAAC"}

package/esm/lib/async-tool-registry.d.ts

@@ -0,0 +1,134 @@
+import type { TaskLogEntry } from './tool-task.js';
+import { ToolTask } from './tool-task.js';
+import type { PendingAsyncTool } from './tool-types.js';
+/**
+ * Outcome of a settled async tool task, harvested by the engine at turn
+ * boundaries (`flushAsyncToolDeliveries`) or during end-of-run drain.
+ */
+export interface SettledToolTask {
+    callId: string;
+    taskId: string;
+    name: string;
+    status: 'completed' | 'failed' | 'cancelled' | 'timed_out';
+    /** Present when status is 'completed'. */
+    result?: unknown;
+    /** Present otherwise. */
+    error?: string;
+    /** The call's arguments, when tracked — feeds PostToolUse at settle. */
+    input?: Record<string, unknown>;
+    /** Wall-clock ms from task start to settlement — feeds PostToolUse. */
+    durationMs: number;
+}
+/**
+ * Per-run registry of async tool tasks (background, deferred, agent).
+ *
+ * Owns the in-process half of async tool support:
+ * - background/agent tasks: tracks the in-flight work + ToolTask (logs,
+ *   inbox, transcript source), queues settled outcomes for turn-boundary
+ *   harvesting, supports drain / cancel / abort-all at run end;
+ * - deferred tasks: tracks identity only (the work lives outside the
+ *   process); the durable copy is mirrored to
+ *   `ConversationState.pendingAsyncTools` by the engine.
+ *
+ * The registry knows nothing about the tool loop or concurrency pools — the
+ * engine (`ModelResult`) owns semaphores and decides when to harvest and how
+ * to deliver. Settlement is first-writer-wins: a task settles exactly once
+ * (cancel racing completion is safe), and settled tasks drop their
+ * controller references so they cannot retain the run graph.
+ */
+export declare class AsyncToolRegistry {
+    private readonly tasks;
+    /** Settled outcomes not yet harvested by the engine. */
+    private settledQueue;
+    private taskCounter;
+    /** Resolvers waiting on "any task settled" (drain support). */
+    private settleWaiters;
+    /** Generate a task id for background/agent tasks (deferred bring their own). */
+    generateTaskId(): string;
+    /**
+     * Register a task so it is visible to steering / cancel / snapshots.
+     * Used for background tasks DURING their grace window — the work is in
+     * flight but not yet committed to async delivery. `untrack` removes it
+     * again when the work settles in-window (the call behaved
+     * synchronously; no async machinery should remain visible).
+     */
+    register(task: ToolTask): void;
+    /**
+     * Remove a task registered via `register` whose work settled inside the
+     * grace window, along with any settlement queued for it in the meantime
+     * (e.g. a cancelTask racing the in-window completion) — the call is
+     * yielding a synchronous output, so a later envelope for the same callId
+     * would be a double delivery.
+     */
+    untrack(callId: string): void;
+    /**
+     * Track an already-started background/agent task. `work` is the tool's
+     * in-flight run promise (output-validated). When `timeoutMs` is set the
+     * task is raced against it, so a body that ignores its abort signal still
+     * settles as `timed_out` instead of hanging the drain. The deadline is
+     * anchored at `task.startedAt` (the work started before tracking — a
+     * grace window may already have elapsed), so `timeoutMs` bounds the
+     * task's TOTAL runtime, matching the documented contract.
+     */
+    trackBackground(task: ToolTask, work: Promise<unknown>, options?: {
+        timeoutMs?: number;
+    }): void;
+    /** Track a deferred task (identity only; work lives outside the process). */
+    trackDeferred(entry: {
+        callId: string;
+        taskId: string;
+        name: string;
+        expiresAt?: number;
+        pollAfterMs?: number;
+    }): ToolTask;
+    private settle;
+    /** Harvest (and clear) settled outcomes queued since the last call. */
+    takeSettled(): SettledToolTask[];
+    /** True when any background/agent task is still in flight. */
+    hasInFlight(): boolean;
+    /** True when any settled outcome awaits harvesting. */
+    hasUnharvestedSettled(): boolean;
+    /** True when any task (any mode) has been tracked this run. */
+    hasTasks(): boolean;
+    /** Find the live task for a task id. */
+    getTask(taskId: string): ToolTask | undefined;
+    /** Find the live task for a call id. */
+    findByCallId(callId: string): ToolTask | undefined;
+    /** All live tasks. */
+    listTasks(): ToolTask[];
+    /** Append a log entry to a task by call id (engine log sink). */
+    appendLog(callId: string, data: unknown, kind?: TaskLogEntry['kind']): void;
+    /** Mark every still-working background/agent task as orphaned (detach mode). */
+    markWorkingAsOrphaned(): PendingAsyncTool[];
+    /** Snapshot of every tracked task (for `getAsyncTasks()` / persistence). */
+    snapshot(): PendingAsyncTool[];
+    /**
+     * Send a steering message to a working task's run body. Deferred tasks
+     * are owned by an external system — steering them is the caller's job.
+     * @returns true when a working in-process task received the message.
+     */
+    sendToTask(taskId: string, message: unknown): boolean;
+    /**
+     * Cancel one task by task id. Settles it as 'cancelled' immediately
+     * (first-writer-wins makes the racing body's own settlement a no-op) and
+     * aborts the controller so cooperative bodies stop working.
+     *
+     * Deferred tasks: cancellation is LOCAL-ONLY — the conversation records
+     * the cancel, but the external system is not notified (mirror of the
+     * sendToTask contract; tell the external system yourself, or use the
+     * tool's `.cancel()` method which persists the terminal status for
+     * cross-process callers).
+     * @returns true when a working task was found and cancelled.
+     */
+    cancelTask(taskId: string, reason?: string): boolean;
+    /** Abort every in-flight background/agent task (run abort / onRunEnd: 'cancel'). */
+    abortAll(reason?: string): void;
+    /**
+     * Wait until every in-flight task settles or `timeoutMs` elapses,
+     * whichever comes first. Returns true when everything settled.
+     */
+    drain(timeoutMs: number): Promise<boolean>;
+    /** Resolve true on the next settle event, or false after `timeoutMs`. */
+    private waitForSettle;
+}
+//# sourceMappingURL=async-tool-registry.d.ts.map

package/esm/lib/async-tool-registry.d.ts.map

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

package/esm/lib/async-tool-registry.js

@@ -0,0 +1,352 @@
+import { ToolTask } from './tool-task.js';
+/**
+ * Per-run registry of async tool tasks (background, deferred, agent).
+ *
+ * Owns the in-process half of async tool support:
+ * - background/agent tasks: tracks the in-flight work + ToolTask (logs,
+ *   inbox, transcript source), queues settled outcomes for turn-boundary
+ *   harvesting, supports drain / cancel / abort-all at run end;
+ * - deferred tasks: tracks identity only (the work lives outside the
+ *   process); the durable copy is mirrored to
+ *   `ConversationState.pendingAsyncTools` by the engine.
+ *
+ * The registry knows nothing about the tool loop or concurrency pools — the
+ * engine (`ModelResult`) owns semaphores and decides when to harvest and how
+ * to deliver. Settlement is first-writer-wins: a task settles exactly once
+ * (cancel racing completion is safe), and settled tasks drop their
+ * controller references so they cannot retain the run graph.
+ */
+export class AsyncToolRegistry {
+    constructor() {
+        this.tasks = new Map();
+        /** Settled outcomes not yet harvested by the engine. */
+        this.settledQueue = [];
+        this.taskCounter = 0;
+        /** Resolvers waiting on "any task settled" (drain support). */
+        this.settleWaiters = [];
+    }
+    /** Generate a task id for background/agent tasks (deferred bring their own). */
+    generateTaskId() {
+        this.taskCounter++;
+        if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+            return `task_${crypto.randomUUID()}`;
+        }
+        return `task_${Date.now()}_${this.taskCounter}`;
+    }
+    /**
+     * Register a task so it is visible to steering / cancel / snapshots.
+     * Used for background tasks DURING their grace window — the work is in
+     * flight but not yet committed to async delivery. `untrack` removes it
+     * again when the work settles in-window (the call behaved
+     * synchronously; no async machinery should remain visible).
+     */
+    register(task) {
+        this.tasks.set(task.callId, task);
+    }
+    /**
+     * Remove a task registered via `register` whose work settled inside the
+     * grace window, along with any settlement queued for it in the meantime
+     * (e.g. a cancelTask racing the in-window completion) — the call is
+     * yielding a synchronous output, so a later envelope for the same callId
+     * would be a double delivery.
+     */
+    untrack(callId) {
+        this.tasks.delete(callId);
+        this.settledQueue = this.settledQueue.filter((s) => s.callId !== callId);
+    }
+    /**
+     * Track an already-started background/agent task. `work` is the tool's
+     * in-flight run promise (output-validated). When `timeoutMs` is set the
+     * task is raced against it, so a body that ignores its abort signal still
+     * settles as `timed_out` instead of hanging the drain. The deadline is
+     * anchored at `task.startedAt` (the work started before tracking — a
+     * grace window may already have elapsed), so `timeoutMs` bounds the
+     * task's TOTAL runtime, matching the documented contract.
+     */
+    trackBackground(task, work, options) {
+        this.tasks.set(task.callId, task);
+        let timer;
+        const timeoutMs = options?.timeoutMs;
+        if (timeoutMs !== undefined && timeoutMs > 0) {
+            const remainingMs = Math.max(0, timeoutMs - (Date.now() - task.startedAt));
+            timer = setTimeout(() => {
+                const timeoutError = new Error(`Tool "${task.toolName}" task timed out after ${timeoutMs}ms`);
+                // Capture the controller BEFORE settling — settle() drops the
+                // reference as a leak guard, and the running body must still be
+                // told to stop (same pattern as cancelTask / abortAll).
+                const controller = task.controller;
+                this.settle(task.callId, {
+                    status: 'timed_out',
+                    error: timeoutError.message,
+                });
+                controller?.abort(timeoutError);
+            }, remainingMs);
+            if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+                timer.unref();
+            }
+        }
+        work
+            .then((result) => {
+            this.settle(task.callId, {
+                status: 'completed',
+                result,
+            });
+        }, (error) => {
+            const cancelled = task.controller?.signal.aborted ?? false;
+            this.settle(task.callId, {
+                status: cancelled ? 'cancelled' : 'failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        });
+    }
+    /** Track a deferred task (identity only; work lives outside the process). */
+    trackDeferred(entry) {
+        const task = new ToolTask({
+            taskId: entry.taskId,
+            callId: entry.callId,
+            toolName: entry.name,
+            mode: 'defer',
+            ...(entry.expiresAt !== undefined && {
+                expiresAt: entry.expiresAt,
+            }),
+            ...(entry.pollAfterMs !== undefined && {
+                pollAfterMs: entry.pollAfterMs,
+            }),
+        });
+        this.tasks.set(entry.callId, task);
+        return task;
+    }
+    settle(callId, outcome) {
+        const task = this.tasks.get(callId);
+        if (!task || task.status !== 'working') {
+            return; // first writer wins
+        }
+        task.status =
+            outcome.status === 'completed'
+                ? 'completed'
+                : outcome.status === 'cancelled'
+                    ? 'cancelled'
+                    : 'failed';
+        task.settledAt = Date.now();
+        if (outcome.status === 'completed') {
+            task.result = outcome.result;
+        }
+        else {
+            task.error = outcome.error;
+            task.appendLog(outcome.error, 'system');
+        }
+        // Leak guard: a settled task must not retain the run graph.
+        task.controller = undefined;
+        this.settledQueue.push({
+            callId,
+            taskId: task.taskId,
+            name: task.toolName,
+            durationMs: (task.settledAt ?? Date.now()) - task.startedAt,
+            ...(task.input !== undefined && {
+                input: task.input,
+            }),
+            ...outcome,
+        });
+        const waiters = this.settleWaiters;
+        this.settleWaiters = [];
+        for (const waiter of waiters) {
+            waiter();
+        }
+    }
+    /** Harvest (and clear) settled outcomes queued since the last call. */
+    takeSettled() {
+        const settled = this.settledQueue;
+        this.settledQueue = [];
+        return settled;
+    }
+    /** True when any background/agent task is still in flight. */
+    hasInFlight() {
+        for (const task of this.tasks.values()) {
+            if (task.mode !== 'defer' && task.status === 'working') {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** True when any settled outcome awaits harvesting. */
+    hasUnharvestedSettled() {
+        return this.settledQueue.length > 0;
+    }
+    /** True when any task (any mode) has been tracked this run. */
+    hasTasks() {
+        return this.tasks.size > 0;
+    }
+    /** Find the live task for a task id. */
+    getTask(taskId) {
+        for (const task of this.tasks.values()) {
+            if (task.taskId === taskId) {
+                return task;
+            }
+        }
+        return undefined;
+    }
+    /** Find the live task for a call id. */
+    findByCallId(callId) {
+        return this.tasks.get(callId);
+    }
+    /** All live tasks. */
+    listTasks() {
+        return Array.from(this.tasks.values());
+    }
+    /** Append a log entry to a task by call id (engine log sink). */
+    appendLog(callId, data, kind) {
+        this.tasks.get(callId)?.appendLog(data, kind);
+    }
+    /** Mark every still-working background/agent task as orphaned (detach mode). */
+    markWorkingAsOrphaned() {
+        const orphaned = [];
+        for (const task of this.tasks.values()) {
+            if (task.mode !== 'defer' && task.status === 'working') {
+                task.orphaned = true;
+                orphaned.push({
+                    callId: task.callId,
+                    taskId: task.taskId,
+                    name: task.toolName,
+                    mode: task.mode,
+                    status: task.status,
+                    startedAt: task.startedAt,
+                    orphaned: true,
+                    ...(task.lastLog !== undefined && {
+                        lastLog: {
+                            at: task.lastLog.at,
+                            text: renderLastLog(task.lastLog.data),
+                        },
+                    }),
+                });
+            }
+        }
+        return orphaned;
+    }
+    /** Snapshot of every tracked task (for `getAsyncTasks()` / persistence). */
+    snapshot() {
+        return Array.from(this.tasks.values(), (t) => ({
+            callId: t.callId,
+            taskId: t.taskId,
+            name: t.toolName,
+            mode: t.mode,
+            status: t.status,
+            startedAt: t.startedAt,
+            ...(t.expiresAt !== undefined && {
+                expiresAt: t.expiresAt,
+            }),
+            ...(t.pollAfterMs !== undefined && {
+                pollAfterMs: t.pollAfterMs,
+            }),
+            ...(t.orphaned === true && {
+                orphaned: true,
+            }),
+            ...(t.lastLog !== undefined && {
+                lastLog: {
+                    at: t.lastLog.at,
+                    text: renderLastLog(t.lastLog.data),
+                },
+            }),
+        }));
+    }
+    /**
+     * Send a steering message to a working task's run body. Deferred tasks
+     * are owned by an external system — steering them is the caller's job.
+     * @returns true when a working in-process task received the message.
+     */
+    sendToTask(taskId, message) {
+        const task = this.getTask(taskId);
+        if (!task || task.status !== 'working') {
+            return false;
+        }
+        if (task.mode === 'defer') {
+            throw new Error(`Task "${taskId}" is deferred — its work runs in an external system; deliver steering messages there instead.`);
+        }
+        task.send(message);
+        return true;
+    }
+    /**
+     * Cancel one task by task id. Settles it as 'cancelled' immediately
+     * (first-writer-wins makes the racing body's own settlement a no-op) and
+     * aborts the controller so cooperative bodies stop working.
+     *
+     * Deferred tasks: cancellation is LOCAL-ONLY — the conversation records
+     * the cancel, but the external system is not notified (mirror of the
+     * sendToTask contract; tell the external system yourself, or use the
+     * tool's `.cancel()` method which persists the terminal status for
+     * cross-process callers).
+     * @returns true when a working task was found and cancelled.
+     */
+    cancelTask(taskId, reason) {
+        const task = this.getTask(taskId);
+        if (!task || task.status !== 'working') {
+            return false;
+        }
+        const controller = task.controller;
+        this.settle(task.callId, {
+            status: 'cancelled',
+            error: reason ?? `Task ${taskId} cancelled`,
+        });
+        controller?.abort(new Error(reason ?? `Task ${taskId} cancelled`));
+        return true;
+    }
+    /** Abort every in-flight background/agent task (run abort / onRunEnd: 'cancel'). */
+    abortAll(reason) {
+        for (const task of this.tasks.values()) {
+            if (task.mode !== 'defer' && task.status === 'working') {
+                const controller = task.controller;
+                this.settle(task.callId, {
+                    status: 'cancelled',
+                    error: reason ?? 'Run aborted',
+                });
+                controller?.abort(new Error(reason ?? 'Run aborted'));
+            }
+        }
+    }
+    /**
+     * Wait until every in-flight task settles or `timeoutMs` elapses,
+     * whichever comes first. Returns true when everything settled.
+     */
+    async drain(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (this.hasInFlight()) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                return false;
+            }
+            const settled = await this.waitForSettle(remaining);
+            if (!settled) {
+                return !this.hasInFlight();
+            }
+        }
+        return true;
+    }
+    /** Resolve true on the next settle event, or false after `timeoutMs`. */
+    waitForSettle(timeoutMs) {
+        return new Promise((resolve) => {
+            const onSettle = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                this.settleWaiters = this.settleWaiters.filter((w) => w !== onSettle);
+                resolve(false);
+            }, timeoutMs);
+            // Don't keep the event loop alive purely for the drain timer.
+            if (typeof timer === 'object' && 'unref' in timer && typeof timer.unref === 'function') {
+                timer.unref();
+            }
+            this.settleWaiters.push(onSettle);
+        });
+    }
+}
+/** Render a log entry's data to the small persisted `lastLog.text` form. */
+function renderLastLog(data) {
+    const text = typeof data === 'string' ? data : (JSON.stringify(data) ?? String(data));
+    return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+//# sourceMappingURL=async-tool-registry.js.map