create-claude-code-visualizer 0.1.0

package/templates/app/src/lib/agent-runner.ts

@@ -0,0 +1,411 @@
+// Agent Runner — manages agent execution independently of HTTP connections.
+// Agents run in-memory; SSE streams are read-only observers.
+
+import { EventEmitter } from "events";
+import { supabase } from "@/lib/supabase";
+import { executeAgent } from "@/lib/run-agent";
+import type { Role } from "@/lib/auth-guard";
+import type { AgentMeta } from "@/lib/types";
+
+// ---------------------------------------------------------------------------
+// RunContext — one per active agent run
+// ---------------------------------------------------------------------------
+
+export interface RunContext {
+  emitter: EventEmitter;
+  status: "running" | "done";
+  pendingApprovals: Map<string, { resolve: (approved: boolean) => void; toolName: string; toolInput: Record<string, unknown> }>;
+  abortController: AbortController;
+  bufferedText: string;
+  flushTimer: ReturnType<typeof setInterval> | null;
+  seq: number;
+  subscriberCount: number; // how many SSE clients are watching
+}
+
+// ---------------------------------------------------------------------------
+// Global registry (survives Next.js dev-mode module reloads)
+// ---------------------------------------------------------------------------
+
+const REGISTRY_KEY = "__agent_runner_registry__" as const;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const g = globalThis as any;
+if (!g[REGISTRY_KEY]) {
+  g[REGISTRY_KEY] = new Map<string, RunContext>();
+}
+export const RunnerRegistry: Map<string, RunContext> = g[REGISTRY_KEY];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function writeEvent(runId: string, seq: number, eventType: string, payload: Record<string, unknown>) {
+  await supabase.from("run_events").insert({ run_id: runId, seq, event_type: eventType, payload });
+}
+
+function emit(ctx: RunContext, runId: string, eventType: string, payload: Record<string, unknown>) {
+  ctx.emitter.emit("event", { type: eventType, seq: ctx.seq, ...payload });
+}
+
+function flushText(ctx: RunContext, runId: string): number | null {
+  if (!ctx.bufferedText) return null;
+  const seq = ++ctx.seq;
+  const text = ctx.bufferedText;
+  ctx.bufferedText = "";
+  // Write batched text to DB (fire-and-forget)
+  writeEvent(runId, seq, "text_chunk", { text });
+  return seq;
+}
+
+function emitAndWrite(ctx: RunContext, runId: string, eventType: string, payload: Record<string, unknown>) {
+  // Flush any buffered text first
+  flushText(ctx, runId);
+  const seq = ++ctx.seq;
+  emit(ctx, runId, eventType, { ...payload, seq });
+  writeEvent(runId, seq, eventType, payload);
+}
+
+// ---------------------------------------------------------------------------
+// executeDetached — starts agent, returns immediately
+// ---------------------------------------------------------------------------
+
+export function executeDetached(
+  runId: string,
+  agent: AgentMeta,
+  prompt: string,
+  sessionId?: string,
+  files?: string[],
+  userRole?: Role,
+  userEmail?: string
+): void {
+  const ctx: RunContext = {
+    emitter: new EventEmitter(),
+    status: "running",
+    pendingApprovals: new Map(),
+    abortController: new AbortController(),
+    bufferedText: "",
+    flushTimer: null,
+    seq: 0,
+    subscriberCount: 0,
+  };
+
+  // Track whether an error event was already emitted (via onError callback)
+  // to prevent the catch block from emitting a duplicate
+  let errorAlreadyEmitted = false;
+
+  // Allow many SSE listeners
+  ctx.emitter.setMaxListeners(50);
+
+  RunnerRegistry.set(runId, ctx);
+
+  // Start 3-second text flush interval
+  ctx.flushTimer = setInterval(() => {
+    flushText(ctx, runId);
+  }, 3000);
+
+  // Inject file paths into prompt
+  let agentPrompt = prompt;
+  if (files && files.length > 0) {
+    const fileList = files.map((p) => `  - ${p}`).join("\n");
+    agentPrompt = `${prompt}\n\n[Attached files — use the Read tool to read these]\n${fileList}`;
+  }
+
+  // Mark as running
+  supabase
+    .from("agent_runs")
+    .update({ status: "running", started_at: new Date().toISOString() })
+    .eq("id", runId)
+    .then(() => {
+      emitAndWrite(ctx, runId, "status", { status: "running" });
+    });
+
+  // Fire-and-forget execution
+  (async () => {
+    try {
+      const result = await executeAgent(agent, agentPrompt, {
+        signal: ctx.abortController.signal,
+        onToken: (text) => {
+          // Emit to live listeners immediately (every token).
+          // No seq — tokens are transient live events, not deduplicated.
+          // They get batched into text_chunk DB events (which have seq) by the flush timer.
+          ctx.bufferedText += text;
+          ctx.emitter.emit("event", { type: "token", text });
+        },
+        onToolCall: (name, status, detail) => {
+          emitAndWrite(ctx, runId, "tool_call", {
+            name,
+            status,
+            ...(detail?.input != null ? { input: detail.input } : {}),
+            ...(detail?.result != null ? { result: detail.result } : {}),
+          });
+        },
+        onThinking: (active) => {
+          emitAndWrite(ctx, runId, "thinking", { active });
+        },
+        onProgress: (info) => {
+          emitAndWrite(ctx, runId, "progress", { info });
+        },
+        onError: (err) => {
+          errorAlreadyEmitted = true;
+          emitAndWrite(ctx, runId, "error", { error: err });
+        },
+        onDebug: (msg) => {
+          // Debug only goes to live listeners, not DB
+          ctx.emitter.emit("event", { type: "debug", message: msg });
+        },
+        onSessionInit: (sid) => {
+          emitAndWrite(ctx, runId, "session_init", { session_id: sid });
+          // Store SDK session ID in metadata (not session_id column — that's the conversation grouping ID)
+          supabase
+            .from("agent_runs")
+            .select("metadata")
+            .eq("id", runId)
+            .single()
+            .then(({ data }) => {
+              const meta = (data?.metadata as Record<string, unknown>) || {};
+              supabase
+                .from("agent_runs")
+                .update({ metadata: { ...meta, sdk_session_id: sid } })
+                .eq("id", runId)
+                .then(() => {});
+            });
+        },
+        onApprovalRequired: async (toolName, toolInput, toolUseId) => {
+          // Flush text, then emit approval event
+          flushText(ctx, runId);
+          const seq = ++ctx.seq;
+
+          const approvalPayload = {
+            tool_name: toolName,
+            tool_input: toolInput,
+            tool_use_id: toolUseId,
+          };
+
+          emit(ctx, runId, "approval_required", { ...approvalPayload, seq });
+          writeEvent(runId, seq, "approval_required", approvalPayload);
+
+          // Persist to agent_runs so it survives reconnection
+          await supabase
+            .from("agent_runs")
+            .update({ pending_approval: approvalPayload })
+            .eq("id", runId);
+
+          // Create notification if no SSE clients are watching
+          if (ctx.subscriberCount === 0) {
+            const { data: run } = await supabase
+              .from("agent_runs")
+              .select("agent_slug, agent_name, session_id")
+              .eq("id", runId)
+              .single();
+
+            if (run) {
+              await supabase.from("notifications").insert({
+                run_id: runId,
+                agent_slug: run.agent_slug,
+                session_id: run.session_id,
+                type: "approval_needed",
+                title: `Approval needed: ${toolName}`,
+                summary: `${run.agent_name} needs permission to use ${toolName}`,
+              });
+            }
+          }
+
+          // Wait for approval (Promise blocks agent execution)
+          return new Promise<boolean>((resolve) => {
+            ctx.pendingApprovals.set(toolUseId, { resolve, toolName, toolInput });
+          });
+        },
+      }, sessionId, userRole, userEmail);
+
+      // --- Completion ---
+      flushText(ctx, runId);
+      if (ctx.flushTimer) clearInterval(ctx.flushTimer);
+
+      const finalStatus = result.aborted ? "stopped" : "completed";
+      const finalPayload = {
+        output: result.output,
+        cost_usd: result.costUsd,
+        duration_ms: result.durationMs,
+        session_id: result.sessionId,
+      };
+
+      await supabase
+        .from("agent_runs")
+        .update({
+          status: finalStatus,
+          output: result.output || null,
+          cost_usd: result.costUsd,
+          duration_ms: result.durationMs,
+          pending_approval: null,
+          completed_at: new Date().toISOString(),
+        })
+        .eq("id", runId);
+
+      const doneType = result.aborted ? "stopped" : "done";
+      emitAndWrite(ctx, runId, doneType, finalPayload);
+
+      // Create completion notification
+      const { data: run } = await supabase
+        .from("agent_runs")
+        .select("agent_slug, agent_name, session_id")
+        .eq("id", runId)
+        .single();
+
+      if (run) {
+        await supabase.from("notifications").insert({
+          run_id: runId,
+          agent_slug: run.agent_slug,
+          session_id: run.session_id,
+          type: "completed",
+          title: `${run.agent_name}: Completed`,
+          summary: result.output ? result.output.slice(0, 200) : null,
+        });
+      }
+
+      ctx.status = "done";
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+
+      flushText(ctx, runId);
+      if (ctx.flushTimer) clearInterval(ctx.flushTimer);
+
+      await supabase
+        .from("agent_runs")
+        .update({
+          status: "failed",
+          error: errorMsg,
+          pending_approval: null,
+          completed_at: new Date().toISOString(),
+        })
+        .eq("id", runId);
+
+      // Only emit error if onError callback didn't already emit it
+      // (prevents duplicate "balance too low" / credit error messages)
+      if (!errorAlreadyEmitted) {
+        emitAndWrite(ctx, runId, "error", { error: errorMsg });
+      }
+
+      // Create failure notification
+      const { data: run } = await supabase
+        .from("agent_runs")
+        .select("agent_slug, agent_name, session_id")
+        .eq("id", runId)
+        .single();
+
+      if (run) {
+        await supabase.from("notifications").insert({
+          run_id: runId,
+          agent_slug: run.agent_slug,
+          session_id: run.session_id,
+          type: "failed",
+          title: `${run.agent_name}: Failed`,
+          summary: errorMsg.slice(0, 200),
+        });
+      }
+
+      ctx.status = "done";
+    } finally {
+      // Deny any still-pending approvals
+      for (const [, entry] of ctx.pendingApprovals) {
+        entry.resolve(false);
+      }
+      ctx.pendingApprovals.clear();
+
+      // Clean up after a delay to let final SSE events drain
+      setTimeout(() => {
+        RunnerRegistry.delete(runId);
+      }, 30_000);
+    }
+  })();
+}
+
+// ---------------------------------------------------------------------------
+// getRunContext — check if agent is running in this process
+// ---------------------------------------------------------------------------
+
+export function getRunContext(runId: string): RunContext | undefined {
+  return RunnerRegistry.get(runId);
+}
+
+// ---------------------------------------------------------------------------
+// stopRun — abort a running agent
+// ---------------------------------------------------------------------------
+
+export async function stopRun(runId: string): Promise<boolean> {
+  const ctx = RunnerRegistry.get(runId);
+  if (ctx) {
+    ctx.abortController.abort();
+    return true;
+  }
+  // RunContext not found — update DB directly (server may have restarted)
+  const { error } = await supabase
+    .from("agent_runs")
+    .update({ status: "stopped", completed_at: new Date().toISOString(), pending_approval: null })
+    .eq("id", runId)
+    .eq("status", "running");
+  return !error;
+}
+
+// ---------------------------------------------------------------------------
+// submitApproval — resolve a pending approval in RunContext
+// ---------------------------------------------------------------------------
+
+export function submitApproval(runId: string, toolUseId: string, approved: boolean): boolean {
+  const ctx = RunnerRegistry.get(runId);
+  if (!ctx) return false;
+  const entry = ctx.pendingApprovals.get(toolUseId);
+  if (!entry) return false;
+  entry.resolve(approved);
+  ctx.pendingApprovals.delete(toolUseId);
+
+  // Clear pending_approval from DB and write resolution event
+  supabase
+    .from("agent_runs")
+    .update({ pending_approval: null })
+    .eq("id", runId)
+    .then(() => {});
+  emitAndWrite(ctx, runId, "approval_resolved", { tool_use_id: toolUseId, approved });
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// cleanupStaleRuns — mark old "running" runs as failed on startup
+// ---------------------------------------------------------------------------
+
+export async function cleanupStaleRuns(): Promise<void> {
+  const tenMinutesAgo = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+
+  const { data: staleRuns } = await supabase
+    .from("agent_runs")
+    .select("id, agent_slug, agent_name, session_id")
+    .eq("status", "running")
+    .lt("started_at", tenMinutesAgo);
+
+  if (!staleRuns || staleRuns.length === 0) return;
+
+  for (const run of staleRuns) {
+    // Skip runs that are actually running in this process
+    if (RunnerRegistry.has(run.id)) continue;
+
+    await supabase
+      .from("agent_runs")
+      .update({
+        status: "failed",
+        error: "Server restarted during execution",
+        pending_approval: null,
+        completed_at: new Date().toISOString(),
+      })
+      .eq("id", run.id);
+
+    await supabase.from("notifications").insert({
+      run_id: run.id,
+      agent_slug: run.agent_slug,
+      session_id: run.session_id,
+      type: "failed",
+      title: `${run.agent_name}: Failed (server restart)`,
+      summary: "Server restarted during execution. Please retry.",
+    });
+  }
+
+  console.log(`[agent-runner] Cleaned up ${staleRuns.length} stale runs`);
+}

package/templates/app/src/lib/agents.ts

@@ -0,0 +1,168 @@
+import fs from "fs";
+import path from "path";
+import matter from "gray-matter";
+import type { AgentMeta } from "./types";
+
+const PROJECT_ROOT = process.env.PROJECT_ROOT || path.resolve(__dirname, "../../../..");
+const AGENTS_DIR = path.join(PROJECT_ROOT, ".claude", "agents");
+
+// The main assistant — uses CLAUDE.md as its prompt, all other agents as subagents
+const MAIN_AGENT: AgentMeta = {
+  slug: "main",
+  name: "My Assistant",
+  description: "Your personal AI assistant with full access to all tools, MCP servers, and specialist subagents.",
+  tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebSearch", "WebFetch", "Agent", "Mcp", "Task", "NotebookEdit", "AskUserQuestion"],
+  color: "#8B5CF6",
+  emoji: "⚡",
+  vibe: "Handles everything or knows who can.",
+  filePath: "",
+};
+
+let cache: { agents: AgentMeta[]; timestamp: number } | null = null;
+const CACHE_TTL = 30_000; // 30 seconds
+
+export function getAgents(): AgentMeta[] {
+  if (cache && Date.now() - cache.timestamp < CACHE_TTL) {
+    return cache.agents;
+  }
+
+  const files = fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith(".md"));
+
+  const agents: AgentMeta[] = files.map((file) => {
+    const filePath = path.join(AGENTS_DIR, file);
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const { data } = matter(raw);
+
+    const slug = path.basename(file, ".md");
+    const tools = data.tools
+      ? String(data.tools)
+          .split(",")
+          .map((t: string) => t.trim())
+          .filter(Boolean)
+      : [];
+
+    const mcpServers = data.mcpServers
+      ? String(data.mcpServers)
+          .split(",")
+          .map((s: string) => s.trim())
+          .filter(Boolean)
+      : undefined;
+
+    return {
+      slug,
+      name: data.name || slug,
+      description: data.description || "",
+      tools,
+      mcpServers,
+      color: data.color,
+      emoji: data.emoji,
+      vibe: data.vibe,
+      model: data.model,
+      filePath,
+    };
+  });
+
+  // Main assistant always comes first
+  const all = [MAIN_AGENT, ...agents];
+  cache = { agents: all, timestamp: Date.now() };
+  return all;
+}
+
+export function getAgent(slug: string): AgentMeta | undefined {
+  return getAgents().find((a) => a.slug === slug);
+}
+
+export function clearAgentCache(): void {
+  cache = null;
+}
+
+export function updateAgentMeta(
+  slug: string,
+  updates: Partial<Pick<AgentMeta, "name" | "description" | "emoji" | "vibe" | "tools" | "mcpServers">>
+): AgentMeta | null {
+  if (slug === "main") return null; // Main agent is not file-backed
+
+  const filePath = path.join(AGENTS_DIR, `${slug}.md`);
+  if (!fs.existsSync(filePath)) return null;
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const { data, content } = matter(raw);
+
+  if (updates.name !== undefined) data.name = updates.name;
+  if (updates.description !== undefined) data.description = updates.description;
+  if (updates.emoji !== undefined) data.emoji = updates.emoji;
+  if (updates.vibe !== undefined) data.vibe = updates.vibe;
+  if (updates.tools !== undefined) data.tools = updates.tools.join(", ");
+  if (updates.mcpServers !== undefined) {
+    if (updates.mcpServers.length > 0) {
+      data.mcpServers = updates.mcpServers.join(", ");
+    } else {
+      delete data.mcpServers;
+    }
+  }
+
+  const updated = matter.stringify(content, data);
+  fs.writeFileSync(filePath, updated, "utf-8");
+
+  // Bust cache so next read picks up changes
+  cache = null;
+
+  return getAgent(slug) || null;
+}
+
+export function getAgentContent(slug: string): string {
+  if (slug === "main") return ""; // Main agent uses CLAUDE.md directly
+  const filePath = path.join(AGENTS_DIR, `${slug}.md`);
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const { content } = matter(raw);
+  return content.trim();
+}
+
+export function createAgent(meta: {
+  name: string;
+  description: string;
+  tools?: string;
+  mcpServers?: string;
+  color?: string;
+  emoji?: string;
+  vibe?: string;
+  model?: string;
+  content: string;
+}): AgentMeta {
+  // Generate slug from name
+  const slug = meta.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  const filePath = path.join(AGENTS_DIR, `${slug}.md`);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Agent "${slug}" already exists`);
+  }
+
+  const frontmatter: Record<string, string> = {
+    name: meta.name,
+    description: meta.description,
+  };
+  if (meta.tools) frontmatter.tools = meta.tools;
+  if (meta.mcpServers) frontmatter.mcpServers = meta.mcpServers;
+  if (meta.color) frontmatter.color = meta.color;
+  if (meta.emoji) frontmatter.emoji = meta.emoji;
+  if (meta.vibe) frontmatter.vibe = meta.vibe;
+  if (meta.model) frontmatter.model = meta.model;
+
+  const fileContent = matter.stringify(meta.content, frontmatter);
+  fs.writeFileSync(filePath, fileContent, "utf-8");
+
+  cache = null;
+  return getAgent(slug)!;
+}
+
+export function deleteAgent(slug: string): boolean {
+  if (slug === "main") return false;
+  const filePath = path.join(AGENTS_DIR, `${slug}.md`);
+  if (!fs.existsSync(filePath)) return false;
+  fs.unlinkSync(filePath);
+  cache = null;
+  return true;
+}

package/templates/app/src/lib/ai.ts

@@ -0,0 +1,40 @@
+const ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages";
+const MODEL = "claude-haiku-4-5-20251001";
+
+interface Message {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export async function callHaiku(
+  system: string,
+  messages: Message[],
+  maxTokens = 256
+): Promise<string> {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) throw new Error("ANTHROPIC_API_KEY not set");
+
+  const res = await fetch(ANTHROPIC_API_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model: MODEL,
+      max_tokens: maxTokens,
+      system,
+      messages,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Anthropic API error ${res.status}: ${body}`);
+  }
+
+  const data = await res.json();
+  const block = data.content?.[0];
+  return block?.type === "text" ? block.text : "";
+}

package/templates/app/src/lib/approval-store.ts

@@ -0,0 +1,70 @@
+// Approval store — now delegates to RunnerRegistry for active runs.
+// Keeps the old in-memory map as fallback for any edge cases,
+// and preserves isReadOnlyMcpTool which is used by run-agent.ts.
+
+import { submitApproval as runnerSubmit, getRunContext } from "@/lib/agent-runner";
+
+// --- Legacy in-memory map (fallback) ---
+
+interface PendingApproval {
+  resolve: (approved: boolean) => void;
+  toolName: string;
+  toolInput: Record<string, unknown>;
+}
+
+const globalKey = "__approval_pending_map__" as const;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const g = globalThis as any;
+if (!g[globalKey]) {
+  g[globalKey] = new Map<string, PendingApproval>();
+}
+const pending: Map<string, PendingApproval> = g[globalKey];
+
+export function requestApproval(
+  runId: string,
+  toolUseId: string,
+  toolName: string,
+  toolInput: Record<string, unknown>
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    pending.set(`${runId}:${toolUseId}`, { resolve, toolName, toolInput });
+  });
+}
+
+export function submitApproval(
+  runId: string,
+  toolUseId: string,
+  approved: boolean
+): boolean {
+  // Try RunnerRegistry first (new detached execution path)
+  if (getRunContext(runId)) {
+    return runnerSubmit(runId, toolUseId, approved);
+  }
+  // Fallback to legacy map
+  const key = `${runId}:${toolUseId}`;
+  const entry = pending.get(key);
+  if (!entry) return false;
+  entry.resolve(approved);
+  pending.delete(key);
+  return true;
+}
+
+export function cancelAllForRun(runId: string): void {
+  for (const [key, entry] of pending) {
+    if (key.startsWith(`${runId}:`)) {
+      entry.resolve(false);
+      pending.delete(key);
+    }
+  }
+}
+
+// Check if a tool name looks like a read-only operation
+const READ_VERBS = ["get", "list", "search", "read", "find", "view", "check", "fetch", "show", "describe", "take_screenshot", "take_snapshot", "take_memory_snapshot", "lighthouse_audit", "performance_analyze", "list_console", "list_network", "list_pages", "get_console", "get_network"];
+
+export function isReadOnlyMcpTool(toolName: string): boolean {
+  const lower = toolName.toLowerCase();
+  return READ_VERBS.some((verb) => {
+    const pattern = new RegExp(`(?:^|__|_)${verb}(?:_|$)`);
+    return pattern.test(lower);
+  });
+}