@openrouter/agent 0.8.0 → 0.10.0

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

@@ -1,11 +1,16 @@
 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';
 export type { Tool } from './tool-types.js';
+/** Identifies objects produced by `@openrouter/agent/tool-set`. */
+export declare const TOOL_SET_SNAPSHOT: unique symbol;
+/** Remove tool-set metadata only from marked snapshots or their spreads. */
+export declare function stripToolSetSnapshotMetadata(input: Record<PropertyKey, unknown>): void;
 /**
  * A field can be either a value of type T or a function that computes T
  */
@@ -18,6 +23,16 @@ type BaseCallModelInput<TTools extends readonly Tool[] = readonly Tool[], TShare
 } & {
     input: FieldOrAsyncFunction<Item[]> | string;
     tools?: TTools;
+    /**
+     * Optional filter restricting which tools are exposed to the model for this
+     * call. Tool names not in this list are removed before the request is sent
+     * and are also not callable by the model. Pairs with
+     * `@openrouter/agent/tool-set`'s `.inferTools()` output — spreading its
+     * `{ tools, activeTools }` (or a whole marked snapshot from `.inferTools()` /
+     * `.resolve()` / `.resolveSituation()`) into this object is safe: `callModel`
+     * strips metadata introduced by that snapshot before sending the request.
+     */
+    activeTools?: readonly string[];
     stopWhen?: StopWhen<TTools>;
     /** Typed context data passed to tools via contextSchema. Includes optional `shared` key. */
     context?: ContextInput<ToolContextMapWithShared<TTools, TShared>>;
@@ -71,6 +86,87 @@ type BaseCallModelInput<TTools extends readonly Tool[] = readonly Tool[], TShare
     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

@@ -1,3 +1,21 @@
+/** Identifies objects produced by `@openrouter/agent/tool-set`. */
+export const TOOL_SET_SNAPSHOT = Symbol.for('@openrouter/agent/tool-set/snapshot');
+const TOOL_SET_SNAPSHOT_METADATA_KEYS = new Set([
+    'enabled',
+    'disabled',
+    'statusByTool',
+    'callModel',
+]);
+/** Remove tool-set metadata only from marked snapshots or their spreads. */
+export function stripToolSetSnapshotMetadata(input) {
+    if (input[TOOL_SET_SNAPSHOT] !== true) {
+        return;
+    }
+    for (const key of TOOL_SET_SNAPSHOT_METADATA_KEYS) {
+        delete input[key];
+    }
+    delete input[TOOL_SET_SNAPSHOT];
+}
 /**
  * Type guard to check if a value is a parameter function
  * Parameter functions take TurnContext and return a value or promise
@@ -50,11 +68,22 @@ export async function resolveAsyncFunctions(input, context) {
         '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
+        'activeTools', // Applied client-side to filter tools before conversion
     ]);
+    const request = {
+        ...input,
+    };
+    stripToolSetSnapshotMetadata(request);
     // Iterate over all keys in the input
-    for (const [key, value] of Object.entries(input)) {
+    for (const [key, value] of Object.entries(request)) {
         // Skip client-only fields - they're handled separately and shouldn't be sent to the API
         // Note: tools are already in API format at this point (converted in callModel()), so we include them
+        //
         if (clientOnlyFields.has(key)) {
             continue;
         }

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

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

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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"}