@openrouter/agent 0.8.0 → 0.10.0

package/esm/lib/model-result.d.ts

@@ -3,10 +3,12 @@ import type { RequestOptions } from '@openrouter/sdk/lib/sdks';
 import type * as models from '@openrouter/sdk/models';
 import type { $ZodObject, $ZodShape } from 'zod/v4/core';
 import type { CallModelInput } from './async-params.js';
+import type { DoomLoopOption, DoomLoopVerdict } from './doom-loop.js';
 import type { HooksManager } from './hooks-manager.js';
+import type { SessionUsageTotals } from './hooks-types.js';
 import type { StreamableOutputItem } from './stream-transformers.js';
 import type { ContextInput } from './tool-context.js';
-import type { ConversationState, InferToolEventsUnion, InferToolOutputsUnion, ParsedToolCall, ResponseStreamEvent, StateAccessor, StopWhen, Tool, ToolContextMapWithShared, ToolStreamEvent, TurnContext } from './tool-types.js';
+import type { ConversationState, CorrelatedResponseStreamEvent, CorrelatedToolStreamEvent, ParsedToolCall, PendingAsyncTool, StateAccessor, StopWhen, Tool, ToolContextMapWithShared, TurnContext } from './tool-types.js';
 /**
  * Default directive appended as a final user message on the forced final
  * turn (`allowFinalResponse` defaulting to on, or explicitly `true`).
@@ -56,6 +58,63 @@ export interface GetResponseOptions<TTools extends readonly Tool[], TShared exte
     strictFinalResponse?: boolean;
     /** Hook system for lifecycle events */
     hooks?: 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). `true` enables recommended defaults;
+     * an object tunes thresholds. Off by default.
+     */
+    doomLoop?: DoomLoopOption;
+    /**
+     * Cancel the whole run: stops the loop at the next boundary and aborts
+     * the in-flight API request/stream. See `CallModelInput.signal`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Default per-tool execution deadline in milliseconds. A tool-level
+     * `timeoutMs` overrides it. See `BaseToolFunction.timeoutMs` for the
+     * semantics (bounds the round's wait, not the tool body).
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Concurrency limits for tool execution. A bare number is shorthand for
+     * `{ round: n }`. `round` bounds simultaneous executions within a tool
+     * round (unbounded by default — matching existing behavior); `background`
+     * bounds detached background-tool work (default 16).
+     */
+    toolConcurrency?: number | {
+        round?: number;
+        background?: number;
+    };
+    /**
+     * Behavior for async tools (`tool.background` / `tool.deferred`).
+     */
+    asyncTools?: {
+        /**
+         * What to do when the run would end with background tasks in flight:
+         * - `'drain'` (default): wait (bounded by `drainTimeoutMs`) and give the
+         *   model up to `maxDrainTurns` extra turns so the final answer
+         *   incorporates late results;
+         * - `'detach'`: return immediately; tasks keep running and their results
+         *   are dropped (persisted as `orphaned` when a StateAccessor exists);
+         * - `'cancel'`: abort in-flight tasks and finish.
+         */
+        onRunEnd?: 'drain' | 'detach' | 'cancel';
+        /** Bound on each end-of-run drain wait. Default 30_000. */
+        drainTimeoutMs?: number;
+        /** Max extra model turns granted to deliver drained results. Default 2. */
+        maxDrainTurns?: number;
+        /**
+         * Model-side check-ins: whether calling a long-running tool with a
+         * `taskId` answers status/logs/transcript instead of starting new work.
+         * Default true. When false, placeholders revert to "do not call this
+         * tool again" and the check schema is not advertised.
+         */
+        checkins?: boolean;
+        /** Max characters for the `transcript` check view. Default 20_000. */
+        maxTranscriptChars?: number;
+    };
 }
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
@@ -87,8 +146,16 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
     private toolEventBroadcaster;
     private allToolExecutionRounds;
     private resolvedRequest;
+    private activeConsumedForcedToolChoiceKey;
+    private configuredForcedToolChoiceKey;
+    private configuredToolChoice;
+    private preparedEffectiveToolChoice;
+    private preparedToolChoiceCommit;
+    private dispatchedToolChoiceCommit;
+    private dispatchedCallerToolChoice;
     private pendingFreshItems;
     private resumingFromClientTools;
+    private resumingFromAsyncTools;
     private stateAccessor;
     private currentState;
     private requireApprovalFn;
@@ -105,7 +172,36 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
     private readonly hookDeniedCalls;
     private pendingModelCall;
     private readonly sessionUsage;
+    private readonly doomLoopMonitor;
+    private doomLoopStop;
+    private pendingDoomLoopSteer;
+    private doomLoopRound;
+    private readonly doomLoopRoundDecisions;
+    private readonly doomLoopRoundKeyMaterial;
+    private doomLoopChain;
+    private pendingDoomLoopEscalation;
+    private readonly doomLoopEscalation;
+    private asyncToolRegistry;
+    private roundGate;
+    private backgroundPool;
+    private readonly perToolGates;
+    private readonly inflightToolControllers;
     constructor(options: GetResponseOptions<TTools, TShared>);
+    /** Lazily create the async tool registry. */
+    private ensureAsyncToolRegistry;
+    /** Per-tool concurrency gate, created on first use. */
+    private perToolGate;
+    /**
+     * Compose the per-call abort signal for one tool execution: the run
+     * signal plus a per-call controller the engine can abort independently
+     * (timeout race, cancelTask, cancel()). The tool deadline deliberately
+     * does NOT ride the signal here — the race in `executeSingleToolCall`
+     * owns exactly one timer (which aborts the controller), so the round's
+     * timeout resolution and the body's abort observation cannot disagree.
+     */
+    private composeToolSignal;
+    /** Abort every in-flight tool execution and background task. */
+    private abortAllToolWork;
     /**
      * Get or create the unified turn broadcaster (lazy initialization).
      * Broadcasts all API stream events, tool events, and turn delimiters across turns.
@@ -249,6 +345,169 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      *   `effectiveToolCall` reflects any `mutatedInput` piped by PreToolUse.
      */
     private runToolWithHooks;
+    /**
+     * Advance the doom-loop round counter and declare the round's calls. Called
+     * at every execution-batch boundary (main tool round, auto-approve batch
+     * while pausing, approved-on-resume batch). Identical calls WITHIN one round
+     * are duplicates — one piece of loop evidence, one shared decision.
+     *
+     * `batch` is every call the round will make. A round's identity for one tool
+     * is the *set* of fingerprints it was called with, and that set has to be
+     * complete before any of the round's calls is scored: accumulating it call
+     * by call made a round that is a superset of the previous one transiently
+     * match it, blocking calls that represented real progress, with the outcome
+     * depending on emission order. Declaration is best-effort — a call whose key
+     * material is exempt or unhashable is simply left out, and the per-call
+     * fallback chain in `enqueueDoomLoopEvaluation` still governs identity at
+     * record time.
+     *
+     * Only calls that the round will actually CHECK are declared. A `loopKey`
+     * function is user code that may count or log, so it must not run for a call
+     * the detector never evaluates: manual tool calls (no `execute`, no
+     * `onToolCalled`) are handed to the caller and never recorded, and every
+     * execution path skips them with the same `isAutoResolvableTool` predicate
+     * used here. Their absence from the declared set is also correct on its own
+     * terms — they are not evidence, so they are not part of the round.
+     *
+     * INVARIANT — every declared member must eventually be recorded. A call
+     * that is declared but never reaches the doom-loop checkpoint is a phantom
+     * member of the round's identity: the tool's streak silently resets the
+     * moment the phantom stops being emitted (pinned by the "declared-but-
+     * never-recorded member" test in doom-loop-fanout.test.ts). The filters
+     * below therefore MIRROR every path that skips recording — unknown/manual
+     * tools (`isAutoResolvableTool`, also gating executeAutoApproveTools and
+     * the approval-resume loop), `hookDeniedCalls` (consumed before the
+     * checkpoint in executeSingleToolCall), and `loopKey`-exempt calls (early
+     * return in checkDoomLoopBeforeExecution; the same resolution is cached
+     * here so both sides agree). If you add a new short-circuit between
+     * declaration and the checkpoint — a pre-execution gate, a batch filter —
+     * it MUST be reflected here, or fan-out detection degrades silently for
+     * that tool rather than failing loudly.
+     *
+     * KNOWN RESIDUAL (documented, not mirrored): a per-request timeout or
+     * abort can cancel a call AFTER declaration but BEFORE its checkpoint,
+     * leaving a declared phantom for that round. Bounded and fail-safe: the
+     * round-set streak for that tool resets when the phantom stops recurring,
+     * while per-call streaks are unaffected — detection degrades to per-call
+     * for the affected tool rather than being lost. Un-declaring mid-round
+     * would mutate the round's identity while it is being scored, which is the
+     * incremental-set order-dependence this design exists to prevent.
+     */
+    private beginDoomLoopRound;
+    /**
+     * Evaluate one call against the doom-loop monitor, serialized on
+     * `doomLoopChain` so parallel executions record in the deterministic
+     * order their evaluations were ENQUEUED (the `.map()` over a round's
+     * calls runs synchronously to its first await, i.e. model-emission
+     * order) — not in hash-completion order.
+     *
+     * Applies the fallback invariant: detection must never take down or
+     * alter a run except via its defined actions. Unhashable key material
+     * (bigint, non-finite numbers, circular/too-deep structures from a
+     * computed loopKey) degrades to `fallbackKeyMaterial`; if THAT is also
+     * unhashable (parse-error path passes null), detection is skipped for
+     * the call and it proceeds normally.
+     *
+     * Returns the final decision for this call (`action: 'proceed'` when no
+     * rung fired or the call is exempt/skipped; `message` carries the
+     * verdict's explanation for block outputs). Side effects (steer queue,
+     * stop arm) are applied here so every caller shares them.
+     */
+    private enqueueDoomLoopEvaluation;
+    /**
+     * Doom-loop checkpoint for one tool call, run before PreToolUse/execution.
+     *
+     * Resolves the tool's `loopKey` declaration (function |
+     * false | absent — see {@link resolveLoopKeyMaterial}) and evaluates the
+     * call against the monitor. Ladder actions:
+     *
+     * - `observe` — hook already emitted, nothing else.
+     * - `steer`   — queue a corrective user message for the next model turn.
+     * - `block`   — return `blocked` so the caller synthesizes an error output
+     *   without executing. The model sees the explanation in the tool result.
+     * - `stop`    — arm `doomLoopStop`; ALSO blocks this call (executing a
+     *   call the detector just condemned, then stopping, would be
+     *   incoherent). The loop halts before the next model request.
+     */
+    private checkDoomLoopBeforeExecution;
+    /**
+     * Emit the DoomLoopDetected hook for a verdict and resolve the final
+     * action. Handlers may override per event (`overrideAction`), letting
+     * userland escalate or de-escalate without reconfiguring the ladder;
+     * the LAST override in the chain wins (matching PermissionRequest's
+     * last-wins convention). Non-blockable verdicts (text, server tools —
+     * the tokens are already emitted / the tool already ran) downgrade a
+     * 'block' override to 'observe'. An 'escalate' override is honored only
+     * when an escalation mechanism is configured with remaining budget;
+     * otherwise it downgrades to 'observe' (never silently to a stronger
+     * action).
+     */
+    private applyDoomLoopVerdict;
+    /**
+     * Apply the side effects of a resolved doom-loop action shared by every
+     * checkpoint: queue steer guidance, arm an escalation for the next
+     * request, or arm the stop verdict. 'block' has no shared side effect —
+     * the calling checkpoint synthesizes the blocked output itself.
+     */
+    private applyDoomLoopSideEffects;
+    /**
+     * Consume a pending escalation into ONE-TURN request overrides:
+     *
+     * - `model` — replace the request's model for this dispatch only (the
+     *   base `resolvedRequest` is never mutated, so the following turn
+     *   reverts automatically).
+     * - `advisor` — append an `openrouter:advisor` server tool (transcript
+     *   forwarded, instructions describing the detected loop) and pin
+     *   `toolChoice` to it via `allowed_tools`/`required`, so the stuck model
+     *   must consult the advisor before doing anything else this turn.
+     *
+     * Burns one unit of the escalation budget (persisted via the monitor) at
+     * APPLICATION time — verdicts the engine never got to apply (run stopped,
+     * paused, or overridden) do not spend.
+     */
+    private takeDoomLoopEscalationOverrides;
+    /**
+     * Step-level doom-loop checkpoint on a fresh model response:
+     *
+     * 1. Text detectors — within-response token repetition + cross-step
+     *    identical-text streak.
+     * 2. Server-tool fingerprints — server tools (web_search_call etc.) never
+     *    pass through runToolWithHooks; their repetition is detected here,
+     *    post-execution, from the echoed call fields on the output item.
+     *    Post-execution ⇒ block is meaningless (allowBlock: false); the
+     *    actions are observe/steer/stop.
+     *
+     * Runs where the loop already inspects each fresh response, so scripted
+     * transcripts exercise it deterministically.
+     */
+    private checkDoomLoopForResponse;
+    /**
+     * Queue steer guidance, deduplicating identical messages (one verdict can
+     * repeat across calls in a round; the model needs the guidance once).
+     */
+    private queueDoomLoopSteer;
+    /**
+     * Inject any queued doom-loop steer messages as a user message before the
+     * next model turn. Reuses the Stop-hook appendPrompt injection path, so
+     * state/messages advance observably. Called in-loop before each follow-up
+     * request AND before every pause-persist, so guidance queued right before
+     * a pause lands in the persisted conversation instead of being dropped.
+     */
+    private flushDoomLoopSteer;
+    /**
+     * Halt the run for an armed doom-loop stop verdict, keeping the persisted
+     * history well-formed: every executable `function_call` in the current
+     * response that has no output yet gets a synthesized halt-error output
+     * (persisted via the normal tool-result path), so a stateful resume never
+     * sends a dangling `function_call` (providers reject those with a 400).
+     *
+     * Used by every stop site: the pre-round break, the post-round break, the
+     * no-tools early return, the allow-final-response gate, and the approval-
+     * resume gate.
+     *
+     * @param resolvedCallIds - call ids that already have outputs this round.
+     */
+    private sealDoomLoopStop;
     /**
      * Build the per-emit context for lifecycle hook emits. Threads this run's
      * session identity into `context.sessionId` on every emit, so a
@@ -258,14 +517,38 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * run to start).
      */
     private hookEmitContext;
+    /**
+     * Emit PostToolUse / PostToolUseFailure for an async task at settlement —
+     * the point its final output actually exists. Round-synchronous tools
+     * emit these in runToolWithHooks; async invocations skip that emission
+     * (no output yet) and land here instead. `durationMs` is the task's
+     * start-to-settle wall clock (includes background-pool queue wait, which
+     * counts against the task's own timeout budget). Observation-only — a
+     * throwing hook must not break delivery.
+     */
+    private emitAsyncSettledHooks;
     /**
      * Emit SessionEnd exactly once, and only when a matching SessionStart
      * actually succeeded. Safe to call from multiple teardown paths.
      */
     private emitSessionEndOnce;
+    /**
+     * Materialize the running session aggregate as an immutable
+     * `SessionUsageTotals`. `cost` is present only when at least one response
+     * reported it, matching the hook payload's optionality (a summed cost of
+     * `0` from cost-less responses would read as "free" rather than "unknown").
+     *
+     * Single source of truth for both `SessionEnd.totalUsage` and the public
+     * `getUsage()` accessor, so the two can never drift.
+     */
+    private snapshotSessionUsage;
     /**
      * Emit PostModelCall for a completed model response and fold its usage
      * into the session aggregate. One emit per materialized response.
+     *
+     * Accumulation runs unconditionally — before the hooks short-circuit —
+     * because `getUsage()` surfaces these totals to callers who configured no
+     * hooks at all. Only the hook emit is gated on a `HooksManager`.
      */
     private emitPostModelCall;
     /**
@@ -292,9 +575,9 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
     private runStopHook;
     /**
      * Session teardown for the no-tools stream paths, which bypass
-     * executeToolsIfNeeded (the normal SessionEnd site). Emits SessionEnd once
-     * and drains pending hook work. Never throws: teardown must not mask the
-     * stream's own outcome.
+     * executeToolsIfNeeded (the normal SessionEnd site). Materializes the
+     * parked model-call telemetry, emits SessionEnd once, and drains pending
+     * hook work. Never throws: teardown must not mask the stream's own outcome.
      */
     private finishHooksSessionForStream;
     /**
@@ -332,6 +615,19 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * one-time `console.warn` in dev builds explains why).
      */
     private maybeRunUserPromptSubmit;
+    /**
+     * Settle an async invocation on the approval/resume path, where results
+     * are accumulated as `UnsentToolResult`s rather than round outputs.
+     *
+     * - background: degrade to synchronous execution — the approval flow is
+     *   already a discrete resume step, so there is no round to unblock; the
+     *   work is awaited and its (validated) value becomes the unsent result.
+     * - defer: the external task HAS been started by `start()`; record the
+     *   pending placeholder as the unsent result and track the task on
+     *   `pendingAsyncTools` so `resumeToolResults` can deliver the real
+     *   result later as an envelope.
+     */
+    private settleAsyncInvocationAsUnsent;
     /**
      * Execute tools that can auto-execute (don't require approval) in parallel.
      *
@@ -392,6 +688,31 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * @param unresolvedCalls - Manual (or otherwise non-auto-resolvable) tool calls
      */
     private persistClientToolsPause;
+    /**
+     * Persist state when one or more deferred tools (`tool.deferred`) started
+     * durable external tasks this round. The placeholder outputs are already
+     * persisted (the round is fully paired), so — unlike HITL/manual pauses —
+     * nothing dangles; the pause exists purely because the model's next turn
+     * should wait for the real results.
+     *
+     * Mirrors `persistHitlPause` in shape. Status `awaiting_async_tools` is
+     * distinct from `awaiting_client_tools`: the tool DID execute; only its
+     * result is pending. Resumption happens via the deferred tool's
+     * `.resolve()` / `.fail()` / `.cancel()` or `resumeToolResults()`.
+     */
+    private persistAsyncToolPause;
+    /**
+     * Harvest background tasks that settled since the last flush and inject
+     * their outcomes into the conversation as `tool_task_result` envelope
+     * messages (user role). Runs at the same safe point as
+     * `flushDoomLoopSteer()` — after a fully-paired round, before the next
+     * request — because injecting between a dangling `function_call` and its
+     * future output would be invalid history.
+     *
+     * A delivery is forward progress: the text-repetition streak is reset so a
+     * model saying "still waiting…" between deliveries is not condemned.
+     */
+    private flushAsyncToolDeliveries;
     /**
      * Compute the `output` payload sent to the model for a successfully
      * settled tool execution. Routes through `toModelOutput` when the tool
@@ -419,7 +740,119 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * outcome consumed by `executeToolRound`'s aggregation loop.
      */
     private executeSingleToolCall;
+    /**
+     * The `tool_timeout` execution outcome for a call whose deadline fired:
+     * the model receives an error output immediately (the abandoned body
+     * keeps running detached).
+     */
+    private buildToolTimeoutOutcome;
+    /**
+     * PermissionRequest-hook denial for a call, as a `hook_blocked` outcome —
+     * or null when the call was not denied. Consumes the entry so a later
+     * round with a reused id is not affected.
+     */
+    private consumeHookDenial;
+    /**
+     * Race a tool execution against its deadline. Returns `'timeout'` when the
+     * deadline fires first — the caller synthesizes the `tool_timeout` output —
+     * and aborts the body's controller so cooperative tools stop working. The
+     * timer is cleared on settle either way.
+     */
+    private raceToolDeadline;
     private executeToolRound;
+    /**
+     * Handle one async invocation from a round.
+     *
+     * Background: start the work under the background pool, race it against
+     * the grace window — settle in time and the call yields a plain
+     * synchronous output (no async machinery visible); otherwise emit the
+     * pending placeholder and let the registry track the task.
+     *
+     * Deferred: emit the placeholder and report the task for the pause path.
+     */
+    private handleAsyncInvocation;
+    /**
+     * Reject a `ctx.defer()` taskId already claimed by ANOTHER pending task.
+     * Task ids are the resolution key (resumeToolResults matches on them), so
+     * a duplicate would make one of the two calls unresolvable — the
+     * conversation would wait forever. Caller-supplied ids
+     * (`ctx.defer(ticket.id)`) carry no uniqueness guarantee; reject the
+     * collision at start time, when the tool can still see it.
+     * @returns the error output for the colliding call, or null when unique.
+     */
+    private rejectDuplicateTaskId;
+    /**
+     * A mutable binding between a tool call's run context and its (created
+     * later) ToolTask. `ctx.log()` entries before the task exists are
+     * buffered; `ctx.onMessage()` registrations are forwarded on bind.
+     */
+    private createRunBinding;
+    /**
+     * Run a background tool's work under the tool's own concurrency gate AND
+     * the background pool. The round path does not touch the per-tool gate
+     * for background lifecycles (the thunk had not run yet), so the gate is
+     * acquired here for the body's lifetime — `maxConcurrency` bounds
+     * executions of the BODY, wherever they run.
+     *
+     * Acquisition order: per-tool gate FIRST, then the pool. The narrow gate
+     * is where a saturated tool's excess calls queue — queuing them on the
+     * shared pool instead would let 16 waiters on one maxConcurrency:2 tool
+     * hold every global slot while only two bodies run, starving every other
+     * background tool. Order is deadlock-safe: only background bodies take
+     * the per-tool gate (the round path skips it for them), and every body
+     * acquires in this same fixed order.
+     *
+     * Queue wait counts against the task's own timeout (tracked by the
+     * registry); an abort observed before the slots free up short-circuits
+     * without running the body.
+     */
+    private runBackgroundWork;
+    /** Broadcast a `tool.async_started` event on the turn broadcaster. */
+    private broadcastAsyncStarted;
+    /** Broadcast a `tool.async_settled` event on the turn broadcaster. */
+    private broadcastAsyncSettled;
+    /**
+     * Build the pending placeholder `function_call_output` for an async tool
+     * call. Pairs the `function_call` immediately (providers 400 on unpaired
+     * calls in follow-up history); the real result arrives later as a
+     * `tool_task_result` envelope. The note steers the model: with check-ins
+     * enabled it points at the universal `task` tool; with check-ins
+     * disabled it forbids re-calling entirely.
+     */
+    private buildPendingPlaceholder;
+    /**
+     * True when the built-in task tool is active for this run. Mirrors
+     * `needsTaskTool` exactly: when a user tool claims the reserved name the
+     * built-in is not registered, so calls named "task" must NOT be
+     * intercepted — they belong to the user's tool.
+     */
+    private taskToolActive;
+    /**
+     * Answer a call to the universal `task` tool: resolve the taskId to its
+     * live registry task (or persisted pendingAsyncTools entry, post-restart)
+     * and its OWNING tool, then dispatch by action:
+     *
+     * - `check` (default): the owning tool's `check.execute` when declared
+     *   (custom `params` validated against `check.schema`), else the SDK
+     *   default status / logs / transcript views.
+     * - `steer`: deliver `message` to the run body's inbox.
+     * - `result`: the final result if settled, else the status view.
+     * - `cancel`: cancel the task.
+     */
+    private answerTaskToolCall;
+    /** `task` tool, action=cancel. */
+    private taskToolCancel;
+    /** `task` tool, action=steer. Returns [result, error?] for `answer`. */
+    private taskToolSteer;
+    /**
+     * `task` tool, action=check (and the status-view fallback for `result`
+     * on an unsettled task): the owning tool's `check.execute` when
+     * declared, else the SDK default views — live-task-backed when the task
+     * is in this process, persisted-state-backed post-restart.
+     */
+    private taskToolCheck;
+    /** Build the narrow ToolTaskHandle façade for check.execute handlers. */
+    private buildTaskHandle;
     /**
      * Resolve async functions for the current turn.
      * Updates the resolved request with turn-specific parameter values.
@@ -439,6 +872,48 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * Uses streaming and pipes events through the turn broadcaster when available.
      */
     private makeFollowupRequest;
+    /**
+     * Append a response's output items to the accumulated request input,
+     * exactly as `makeFollowupRequest` does before adding tool results. Used
+     * by the end-of-run drain, where envelope messages must land AFTER the
+     * final assistant output in the request.
+     */
+    private accumulateResponseIntoInput;
+    /**
+     * End-of-run handling for async background tasks still in flight (or
+     * settled but unharvested) when the loop is about to finalize.
+     *
+     * - `'drain'` (default): wait for tasks (bounded by `drainTimeoutMs`),
+     *   inject their results, and give the model up to `maxDrainTurns` extra
+     *   `toolChoice: 'none'` turns so the final answer incorporates them.
+     * - `'detach'`: return immediately; still-working tasks are marked
+     *   `orphaned` on persisted state and their eventual results are dropped.
+     * - `'cancel'`: abort in-flight tasks and finish.
+     *
+     * @returns the (possibly replaced) final response.
+     */
+    private handleRunEndAsyncTasks;
+    /**
+     * Broadcast every unharvested settlement as dropped (no in-run delivery),
+     * mirror the terminal status onto persisted `pendingAsyncTools`, and
+     * append a terminal `tool_task_result` envelope to persisted history.
+     *
+     * The status mirror prevents a stuck resume: an entry persisted as
+     * `working` for a task that only ever settles in-memory (abortAll at
+     * drain exhaustion / run cancel) would pin a later cross-process resume
+     * to `awaiting_async_tools` forever. The envelope keeps the pending
+     * placeholder's "the result will be delivered" promise honest for
+     * PERSISTED conversations: the run is over (no more model dispatch), but
+     * the terminal outcome rides along on the next `callModel({ state })`
+     * instead of vanishing.
+     */
+    private dropSettledTasks;
+    /**
+     * `onRunEnd: 'detach'`: mark still-working tasks orphaned on persisted
+     * state (their eventual results are dropped) and drop unharvested
+     * settlements.
+     */
+    private detachWorkingTasks;
     /**
      * Make a final no-tool-calls request to coerce a text response after the
      * loop was halted by `stopWhen` mid-tool-call. Reuses the resolved request
@@ -453,6 +928,17 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
     /**
      * Validate the final response has required fields.
      *
+     * Message prefixes (`Invalid final response: missing required fields`,
+     * `Invalid final response: empty or invalid output`) are load-bearing —
+     * callers and tests match on them. Detail is appended after an em dash;
+     * never reword the prefixes.
+     *
+     * The detail exists because the bare "empty or invalid output" message was
+     * routinely misread as "the model returned a tool call and validation
+     * rejected it" (issue #45). It does not: this is a pure array-length check,
+     * so a `function_call`-only output passes. Naming the actual defect —
+     * empty array vs. wrong type — stops that misdiagnosis at the error string.
+     *
      * @param response - The response to validate
      * @param allowEmptyOutput - When true, tolerate an empty (but present) output array
      * @throws Error if response is missing required fields or has invalid output
@@ -471,6 +957,22 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * prefix intact.
      */
     private retryCurrentRequest;
+    /**
+     * Build the RequestOptions for one API dispatch, composing the run-level
+     * cancellation signal (`options.signal`) with the caller's RequestOptions.
+     *
+     * The SDK only auto-wires `timeoutMs` into an abort signal when NO signal
+     * is present on the options — a supplied signal silently disables the
+     * timeout. Composing here keeps both: each request is bounded by
+     * whichever of {run signal, caller signal, per-request timeout} fires
+     * first. MUST be called once per dispatch — `AbortSignal.timeout()`
+     * starts counting at creation, so a cached composite would burn its
+     * budget across turns instead of per request.
+     *
+     * Also the per-request fail-fast checkpoint: an already-aborted run
+     * signal throws its abort reason here, before any network I/O.
+     */
+    private dispatchRequestOptions;
     /**
      * Resolve async functions in the request for a given turn context.
      * Extracts non-function fields and resolves any async parameter functions.
@@ -479,6 +981,33 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * @returns The resolved request without async functions
      */
     private resolveRequestForContext;
+    /**
+     * Record the freshly-resolved caller choice before deriving its wire value.
+     * An unforced turn clears the consumed key, re-arming the same forced value
+     * if it appears again later. A different forced key re-arms immediately.
+     */
+    private applyResolvedForcedToolChoicePolicy;
+    /**
+     * Derive the caller-configured tool choice for the active logical run.
+     * Engine-owned one-turn overrides (`none` for finalization, or a pinned
+     * doom-loop advisor) are applied after this helper and therefore still win.
+     */
+    private applyForcedToolChoicePolicy;
+    /**
+     * Bind the prepared caller-policy transition to the actual wire request.
+     * Engine-owned overrides (for example a forced advisor consult) deliberately
+     * produce a different semantic key and therefore cannot commit caller state.
+     */
+    private beginToolChoiceDispatch;
+    /**
+     * Commit only after the prepared caller choice reached the wire and a
+     * response was materialized. A pause before dispatch leaves persisted state
+     * untouched; a forced choice is consumed only when that response called a
+     * tool.
+     */
+    private commitToolChoiceDispatch;
+    /** Clear all runtime and persisted policy state for a terminal run exit. */
+    private resetForcedToolChoicePolicy;
     /**
      * Apply `onResponseReceived` hooks to the freshly-supplied input items
      * only, without re-hooking historical items that live in
@@ -549,6 +1078,10 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * Get the complete response object including usage information.
      * This will consume the stream until completion and execute any tools.
      * Returns the full OpenResponsesResult with usage data (inputTokens, outputTokens, cachedTokens, etc.)
+     *
+     * Note: in a multi-round tool loop this is the **final** round's response
+     * only — its `usage` block covers that one generation, not the run. For
+     * aggregate totals across every model call, use `getUsage()`.
      */
     getResponse(): Promise<models.OpenResponsesResult>;
     /**
@@ -556,7 +1089,7 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * Multiple consumers can iterate over this stream concurrently.
      * Includes API events, tool events, and turn.start/turn.end delimiters.
      */
-    getFullResponsesStream(): AsyncIterableIterator<ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>>;
+    getFullResponsesStream(): AsyncIterableIterator<CorrelatedResponseStreamEvent<TTools>>;
     /**
      * Stream only text deltas as they arrive from all turns.
      * This filters the full event stream to only yield text content,
@@ -576,6 +1109,17 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * - file_search_call: File search operations
      * - image_generation_call: Image generation operations
      * - function_call_output: Results from executed tools
+     *
+     * This stream carries **output items only** — no usage or response-level
+     * metadata. The `response.completed` events (which hold each round's usage
+     * block) are not surfaced here, and `getResponse()` afterwards returns only
+     * the *final* round's response, so a multi-round tool loop's `tool_calls`
+     * generations are not accounted for by either. For usage, reach for:
+     * - `getUsage()` — aggregate token/cost totals across every round
+     * - the `PostModelCall` hook — one emit per model call, with
+     *   `turnType`/`turnNumber` and that call's own `usage`
+     * - `getFullResponsesStream()` — raw events including each round's
+     *   `response.completed`, and therefore its per-round usage block
      */
     getItemsStream(): AsyncIterableIterator<StreamableOutputItem<TTools>>;
     /**
@@ -620,7 +1164,7 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * - Tool call argument deltas as { type: "delta", content: string }
      * - Preliminary results as { type: "preliminary_result", toolCallId, result }
      */
-    getToolStream(): AsyncIterableIterator<ToolStreamEvent<InferToolEventsUnion<TTools>>>;
+    getToolStream(): AsyncIterableIterator<CorrelatedToolStreamEvent<TTools>>;
     /**
      * Get all tool calls from the completed response (before auto-execution).
      * Note: If tools have execute functions, they will be automatically executed
@@ -647,16 +1191,66 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      */
     getContextUpdates(): AsyncGenerator<ToolContextMapWithShared<TTools, TShared>>;
     /**
-     * Cancel the underlying stream and all consumers
+     * Cancel the underlying stream and all consumers, and abort in-flight
+     * tool executions and background tasks (their `ctx.signal` fires).
+     *
+     * Note: prior releases only cancelled the stream; aborting tool work is
+     * new with async tool support.
      */
     cancel(): Promise<void>;
+    /**
+     * Snapshot of every async tool task tracked by this run (background and
+     * deferred), including settled ones.
+     */
+    getAsyncTasks(): PendingAsyncTool[];
+    /**
+     * Cancel one in-process async task by its task id. Background tasks abort
+     * their `ctx.signal`; the model receives a `status: 'cancelled'` envelope
+     * at the next delivery point so it is not left waiting forever.
+     *
+     * For deferred tasks in a paused (possibly other-process) conversation,
+     * use the deferred tool's `.cancel()` method instead.
+     *
+     * @returns true when a working task was found and cancelled.
+     */
+    cancelTask(taskId: string, reason?: string): boolean;
+    /**
+     * Send a steering message to a running in-process task. Delivered to the
+     * run body's `ctx.onMessage` handler (queued until one registers). Agent
+     * tools (`tool.agent()`) auto-forward messages into the child
+     * conversation as user messages at the child's next turn boundary.
+     *
+     * Throws for deferred tasks — their work runs in an external system;
+     * steer it there.
+     *
+     * @returns true when a working task received (or queued) the message.
+     */
+    sendToTask(taskId: string, message: unknown): boolean;
+    /**
+     * Queue a user-role message for injection into this run's conversation at
+     * the next safe turn boundary (the same mechanism doom-loop steer
+     * guidance uses — never between a dangling `function_call` and its
+     * output). The primary consumer is `tool.agent()`, which forwards
+     * steering messages into child conversations through this.
+     *
+     * Delivery requires a next dispatch: boundaries are post-tool-round
+     * follow-ups, pause-persists, and end-of-run drain turns. A message
+     * queued while the run is composing its FINAL text response (no further
+     * dispatch of any kind) has no boundary left and is not delivered —
+     * steer while the run still has work in flight.
+     */
+    queueUserMessage(text: string): void;
     /**
      * Check if the conversation requires human/client input to continue.
-     * Returns true when the conversation is paused waiting for caller-supplied
-     * decisions — approval/rejection (`awaiting_approval`), HITL tool resume
-     * (`awaiting_hitl`), or client-executed manual tools (`awaiting_client_tools`).
-     * Also returns true whenever `pendingToolCalls` is populated regardless of
-     * status.
+     * Returns true when the conversation is paused waiting on the CALLER —
+     * approval/rejection (`awaiting_approval`), HITL tool resume
+     * (`awaiting_hitl`), client-executed manual tools
+     * (`awaiting_client_tools`), or an external async task resolution
+     * (`awaiting_async_tools`, cleared via the deferred tool's `.resolve()` /
+     * `.fail()` / `.cancel()` or `resumeToolResults()` — NOT via
+     * `approveToolCalls`). Also returns true whenever `pendingToolCalls` is
+     * populated regardless of status. To branch on the pause KIND, read
+     * `(await getState()).status` instead.
      */
     requiresApproval(): Promise<boolean>;
     /**
@@ -671,5 +1265,47 @@ export declare class ModelResult<TTools extends readonly Tool[], TShared extends
      * To resume a conversation, use the StateAccessor pattern.
      */
     getState(): Promise<ConversationState<TTools>>;
+    /**
+     * The doom-loop verdict that stopped this run, or null when the run was
+     * not stopped by doom-loop detection (including when detection is off).
+     * Resolves after the tool loop settles. For per-event observation use the
+     * `DoomLoopDetected` hook.
+     */
+    getDoomLoopVerdict(): Promise<DoomLoopVerdict | null>;
+    /**
+     * Aggregate token/cost usage across **every** model call this run made —
+     * the initial request, each tool-round follow-up, the empty-final retry,
+     * the `allowFinalResponse` final turn, and approval-resume requests.
+     *
+     * This is the pull-based counterpart to the `SessionEnd.totalUsage` hook
+     * payload (same `SessionUsageTotals` shape, same numbers) and exists
+     * because `getResponse()` returns only the **final** round's response: in a
+     * multi-round tool loop the `tool_calls` generations' tokens are otherwise
+     * unreachable, and `getItemsStream()` carries output items only — no
+     * `response.completed` usage block.
+     *
+     * Gates on run completion the same way `getResponse()` does, so totals are
+     * final whether you await it directly, after `getResponse()`, or after
+     * consuming any of the streaming getters — except on an approval-resumed
+     * run, where reading usage never advances the tool loop: the resume
+     * request's own generation is awaited and counted, but no further rounds
+     * are driven, so totals can be mid-run. Await `getResponse()`/`getText()`
+     * first for final totals there. On a run that paused (approval / HITL) or
+     * failed, it returns the totals accrued so far — `modelCalls: 0` with
+     * zeroed tokens when no model call ever completed.
+     *
+     * Unlike `getResponse()`, this never rejects: a failed run still consumed
+     * tokens, and cost accounting typically runs in a `finally`/`catch` where a
+     * second throw would mask the run's original error. Await the run itself
+     * (e.g. `getResponse()`) if you need to observe the failure.
+     *
+     * `cost` is present only when the server reported cost accounting for at
+     * least one call; a `0` would be indistinguishable from "free".
+     *
+     * For per-call granularity use the `PostModelCall` hook (one emit per model
+     * call, with `turnType`/`turnNumber`) or `getFullResponsesStream()`, whose
+     * `response.completed` events carry each round's own usage block.
+     */
+    getUsage(): Promise<SessionUsageTotals>;
 }
 //# sourceMappingURL=model-result.d.ts.map