@takara-ai/miru-code 1.5.3 → 1.7.2

package/src/installer/style-packs/caveman.ts

@@ -0,0 +1,118 @@
+/**
+ * Caveman mode — on-demand Agent Skill body (chat compression).
+ * Installed by `miru install` (Phase B); content-only module for Phase A.
+ */
+
+export const CAVEMAN_SKILL_NAME = "caveman";
+
+/** Full `SKILL.md` (YAML frontmatter + body) written to the agent skill path. */
+export const CAVEMAN_SKILL_MD = `---
+name: caveman
+description: >-
+  Compress agent chat replies: less filler, max meaning. Use when the user
+  says caveman mode, /caveman, talk like caveman, be brief, or asks for fewer
+  tokens in chat. Intensities: /caveman lite|full|ultra. Stop with stop caveman
+  or normal mode. Chat narration only — not commits, PRs, or customer docs
+  unless the user asks.
+---
+
+# Caveman mode
+
+On-demand chat compression for Miru. **Brain big, mouth small.**
+
+Inspired by [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) — original Miru skill text.
+
+## Activate / stop
+
+| User says | Effect |
+|-----------|--------|
+| \`/caveman\`, \`caveman mode\`, \`talk like caveman\` | ON at **full** (default) |
+| \`/caveman lite\` | ON at lite |
+| \`/caveman full\` | ON at full |
+| \`/caveman ultra\` | ON at ultra |
+| \`stop caveman\`, \`normal mode\` | OFF — resume normal prose |
+
+Level sticks until the user changes it or the session ends. Do not stay in caveman after stop.
+
+## Intensity
+
+| Level | Behaviour |
+|-------|-----------|
+| **lite** | No polite filler, no task-restatement preamble. Keep articles and full sentences. Lead with the answer. |
+| **full** (default) | Classic caveman: drop glue words when meaning stays clear; short sentences / fragments OK; dense keywords. |
+| **ultra** | Maximum fragment compression. Still never sacrifice untouchables or safety (below). |
+
+## Style rules (when ON)
+
+- No polite talk ("sure", "happy to help", "great question")
+- No restating the user's task as a preamble
+- Lead with the answer
+- Prefer keywords / symbols (\`→\`, \`=\`, \`vs\`) over glue-heavy prose
+- Drop articles/copulas only when meaning stays clear
+- Short sentence or fragment OK
+
+## Auto-clarity (drop caveman for that segment)
+
+Use **normal clear prose** for:
+
+- Security warnings and security-relevant detail
+- Irreversible / destructive action confirmations (force-push, drop table, delete prod, etc.)
+- Multi-step sequences where fragment order could be misread
+- When the user asks to clarify or repeats a question
+
+Resume caveman after that segment if still ON.
+
+**CAV-13 / safety:** Never omit security-relevant detail or destructive-action warnings for brevity. Brevity never hides risk. If unsure, use normal prose for the warning.
+
+## Never sacrifice (untouchables)
+
+Byte-exact — do not compress or paraphrase:
+
+- Paths, file:line citations
+- Code fences and identifiers
+- CLI commands
+- Exact error strings / quoted text
+- Miru MCP tool use (\`search\` / \`locate\` / \`expand\` / \`find_related\`) when search policy is installed
+
+Caveman applies to surrounding prose only.
+
+## Chat vs persisted docs
+
+Default: caveman = **live chat replies only**.
+
+Commits, PR bodies, customer docs, READMEs, Linear text, memory files → **normal usable English** unless the user explicitly asks for caveman tone on that artifact.
+
+## Token honesty
+
+Output can shrink a lot on chatty replies. Session-level savings are often smaller; the skill itself costs input tokens each turn. No guaranteed % savings.
+
+## Clarity over parody
+
+If a reply is harder to use than normal concise prose, loosen grammar for that turn.
+
+## Examples
+
+### 1. Factual lookup
+
+**Before:**
+> Sure! I'd be happy to help. Looking at your question about where auth middleware is configured — I searched the codebase and it appears the authentication middleware is set up in \`src/auth/middleware.ts\` around line 42.
+
+**After (full):**
+> Auth middleware → \`src/auth/middleware.ts:42\`
+
+### 2. Recommendation
+
+**Before:**
+> Great question! There are a few approaches you could take here. I would generally recommend using the existing cache helper rather than rolling your own, because it already handles invalidation.
+
+**After (full):**
+> Use existing cache helper → handles invalidation. Don't roll own.
+
+### 3. Debug / failure finding
+
+**Before:**
+> I looked into the failure you described. It seems like the issue is that the API key is missing from the environment, which causes the client to throw a 401 Unauthorized when calling embeddings.
+
+**After (full):**
+> Fail = missing API key → embeddings 401 Unauthorized.
+`;

package/src/installer/style-packs/ste/skill.ts

@@ -0,0 +1,218 @@
+/**
+ * STE mode — on-demand Agent Skill + references (clear technical English).
+ * Unofficial ASD-STE100-inspired aid; not ASD-certified.
+ */
+
+export const STE_SKILL_NAME = "ste";
+
+export interface SteReferenceFile {
+  relativePath: string;
+  content: string;
+}
+
+/** Compact pragmatic `SKILL.md` (YAML frontmatter + body). */
+export const STE_SKILL_MD = `---
+name: ste
+description: >-
+  Clear technical English for docs, runbooks, errors, and release notes.
+  Use when the user says STE, ASD-STE100, /ste, de-slop, write for non-native
+  readers, or asks to rewrite technical prose. Pragmatic by default; strict
+  when they ask for STE compliance. Not for marketing or brand copy. Not for
+  ultra-compressed chat telegraph style.
+---
+
+# STE writing (Simplified Technical English)
+
+On-demand clear technical writing for Miru. **Short complete sentences. Keep articles.**
+
+Unofficial aid inspired by [ASD-STE100](https://www.asd-ste100.org) Issue 9 themes.
+**Not ASD-certified. Not ASD-endorsed.** Full dictionary compliance needs the official standard at asd-ste100.org.
+
+Inspired by prior art ([AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), [woosal STE kit](https://github.com/woosal1337/blog/tree/main/videos/ep01-the-cure-for-ai-slop)) — original Miru skill text. Do not vend copyrighted ASD dictionary word lists.
+
+## Activate
+
+| User says | Effect |
+|-----------|--------|
+| \`/ste\`, \`STE\`, \`write in STE\`, \`de-slop this\` | ON **pragmatic** (default) |
+| \`ASD-STE100\`, \`strict STE\`, \`STE compliance\` | ON **strict** — also load \`references/rules.md\` |
+| Check / audit my STE | Use \`references/checklist.md\` |
+
+## Task flow
+
+1. Select mode (pragmatic vs strict)
+2. Classify text as **procedural** or **descriptive**
+3. Pick one consistent term per concept
+4. Apply core rules below
+5. Run **self-check**
+6. Deliver
+
+## Modes
+
+| Mode | Behaviour |
+|------|-----------|
+| **Pragmatic** (default) | Structural rules + consistent terms. Domain nouns/verbs OK (\`webhook\`, \`deploy\`, \`commit\`). |
+| **Strict** | Stricter vocabulary discipline. Tell the user full compliance needs the official ASD dictionary: https://www.asd-ste100.org — then load \`references/rules.md\`. |
+
+Cite rule numbers **only** when they appear in \`references/rules.md\`. Do not invent ASD rule IDs.
+
+## Core rules (pragmatic)
+
+- Short **complete** sentences. Keep \`a\` / \`an\` / \`the\` and \`that\`. No telegraph omission.
+- No semicolons — use two sentences.
+- **Procedural:** imperative; about 20 words max per sentence; one instruction per sentence; **condition BEFORE command**.
+- **Descriptive:** simple tenses; about 25 words max per sentence; one topic per paragraph.
+- Active voice; simple tenses; avoid present-perfect stacks and comma "-ing" padding.
+- Prefer modals \`can\` / \`will\` / \`must\`. Avoid \`should\` / \`would\` / \`may\` / \`might\` / \`could\` in instructions.
+- One name per concept in the document (no check/verify/confirm/validate roulette).
+- Warnings: state the command or condition first, then the risk.
+
+## Untouchables
+
+Never alter:
+
+- Code fences, identifiers, CLI flags, paths
+- Quoted errors, product/API names
+- Required safety conditions, limits, versions
+
+If shortening would drop a required qualifier, keep the longer clear sentence.
+Miru MCP tool use stays intact when search policy is installed.
+
+## Not for marketing
+
+Do **not** apply STE to marketing, brand, or persuasive copy. Decline and offer a docs-oriented rewrite instead.
+
+## Slop → plain (examples)
+
+| Slop | Plain |
+|------|-------|
+| It is worth noting that the service is highly robust | The service stays up if the primary node fails |
+| You should consider carefully validating the input | You must validate the input |
+| Feel free to simply leverage the existing utility | Use the existing utility |
+
+## Before / after
+
+**Before (slop):**
+> It is worth noting that you should carefully ensure the migration has completed successfully before you proceed to delete the old volume, as doing so might potentially result in irreversible data loss.
+
+**After (STE pragmatic):**
+> Wait until the migration is complete. Then delete the old volume. If you delete the volume too early, you will lose data permanently.
+
+## Self-check (before delivery)
+
+1. Sentences complete with articles where needed?
+2. One instruction per procedural sentence; condition before command?
+3. Terms consistent; modals are can/will/must where instructions appear?
+4. Code, paths, errors, and safety limits untouched?
+
+For a longer audit, read \`references/checklist.md\`.
+
+## References
+
+- \`references/rules.md\` — fuller paraphrased rule catalog (strict / audit)
+- \`references/checklist.md\` — extended self-check patterns
+`;
+
+export const STE_RULES_MD = `# STE rules catalog (Miru paraphrase)
+
+Unofficial structural catalog for Miru STE **strict** / audit use.
+Themes follow ASD-STE100 Issue 9. **Not a copy of the official standard. Not a dictionary.**
+Official standard and dictionary: https://www.asd-ste100.org
+
+Cite the rule IDs below only. Do not invent other ASD numbers.
+
+## Words and terms
+
+### R1 — One name per concept
+Pick one term for each idea in the document. Do not rotate synonyms (\`check\` / \`verify\` / \`validate\`) for the same action.
+
+### R2 — Approved instruction modals
+In procedures, prefer \`can\`, \`will\`, \`must\`. Avoid \`should\`, \`would\`, \`may\`, \`might\`, \`could\` when you give an instruction.
+
+### R3 — Keep articles and "that"
+Write complete noun phrases. Keep \`a\`, \`an\`, \`the\`, and \`that\`. Do not drop them for brevity.
+
+### R4 — No semicolon glue
+Do not join two ideas with a semicolon. Use two sentences.
+
+## Sentences
+
+### R5 — Procedural length
+In procedures, aim for about **20 words or fewer** per sentence. Give **one instruction** per sentence.
+
+### R6 — Descriptive length
+In descriptions, aim for about **25 words or fewer** per sentence. Keep **one topic** per paragraph.
+
+### R7 — Condition before command
+State the condition first. Then give the command.
+
+Example: \`If the node is down, stop the job.\`
+Not: \`Stop the job if the node is down.\` when the condition is the safety gate.
+
+### R8 — Active voice and simple tense
+Prefer active voice and simple present or simple past. Avoid stacked present-perfect and trailing "-ing" clauses that hide the actor.
+
+## Safety
+
+### R9 — Warning shape
+For destructive actions: state the command or the condition clearly, then state the risk.
+
+Example: \`Do not run this on production. This command deletes all rows in the table.\`
+
+### R10 — Do not drop required limits
+If a version, limit, or condition is required for safety, keep it. Clarity beats compression.
+
+## Software examples
+
+| Weak | Stronger STE shape |
+|------|--------------------|
+| You might want to restart the pod | Restart the pod |
+| Ensure that connectivity has been established | Make sure the connection is up |
+| After having deployed the chart, proceed to verify | Deploy the chart. Then check the release status |
+
+## Dictionary
+
+Miru does **not** ship the ASD approved-word list. For strict vocabulary compliance, use the official dictionary from asd-ste100.org. Domain technical nouns (\`Kubernetes\`, \`webhook\`, \`IAM\`) stay as product names (untouchable).
+`;
+
+export const STE_CHECKLIST_MD = `# STE extended checklist (Miru)
+
+Use this for **check mode** / audits after a rewrite. Unofficial. Not ASD certification.
+
+## Structure
+
+- [ ] Procedural sentences ≈ ≤20 words; one instruction each
+- [ ] Descriptive sentences ≈ ≤25 words; one topic per paragraph
+- [ ] Condition appears before the command when safety depends on it
+- [ ] No semicolons used as sentence glue
+- [ ] Articles and \`that\` kept (not telegraph)
+
+## Wording
+
+- [ ] One term per concept across the document
+- [ ] Instruction modals are can / will / must (not should / might / could)
+- [ ] Active voice; simple tenses
+- [ ] No marketing filler ("robust", "seamless", "it is worth noting")
+
+## Safety and precision
+
+- [ ] Destructive steps warn with command/condition first, then risk
+- [ ] Required versions, limits, and conditions still present
+- [ ] Code, paths, CLI, quoted errors unchanged
+
+## Scope
+
+- [ ] Not applied to marketing / brand copy
+- [ ] Strict mode users pointed at https://www.asd-ste100.org for the official dictionary
+- [ ] Disclaimer remembered: Miru STE is unofficial / not certified
+
+## Delivery
+
+- [ ] Self-check in the main skill completed before send
+`;
+
+/** Files written under the skill directory beside `SKILL.md`. */
+export const STE_REFERENCE_FILES: SteReferenceFile[] = [
+  { relativePath: "references/rules.md", content: STE_RULES_MD },
+  { relativePath: "references/checklist.md", content: STE_CHECKLIST_MD },
+];

package/src/mcp/auth-tool.ts

@@ -0,0 +1,161 @@
+import * as z from "zod";
+import {
+  checkDeviceAuthorizationOnce,
+  type DeviceAuthConfig,
+  type DeviceAuthorizationStart,
+  openBrowserForDeviceLogin,
+  resolveDeviceAuthConfig,
+  startDeviceAuthorization,
+} from "../auth/device.ts";
+import { isCredentialsError } from "../auth/errors.ts";
+import { saveStoredCredentials, setStoredCredentialsEnvToken } from "../credentials.ts";
+import { toolText } from "./index-cache.ts";
+import type { MiruMcpServer } from "./runtime.ts";
+
+type ToolResult = ReturnType<typeof toolText>;
+
+const CHECK_HINT =
+  'Once the user approves, call `auth` again with action "check" to finish signing in.';
+
+/** Appended to credentials failures so an agent knows Miru's own recovery step. */
+const RECOVERY_HINT =
+  'Miru is not signed in. Call the `auth` tool with action "start" — it opens the Takara ' +
+  'device-login page in the browser — then action "check" once the user approves.';
+
+const AUTH_TOOL_DESCRIPTION =
+  "Sign in with Takara credentials via device-code login — no terminal required. " +
+  "Only call this in direct response to a tool error mentioning missing/expired " +
+  "credentials — never speculatively, since it starts a real sign-in prompt for the " +
+  'user. Call with no arguments (or action "start") to begin: it opens the device-login ' +
+  `page in the user's browser and returns that URL plus a short code. ${CHECK_HINT}`;
+
+/** Browser opener seam; the real one spawns a detached `open`/`xdg-open`/`start`. */
+export type BrowserOpener = (url: string) => boolean;
+
+/** Opening is on unless MIRU_OPEN_BROWSER is set to something other than "1" (matches `miru setup`). */
+function openIfAllowed(open: BrowserOpener, url: string): boolean {
+  const raw = process.env.MIRU_OPEN_BROWSER;
+  if (raw !== undefined && raw !== "1") {
+    return false;
+  }
+  return open(url);
+}
+
+function approvalText(link: string, userCode: string, opened: boolean): string {
+  const lead = opened ? `A browser tab is open at ${link}` : `Ask the user to open ${link}`;
+  return `${lead}. Code: ${userCode}. ${CHECK_HINT}`;
+}
+
+/** Tool-failure text for every Miru tool, with the sign-in step added when relevant. */
+export function toolErrorText(err: unknown): ToolResult {
+  const message = err instanceof Error ? err.message : String(err);
+  return toolText(isCredentialsError(err) ? `${message}\n\n${RECOVERY_HINT}` : message);
+}
+
+type PendingDeviceAuth = {
+  start: DeviceAuthorizationStart;
+  config: DeviceAuthConfig;
+  startedAtMs: number;
+};
+
+function isExpired(entry: PendingDeviceAuth): boolean {
+  return Date.now() >= entry.startedAtMs + entry.start.expiresIn * 1000;
+}
+
+/**
+ * Per-registration auth-tool state, scoped to one `registerAuthTool` call rather than
+ * the module — a process could in principle host more than one MiruMcpServer (tests
+ * already do), and a module-level singleton would let their device logins collide.
+ */
+class AuthToolState {
+  private pending: PendingDeviceAuth | null = null;
+
+  constructor(private readonly openBrowser: BrowserOpener) {}
+
+  async start(): Promise<ToolResult> {
+    let pending = this.pending;
+    if (!pending || isExpired(pending)) {
+      const config = resolveDeviceAuthConfig();
+      const start = await startDeviceAuthorization({ config });
+      pending = { start, config, startedAtMs: Date.now() };
+      this.pending = pending;
+    }
+
+    const { verificationUriComplete, verificationUri, userCode } = pending.start;
+    const link = verificationUriComplete ?? verificationUri;
+    // Reopening on a repeat call is deliberate: the user may have closed the first tab.
+    return toolText(approvalText(link, userCode, openIfAllowed(this.openBrowser, link)));
+  }
+
+  async check(): Promise<ToolResult> {
+    if (!this.pending) {
+      return toolText('No device login is pending. Call `auth` with action "start" first.');
+    }
+
+    const { start, config } = this.pending;
+    // Errors (network failure, unrecognized OAuth error code) intentionally leave
+    // `pending` intact — a transient failure shouldn't force the user to restart
+    // the whole login, just retry the check.
+    const result = await checkDeviceAuthorizationOnce(start, { config });
+
+    switch (result.status) {
+      case "success": {
+        this.pending = null;
+        const { tokens } = result;
+        await saveStoredCredentials({
+          kind: "device_code",
+          accessToken: tokens.accessToken,
+          refreshToken: tokens.refreshToken,
+          expiresAt: tokens.expiresAt,
+          tokenType: tokens.tokenType,
+          scope: tokens.scope,
+        });
+        setStoredCredentialsEnvToken(tokens.accessToken);
+        return toolText("Signed in successfully. Miru tools are now ready to use.");
+      }
+      case "pending":
+        return toolText(
+          'Still waiting for approval. Ask the user to confirm they clicked and approved, then call `auth` again with action "check".',
+        );
+      case "slow_down":
+        return toolText(
+          'Checking too soon — wait a bit before calling `auth` again with action "check".',
+        );
+      case "denied":
+        this.pending = null;
+        return toolText('Sign-in was denied. Call `auth` with action "start" to try again.');
+      case "expired":
+        this.pending = null;
+        return toolText(
+          'The device code expired before it was approved. Call `auth` with action "start" to try again.',
+        );
+    }
+  }
+}
+
+export function registerAuthTool(
+  server: MiruMcpServer,
+  options?: { openBrowser?: BrowserOpener },
+): void {
+  const state = new AuthToolState(options?.openBrowser ?? openBrowserForDeviceLogin);
+
+  server.registerTool(
+    "auth",
+    {
+      description: AUTH_TOOL_DESCRIPTION,
+      inputSchema: {
+        action: z
+          .enum(["start", "check"])
+          .optional()
+          .describe('"start" begins a device-code login (default); "check" completes it.'),
+      },
+    },
+    async ({ action }) => {
+      try {
+        return action === "check" ? await state.check() : await state.start();
+      } catch (err) {
+        return toolText(err instanceof Error ? err.message : String(err));
+      }
+    },
+  );
+}

package/src/mcp/index-cache.ts

@@ -399,7 +399,8 @@ export async function getIndexForRepo(
     return await cache.get(repo, ref);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to index ${repo}: ${message}`);
+    // Keep `cause` so the tool boundary can still recognize a credentials failure.
+    throw new Error(`Failed to index ${repo}: ${message}`, { cause: err });
   }
 }
 

package/src/mcp/server.ts

@@ -34,6 +34,7 @@ import {
   MAX_MCP_TOP_K,
   resolveChunk,
 } from "../utils.ts";
+import { registerAuthTool, toolErrorText } from "./auth-tool.ts";
 import {
   formatExpandResultsText,
   formatLiteralLocateText,
@@ -88,6 +89,8 @@ export function createMcpServer(
     },
   );
 
+  registerAuthTool(server);
+
   server.registerTool(
     "search",
     {
@@ -158,7 +161,7 @@ export function createMcpServer(
         const body = formatResultsText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -244,7 +247,7 @@ export function createMcpServer(
         const body = formatLiteralLocateText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -305,7 +308,7 @@ export function createMcpServer(
           ),
         );
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -357,7 +360,7 @@ export function createMcpServer(
           ),
         );
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );

package/src/prompt.ts

@@ -73,7 +73,10 @@ export async function promptText(message: string, defaultValue = ""): Promise<st
   }
 }
 
-export async function promptHidden(message: string): Promise<string> {
+export async function promptHidden(
+  message: string,
+  stream: NodeJS.WriteStream = output,
+): Promise<string> {
   if (!input.isTTY) {
     throw new Error(
       "Cannot prompt for API key: stdin is not a TTY. Run `miru setup --key YOUR_KEY` or set TAKARA_API_KEY.",
@@ -81,7 +84,7 @@ export async function promptHidden(message: string): Promise<string> {
   }
 
   return new Promise((resolve, reject) => {
-    output.write(message);
+    stream.write(message);
     input.setRawMode?.(true);
     input.resume();
     input.setEncoding("utf8");
@@ -95,20 +98,20 @@ export async function promptHidden(message: string): Promise<string> {
 
         if (result.cancel) {
           cleanup();
-          output.write("\n");
+          stream.write("\n");
           reject(new Error("Setup cancelled."));
           process.exit(130);
         }
 
         if (result.submit) {
           cleanup();
-          output.write("\n");
+          stream.write("\n");
           resolve(state.value.trim());
           return;
         }
 
         if (result.echo) {
-          output.write(result.echo);
+          stream.write(result.echo);
         }
       }
     };