terramend 0.2.0

package/src/utils/agent.ts

@@ -0,0 +1,139 @@
+import type { Agent } from "#app/agents/index";
+import { agents } from "#app/agents/index";
+import {
+  BEDROCK_MODEL_ID_ENV,
+  getModelProvider,
+  isBedrockAnthropicId,
+  isVertexAnthropicId,
+  resolveCliModel,
+  resolveDisplayAlias,
+  VERTEX_MODEL_ID_ENV,
+} from "#app/models";
+import { log } from "#app/utils/cli";
+import { VERTEX_SERVICE_ACCOUNT_JSON_ENV } from "#app/utils/vertex";
+
+function hasEnvVar(name: string): boolean {
+  const val = process.env[name];
+  return typeof val === "string" && val.length > 0;
+}
+
+function hasClaudeCodeAuth(): boolean {
+  return hasEnvVar("CLAUDE_CODE_OAUTH_TOKEN") || hasEnvVar("ANTHROPIC_API_KEY");
+}
+
+function hasBedrockAuth(): boolean {
+  return (
+    hasEnvVar("AWS_BEARER_TOKEN_BEDROCK") ||
+    (hasEnvVar("AWS_ACCESS_KEY_ID") && hasEnvVar("AWS_SECRET_ACCESS_KEY"))
+  );
+}
+
+function hasVertexAuth(): boolean {
+  return hasEnvVar(VERTEX_SERVICE_ACCOUNT_JSON_ENV);
+}
+
+/**
+ * resolve a single slug to its CLI-ready model string. routing aliases
+ * (e.g. `bedrock/byok`) defer to their backing env var instead of the
+ * sentinel stored in `resolve`. shared between TERRAMEND_MODEL override
+ * and repo-config slug resolution so both paths get the same routing
+ * semantics — without this helper, `TERRAMEND_MODEL=bedrock/byok` would
+ * leak the literal sentinel string `"bedrock"` downstream.
+ */
+function resolveSlug(slug: string): string | undefined {
+  const alias = resolveDisplayAlias(slug);
+  if (alias?.routing === "bedrock") {
+    const bedrockId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    if (!bedrockId) {
+      throw new Error(
+        `${BEDROCK_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
+          `set it to an AWS Bedrock model ID from the Bedrock console. ` +
+          `see https://docs.terramend.com/bedrock for setup.`,
+      );
+    }
+    return bedrockId;
+  }
+  if (alias?.routing === "vertex") {
+    const vertexId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
+    if (!vertexId) {
+      throw new Error(
+        `${VERTEX_MODEL_ID_ENV} env var is required when the model is set to "${slug}". ` +
+          `set it to a Google Vertex AI model ID from Model Garden. ` +
+          `see https://docs.terramend.com/vertex for setup.`,
+      );
+    }
+    return vertexId;
+  }
+  return resolveCliModel(slug);
+}
+
+/**
+ * resolve the effective model for this run.
+ *
+ * priority:
+ *   1. TERRAMEND_MODEL env var — resolved through the alias registry first,
+ *      so values like "anthropic/claude-opus" become "anthropic/claude-opus-4-7".
+ *      raw specifiers (e.g. "anthropic/claude-opus-4-6") pass through unchanged.
+ *      always wins — bypasses Bedrock routing entirely. to test a different
+ *      Bedrock model, change `BEDROCK_MODEL_ID`, not `TERRAMEND_MODEL`.
+ *   2. slug from repo config / payload → alias registry. routing slugs
+ *      (e.g. `bedrock/byok`) defer to a separate env var (`BEDROCK_MODEL_ID`).
+ *   3. undefined — agent will auto-select.
+ */
+export function resolveModel(ctx: { slug?: string | undefined }): string | undefined {
+  const envModel = process.env.TERRAMEND_MODEL?.trim();
+  if (envModel) {
+    return resolveSlug(envModel) ?? envModel;
+  }
+
+  if (ctx.slug) {
+    const resolved = resolveSlug(ctx.slug);
+    if (resolved) {
+      return resolved;
+    }
+    log.warning(`» unknown model slug "${ctx.slug}" — agent will auto-select`);
+  }
+
+  return undefined;
+}
+
+export function resolveAgent(ctx: { model?: string | undefined }): Agent {
+  // 1. explicit env var override (escape hatch)
+  const envAgent = process.env.TERRAMEND_AGENT?.trim();
+  if (envAgent) {
+    if (envAgent in agents) {
+      return agents[envAgent as keyof typeof agents];
+    }
+    log.warning(`» unknown TERRAMEND_AGENT="${envAgent}" — falling through to auto-select`);
+  }
+
+  // 2. Bedrock routing: when BEDROCK_MODEL_ID is the resolved model, route
+  //    Anthropic IDs through claude-code (which supports Bedrock natively
+  //    once CLAUDE_CODE_USE_BEDROCK=1) and everything else through opencode's
+  //    `amazon-bedrock` provider.
+  if (ctx.model && hasBedrockAuth() && process.env[BEDROCK_MODEL_ID_ENV]?.trim() === ctx.model) {
+    return isBedrockAnthropicId(ctx.model) ? agents.claude : agents.opencode;
+  }
+
+  // 3. Vertex routing: same shape as Bedrock, but Anthropic Vertex IDs are
+  //    anchored `claude-*` IDs and non-Anthropic models use opencode's
+  //    `google-vertex` provider.
+  if (ctx.model && hasVertexAuth() && process.env[VERTEX_MODEL_ID_ENV]?.trim() === ctx.model) {
+    return isVertexAnthropicId(ctx.model) ? agents.claude : agents.opencode;
+  }
+
+  // 4. if model is Anthropic and Claude Code credentials are available, use Claude Code
+  if (ctx.model) {
+    try {
+      const provider = getModelProvider(ctx.model);
+      if (provider === "anthropic" && hasClaudeCodeAuth()) {
+        return agents.claude;
+      }
+    } catch {
+      // invalid model format — fall through
+    }
+  }
+
+  // 5. default: OpenCode (universal, supports all providers)
+  return agents.opencode;
+}

package/src/utils/agentHangReport.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import { type AgentDiagnostic, formatAgentHangBody } from "#app/utils/agentHangReport";
+
+function makeDiagnostic(overrides: Partial<AgentDiagnostic> = {}): AgentDiagnostic {
+  return {
+    label: "Terramend",
+    recentStderr: [],
+    lastProviderError: undefined,
+    eventCount: 0,
+    ...overrides,
+  };
+}
+
+describe("formatAgentHangBody", () => {
+  it("returns null when no diagnostic is available", () => {
+    const body = formatAgentHangBody({
+      diagnostic: undefined,
+      isHang: true,
+      errorMessage: "activity timeout: no output for 301s",
+    });
+    expect(body).toBeNull();
+  });
+
+  it("renders a hang headline with parsed idle seconds", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ eventCount: 12 }),
+      isHang: true,
+      errorMessage: "activity timeout: no output for 301s",
+    });
+    expect(body).toContain("**Terramend stalled**");
+    expect(body).toContain("stopped emitting events for 301s");
+    expect(body).toContain("12 events were processed before the failure.");
+  });
+
+  it("falls back to a generic hang explanation when idle seconds cannot be parsed", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ eventCount: 3 }),
+      isHang: true,
+      errorMessage: "watchdog fired",
+    });
+    expect(body).toContain(
+      "The agent stopped emitting events and was killed by the activity-timeout watchdog.",
+    );
+  });
+
+  it("renders a failure headline with the raw error for non-hang exits", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ eventCount: 1 }),
+      isHang: false,
+      errorMessage: "spawn exited with code 7",
+    });
+    expect(body).toContain("**Terramend failed**");
+    expect(body).toContain("The agent exited unexpectedly: spawn exited with code 7");
+  });
+
+  it("includes the provider-error label as a likely cause in the headline", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ lastProviderError: "provider auth error" }),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).toContain("— likely cause: `provider auth error`");
+    // labeled cause suppresses the reachability nudge for zero-event runs
+    expect(body).toContain("No events were emitted before the failure.");
+    expect(body).not.toContain("check whether the model provider is reachable");
+  });
+
+  it("nudges about provider reachability when zero events and no provider label", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic(),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).toContain(
+      "No events were emitted — check whether the model provider is reachable.",
+    );
+  });
+
+  it("omits the stderr details block when no stderr was captured", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic(),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).not.toContain("<details>");
+  });
+
+  it("renders captured stderr inside a fenced details block", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ recentStderr: ["line one", "line two"] }),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).toContain("<details><summary>Recent agent stderr</summary>");
+    expect(body).toContain("line one\nline two");
+    expect(body).toContain("```");
+  });
+
+  it("escalates the fence beyond the longest backtick run in stderr", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ recentStderr: ["payload with ````` five backticks"] }),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).toContain("``````\npayload with ````` five backticks\n``````");
+  });
+
+  it("truncates stderr tails beyond the byte cap and marks the truncation", () => {
+    const longLine = "x".repeat(1000);
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ recentStderr: [longLine, longLine, longLine, longLine] }),
+      isHang: true,
+      errorMessage: "no output for 60s",
+    });
+    expect(body).toContain("... (older lines truncated)");
+    // the rendered tail is bounded: cap + truncation banner + surrounding markdown
+    expect(body).toBeTypeOf("string");
+    if (body) expect(body.length).toBeLessThan(3600);
+  });
+});
+
+describe("formatAgentHangBody billing-exhausted branch", () => {
+  it("replaces the generic headline with a billing CTA when the label matches", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({ lastProviderError: "provider billing exhausted" }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain("**Terramend stopped**");
+    expect(body).toContain("billing-exhausted response");
+    expect(body).toContain("Top up your model-provider balance");
+    expect(body).not.toContain("stalled");
+  });
+
+  it("links the provider billing url when stderr embeds a known billing host", () => {
+    const url = "https://opencode.ai/settings/billing?from=zen";
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({
+        lastProviderError: "provider billing exhausted",
+        recentStderr: ["some noise", `error: out of credits, visit ${url} to top up`],
+      }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain(`[${url}](${url})`);
+  });
+
+  it("prefers the most recent billing url in the stderr buffer", () => {
+    const older = "https://console.anthropic.com/settings/old";
+    const newer = "https://console.anthropic.com/settings/billing";
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({
+        lastProviderError: "provider billing exhausted",
+        recentStderr: [`see ${older}`, `see ${newer}`],
+      }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain(`[${newer}](${newer})`);
+    // the older url still shows in the stderr tail, but must not be the CTA link
+    expect(body).not.toContain(`[${older}]`);
+  });
+
+  it("ignores urls on non-billing hosts so a stray link cannot pose as the remedy", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({
+        lastProviderError: "provider billing exhausted",
+        recentStderr: ["see https://evil.example.com/billing for details"],
+      }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain("Top up your model-provider balance");
+    // the stray url still shows in the stderr tail, but must not become a CTA link
+    expect(body).not.toContain("[https://evil.example.com");
+  });
+
+  it("matches a google cloud billing console url", () => {
+    const url = "https://console.cloud.google.com/billing/12345";
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({
+        lastProviderError: "provider billing exhausted",
+        recentStderr: [`visit ${url}`],
+      }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain(`[${url}](${url})`);
+  });
+
+  it("includes the stderr details block in the billing body too", () => {
+    const body = formatAgentHangBody({
+      diagnostic: makeDiagnostic({
+        lastProviderError: "provider billing exhausted",
+        recentStderr: ["insufficient balance"],
+      }),
+      isHang: true,
+      errorMessage: "no output for 300s",
+    });
+    expect(body).toContain("<details><summary>Recent agent stderr</summary>");
+    expect(body).toContain("insufficient balance");
+  });
+});

package/src/utils/agentHangReport.ts

@@ -0,0 +1,170 @@
+const MAX_STDERR_BYTES = 3000;
+
+/**
+ * mutable per-run handle the agent harness writes to as a run progresses.
+ * the action's outer try/catch in `main.ts` reads this off `toolState` when
+ * the activity-timeout watchdog wins the race against the harness's own
+ * catch — the bare timer reject reason ("activity timeout: no output for
+ * 302s") tells the user nothing actionable, but `recentStderr` +
+ * `lastProviderError` together usually point straight at the upstream cause.
+ *
+ * `recentStderr` is shared by reference with the harness's bounded ring
+ * buffer, so the diagnostic always reflects the latest captured tail.
+ */
+export type AgentDiagnostic = {
+  /** display label for the agent, e.g. "Terramend". used in the headline. */
+  label: string;
+  /** shared reference to the harness's bounded stderr ring buffer. */
+  recentStderr: string[];
+  /** most-recent provider-error label from `detectProviderError`, if any. */
+  lastProviderError: string | undefined;
+  /** count of stdout events successfully parsed before the failure. */
+  eventCount: number;
+};
+
+/**
+ * Build a user-facing markdown body for an agent hang or failure.
+ *
+ * Rendered into both the PR progress comment and the GitHub Actions job
+ * summary. Returns `null` when no diagnostic is available, which signals to
+ * the caller to fall back to its bare-error rendering.
+ *
+ * `errorMessage` is the underlying timer / spawn reject string (e.g.
+ * `activity timeout: no output for 301s`). The idle seconds are parsed out
+ * of it for the hang explanation — total runtime would overstate the stall
+ * for runs that streamed for a long time before going quiet.
+ */
+export function formatAgentHangBody(input: {
+  diagnostic: AgentDiagnostic | undefined;
+  isHang: boolean;
+  errorMessage: string;
+}): string | null {
+  if (!input.diagnostic) return null;
+
+  // billing exhaustion (CreditsError / FreeUsageLimitError / spending cap /
+  // Insufficient balance) is mis-classified as transient by upstream harnesses
+  // and the run only ends when the activity-timeout watchdog fires (see #778).
+  // when we recognise the billing label, replace the generic "stalled — auth
+  // error" headline with a billing-specific CTA that names the actual remedy.
+  if (input.diagnostic.lastProviderError === "provider billing exhausted") {
+    return formatBillingExhaustedBody(input.diagnostic);
+  }
+
+  const verb = input.isHang ? "stalled" : "failed";
+  const cause = input.diagnostic.lastProviderError
+    ? ` — likely cause: \`${input.diagnostic.lastProviderError}\``
+    : "";
+  const headline = `**${input.diagnostic.label} ${verb}**${cause}`;
+
+  const explanation = formatExplanation({
+    isHang: input.isHang,
+    errorMessage: input.errorMessage,
+  });
+  const parts = [headline, "", `${explanation} ${formatEventsPart(input.diagnostic)}`];
+
+  const tail = renderStderrTail(input.diagnostic.recentStderr);
+  if (tail) {
+    // pick a fence longer than any backtick run in the body so a stderr line
+    // containing ``` (provider error JSON occasionally embeds it) can't
+    // terminate the fence early and corrupt the rest of the markdown.
+    const fence = pickFence(tail);
+    parts.push(
+      "",
+      "<details><summary>Recent agent stderr</summary>",
+      "",
+      fence,
+      tail,
+      fence,
+      "",
+      "</details>",
+    );
+  }
+
+  return parts.join("\n");
+}
+
+function formatExplanation(input: { isHang: boolean; errorMessage: string }): string {
+  if (!input.isHang) return `The agent exited unexpectedly: ${input.errorMessage}`;
+  const idleSec = parseIdleSec(input.errorMessage);
+  if (idleSec === undefined) {
+    return "The agent stopped emitting events and was killed by the activity-timeout watchdog.";
+  }
+  return `The agent stopped emitting events for ${idleSec}s and was killed by the activity-timeout watchdog.`;
+}
+
+function parseIdleSec(message: string): number | undefined {
+  const match = /no output for (\d+)s/.exec(message);
+  return match ? Number(match[1]) : undefined;
+}
+
+function formatEventsPart(diagnostic: AgentDiagnostic): string {
+  if (diagnostic.eventCount > 0) {
+    return `${diagnostic.eventCount} events were processed before the failure.`;
+  }
+  // when the provider-error label already names the cause in the headline,
+  // the reachability nudge below contradicts it (e.g. an immediate 401 also
+  // produces zero events but isn't a reachability problem). suppress it.
+  if (diagnostic.lastProviderError) return "No events were emitted before the failure.";
+  return "No events were emitted — check whether the model provider is reachable.";
+}
+
+function renderStderrTail(lines: readonly string[]): string {
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  if (joined.length <= MAX_STDERR_BYTES) return joined;
+  return `... (older lines truncated)\n${joined.slice(-MAX_STDERR_BYTES)}`;
+}
+
+function pickFence(content: string): string {
+  let max = 0;
+  for (const match of content.matchAll(/`+/g)) {
+    if (match[0].length > max) max = match[0].length;
+  }
+  return "`".repeat(Math.max(3, max + 1));
+}
+
+/**
+ * Pull a billing URL out of the captured stderr if the provider helpfully
+ * embedded one (OpenCode Zen does — Anthropic and Gemini do not). Restricted
+ * to known billing/console hosts so a stray URL elsewhere in the buffer
+ * can't masquerade as the remedy link.
+ */
+function extractBillingUrl(lines: readonly string[]): string | undefined {
+  const urlPattern =
+    /https:\/\/(?:opencode\.ai\/[^\s"]*billing[^\s"]*|console\.anthropic\.com[^\s"]*|console\.cloud\.google\.com[^\s"]*billing[^\s"]*)/i;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = urlPattern.exec(lines[i] ?? "");
+    if (m) return m[0];
+  }
+  return undefined;
+}
+
+function formatBillingExhaustedBody(diagnostic: AgentDiagnostic): string {
+  const headline = `**${diagnostic.label} stopped** — your model provider returned a billing-exhausted response.`;
+
+  const billingUrl = extractBillingUrl(diagnostic.recentStderr);
+  const cta = billingUrl
+    ? `Top up your provider balance, then re-run: [${billingUrl}](${billingUrl})`
+    : "Top up your model-provider balance (or rotate to a key with remaining credits) and re-run.";
+  const explanation =
+    "The agent kept retrying the request because the provider marked the failure as transient. Terramend's activity-timeout watchdog ended the run after no further events were emitted.";
+
+  const parts = [headline, "", explanation, "", cta];
+
+  const tail = renderStderrTail(diagnostic.recentStderr);
+  if (tail) {
+    const fence = pickFence(tail);
+    parts.push(
+      "",
+      "<details><summary>Recent agent stderr</summary>",
+      "",
+      fence,
+      tail,
+      fence,
+      "",
+      "</details>",
+    );
+  }
+
+  return parts.join("\n");
+}

package/src/utils/apiFetch.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { apiFetch } from "#app/utils/apiFetch";
+
+vi.mock("#app/utils/cli", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+type FetchArgs = [string, RequestInit];
+
+function stubFetch(): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+function lastFetchCall(fetchMock: ReturnType<typeof vi.fn>): FetchArgs {
+  const call = fetchMock.mock.calls.at(-1);
+  if (!call) throw new Error("expected fetch to have been called");
+  return call as FetchArgs;
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+describe("apiFetch", () => {
+  it("defaults to GET against the configured API_URL without bypass artifacts", async () => {
+    vi.stubEnv("API_URL", "http://localhost:3000");
+    vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "");
+    const fetchMock = stubFetch();
+
+    await apiFetch({ path: "/api/foo" });
+
+    const [url, init] = lastFetchCall(fetchMock);
+    expect(url).toBe("http://localhost:3000/api/foo");
+    expect(init.method).toBe("GET");
+    expect(init.headers).toEqual({});
+    expect(init.body).toBeUndefined();
+    expect(init.signal).toBeUndefined();
+  });
+
+  it("falls back to https://terramend.dev when API_URL is unset", async () => {
+    vi.stubEnv("API_URL", "");
+    vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "");
+    const fetchMock = stubFetch();
+
+    await apiFetch({ path: "/api/foo" });
+
+    const [url] = lastFetchCall(fetchMock);
+    expect(url).toBe("https://terramend.dev/api/foo");
+  });
+
+  it("adds the Vercel bypass secret as both a query param and a header", async () => {
+    vi.stubEnv("API_URL", "http://localhost:3000");
+    vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "shh");
+    const fetchMock = stubFetch();
+
+    await apiFetch({ path: "/api/foo", method: "POST", body: "{}" });
+
+    const [url, init] = lastFetchCall(fetchMock);
+    expect(new URL(url).searchParams.get("x-vercel-protection-bypass")).toBe("shh");
+    expect(init.headers).toMatchObject({ "x-vercel-protection-bypass": "shh" });
+  });
+
+  it("strips Content-Type headers (any casing) from body-less requests", async () => {
+    vi.stubEnv("API_URL", "http://localhost:3000");
+    vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "");
+    const fetchMock = stubFetch();
+
+    await apiFetch({
+      path: "/api/foo",
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: "Bearer tok" },
+    });
+
+    const [, init] = lastFetchCall(fetchMock);
+    expect(init.headers).toEqual({ Authorization: "Bearer tok" });
+  });
+
+  it("keeps Content-Type and forwards body, method, and signal when a body is present", async () => {
+    vi.stubEnv("API_URL", "http://localhost:3000");
+    vi.stubEnv("VERCEL_AUTOMATION_BYPASS_SECRET", "");
+    const fetchMock = stubFetch();
+    const controller = new AbortController();
+
+    await apiFetch({
+      path: "/api/foo",
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: '{"a":1}',
+      signal: controller.signal,
+    });
+
+    const [, init] = lastFetchCall(fetchMock);
+    expect(init.method).toBe("PATCH");
+    expect(init.headers).toEqual({ "Content-Type": "application/json" });
+    expect(init.body).toBe('{"a":1}');
+    expect(init.signal).toBe(controller.signal);
+  });
+
+  it("propagates getApiUrl validation errors without fetching", async () => {
+    vi.stubEnv("API_URL", "https://evil.example.com");
+    const fetchMock = stubFetch();
+
+    await expect(apiFetch({ path: "/api/foo" })).rejects.toThrow("is not allowed");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/src/utils/apiFetch.ts

@@ -0,0 +1,62 @@
+import { getApiUrl } from "#app/utils/apiUrl";
+import { log } from "#app/utils/cli";
+
+type ApiFetchOptions = {
+  path: string;
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: string | undefined;
+  signal?: AbortSignal | undefined;
+};
+
+/**
+ * fetch wrapper for hitting the Terramend API with Vercel deployment protection bypass.
+ *
+ * adds the bypass secret as BOTH a query parameter and a header for maximum reliability.
+ * the server-side forwarding code uses query params, and the Vercel docs say both work,
+ * so we do both as belt-and-suspenders.
+ *
+ * the query param approach is the primary bypass mechanism (matches server-side forwarding).
+ * the header is added as a fallback.
+ */
+export async function apiFetch(options: ApiFetchOptions): Promise<Response> {
+  const apiUrl = getApiUrl();
+  const url = new URL(options.path, apiUrl);
+
+  const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+  if (bypassSecret) {
+    url.searchParams.set("x-vercel-protection-bypass", bypassSecret);
+  }
+
+  const headers: Record<string, string> = {
+    ...options.headers,
+  };
+
+  // also add as header for belt-and-suspenders
+  if (bypassSecret) {
+    headers["x-vercel-protection-bypass"] = bypassSecret;
+  }
+
+  // never send Content-Type on body-less requests. empirically, Vercel's
+  // Next.js lambda adapter (Next 16.1.x) throws `SyntaxError: Unexpected
+  // end of data` before delegating to the route handler — returning a 500 —
+  // when Content-Type is set but no body is present. exact mechanism is
+  // unverified (minified runtime frame), but Content-Type on a body-less
+  // request has no defined semantics per RFC 9110 §8.3 anyway. see #692.
+  if (!options.body) {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === "content-type") delete headers[key];
+    }
+  }
+
+  log.debug(`api fetch: ${options.method ?? "GET"} ${url.pathname}`);
+
+  const init: RequestInit = {
+    method: options.method ?? "GET",
+    headers,
+  };
+  if (options.body) init.body = options.body;
+  if (options.signal) init.signal = options.signal;
+
+  return fetch(url.toString(), init);
+}