muonroi-cli 1.2.0

package/src/flow/warning-persist.ts

@@ -0,0 +1,84 @@
+/**
+ * Persists EE hook warnings into the active run's state.md.
+ *
+ * Fire-and-forget: errors are caught and logged, never thrown.
+ * Cap: keeps the last MAX_STORED_WARNINGS unique warnings (deduplicated by
+ * principle_uuid) to prevent unbounded context growth in state.md.
+ */
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { renderInterceptWarning } from "../ee/render.js";
+import type { InterceptMatch } from "../ee/types.js";
+import { getSection } from "./parser.js";
+import { getActiveRunId, loadRun, updateRunFile } from "./run-manager.js";
+import { FLOW_DIR_NAME } from "./scaffold.js";
+
+const MAX_STORED_WARNINGS = 20;
+
+/** Parse stored warning lines back to principle_uuid for dedup. */
+function _extractUuids(snapshot: string): string[] {
+  const uuids: string[] = [];
+  for (const line of snapshot.split("\n")) {
+    // Warnings rendered with renderInterceptWarning contain principle_uuid implicitly
+    // via the message. We tag each entry with UUID in the persisted format below.
+    const m = line.match(/\[uuid:([^\]]+)\]/);
+    if (m) uuids.push(m[1]);
+  }
+  return uuids;
+}
+
+function tagWarning(match: InterceptMatch, text: string): string {
+  return `[uuid:${match.principle_uuid}] ${text}`;
+}
+
+/** Keep only the last MAX_STORED_WARNINGS unique-uuid entries. */
+function trimSnapshot(snapshot: string, _newUuid: string): string {
+  // Split into per-warning blocks (each starts with a timestamp tag)
+  const entries = snapshot.split(/(?=\[\d{4}-\d{2}-\d{2})/);
+  const seen = new Set<string>();
+  const kept: string[] = [];
+
+  for (const entry of entries.reverse()) {
+    // newest first
+    const m = entry.match(/\[uuid:([^\]]+)\]/);
+    const uuid = m ? m[1] : entry.slice(0, 40); // fallback key
+    if (!seen.has(uuid) && seen.size < MAX_STORED_WARNINGS - 1) {
+      seen.add(uuid);
+      kept.unshift(entry);
+    }
+  }
+
+  return kept.filter(Boolean).join("").trim();
+}
+
+export async function persistWarning(cwd: string, match: InterceptMatch): Promise<void> {
+  try {
+    const flowDir = path.join(cwd, FLOW_DIR_NAME);
+    try {
+      await fs.access(flowDir);
+    } catch {
+      return;
+    }
+
+    const runId = await getActiveRunId(flowDir);
+    if (!runId) return;
+
+    const runState = await loadRun(flowDir, runId);
+    if (!runState) return;
+
+    const warningText = tagWarning(match, renderInterceptWarning(match));
+    const timestampedWarning = `[${new Date().toISOString()}] ${warningText}`;
+
+    const existing = getSection(runState.state, "Experience Snapshot") ?? "";
+
+    // Deduplicate and cap
+    const trimmed = trimSnapshot(existing, match.principle_uuid);
+    const updated = trimmed ? `${trimmed}\n${timestampedWarning}` : timestampedWarning;
+
+    runState.state.sections.set("Experience Snapshot", updated);
+    await updateRunFile(flowDir, runId, "state.md", runState.state);
+  } catch (err) {
+    console.warn("[warning-persist] Failed to persist warning:", err);
+  }
+}

package/src/gsd/__tests__/types.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { detectGsdPhase, GSD_PHASES, isGsdPhase } from "../types";
+
+describe("GSD types", () => {
+  it("GSD_PHASES contains all expected phases", () => {
+    expect(GSD_PHASES).toContain("discuss");
+    expect(GSD_PHASES).toContain("plan");
+    expect(GSD_PHASES).toContain("execute");
+    expect(GSD_PHASES).toContain("verify");
+    expect(GSD_PHASES).toContain("review");
+    expect(GSD_PHASES.length).toBe(5);
+  });
+
+  it("isGsdPhase returns true for valid phases", () => {
+    expect(isGsdPhase("discuss")).toBe(true);
+    expect(isGsdPhase("plan")).toBe(true);
+    expect(isGsdPhase("execute")).toBe(true);
+    expect(isGsdPhase("verify")).toBe(true);
+    expect(isGsdPhase("review")).toBe(true);
+  });
+
+  it("isGsdPhase returns false for invalid strings", () => {
+    expect(isGsdPhase("unknown")).toBe(false);
+    expect(isGsdPhase("")).toBe(false);
+    expect(isGsdPhase("PLAN")).toBe(false);
+  });
+
+  it("detectGsdPhase detects plan from keywords", () => {
+    expect(detectGsdPhase("plan the implementation")).toBe("plan");
+    expect(detectGsdPhase("let's plan this feature")).toBe("plan");
+  });
+
+  it("detectGsdPhase detects execute from keywords", () => {
+    expect(detectGsdPhase("execute the plan now")).toBe("execute");
+    expect(detectGsdPhase("implement the feature")).toBe("execute");
+    expect(detectGsdPhase("build the component")).toBe("execute");
+  });
+
+  it("detectGsdPhase detects verify from keywords", () => {
+    expect(detectGsdPhase("verify the results")).toBe("verify");
+    expect(detectGsdPhase("validate that it works")).toBe("verify");
+    expect(detectGsdPhase("test the implementation")).toBe("verify");
+  });
+
+  it("detectGsdPhase detects review from keywords", () => {
+    expect(detectGsdPhase("review the code")).toBe("review");
+    expect(detectGsdPhase("audit the changes")).toBe("review");
+  });
+
+  it("detectGsdPhase detects discuss from keywords", () => {
+    expect(detectGsdPhase("discuss the approach")).toBe("discuss");
+    expect(detectGsdPhase("let's brainstorm ideas")).toBe("discuss");
+  });
+
+  it("detectGsdPhase returns null for no match", () => {
+    expect(detectGsdPhase("hello world")).toBeNull();
+    expect(detectGsdPhase("")).toBeNull();
+  });
+});
+
+describe("detectGsdPhase — ambiguity resolution", () => {
+  it("'implement the plan' returns execute (action verb wins)", () => {
+    expect(detectGsdPhase("implement the plan")).toBe("execute");
+  });
+
+  it("'plan the implementation' returns plan (plan appears first)", () => {
+    expect(detectGsdPhase("plan the implementation")).toBe("plan");
+  });
+
+  it("'discuss the plan before executing' returns discuss (discuss first)", () => {
+    expect(detectGsdPhase("discuss the plan before executing")).toBe("discuss");
+  });
+
+  it("'build and verify the feature' returns execute (build first)", () => {
+    expect(detectGsdPhase("build and verify the feature")).toBe("execute");
+  });
+});

package/src/gsd/index.ts

@@ -0,0 +1 @@
+export { detectGsdPhase, GSD_PHASES, type GsdPhase, isGsdPhase } from "./types.js";

package/src/gsd/types.ts

@@ -0,0 +1,47 @@
+export const GSD_PHASES = ["discuss", "plan", "execute", "verify", "review"] as const;
+
+export type GsdPhase = (typeof GSD_PHASES)[number];
+
+export function isGsdPhase(value: string): value is GsdPhase {
+  return (GSD_PHASES as readonly string[]).includes(value);
+}
+
+const PHASE_KEYWORDS: Record<GsdPhase, string[]> = {
+  discuss: ["discuss", "brainstorm", "explore", "think about", "consider"],
+  plan: ["plan", "design", "architect", "outline", "roadmap"],
+  execute: ["execute", "implement", "build", "create", "write", "code", "develop"],
+  verify: ["verify", "validate", "test", "check", "confirm", "ensure"],
+  review: ["review", "audit", "inspect", "examine", "evaluate"],
+};
+
+const PHASE_PRIORITY: Record<GsdPhase, number> = {
+  execute: 5,
+  verify: 4,
+  discuss: 3,
+  plan: 2,
+  review: 1,
+};
+
+export function detectGsdPhase(text: string): GsdPhase | null {
+  const lower = text.toLowerCase();
+
+  let bestPhase: GsdPhase | null = null;
+  let bestPos = Infinity;
+  let bestPriority = -1;
+
+  for (const [phase, keywords] of Object.entries(PHASE_KEYWORDS) as [GsdPhase, string[]][]) {
+    for (const kw of keywords) {
+      const pos = lower.indexOf(kw);
+      if (pos === -1) continue;
+
+      const priority = PHASE_PRIORITY[phase];
+      if (pos < bestPos || (pos === bestPos && priority > bestPriority)) {
+        bestPhase = phase;
+        bestPos = pos;
+        bestPriority = priority;
+      }
+    }
+  }
+
+  return bestPhase;
+}

package/src/headless/output.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+import type { StreamChunk, ToolCall } from "../types";
+import {
+  createHeadlessJsonlEmitter,
+  isHeadlessOutputFormat,
+  renderHeadlessChunk,
+  renderHeadlessPrelude,
+} from "./output";
+
+function toolCall(name: string): ToolCall {
+  return {
+    id: "tc-1",
+    type: "function",
+    function: {
+      name,
+      arguments: "{}",
+    },
+  };
+}
+
+function expectSessionAndTimestamp(e: { sessionID?: string; timestamp?: number }, sessionId?: string) {
+  if (sessionId !== undefined) {
+    expect(e.sessionID).toBe(sessionId);
+  } else {
+    expect(e.sessionID).toBeUndefined();
+  }
+  expect(typeof e.timestamp).toBe("number");
+}
+
+describe("headless output helpers", () => {
+  it("recognizes supported output formats", () => {
+    expect(isHeadlessOutputFormat("text")).toBe(true);
+    expect(isHeadlessOutputFormat("json")).toBe(true);
+    expect(isHeadlessOutputFormat("xml")).toBe(false);
+  });
+
+  it("renders the text prelude with session metadata", () => {
+    expect(renderHeadlessPrelude("text", "session-123")).toEqual({
+      stdout: "\u001b[36m⏳ Processing...\u001b[0m\n",
+      stderr: "\u001b[2mSession: session-123\u001b[0m\n",
+    });
+  });
+
+  it("suppresses the prelude in json mode", () => {
+    expect(renderHeadlessPrelude("json", "session-123")).toEqual({});
+  });
+
+  it("renders tool calls for text mode", () => {
+    const chunk: StreamChunk = {
+      type: "tool_calls",
+      toolCalls: [toolCall("bash"), toolCall("read_file")],
+    };
+
+    expect(renderHeadlessChunk(chunk)).toEqual({
+      stderr: "\u001b[33m▸ bash\u001b[0m\n\u001b[33m▸ read_file\u001b[0m\n",
+    });
+  });
+
+  it("renders tool results for text mode", () => {
+    const chunk: StreamChunk = {
+      type: "tool_result",
+      toolCall: toolCall("bash"),
+      toolResult: {
+        success: false,
+        output: "failed",
+      },
+    };
+
+    expect(renderHeadlessChunk(chunk)).toEqual({
+      stderr: "\u001b[31m✗ bash\u001b[0m\n",
+    });
+  });
+
+  it("renders generated media paths in text mode tool results", () => {
+    const chunk: StreamChunk = {
+      type: "tool_result",
+      toolCall: toolCall("generate_image"),
+      toolResult: {
+        success: true,
+        output: "Generated 1 image.",
+        media: [{ kind: "image", path: "/tmp/generated.png", url: "https://example.com/generated.png" }],
+      },
+    };
+
+    expect(renderHeadlessChunk(chunk)).toEqual({
+      stderr: "\u001b[32m▸ generate_image\u001b[0m\n  /tmp/generated.png (https://example.com/generated.png)\n",
+    });
+  });
+
+  it("emits semantic JSONL for a single step with text and tool (json emitter)", () => {
+    const sessionId = "jsonl-test-session";
+    const tc = toolCall("bash");
+    const { observer, consumeChunk, flush } = createHeadlessJsonlEmitter(sessionId);
+    let combined = "";
+
+    observer.onStepStart?.({ stepNumber: 1, timestamp: 100 });
+    combined += consumeChunk({ type: "content", content: "hello" }).stdout ?? "";
+    observer.onToolStart?.({ toolCall: tc, timestamp: 110 });
+    combined +=
+      consumeChunk({
+        type: "tool_calls",
+        toolCalls: [tc],
+      }).stdout ?? "";
+    observer.onToolFinish?.({
+      toolCall: tc,
+      toolResult: { success: true, output: "ok" },
+      timestamp: 130,
+    });
+    combined +=
+      consumeChunk({
+        type: "tool_result",
+        toolCall: tc,
+        toolResult: { success: true, output: "ok" },
+      }).stdout ?? "";
+    observer.onStepFinish?.({
+      stepNumber: 1,
+      timestamp: 200,
+      finishReason: "stop",
+      usage: { inputTokens: 1, outputTokens: 2, totalTokens: 3 },
+    });
+    combined += flush().stdout ?? "";
+
+    const events = combined
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l));
+    expect(events.map((e) => e.type)).toEqual(["step_start", "text", "tool_use", "step_finish"]);
+    expectSessionAndTimestamp(events[0], sessionId);
+    expect(events[0]).toMatchObject({ type: "step_start", stepNumber: 1, timestamp: 100 });
+
+    expectSessionAndTimestamp(events[1], sessionId);
+    expect(events[1]).toMatchObject({ type: "text", stepNumber: 1, text: "hello" });
+
+    expectSessionAndTimestamp(events[2], sessionId);
+    expect(events[2]).toMatchObject({
+      type: "tool_use",
+      stepNumber: 1,
+      timestamp: 130,
+      timing: { startedAt: 110, finishedAt: 130, durationMs: 20 },
+    });
+
+    expectSessionAndTimestamp(events[3], sessionId);
+    expect(events[3]).toMatchObject({
+      type: "step_finish",
+      stepNumber: 1,
+      finishReason: "stop",
+      usage: { inputTokens: 1, outputTokens: 2, totalTokens: 3 },
+      timestamp: 200,
+    });
+  });
+
+  it("does not emit empty text events at step_finish when tools already flushed assistant text", () => {
+    const sessionId = "sess-2";
+    const tc = toolCall("bash");
+    const { observer, consumeChunk, flush } = createHeadlessJsonlEmitter(sessionId);
+    let combined = "";
+    observer.onStepStart?.({ stepNumber: 0, timestamp: 1 });
+    combined += consumeChunk({ type: "content", content: "x" }).stdout ?? "";
+    observer.onToolStart?.({ toolCall: tc, timestamp: 5 });
+    combined += consumeChunk({ type: "tool_calls", toolCalls: [tc] }).stdout ?? "";
+    observer.onToolFinish?.({
+      toolCall: tc,
+      toolResult: { success: true, output: "y" },
+      timestamp: 8,
+    });
+    combined +=
+      consumeChunk({
+        type: "tool_result",
+        toolCall: tc,
+        toolResult: { success: true, output: "y" },
+      }).stdout ?? "";
+    observer.onStepFinish?.({
+      stepNumber: 0,
+      timestamp: 2,
+      finishReason: "tool-calls",
+      usage: {},
+    });
+    combined += flush().stdout ?? "";
+    const events = combined
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l));
+    expect(events.filter((e) => e.type === "text").every((e) => e.text.length > 0)).toBe(true);
+    expect(events.map((e) => e.type)).toEqual(["step_start", "text", "tool_use", "step_finish"]);
+    for (const e of events) {
+      expectSessionAndTimestamp(e, sessionId);
+    }
+  });
+
+  it("emits error events from stream chunks", () => {
+    const sessionId = "err-session";
+    const { consumeChunk } = createHeadlessJsonlEmitter(sessionId);
+    const w = consumeChunk({ type: "error", content: "boom" });
+    const parsed = JSON.parse(w.stdout?.trim() ?? "{}");
+    expect(parsed).toMatchObject({
+      type: "error",
+      message: "boom",
+    });
+    expectSessionAndTimestamp(parsed, sessionId);
+  });
+});