fix(cli): setup-opencode respects --api-key/OMNIROUTE_API_KEY over context token (#12783)

bin/cli/commands/setup-opencode.mjs

@@ -35,16 +35,24 @@ export function resolveOpencodeTarget(opts = {}) {
       baseUrl = `http://localhost:${Number(opts.port ?? process.env.PORT ?? 20128) || 20128}`;
   }
 
+  // Precedence: explicit --api-key flag > OMNIROUTE_API_KEY env var > active
+  // context's management token. A context's accessToken/apiKey is a CLI
+  // management credential (oma_live_...) with no /v1/* inference scope — it
+  // must never silently outrank a real inference key the caller supplied
+  // either as a flag or via the ambient env var (mirrors the explicit >
+  // ambient-env > context precedence documented in bin/cli/api.mjs's
+  // buildHeaders()). Only fall back to the context token when neither an
+  // explicit flag nor the env var is set.
   let apiKey = opts.apiKey ?? opts["api-key"];
+  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
   if (!apiKey) {
     try {
       const c = resolveActiveContext(opts.context ?? process.env.OMNIROUTE_CONTEXT);
-      apiKey = c?.accessToken || c?.apiKey;
+      apiKey = c?.accessToken || c?.apiKey || "";
     } catch {
       /* no context auth */
     }
   }
-  if (!apiKey) apiKey = process.env.OMNIROUTE_API_KEY || "";
   return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
 }
 
@@ -177,8 +185,17 @@ export function registerSetupOpencode(program) {
       "--allow-container-write",
       "Write even when the target is inside a container and not mounted from the host"
     )
-    .action(async (opts) => {
-      const code = await runSetupOpencodeCommand(opts);
+    .action(async (opts, cmd) => {
+      // Commander parses the ancestor program's own global --api-key option
+      // (bin/cli/program.mjs, bound to .env("OMNIROUTE_API_KEY")) against any
+      // occurrence of the flag in argv, so it wins the value even when the
+      // user typed --api-key AFTER `setup-opencode` — this local option's own
+      // `opts.apiKey` never sees it. cmd.optsWithGlobals() resolves to the
+      // correct value either way ("globals overwrite locals" is exactly the
+      // outcome we want here, since the global option is where the value
+      // always actually lands).
+      const resolvedOpts = { ...opts, apiKey: cmd.optsWithGlobals().apiKey ?? opts.apiKey };
+      const code = await runSetupOpencodeCommand(resolvedOpts);
       if (code !== 0) process.exit(code);
     });
 }

changelog.d/fixes/12129-context-handoff-native-passthrough-shape.md

@@ -1 +0,0 @@
-- fix(sse): require Responses-shaped body before native OpenAI-compatible passthrough (#12129)

changelog.d/fixes/12783-setup-opencode-api-key-precedence.md

@@ -0,0 +1 @@
+- fix(cli): setup-opencode no longer sends an active context's management token to `/v1/models` when `--api-key`/`OMNIROUTE_API_KEY` is supplied — an explicit flag or the env var now always outranks the context's token, and the flag itself is no longer swallowed by the parent program's global `--api-key` option (#12783)

open-sse/handlers/chatCore.ts

@@ -731,7 +731,6 @@ export async function handleChatCore({
       sourceFormat,
       endpointPath,
       providerSpecificData: credentials?.providerSpecificData,
-      body,
     });
   const responsesInputItems = Array.isArray(body?.input) ? body.input : [];
   const customToolNames = collectCustomToolNamesForSourceFormat(

open-sse/handlers/chatCore/passthroughHelpers.ts

@@ -53,35 +53,19 @@ export function stampNativeResponsesPassthroughBody(
   return { ...body, _nativeOpenAICompatibleResponsesPassthrough: true };
 }
 
-// A body only qualifies for the native-Responses passthrough fast path when it is
-// actually shaped like a Responses API request (`input`, no `messages`). Endpoint
-// path alone is not sufficient: an internally-synthesized Chat Completions-shaped
-// body (e.g. the context-handoff summary request) can be dispatched through a
-// closure that still carries the original client request's `/responses` endpoint,
-// which otherwise makes `sourceFormat` resolve to "openai-responses" even though
-// the body itself was never translated. See issue #12129.
-function isResponsesShapedBody(body: unknown): boolean {
-  if (!body || typeof body !== "object") return false;
-  const candidate = body as Record<string, unknown>;
-  return candidate.input !== undefined && candidate.messages === undefined;
-}
-
 export function shouldUseNativeOpenAICompatibleResponsesPassthrough({
   provider,
   sourceFormat,
   endpointPath,
   providerSpecificData,
-  body,
 }: {
   provider?: string | null;
   sourceFormat?: string | null;
   endpointPath?: string | null;
   providerSpecificData?: unknown;
-  body?: unknown;
 }): boolean {
   if (!provider?.startsWith("openai-compatible-")) return false;
   if (sourceFormat !== FORMATS.OPENAI_RESPONSES) return false;
-  if (body !== undefined && !isResponsesShapedBody(body)) return false;
   if (providerSpecificData && typeof providerSpecificData === "object") {
     const psd = providerSpecificData as Record<string, unknown>;
     if (psd.apiType === "responses" || psd._omnirouteForceResponsesUpstream === true) {

tests/unit/context-handoff-native-passthrough-bug.test.ts

@@ -1,86 +0,0 @@
-// Regression test for issue #12129: an internal context-handoff summary request (built in
-// Chat Completions shape -- `messages`, no `input`) is dispatched through the SAME
-// handleSingleModel closure that carries the ORIGINAL client request's endpoint.
-// When that original endpoint matched `/responses` and the resolved handoff-model
-// provider is an openai-compatible-* connection configured with apiType "responses",
-// the pipeline used to decide the body was already native-Responses-shaped and skip
-// chat->responses translation entirely (`_nativeOpenAICompatibleResponsesPassthrough`),
-// so the upstream received `messages` on `/v1/responses` and rejected it with zero input.
-//
-// Fix: `shouldUseNativeOpenAICompatibleResponsesPassthrough` now requires the body to
-// actually look Responses-shaped (`input` present, `messages` absent) before allowing
-// the passthrough fast path, so an internally-synthesized chat-shaped body is routed
-// through the normal chat->responses translation layer instead.
-import assert from "node:assert/strict";
-import { test } from "node:test";
-
-import { resolveChatCoreRequestFormat } from "../../open-sse/handlers/chatCore/requestFormat.ts";
-import { shouldUseNativeOpenAICompatibleResponsesPassthrough } from "../../open-sse/handlers/chatCore/passthroughHelpers.ts";
-
-test("internal chat-shaped handoff body is no longer treated as native Responses passthrough", () => {
-  const clientRawRequest = {
-    endpoint: "/v1/responses",
-    headers: new Headers(),
-  };
-
-  const summaryBody = {
-    model: "some-handoff-model",
-    messages: [{ role: "user", content: "Summarize this conversation." }],
-    stream: false,
-    max_tokens: 800,
-    temperature: 0.1,
-    _omnirouteSkipContextRelay: true,
-    _omnirouteInternalRequest: "context-handoff",
-  };
-
-  const { sourceFormat, endpointPath } = resolveChatCoreRequestFormat({
-    clientRawRequest,
-    body: summaryBody,
-    provider: "openai-compatible-responses-cliproxy",
-    userAgent: null,
-  });
-
-  assert.equal(sourceFormat, "openai-responses");
-  assert.equal(endpointPath, "/v1/responses");
-
-  const providerSpecificData = { apiType: "responses" };
-
-  const nativePassthrough = shouldUseNativeOpenAICompatibleResponsesPassthrough({
-    provider: "openai-compatible-responses-cliproxy",
-    sourceFormat,
-    endpointPath,
-    providerSpecificData,
-    body: summaryBody,
-  });
-
-  assert.equal(
-    nativePassthrough,
-    false,
-    "fixed: chat-shaped internal body must not take the native-Responses passthrough shortcut"
-  );
-
-  assert.equal((summaryBody as Record<string, unknown>).input, undefined);
-  assert.ok(Array.isArray(summaryBody.messages) && summaryBody.messages.length > 0);
-});
-
-test("genuine Responses-shaped body still takes the native passthrough fast path", () => {
-  const genuineResponsesBody = {
-    model: "gpt-5.6-sol",
-    input: [{ role: "user", content: [{ type: "input_text", text: "Hello" }] }],
-    stream: false,
-  };
-
-  const nativePassthrough = shouldUseNativeOpenAICompatibleResponsesPassthrough({
-    provider: "openai-compatible-responses-cliproxy",
-    sourceFormat: "openai-responses",
-    endpointPath: "/v1/responses",
-    providerSpecificData: { apiType: "responses" },
-    body: genuineResponsesBody,
-  });
-
-  assert.equal(
-    nativePassthrough,
-    true,
-    "a genuine Responses-shaped client body must keep the zero-translation fast path"
-  );
-});

tests/unit/repro-12783-setup-opencode-apikey.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { resolveOpencodeTarget } from "../../bin/cli/commands/setup-opencode.mjs";
+
+/** Point OMNIROUTE_CONTEXT config resolution at an isolated, throwaway DATA_DIR. */
+function withIsolatedContext(contextConfig, fn) {
+  const dir = mkdtempSync(join(tmpdir(), "omniroute-setup-opencode-test-"));
+  const originalDataDir = process.env.DATA_DIR;
+  process.env.DATA_DIR = dir;
+  writeFileSync(
+    join(dir, "config.json"),
+    JSON.stringify({
+      version: 1,
+      currentContext: "remote",
+      contexts: { remote: contextConfig },
+    })
+  );
+  try {
+    return fn();
+  } finally {
+    if (originalDataDir === undefined) delete process.env.DATA_DIR;
+    else process.env.DATA_DIR = originalDataDir;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function withEnvApiKey(value, fn) {
+  const original = process.env.OMNIROUTE_API_KEY;
+  if (value === undefined) delete process.env.OMNIROUTE_API_KEY;
+  else process.env.OMNIROUTE_API_KEY = value;
+  try {
+    return fn();
+  } finally {
+    if (original === undefined) delete process.env.OMNIROUTE_API_KEY;
+    else process.env.OMNIROUTE_API_KEY = original;
+  }
+}
+
+test("setup-opencode: --api-key typed AFTER the subcommand name is not stolen by the parent program's global option", async () => {
+  const { createProgram } = await import("../../bin/cli/program.mjs");
+  const program = createProgram();
+  const setupOpencode = program.commands.find((c) => c.name() === "setup-opencode");
+  assert.ok(setupOpencode, "setup-opencode subcommand must be registered");
+
+  let capturedApiKey;
+  setupOpencode._actionHandler = null; // avoid the real network-calling action
+  setupOpencode.action((opts, cmd) => {
+    capturedApiKey = cmd.optsWithGlobals().apiKey ?? opts.apiKey;
+  });
+
+  await program.parseAsync(
+    [
+      "node",
+      "omniroute",
+      "setup-opencode",
+      "--remote",
+      "http://100.64.0.1:20128",
+      "--api-key",
+      "sk-TESTKEY123",
+    ],
+    { from: "node" }
+  );
+
+  assert.equal(
+    capturedApiKey,
+    "sk-TESTKEY123",
+    "the CLI-supplied --api-key value must reach the setup-opencode action handler"
+  );
+});
+
+test("resolveOpencodeTarget: (a) explicit --api-key flag wins over an active context's management token", () => {
+  withEnvApiKey(undefined, () => {
+    withIsolatedContext(
+      { baseUrl: "http://100.64.0.1:20128", accessToken: "oma_live_CONTEXT_TOKEN" },
+      () => {
+        const { apiKey } = resolveOpencodeTarget({ apiKey: "sk-FLAG", context: "remote" });
+        assert.equal(apiKey, "sk-FLAG");
+      }
+    );
+  });
+});
+
+test("resolveOpencodeTarget: (b) OMNIROUTE_API_KEY env wins over an active context's management token when no flag is passed", () => {
+  withEnvApiKey("sk-ENVKEY", () => {
+    withIsolatedContext(
+      { baseUrl: "http://100.64.0.1:20128", accessToken: "oma_live_CONTEXT_TOKEN" },
+      () => {
+        const { apiKey } = resolveOpencodeTarget({ context: "remote" });
+        assert.equal(apiKey, "sk-ENVKEY");
+      }
+    );
+  });
+});
+
+test("resolveOpencodeTarget: (c) the context's token is used only when neither a flag nor the env var is set", () => {
+  withEnvApiKey(undefined, () => {
+    withIsolatedContext(
+      { baseUrl: "http://100.64.0.1:20128", accessToken: "oma_live_CONTEXT_TOKEN" },
+      () => {
+        const { apiKey } = resolveOpencodeTarget({ context: "remote" });
+        assert.equal(apiKey, "oma_live_CONTEXT_TOKEN");
+      }
+    );
+  });
+});
+
+test("resolveOpencodeTarget: falls back to '' when neither a flag, env var, nor a resolvable context is present", () => {
+  withEnvApiKey(undefined, () => {
+    withIsolatedContext({ baseUrl: "http://100.64.0.1:20128" }, () => {
+      const { apiKey } = resolveOpencodeTarget({
+        remote: "http://100.64.0.1:20128",
+        context: "__no-such-context__",
+      });
+      assert.equal(apiKey, "");
+    });
+  });
+});