muonroi-cli 1.2.0

package/src/headless/output.ts

@@ -0,0 +1,312 @@
+import type {
+  ProcessMessageObserver,
+  ProcessMessageStepFinish,
+  ProcessMessageStepStart,
+} from "../orchestrator/orchestrator";
+import type { StreamChunk, ToolCall, ToolResult } from "../types";
+
+export type HeadlessOutputFormat = "text" | "json";
+
+export interface HeadlessWrites {
+  stdout?: string;
+  stderr?: string;
+}
+
+/** Semantic JSONL events for headless `--format json` (OpenCode-style). */
+export type HeadlessJsonEvent =
+  | {
+      type: "step_start";
+      sessionID?: string;
+      stepNumber: number;
+      timestamp: number;
+    }
+  | {
+      type: "text";
+      sessionID?: string;
+      stepNumber: number;
+      text: string;
+      timestamp: number;
+    }
+  | {
+      type: "tool_use";
+      sessionID?: string;
+      stepNumber: number;
+      timestamp: number;
+      toolCall: ToolCall;
+      toolResult: ToolResult;
+      /** Present when `onToolStart` / `onToolFinish` observer hooks ran for this tool call. */
+      timing?: {
+        startedAt?: number;
+        finishedAt?: number;
+        durationMs?: number;
+      };
+    }
+  | {
+      type: "step_finish";
+      sessionID?: string;
+      stepNumber: number;
+      timestamp: number;
+      finishReason: string;
+      usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        costUsdTicks?: number;
+      };
+    }
+  | {
+      type: "error";
+      sessionID?: string;
+      message: string;
+      timestamp: number;
+    };
+
+export function isHeadlessOutputFormat(value: string): value is HeadlessOutputFormat {
+  return value === "text" || value === "json";
+}
+
+export function renderHeadlessPrelude(format: HeadlessOutputFormat, sessionId?: string): HeadlessWrites {
+  if (format === "json") {
+    return {};
+  }
+
+  return {
+    stdout: "\x1b[36m⏳ Processing...\x1b[0m\n",
+    stderr: sessionId ? `\x1b[2mSession: ${sessionId}\x1b[0m\n` : undefined,
+  };
+}
+
+/**
+ * Headless text output only. JSON streaming uses {@link createHeadlessJsonlEmitter} + `Agent.processMessage` observer.
+ */
+export function renderHeadlessChunk(chunk: StreamChunk): HeadlessWrites {
+  switch (chunk.type) {
+    case "content":
+      return chunk.content ? { stdout: chunk.content } : {};
+
+    case "tool_calls":
+      return chunk.toolCalls?.length
+        ? {
+            stderr: chunk.toolCalls.map((tc) => `\x1b[33m▸ ${formatToolCallLabel(tc)}\x1b[0m\n`).join(""),
+          }
+        : {};
+
+    case "tool_result": {
+      if (!chunk.toolResult) {
+        return {};
+      }
+
+      const icon = chunk.toolResult.success ? "▸" : "✗";
+      const color = chunk.toolResult.success ? "\x1b[32m" : "\x1b[31m";
+      const label = chunk.toolCall ? formatToolCallLabel(chunk.toolCall) : "tool";
+      const mediaLines =
+        chunk.toolResult.media?.map((asset) => {
+          const suffix = asset.url ? ` (${asset.url})` : "";
+          return `  ${asset.path}${suffix}`;
+        }) ?? [];
+      const stderr = [`${color}${icon} ${label}\x1b[0m`, ...mediaLines].join("\n");
+      return { stderr: `${stderr}\n` };
+    }
+
+    case "error":
+      return chunk.content ? { stderr: `\x1b[31m${chunk.content}\x1b[0m\n` } : {};
+
+    case "done":
+      return { stdout: "\n" };
+
+    case "reasoning":
+      return {};
+
+    default:
+      return {};
+  }
+}
+
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function formatToolCallLabel(tc: ToolCall): string {
+  const name = tc.function.name;
+  try {
+    const args = JSON.parse(tc.function.arguments || "{}") as Record<string, unknown>;
+    if (name === "bash" && typeof args.command === "string") {
+      const cmd = args.command.replace(/\n/g, " ").trim();
+      return `bash: ${truncate(cmd, 80)}`;
+    }
+    if (name === "task" && typeof args.agent === "string") {
+      const desc = typeof args.description === "string" ? ` — ${args.description}` : "";
+      return `task: ${args.agent}${truncate(desc, 60)}`;
+    }
+    if (name === "read_file" && typeof args.path === "string") {
+      return `read: ${args.path}`;
+    }
+    if ((name === "write_file" || name === "edit_file") && typeof args.path === "string") {
+      return `${name === "write_file" ? "write" : "edit"}: ${args.path}`;
+    }
+  } catch {}
+  return name;
+}
+
+function jsonLine(event: HeadlessJsonEvent): string {
+  return `${JSON.stringify(event)}\n`;
+}
+
+/**
+ * Buffers assistant `content` per step and emits JSONL: step_start, text, tool_use, step_finish, error.
+ * Pair with `agent.processMessage(prompt, emitter.observer)` in headless JSON mode only.
+ *
+ * @param sessionId Agent session id (from {@link Agent.getSessionId}) — included on each JSONL line when set.
+ */
+export function createHeadlessJsonlEmitter(sessionId?: string): {
+  observer: ProcessMessageObserver;
+  consumeChunk(chunk: StreamChunk): HeadlessWrites;
+  /** Call after the `processMessage` iterator completes to flush any trailing observer output. */
+  flush(): HeadlessWrites;
+} {
+  let pending = "";
+  let currentStep = 0;
+  let textBuffer = "";
+  /** Tool call id → timing from {@link ProcessMessageObserver.onToolStart} / {@link ProcessMessageObserver.onToolFinish}. */
+  const toolTiming = new Map<string, { startedAt?: number; finishedAt?: number }>();
+
+  function withSession<T extends Record<string, unknown>>(event: T): T & { sessionID?: string } {
+    return sessionId ? { ...event, sessionID: sessionId } : event;
+  }
+
+  const observer: ProcessMessageObserver = {
+    onStepStart(info: ProcessMessageStepStart) {
+      currentStep = info.stepNumber;
+      textBuffer = "";
+      pending += jsonLine(
+        withSession({
+          type: "step_start",
+          stepNumber: info.stepNumber,
+          timestamp: info.timestamp,
+        }) as HeadlessJsonEvent,
+      );
+    },
+    onStepFinish(info: ProcessMessageStepFinish) {
+      if (textBuffer.length > 0) {
+        pending += jsonLine(
+          withSession({
+            type: "text",
+            stepNumber: info.stepNumber,
+            text: textBuffer,
+            timestamp: Date.now(),
+          }) as HeadlessJsonEvent,
+        );
+        textBuffer = "";
+      }
+      pending += jsonLine(
+        withSession({
+          type: "step_finish",
+          stepNumber: info.stepNumber,
+          timestamp: info.timestamp,
+          finishReason: info.finishReason,
+          usage: info.usage,
+        }) as HeadlessJsonEvent,
+      );
+    },
+    onToolStart(info) {
+      const prev = toolTiming.get(info.toolCall.id) ?? {};
+      toolTiming.set(info.toolCall.id, { ...prev, startedAt: info.timestamp });
+    },
+    onToolFinish(info) {
+      const prev = toolTiming.get(info.toolCall.id) ?? {};
+      toolTiming.set(info.toolCall.id, { ...prev, finishedAt: info.timestamp });
+    },
+  };
+
+  function drainPending(): string {
+    const out = pending;
+    pending = "";
+    return out;
+  }
+
+  function flush(): HeadlessWrites {
+    const stdout = drainPending();
+    return stdout ? { stdout } : {};
+  }
+
+  function consumeChunk(chunk: StreamChunk): HeadlessWrites {
+    let stdout = drainPending();
+
+    switch (chunk.type) {
+      case "content":
+        textBuffer += chunk.content ?? "";
+        break;
+
+      case "tool_calls": {
+        if (textBuffer.length > 0) {
+          stdout += jsonLine(
+            withSession({
+              type: "text",
+              stepNumber: currentStep,
+              text: textBuffer,
+              timestamp: Date.now(),
+            }) as HeadlessJsonEvent,
+          );
+          textBuffer = "";
+        }
+        break;
+      }
+
+      case "tool_result": {
+        if (chunk.toolCall && chunk.toolResult) {
+          const id = chunk.toolCall.id;
+          const timingEntry = toolTiming.get(id);
+          toolTiming.delete(id);
+
+          let timing: { startedAt?: number; finishedAt?: number; durationMs?: number } | undefined;
+          if (timingEntry) {
+            const startedAt = timingEntry.startedAt;
+            const finishedAt = timingEntry.finishedAt;
+            if (startedAt !== undefined || finishedAt !== undefined) {
+              timing = {};
+              if (startedAt !== undefined) timing.startedAt = startedAt;
+              if (finishedAt !== undefined) timing.finishedAt = finishedAt;
+              if (startedAt !== undefined && finishedAt !== undefined) {
+                timing.durationMs = finishedAt - startedAt;
+              }
+            }
+          }
+
+          const eventTime = timingEntry?.finishedAt ?? timingEntry?.startedAt ?? Date.now();
+          stdout += jsonLine(
+            withSession({
+              type: "tool_use",
+              stepNumber: currentStep,
+              timestamp: eventTime,
+              toolCall: chunk.toolCall,
+              toolResult: chunk.toolResult,
+              ...(timing ? { timing } : {}),
+            }) as HeadlessJsonEvent,
+          );
+        }
+        break;
+      }
+
+      case "error":
+        stdout += jsonLine(
+          withSession({
+            type: "error",
+            message: chunk.content ?? "",
+            timestamp: Date.now(),
+          }) as HeadlessJsonEvent,
+        );
+        break;
+
+      case "reasoning":
+      case "done":
+        break;
+
+      default:
+        break;
+    }
+
+    return stdout ? { stdout } : {};
+  }
+
+  return { observer, consumeChunk, flush };
+}

package/src/hooks/config.ts

@@ -0,0 +1,41 @@
+import { loadUserSettings } from "../utils/settings.js";
+import type { HookCommand, HookEvent, HookMatcher, HooksConfig } from "./types.js";
+
+/**
+ * Load hooks config from user settings (~/.muonroi-cli/user-settings.json) only.
+ *
+ * Project-level .muonroi-cli/settings.json hooks are intentionally excluded because
+ * that file is repo-committed — a malicious repository could execute arbitrary
+ * unsandboxed commands on a developer's machine via hook definitions.
+ * Hooks run on the host (outside any sandbox) so they must be user-configured.
+ */
+export function loadHooksConfig(): HooksConfig {
+  return loadUserSettings().hooks ?? {};
+}
+
+/**
+ * Get hooks that match a given event and optional match value.
+ *
+ * For events that have a matcher field (e.g. PreToolUse matches on tool_name),
+ * only matchers whose `matcher` string matches `matchValue` are included,
+ * plus matchers with no `matcher` (which match everything).
+ */
+export function getMatchingHooks(config: HooksConfig, event: HookEvent, matchValue?: string): HookCommand[] {
+  const matchers = config[event];
+  if (!matchers || matchers.length === 0) return [];
+
+  const matched: HookCommand[] = [];
+  for (const entry of matchers) {
+    if (matchesPattern(entry, matchValue)) {
+      matched.push(...entry.hooks);
+    }
+  }
+
+  return matched;
+}
+
+function matchesPattern(entry: HookMatcher, matchValue?: string): boolean {
+  if (!entry.matcher) return true;
+  if (!matchValue) return false;
+  return matchValue === entry.matcher;
+}

package/src/hooks/index.ts

@@ -0,0 +1,250 @@
+/**
+ * Hook dispatcher — routes PreToolUse / PostToolUse events through the
+ * Experience Engine HTTP client at localhost:8082.
+ *
+ * Plan 00.06: src/hooks/executor.ts (shell-spawn approach) has been deleted.
+ * This module is the new dispatcher. It preserves the original public function
+ * signatures so call sites in the orchestrator do not change.
+ *
+ * Shell-spawn was:
+ *   spawn("sh", ["-c", hook.command], ...)  — broken on Windows without WSL.
+ * HTTP client is:
+ *   POST http://localhost:8082/api/intercept  — cross-platform, safe, auditable.
+ *
+ * Architecture: EE is optional. If EE is not running, all intercepts fall back
+ * to { decision: "allow" } so the TUI is never blocked by a missing EE process.
+ */
+
+// Re-export type-only items that callers may import from this module
+export { getMatchingHooks, loadHooksConfig } from "./config.js";
+export type {
+  AggregatedHookResult,
+  BaseHookInput,
+  CommandHook,
+  HookCommand,
+  HookEvent,
+  HookInput,
+  HookMatcher,
+  HookOutput,
+  HookResult,
+  HooksConfig,
+  PostToolUseFailureHookInput,
+  PostToolUseHookInput,
+  PreToolUseHookInput,
+} from "./types.js";
+export { getMatchQuery, HOOK_EVENTS, isHookEvent } from "./types.js";
+
+import { interceptWithDefaults } from "../ee/intercept.js";
+import { getTenantId } from "../ee/tenant.js";
+import { type JudgeContext } from "../ee/judge.js";
+import { posttool } from "../ee/posttool.js";
+import { reconcilePromptStale } from "../ee/prompt-stale.js";
+import { buildScope } from "../ee/scope.js";
+import type { InterceptResponse, Scope } from "../ee/types.js";
+import type {
+  AggregatedHookResult,
+  HookInput,
+  PostToolUseFailureHookInput,
+  PostToolUseHookInput,
+  PreToolUseHookInput,
+} from "./types.js";
+
+// Cached scope for posttool calls (computed once at first use)
+let _cachedScope: Scope | null = null;
+
+// Latch: stores the last PreToolUse warning response so PostToolUse can build judgeCtx.
+// Follows the _cachedScope module-level variable pattern.
+let _lastWarningResponse: InterceptResponse | null = null;
+
+/** Reset hook module state — for test teardown only. */
+export function resetHookState(): void {
+  _lastWarningResponse = null;
+  _cachedScope = null;
+}
+
+function emptyResult(): AggregatedHookResult {
+  return {
+    blocked: false,
+    blockingErrors: [],
+    preventContinuation: false,
+    additionalContexts: [],
+    results: [],
+  };
+}
+
+/**
+ * Dispatch a hook event to the EE HTTP client.
+ *
+ * - PreToolUse:  blocking intercept call → may return decision:block
+ * - PostToolUse: fire-and-forget posttool call
+ * - All other events: allow by default (Phase 1 EE-02+ extends this)
+ *
+ * Swallows all errors so hooks never crash the orchestrator.
+ */
+export async function executeEventHooks(
+  input: HookInput,
+  cwd: string,
+  _signal?: AbortSignal,
+): Promise<AggregatedHookResult> {
+  try {
+    if (input.hook_event_name === "PreToolUse") {
+      const r = await interceptWithDefaults({
+        toolName: input.tool_name,
+        toolInput: input.tool_input,
+        cwd,
+      });
+      // Thread the warning response to PostToolUse via module-level latch
+      _lastWarningResponse = r;
+      if (r.decision === "block") {
+        return {
+          blocked: true,
+          blockingErrors: [{ command: "ee:intercept", stderr: r.reason ?? "ee-blocked" }],
+          preventContinuation: true,
+          stopReason: r.reason ?? "ee-blocked",
+          additionalContexts: r.suggestions ?? [],
+          decision: "block",
+          results: [],
+        };
+      }
+      return {
+        blocked: false,
+        blockingErrors: [],
+        preventContinuation: false,
+        additionalContexts: r.suggestions ?? [],
+        decision: "approve",
+        results: [],
+      };
+    }
+
+    if (input.hook_event_name === "PostToolUse") {
+      if (!_cachedScope) _cachedScope = await buildScope({ cwd });
+      const judgeCtx: JudgeContext = {
+        warningResponse: _lastWarningResponse,
+        toolName: input.tool_name,
+        outcome: { success: true },
+        cwdMatchedAtPretool: _lastWarningResponse !== null,
+        diffPresent: false,
+        tenantId: getTenantId(),
+      };
+      _lastWarningResponse = null; // reset after use — prevents cross-turn contamination
+      await posttool(
+        {
+          toolName: input.tool_name,
+          toolInput: input.tool_input,
+          outcome: {
+            // PostToolUse always means success — failure goes to PostToolUseFailure
+            success: true,
+          },
+          cwd,
+          tenantId: getTenantId(),
+          scope: _cachedScope,
+        },
+        judgeCtx,
+      );
+      // STALE-02/STALE-03: fire-and-forget per-turn prompt-stale reconciliation
+      reconcilePromptStale(cwd); // void — does not block (B-4)
+      return emptyResult();
+    }
+
+    if (input.hook_event_name === "PostToolUseFailure") {
+      const failInput = input as PostToolUseFailureHookInput;
+      if (!_cachedScope) _cachedScope = await buildScope({ cwd });
+      const judgeCtx: JudgeContext = {
+        warningResponse: _lastWarningResponse,
+        toolName: failInput.tool_name,
+        outcome: { success: false, error: failInput.error },
+        cwdMatchedAtPretool: _lastWarningResponse !== null,
+        diffPresent: false,
+        tenantId: getTenantId(),
+      };
+      _lastWarningResponse = null; // reset after use — prevents cross-turn contamination
+      await posttool(
+        {
+          toolName: failInput.tool_name,
+          toolInput: failInput.tool_input,
+          outcome: {
+            success: false,
+            error: failInput.error,
+          },
+          cwd,
+          tenantId: getTenantId(),
+          scope: _cachedScope,
+        },
+        judgeCtx,
+      );
+      // STALE-02/STALE-03: fire-and-forget per-turn prompt-stale reconciliation
+      reconcilePromptStale(cwd); // void — does not block (B-4)
+      return emptyResult();
+    }
+
+    // All other event names: allow by default (Phase 1 EE-02+ extends coverage)
+    return emptyResult();
+  } catch {
+    // EE errors must never crash the orchestrator
+    return emptyResult();
+  }
+}
+
+/**
+ * Fire PreToolUse hooks. Returns the aggregated result which may block execution.
+ */
+export async function executePreToolHooks(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+  sessionId?: string,
+  signal?: AbortSignal,
+): Promise<AggregatedHookResult> {
+  const input: PreToolUseHookInput = {
+    hook_event_name: "PreToolUse",
+    tool_name: toolName,
+    tool_input: toolInput,
+    session_id: sessionId,
+    cwd,
+  };
+  return executeEventHooks(input, cwd, signal);
+}
+
+/**
+ * Fire PostToolUse hooks after a successful tool execution.
+ */
+export async function executePostToolHooks(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  toolOutput: Record<string, unknown>,
+  cwd: string,
+  sessionId?: string,
+  signal?: AbortSignal,
+): Promise<AggregatedHookResult> {
+  const input: PostToolUseHookInput = {
+    hook_event_name: "PostToolUse",
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_output: toolOutput,
+    session_id: sessionId,
+    cwd,
+  };
+  return executeEventHooks(input, cwd, signal);
+}
+
+/**
+ * Fire PostToolUseFailure hooks after a tool execution fails.
+ */
+export async function executePostToolFailureHooks(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  error: string,
+  cwd: string,
+  sessionId?: string,
+  signal?: AbortSignal,
+): Promise<AggregatedHookResult> {
+  const input: PostToolUseFailureHookInput = {
+    hook_event_name: "PostToolUseFailure",
+    tool_name: toolName,
+    tool_input: toolInput,
+    error,
+    session_id: sessionId,
+    cwd,
+  };
+  return executeEventHooks(input, cwd, signal);
+}