chore: version packages

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@openrouter/mcp@1.0.0

Major Changes

• #86 53d71cc Thanks @LukasParke! - Support both MCP protocol revisions. Any server now works out of the box, whether it
  speaks 2025-11-25 or 2026-07-28.

  Migrates from @modelcontextprotocol/sdk@^1.29.0 to @modelcontextprotocol/client@^2.0.0
  and adds protocolNegotiation?: 'legacy' | 'auto' | { pin: string }, defaulting to
  'auto'. Under 'auto' the client probes with server/discover and then speaks whichever
  revision the server offers — the per-request _meta envelope for 2026-07-28, or the
  classic initialize handshake for 2025-11-25 and earlier.

  Breaking: Node 20+ is required — @modelcontextprotocol/client@2.0.0 declares
  engines.node: >=20, and this package now declares the same so Node 18/19 consumers get an
  install-time warning instead of a runtime failure.

  Breaking: if you pass auth: { kind: 'oauth', provider }, your provider must satisfy
  @modelcontextprotocol/client@2.0.0's OAuthClientProvider — change the import specifier,
  and note tokens() now returns StoredOAuthTokens (same fields, so most providers compile
  unchanged). Type it with the newly exported MCPOAuthClientProvider to avoid depending on
  that path again.

  protocolNegotiation defaults to 'auto', where the SDK defaults to 'legacy', so every
  connection's first request is a server/discover probe. This is not a connectivity
  break: when you have not set protocolNegotiation yourself, a failed connect is retried
  once with 'legacy', so a proxy, WAF, or gateway that hangs or 5xx's on an unknown method
  still connects exactly as it did before. Modern servers get 2026-07-28, everything else
  lands where it always did.

  The server/discover probe is bounded at 30s (probeTimeoutMs to change it). The SDK
  otherwise gives the probe the full 60s request timeout, which under 'auto' — where the probe
  is the first request of every connection — would mean minutes of hang against a gateway that
  black-holes requests. It is not tighter than that on purpose: on HTTP a probe timeout is
  classified as an outage and the legacy retry sends an initialize that revision 2026-07-28
  removed, so a modern-only server slower than the ceiling would fail to connect rather than
  merely take longer. Serverless cold starts make an aggressive value a correctness problem.

  The cost lands only on already-failing connects: the retry re-walks the same transport ladder
  under 'legacy', so a genuinely unreachable server is dialled up to four times rather than
  two. The retry deliberately does not pin one transport — a legacy server reachable only
  over SSE, behind probe-hostile infrastructure, needs SSE offered again under 'legacy' or it
  stops connecting entirely, which is the regression this mechanism exists to prevent.

  The retry is skipped on an auth failure — the SDK's UnauthorizedError, or (when an OAuth
  provider is configured) a 401 status from the probe, which the SDK reports as an
  SdkHttpError instead of routing through the OAuth flow. A 403 always degrades, even
  under OAuth: the SDK's PKCE side effects live exclusively behind its 401 branch, so a 403
  retry re-drives nothing — while gateways commonly answer unknown methods with 403, which is
  the very scenario the retry exists to rescue. Auth failures are recognised whether they came
  from the last attempt or an earlier one. Rejected credentials are not something a different protocol revision fixes, and re-running
  the attempt would drive an OAuth provider's authorization flow a second time and overwrite the
  stored PKCE verifier.

  connect-level calls accept a signal that aborts the whole ladder — every transport
  attempt, the probe, and the implicit legacy retry — so a caller with its own deadline can
  bound the worst case (~3 minutes against a black-holing gateway on the default path). An
  aborted connect is never retried. Snapshot replays also no longer perform the construction
  write-back: the snapshot it would write is the one just read, so it was a store round-trip
  per rehydrate buying nothing. Three maintenance writes survive, all best-effort: an OAuth
  provider under cacheCredentials: true re-persists its current tokens (so the stored entry
  tracks rotation instead of expiring into a forced fresh connect), a rotated static credential
  (bearer/headers auth passed by the caller under cacheCredentials: true) updates the
  stored header block the same way, and an entry carrying a
  legacy sessionId from an earlier version is rewritten once without it. Every maintenance write reads the
  store first and only ever rewrites an entry it already holds: the rotation writes graft the
  credential block onto the stored entry (never the caller's possibly-older input snapshot, which could
  roll back a newer entry written by a concurrent refresh()), skip entirely when the stored
  entry never held that credential block, and write nothing at all when the credential is
  unchanged — an unrotated OAuth token in particular is never re-persisted, which would ratchet
  its recorded expiry forward (expires_in is relative to issuance) and could drop stored
  fields the provider no longer reports — expires_in is relative to issuance, so restamping it per replay would
  push the recorded expiry forward forever. No maintenance write can introduce credentials into a
  store that lacked them. If your store implementation extends entry TTLs on write
  (Redis SETEX-style), note that warm hits no longer touch the store, so such entries now
  expire on their own schedule rather than being kept alive by access; size the TTL to the
  staleness window you actually want.

  MCPConnectionError now carries every underlying failure in errors (matching
  AggregateError), flat and in attempt order across both negotiation passes, so a caller sees
  all of them rather than only the last — which is all cause holds.

  An explicit protocolNegotiation is honoured exactly, including 'auto' — asking for a
  mode means asking for its failures too, and silently overriding a { pin } would defeat the
  point of pinning. Pass 'legacy' to skip the probe entirely.

  import { createMCPTools, type MCPOAuthClientProvider } from "@openrouter/mcp";
  
  // Default: probes with `server/discover`, then speaks whichever revision the
  // server offers. If the probe fails — a gateway that rejects unknown methods —
  // this retries once with the classic `initialize` handshake, so a server that
  // worked before still connects.
  const mcp = await createMCPTools({ url: "https://mcp.example.com/mcp" });
  
  // Skip the probe entirely. Saves the extra round trip if you already know the
  // server is 2025-era. Not required for compatibility — the default degrades on
  // its own.
  const legacy = await createMCPTools({
    url: "https://mcp.example.com/mcp",
    protocolNegotiation: "legacy",
  });
  
  // Explicit modes are honoured exactly — this one fails rather than degrading.
  const strict = await createMCPTools({
    url: "https://mcp.example.com/mcp",
    protocolNegotiation: "auto",
  });
  
  // Or pin one revision explicitly.
  const pinned = await createMCPTools({
    url: "https://mcp.example.com/mcp",
    protocolNegotiation: { pin: "2026-07-28" },
  });
  
  // OAuth providers: type against the new export rather than the SDK path.
  const provider: MCPOAuthClientProvider = myProvider;
  await createMCPTools({
    url: "https://mcp.example.com/mcp",
    auth: { kind: "oauth", provider },
  });

  Cache writes are best-effort, the probe is tunable, and multi-attempt failures carry every
  underlying error:

  import { createMCPTools, MCPCacheWriteError } from "@openrouter/mcp";
  
  // New option: ceiling on the `server/discover` probe (default 30s). Raise for a
  // server slow to answer its first request; lower to fail fast on infrastructure
  // you control.
  const mcp = await createMCPTools({
    url: "https://mcp.example.com/mcp",
    probeTimeoutMs: 60_000,
  });
  
  // New export: a store outage no longer fails the call — the handle stays usable
  // and only the cache entry is stale. Catch it from refresh() to treat a write
  // failure as fatal anyway.
  try {
    await mcp.refresh();
  } catch (err) {
    if (err instanceof MCPCacheWriteError) {
      // Tools were re-read successfully; only persisting the snapshot failed.
      metrics.increment("mcp.cache_write_failed");
    } else {
      throw err;
    }
  }

  When more than one transport was tried, MCPConnectionError carries every underlying failure
  on errors — cause still holds the last one, which on its own hides an auth rejection from
  an earlier attempt:

  import { createMCPTools, MCPConnectionError } from "@openrouter/mcp";
  
  try {
    await createMCPTools({ url: "https://mcp.example.com/mcp" });
  } catch (err) {
    if (err instanceof MCPConnectionError) {
      console.error("last attempt:", err.cause);
      // Every attempt's failure, flat and in order — a single-attempt failure
      // contributes its one underlying error, so this is never empty.
      for (const attempt of err.errors) {
        console.error("attempt:", attempt);
      }
    }
    throw err;
  }

  Rehydrating a snapshot now enforces staleness.maxAgeMs on every path, including
  reconnectOnExpiry: false. If the re-list that would refresh an over-age snapshot fails,
  the call rejects rather than quietly serving tools you declared too old — catch
  MCPStaleSnapshotError to opt back into stale-but-usable tools:

  import {
    rehydrateMCPTools,
    MCPStaleSnapshotError,
    type MCPProtocolRevision,
  } from "@openrouter/mcp";
  
  async function load(snapshot: SerializedMCPServer) {
    try {
      // Over-age snapshots re-list over the replayed connection. New: this holds
      // under `reconnectOnExpiry: false` too, where it previously replayed silently.
      return await rehydrateMCPTools({
        snapshot,
        staleness: { maxAgeMs: 60_000 },
        reconnectOnExpiry: false,
      });
    } catch (err) {
      if (err instanceof MCPStaleSnapshotError) {
        // The connection is fine; only the re-list failed. Accept the cached
        // tool set rather than failing the request.
        return await rehydrateMCPTools({ snapshot, reconnectOnExpiry: false });
      }
      throw err;
    }
  }
  
  // The two known revisions autocomplete and typo-check; any other string still
  // compiles, so pinning a future revision needs no cast.
  const revision: MCPProtocolRevision = "2026-07-28";
  await createMCPTools({
    url: "https://mcp.example.com/mcp",
    protocolNegotiation: { pin: revision },
  });

  Also in this release:

  • Fixes a silent bug in the callTool bridge: SDK v2 dropped the middle argument, so the
    old call shape would have put signal and onprogress in an unread slot, disabling
    cancellation and progress streaming.
  • Corrects the self-reported clientInfo version, which said 0.1.0 while the package was
    0.0.1, and now generates it from package.json so it cannot drift.
  • staleness.maxAgeMs is now honoured by rehydrateMCPTools() too, not just by
    createMCPTools()'s cache-hit path — a direct rehydrate previously replayed snapshots of
    any age. This holds under reconnectOnExpiry: false as well: a stale snapshot re-lists
    over the replayed connection rather than being served as-is, since "stale" means the tool
    set needs re-reading, not that the transport needs rebuilding. If that re-list fails, the
    call rejects with the new MCPStaleSnapshotError rather than quietly serving tools the
    caller declared too old — catch it specifically to opt into stale-but-usable tools. It
    subclasses MCPCacheError, so existing catch sites are unaffected.
  • onElicitation is no longer deprecated: it works on both revisions, since the
    multi-round-trip driver routes input_required through the same handler.
  • Your MCPCacheStore failing no longer fails the call, on either side. Writes are
    best-effort: a store outage previously discarded a live connection whose tools had been
    read successfully, and broke the documented stale-snapshot recovery, which writes through
    the same store. Reads are a miss: a failing store.get falls through to a fresh connect,
    exactly as an empty cache would. handle.refresh() reports a write failure as the new
    MCPCacheWriteError (a subclass of MCPCacheError) for callers who do want to treat it
    as fatal, and onToolsChanged subscribers are still notified whenever the re-list itself
    succeeded, whatever failed afterwards (a store write, or the OAuth provider rejecting
    while the snapshot was being built) — the
    tools were re-read successfully, and skipping the announcement would leave subscribers
    permanently out of sync with handle.tools.
  • An auth failure no longer falls through the transport ladder. A 401 on Streamable HTTP used
    to try SSE with the same authProvider, re-entering the SDK's auth path for a second
    redirectToAuthorization and overwriting the saved PKCE verifier — the same duplicated side
    effect the negotiation retry already guarded against, one layer down.
  • handle.refresh() genuinely re-reads the tool list again. SDK v2 added a per-client
    response cache honouring the server's ttlMs on tools/list (up to 24h), so a refresh
    inside that window would have returned the cached list — an app calling refresh() to
    pick up new server tools could have kept the old set. Every internal tools/list now
    sends cacheMode: 'refresh', as does list_resources — a listing's job is to report what
    exists now, and a cached one reads to the model like its write silently failed.
    read_resource deliberately still honours the server's TTL: contents can be large, and
    the SDK already evicts per-URI on notifications/resources/updated.
  • rehydrateMCPTools() no longer replays a snapshot's sessionId. With one present, SDK v2
    skips negotiation entirely and leaves server capabilities and version undefined without
    erroring — so the replayed handle would silently lose its resource tools. Sessions are
    removed in 2026-07-28 anyway (SEP-2567), so the replay does a fresh handshake.
  • Snapshots no longer persist sessionId at all. A Streamable HTTP Mcp-Session-Id is
    bearer-equivalent to an authenticated server session, and with the replay path no longer
    reading it, writing it to a cache store was attack surface for no functionality. The field
    stays on the snapshot type so existing cache entries keep deserializing; treat any value
    found there as untrusted legacy data.
  • A failed connect() no longer leaks its transport. The SDK does not close a transport
    whose start() threw, so a rejected connection left an open keep-alive socket — most
    visibly on the new probe-failure path, where a strict gateway leaked one per attempt.
  • The 'auto' probe applies to SSE as well, including a pinned transport: 'sse' and the
    Streamable HTTP → SSE fallback, since all three share one client factory. The legacy retry
    covers each of them, so pinning SSE for a legacy server still connects.
  • protocolNegotiation: { pin } now autocompletes and typo-checks the two known revisions
    ('2025-11-25', '2026-07-28') while still accepting any other string, so pinning a
    future revision compiles without a cast. The revision union is exported as
    MCPProtocolRevision.
  • New test coverage for both protocol eras over InMemoryTransport, for the
    Streamable HTTP → SSE fallback, for tools/list_changed dispatch end to end, and for the
    clientInfo we self-report.

Minor Changes

• #74 f412281 Thanks @LukasParke! - Doom-loop loopKey support for MCP-wrapped tools (pairs with @openrouter/agent's doomLoop option).

  Two ways to declare a wrapped tool's call identity: a client-side loopKeys map on createMCPTools/rehydrateMCPTools (keyed by unprefixed MCP tool name; any ToolLoopKey form — function, field-name array, or false to exempt), and a server-advertised _meta['openrouter/loopKey'] on the tool definition (data-only: field-name array or false). Client config takes precedence. Server-advertised declarations ride the cache snapshot (SerializedMCPToolDef.loopKey), so rehydrated tool sets keep their identities without a listTools() round-trip; function forms are client-side only and cannot be cached.

  import { createMCPTools } from "@openrouter/mcp";
  
  const mcp = await createMCPTools({
    url: "https://mcp.example.com/mcp",
    // Keyed by the UNPREFIXED MCP tool name, even when toolNamePrefix is set.
    // Any ToolLoopKey form: a field-name array, `false` to exempt, or a
    // function computing key material (client-side only — not cacheable).
    loopKeys: {
      run_command: ["command", "cwd"],
      poll_job: false,
    },
    cache: { store },
  });
  
  const result = client.callModel({
    model: "z-ai/glm-5.2",
    input: "Get the build passing.",
    tools: mcp.tools,
    doomLoop: true,
  });

  A server can advertise the same thing itself via
  _meta['openrouter/loopKey'] on the tool definition (data-only: a field-name
  array or false). Client loopKeys win over a server declaration, and
  server-advertised values survive a cache round-trip via
  SerializedMCPToolDef.loopKey.

Patch Changes

• #86 53d71cc Thanks @LukasParke! - Generate the clientInfo version from package.json instead of hardcoding it. build
  regenerates src/version.ts, and a unit test fails if the committed value drifts, so the
  version reported to MCP servers cannot go stale across a release.
• Updated dependencies [e8d7d6d, 78c562e, 78c562e, 75271c3, 5a7ed03, a629cf1, 78c562e, 3028554, 231fb65, 0efdbb0]:
  • @openrouter/agent@0.9.0

@openrouter/agent@0.9.0

Minor Changes

• #90 e8d7d6d Thanks @LukasParke! - Async tool support: a unified run() tool interface with lifecycles, model-side task check-ins, steering, subagent tools (tool.agent()), per-tool cancellation & timeouts, and tool concurrency controls.

  One tool interface. Every tool is declared the same way: a run handler (async function or async generator) plus lifecycle: 'sync' (default) | 'background' | 'deferred'. Generator yields become the task's log (feeding check-ins, tool.preliminary_result events, and transcripts); the generator's return is the result, validated against outputSchema. Non-generator bodies log via ctx.log(). The released execute / execute: false / onToolCalled forms are unchanged.

  • 'background' — the loop keeps going. Work settling within the grace window (graceMs, default 250ms) behaves like a sync call; otherwise the model receives a pending placeholder immediately (satisfying the provider requirement that every function_call in follow-up history has a paired output) and the result is injected as a tool_task_result user message when it settles. asyncTools.onRunEnd: 'drain' (default) | 'detach' | 'cancel' governs run end.
  • 'deferred' — run returns ctx.defer(taskId) to park the call on durable external work; the run pauses with the new ConversationStatus 'awaiting_async_tools'. The built tool carries typed .resolve() / .fail() / .cancel() completion methods (output checked against outputSchema at compile time and runtime), callable from any process holding the StateAccessor; resumeToolResults() is the low-level batch entry point. Double resolution throws ToolTaskAlreadySettledError.

  Model-side task interactions. When any long-running tool is registered, the SDK appends ONE universal task tool — a single static wire definition no matter how many async tools exist (per-tool schemas are never augmented; context cost stays constant). The model addresses tasks by taskId: action: 'check' (default) | 'steer' | 'result' | 'cancel', with view: 'status' | 'logs' | 'transcript' for checks. Calls are engine-intercepted and dispatched to the OWNING tool's check: { schema, execute } config when declared (custom params validated against check.schema), else the SDK default views — universal interface, tool-specific handling. Check handlers receive turnContext.toolCallStatus, turnContext.accumulatedYieldedEvents, and a turnContext.task handle (statusView / tailLogs / transcript / send / cancel). Task-tool calls are doom-loop-exempt and bypass concurrency/timeout gates. Opt out with asyncTools: { checkins: false }. After a process restart, deferred tasks answer status from persisted state (including a bounded lastLog — a new additive PendingAsyncTool field).

  Steering. Running tasks have an inbox: run bodies opt in via ctx.onMessage(handler); deliver from code with ModelResult.sendToTask(taskId, message) or from the model via a custom check param forwarded with turnContext.task.send(...). New ModelResult.queueUserMessage(text) injects a user message at the next safe turn boundary.

  Subagent tools. tool.agent() creates a tool whose work IS a child callModel conversation, running as a background task: the parent loop keeps going, each child turn becomes a log entry, the child conversation is the check-in transcript (status adds turnsCompleted / currentActivity), the result mapper (default: { text: await child.getText() }) shapes the delivered output, cancelTask / parent abort / timeoutMs cancel the child, and steering messages are injected into the child as user messages. Children run in-memory and do not inherit parent hooks (pass child hooks in the agent spec explicitly).

  Cancellation & timeouts. Tool contexts carry ctx.signal (fires on run abort, per-tool timeoutMs / run-level toolTimeoutMs, cancelTask, ModelResult.cancel()), plus ctx.callId / ctx.conversationId. Timeouts bound the round's wait, not the tool body ({ error, code: 'tool_timeout' }). Behavior change: ModelResult.cancel() now also aborts in-flight tool work (previously stream-only).

  Concurrency. toolConcurrency: number | { round?, background? } (round unbounded by default; background pool default 16) plus per-tool maxConcurrency. Output order stays call order.

  Events. New tool.async_started / tool.async_settled (with delivery: 'injected' | 'pending_resume' | 'dropped'); progress reuses tool.preliminary_result; tool.result fires exactly once per call with the final value. ModelResult.getAsyncTasks() inspects live tasks. Doom-loop detection treats a late-result delivery as forward progress.

  State fields (pendingAsyncTools with lastLog, settledAsyncCallIds) are additive within ConversationState version 1. New subpath exports: resume-tool-results, tool-concurrency, async-tool-registry, tool-task, tool-check, agent-tool. The reserved tool name task is rejected by tool() and, when supplied dynamically, suppresses the built-in with a warning.

  Note: tool.background() and tool.deferred() existed only on this PR's branch and were never published; they are replaced by lifecycle. No released consumer is affected.

  API example

  import { callModel, tool } from "@openrouter/agent";
  import { z } from "zod";
  
  // Background: ordinary run; the loop keeps going while it works.
  const renderVideo = tool({
    name: "render_video",
    lifecycle: "background",
    inputSchema: z.object({ script: z.string() }),
    outputSchema: z.object({ url: z.string() }),
    ack: "Rendering started.",
    timeoutMs: 300_000,
    check: {
      schema: z.object({ focus: z.string().optional() }), // validates task({ params })
      execute: async (params, turnContext) => {
        if (params.focus) turnContext.task?.send(params.focus);
        return turnContext.task?.statusView();
      },
    },
    run: async function* ({ script }, ctx) {
      const job = await renderer.start(script, { signal: ctx?.signal });
      ctx?.onMessage((msg) => job.reprioritize(msg));
      for await (const p of job.progress()) yield { pct: p }; // → task log + events
      return job.result(); // → delivered result
    },
  });
  
  // Deferred: durable external work, resumed from any process.
  const legalReview = tool({
    name: "request_legal_review",
    lifecycle: "deferred",
    inputSchema: z.object({ contractId: z.string() }),
    outputSchema: z.object({ approved: z.boolean() }),
    run: async ({ contractId }, ctx) =>
      ctx!.defer(
        (await legal.open(contractId, { conversationId: ctx?.conversationId }))
          .id
      ),
  });
  
  // Subagent: a child conversation as a background tool.
  const researcher = tool.agent({
    name: "research_topic",
    inputSchema: z.object({ topic: z.string() }),
    outputSchema: z.object({ text: z.string() }),
    agent: ({ topic }) => ({
      model: "openai/gpt-4o",
      input: `Research: ${topic}`,
      tools: [searchTool] as const,
    }),
  });
  
  const result = callModel(client, {
    model: "openai/gpt-4o",
    input: "Render the explainer, get it approved, and research the market",
    tools: [renderVideo, legalReview, researcher] as const,
    state,
    toolConcurrency: { round: 4 },
  });
  
  // The model interacts with running tasks through ONE universal tool:
  //   task({ taskId: "task_7f3" })                          → status view
  //   task({ taskId, view: "logs", tail: 5 })               → recent progress
  //   task({ taskId, view: "transcript" })                  → agent child conversation
  //   task({ taskId, action: "steer", message: "shorter" }) → steers the job
  //   task({ taskId, action: "cancel" })                    → stops it
  
  // Developer-side observability & control:
  result.getAsyncTasks();
  result.sendToTask(taskId, "prioritize accuracy");
  result.cancelTask(taskId);
  
  // Webhook handler — different process, days later. Typed by outputSchema.
  await legalReview.resolve(client, {
    state: makeAccessor(conversationId),
    taskId: ticketId,
    output: { approved: true },
    run: { model: "openai/gpt-4o" },
  });

• #73 78c562e Thanks @LukasParke! - Doom-loop detection for the tool-execution loop (opt-in via doomLoop on callModel).

  Catches runs that stop making progress while continuing to spend: the model re-issuing the same tool call with identical arguments in consecutive rounds (including repeated empty {} calls and repeated invalid-JSON calls), repeating identical server-tool requests (web_search_call etc., detected post-execution at the step checkpoint), or emitting the same text tokens over and over. Detection is deterministic — a verdict is a pure function of the transcript — and responds through a configurable graduated ladder: observe (emit the new DoomLoopDetected hook) → steer (inject corrective guidance; queued guidance persists across pauses) → block (refuse the call with an explanatory tool error, before execution) → stop (halt before any further model request; unresolved calls in the final turn get synthesized halt-error outputs so persisted history stays well-formed; SessionEnd.reason: 'doom_loop').

  Streaks are round-scoped: N identical calls fanned out in parallel within one round count once (a streak measures the model re-issuing a call after seeing its result). Tools declare call identity via loopKey on the tool definition — a computed function over the call's validated arguments (e.g. ({ command, cwd }) => ({ command, cwd }); returning null exempts a call), or false (statically exempt); absent means the full validated arguments. MCP-wrapped tools accept loopKey via markMcp(tool, { loopKey }). Fingerprints are a cross-port contract: RFC 8785 (JCS) canonicalization + SHA-256 over UTF-8 via WebCrypto, with conformance vectors in tests/vectors/doom-loop-fingerprints.json for the Python/Go ports. Unhashable key material (bigint, circular, >64 deep) falls back to the full-arguments identity — detection never fails a run.

  Detector state persists inside ConversationState.doomLoop: streaks survive serialize → resume, a stop verdict survives decision-only resumes (approve/reject) and clears on a fresh conversational turn, and queued steer guidance is delivered on resume. Ladder configs warn on dead rungs and on block with stop: false (unbounded block/re-issue). Documented, test-locked limits: varying-input (nonce) loops evade the default identity without a loopKey; paraphrased text repetition is not detected; manual/client-executed calls are not recorded. New @openrouter/agent/doom-loop subpath exports the primitives; ModelResult.getDoomLoopVerdict() reports a stopping verdict.

• #73 78c562e Thanks @LukasParke! - Doom-loop escalation recovery: a new escalate ladder rung between steer and block that unblocks a stuck run by throwing more intelligence at the next turn instead of refusing or halting.

  Configure via doomLoop.escalation: model runs the NEXT turn on a stronger model (one-turn override, automatic revert), and/or advisor forces an openrouter:advisor consult (the advisor server tool is appended with forwardTranscript: true and loop-diagnosing instructions, and toolChoice is pinned to it via allowed_tools/required so the stuck model must ask for guidance first; an object form passes through as advisor parameters). A user notice naming the detected loop accompanies the escalated turn.

  Escalations are real spend on a run already suspected of wasting it, so they are budgeted: maxEscalations (default 2) caps recoveries per conversation, budget is consumed when a recovery is applied (not at verdict time), escalationsUsed persists in ConversationState.doomLoop so resumes cannot reset it, and concurrent detector verdicts in one window escalate once. Exhausted or unconfigured escalations fall through to the weaker rungs; resolve-time warnings flag an escalate rung without a mechanism (and vice versa). The DoomLoopDetected hook's action/overrideAction enums gain 'escalate' — an override without config/budget downgrades to observe, never silently to a stronger action.

• #89 75271c3 Thanks @LukasParke! - Fix doom-loop detection missing a repeated same-tool fan-out.

  Streaks compared a tool's last fingerprint, so read(a), read(b), read(c)
  reissued verbatim had a different last call every round and each round's first
  call reset the streak to 1. Eight identical rounds of a three-call fan-out
  produced zero detections, while single-call rounds tripped at round 2 — and
  distinct-argument fan-out is the dominant shape in parallel-tool-calling agents.

  A round's identity for one tool is now the set of fingerprints it was called
  with, compared across rounds. The engine declares a round's complete set before
  any of its calls is scored, so ordering within the round does not matter, a
  changed member resets the streak, and neither a strict subset nor a superset is
  a repeat — a round that adds new work is progress, not repetition. Every call in
  a repeating round reports that round's streak, so at the block rung a repeating
  fan-out stops spending rather than only its last call being refused.

  Per-call streaks accumulate alongside the round-set streak, and the
  stronger evidence decides. Each (tool, arguments) identity counts its own
  consecutive rounds, whatever its round-mates did — so a call repeating inside
  varying company ([a,b], [a,c], [a,d]: a is a 3-peat) is flagged even
  though every round's set differs, a repeat keeps counting when a paused HITL
  member drops from the resumed round, and undeclared paths (server-tool records,
  direct callers) get order-independent per-call detection without a declaration.
  When the per-call count alone crosses a rung, only that call is refused and its
  verdict quotes its own identity; genuinely new round-mates run free. For an
  exactly-repeating round both counts are equal, so nothing double-fires. A
  partial repeat ([a,b,c] then [a,b]) flags the re-issued calls at the
  observe rung rather than being invisible; a superset round ([a,b], [a,b],
  [a,b,c]) flags the repeated members while the new call always executes.

  A call that a round's declaration could not include (unhashable key material)
  cannot inherit or move the round's counters; its own verbatim repetition still
  accumulates per-call evidence like any other repeat.

  Resumed runs: a multi-call round's fingerprint set and per-call counts are
  persisted alongside its streak (new optional roundFingerprints and
  callStreaks on DoomLoopStreak — additive; pre-existing blobs restore with
  their old single-call semantics). A repeating
  fan-out therefore keeps its evidence across save/resume boundaries: approval
  pauses no longer reset a fan-out sitting at the block rung, and per-turn-resume
  topologies (one callModel per user turn, state persisted between) accumulate
  across turns instead of re-baselining on every one. Because the streak travels
  with the exact set that earned it, a resumed round containing only a subset of
  that set is a different round and starts at 1 — a lesser call can never inherit
  a fan-out's evidence. Single-call streaks behave exactly as before.

  New API: DoomLoopMonitor.declareRound(round, calls) — declares a round's
  complete call set before any of it is scored. DoomLoopMonitor is exported, so
  this is a new public method, additive only. Callers using callModel need not
  touch it (the engine calls it); direct DoomLoopMonitor users and SDK ports
  should, so a repeating fan-out is flagged as one unit (shared verdict, shared
  steer message) rather than only via each member's individual per-call count.

  Single-call round timing, in-round duplicate collapsing, verdict payloads, and
  the number of times a tool's loopKey is invoked (once per checked call) are
  unchanged. The persisted shape gains two optional fields (roundFingerprints
  and callStreaks, both above); everything existing is untouched and old blobs
  restore cleanly with their old semantics.

  Newly reachable false positive. The detector compares arguments, not
  results, so repetition shapes that were previously invisible now accumulate and
  are refused at the default block rung from round 3. Two variants:

  • A stable set of parallel arguments every round — an agent re-reading the
    same context files each turn, or a fixed fan-out of pollers — blocks with one
    synthesized error per call in the round.
  • A single call re-issued verbatim while its round-mates CHANGE — re-reading an
    anchor file (README, config, schema) while exploring new files each turn
    ([a], [a,b], [a,b,c]: a blocks from round 3 even though every round
    adds work). The per-call detector counts the call's own consecutive rounds,
    so the round being "progress" does not exempt a member that itself repeats:
    a file already read is in context, and re-reading it is spend without
    progress.

  Exempt such tools with loopKey: false (or a loopKey returning null for
  the call). These classes were invisible to the detector before, so no existing
  exemption covered them; the graduated ladder gives every shape a free round and
  an observe warning before anything is refused.

  For callModel users, nothing to change — doomLoop is configured exactly as
  before, and the engine declares each round for you. What changed is when it
  fires:

  import { callModel } from "@openrouter/agent";
  
  const result = callModel(client, {
    model: "z-ai/glm-5.2",
    input: "Summarize these files.",
    tools: [readTool],
    // Unchanged config; the ladder default is observe@2, block@3, stop@6.
    doomLoop: true,
  });
  
  // Say the model reissues the SAME three-call fan-out every round:
  //   round 1: read(a), read(b), read(c)
  //   round 2: read(a), read(b), read(c)   <- identical set
  //
  // was: no detection, ever. Each round's first call reset the streak, so
  //      a fan-out could spin indefinitely while single calls tripped at
  //      round 2.
  // now: round 2 is streak 2 (observe), round 3 is streak 3 (block) — and
  //      EVERY call of the round is refused at the block rung, not just one,
  //      so the fan-out stops spending.
  //
  // A round that ADDS work resets the ROUND streak, but each repeated call
  // keeps its own count — the model re-read a, b, c a third time:
  //   round 3: read(a), read(b), read(c), read(d)
  //            -> a, b, c blocked (3rd consecutive round each); d executes.
  //
  // `loopKey` still runs exactly once per checked call. Persisted state gains
  // two optional fields so fan-out and per-call evidence survive save/resume;
  // old state restores cleanly.

  Driving DoomLoopMonitor directly (or porting it) is the case that needs the
  new call — declare a round's whole batch before recording any of it.
  resolveDoomLoopOption and ResolvedDoomLoopConfig are now exported too:
  DoomLoopMonitor was previously exported without its config resolver, so it
  could not actually be constructed from the public API.

  import { DoomLoopMonitor, resolveDoomLoopOption } from "@openrouter/agent";
  
  const monitor = new DoomLoopMonitor(resolveDoomLoopOption(true));
  
  for (const [round, batch] of batches.entries()) {
    // NEW: declare the round's complete set BEFORE recording any of its calls,
    // so a repeating fan-out is scored as one unit. (Per-call repetition is
    // detected either way; the declaration adds whole-round identity.)
    await monitor.declareRound(
      round,
      batch.map((call) => ({
        toolName: call.name,
        keyMaterial: call.arguments,
      }))
    );
  
    for (const call of batch) {
      const { verdict } = await monitor.recordToolCall(
        call.name,
        call.arguments,
        round
      );
      if (verdict?.action === "block") refuse(call, verdict.message);
    }
  }

• #97 a629cf1 Thanks @LukasParke! - New ModelResult.getUsage() accessor: aggregate token/cost usage across every model call a run made.

  const result = callModel(client, { model, input, tools });
  
  for await (const item of result.getItemsStream()) {
    render(item);
  }
  
  // new: aggregate totals across EVERY round of the tool loop
  const usage = await result.getUsage();
  console.log(usage.modelCalls, usage.totalTokens, usage.cost);
  
  // was (and still is): the FINAL round's response only
  const response = await result.getResponse();
  console.log(response.usage?.totalTokens);

  getResponse() resolves to the final round's response, so in a multi-round tool loop the tokens spent on the intermediate tool_calls generations were unreachable — and getItemsStream() carries output items only, never surfacing the response.completed events that hold each round's usage block. Callers streaming items therefore had no way to account for a run's real token spend without registering a hook.

  await result.getUsage() returns the same SessionUsageTotals shape as the SessionEnd hook's totalUsage (modelCalls, inputTokens, outputTokens, totalTokens, cachedTokens, reasoningTokens, and cost when the server reported it), summed over the initial request, each tool-round follow-up, the empty-final retry, the allowFinalResponse final turn, and approval-resume requests. It gates on run completion like getResponse() does, so totals are final whether awaited directly, after getResponse(), or after draining any streaming getter — including getItemsStream() (on an approval-resumed run, reading usage never advances the tool loop; await getResponse()/getText() first for final totals there). Unlike getResponse() it never rejects (a failed run still consumed tokens), returning the totals accrued so far.

  The usage aggregate is now accumulated independently of the hook system, so it is correct for callers who configured no hooks at all; previously it only advanced as a side effect of PostModelCall emission. SessionEnd.totalUsage and getUsage() read from one snapshot helper and cannot drift.

• #73 78c562e Thanks @LukasParke! - Run-level cancellation and per-request timeout composition.

  New signal option on callModel: aborting it stops the tool-execution loop at the next turn boundary AND aborts the in-flight API request/stream, so a stalled provider fails fast with the abort reason instead of hanging until an outer caller/test timeout. A pre-aborted signal fails before any network dispatch.

  RequestOptions.timeoutMs (the third callModel argument) now reliably bounds each request the loop makes even when a signal is present: the underlying SDK skips its own timeoutMs wiring whenever a request carries a signal, so the engine composes {run signal, caller signal, per-request timeout} via AbortSignal.any per dispatch — each request gets a fresh timeout budget (not one shared per-run timer), and whichever bound fires first wins.

• #99 3028554 Thanks @devin-ai-integration! - Add strict to all client function-tool definitions, including tool.agent(), and pass it through serialization instead of hardcoding strict: null, so providers can enforce structured-outputs-style schema adherence on tool-call arguments.

  The SDK forwards the caller's generated schema unchanged and propagates provider validation errors. OpenAI-style strict schemas require every object property to be listed in required; use Zod .nullable() for conceptually optional values because .optional() allows the key to be omitted.

  import { tool } from "@openrouter/agent";
  import { z } from "zod/v4";
  
  const searchTool = tool({
    name: "search",
    inputSchema: z.object({ query: z.string() }),
    strict: true, // was: silently dropped (serialized as strict: null)
    // now: serialized as strict: true on the wire tool definition
    execute: async ({ query }) => runSearch(query),
  });

Patch Changes

• #95 5a7ed03 Thanks @LukasParke! - Clarify the validateFinalResponse error messages so an empty final turn can't be misread as "validation rejected my tool call" (issue #45).

  Invalid final response: empty or invalid output now names the actual defect: output array is empty (length 0) for response "<id>" — with the response id and a pointer to the strictFinalResponse/allowFinalResponse options — versus output is not an array (got <type>) when the payload is malformed. Invalid final response: missing required fields now lists which fields were absent (id, output, or both).

  Diagnostics only — no behavior change. Validation remains a pure array-length check, so tool-call-only output still passes (it always did; that was the misdiagnosis in #45). Both historical message prefixes are unchanged, so any matcher on them keeps working.

• #91 231fb65 Thanks @w0nche0l! - Thread the executed tool call into the hook execute context. context.toolCall is part of the tool-facing contract, but only the non-streaming orchestrator populated it — the streaming ModelResult loop builds its turn context with just numberOfTurns, so execute / onToolCalled hooks saw toolCall: undefined on the streaming path. buildExecuteCtx now fills the gap from the executed call: a caller-provided turnContext.toolCall still wins (the orchestrator's carries status), and otherwise the executed ParsedToolCall is converted back to a wire-shaped FunctionCallItem. The onResponseReceived path intentionally threads nothing — only the function_call_output item is in scope there.

• #100 0efdbb0 Thanks @devin-ai-integration! - Relax an unchanged forced toolChoice (required, a specific tool, or allowed_tools with mode: 'required') to auto after it produces a tool call, including follow-ups resumed after approval, HITL, client-tool, or async-tool pauses. Dynamically resolved choices re-arm when their semantic value changes. This lets the model synthesize a final text answer instead of being forced to call tools until the step budget runs out (DEV-785).

  const result = callModel(client, {
    model: "openai/gpt-4o",
    input: "Plan, research, then submit.",
    tools: [planTool, searchTool, submitTool] as const,
    toolChoice: ({ numberOfTurns }) =>
      numberOfTurns === 0
        ? { type: "function", name: "plan" }
        : numberOfTurns === 3
        ? { type: "function", name: "submit" }
        : "auto",
  });

[cortex-github-agent]

⚠️ APPROVE withheld by policy — PR author @github-actions[bot] is not a member of OpenRouterTeam (association: CONTRIBUTOR). Review posted as COMMENT; a maintainer must approve out-of-band.

Summary

Automated Changesets release PR: consumes the three pending changesets, bumps @openrouter/agent 0.8.0 → 0.9.0 (minor, matching three minor changesets) and @openrouter/mcp 0.0.1 → 0.0.2 (patch, per updateInternalDependencies: "patch" in .changeset/config.json), with matching CHANGELOG entries. No source changes; version/changelog math is internally consistent and no dependency range edit is needed since packages/mcp/package.json uses @openrouter/agent: workspace:*.

✅ No findings.

[cortex-github-agent]

⚠️ APPROVE withheld by policy — PR author @github-actions[bot] is not a member of OpenRouterTeam (association: CONTRIBUTOR). Review posted as COMMENT; a maintainer must approve out-of-band.

Summary

Update review of head 4125c61: the diff content is byte-identical to the version I reviewed at a97ef22 (same three changesets consumed, @openrouter/agent 0.8.0 → 0.9.0, @openrouter/mcp 0.0.1 → 0.0.2, same CHANGELOG bodies) — the synchronize was a regeneration/rebase of the Changesets branch, not a content change. Re-verified at the new head: .changeset/ contains no leftover pending changesets, packages/agent/package.json:3 reads 0.9.0 with the ./doom-loop subpath export present (matching the changelog's claim of a new @openrouter/agent/doom-loop entry point), and packages/mcp/package.json still depends on @openrouter/agent: workspace:*, so no dependency range rewrite is missing.

✅ No findings.