terramend 0.2.0

package/src/utils/byokFallback.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveCliModel } from "#app/models";
+import {
+  buildUnavailableModelError,
+  FREE_FALLBACK_SLUG,
+  hasProviderKeyForModel,
+  selectFallbackModelIfNeeded,
+} from "#app/utils/byokFallback";
+
+describe("FREE_FALLBACK_SLUG", () => {
+  it("resolves in the curated catalog", () => {
+    expect(resolveCliModel(FREE_FALLBACK_SLUG)).toBe("opencode/big-pickle");
+  });
+
+  it("is opencode/big-pickle", () => {
+    expect(FREE_FALLBACK_SLUG).toBe("opencode/big-pickle");
+  });
+});
+
+describe("selectFallbackModelIfNeeded", () => {
+  const empty = new Set<string>();
+
+  it("falls back to free when the model is unauthorized AND no provider key is present", () => {
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "anthropic/claude-opus-4-7",
+      authorized: empty,
+      providerKeyPresent: false,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({
+      kind: "fallback",
+      from: "anthropic/claude-opus-4-7",
+      to: FREE_FALLBACK_SLUG,
+    });
+  });
+
+  it("uses the resolved model when the claude harness serves it", () => {
+    // opencode models can't see CLAUDE_CODE_OAUTH_TOKEN, so `authorized` is
+    // empty for anthropic/* — and the OAuth token counts as a present provider
+    // key, which would land in `unavailable` and fail the run. resolveAgent
+    // picks the claude agent, which brings its own auth; the gate must defer.
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "anthropic/claude-opus-4-8",
+      authorized: empty,
+      providerKeyPresent: true,
+      agentName: "claude",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("reports unavailable (does NOT downgrade) when a provider key IS present but the model is unauthorized", () => {
+    // PR #2 scenario: Google key set, but the configured Google model id isn't
+    // one OpenCode can route → fail loudly instead of silently serving free.
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "google/gemini-3.5-flash-lite",
+      authorized: new Set(["google/gemini-3.5-flash", "google/gemini-3.1-pro"]),
+      providerKeyPresent: true,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "unavailable", model: "google/gemini-3.5-flash-lite" });
+  });
+
+  it("uses the resolved model when it IS authorized (regardless of key presence)", () => {
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "anthropic/claude-opus-4-7",
+      authorized: new Set(["anthropic/claude-opus-4-7"]),
+      providerKeyPresent: true,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("uses the resolved model when none is resolved (auto-select path)", () => {
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: undefined,
+      authorized: empty,
+      providerKeyPresent: false,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("uses the resolved model when it is itself the free fallback", () => {
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: FREE_FALLBACK_SLUG,
+      authorized: empty,
+      providerKeyPresent: false,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("uses the resolved model for Bedrock routing (raw model ID has no slash)", () => {
+    // resolveModel({slug:"bedrock/byok"}) returns the raw BEDROCK_MODEL_ID
+    // value (e.g. "eu.anthropic.claude-opus-4-7"), which has no `/`. the
+    // routing validator (validateBedrockSetup) owns auth + region + model-id
+    // checking for this path, not the BYOK fallback gate.
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "eu.anthropic.claude-opus-4-7",
+      authorized: empty,
+      providerKeyPresent: true,
+      agentName: "claude",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("the no-slash skip holds on its own (opencode agent, key present)", () => {
+    // distinguishes the raw-ID guard from the claude-agent guard right after
+    // it: with agentName "opencode" + a present key, deleting the no-slash
+    // check would mis-route this to `unavailable` and fail the run.
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: "amazon.titan-text-express-v1",
+      authorized: empty,
+      providerKeyPresent: true,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+
+  it("uses the resolved model when stored minimax-m2.5-free resolves to big-pickle", () => {
+    const result = selectFallbackModelIfNeeded({
+      resolvedModel: resolveCliModel("opencode/minimax-m2.5-free"),
+      authorized: empty,
+      providerKeyPresent: false,
+      agentName: "opencode",
+    });
+    expect(result).toEqual({ kind: "use-resolved" });
+  });
+});
+
+describe("hasProviderKeyForModel", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("is true when a Google key is present for a resolved Google model", () => {
+    vi.stubEnv("GOOGLE_GENERATIVE_AI_API_KEY", "xxx");
+    expect(hasProviderKeyForModel("google/gemini-3.5-flash-lite")).toBe(true);
+  });
+
+  it("is true for the alternate Google key env var", () => {
+    vi.stubEnv("GEMINI_API_KEY", "xxx");
+    expect(hasProviderKeyForModel("google/gemini-3.1-pro-preview")).toBe(true);
+  });
+
+  it("is false when no key for that provider is present", () => {
+    vi.stubEnv("GEMINI_API_KEY", "");
+    vi.stubEnv("GOOGLE_GENERATIVE_AI_API_KEY", "");
+    expect(hasProviderKeyForModel("google/gemini-3.5-flash-lite")).toBe(false);
+  });
+
+  it("detects the Anthropic OAuth token shape as a present key", () => {
+    vi.stubEnv("ANTHROPIC_API_KEY", "");
+    vi.stubEnv("CLAUDE_CODE_OAUTH_TOKEN", "tok");
+    expect(hasProviderKeyForModel("anthropic/claude-opus-4-8")).toBe(true);
+  });
+
+  it("is false for an unknown provider (no catalog env vars)", () => {
+    expect(hasProviderKeyForModel("madeup/model")).toBe(false);
+  });
+});
+
+describe("buildUnavailableModelError", () => {
+  it("lists same-provider authorized models and names the provider", () => {
+    const msg = buildUnavailableModelError({
+      model: "google/gemini-3.5-flash-lite",
+      authorized: new Set([
+        "google/gemini-3.5-flash",
+        "google/gemini-3.1-pro",
+        "anthropic/claude-opus-4-8",
+      ]),
+    });
+    expect(msg).toContain(
+      'model "google/gemini-3.5-flash-lite" is not available to your Google key',
+    );
+    expect(msg).toContain("  - google/gemini-3.5-flash");
+    expect(msg).toContain("  - google/gemini-3.1-pro");
+    // unrelated provider is filtered out when same-provider matches exist
+    expect(msg).not.toContain("anthropic/claude-opus-4-8");
+  });
+
+  it("falls back to the full authorized list when no same-provider model is authorized", () => {
+    const msg = buildUnavailableModelError({
+      model: "google/gemini-3.5-flash-lite",
+      authorized: new Set(["anthropic/claude-opus-4-8"]),
+    });
+    expect(msg).toContain("  - anthropic/claude-opus-4-8");
+  });
+
+  it("lists the authorized models sorted, not in Set insertion order", () => {
+    const msg = buildUnavailableModelError({
+      model: "google/gemini-3.5-flash-lite",
+      authorized: new Set(["google/z-model", "google/a-model"]),
+    });
+    expect(msg.indexOf("google/a-model")).toBeLessThan(msg.indexOf("google/z-model"));
+  });
+
+  it("handles an empty authorized set without throwing", () => {
+    const msg = buildUnavailableModelError({
+      model: "google/gemini-3.5-flash-lite",
+      authorized: new Set(),
+    });
+    expect(msg).toContain("does not authorize any model");
+  });
+});

package/src/utils/byokFallback.ts

@@ -0,0 +1,128 @@
+import type { AgentId } from "#app/external";
+import { getModelEnvVars, getProviderDisplayName } from "#app/models";
+
+/**
+ * Slug we fall back to when a BYOK-required model is configured but the
+ * runner has no provider key in env. Picked because it's free, stable, and
+ * currently served by OpenCode Zen without a key.
+ *
+ * The slug is intentionally hard-coded and not a config knob — the
+ * fallback is a safety net, not a user-facing preference, and adding a
+ * config surface here would just push the same "what to fall back to"
+ * decision into another setting that goes stale the same way.
+ */
+export const FREE_FALLBACK_SLUG = "opencode/big-pickle";
+
+/**
+ * Outcome of the BYOK model gate.
+ *
+ *   - `use-resolved`: run the configured model as-is.
+ *   - `fallback`: the runner has NO provider key for this model's provider,
+ *     so swap to the free OpenCode slug — a genuine no-key safety net.
+ *   - `unavailable`: a provider key IS present but the configured model is
+ *     not one OpenCode can route with it. This is almost always a wrong or
+ *     mistyped model id (or a key scoped to other models). We must NOT
+ *     silently downgrade to the free model — that hides the misconfiguration
+ *     and produces a free run the user didn't ask for (see PR #2). The caller
+ *     fails loudly with the authorized-model list instead.
+ */
+export type FallbackDecision =
+  | { kind: "use-resolved" }
+  | { kind: "fallback"; from: string; to: string }
+  | { kind: "unavailable"; model: string };
+
+function hasEnvVar(name: string): boolean {
+  const value = process.env[name];
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Does the runner have a provider credential for `resolvedModel`'s provider?
+ *
+ * Uses the provider→envVars map in `models.ts` (provider-level, since a
+ * resolved specifier like `google/gemini-3.5-flash-lite` won't match a catalog
+ * model key and correctly falls through to the provider's env vars). A present
+ * key is what distinguishes the two not-authorized situations: key present =
+ * wrong/unavailable model id (fail loudly); no key = genuine BYOK gap (free
+ * fallback).
+ */
+export function hasProviderKeyForModel(resolvedModel: string): boolean {
+  return getModelEnvVars(resolvedModel).some(hasEnvVar);
+}
+
+/**
+ * Decide whether to run the configured model, fall back to the free model, or
+ * fail because the model is unavailable to the present key.
+ *
+ * `authorized` is OpenCode's authoritative "what can I route right now"
+ * snapshot, captured after Codex auth.json is in place.
+ *
+ * Skip cases (always `use-resolved`, without consulting `authorized`):
+ *   - No resolved model: auto-select handles it downstream.
+ *   - Resolved model is the free fallback already.
+ *   - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
+ *     validators (`validateBedrockSetup` / `validateVertexSetup`) cover
+ *     auth + region/location/model-id; `opencode models` does not.
+ *   - The selected agent is `claude`: the Claude Code harness brings its own
+ *     auth and `resolveAgent` only returns it when that auth is present.
+ *     `opencode models` can't see `CLAUDE_CODE_OAUTH_TOKEN`, so without this
+ *     an OAuth-subscription run on an Anthropic model would land in
+ *     `unavailable` (the token counts as a present provider key) and fail a
+ *     run the claude harness serves fine. `validateAgentApiKey` still covers
+ *     the claude path with its own Anthropic auth check.
+ */
+export function selectFallbackModelIfNeeded(input: {
+  resolvedModel: string | undefined;
+  authorized: Set<string>;
+  /** whether a provider key for the resolved model's provider is present in env */
+  providerKeyPresent: boolean;
+  /** which agent harness `resolveAgent` picks for the resolved model */
+  agentName: AgentId;
+}): FallbackDecision {
+  if (!input.resolvedModel) return { kind: "use-resolved" };
+  if (input.resolvedModel === FREE_FALLBACK_SLUG) return { kind: "use-resolved" };
+  if (!input.resolvedModel.includes("/")) return { kind: "use-resolved" };
+  if (input.agentName === "claude") return { kind: "use-resolved" };
+  if (input.authorized.has(input.resolvedModel)) return { kind: "use-resolved" };
+
+  // resolved model is NOT in OpenCode's authorized set. split the two cases:
+  if (input.providerKeyPresent) {
+    // a key for this provider is configured — the model id is wrong or not
+    // available to this key. surface it; do not silently serve a free model.
+    return { kind: "unavailable", model: input.resolvedModel };
+  }
+  // no key at all → genuine BYOK gap → free safety net so the run still works.
+  return { kind: "fallback", from: input.resolvedModel, to: FREE_FALLBACK_SLUG };
+}
+
+/**
+ * Loud, actionable error for the `unavailable` decision: a provider key is
+ * present but the configured model isn't one the key can serve. Lists the
+ * models OpenCode CAN route (same-provider first) so the user can copy a valid
+ * slug instead of getting a silent free downgrade.
+ */
+export function buildUnavailableModelError(input: {
+  model: string;
+  authorized: Set<string>;
+}): string {
+  const provider = input.model.slice(0, input.model.indexOf("/"));
+  const providerLabel = getProviderDisplayName(input.model) ?? provider;
+  const all = [...input.authorized].sort();
+  const sameProvider = all.filter((m) => m.startsWith(`${provider}/`));
+  const shown = sameProvider.length > 0 ? sameProvider : all;
+  const list =
+    shown.length > 0
+      ? shown.map((m) => `  - ${m}`).join("\n")
+      : "  (none — your key does not authorize any model OpenCode can route)";
+
+  return [
+    `model "${input.model}" is not available to your ${providerLabel} key.`,
+    ``,
+    `A provider credential is present, so Terramend did not fall back to the free model —`,
+    `it surfaces this instead so you can pick a valid id. Models your key can serve:`,
+    ``,
+    list,
+    ``,
+    `Set the model (the \`model\` input, or \`TERRAMEND_MODEL\`) to one of the slugs above.`,
+  ].join("\n");
+}

package/src/utils/claudeSubscription.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveModelSlug } from "#app/models";
+import { preflightClaudeSubscription } from "#app/utils/claudeSubscription";
+
+type FetchArgs = [input: string | URL | Request, init?: RequestInit];
+
+function stubFetch(impl: () => Promise<Response>) {
+  const mock = vi.fn(impl);
+  vi.stubGlobal("fetch", mock);
+  return mock;
+}
+
+function firstCall(mock: { mock: { calls: unknown[][] } }): FetchArgs {
+  const call = mock.mock.calls[0];
+  if (!call) throw new Error("expected fetch to have been called");
+  return call as FetchArgs;
+}
+
+function requestBody(mock: { mock: { calls: unknown[][] } }): Record<string, unknown> {
+  const [, init] = firstCall(mock);
+  if (!init || typeof init.body !== "string") throw new Error("expected a string request body");
+  return JSON.parse(init.body) as Record<string, unknown>;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("preflightClaudeSubscription", () => {
+  it("returns usable on 200 OK and probes with the run's model on the OAuth surface", async () => {
+    const mock = stubFetch(async () => new Response("{}", { status: 200 }));
+
+    const result = await preflightClaudeSubscription({
+      token: "oauth-tok",
+      model: "claude-fable-5",
+    });
+
+    expect(result).toEqual({ usable: true });
+    expect(mock).toHaveBeenCalledTimes(1);
+    const [url, init] = firstCall(mock);
+    expect(url).toBe("https://api.anthropic.com/v1/messages");
+    if (!init) throw new Error("expected a request init");
+    expect(init.method).toBe("POST");
+    expect(init.headers).toMatchObject({
+      authorization: "Bearer oauth-tok",
+      "anthropic-beta": "claude-code-20250219,oauth-2025-04-20",
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+      "x-app": "cli",
+    });
+    expect(requestBody(mock)).toMatchObject({ model: "claude-fable-5", max_tokens: 1 });
+  });
+
+  it("falls back to the registry-resolved haiku probe model when no model is set", async () => {
+    const mock = stubFetch(async () => new Response("{}", { status: 200 }));
+
+    await preflightClaudeSubscription({ token: "oauth-tok", model: undefined });
+
+    const resolved = resolveModelSlug("anthropic/claude-haiku");
+    if (!resolved) throw new Error("anthropic/claude-haiku missing from registry");
+    const expected = resolved.slice(resolved.indexOf("/") + 1);
+    const body = requestBody(mock);
+    expect(body.model).toBe(expected);
+    expect(String(body.model)).not.toContain("/");
+  });
+
+  it("marks the token unusable on 401 with the error.message from the JSON body", async () => {
+    stubFetch(
+      async () =>
+        new Response(JSON.stringify({ error: { message: "OAuth token revoked" } }), {
+          status: 401,
+        }),
+    );
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: false, reason: "401: OAuth token revoked" });
+  });
+
+  it("marks the token unusable on 429 (subscription limit hit)", async () => {
+    stubFetch(
+      async () =>
+        new Response(JSON.stringify({ error: { message: "You've hit your Opus limit" } }), {
+          status: 429,
+        }),
+    );
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-opus-4-8" });
+
+    expect(result).toEqual({ usable: false, reason: "429: You've hit your Opus limit" });
+  });
+
+  it.each([400, 403, 500, 529])("fails open (usable) on status %d", async (status) => {
+    stubFetch(async () => new Response("nope", { status }));
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: true });
+  });
+
+  it("fails open when fetch itself throws (network error / timeout)", async () => {
+    stubFetch(async () => {
+      throw new TypeError("fetch failed");
+    });
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: true });
+  });
+
+  it("uses a raw excerpt of a non-JSON 401 body, capped at 200 chars", async () => {
+    const html = `<html>upstream error${"x".repeat(300)}</html>`;
+    stubFetch(async () => new Response(html, { status: 401 }));
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result.usable).toBe(false);
+    if (result.usable) throw new Error("expected an unusable result");
+    expect(result.reason).toBe(`401: ${html.slice(0, 200)}`);
+  });
+
+  it("uses the raw excerpt when the JSON body has no error.message string", async () => {
+    const body = JSON.stringify({ error: "rate_limited" });
+    stubFetch(async () => new Response(body, { status: 429 }));
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: false, reason: `429: ${body}` });
+  });
+
+  it("degrades to an empty reason body when reading the response body fails", async () => {
+    const fake = {
+      status: 401,
+      text: () => Promise.reject(new Error("body stream interrupted")),
+    } as unknown as Response;
+    stubFetch(async () => fake);
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: false, reason: "401: " });
+  });
+
+  it("sends the exact probe body Anthropic's OAuth gate validates", async () => {
+    // the system-identity block and 1-token cap are what make the probe both
+    // accepted by the OAuth surface and effectively free — pin the full shape.
+    const mock = stubFetch(async () => new Response("{}", { status: 200 }));
+
+    await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(requestBody(mock)).toEqual({
+      model: "claude-fable-5",
+      max_tokens: 1,
+      system: "You are Claude Code, Anthropic's official CLI for Claude.",
+      messages: [{ role: "user", content: "ok" }],
+    });
+  });
+
+  it("uses the raw excerpt when error.message exists but is not a string", async () => {
+    const body = JSON.stringify({ error: { message: 42 } });
+    stubFetch(async () => new Response(body, { status: 401 }));
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: false, reason: `401: ${body}` });
+  });
+
+  it.each([
+    "null",
+    "42",
+    '"just a string"',
+    JSON.stringify({ no_error_key: 1 }),
+  ])("uses the raw excerpt for JSON body %s (no extractable error.message)", async (body) => {
+    stubFetch(async () => new Response(body, { status: 429 }));
+
+    const result = await preflightClaudeSubscription({ token: "t", model: "claude-fable-5" });
+
+    expect(result).toEqual({ usable: false, reason: `429: ${body}` });
+  });
+});

package/src/utils/claudeSubscription.ts

@@ -0,0 +1,93 @@
+import { resolveModelSlug } from "#app/models";
+
+/**
+ * identity block Anthropic's OAuth gate validates on `/v1/messages` calls
+ * authenticated with a Claude Code OAuth token. haiku is currently exempt
+ * but sending it costs nothing and survives the exemption being removed.
+ */
+const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+
+// fallback probe model for runs with no explicit model (claude-code picks its
+// own default there, so per-model accuracy is moot — only whether the
+// subscription answers at all). registry-resolved so a catalog bump keeps
+// the id fresh.
+const fallbackResolve = resolveModelSlug("anthropic/claude-haiku");
+if (!fallbackResolve) {
+  throw new Error("claudeSubscription preflight: anthropic/claude-haiku missing from registry");
+}
+const FALLBACK_PROBE_MODEL = fallbackResolve.slice(fallbackResolve.indexOf("/") + 1);
+
+export type SubscriptionPreflight = { usable: true } | { usable: false; reason: string };
+
+/**
+ * preflight a Claude subscription OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`)
+ * with a 1-token Messages call, so the agent can fall back to
+ * `ANTHROPIC_API_KEY` when the subscription is exhausted or revoked instead
+ * of failing the whole run at its first model call. rides the same de-facto
+ * OAuth surface Claude Code itself uses: Bearer auth + the
+ * `claude-code-20250219,oauth-2025-04-20` betas + the identity system prompt.
+ *
+ * probes the run's own model when known — subscription limits can be
+ * per-model ("You've hit your Opus limit"), so a cheaper stand-in could pass
+ * preflight and still leave the run dead on arrival.
+ *
+ * fail-open by design: only 401 (revoked/expired token) and 429
+ * (session/weekly/per-model limit) mark the token unusable. network errors,
+ * 5xx, and request-shape drift (400) all keep today's subscription-first
+ * behavior, so the preflight can never fail a run that would have worked —
+ * the worst wrong answer is a run that bills the API key instead of the
+ * subscription.
+ */
+export async function preflightClaudeSubscription(params: {
+  token: string;
+  /** bare Anthropic model id the run will use (e.g. "claude-fable-5") */
+  model: string | undefined;
+}): Promise<SubscriptionPreflight> {
+  let res: Response;
+  try {
+    res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${params.token}`,
+        "anthropic-beta": "claude-code-20250219,oauth-2025-04-20",
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+        "x-app": "cli",
+      },
+      body: JSON.stringify({
+        model: params.model ?? FALLBACK_PROBE_MODEL,
+        max_tokens: 1,
+        system: CLAUDE_CODE_IDENTITY,
+        messages: [{ role: "user", content: "ok" }],
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch {
+    // network failure / timeout says nothing about the credential
+    return { usable: true };
+  }
+  if (res.status !== 401 && res.status !== 429) return { usable: true };
+  const body = await res.text().catch(() => "");
+  return { usable: false, reason: `${res.status}: ${extractApiErrorMessage(body)}` };
+}
+
+/** pull `error.message` out of an Anthropic error payload, else a raw excerpt */
+function extractApiErrorMessage(body: string): string {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "error" in parsed &&
+      typeof parsed.error === "object" &&
+      parsed.error !== null &&
+      "message" in parsed.error &&
+      typeof parsed.error.message === "string"
+    ) {
+      return parsed.error.message;
+    }
+  } catch {
+    // not json — fall through to the raw excerpt
+  }
+  return body.slice(0, 200);
+}

package/src/utils/cli.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI utilities
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+// re-export logging utilities for backward compatibility
+export {
+  formatIndentedField,
+  formatJsonValue,
+  formatUsageSummary,
+  log,
+  writeSummary,
+} from "#app/utils/log";
+
+/**
+ * Finds a CLI executable path by checking if it's installed globally
+ * @param name The name of the CLI executable to find
+ * @returns The path to the CLI executable, or null if not found
+ */
+export function findCliPath(name: string): string | null {
+  const result = spawnSync("which", [name], { encoding: "utf-8" });
+  if (result.status === 0 && result.stdout) {
+    const cliPath = result.stdout.trim();
+    if (cliPath && existsSync(cliPath)) {
+      return cliPath;
+    }
+  }
+  return null;
+}