@hellcoder/companion 0.116.0 → 0.116.1-preview.20260814041931.d191f06

package/server/magic-ui-settings.ts

@@ -0,0 +1,38 @@
+import { getSettings } from "./settings-manager.js";
+import { isClaudeCliAvailable } from "./claude-cli-runner.js";
+import type { SessionState } from "./session-types.js";
+
+export interface EffectiveMagicUiSettings {
+  /**
+   * Whether MagicUI is effectively on for this session: the per-session
+   * opt-in wins, falling back to the global default. Always false when the
+   * Claude CLI is unavailable — the watcher rides the CLI subscription
+   * login and cannot run without it (never the Anthropic API key).
+   */
+  enabled: boolean;
+  /** Model for the watcher session. Cheap-by-default (Haiku). */
+  model: string;
+}
+
+/**
+ * Resolve effective MagicUI settings for a session.
+ *
+ * Unlike AI validation (where the global setting is a default that sessions
+ * inherit), MagicUI is deliberately availability-gated AND opt-in:
+ * the global toggle makes the feature available to users, but a session only
+ * runs the watcher when the user explicitly enabled it for that session.
+ * (A global default-on would silently start a Haiku watcher for every
+ * session — surprise token burn.)
+ */
+export function getEffectiveMagicUi(
+  sessionState: SessionState,
+): EffectiveMagicUiSettings {
+  const global = getSettings();
+  return {
+    enabled:
+      global.magicUiEnabled
+      && sessionState.magicUiActive === true
+      && isClaudeCliAvailable(),
+    model: global.magicUiModel,
+  };
+}

package/server/magic-ui-store.ts

@@ -0,0 +1,94 @@
+// ─── MagicUI dashboard state persistence ─────────────────────────────────────
+//
+// One JSON file per session under ~/.companion/magic-ui/. Debounced writes
+// (same 150ms pattern as session-store.ts) because the watcher can emit
+// several patches in quick succession. State survives server restarts so a
+// reload / late-joining browser instantly sees the current dashboard.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+import { emptyMagicUiState, type MagicUiDashboardState } from "./magic-ui-types.js";
+
+const WRITE_DEBOUNCE_MS = 150;
+
+export class MagicUiStore {
+  private readonly dir: string;
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private pending = new Map<string, MagicUiDashboardState>();
+
+  constructor(dir?: string) {
+    this.dir = dir || join(COMPANION_HOME, "magic-ui");
+  }
+
+  private fileFor(sessionId: string): string {
+    // Session ids are UUIDs, but never trust them as path components.
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(this.dir, `${safe}.json`);
+  }
+
+  load(sessionId: string, now: number): MagicUiDashboardState {
+    try {
+      const file = this.fileFor(sessionId);
+      if (existsSync(file)) {
+        const raw = JSON.parse(readFileSync(file, "utf-8")) as Partial<MagicUiDashboardState>;
+        if (raw && typeof raw.version === "number" && raw.slots && typeof raw.slots === "object") {
+          return {
+            ...emptyMagicUiState(now),
+            ...raw,
+            // A freshly loaded dashboard is not being driven yet.
+            status: "stopped",
+          } as MagicUiDashboardState;
+        }
+      }
+    } catch {
+      // Corrupt state file → start fresh; the watcher rebuilds from its seed.
+    }
+    return emptyMagicUiState(now);
+  }
+
+  save(sessionId: string, state: MagicUiDashboardState): void {
+    this.pending.set(sessionId, state);
+    if (this.timers.has(sessionId)) return;
+    this.timers.set(
+      sessionId,
+      setTimeout(() => {
+        this.timers.delete(sessionId);
+        this.flush(sessionId);
+      }, WRITE_DEBOUNCE_MS),
+    );
+  }
+
+  flush(sessionId: string): void {
+    const state = this.pending.get(sessionId);
+    if (!state) return;
+    this.pending.delete(sessionId);
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      writeFileSync(this.fileFor(sessionId), JSON.stringify(state), "utf-8");
+    } catch (err) {
+      console.warn(`[magic-ui] Failed to persist dashboard for ${sessionId}:`, err);
+    }
+  }
+
+  flushAll(): void {
+    for (const sessionId of [...this.pending.keys()]) {
+      const timer = this.timers.get(sessionId);
+      if (timer) clearTimeout(timer);
+      this.timers.delete(sessionId);
+      this.flush(sessionId);
+    }
+  }
+
+  remove(sessionId: string): void {
+    const timer = this.timers.get(sessionId);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(sessionId);
+    this.pending.delete(sessionId);
+    try {
+      rmSync(this.fileFor(sessionId), { force: true });
+    } catch {
+      // best-effort
+    }
+  }
+}

package/server/magic-ui-types.ts

@@ -0,0 +1,138 @@
+// ─── MagicUI types ───────────────────────────────────────────────────────────
+//
+// Shared vocabulary between the server-side Haiku watcher, the canonical
+// dashboard state it maintains, and the browser/iframe runtime that renders
+// it. The watcher never authors whole documents: it emits small patch
+// operations (MagicUiOp) that the server validates, sanitizes and folds into
+// a MagicUiDashboardState — the single source of truth that late-joining
+// browsers receive as a snapshot.
+//
+// Imported by both web/server and web/src (same pattern as session-types.ts).
+
+export type MagicUiArea = "hero" | "main" | "side" | "footer";
+
+export type MagicUiTrend = "up" | "down" | "flat";
+
+export interface MagicChartSpec {
+  kind: "bar" | "line" | "donut" | "sparkline";
+  title?: string;
+  labels?: string[];
+  series: Array<{ label: string; data: number[] }>;
+}
+
+export interface MagicUiStat {
+  label: string;
+  value: string;
+  trend?: MagicUiTrend;
+}
+
+/** A copyable/expandable script or command the user is asked to run. */
+export interface MagicUiSnippet {
+  title: string;
+  language?: string;
+  code: string;
+}
+
+/**
+ * An unresolved point where the main agent is waiting on the user —
+ * a question, a manual step ("run this and report back"), or a blocker.
+ * Rendered prominently in the runtime-owned Open Points panel until a
+ * resolve_item op clears it.
+ */
+export interface MagicUiOpenItem {
+  id: string;
+  ts: number;
+  text: string;
+  kind: "action" | "question" | "blocker";
+}
+
+export interface MagicUiDecisionEntry {
+  id: string;
+  ts: number;
+  /**
+   * user    — the user answered a permission prompt / question
+   * ai_auto — AI validation auto-resolved a permission
+   * agent   — a notable choice the main agent made (watcher-observed)
+   */
+  source: "user" | "ai_auto" | "agent";
+  title: string;
+  detail: string;
+  behavior?: "allow" | "deny";
+}
+
+/** One named region of the dashboard grid. Exactly one content kind is set. */
+export interface MagicUiSlot {
+  title?: string;
+  html?: string;
+  chart?: MagicChartSpec;
+  stat?: MagicUiStat;
+  snippet?: MagicUiSnippet;
+  updatedAt: number;
+}
+
+export interface MagicUiLayoutEntry {
+  slot: string;
+  area: MagicUiArea;
+  span?: 1 | 2 | 3;
+}
+
+export type MagicUiStatus = "live" | "degraded" | "stopped";
+
+/** Patch operations the watcher model may emit (one JSON array per turn). */
+export type MagicUiOp =
+  | { op: "set_slot"; slot: string; html: string; title?: string; area?: MagicUiArea; span?: 1 | 2 | 3 }
+  | { op: "remove_slot"; slot: string }
+  | { op: "layout"; slots: MagicUiLayoutEntry[] }
+  | { op: "chart"; slot: string; spec: MagicChartSpec; title?: string; area?: MagicUiArea; span?: 1 | 2 | 3 }
+  | { op: "stat"; slot: string; label: string; value: string; trend?: MagicUiTrend; area?: MagicUiArea; span?: 1 | 2 | 3 }
+  | { op: "snippet"; slot: string; title: string; code: string; language?: string; area?: MagicUiArea; span?: 1 | 2 | 3 }
+  | { op: "open_item"; id: string; text: string; kind?: "action" | "question" | "blocker" }
+  | { op: "resolve_item"; id: string }
+  | { op: "decision_log"; title: string; detail: string }
+  | { op: "session_summary"; text: string };
+
+export interface MagicUiDashboardState {
+  /** Monotonic version, bumped once per applied patch batch. */
+  version: number;
+  slots: Record<string, MagicUiSlot>;
+  layout: MagicUiLayoutEntry[];
+  /** Newest first; server-owned entries (user/ai_auto) + watcher-observed agent ones. */
+  decisionLog: MagicUiDecisionEntry[];
+  /** Unresolved user-facing points, newest first. */
+  openItems: MagicUiOpenItem[];
+  /** Rolling watcher-maintained summary; the seed for watcher restarts. Not rendered. */
+  sessionSummary: string;
+  status: MagicUiStatus;
+  updatedAt: number;
+}
+
+export function emptyMagicUiState(now: number): MagicUiDashboardState {
+  return {
+    version: 0,
+    slots: {},
+    layout: [],
+    decisionLog: [],
+    openItems: [],
+    sessionSummary: "",
+    status: "live",
+    updatedAt: now,
+  };
+}
+
+// ── Budgets (enforced server-side in magic-ui-ops.ts) ────────────────────────
+
+/** Hard cap on named slots; the prompt asks the model to stay well under. */
+export const MAGIC_UI_MAX_SLOTS = 24;
+/** Per-slot sanitized HTML budget (chars). */
+export const MAGIC_UI_MAX_HTML_CHARS = 8_192;
+/** Per-snippet code budget (chars). */
+export const MAGIC_UI_MAX_SNIPPET_CHARS = 8_192;
+/** Max ops applied from a single watcher turn; the rest is dropped. */
+export const MAGIC_UI_MAX_OPS_PER_TURN = 30;
+/** Decision log retention (newest first). */
+export const MAGIC_UI_MAX_DECISIONS = 50;
+/** Open point retention (newest first). */
+export const MAGIC_UI_MAX_OPEN_ITEMS = 30;
+/** Chart size guards. */
+export const MAGIC_UI_MAX_CHART_SERIES = 6;
+export const MAGIC_UI_MAX_CHART_POINTS = 100;

package/server/magic-ui-watcher.test.ts

@@ -0,0 +1,288 @@
+// Tests for the MagicUI watcher: digest building, flush triggers, the
+// one-turn-in-flight merge discipline, server-generated decision log
+// entries, and manager opt-in reconciliation.
+//
+// The Agent SDK query() is replaced by an injectable fake that consumes the
+// watcher's streaming input queue and replies per test script — no network,
+// no subprocess.
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import {
+  buildDigest,
+  MagicUiWatcher,
+  MagicUiWatcherManager,
+} from "./magic-ui-watcher.js";
+import { emptyMagicUiState, type MagicUiDashboardState } from "./magic-ui-types.js";
+import type { MagicUiStore } from "./magic-ui-store.js";
+import type { BrowserIncomingMessage, SessionState } from "./session-types.js";
+import { companionBus } from "./event-bus.js";
+
+vi.mock("./path-resolver.js", () => ({
+  resolveBinary: () => "/usr/bin/claude-fake",
+  getEnrichedPath: () => process.env.PATH ?? "",
+}));
+
+// Settings used by the manager's reconcile path.
+const mockSettings = { magicUiEnabled: true, magicUiModel: "claude-haiku-4-5" };
+vi.mock("./settings-manager.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./settings-manager.js")>();
+  return { ...actual, getSettings: () => ({ ...actual.getSettings(), ...mockSettings }) };
+});
+vi.mock("./claude-cli-runner.js", () => ({
+  isClaudeCliAvailable: () => true,
+  runClaudePrompt: vi.fn(),
+}));
+
+function fakeStore(initial?: MagicUiDashboardState) {
+  return {
+    saved: [] as MagicUiDashboardState[],
+    load: vi.fn(() => initial ?? emptyMagicUiState(0)),
+    save: vi.fn(function (this: unknown, _id: string, state: MagicUiDashboardState) {
+      store.saved.push(state);
+    }),
+    flush: vi.fn(),
+    flushAll: vi.fn(),
+    remove: vi.fn(),
+  };
+}
+let store: ReturnType<typeof fakeStore>;
+
+/** Fake SDK query: consumes the prompt queue; for each user message calls
+ *  the responder and yields an assistant + result frame. */
+function makeFakeQuery(responder: (text: string) => string | Promise<string>) {
+  const received: string[] = [];
+  const fn = (({ prompt }: { prompt: AsyncIterable<SDKUserMessage> }) => {
+    async function* gen() {
+      for await (const m of prompt) {
+        const text = typeof m.message.content === "string" ? m.message.content : "";
+        received.push(text);
+        const reply = await responder(text);
+        yield { type: "assistant", message: { role: "assistant", content: [{ type: "text", text: reply }] }, parent_tool_use_id: null };
+        yield { type: "result", subtype: "success" };
+      }
+    }
+    return gen();
+  }) as unknown as typeof import("@anthropic-ai/claude-agent-sdk").query;
+  return { fn, received };
+}
+
+function assistantMsg(text: string, tools: Array<{ name: string; input: Record<string, unknown> }> = []): BrowserIncomingMessage {
+  return {
+    type: "assistant",
+    message: {
+      role: "assistant",
+      content: [
+        ...(text ? [{ type: "text", text }] : []),
+        ...tools.map((t, i) => ({ type: "tool_use", id: `t${i}`, name: t.name, input: t.input })),
+      ],
+    },
+    parent_tool_use_id: null,
+  } as unknown as BrowserIncomingMessage;
+}
+
+const OPS_REPLY = '```json\n[{"op":"set_slot","slot":"hero","html":"<p>Refactoring auth</p>","area":"hero"}]\n```';
+
+let broadcasts: Array<{ sessionId: string; msg: BrowserIncomingMessage }>;
+function makeWatcher(responder: (text: string) => string | Promise<string>) {
+  const { fn, received } = makeFakeQuery(responder);
+  const watcher = new MagicUiWatcher("sess-1", {
+    broadcast: (sessionId, msg) => broadcasts.push({ sessionId, msg }),
+    store: store as unknown as MagicUiStore,
+    model: "claude-haiku-4-5",
+    queryFn: fn,
+  });
+  return { watcher, received };
+}
+
+async function waitFor(cond: () => boolean, ms = 2000): Promise<void> {
+  const start = Date.now();
+  while (!cond()) {
+    if (Date.now() - start > ms) throw new Error("waitFor timed out");
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+beforeEach(() => {
+  broadcasts = [];
+  store = fakeStore();
+  mockSettings.magicUiEnabled = true;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("buildDigest", () => {
+  it("assembles a compact digest and enforces the size budget", () => {
+    const digest = buildDigest({
+      texts: ["Refactored the auth middleware", "x".repeat(1_000)],
+      tools: [{ name: "Edit", summary: "Edit(src/auth.ts)" }],
+      files: new Set(["src/auth.ts"]),
+      permissionLines: ["PENDING PERMISSION wanted: Bash — rm -rf dist"],
+      resultLine: "92s, 6 turns",
+      firstEventAt: 1,
+    }, 7);
+    expect(digest).toContain("TURN DIGEST #7");
+    expect(digest).toContain("Refactored the auth middleware");
+    expect(digest).toContain("Edit(src/auth.ts)");
+    expect(digest).toContain("files touched: src/auth.ts");
+    expect(digest).toContain("PENDING PERMISSION");
+    expect(digest).toContain("result: 92s, 6 turns");
+    // Long assistant text is truncated per-snippet
+    expect(digest).toContain("…");
+    expect(digest.length).toBeLessThanOrEqual(4_100);
+  });
+});
+
+describe("MagicUiWatcher", () => {
+  it("broadcasts the initial snapshot on start", () => {
+    const { watcher } = makeWatcher(() => "[]");
+    watcher.start();
+    expect(broadcasts.some((b) => b.msg.type === "magic_ui_state")).toBe(true);
+    watcher.stop();
+  });
+
+  it("flushes a digest on turn end and applies the reply ops", async () => {
+    const { watcher, received } = makeWatcher(() => OPS_REPLY);
+    watcher.start();
+    watcher.onAssistantMessage(assistantMsg("Working on auth", [{ name: "Edit", input: { file_path: "src/auth.ts" } }]));
+    watcher.onResult({ type: "result", data: { duration_ms: 5000, num_turns: 2 } } as unknown as BrowserIncomingMessage);
+
+    await waitFor(() => watcher.state.version > 0 && !!watcher.state.slots.hero);
+    expect(received[0]).toContain("Working on auth");
+    expect(received[0]).toContain("Edit(src/auth.ts)");
+    expect(watcher.state.slots.hero.html).toContain("Refactoring auth");
+    // persisted + broadcast
+    expect(store.save).toHaveBeenCalled();
+    expect(broadcasts.filter((b) => b.msg.type === "magic_ui_state").length).toBeGreaterThan(1);
+    watcher.stop();
+  });
+
+  it("flushes immediately when a permission arrives", async () => {
+    const { watcher, received } = makeWatcher(() => "[]");
+    watcher.start();
+    watcher.onPermissionRequested({
+      request_id: "r1",
+      tool_name: "Bash",
+      input: { command: "rm -rf dist" },
+      tool_use_id: "t1",
+      timestamp: 1,
+    });
+    await waitFor(() => received.length === 1);
+    expect(received[0]).toContain("PENDING PERMISSION wanted: Bash");
+    expect(received[0]).toContain("rm -rf dist");
+    watcher.stop();
+  });
+
+  it("keeps one turn in flight and merges digests queued behind it", async () => {
+    let releaseFirst: (v: string) => void = () => {};
+    let call = 0;
+    const { watcher, received } = makeWatcher((text) => {
+      call += 1;
+      if (call === 1) return new Promise<string>((resolve) => { releaseFirst = () => resolve("[]"); void text; });
+      return "[]";
+    });
+    watcher.start();
+    // First flush → in flight (responder blocks)
+    watcher.onAssistantMessage(assistantMsg("first chunk"));
+    watcher.onResult({ type: "result" } as unknown as BrowserIncomingMessage);
+    await waitFor(() => received.length === 1);
+    // Two more flushes while in flight → merged into ONE pending digest
+    watcher.onAssistantMessage(assistantMsg("second chunk"));
+    watcher.onResult({ type: "result" } as unknown as BrowserIncomingMessage);
+    watcher.onAssistantMessage(assistantMsg("third chunk"));
+    watcher.onResult({ type: "result" } as unknown as BrowserIncomingMessage);
+    expect(received.length).toBe(1);
+    releaseFirst("[]");
+    await waitFor(() => received.length === 2);
+    expect(received[1]).toContain("second chunk");
+    expect(received[1]).toContain("third chunk");
+    watcher.stop();
+  });
+
+  it("appends server-generated decision entries without involving the model", () => {
+    const { watcher } = makeWatcher(() => "[]");
+    watcher.start();
+    watcher.onPermissionResolved({
+      behavior: "allow",
+      resolvedBy: "user",
+      toolName: "AskUserQuestion",
+      answers: { "Which DB?": "Postgres" },
+    });
+    expect(watcher.state.decisionLog[0]).toMatchObject({
+      source: "user",
+      title: "Answered the agent's question",
+      behavior: "allow",
+    });
+    expect(watcher.state.decisionLog[0].detail).toContain("Which DB? → Postgres");
+
+    watcher.onPermissionResolved({ behavior: "deny", resolvedBy: "ai", toolName: "Bash", reason: "dangerous" });
+    expect(watcher.state.decisionLog[0]).toMatchObject({ source: "ai_auto", title: "Bash", behavior: "deny" });
+    watcher.stop();
+  });
+
+  it("ignores unparseable replies without corrupting state", async () => {
+    const { watcher, received } = makeWatcher(() => "sorry, I cannot do that");
+    watcher.start();
+    const versionBefore = watcher.state.version;
+    watcher.onAssistantMessage(assistantMsg("hello"));
+    watcher.onResult({ type: "result" } as unknown as BrowserIncomingMessage);
+    await waitFor(() => received.length === 1);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(watcher.state.version).toBe(versionBefore);
+    watcher.stop();
+  });
+});
+
+describe("MagicUiWatcherManager", () => {
+  function makeManager(sessionState: SessionState | undefined) {
+    const { fn } = makeFakeQuery(() => "[]");
+    return new MagicUiWatcherManager({
+      broadcast: (sessionId, msg) => broadcasts.push({ sessionId, msg }),
+      getSessionState: () => sessionState,
+      store: store as unknown as MagicUiStore,
+      queryFn: fn,
+    });
+  }
+
+  const activeSession = { session_id: "sess-1", magicUiActive: true } as SessionState;
+
+  it("starts a watcher when the session opts in and stops it on opt-out", () => {
+    const manager = makeManager(activeSession);
+    companionBus.emit("magic-ui:setting-changed", { sessionId: "sess-1", magicUiActive: true });
+    expect(broadcasts.some((b) => b.msg.type === "magic_ui_state")).toBe(true);
+
+    broadcasts = [];
+    activeSession.magicUiActive = false;
+    companionBus.emit("magic-ui:setting-changed", { sessionId: "sess-1", magicUiActive: false });
+    // stop() broadcasts a final stopped-status snapshot
+    const last = broadcasts.filter((b) => b.msg.type === "magic_ui_state").pop();
+    expect((last?.msg as { state: MagicUiDashboardState }).state.status).toBe("stopped");
+    activeSession.magicUiActive = true;
+    manager.shutdown();
+  });
+
+  it("lazily starts a watcher when messages arrive for an opted-in session", async () => {
+    const manager = makeManager({ session_id: "sess-1", magicUiActive: true } as SessionState);
+    companionBus.emit("message:assistant", { sessionId: "sess-1", message: assistantMsg("hi") });
+    expect(broadcasts.some((b) => b.msg.type === "magic_ui_state")).toBe(true);
+    manager.shutdown();
+  });
+
+  it("does not start watchers for sessions that did not opt in", () => {
+    const manager = makeManager({ session_id: "sess-1", magicUiActive: null } as SessionState);
+    companionBus.emit("message:assistant", { sessionId: "sess-1", message: assistantMsg("hi") });
+    expect(broadcasts.length).toBe(0);
+    manager.shutdown();
+  });
+
+  it("serves persisted snapshots on sync requests even without an active watcher", () => {
+    const persisted: MagicUiDashboardState = { ...emptyMagicUiState(1), version: 4 };
+    store = fakeStore(persisted);
+    const manager = makeManager({ session_id: "sess-1", magicUiActive: null } as SessionState);
+    companionBus.emit("magic-ui:sync-requested", { sessionId: "sess-1" });
+    const snap = broadcasts.find((b) => b.msg.type === "magic_ui_state");
+    expect((snap?.msg as { state: MagicUiDashboardState }).state.version).toBe(4);
+    manager.shutdown();
+  });
+});