opencode-anthropic-fix 2.1.0 → 2.2.0

package/lib/host/v2.mjs

@@ -0,0 +1,305 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createAnthropicRuntime } from "./runtime.mjs";
+import { registerAnthropicCommandRpc, registerAnthropicServerCommand } from "./command-rpc.mjs";
+import { setupV2Transport } from "./v2-transport.mjs";
+import { V2_SDK_PACKAGE } from "./v2-language.mjs";
+import { prepareV2Tools } from "./tool-names.mjs";
+import { applyV2MessagePolicies, assertPortableV2History } from "./v2-context.mjs";
+import { isTruthyEnv } from "../env.mjs";
+import { hasOneMillionContext, isOpus46Model, isOpus47Model, isOpus48Model } from "../mimicry/wire-compat.mjs";
+
+export const OAUTH_METHOD_ID = "opencode-anthropic-fix";
+// Keep the AI SDK route while resolving the shipped factory locally. The host's
+// built-in dynamic hook executes before ours, so a registry spec adds an install.
+export const V2_MODEL_PACKAGE = `aisdk:${V2_SDK_PACKAGE}`;
+
+/** @param {object} auth */
+function credential(auth) {
+  if (!auth?.access || !auth?.refresh) throw new Error("No enabled Anthropic OAuth account. Use /anthropic login.");
+  return {
+    type: "oauth",
+    methodID: OAUTH_METHOD_ID,
+    access: auth.access,
+    refresh: auth.refresh,
+    expires: auth.expires,
+  };
+}
+
+/**
+ * v2 owns registration and presentation; the shared runtime owns credentials,
+ * request construction and retries. No v1 hooks are returned to the v2 host.
+ * @param {import('@opencode/plugin').Plugin.Context} context
+ * @param {{createRuntime?: typeof createAnthropicRuntime, setupTransport?: typeof setupV2Transport}} [dependencies]
+ */
+export async function setupV2(context, dependencies = {}) {
+  const runtime = (dependencies.createRuntime ?? createAnthropicRuntime)({
+    interactiveOAuth: false,
+    hostCompatShim: true, // @ai-sdk/anthropic 3.0.111 is pinned, even when the host omits its UA.
+    prepareRequest: prepareV2Tools,
+  });
+  const commands = new AsyncLocalStorage();
+  const registrations = [];
+  let disposed = false;
+  let managed = false;
+  let poolAvailable = false;
+  let ownedConnection = false;
+  const knownOwnedConnections = new Set();
+  let fetchPromise;
+  let connection;
+  let config;
+  let transport;
+  let refreshStatePromise;
+  let stateSignature;
+  let warnedAboutHaikuSummary = false;
+
+  function assertActive() {
+    if (disposed) throw new Error("Anthropic plugin is disposed");
+  }
+
+  async function dispose() {
+    if (disposed) return;
+    disposed = true;
+    const failures = [];
+    for (const resource of [transport, ...registrations.reverse(), runtime]) {
+      try {
+        await resource?.dispose();
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length) throw new AggregateError(failures, "Failed to dispose Anthropic plugin resources");
+  }
+
+  async function refreshState() {
+    assertActive();
+    if (refreshStatePromise) return refreshStatePromise;
+    refreshStatePromise = (async () => {
+      runtime.reloadConfig();
+      poolAvailable = Boolean(await runtime.getCurrentAuth({ allowExpired: true }));
+      assertActive();
+      connection = await context.integration.connection.active("anthropic");
+      assertActive();
+      // An explicitly selected API key/environment connection remains native.
+      // Existing pools can be used before connecting a v2 credential.
+      const connectionKey = JSON.stringify(connection);
+      ownedConnection = knownOwnedConnections.has(connectionKey);
+      if (connection?.type === "credential" && connection.method === "oauth") {
+        try {
+          const activeCredential = await context.integration.connection.resolve(connection);
+          assertActive();
+          ownedConnection = activeCredential?.methodID === OAUTH_METHOD_ID;
+          if (ownedConnection) knownOwnedConnections.add(connectionKey);
+          else knownOwnedConnections.delete(connectionKey);
+        } catch (error) {
+          if (disposed) throw error;
+          // The host may attempt to refresh an expired credential after its
+          // account was removed. Keep administration available and preserve a
+          // known owned connection's disabled state; never print token errors.
+          console.warn(
+            "[anthropic] The selected OAuth connection could not be resolved. Reconnect through /anthropic login.",
+          );
+        }
+      }
+      managed = poolAvailable && (!connection || ownedConnection);
+      config = structuredClone(runtime.getConfig());
+      if (managed && config.token_economy_strategies.haiku_rolling_summary && !warnedAboutHaikuSummary) {
+        warnedAboutHaikuSummary = true;
+        console.warn(
+          "[anthropic] haiku_rolling_summary requires a v1 fork hook; OpenCode v2 uses summary compaction instead.",
+        );
+      }
+      const nextSignature = JSON.stringify({
+        managed,
+        ownedConnection,
+        connection,
+        limits: config.override_model_limits,
+      });
+      if (nextSignature !== stateSignature) {
+        stateSignature = nextSignature;
+        fetchPromise = undefined;
+        await context.provider.reload();
+      }
+    })().finally(() => {
+      refreshStatePromise = undefined;
+    });
+    return refreshStatePromise;
+  }
+
+  try {
+    const hooks = await runtime.initialize({
+      client: {
+        // The runtime persists the rotated token under its cross-process lock.
+        // v2 persists the returned credential only through its OAuth callbacks;
+        // there is deliberately no invented credential-update API here.
+        auth: {
+          async set() {
+            return undefined;
+          },
+        },
+        session: {
+          async prompt({ body }) {
+            const output = commands.getStore();
+            if (!output) throw new Error("Administrative output requires an Anthropic command invocation");
+            output.push(...body.parts.filter((part) => part.type === "text").map((part) => part.text));
+          },
+        },
+        tui: {
+          async showToast({ body }) {
+            const output = commands.getStore();
+            if (output) output.push(body.message);
+          },
+        },
+      },
+    });
+
+    const isManagedModel = (model) => managed && model?.providerID === "anthropic";
+    transport = await (dependencies.setupTransport ?? setupV2Transport)(context, {
+      isManagedModel,
+      async fetch(input, init) {
+        if (disposed) throw new Error("Anthropic plugin is disposed");
+        if (!managed) throw new Error("The Anthropic OAuth connection changed. Retry with the selected connection.");
+        fetchPromise ??= hooks.auth.loader(
+          async () => (await runtime.getCurrentAuth({ allowExpired: true })) ?? { type: "none" },
+          { models: {} },
+        );
+        const executor = await fetchPromise;
+        if (typeof executor.fetch !== "function") {
+          fetchPromise = undefined;
+          throw new Error("No enabled Anthropic OAuth account. Use /anthropic login.");
+        }
+        return executor.fetch(input, init);
+      },
+    });
+
+    registrations.push(
+      await context.integration.transform((editor) => {
+        editor.method.update({
+          integrationID: "anthropic",
+          method: { id: OAUTH_METHOD_ID, type: "oauth", label: "Claude Pro/Max (multi-account)" },
+          async authorize() {
+            const flow = await runtime.authorizeOAuth();
+            return {
+              url: flow.url,
+              instructions: flow.instructions,
+              mode: "code",
+              async callback(code) {
+                const result = await flow.callback(code);
+                if (result.type !== "success") throw new Error("Anthropic authorization failed. Start login again.");
+                fetchPromise = undefined;
+                await refreshState();
+                return credential(result);
+              },
+            };
+          },
+          async refresh() {
+            // Disk stays authoritative after logout/removal and cross-process refresh.
+            return credential(await runtime.getCurrentAuth({ refresh: true }));
+          },
+          label: () => "Claude Pro/Max account pool",
+        });
+      }),
+    );
+
+    registrations.push(
+      await context.provider.transform((editor) => {
+        if ((!managed && !ownedConnection) || !editor.get("anthropic")) return;
+        editor.update("anthropic", (provider) => {
+          if (!poolAvailable) {
+            // A stale host credential must not resurrect an account removed
+            // from the authoritative pool by silently reverting to native.
+            provider.activation = "disabled";
+            return;
+          }
+          provider.activation = "enabled";
+          provider.package = V2_MODEL_PACKAGE;
+          provider.settings = { ...provider.settings, apiKey: "opencode-managed-oauth" };
+          // Core 2.0.22+ defaults to five-minute header/chunk limits. The
+          // executor has attempt budgets, not a total deadline (transient 429s
+          // and Retry-After waits can exceed five minutes). Do not race it with
+          // host timers. Auxiliary work has its own deadline in the bridge.
+          provider.settings.timeout = false;
+          provider.settings.headerTimeout = false;
+          // 2.0.21's public schema only accepts a number here; its fetch wrapper
+          // enables the timer only for values > 0. 2.0.22 requires false instead.
+          provider.settings.chunkTimeout = context.app?.version === "2.0.21" ? 0 : false;
+          // The compatibility route uses the host's summary compaction instead.
+          provider.settings.compaction = { type: "summary" };
+        });
+      }),
+    );
+    registrations.push(
+      await context.model.transform((editor) => {
+        if (!managed) return;
+        for (const candidate of editor.list("anthropic")) {
+          editor.update(candidate.providerID, candidate.id, (model) => {
+            model.package = V2_MODEL_PACKAGE;
+            model.settings = { ...model.settings };
+            model.settings.compaction = { type: "summary" };
+            // The host merges a selected variant after the base model settings.
+            for (const variant of model.variants ?? []) {
+              variant.settings = { ...variant.settings, compaction: { type: "summary" } };
+            }
+            model.cost = model.cost.map((tier) => ({ ...tier, input: 0, output: 0, cache: { read: 0, write: 0 } }));
+            if (
+              config.override_model_limits.enabled &&
+              !isTruthyEnv(process.env.CLAUDE_CODE_DISABLE_1M_CONTEXT) &&
+              (hasOneMillionContext(model.id) ||
+                isOpus46Model(model.id) ||
+                isOpus47Model(model.id) ||
+                isOpus48Model(model.id))
+            ) {
+              model.limit.context = config.override_model_limits.context;
+              if (config.override_model_limits.output > 0) model.limit.output = config.override_model_limits.output;
+            }
+          });
+        }
+      }),
+    );
+
+    for (const name of ["context", "compaction", "generate", "title"]) {
+      registrations.push(
+        await context.session.hook(
+          name,
+          async (event) => {
+            await refreshState();
+            if (!isManagedModel(event.model)) return;
+            assertPortableV2History(event.messages);
+            applyV2MessagePolicies(event.messages, runtime.getConfig().token_economy_strategies);
+            await hooks["experimental.chat.system.transform"]({ model: event.model }, { system: event.system });
+            for (let i = 0; i < event.system.length; i++) {
+              if (typeof event.system[i] === "string") event.system[i] = { type: "text", text: event.system[i] };
+            }
+            if (name === "compaction") {
+              const output = { context: [] };
+              await hooks["experimental.session.compacting"]({ sessionID: event.sessionID }, output);
+              event.system.push(...output.context.map((text) => ({ type: "text", text })));
+            }
+          },
+          { providerID: "anthropic" },
+        ),
+      );
+    }
+
+    registrations.push(await registerAnthropicServerCommand(context));
+    registrations.push(
+      await registerAnthropicCommandRpc(context, async (input) => {
+        const output = [];
+        await commands.run(output, () => runtime.executeCommand(input));
+        fetchPromise = undefined;
+        await refreshState();
+        return output.join("\n\n");
+      }),
+    );
+    await refreshState();
+    return dispose;
+  } catch (error) {
+    try {
+      await dispose();
+    } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], "Anthropic v2 initialization and cleanup failed", {
+        cause: cleanupError,
+      });
+    }
+    throw error;
+  }
+}

package/lib/mimicry/request-body.mjs

@@ -34,7 +34,9 @@ import {
   repairOrphanedToolUseBlocks,
 } from "./request-helpers.mjs";
 import { isFalsyEnv, isTruthyEnv } from "../env.mjs";
-import { sessionMetrics } from "../session-metrics.mjs";
+import { sessionMetrics as legacySessionMetrics } from "../session-metrics.mjs";
+
+const THINKING_DISPLAYS = new Set(["summarized", "omitted"]);
 
 /**
  * Coerce an incoming `thinking` block to the shape the model actually accepts.
@@ -65,7 +67,12 @@ export function normalizeThinkingBlock(thinking, model) {
       const parsedBudget = parseInt(process.env.MAX_THINKING_TOKENS, 10);
       return { type: "enabled", budget_tokens: Number.isNaN(parsedBudget) ? 16000 : parsedBudget };
     }
-    return { type: "adaptive" };
+    // Keep the caller's display: dropping it makes the wire builder fall back to "updates",
+    // which returns empty thinking text on models that default to "omitted" (Opus 5.5, Fable 5.1).
+    // Only the values the wire builder honors are kept.
+    return THINKING_DISPLAYS.has(thinking.display)
+      ? { type: "adaptive", display: thinking.display }
+      : { type: "adaptive" };
   }
 
   // Non-adaptive models: pass through unchanged
@@ -103,6 +110,7 @@ export const CORE_TOOL_NAMES = new Set([
  */
 export function transformRequestBody(body, signature, runtime, taskBudgetsActive, config) {
   if (!body || typeof body !== "string") return body;
+  const sessionMetrics = runtime?.sessionMetrics ?? legacySessionMetrics;
 
   try {
     const parsed = JSON.parse(body);
@@ -123,7 +131,7 @@ export function transformRequestBody(body, signature, runtime, taskBudgetsActive
     }
     // Output cap: resolve max_tokens before any other body transforms
     if (config?.output_cap?.enabled) {
-      parsed.max_tokens = resolveMaxTokens(parsed, config);
+      parsed.max_tokens = resolveMaxTokens(parsed, config, sessionMetrics);
     }
     // The body-level `anthropic_beta` array existed only for Bedrock, which does
     // not forward custom HTTP headers. Multi-provider support was removed, and
@@ -519,23 +527,25 @@ export function transformRequestBody(body, signature, runtime, taskBudgetsActive
     // opencode uses lowercase names while CC uses PascalCase. While only "todowrite"
     // is currently confirmed blocklisted, we rename ALL core opencode tools to match
     // CC's naming convention as a preventive measure against future blocklist additions.
-    const OC_TO_CC_TOOL_NAMES = {
-      bash: "Bash",
-      read: "Read",
-      glob: "Glob",
-      grep: "Grep",
-      edit: "Edit",
-      write: "Write",
-      webfetch: "WebFetch",
-      todowrite: "TodoWrite",
-      skill: "Skill",
-      task: "Task",
-      compress: "Compress",
-    };
+    const OC_TO_CC_TOOL_NAMES = new Map(
+      Object.entries({
+        bash: "Bash",
+        read: "Read",
+        glob: "Glob",
+        grep: "Grep",
+        edit: "Edit",
+        write: "Write",
+        webfetch: "WebFetch",
+        todowrite: "TodoWrite",
+        skill: "Skill",
+        task: "Task",
+        compress: "Compress",
+      }),
+    );
     if (Array.isArray(parsed.tools)) {
       for (const tool of parsed.tools) {
-        if (tool.name && OC_TO_CC_TOOL_NAMES[tool.name]) {
-          tool.name = OC_TO_CC_TOOL_NAMES[tool.name];
+        if (tool.name && OC_TO_CC_TOOL_NAMES.has(tool.name)) {
+          tool.name = OC_TO_CC_TOOL_NAMES.get(tool.name);
         }
       }
     }
@@ -544,8 +554,8 @@ export function transformRequestBody(body, signature, runtime, taskBudgetsActive
       for (const msg of parsed.messages) {
         if (!Array.isArray(msg.content)) continue;
         for (const block of msg.content) {
-          if (block.type === "tool_use" && block.name && OC_TO_CC_TOOL_NAMES[block.name]) {
-            block.name = OC_TO_CC_TOOL_NAMES[block.name];
+          if (block.type === "tool_use" && block.name && OC_TO_CC_TOOL_NAMES.has(block.name)) {
+            block.name = OC_TO_CC_TOOL_NAMES.get(block.name);
           }
         }
       }
@@ -605,7 +615,7 @@ export function transformRequestBody(body, signature, runtime, taskBudgetsActive
       parsed.model &&
       !/claude-3-|haiku/i.test(parsed.model)
     ) {
-      const coreToolNames = new Set(Object.values(OC_TO_CC_TOOL_NAMES));
+      const coreToolNames = new Set(OC_TO_CC_TOOL_NAMES.values());
       for (const tool of parsed.tools) {
         if (tool.name && !coreToolNames.has(tool.name)) {
           tool.defer_loading = true;

package/lib/mimicry/request-helpers.mjs

@@ -4,7 +4,7 @@
 //
 // Leaf helpers used by transformRequestBody, extracted from index.mjs so the
 // orchestrator can become a thin importer. All are pure except resolveMaxTokens,
-// which reads/writes the shared sessionMetrics.lastStopReason singleton.
+// which reads/writes the caller's session metrics (or the legacy default).
 
 import { sessionMetrics } from "../session-metrics.mjs";
 
@@ -219,25 +219,26 @@ export function buildRequestMetadata(input) {
 /**
  * Resolve the outgoing max_tokens honoring the output_cap config and a
  * one-turn escalation when the previous stream stopped on max_tokens.
- * Reads/writes the shared sessionMetrics.lastStopReason singleton.
+ * Reads/writes the injected metrics; standalone callers retain the legacy default.
  * @param {{max_tokens?: number}} body
  * @param {any} config
+ * @param {typeof sessionMetrics} [metrics]
  * @returns {number|undefined}
  */
-export function resolveMaxTokens(body, config) {
+export function resolveMaxTokens(body, config, metrics = sessionMetrics) {
   if (!config.output_cap?.enabled) return body.max_tokens; // passthrough
   if (body.max_tokens != null) return body.max_tokens; // caller-specified wins
   // QA note L-escalation: lastStopReason is set by extractUsageFromSSEEvent AFTER the stream
   // completes. The timing works correctly for "escalate for one turn" because this function runs
   // BEFORE the next request's stream starts. If the response pipeline changes to update stop
   // reason mid-stream or before response completion, this ordering assumption would break.
-  const escalated = sessionMetrics.lastStopReason === "max_tokens";
+  const escalated = metrics.lastStopReason === "max_tokens";
   const result = escalated
     ? (config.output_cap.escalated_max_tokens ?? 64_000)
     : (config.output_cap.default_max_tokens ?? 8_000);
   // Reset after escalation is consumed (sticky for exactly one turn)
   if (escalated) {
-    sessionMetrics.lastStopReason = null;
+    metrics.lastStopReason = null;
   }
   return result;
 }

package/lib/mimicry/response-stream.mjs

@@ -143,30 +143,32 @@ export function stripMcpPrefixFromSSE(text) {
  * Built from the outgoing OC_TO_CC_TOOL_NAMES map (defined in transformRequestBody).
  * Must stay in sync with that map.
  */
-export const CC_TO_OC_TOOL_NAMES = {
-  Bash: "bash",
-  Read: "read",
-  Glob: "glob",
-  Grep: "grep",
-  Edit: "edit",
-  Write: "write",
-  WebFetch: "webfetch",
-  TodoWrite: "todowrite",
-  Skill: "skill",
-  Task: "task",
-  Compress: "compress",
-};
+export const CC_TO_OC_TOOL_NAMES = new Map(
+  Object.entries({
+    Bash: "bash",
+    Read: "read",
+    Glob: "glob",
+    Grep: "grep",
+    Edit: "edit",
+    Write: "write",
+    WebFetch: "webfetch",
+    TodoWrite: "todowrite",
+    Skill: "skill",
+    Task: "task",
+    Compress: "compress",
+  }),
+);
 
 /**
  * Reverse-map a tool name from CC PascalCase back to opencode lowercase,
  * and strip `mcp_` prefix if present. Returns the original name if no mapping exists.
  * @param {string} name
+ * @param {Map<string, string>} [toolNameMap] - Per-request restoration of host tool names.
  * @returns {string}
  */
-export function reverseMapToolName(name) {
-  if (CC_TO_OC_TOOL_NAMES[name]) return CC_TO_OC_TOOL_NAMES[name];
-  if (name.startsWith("mcp_")) return name.slice(4);
-  return name;
+export function reverseMapToolName(name, toolNameMap) {
+  const mapped = CC_TO_OC_TOOL_NAMES.get(name) ?? (name.startsWith("mcp_") ? name.slice(4) : name);
+  return toolNameMap?.get(mapped) ?? mapped;
 }
 
 /**
@@ -175,9 +177,10 @@ export function reverseMapToolName(name) {
  * Returns true if any modification was made.
  *
  * @param {any} parsed
+ * @param {Map<string, string>} [toolNameMap]
  * @returns {boolean}
  */
-export function stripMcpPrefixFromParsedEvent(parsed) {
+export function stripMcpPrefixFromParsedEvent(parsed, toolNameMap) {
   if (!parsed || typeof parsed !== "object") return false;
 
   let modified = false;
@@ -188,7 +191,7 @@ export function stripMcpPrefixFromParsedEvent(parsed) {
     (parsed.content_block.type === "tool_use" || parsed.content_block.type === "tool_reference") &&
     typeof parsed.content_block.name === "string"
   ) {
-    const mapped = reverseMapToolName(parsed.content_block.name);
+    const mapped = reverseMapToolName(parsed.content_block.name, toolNameMap);
     if (mapped !== parsed.content_block.name) {
       parsed.content_block.name = mapped;
       modified = true;
@@ -199,7 +202,7 @@ export function stripMcpPrefixFromParsedEvent(parsed) {
   if (parsed.message && Array.isArray(parsed.message.content)) {
     for (const block of parsed.message.content) {
       if ((block.type === "tool_use" || block.type === "tool_reference") && typeof block.name === "string") {
-        const mapped = reverseMapToolName(block.name);
+        const mapped = reverseMapToolName(block.name, toolNameMap);
         if (mapped !== block.name) {
           block.name = mapped;
           modified = true;
@@ -212,7 +215,7 @@ export function stripMcpPrefixFromParsedEvent(parsed) {
   if (Array.isArray(parsed.content)) {
     for (const block of parsed.content) {
       if ((block.type === "tool_use" || block.type === "tool_reference") && typeof block.name === "string") {
-        const mapped = reverseMapToolName(block.name);
+        const mapped = reverseMapToolName(block.name, toolNameMap);
         if (mapped !== block.name) {
           block.name = mapped;
           modified = true;
@@ -803,6 +806,7 @@ function createPassthroughStream(reader, idleTimeoutMs) {
  *
  * @param {Response} response
  * @param {object} options
+ * @param {Map<string, string>} [options.toolNameMap] - Host aliases specific to this request.
  * @param {((stats: UsageStats) => void) | null} [options.onUsage]
  * @param {((details: {reason: import('../backoff.mjs').RateLimitReason, invalidateToken: boolean}) => void) | null} [options.onAccountError]
  * @param {((stats: {blockTypeFallbacks: number, deltasDropped: number, eventsDropped: number, dryRun?: boolean}) => void) | null} [options.onHostCompatShim]
@@ -839,6 +843,7 @@ export function createTransformedSSEStream(
     onAccountError,
     onHostCompatShim,
     hostCompatShim = true,
+    toolNameMap,
     correlationId,
     idleTimeoutMs,
     captureEnabled,
@@ -939,7 +944,7 @@ export function createTransformedSSEStream(
     }
     if (shimAction === "drop") return [];
 
-    const mcpModified = stripMcpPrefixFromParsedEvent(parsed);
+    const mcpModified = stripMcpPrefixFromParsedEvent(parsed, toolNameMap);
     if (shimAction === "rewrite" || mcpModified) {
       // Re-serialize only the `data:` line(s) this event actually changed;
       // every other line in the block (event:, id:, comments) is untouched.

package/lib/oauth.mjs

@@ -179,9 +179,21 @@ function buildTokenHeaders() {
  * @param {number} ms
  * @returns {Promise<void>}
  */
-function sleep(ms) {
+function sleep(ms, signal) {
+  signal?.throwIfAborted();
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
 }
 
 /**
@@ -442,7 +454,7 @@ export function parseOAuthCallback(input) {
  * Exchange an authorization code for tokens.
  * @param {string} code
  * @param {string} verifier
- * @param {{ sdkTokenUserAgent?: boolean }} [options] - `sdkTokenUserAgent` is
+ * @param {{ sdkTokenUserAgent?: boolean, signal?: AbortSignal }} [options] - `sdkTokenUserAgent` is
  *   accepted and ignored. It is retained so existing call sites keep type-
  *   checking; there is only one token fingerprint. See §7 divergence D2.
  * @returns {Promise<
@@ -458,7 +470,7 @@ export function parseOAuthCallback(input) {
  *     }
  * >}
  */
-export async function exchange(code, verifier, _options = {}) {
+export async function exchange(code, verifier, options = {}) {
   const tokenHeaders = buildTokenHeaders();
   const fail = (status, rawText = "", cooldownHint = { retryAfterMs: null }) => {
     const { errorCode, reason } = parseOAuthErrorBody(rawText);
@@ -486,6 +498,7 @@ export async function exchange(code, verifier, _options = {}) {
   const { code: authCode, state: authState } = parseOAuthCallback(code);
   let result;
   for (let attempt = 0; attempt <= OAUTH_MAX_RETRIES; attempt++) {
+    options.signal?.throwIfAborted();
     try {
       // SHAPE IS INPUT-DEPENDENT (D8). `state` is present only when the pasted
       // callback carried one, so this body is five keys for a bare code and six
@@ -504,11 +517,16 @@ export async function exchange(code, verifier, _options = {}) {
         method: "POST",
         headers: tokenHeaders,
         body: JSON.stringify(exchangeBody),
-        signal: AbortSignal.timeout(15_000),
+        // Match the runtime's AbortSignal.any baseline; a caller signal must
+        // not replace the independent per-attempt network deadline.
+        signal: options.signal
+          ? AbortSignal.any([options.signal, AbortSignal.timeout(15_000)])
+          : AbortSignal.timeout(15_000),
       });
     } catch (err) {
+      options.signal?.throwIfAborted();
       if (attempt < OAUTH_MAX_RETRIES) {
-        await sleep(Math.min(500 * 2 ** attempt, 2000));
+        await sleep(Math.min(500 * 2 ** attempt, 2000), options.signal);
         continue;
       }
       return fail(undefined, err instanceof Error ? err.message : String(err));
@@ -524,7 +542,7 @@ export async function exchange(code, verifier, _options = {}) {
           : "";
 
       if (attempt < OAUTH_MAX_RETRIES && isRetryableTokenStatus(result.status)) {
-        await sleep(getRetryDelayMs(result, attempt));
+        await sleep(getRetryDelayMs(result, attempt), options.signal);
         continue;
       }
 
@@ -638,6 +656,7 @@ export async function refreshToken(refreshTokenValue, options = {}) {
   const tokenHeaders = buildTokenHeaders();
 
   for (let attempt = 0; attempt <= OAUTH_MAX_RETRIES; attempt++) {
+    options.signal?.throwIfAborted();
     let resp;
     // A single AbortSignal.timeout() created outside the loop starts counting at
     // creation, so a slow first attempt would leave the retries with no budget
@@ -658,8 +677,9 @@ export async function refreshToken(refreshTokenValue, options = {}) {
         signal,
       });
     } catch (err) {
+      options.signal?.throwIfAborted();
       if (attempt < OAUTH_MAX_RETRIES) {
-        await sleep(Math.min(500 * 2 ** attempt, 2000));
+        await sleep(Math.min(500 * 2 ** attempt, 2000), options.signal);
         continue;
       }
       throw err;
@@ -670,7 +690,7 @@ export async function refreshToken(refreshTokenValue, options = {}) {
       const retryAfterMs = getRetryDelayMs(resp, attempt);
 
       if (attempt < OAUTH_MAX_RETRIES && isRetryableTokenStatus(resp.status)) {
-        await sleep(retryAfterMs);
+        await sleep(retryAfterMs, options.signal);
         continue;
       }