@takara-ai/miru-code 1.5.3 → 1.7.2

package/src/auth/providers.ts

@@ -0,0 +1,115 @@
+import { dim, warn, writeStderr } from "../cli-ui.ts";
+import { validateEmbeddingApiKey } from "../embeddings/validate.ts";
+import { promptConfirm } from "../installer/prompt.ts";
+import { promptHidden } from "../prompt.ts";
+import { Spinner } from "../spinner.ts";
+import {
+  openBrowserForDeviceLogin,
+  pollDeviceAuthorization,
+  startDeviceAuthorization,
+} from "./device.ts";
+import type { AuthenticatedCredentials } from "./types.ts";
+
+export type AuthMode = "api_key" | "device_code";
+
+export interface AuthenticateOptions {
+  apiKey?: string;
+  device?: boolean;
+  skipValidation?: boolean;
+  allowManualFallback?: boolean;
+  interactive?: boolean;
+}
+
+async function promptApiKey(): Promise<string> {
+  let key = "";
+  while (!key) {
+    key = await promptHidden("Takara API key (input hidden): ", process.stderr);
+    if (!key) {
+      warn("API key cannot be empty.");
+    }
+  }
+  return key;
+}
+
+async function resolveAuthMode(options: AuthenticateOptions): Promise<AuthMode> {
+  if (options.apiKey) {
+    return "api_key";
+  }
+  if (options.device || options.interactive) {
+    return "device_code";
+  }
+  throw new Error("Choose an auth mode with `miru setup --device` or `miru setup --key TOKEN`.");
+}
+
+async function authenticateWithApiKey(
+  options: AuthenticateOptions,
+): Promise<AuthenticatedCredentials> {
+  const apiKey = options.apiKey ?? (await promptApiKey());
+  if (!options.skipValidation) {
+    const spinner = new Spinner("Validating API key");
+    spinner.start();
+    const result = await validateEmbeddingApiKey({ apiKey });
+    if (!result.valid) {
+      spinner.stop();
+      throw new Error(result.message);
+    }
+    spinner.succeed("API key validated");
+  }
+  return { kind: "api_key", apiKey };
+}
+
+async function authenticateWithDeviceCode(
+  options: AuthenticateOptions,
+): Promise<AuthenticatedCredentials> {
+  writeStderr("");
+  const spinner = new Spinner("Authenticating");
+  spinner.start();
+  try {
+    const start = await startDeviceAuthorization();
+    const verificationUrl = start.verificationUriComplete ?? start.verificationUri;
+
+    const shouldOpenBrowser =
+      options.interactive &&
+      (process.env.MIRU_OPEN_BROWSER === undefined || process.env.MIRU_OPEN_BROWSER === "1");
+    if (shouldOpenBrowser) {
+      openBrowserForDeviceLogin(verificationUrl);
+    }
+
+    let visit = dim(`  Visit ${verificationUrl}`);
+    if (!start.verificationUriComplete) {
+      visit += `\n${dim(`  Code: ${start.userCode}`)}`;
+    }
+    spinner.follow(visit);
+
+    const tokens = await pollDeviceAuthorization(start);
+    spinner.succeed("");
+    return {
+      kind: "device_code",
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAt: tokens.expiresAt,
+      tokenType: tokens.tokenType,
+      scope: tokens.scope,
+    };
+  } catch (err) {
+    spinner.stop();
+    if (options.allowManualFallback && options.interactive) {
+      warn(err instanceof Error ? err.message : String(err));
+      const fallback = await promptConfirm("Enter an API key instead?", true);
+      if (fallback) {
+        return authenticateWithApiKey(options);
+      }
+    }
+    throw err;
+  }
+}
+
+export async function authenticateWithProvider(
+  options: AuthenticateOptions,
+): Promise<AuthenticatedCredentials> {
+  const mode = await resolveAuthMode(options);
+  if (mode === "device_code") {
+    return authenticateWithDeviceCode(options);
+  }
+  return authenticateWithApiKey(options);
+}

package/src/auth/types.ts

@@ -0,0 +1,65 @@
+export const CREDENTIALS_VERSION = 2;
+export const LEGACY_CREDENTIALS_VERSION = 1;
+
+export type StoredCredentialKind = "api_key" | "device_code" | "sagemaker";
+
+export interface StoredApiKeyCredentials {
+  version: typeof CREDENTIALS_VERSION;
+  kind: "api_key";
+  api_key: string;
+}
+
+export interface StoredDeviceCodeCredentials {
+  version: typeof CREDENTIALS_VERSION;
+  kind: "device_code";
+  access_token: string;
+  refresh_token?: string;
+  expires_at?: string;
+  token_type?: string;
+  scope?: string;
+}
+
+/** Self-hosted SageMaker embedding endpoint — mutually exclusive with Takara token auth. */
+export interface StoredSageMakerCredentials {
+  version: typeof CREDENTIALS_VERSION;
+  kind: "sagemaker";
+  endpoint_arn: string;
+  profile?: string;
+}
+
+export type StoredCredentials =
+  | StoredApiKeyCredentials
+  | StoredDeviceCodeCredentials
+  | StoredSageMakerCredentials;
+
+/** Pre-v2 credentials.json shape, from before device-code auth and the `kind` discriminator existed. */
+export interface LegacyStoredCredentials {
+  version: typeof LEGACY_CREDENTIALS_VERSION;
+  takara_api_key?: string;
+  sagemaker?: { endpoint_arn: string; profile?: string };
+}
+
+export type SaveStoredCredentialsInput =
+  | string
+  | { kind: "api_key"; apiKey: string }
+  | {
+      kind: "device_code";
+      accessToken: string;
+      refreshToken?: string;
+      expiresAt?: string;
+      tokenType?: string;
+      scope?: string;
+    }
+  | { kind: "sagemaker"; endpointArn: string; profile?: string };
+
+export type AuthenticatedCredentials = Exclude<
+  SaveStoredCredentialsInput,
+  string | { kind: "sagemaker"; endpointArn: string; profile?: string }
+>;
+
+/** Token to hydrate TAKARA_API_KEY with. Not defined for SageMaker (AWS-profile auth, no bearer token). */
+export function credentialAccessToken(
+  credentials: StoredApiKeyCredentials | StoredDeviceCodeCredentials,
+): string {
+  return credentials.kind === "api_key" ? credentials.api_key : credentials.access_token;
+}

package/src/cli.ts

@@ -11,6 +11,7 @@ import {
   info,
   prefersJsonOutput,
   success,
+  warn,
   writeStdout,
 } from "./cli-ui.ts";
 import { loadStoredCredentials } from "./credentials.ts";
@@ -20,8 +21,9 @@ import {
   AGENT_IDS,
   formatUnknownAgent,
   printCommandHelp,
-  printFullHelp,
+  printEnvironmentHelp,
   printMainHelp,
+  printSageMakerHelp,
 } from "./help.ts";
 import { getBenchmarkModeStatus, setBenchmarkMode } from "./installer/benchmark-mode.ts";
 import { runSearchGuardFromStdin } from "./installer/hooks/search-guard.ts";
@@ -61,7 +63,13 @@ process.title = "miru";
 
 await loadEnvFiles();
 normalizeTakaraApiKeyEnv();
-await loadStoredCredentials();
+// Soft-fail: expired/revoked device refresh must not brick `miru -v`, `setup --clear`, etc.
+// Command paths call ensureCredentials() which recovers interactively when allowed.
+try {
+  await loadStoredCredentials();
+} catch {
+  // Leave recovery to ensureCredentials / setup.
+}
 
 const CLI_COMMANDS = new Set([
   "search",
@@ -74,6 +82,8 @@ const CLI_COMMANDS = new Set([
   "setup",
   "clear",
   "benchmark",
+  "env",
+  "environment",
   "hook-guard",
   "help",
   "-h",
@@ -408,7 +418,7 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "-h" || command === "--help") {
-    printFullHelp();
+    printMainHelp();
     return;
   }
 
@@ -419,7 +429,7 @@ async function runCli(argv: string[]): Promise<void> {
 
   if (command === "help") {
     const topic = rest[0];
-    if (!topic) {
+    if (!topic || topic === "-h" || topic === "--help") {
       printMainHelp();
       return;
     }
@@ -427,6 +437,25 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "setup" && (rest.includes("-h") || rest.includes("--help"))) {
+    if (rest.includes("--sagemaker")) {
+      printSageMakerHelp();
+    } else {
+      printCommandHelp("setup");
+    }
+    return;
+  }
+
+  if (command === "env" || command === "environment") {
+    printEnvironmentHelp();
+    return;
+  }
+
+  if (rest[0] === "-h" || rest[0] === "--help") {
+    printCommandHelp(command);
+    return;
+  }
+
   if (command === "hook-guard") {
     process.exit(await runSearchGuardFromStdin());
   }
@@ -474,26 +503,35 @@ async function runCli(argv: string[]): Promise<void> {
   if (command === "setup") {
     const { args, error } = parseSetupCliArgs(rest);
     if (error === "clear_with_key") {
-      fail("miru setup --clear cannot be combined with --key.");
+      fail("miru setup --clear cannot be combined with --key, --device, or --sagemaker.");
       process.exit(1);
     }
     if (error === "sagemaker_with_key") {
       fail("miru setup --sagemaker cannot be combined with --key.");
       process.exit(1);
     }
+    if (error === "device_with_key") {
+      fail("miru setup accepts either --device or --key TOKEN, not both.");
+      process.exit(1);
+    }
+    if (error === "device_with_sagemaker") {
+      fail("miru setup --device cannot be combined with --sagemaker.");
+      process.exit(1);
+    }
     if (args.clear) {
       await runClearCredentials();
       return;
     }
     const { newlySaved } = await runSetup({
       apiKey: args.apiKey,
+      device: args.device,
       force: args.force,
       sagemaker: args.sagemaker,
       sagemakerArn: args.sagemakerArn,
       profile: args.profile,
     });
     if (newlySaved) {
-      const offerInstall = canPromptForCredentials() && !args.apiKey && !args.force;
+      const offerInstall = canPromptForCredentials() && !args.apiKey && !args.device && !args.force;
       if (offerInstall) {
         const install = await promptConfirm("Configure Miru in your coding agent now?");
         if (install) {
@@ -501,7 +539,7 @@ async function runCli(argv: string[]): Promise<void> {
           return;
         }
       }
-      hint("Run `miru install` to add Miru to your IDE.");
+      hint("To add Miru to your IDE, run `miru install`.");
     }
     return;
   }
@@ -675,7 +713,20 @@ async function runMcp(argv: string[]): Promise<void> {
 }
 
 async function runMcpWithCredentials(argv: string[]): Promise<void> {
-  await ensureCredentials({ interactive: false });
+  // The MCP server is spawned as a headless stdio subprocess, never a real
+  // login terminal, so it must never crash the whole process over missing
+  // credentials — that would kill every tool, not just the ones needing
+  // embeddings. Best-effort load/refresh whatever's already stored; leave it
+  // to individual tool calls to report a missing-credentials error, and to
+  // the `auth` tool (src/mcp/auth-tool.ts) to complete device-code login
+  // in-band without a terminal.
+  await loadStoredCredentials().catch((err: unknown) => {
+    // Swallow so a stale/revoked refresh token etc. can't crash the server — but
+    // don't swallow silently, or the only symptom is a later "credentials
+    // required" tool error with no clue why stored credentials didn't work.
+    warn(`Could not load stored credentials: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  });
   await runMcp(argv);
 }
 

package/src/credentials.ts

@@ -1,19 +1,23 @@
-import { chmod, mkdir } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { deviceCredentialsNeedRefresh, refreshDeviceAuthorization } from "./auth/device.ts";
+import {
+  CREDENTIALS_VERSION,
+  credentialAccessToken,
+  LEGACY_CREDENTIALS_VERSION,
+  type LegacyStoredCredentials,
+  type SaveStoredCredentialsInput,
+  type StoredCredentials,
+  type StoredSageMakerCredentials,
+} from "./auth/types.ts";
 import { hasTakaraApiKeyInEnv, normalizeTakaraApiKeyEnv } from "./env.ts";
 
 const CREDENTIALS_FILENAME = "credentials.json";
-const CREDENTIALS_VERSION = 1;
+let activeStoredToken: string | null = null;
 
-export interface StoredSageMakerCredentials {
-  endpoint_arn: string;
-  profile?: string;
-}
-
-interface StoredCredentials {
-  version: number;
-  takara_api_key?: string;
-  sagemaker?: StoredSageMakerCredentials;
+export function setStoredCredentialsEnvToken(token: string): void {
+  activeStoredToken = token;
+  process.env.TAKARA_API_KEY = token;
 }
 
 export function resolveCredentialsDir(): string {
@@ -51,11 +55,44 @@ export async function readStoredCredentials(): Promise<StoredCredentials | null>
     return null;
   }
   try {
-    const parsed = JSON.parse(await Bun.file(path).text()) as StoredCredentials;
-    if (parsed.version !== CREDENTIALS_VERSION || (!parsed.takara_api_key && !parsed.sagemaker)) {
+    const parsed = JSON.parse(await readFile(path, "utf-8")) as
+      | StoredCredentials
+      | LegacyStoredCredentials;
+    if (parsed.version === LEGACY_CREDENTIALS_VERSION) {
+      if (parsed.sagemaker) {
+        return {
+          version: CREDENTIALS_VERSION,
+          kind: "sagemaker",
+          endpoint_arn: parsed.sagemaker.endpoint_arn,
+          profile: parsed.sagemaker.profile,
+        };
+      }
+      if (parsed.takara_api_key?.trim()) {
+        return {
+          version: CREDENTIALS_VERSION,
+          kind: "api_key",
+          api_key: parsed.takara_api_key,
+        };
+      }
+      return null;
+    }
+    if (parsed.version !== CREDENTIALS_VERSION || !("kind" in parsed)) {
       return null;
     }
-    return parsed;
+    if (parsed.kind === "api_key" && parsed.api_key?.trim()) {
+      return parsed;
+    }
+    if (parsed.kind === "sagemaker" && parsed.endpoint_arn?.trim()) {
+      return parsed;
+    }
+    if (parsed.kind === "device_code") {
+      if (!parsed.access_token?.trim()) {
+        // Treat incomplete device files as absent so `setup --clear` and recovery can proceed.
+        return null;
+      }
+      return parsed;
+    }
+    return null;
   } catch {
     return null;
   }
@@ -85,26 +122,21 @@ function hydrateSageMakerEnv(sagemaker: StoredSageMakerCredentials): void {
 export async function beginModeSwitch(to: "takara" | "sagemaker"): Promise<void> {
   const stored = await readStoredCredentials();
   if (to === "takara") {
-    clearSageMakerEnv(stored?.sagemaker);
+    clearSageMakerEnv(stored?.kind === "sagemaker" ? stored : undefined);
   } else {
     clearTakaraEnv();
   }
 }
 
-async function writeExclusive(payload: StoredCredentials): Promise<string> {
-  const dir = resolveCredentialsDir();
-  const path = resolveCredentialsPath();
-  await mkdir(dir, { recursive: true, mode: 0o700 });
-  await Bun.write(path, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
-  try {
-    await chmod(path, 0o600);
-  } catch {
-    // Windows may not support Unix mode bits on all filesystems.
-  }
-  return path;
+function envUsesStoredToken(): boolean {
+  return activeStoredToken !== null && process.env.TAKARA_API_KEY === activeStoredToken;
+}
+
+function markLoadedToken(token: string): void {
+  setStoredCredentialsEnvToken(token);
 }
 
-/** Apply credentials.json as the sole mode — never leave Takara and SageMaker both active. */
+/** Hydrate TAKARA_API_KEY / SageMaker env vars from the credentials file when env is unset. */
 export async function loadStoredCredentials(): Promise<boolean> {
   normalizeTakaraApiKeyEnv();
   const stored = await readStoredCredentials();
@@ -112,23 +144,10 @@ export async function loadStoredCredentials(): Promise<boolean> {
     return false;
   }
 
-  if (stored.takara_api_key) {
-    let changed = false;
-    if (!hasTakaraApiKeyInEnv()) {
-      process.env.TAKARA_API_KEY = stored.takara_api_key;
-      changed = true;
-    }
-    if (process.env.MIRU_SAGEMAKER_ENDPOINT_ARN || process.env.MIRU_SAGEMAKER_ENDPOINT_NAME) {
-      clearSageMakerEnv(stored.sagemaker);
-      changed = true;
-    }
-    return changed;
-  }
-
-  if (stored.sagemaker) {
+  if (stored.kind === "sagemaker") {
     let changed = false;
     if (!process.env.MIRU_SAGEMAKER_ENDPOINT_ARN?.trim()) {
-      hydrateSageMakerEnv(stored.sagemaker);
+      hydrateSageMakerEnv(stored);
       changed = true;
     }
     if (hasTakaraApiKeyInEnv()) {
@@ -137,26 +156,102 @@ export async function loadStoredCredentials(): Promise<boolean> {
     }
     return changed;
   }
-  return false;
-}
 
-export async function saveStoredCredentials(apiKey: string): Promise<string> {
-  const previous = await readStoredCredentials();
-  const path = await writeExclusive({ version: CREDENTIALS_VERSION, takara_api_key: apiKey });
-  process.env.TAKARA_API_KEY = apiKey;
-  clearSageMakerEnv(previous?.sagemaker);
-  return path;
+  // Takara token modes (api_key / device_code) are mutually exclusive with SageMaker.
+  const needsSageMakerClear = Boolean(
+    process.env.MIRU_SAGEMAKER_ENDPOINT_ARN || process.env.MIRU_SAGEMAKER_ENDPOINT_NAME,
+  );
+  const needsToken = !hasTakaraApiKeyInEnv() || envUsesStoredToken();
+
+  if (!needsToken && !needsSageMakerClear) {
+    return false;
+  }
+
+  if (needsSageMakerClear) {
+    clearSageMakerEnv();
+  }
+
+  if (!needsToken) {
+    return true;
+  }
+
+  if (stored.kind === "device_code" && deviceCredentialsNeedRefresh(stored)) {
+    const refreshed = await refreshDeviceAuthorization(stored);
+    await saveStoredCredentials({
+      kind: "device_code",
+      accessToken: refreshed.accessToken,
+      refreshToken: refreshed.refreshToken,
+      expiresAt: refreshed.expiresAt,
+      tokenType: refreshed.tokenType,
+      scope: refreshed.scope,
+    });
+    markLoadedToken(refreshed.accessToken);
+    return true;
+  }
+  markLoadedToken(credentialAccessToken(stored));
+  return true;
 }
 
-export async function saveStoredSageMakerCredentials(
-  sagemaker: StoredSageMakerCredentials,
-): Promise<string> {
-  const path = await writeExclusive({ version: CREDENTIALS_VERSION, sagemaker });
-  clearTakaraEnv();
-  process.env.MIRU_SAGEMAKER_ENDPOINT_ARN = sagemaker.endpoint_arn;
-  if (sagemaker.profile) {
-    process.env.AWS_PROFILE = sagemaker.profile;
+export async function saveStoredCredentials(input: SaveStoredCredentialsInput): Promise<string> {
+  const dir = resolveCredentialsDir();
+  const path = resolveCredentialsPath();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+
+  const payload: StoredCredentials =
+    typeof input === "string" || input.kind === "api_key"
+      ? {
+          version: CREDENTIALS_VERSION,
+          kind: "api_key",
+          api_key: typeof input === "string" ? input : input.apiKey,
+        }
+      : input.kind === "sagemaker"
+        ? {
+            version: CREDENTIALS_VERSION,
+            kind: "sagemaker",
+            endpoint_arn: input.endpointArn,
+            profile: input.profile,
+          }
+        : {
+            version: CREDENTIALS_VERSION,
+            kind: "device_code",
+            access_token: input.accessToken,
+            refresh_token: input.refreshToken,
+            expires_at: input.expiresAt,
+            token_type: input.tokenType,
+            scope: input.scope,
+          };
+
+  await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Windows may not support Unix mode bits on all filesystems.
+  }
+
+  // Takara-token and SageMaker modes are mutually exclusive — activating one mode
+  // unconditionally drops the other's env state, regardless of its current value.
+  if (payload.kind === "sagemaker") {
+    clearTakaraEnv();
+    activeStoredToken = null;
+    process.env.MIRU_SAGEMAKER_ENDPOINT_ARN = payload.endpoint_arn;
+    if (payload.profile) {
+      process.env.AWS_PROFILE = payload.profile;
+    }
+  } else {
+    delete process.env.MIRU_SAGEMAKER_ENDPOINT_ARN;
+    delete process.env.MIRU_SAGEMAKER_ENDPOINT_NAME;
+    delete process.env.MIRU_SAGEMAKER_REGION;
+    delete process.env.AWS_PROFILE;
+    // api_key saves activate immediately; device_code saves (initial login or refresh)
+    // leave env hydration to the caller (setup.ts / loadStoredCredentials refresh path).
+    if (payload.kind === "api_key") {
+      setStoredCredentialsEnvToken(payload.api_key);
+    }
   }
+
   return path;
 }
 
@@ -166,15 +261,28 @@ export async function clearStoredCredentials(): Promise<{ cleared: boolean; path
     return { cleared: false, path };
   }
 
-  const stored = await readStoredCredentials();
-  await Bun.file(path).delete();
-
-  if (stored?.takara_api_key && process.env.TAKARA_API_KEY === stored.takara_api_key) {
-    clearTakaraEnv();
+  // Read for env cleanup, but never let parse errors block deletion.
+  let stored: StoredCredentials | null = null;
+  try {
+    stored = await readStoredCredentials();
+  } catch {
+    // Ignore parse/read errors — removal still proceeds.
   }
-  if (stored?.sagemaker) {
-    clearSageMakerEnv(stored.sagemaker);
+  await rm(path, { force: true });
+
+  if (stored) {
+    if (stored.kind === "sagemaker") {
+      if (process.env.MIRU_SAGEMAKER_ENDPOINT_ARN === stored.endpoint_arn) {
+        delete process.env.MIRU_SAGEMAKER_ENDPOINT_ARN;
+      }
+      if (stored.profile && process.env.AWS_PROFILE === stored.profile) {
+        delete process.env.AWS_PROFILE;
+      }
+    } else if (process.env.TAKARA_API_KEY === credentialAccessToken(stored)) {
+      delete process.env.TAKARA_API_KEY;
+    }
   }
+  activeStoredToken = null;
 
   return { cleared: true, path };
 }

package/src/embeddings/openai.ts

@@ -1,4 +1,5 @@
 import { mapPool, resolveWorkerConcurrency } from "../concurrency.ts";
+import { loadStoredCredentials } from "../credentials.ts";
 import { envFirstString, envOptionalInt, resolveEmbeddingApiKey } from "../env.ts";
 import { createSageMakerClient, resolveSageMakerConfig } from "./sagemaker.ts";
 
@@ -346,8 +347,6 @@ class EmbeddingApiError extends Error {
 }
 
 function createClient(): EmbeddingClient {
-  const apiKey = resolveEmbeddingApiKey();
-
   const baseUrl = resolveEmbeddingBaseUrl();
   const endpoint = `${baseUrl}/embeddings`;
 
@@ -357,6 +356,8 @@ function createClient(): EmbeddingClient {
       model: string,
       dimensions?: number,
     ): Promise<EmbeddingResponse> {
+      await loadStoredCredentials();
+      const apiKey = resolveEmbeddingApiKey();
       const body: Record<string, unknown> = { model, input };
       if (dimensions != null) {
         body.dimensions = dimensions;

package/src/env.ts

@@ -1,3 +1,5 @@
+import { CredentialsError } from "./auth/errors.ts";
+
 export function envInt(name: string, fallback: number, min = 1): number {
   const raw = process.env[name];
   if (!raw) {
@@ -59,8 +61,10 @@ export function hasTakaraApiKeyInEnv(): boolean {
 export function resolveEmbeddingApiKey(): string {
   const key = process.env[TAKARA_API_KEY_ENV]?.trim() ?? "";
   if (!isUsableTakaraApiKey(key)) {
-    throw new Error(
-      "Takara API key required. Run `miru setup`, or set TAKARA_API_KEY in your MCP server env or .env.local.",
+    throw new CredentialsError(
+      "Takara credentials required. If you're an agent with Miru MCP tools available, call the " +
+        "`auth` tool to sign in. Otherwise run `miru setup`, or set TAKARA_API_KEY in your MCP " +
+        "server env or .env.local.",
     );
   }
   return key;