terramend 0.2.0

package/src/utils/apiKeys.test.ts

@@ -0,0 +1,344 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  formatApiKeyErrorSummary,
+  isApiKeyAuthError,
+  validateAgentApiKey,
+} from "#app/utils/apiKeys";
+
+const savedEnv = { ...process.env };
+
+const ENV_KEYS_TO_STRIP = [
+  /_API_KEY$/,
+  /^CLAUDE_CODE_OAUTH_TOKEN$/,
+  /^CODEX_AUTH_JSON$/,
+  /^AWS_BEARER_TOKEN_BEDROCK$/,
+  /^AWS_ACCESS_KEY_ID$/,
+  /^AWS_SECRET_ACCESS_KEY$/,
+  /^AWS_SESSION_TOKEN$/,
+  /^AWS_REGION$/,
+  /^BEDROCK_MODEL_ID$/,
+  /^GOOGLE_APPLICATION_CREDENTIALS$/,
+  /^GOOGLE_CLOUD_PROJECT$/,
+  /^VERTEX_SERVICE_ACCOUNT_JSON$/,
+  /^VERTEX_LOCATION$/,
+  /^VERTEX_MODEL_ID$/,
+];
+
+beforeEach(() => {
+  for (const key of Object.keys(process.env)) {
+    if (ENV_KEYS_TO_STRIP.some((re) => re.test(key))) delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  process.env = { ...savedEnv };
+});
+
+const opencode = { name: "opencode" };
+const claude = { name: "claude" };
+const owner = "test-owner";
+const name = "test-repo";
+
+describe("validateAgentApiKey — opencode", () => {
+  it("passes when the resolved model is in the authorized set", () => {
+    expect(() =>
+      validateAgentApiKey({
+        agent: opencode,
+        model: "anthropic/claude-opus-4-7",
+        authorized: new Set(["anthropic/claude-opus-4-7"]),
+        owner,
+        name,
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws when the resolved model is absent from the authorized set", () => {
+    expect(() =>
+      validateAgentApiKey({
+        agent: opencode,
+        model: "anthropic/claude-opus-4-7",
+        authorized: new Set(),
+        owner,
+        name,
+      }),
+    ).toThrow("no API key found");
+  });
+
+  it("passes the auto-select path when the authorized set is non-empty", () => {
+    expect(() =>
+      validateAgentApiKey({
+        agent: opencode,
+        model: undefined,
+        authorized: new Set(["opencode/big-pickle"]),
+        owner,
+        name,
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws the auto-select path when the authorized set is empty", () => {
+    expect(() =>
+      validateAgentApiKey({
+        agent: opencode,
+        model: undefined,
+        authorized: new Set(),
+        owner,
+        name,
+      }),
+    ).toThrow("no API key found");
+  });
+});
+
+describe("validateAgentApiKey — claude (static Anthropic check)", () => {
+  it("passes when ANTHROPIC_API_KEY is set", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    expect(() =>
+      validateAgentApiKey({
+        agent: claude,
+        model: "anthropic/claude-opus-4-7",
+        authorized: new Set(),
+        owner,
+        name,
+      }),
+    ).not.toThrow();
+  });
+
+  it("passes when CLAUDE_CODE_OAUTH_TOKEN is set", () => {
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-test";
+    expect(() =>
+      validateAgentApiKey({
+        agent: claude,
+        model: "anthropic/claude-opus-4-7",
+        authorized: new Set(),
+        owner,
+        name,
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws when neither Anthropic credential is set", () => {
+    expect(() =>
+      validateAgentApiKey({
+        agent: claude,
+        model: "anthropic/claude-opus-4-7",
+        authorized: new Set(),
+        owner,
+        name,
+      }),
+    ).toThrow("no API key found");
+  });
+});
+
+describe("validateAgentApiKey — Bedrock routing", () => {
+  const params = { agent: opencode, authorized: new Set<string>(), owner, name };
+
+  it("passes with AWS_BEARER_TOKEN_BEDROCK + AWS_REGION + BEDROCK_MODEL_ID", () => {
+    process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+    process.env.AWS_REGION = "eu-west-2";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).not.toThrow();
+  });
+
+  it("passes with AWS access keys + region + model id", () => {
+    process.env.AWS_ACCESS_KEY_ID = "AKIA-test";
+    process.env.AWS_SECRET_ACCESS_KEY = "secret-test";
+    process.env.AWS_REGION = "eu-west-2";
+    process.env.BEDROCK_MODEL_ID = "amazon.nova-pro-v1:0";
+    expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).not.toThrow();
+  });
+
+  it("throws when BEDROCK_MODEL_ID is missing", () => {
+    process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+    process.env.AWS_REGION = "eu-west-2";
+    expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).toThrow(
+      "BEDROCK_MODEL_ID",
+    );
+  });
+
+  // regression: main.ts passes the post-resolveModel value into
+  // validateAgentApiKey, which for Bedrock is the raw AWS model ID (no `/`).
+  it("accepts a raw Bedrock model ID without throwing", () => {
+    process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+    process.env.AWS_REGION = "eu-west-2";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-6-v1";
+    expect(() =>
+      validateAgentApiKey({ ...params, model: "eu.anthropic.claude-opus-4-6-v1" }),
+    ).not.toThrow();
+  });
+
+  it("throws on raw Bedrock model ID when AWS auth is missing", () => {
+    process.env.AWS_REGION = "eu-west-2";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-6-v1";
+    expect(() =>
+      validateAgentApiKey({ ...params, model: "eu.anthropic.claude-opus-4-6-v1" }),
+    ).toThrow("AWS_BEARER_TOKEN_BEDROCK");
+  });
+});
+
+describe("validateAgentApiKey — Vertex routing", () => {
+  const params = { agent: opencode, authorized: new Set<string>(), owner, name };
+
+  it("passes with service-account JSON + project + location + model id", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+    process.env.GOOGLE_CLOUD_PROJECT = "test-project";
+    process.env.VERTEX_LOCATION = "europe-west2";
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).not.toThrow();
+  });
+
+  it("throws when VERTEX_MODEL_ID is missing", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+    process.env.GOOGLE_CLOUD_PROJECT = "test-project";
+    process.env.VERTEX_LOCATION = "europe-west2";
+    expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).toThrow(
+      "VERTEX_MODEL_ID",
+    );
+  });
+
+  it("accepts a raw Vertex model ID without throwing", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = "{}";
+    process.env.GOOGLE_CLOUD_PROJECT = "test-project";
+    process.env.VERTEX_LOCATION = "europe-west2";
+    process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
+    expect(() => validateAgentApiKey({ ...params, model: "gemini-2.5-pro" })).not.toThrow();
+  });
+
+  it("throws on raw Vertex model ID when auth is missing", () => {
+    process.env.GOOGLE_CLOUD_PROJECT = "test-project";
+    process.env.VERTEX_LOCATION = "europe-west2";
+    process.env.VERTEX_MODEL_ID = "gemini-2.5-pro";
+    expect(() => validateAgentApiKey({ ...params, model: "gemini-2.5-pro" })).toThrow(
+      "VERTEX_SERVICE_ACCOUNT_JSON",
+    );
+  });
+});
+
+describe("validateAgentApiKey — claude auto-select (no model)", () => {
+  it("passes when ANTHROPIC_API_KEY is set", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    expect(() =>
+      validateAgentApiKey({ agent: claude, model: undefined, authorized: new Set(), owner, name }),
+    ).not.toThrow();
+  });
+
+  it("passes when CLAUDE_CODE_OAUTH_TOKEN is set", () => {
+    process.env.CLAUDE_CODE_OAUTH_TOKEN = "oauth-test";
+    expect(() =>
+      validateAgentApiKey({ agent: claude, model: undefined, authorized: new Set(), owner, name }),
+    ).not.toThrow();
+  });
+
+  it("throws when neither Anthropic credential is set", () => {
+    expect(() =>
+      validateAgentApiKey({ agent: claude, model: undefined, authorized: new Set(), owner, name }),
+    ).toThrow("no API key found");
+  });
+});
+
+describe("validateAgentApiKey — Bedrock auth shape edge cases", () => {
+  const params = { agent: opencode, authorized: new Set<string>(), owner, name };
+
+  it("treats an access key without its secret as missing auth", () => {
+    process.env.AWS_ACCESS_KEY_ID = "AKIA-test";
+    process.env.AWS_REGION = "eu-west-2";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).toThrow(
+      "AWS_BEARER_TOKEN_BEDROCK (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)",
+    );
+  });
+
+  it("lists AWS_REGION when only the region is missing", () => {
+    process.env.AWS_BEARER_TOKEN_BEDROCK = "bedrock-token";
+    process.env.BEDROCK_MODEL_ID = "eu.anthropic.claude-opus-4-7";
+    expect(() => validateAgentApiKey({ ...params, model: "bedrock/byok" })).toThrow("AWS_REGION");
+  });
+});
+
+describe("validateAgentApiKey — Vertex project resolution", () => {
+  const params = { agent: opencode, authorized: new Set<string>(), owner, name };
+
+  it("accepts the project id embedded in the service-account JSON", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = '{"project_id":"embedded-project"}';
+    process.env.VERTEX_LOCATION = "europe-west2";
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).not.toThrow();
+  });
+
+  it("lists VERTEX_LOCATION when only the location is missing", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = '{"project_id":"embedded-project"}';
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).toThrow(
+      "VERTEX_LOCATION",
+    );
+  });
+
+  it("lists GOOGLE_CLOUD_PROJECT when neither env nor the JSON carries a project id", () => {
+    process.env.VERTEX_SERVICE_ACCOUNT_JSON = '{"client_email":"sa@example.iam"}';
+    process.env.VERTEX_LOCATION = "europe-west2";
+    process.env.VERTEX_MODEL_ID = "claude-opus-4-1@20250805";
+    expect(() => validateAgentApiKey({ ...params, model: "vertex/byok" })).toThrow(
+      "GOOGLE_CLOUD_PROJECT",
+    );
+  });
+});
+
+describe("isApiKeyAuthError", () => {
+  it("matches the missing-key marker thrown by validateAgentApiKey", () => {
+    expect(isApiKeyAuthError("no API key found. Terramend needs ...")).toBe(true);
+  });
+
+  it("matches Claude CLI 401 strings", () => {
+    expect(isApiKeyAuthError("Invalid API key · Fix external API key")).toBe(true);
+  });
+
+  it("matches OpenAI / OpenRouter 401 phrasings", () => {
+    expect(isApiKeyAuthError("ProviderAuthError: User not found")).toBe(true);
+    expect(isApiKeyAuthError("401 Invalid authentication")).toBe(true);
+  });
+
+  // see #782 — direct-Anthropic 401 shape (revoked / mistyped / rotated
+  // ANTHROPIC_API_KEY) reaches us via Claude CLI as a JSON dump, not as
+  // any of the canonical "Invalid API key" strings.
+  it("matches direct-Anthropic 401 shapes", () => {
+    expect(
+      isApiKeyAuthError(
+        'Failed to authenticate. API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid bearer token"}}',
+      ),
+    ).toBe(true);
+    expect(
+      isApiKeyAuthError(
+        "» Terramend result error: subtype=success, api_error_status=401, message=Failed to authenticate.",
+      ),
+    ).toBe(true);
+  });
+
+  it("ignores unrelated errors", () => {
+    expect(isApiKeyAuthError("git fetch failed")).toBe(false);
+    expect(isApiKeyAuthError("")).toBe(false);
+  });
+});
+
+describe("formatApiKeyErrorSummary", () => {
+  it("renders the missing-key body when the raw error contains the marker", () => {
+    const msg = formatApiKeyErrorSummary({
+      owner: "acme",
+      name: "repo",
+      raw: "no API key found in this run",
+    });
+    expect(msg).toContain("no API key found");
+    expect(msg).toContain("https://github.com/acme/repo/settings/secrets/actions");
+    expect(msg).toContain("/console/acme/repo");
+    expect(msg).toContain("https://discord.gg/8y96raFg8e");
+  });
+
+  it("renders the invalid-key body for any other auth error", () => {
+    const msg = formatApiKeyErrorSummary({
+      owner: "acme",
+      name: "repo",
+      raw: "Invalid API key · Fix external API key",
+    });
+    expect(msg).toContain("rejected (401)");
+    expect(msg).toContain("https://github.com/acme/repo/settings/secrets/actions");
+    expect(msg).toContain("https://discord.gg/8y96raFg8e");
+  });
+});

package/src/utils/apiKeys.ts

@@ -0,0 +1,206 @@
+import { BEDROCK_MODEL_ID_ENV, resolveDisplayAlias, VERTEX_MODEL_ID_ENV } from "#app/models";
+import { getApiUrl } from "#app/utils/apiUrl";
+import {
+  GOOGLE_CLOUD_PROJECT_ENV,
+  readProjectIdFromVertexServiceAccountJson,
+  VERTEX_LOCATION_ENV,
+  VERTEX_SERVICE_ACCOUNT_JSON_ENV,
+} from "#app/utils/vertex";
+
+/** marker prefix on the throw message for the catch-side reclassification path */
+const MISSING_KEY_MARKER = "no API key found";
+
+/** Markdown body used for both the thrown error and the formatted PR comment summary. */
+function buildMissingApiKeyError(params: { owner: string; name: string }): string {
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+  const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
+
+  return [
+    `**${MISSING_KEY_MARKER}** — Terramend needs at least one LLM provider API key (e.g. \`ANTHROPIC_API_KEY\`, \`OPENAI_API_KEY\`, \`GEMINI_API_KEY\`) configured as a GitHub Actions secret.`,
+    "",
+    `[Open repo secrets →](${githubSecretsUrl}) · [Configure model →](${settingsUrl}) · [Setup docs →](https://docs.terramend.com/keys) · [Ask in Discord →](https://discord.gg/8y96raFg8e)`,
+  ].join("\n");
+}
+
+function buildBedrockSetupError(params: {
+  owner: string;
+  name: string;
+  missing: string[];
+}): string {
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+
+  return `Bedrock model selected but required configuration is missing: ${params.missing.join(", ")}.
+
+add the missing secret(s) to your GitHub repository at ${githubSecretsUrl}, then reference them in your workflow's \`env:\` block:
+
+  AWS_BEARER_TOKEN_BEDROCK: \${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
+  AWS_REGION: \${{ secrets.AWS_REGION }}
+  ${BEDROCK_MODEL_ID_ENV}: \${{ secrets.${BEDROCK_MODEL_ID_ENV} }}
+
+\`AWS_BEARER_TOKEN_BEDROCK\` may be substituted with \`AWS_ACCESS_KEY_ID\` + \`AWS_SECRET_ACCESS_KEY\` (and optional \`AWS_SESSION_TOKEN\`) if you prefer access keys.
+
+for full setup instructions, see https://docs.terramend.com/bedrock`;
+}
+
+function buildVertexSetupError(params: { owner: string; name: string; missing: string[] }): string {
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+
+  return `Google Vertex AI model selected but required configuration is missing: ${params.missing.join(", ")}.
+
+add the missing secret(s) to your GitHub repository at ${githubSecretsUrl}, then reference them in your workflow's \`env:\` block:
+
+  ${VERTEX_SERVICE_ACCOUNT_JSON_ENV}: \${{ secrets.${VERTEX_SERVICE_ACCOUNT_JSON_ENV} }}
+  ${GOOGLE_CLOUD_PROJECT_ENV}: my-project
+  ${VERTEX_LOCATION_ENV}: global
+  ${VERTEX_MODEL_ID_ENV}: <vertex-model-id>
+
+for full setup instructions, see https://docs.terramend.com/vertex`;
+}
+
+function hasEnvVar(name: string): boolean {
+  const value = process.env[name];
+  return typeof value === "string" && value.length > 0;
+}
+
+function validateBedrockSetup(params: { owner: string; name: string }): void {
+  const hasAuth =
+    hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") ||
+    (hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY"));
+
+  const missing: string[] = [];
+  if (!hasAuth)
+    missing.push("AWS_BEARER_TOKEN_BEDROCK (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)");
+  if (!hasEnvVar("AWS_REGION")) missing.push("AWS_REGION");
+  if (!hasEnvVar(BEDROCK_MODEL_ID_ENV)) missing.push(BEDROCK_MODEL_ID_ENV);
+
+  if (missing.length > 0) {
+    throw new Error(buildBedrockSetupError({ owner: params.owner, name: params.name, missing }));
+  }
+}
+
+function validateVertexSetup(params: { owner: string; name: string }): void {
+  const hasAuth = hasEnvVar(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
+  const hasProject =
+    hasEnvVar(GOOGLE_CLOUD_PROJECT_ENV) ||
+    readProjectIdFromVertexServiceAccountJson() !== undefined;
+
+  const missing: string[] = [];
+  if (!hasAuth) missing.push(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
+  if (!hasProject) missing.push(GOOGLE_CLOUD_PROJECT_ENV);
+  if (!hasEnvVar(VERTEX_LOCATION_ENV)) missing.push(VERTEX_LOCATION_ENV);
+  if (!hasEnvVar(VERTEX_MODEL_ID_ENV)) missing.push(VERTEX_MODEL_ID_ENV);
+
+  if (missing.length > 0) {
+    throw new Error(buildVertexSetupError({ owner: params.owner, name: params.name, missing }));
+  }
+}
+
+/**
+ * Validate that the resolved model can actually be served by the chosen
+ * agent. For routing slugs (Bedrock / Vertex) the auth shape is multi-var
+ * (auth + region/location + model-id) and `opencode models` doesn't catch
+ * gaps in the latter two — keep dedicated setup validators. For the
+ * opencode path, the authoritative answer comes from OpenCode's own model
+ * introspection (`authorized` set captured in `openCodeModels.ts`). For
+ * the claude path, fall back to the static check (`ANTHROPIC_API_KEY` /
+ * `CLAUDE_CODE_OAUTH_TOKEN`).
+ */
+export function validateAgentApiKey(params: {
+  agent: { name: string };
+  model: string | undefined;
+  authorized: Set<string>;
+  owner: string;
+  name: string;
+}): void {
+  if (params.model) {
+    const alias = resolveDisplayAlias(params.model);
+    if (alias?.routing === "bedrock") {
+      validateBedrockSetup({ owner: params.owner, name: params.name });
+      return;
+    }
+    if (alias?.routing === "vertex") {
+      validateVertexSetup({ owner: params.owner, name: params.name });
+      return;
+    }
+
+    // raw backend model IDs (post-resolveModel for routing slugs) have no
+    // `/`. discriminate by the env-var sentinel, then run the matching
+    // setup validator — `opencode models` doesn't help here because the
+    // Bedrock/Vertex provider plugins need region/location/model-id wired
+    // through env regardless of CLI-side auth.
+    if (!params.model.includes("/")) {
+      if (process.env[VERTEX_MODEL_ID_ENV]?.trim() === params.model) {
+        validateVertexSetup({ owner: params.owner, name: params.name });
+        return;
+      }
+      validateBedrockSetup({ owner: params.owner, name: params.name });
+      return;
+    }
+
+    if (params.agent.name === "opencode") {
+      if (params.authorized.has(params.model)) return;
+      throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
+    }
+
+    // claude: single-provider check on the Anthropic auth shapes.
+    if (hasEnvVar("ANTHROPIC_API_KEY") || hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN")) return;
+    throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
+  }
+
+  // no model configured (auto-select path).
+  if (params.agent.name === "opencode") {
+    if (params.authorized.size > 0) return;
+    throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
+  }
+  if (hasEnvVar("ANTHROPIC_API_KEY") || hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN")) return;
+  throw new Error(buildMissingApiKeyError({ owner: params.owner, name: params.name }));
+}
+
+/**
+ * Detect agent-runtime auth failures that should be reformatted as an actionable
+ * key-fix CTA before being shown to the user. Covers the shapes we see:
+ *   - missing key (validateAgentApiKey throw): contains MISSING_KEY_MARKER
+ *   - revoked / invalid key (Claude CLI 401 surfaced via api_error_status):
+ *     "Invalid API key · Fix external API key" + similar provider variants
+ *   - direct-Anthropic 401 (`Failed to authenticate. API Error: 401 ...
+ *     {"type":"error","error":{"type":"authentication_error", ...
+ *     "Invalid bearer token"}}`) emitted by the Claude CLI for revoked /
+ *     mistyped / rotated `ANTHROPIC_API_KEY`. see #782.
+ */
+export function isApiKeyAuthError(text: string): boolean {
+  if (!text) return false;
+  return (
+    text.includes(MISSING_KEY_MARKER) ||
+    /Invalid API key/i.test(text) ||
+    /\bUser not found\b/i.test(text) ||
+    /\bInvalid authentication\b/i.test(text) ||
+    /authentication_error/i.test(text) ||
+    /Invalid bearer token/i.test(text) ||
+    /api_error_status\s*=\s*401/i.test(text) ||
+    /API Error:\s*401/i.test(text)
+  );
+}
+
+/**
+ * Friendly Markdown summary for both the missing-key and invalid-key cases.
+ * Used in the catch / result-failure paths in `main.ts` to overwrite the raw
+ * agent error before it's posted to the PR progress comment.
+ */
+export function formatApiKeyErrorSummary(params: {
+  owner: string;
+  name: string;
+  raw: string;
+}): string {
+  if (params.raw.includes(MISSING_KEY_MARKER)) {
+    return buildMissingApiKeyError({ owner: params.owner, name: params.name });
+  }
+
+  const githubSecretsUrl = `https://github.com/${params.owner}/${params.name}/settings/secrets/actions`;
+  const settingsUrl = `${getApiUrl()}/console/${params.owner}/${params.name}`;
+
+  return [
+    `**Your LLM provider API key was rejected (401).** Rotate the key in your provider dashboard, then update the matching GitHub Actions secret.`,
+    "",
+    `[Update repo secret →](${githubSecretsUrl}) · [Model settings →](${settingsUrl}) · [Setup docs →](https://docs.terramend.com/keys) · [Ask in Discord →](https://discord.gg/8y96raFg8e)`,
+  ].join("\n");
+}

package/src/utils/apiUrl.test.ts

@@ -0,0 +1,30 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { isBackendConfigured } from "#app/utils/apiUrl";
+
+describe("isBackendConfigured", () => {
+  let saved: string | undefined;
+
+  beforeEach(() => {
+    saved = process.env.API_URL;
+  });
+
+  afterEach(() => {
+    if (saved === undefined) delete process.env.API_URL;
+    else process.env.API_URL = saved;
+  });
+
+  it("is false when API_URL is unset (standalone BYOK — dormant seams no-op)", () => {
+    delete process.env.API_URL;
+    expect(isBackendConfigured()).toBe(false);
+  });
+
+  it("is false for an empty API_URL", () => {
+    process.env.API_URL = "";
+    expect(isBackendConfigured()).toBe(false);
+  });
+
+  it("is true when API_URL points at a real backend (hosted SaaS / local dev)", () => {
+    process.env.API_URL = "http://localhost:3000";
+    expect(isBackendConfigured()).toBe(true);
+  });
+});

package/src/utils/apiUrl.ts

@@ -0,0 +1,59 @@
+import { log } from "#app/utils/cli";
+
+function isLocalUrl(url: URL): boolean {
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1";
+}
+
+// The Terramend JWT (apiToken) and codex write-back secret travel as
+// `Authorization: Bearer` to this host. Pin it to a known allowlist so a
+// misconfigured/hostile `API_URL` can't redirect those bearer credentials to
+// an attacker-controlled host (https alone is not enough — it must be the right
+// host). localhost stays exempt for local dev.
+function isAllowedApiHost(url: URL): boolean {
+  if (isLocalUrl(url)) return true;
+  const host = url.hostname.toLowerCase();
+  return host === "terramend.dev" || host.endsWith(".terramend.com");
+}
+
+/**
+ * resolve the Terramend API base URL.
+ *
+ * in the action: API_URL is not explicitly set, so this falls back to https://terramend.com.
+ * in local dev: API_URL=http://localhost:3000 (from .env).
+ *
+ * enforces https:// for non-local URLs to prevent cleartext credential transmission.
+ */
+export function getApiUrl(): string {
+  const raw = process.env.API_URL || "https://terramend.dev";
+  const parsed = new URL(raw);
+
+  if (parsed.protocol !== "https:" && !isLocalUrl(parsed)) {
+    throw new Error(
+      `API_URL must use https:// (got ${parsed.protocol}). only localhost is exempt.`,
+    );
+  }
+
+  if (!isAllowedApiHost(parsed)) {
+    throw new Error(
+      `API_URL host '${parsed.hostname}' is not allowed. ` +
+        `Bearer credentials are only sent to terramend.dev (or a *.terramend.com host) or localhost.`,
+    );
+  }
+
+  log.debug(`resolved API_URL: ${raw}`);
+  return raw;
+}
+
+/**
+ * Whether a real Terramend backend is configured.
+ *
+ * Standalone BYOK runs (the OSS default) leave `API_URL` unset — `getApiUrl`
+ * then falls back to the marketing host, which serves no API. The dormant
+ * open-core persistence seams (repo learnings, run-field PATCHes) must no-op
+ * in that case rather than POST into the void and surface the host's 404 as a
+ * CI warning. A real backend — the hosted SaaS, or local dev with
+ * `API_URL=http://localhost:3000` — sets `API_URL` explicitly.
+ */
+export function isBackendConfigured(): boolean {
+  return Boolean(process.env.API_URL);
+}