@takara-ai/miru-code 1.5.3 → 1.7.2

package/README.md

@@ -1,8 +1,22 @@
 # Miru (見る)
 
-Your AI agent finds the code it needs in 60% fewer tokens.
+[![CI](https://github.com/takara-ai/miru-code/actions/workflows/ci.yml/badge.svg)](https://github.com/takara-ai/miru-code/actions/workflows/ci.yml) [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE) [![bun](https://img.shields.io/badge/runtime-bun%201.1%2B-black)](https://bun.sh)
+
+
+**Hybrid code search for AI coding agents.** Find code by meaning, not grep.
+
+Your AI agent finds the code it needs with up to 50% fewer tokens.
+
+Miru returns the best **chunks** (path, lines, snippet) for questions like *"where is auth middleware configured?"* — plugged directly into Claude Code, Cursor, Copilot, Codex, and 9+ other agents via MCP.
+
+---
+
+## How it fits into your agent's workflow
+
+![How Miru fits into an agent's workflow](docs/miru-workflow-diagram.svg)
+
+Miru replaces the grep/glob-style search agents fall back on today. Install once, and every connected agent gets `search` and `find_related` MCP tools automatically.
 
-**Requires:** [Bun](https://bun.sh) 1.1+ · [Takara API key](https://takara.ai)
 
 ## Install
 
@@ -10,20 +24,21 @@ Your AI agent finds the code it needs in 60% fewer tokens.
 bun add -g @takara-ai/miru-code
 ```
 
-## Set up API key
+## Set up credentials
 
 ```bash
 miru setup
 ```
 
-Validates your key and saves it locally. Skip this if you prefer — `miru search` or `miru install` will prompt on first run.
+Interactive `miru setup` defaults to device-code login and saves the resulting credentials locally. Manual bearer-token entry is still available with `--key`. If credentials are missing, the interactive MCP/plugin path can bootstrap the same device flow automatically on first use.
 
 ```bash
-miru setup --key YOUR_TOKEN   # non-interactive
-miru setup --clear            # remove stored key
+miru setup --device           # explicit device-code login
+miru setup --key YOUR_TOKEN   # store a bearer token directly
+miru setup --clear            # remove stored credentials
 ```
 
-MCP loads your key from `credentials.json` automatically — no env block needed in MCP config.
+Miru stores versioned credentials in `credentials.json` and automatically loads or refreshes them for MCP and CLI use. `TAKARA_API_KEY` still overrides stored credentials when set explicitly.
 
 ## Add to your IDE
 
@@ -41,6 +56,8 @@ Interactive TUI — **↑↓** move, **space** toggle, **a** all, **enter** conf
 | Sub-agent                     | Dedicated `miru-code` agent file                                    |
 | Cursor rules                  | Always-on `.cursor/rules/miru-code.mdc` (Cursor only)               |
 | Search hooks *(experimental)* | Block built-in Grep/Glob and redirect to Miru MCP                   |
+| Caveman *(experimental)*      | On-demand chat compression skill (`/caveman`)                       |
+| STE writing *(experimental)*  | On-demand clear technical English for docs (`/ste`)                 |
 
 
 Restart the IDE when done.
@@ -52,21 +69,59 @@ miru uninstall   # remove miru config
 **Supported:** Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code · Visual Studio (Windows) · Windsurf / Devin Desktop
 
 
-| IDE            | MCP                                   | Instructions / rules            | Hooks *(experimental)*                            |
-| -------------- | ------------------------------------- | ------------------------------- | ------------------------------------------------- |
-| Cursor         | `~/.cursor/mcp.json`                  | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json`                            |
-| Claude Code    | `~/.claude.json`                      | `~/.claude/CLAUDE.md`           | `~/.claude/settings.json`                         |
-| Gemini CLI     | `~/.gemini/settings.json`             | `~/.gemini/GEMINI.md`           | `~/.gemini/settings.json` (`BeforeTool`)          |
-| Kiro           | `~/.kiro/settings/mcp.json`           | `~/.kiro/steering/miru.md`      | `~/.kiro/settings/hooks.json`                     |
-| OpenCode       | `~/.config/opencode/opencode.json(c)` | `~/.config/opencode/AGENTS.md`  | `~/.config/opencode/plugins/miru-search-guard.ts` |
-| GitHub Copilot | `~/.copilot/mcp-config.json`          | —                               | `~/.copilot/hooks/miru-search.json`               |
-| Codex          | `~/.codex/config.toml`                | `~/.codex/AGENTS.md`            | `~/.codex/hooks.json`                             |
-| VS Code        | `…/Code/User/mcp.json`                | —                               | `~/.copilot/hooks/miru-search.json`               |
-| Visual Studio  | `%USERPROFILE%\.mcp.json`             | —                               | `~/.copilot/hooks/miru-search.json`               |
-| Windsurf       | —                                     | —                               | `~/.codeium/windsurf/hooks.json`                  |
+| IDE            | MCP                                   | Instructions / rules            | Hooks *(experimental)*                            | Caveman *(experimental)*                            | STE *(experimental)*                         |
+| -------------- | ------------------------------------- | ------------------------------- | ------------------------------------------------- | --------------------------------------------------- | -------------------------------------------- |
+| Cursor         | `~/.cursor/mcp.json`                  | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json`                            | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Claude Code    | `~/.claude.json`                      | `~/.claude/CLAUDE.md`           | `~/.claude/settings.json`                         | `~/.claude/skills/caveman/SKILL.md`                 | `~/.claude/skills/ste/SKILL.md`              |
+| Gemini CLI     | `~/.gemini/settings.json`             | `~/.gemini/GEMINI.md`           | `~/.gemini/settings.json` (`BeforeTool`)          | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Kiro           | `~/.kiro/settings/mcp.json`           | `~/.kiro/steering/miru.md`      | `~/.kiro/settings/hooks.json`                     | `~/.kiro/skills/caveman/SKILL.md`                   | `~/.kiro/skills/ste/SKILL.md`                |
+| OpenCode       | `$XDG_CONFIG_HOME/opencode/opencode.json(c)` *(else `~/.config/opencode/…`)* | `…/AGENTS.md` | `…/plugins/miru-search-guard.ts` | `~/.agents/skills/caveman/SKILL.md` | `~/.agents/skills/ste/SKILL.md` |
+| GitHub Copilot | `~/.copilot/mcp-config.json`          | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Codex          | `~/.codex/config.toml`                | `~/.codex/AGENTS.md`            | `~/.codex/hooks.json`                             | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| VS Code        | `…/Code/User/mcp.json`                | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Visual Studio  | `%USERPROFILE%\.mcp.json`             | —                               | `~/.copilot/hooks/miru-search.json`               | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+| Windsurf       | —                                     | —                               | `~/.codeium/windsurf/hooks.json`                  | `~/.agents/skills/caveman/SKILL.md`                 | `~/.agents/skills/ste/SKILL.md`              |
+
+
+### Plugin packaging
+
+This repo now includes plugin packaging for:
+
+- Codex: `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`
+- Claude Code: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+- Cursor: `plugin.json` and `.cursor/rules/miru-code-search.mdc`
+
+Current limitation:
+
+- these plugin manifests still launch the published Miru runtime through `bunx @takara-ai/miru-code`
+- that means local source edits do not affect plugin behavior until a package version is published
+- and a fully self-contained “no Bun required” plugin install is still future work
+
+### Search hooks
+
+Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only *(experimental)* — no MCP entry yet. Caveman is an on-demand Agent Skill (default off): invoke with `/caveman` or “talk like caveman”; stop with “normal mode”. Invocation UI varies by IDE (`/caveman`, `$caveman`, `@caveman`, etc.). Most IDEs share `~/.agents/skills/caveman/SKILL.md` (including Copilot / VS Code / Visual Studio); Claude Code and Kiro keep vendor-native skill dirs. Ownership is tracked on the shared path so uninstalling one IDE keeps the skill while another still owns it; selecting all owners removes it once. STE is an on-demand Agent Skill (default off): invoke with `/ste` or “de-slop this”; keep articles and complete sentences. Most IDEs share `~/.agents/skills/ste/` the same way (ownership via `miru-owners.json`); Claude Code and Kiro keep vendor-native STE dirs.
+
+<details>
+<summary>STE writing <em>(experimental)</em></summary>
+
+STE helps write **clear technical English** for docs, runbooks, errors, and release notes (pragmatic ASD-STE100-inspired rules). Invoke with `/ste` or “de-slop this”. Keep articles and complete sentences — not telegraph-style omission.
+
+**Not ASD-certified.** Full dictionary compliance needs the official standard at [asd-ste100.org](https://www.asd-ste100.org). Miru does not ship the copyrighted ASD dictionary.
+
+Not for marketing or brand copy. Off by default; enable STE in the installer for any supported IDE. Restart the IDE (or reload skills) after install. For Codex, install also sets `[features] skills = true` in `~/.codex/config.toml` (same as Caveman).
+
+</details>
+
+<details>
+<summary>Caveman mode <em>(experimental)</em></summary>
+
+Caveman compresses **live chat replies** (less filler, max meaning). Intensities: `/caveman lite|full|ultra` (default full). Persisted artifacts (commits, PRs, customer docs) stay normal prose unless you ask otherwise.
 
+Security / destructive warnings use clear normal prose (auto-clarity) — brevity never hides risk. Session token savings vary; the skill itself costs input tokens. No guaranteed %.
 
-Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only *(experimental)* — no MCP entry yet.
+Off by default at install time. Enable Caveman in the installer for any supported IDE. Restart the IDE (or reload skills) after install. For Codex, the installer also sets `[features] skills = true` in `~/.codex/config.toml` (required for Codex to load skills).
+
+</details>
 
 <details>
 <summary>Search hooks <em>(experimental)</em></summary>
@@ -180,10 +235,11 @@ Set `MIRU_AST_CHUNKING=0` to disable AST and use structural → lines only.
 
 ## CLI reference
 
+Run `miru -h` for the command list, or `miru <command> -h` for details.
 
 | Command                                  | Purpose                                                                           |
-| ---------------------------------------- | --------------------------------------------------------------------------------- |
-| `miru setup`                             | Store API key                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------- |
+| `miru setup`                             | Authenticate and store credentials                                                |
 | `miru install`                           | Configure IDE (global)                                                            |
 | `miru uninstall`                         | Remove IDE config                                                                     |
 | `miru search <query> [path]`             | Search (`-k N`, `--content`, `--json`)                                            |
@@ -335,7 +391,7 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 
 For benchmark mode, set `"args": ["--benchmark"]` (or append that flag). Prefer `miru benchmark on` after a normal install — it updates every agent config.
 
-Run `miru setup` once so the server can load your key from `credentials.json`.
+Run `miru setup` once so the server can load credentials from `credentials.json`. If the MCP server starts in an interactive terminal without stored credentials, it will start device login automatically.
 
 Use `bunx` + `@takara-ai/miru-code` if `miru` is not global. Wrapper key varies by IDE (`mcpServers`, `servers`, or `mcp`).
 
@@ -347,10 +403,31 @@ bun install && cp .env.example .env.local
 bun test && bun run typecheck
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pre-commit hooks, commit message conventions, and the PR process.
+
 Local MCP: `"command": "bun", "args": ["/path/to/miru-code/src/cli.ts"]`
 
-`miru help` / setup print a framed wordmark on color terminals (`MIRU_QUIET=1` for subtitle only). Crane art lives in `src/brand-banner.ts`; regenerate with `bun run scripts/render-crane-art.ts` (ImageMagick). The crane is a registered mark of Takara.ai Ltd.
+`miru -h` / setup print a framed wordmark on color terminals (`MIRU_QUIET=1` for subtitle only). Crane art lives in `src/brand-banner.ts`; regenerate with `bun run scripts/render-crane-art.ts` (ImageMagick). The crane is a registered mark of Takara.ai Ltd.
+
+## Codex plugin in this repo
+
+This repo includes a repo-local Codex plugin:
+
+- `.codex-plugin/plugin.json`
+- `.mcp.json`
+- `.agents/plugins/marketplace.json`
+
+The plugin intentionally launches the published package with `bunx @takara-ai/miru-code` instead of the checked-out source tree, so local source edits here do not affect the Codex plugin until a new package version is published.
+
+## Credits
+
+Miru uses work by [MinishLab](https://github.com/MinishLab). Thank you to its authors.
+
+- **[semble](https://github.com/MinishLab/semble)** (MIT). Miru ports parts of semble. These parts include the file walker, the index layout, the BM25 tokenizer, the hybrid search pipeline, and the ranking signals.
+- **[potion-code](https://huggingface.co/minishlab/potion-code-16M)** and **[Model2Vec](https://github.com/MinishLab/model2vec)** (MIT). The WordPiece tokenizer in `tokenizer/tokenizer.json` comes from potion-code.
+
+See [NOTICE](./NOTICE) for the licence text and the Model2Vec citation.
 
 ## License
 
-MIT
+MIT

package/docs/miru-workflow-diagram.svg

@@ -0,0 +1,47 @@
+<svg width="800" height="280" viewBox="0 0 800 280" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="miru-diagram-title miru-diagram-desc">
+  <title id="miru-diagram-title">How Miru fits into an agent's code search workflow</title>
+  <desc id="miru-diagram-desc">A coding agent sends a natural-language query to the Miru MCP server, which runs hybrid search (AST-aware embeddings plus BM25 and reranking) over the indexed repository, then returns ranked code chunks back to the agent.</desc>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M1 1L8 5L1 9" fill="none" stroke="#4A4D4E" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+  </defs>
+
+  <rect x="0" y="0" width="800" height="280" fill="#FFFFFF"/>
+
+  <text x="400" y="34" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="13" fill="#4A4D4E">
+    Replaces the grep/glob-style search agents fall back on today
+  </text>
+
+  <!-- Coding agent -->
+  <g>
+    <rect x="40" y="100" width="180" height="80" rx="10" fill="#FFFFFF" stroke="#4A4D4E" stroke-width="1.5"/>
+    <text x="130" y="134" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="16" font-weight="600" fill="#000000">Coding agent</text>
+    <text x="130" y="156" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12" fill="#4A4D4E">"where's auth set up?"</text>
+  </g>
+
+  <line x1="220" y1="140" x2="288" y2="140" stroke="#4A4D4E" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <!-- Miru MCP server (hero box, Takara Red) -->
+  <g>
+    <rect x="290" y="70" width="220" height="140" rx="10" fill="#D91009"/>
+    <text x="400" y="106" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="17" font-weight="700" fill="#FFFFFF">Miru MCP server</text>
+    <text x="400" y="132" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12.5" fill="#FFFFFF">AST-aware embeddings</text>
+    <text x="400" y="150" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12.5" fill="#FFFFFF">+ BM25 + reranking</text>
+    <text x="400" y="168" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12.5" fill="#FFFFFF">over indexed repo</text>
+  </g>
+
+  <line x1="510" y1="140" x2="578" y2="140" stroke="#4A4D4E" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <!-- Ranked chunks (accent, Azure Blue) -->
+  <g>
+    <rect x="580" y="100" width="180" height="80" rx="10" fill="#FFFFFF" stroke="#00A3EE" stroke-width="1.75"/>
+    <text x="670" y="134" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="16" font-weight="600" fill="#00668F">Ranked chunks</text>
+    <text x="670" y="156" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12" fill="#4A4D4E">path, lines, snippet</text>
+  </g>
+
+  <text x="400" y="248" text-anchor="middle" font-family="Lato, 'Gill Sans', sans-serif" font-size="12" fill="#4A4D4E">
+    Every connected agent (Cursor, Claude Code, Copilot, Codex, and more) gets this via MCP
+  </text>
+</svg>

package/docs/self-hosted-sagemaker.md

@@ -113,4 +113,4 @@ Prefer `miru setup --sagemaker` so auth is checked automatically. You can also s
 
 Optional TEI-style knobs: `MIRU_SAGEMAKER_NORMALIZE`, `MIRU_SAGEMAKER_TRUNCATE`, `MIRU_SAGEMAKER_TRUNCATION_DIRECTION`, `MIRU_SAGEMAKER_PROMPT_NAME`.
 
-See `miru help setup` and `miru -h` for the same flags in the CLI.
+See `miru help setup` and `miru -h` for the same flags in the CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.5.3",
+  "version": "1.7.2",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "grammars",
     "tokenizer",
     "docs",
+    "scripts/install-git-hooks.ts",
     "README.md",
     "LICENSE"
   ],
@@ -52,6 +53,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "prepare": "bun run scripts/install-git-hooks.ts",
     "vendor-grammars": "bun run scripts/vendor-grammars.ts",
     "prepublishOnly": "bun run vendor-grammars && bun run typecheck && bun test",
     "benchmark:ab": "bun run scripts/search-ab-local.ts",

package/scripts/install-git-hooks.ts

@@ -0,0 +1,29 @@
+/**
+ * package.json `prepare` — wire prek git hooks when developing from a clone.
+ * Bun-native (no shell redirects) so `bun install` works on Windows CI.
+ *
+ * Skips when not a git checkout or `prek` is missing from PATH.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+if (!existsSync(join(root, ".git"))) {
+  process.exit(0);
+}
+
+const prek = Bun.which("prek");
+if (!prek) {
+  console.log("prek not found; skipping git hook install (see CONTRIBUTING.md)");
+  process.exit(0);
+}
+
+const result = Bun.spawnSync([prek, "install", "--install-hooks"], {
+  cwd: root,
+  stdout: "inherit",
+  stderr: "inherit",
+});
+
+process.exit(result.exitCode === 0 ? 0 : (result.exitCode ?? 1));

package/src/auth/device.ts

@@ -0,0 +1,306 @@
+import { envFirstString } from "../env.ts";
+import { CredentialsError } from "./errors.ts";
+import type { StoredDeviceCodeCredentials } from "./types.ts";
+
+const DEFAULT_AUTH_BASE_URL = "https://auth.takara.ai";
+const DEFAULT_DEVICE_CODE_PATH = "/oauth/device/code";
+const DEFAULT_TOKEN_PATH = "/oauth/token";
+const DEFAULT_CLIENT_ID = "miru-code";
+const EXPIRY_SKEW_MS = 60_000;
+
+export interface DeviceAuthConfig {
+  baseUrl: string;
+  clientId: string;
+  scope?: string;
+  audience?: string;
+  deviceCodePath: string;
+  tokenPath: string;
+}
+
+export interface DeviceAuthorizationStart {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresIn: number;
+  interval: number;
+}
+
+export interface DeviceAuthorizationTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: string;
+  tokenType?: string;
+  scope?: string;
+}
+
+interface OAuthTokenSuccess {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+  scope?: string;
+}
+
+interface OAuthTokenError {
+  error?: string;
+  error_description?: string;
+}
+
+export function resolveDeviceAuthConfig(): DeviceAuthConfig {
+  return {
+    baseUrl: envFirstString(["MIRU_AUTH_BASE_URL"], DEFAULT_AUTH_BASE_URL).replace(/\/$/, ""),
+    clientId: envFirstString(["MIRU_AUTH_CLIENT_ID"], DEFAULT_CLIENT_ID),
+    scope: process.env.MIRU_AUTH_SCOPE?.trim() || undefined,
+    audience: process.env.MIRU_AUTH_AUDIENCE?.trim() || undefined,
+    deviceCodePath: process.env.MIRU_DEVICE_CODE_PATH?.trim() || DEFAULT_DEVICE_CODE_PATH,
+    tokenPath: process.env.MIRU_TOKEN_PATH?.trim() || DEFAULT_TOKEN_PATH,
+  };
+}
+
+function resolveUrl(baseUrl: string, path: string): string {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+function tokenExpiryToIso(expiresIn?: number): string | undefined {
+  if (expiresIn == null || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    return undefined;
+  }
+  return new Date(Date.now() + expiresIn * 1000).toISOString();
+}
+
+function normalizeTokenSuccess(payload: OAuthTokenSuccess): DeviceAuthorizationTokens {
+  return {
+    accessToken: payload.access_token,
+    refreshToken: payload.refresh_token,
+    expiresAt: tokenExpiryToIso(payload.expires_in),
+    tokenType: payload.token_type,
+    scope: payload.scope,
+  };
+}
+
+function parseTokenError(payload: OAuthTokenError): string {
+  const code = payload.error?.trim();
+  const description = payload.error_description?.trim();
+  if (code && description) {
+    return `${code}: ${description}`;
+  }
+  return code || description || "unknown_error";
+}
+
+async function postForm(
+  url: string,
+  body: URLSearchParams,
+  fetchImpl: typeof fetch,
+): Promise<Response> {
+  return fetchImpl(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+}
+
+export async function startDeviceAuthorization(options?: {
+  config?: DeviceAuthConfig;
+  fetchImpl?: typeof fetch;
+}): Promise<DeviceAuthorizationStart> {
+  const config = options?.config ?? resolveDeviceAuthConfig();
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const body = new URLSearchParams({ client_id: config.clientId });
+  if (config.scope) {
+    body.set("scope", config.scope);
+  }
+  if (config.audience) {
+    body.set("audience", config.audience);
+  }
+
+  const response = await postForm(
+    resolveUrl(config.baseUrl, config.deviceCodePath),
+    body,
+    fetchImpl,
+  );
+  const text = await response.text();
+  const payload = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+  if (!response.ok) {
+    throw new Error(`Device authorization failed: ${text || response.statusText}`);
+  }
+
+  const deviceCode = String(payload.device_code ?? "").trim();
+  const userCode = String(payload.user_code ?? "").trim();
+  const verificationUri = String(payload.verification_uri ?? payload.verification_url ?? "").trim();
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new Error("Device authorization response was missing required fields.");
+  }
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    verificationUriComplete:
+      typeof payload.verification_uri_complete === "string"
+        ? payload.verification_uri_complete
+        : undefined,
+    expiresIn:
+      typeof payload.expires_in === "number" && payload.expires_in > 0 ? payload.expires_in : 600,
+    interval: typeof payload.interval === "number" && payload.interval >= 0 ? payload.interval : 5,
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export type DeviceAuthorizationCheck =
+  | { status: "success"; tokens: DeviceAuthorizationTokens }
+  | { status: "pending" }
+  | { status: "slow_down" }
+  | { status: "denied" }
+  | { status: "expired" };
+
+/**
+ * Single non-blocking poll attempt against the token endpoint — no internal
+ * sleep. Used directly by the `auth` MCP tool (one check per tool call, so a
+ * call never blocks for the device code's full expiry window), and by
+ * pollDeviceAuthorization's blocking loop below for the CLI path.
+ */
+export async function checkDeviceAuthorizationOnce(
+  start: DeviceAuthorizationStart,
+  options?: { config?: DeviceAuthConfig; fetchImpl?: typeof fetch },
+): Promise<DeviceAuthorizationCheck> {
+  const config = options?.config ?? resolveDeviceAuthConfig();
+  const fetchImpl = options?.fetchImpl ?? fetch;
+
+  const body = new URLSearchParams({
+    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+    device_code: start.deviceCode,
+    client_id: config.clientId,
+  });
+  const response = await postForm(resolveUrl(config.baseUrl, config.tokenPath), body, fetchImpl);
+  const text = await response.text();
+  const payload = text ? (JSON.parse(text) as OAuthTokenSuccess | OAuthTokenError) : {};
+
+  if (response.ok) {
+    const success = payload as OAuthTokenSuccess;
+    if (!success.access_token?.trim()) {
+      throw new Error("Device login succeeded but did not return an access token.");
+    }
+    return { status: "success", tokens: normalizeTokenSuccess(success) };
+  }
+
+  const error = (payload as OAuthTokenError).error;
+  if (error === "authorization_pending") {
+    return { status: "pending" };
+  }
+  if (error === "slow_down") {
+    return { status: "slow_down" };
+  }
+  if (error === "access_denied") {
+    return { status: "denied" };
+  }
+  if (error === "expired_token") {
+    return { status: "expired" };
+  }
+  throw new Error(`Device login failed: ${parseTokenError(payload as OAuthTokenError)}`);
+}
+
+export async function pollDeviceAuthorization(
+  start: DeviceAuthorizationStart,
+  options?: { config?: DeviceAuthConfig; fetchImpl?: typeof fetch },
+): Promise<DeviceAuthorizationTokens> {
+  const deadline = Date.now() + start.expiresIn * 1000;
+  let intervalMs = start.interval * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+
+    const check = await checkDeviceAuthorizationOnce(start, options);
+    if (check.status === "success") {
+      return check.tokens;
+    }
+    if (check.status === "pending") {
+      continue;
+    }
+    if (check.status === "slow_down") {
+      intervalMs += 5_000;
+      continue;
+    }
+    if (check.status === "denied") {
+      throw new Error("Device login was denied.");
+    }
+    if (check.status === "expired") {
+      throw new Error("Device login expired before it was completed.");
+    }
+  }
+
+  throw new Error("Device login timed out before it was completed.");
+}
+
+export async function refreshDeviceAuthorization(
+  credentials: StoredDeviceCodeCredentials,
+  options?: { config?: DeviceAuthConfig; fetchImpl?: typeof fetch },
+): Promise<DeviceAuthorizationTokens> {
+  if (!credentials.refresh_token?.trim()) {
+    throw new CredentialsError(
+      "Stored device credentials cannot be refreshed because no refresh token exists.",
+    );
+  }
+
+  const config = options?.config ?? resolveDeviceAuthConfig();
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: credentials.refresh_token,
+    client_id: config.clientId,
+  });
+  const response = await postForm(resolveUrl(config.baseUrl, config.tokenPath), body, fetchImpl);
+  const text = await response.text();
+  const payload = text ? (JSON.parse(text) as OAuthTokenSuccess | OAuthTokenError) : {};
+
+  if (!response.ok) {
+    throw new CredentialsError(
+      `Device token refresh failed: ${parseTokenError(payload as OAuthTokenError)}`,
+    );
+  }
+
+  const success = payload as OAuthTokenSuccess;
+  if (!success.access_token?.trim()) {
+    throw new CredentialsError("Token refresh succeeded but did not return an access token.");
+  }
+
+  return normalizeTokenSuccess({
+    ...success,
+    refresh_token: success.refresh_token ?? credentials.refresh_token,
+  });
+}
+
+export function deviceCredentialsNeedRefresh(credentials: StoredDeviceCodeCredentials): boolean {
+  if (!credentials.expires_at) {
+    return false;
+  }
+  const expiresAt = Date.parse(credentials.expires_at);
+  if (!Number.isFinite(expiresAt)) {
+    return true;
+  }
+  return expiresAt <= Date.now() + EXPIRY_SKEW_MS;
+}
+
+export function openBrowserForDeviceLogin(url: string): boolean {
+  const command =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url];
+  try {
+    const proc = Bun.spawn(command, {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    // Detach so the spinner's event loop / process lifecycle can't kill `open`.
+    proc.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/auth/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * Signals that Miru has no usable credentials — missing, expired, or revoked.
+ * Callers that can recover (the MCP `auth` tool, `miru setup`) branch on this
+ * instead of matching error text.
+ */
+export class CredentialsError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "CredentialsError";
+  }
+}
+
+/** True when `error`, or anything in its `cause` chain, is a CredentialsError. */
+export function isCredentialsError(error: unknown): boolean {
+  let current: unknown = error;
+  // Bounded so a self-referencing cause chain cannot spin forever.
+  for (let depth = 0; depth < 10 && current instanceof Error; depth++) {
+    if (current instanceof CredentialsError) {
+      return true;
+    }
+    current = current.cause;
+  }
+  return false;
+}