@towles/tool 0.0.106 → 0.0.108

package/plugins/tt-agentboard/packages/runtime/src/agents/watchers/amp.ts

@@ -0,0 +1,316 @@
+/**
+ * Amp agent watcher
+ *
+ * Watches ~/.local/share/amp/threads/ for JSON file changes,
+ * determines agent status from the last message, and emits events
+ * mapped to mux sessions via the project directory in each thread.
+ *
+ * All file I/O is async to avoid blocking the server event loop.
+ */
+
+import { watch } from "node:fs";
+import type { FSWatcher } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import type { AgentStatus } from "../../contracts/agent";
+import type { AgentWatcher, AgentWatcherContext } from "../../contracts/agent-watcher";
+
+// --- Thread file types ---
+
+interface MessageState {
+  type?: string;
+  stopReason?: string;
+}
+
+interface Message {
+  role?: string;
+  state?: MessageState;
+}
+
+interface ThreadSnapshot {
+  status: AgentStatus;
+  version: number;
+  title?: string;
+  projectDir?: string;
+  mtimeMs: number;
+}
+
+const STALE_MS = 5 * 60 * 1000;
+const POLL_MS = 2000;
+
+// --- Status detection ---
+
+export function determineStatus(
+  lastMsg: { role?: string; state?: MessageState } | null,
+): AgentStatus {
+  if (!lastMsg?.role) return "idle";
+
+  if (lastMsg.role === "user") return "running";
+
+  if (lastMsg.role === "assistant") {
+    const state = lastMsg.state;
+    if (!state) return "running";
+    if (state.type === "streaming") return "running";
+    if (state.type === "cancelled" || state.type === "aborted" || state.type === "interrupted")
+      return "interrupted";
+    if (state.type === "error" || state.type === "errored" || state.type === "failed")
+      return "error";
+    if (state.type === "complete") {
+      if (state.stopReason === "tool_use") return "running";
+      if (state.stopReason === "end_turn") return "done";
+      // Amp uses other stop reasons such as max_tokens for terminal failures.
+      return "error";
+    }
+    return "waiting";
+  }
+
+  return "idle";
+}
+
+// --- Async thread file parsing ---
+
+async function parseThreadFile(filePath: string): Promise<{
+  version: number;
+  title?: string;
+  projectDir?: string;
+  lastMessage: Message | null;
+} | null> {
+  try {
+    const raw = await Bun.file(filePath).text();
+    const thread = JSON.parse(raw);
+    const messages = thread.messages ?? [];
+    const lastMsg = messages.length > 0 ? messages[messages.length - 1] : null;
+    const uri: string = thread.env?.initial?.trees?.[0]?.uri ?? "";
+    const projectDir = uri.startsWith("file://") ? uri.slice(7) : undefined;
+
+    return {
+      version: thread.v ?? 0,
+      title: thread.title || undefined,
+      projectDir,
+      lastMessage: lastMsg ? { role: lastMsg.role, state: lastMsg.state } : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// --- Watcher implementation ---
+
+export class AmpAgentWatcher implements AgentWatcher {
+  readonly name = "amp";
+
+  private threads = new Map<string, ThreadSnapshot>();
+  private fsWatcher: FSWatcher | null = null;
+  private sessionWatcher: FSWatcher | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private ctx: AgentWatcherContext | null = null;
+  private threadsDir: string;
+  private sessionFile: string;
+  private scanning = false;
+  private seeded = false;
+  private lastFocusedThread: string | null = null;
+
+  constructor() {
+    const dataDir = join(homedir(), ".local", "share", "amp");
+    this.threadsDir = join(dataDir, "threads");
+    this.sessionFile = join(dataDir, "session.json");
+  }
+
+  start(ctx: AgentWatcherContext): void {
+    this.ctx = ctx;
+    this.setupWatch();
+    this.setupSessionWatch();
+    setTimeout(() => this.scan(), 50);
+    this.pollTimer = setInterval(() => this.scan(), POLL_MS);
+  }
+
+  stop(): void {
+    if (this.fsWatcher) {
+      try {
+        this.fsWatcher.close();
+      } catch {}
+      this.fsWatcher = null;
+    }
+    if (this.sessionWatcher) {
+      try {
+        this.sessionWatcher.close();
+      } catch {}
+      this.sessionWatcher = null;
+    }
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    this.ctx = null;
+  }
+
+  private emitThread(threadId: string, snapshot: ThreadSnapshot): boolean {
+    if (!this.ctx || !snapshot.projectDir || snapshot.status === "idle") return false;
+
+    const session = this.ctx.resolveSession(snapshot.projectDir);
+    if (!session || session === "unknown") return false;
+
+    this.ctx.emit({
+      agent: "amp",
+      session,
+      status: snapshot.status,
+      ts: Date.now(),
+      threadId,
+      threadName: snapshot.title,
+    });
+    return true;
+  }
+
+  private async processThread(filePath: string): Promise<boolean> {
+    if (!this.ctx) return false;
+
+    let fileStat;
+    try {
+      fileStat = await stat(filePath);
+    } catch {
+      return false;
+    }
+
+    const threadId = basename(filePath, ".json");
+    const prev = this.threads.get(threadId);
+
+    // Quick mtime check — skip if file hasn't changed since we last saw this version
+    if (prev && fileStat.mtimeMs <= prev.mtimeMs) return false;
+
+    const parsed = await parseThreadFile(filePath);
+    if (!parsed) return false;
+
+    const status = determineStatus(parsed.lastMessage);
+    const statusChanged = prev?.status !== status;
+    const titleChanged = prev?.title !== parsed.title;
+    const projectDirChanged = prev?.projectDir !== parsed.projectDir;
+
+    if (
+      prev &&
+      parsed.version === prev.version &&
+      !statusChanged &&
+      !titleChanged &&
+      !projectDirChanged
+    ) {
+      // Update mtime even if version unchanged to avoid re-reading
+      prev.mtimeMs = fileStat.mtimeMs;
+      return false;
+    }
+
+    const snapshot: ThreadSnapshot = {
+      status,
+      version: parsed.version,
+      title: parsed.title,
+      projectDir: parsed.projectDir,
+      mtimeMs: fileStat.mtimeMs,
+    };
+    this.threads.set(threadId, snapshot);
+
+    // Seed mode: record state without emitting
+    if (!this.seeded) return false;
+
+    return (statusChanged || titleChanged) && this.emitThread(threadId, snapshot);
+  }
+
+  private async scan(): Promise<void> {
+    if (this.scanning || !this.ctx) return;
+    this.scanning = true;
+    const initialSeed = !this.seeded;
+
+    try {
+      let files: string[];
+      try {
+        files = await readdir(this.threadsDir);
+      } catch {
+        return;
+      }
+
+      const now = Date.now();
+      for (const file of files) {
+        if (!file.startsWith("T-") || !file.endsWith(".json")) continue;
+        const filePath = join(this.threadsDir, file);
+        let fileStat;
+        try {
+          fileStat = await stat(filePath);
+        } catch {
+          continue;
+        }
+        if (now - fileStat.mtimeMs > STALE_MS) continue;
+        await this.processThread(filePath);
+      }
+    } finally {
+      if (initialSeed) {
+        this.seeded = true;
+        for (const [threadId, snapshot] of this.threads) {
+          this.emitThread(threadId, snapshot);
+        }
+      }
+      this.scanning = false;
+    }
+  }
+
+  private setupWatch(): void {
+    try {
+      this.fsWatcher = watch(this.threadsDir, (_eventType, filename) => {
+        if (!filename?.startsWith("T-") || !filename.endsWith(".json")) return;
+        this.processThread(join(this.threadsDir, filename));
+      });
+    } catch {
+      // fs.watch failed; polling handles it
+    }
+  }
+
+  /** Watch Amp's session.json for lastThreadId changes — thread-level "seen" signal */
+  private setupSessionWatch(): void {
+    // Seed the initial focused thread
+    this.checkSessionFocus();
+
+    try {
+      this.sessionWatcher = watch(this.sessionFile, () => {
+        this.checkSessionFocus();
+      });
+    } catch {
+      // session.json doesn't exist yet or can't be watched; ignore
+    }
+  }
+
+  /** Read session.json and emit "idle" for a terminal thread the user has focused in Amp */
+  private async checkSessionFocus(): Promise<void> {
+    if (!this.ctx || !this.seeded) return;
+
+    try {
+      const raw = await Bun.file(this.sessionFile).text();
+      const session = JSON.parse(raw);
+      const threadId: string | undefined = session.lastThreadId;
+      if (!threadId || threadId === this.lastFocusedThread) return;
+
+      this.lastFocusedThread = threadId;
+
+      // If this thread is tracked and in a terminal state, the user just "saw" it
+      const snapshot = this.threads.get(threadId);
+      if (!snapshot || !snapshot.projectDir) return;
+      if (
+        snapshot.status !== "done" &&
+        snapshot.status !== "error" &&
+        snapshot.status !== "interrupted"
+      )
+        return;
+
+      const muxSession = this.ctx.resolveSession(snapshot.projectDir);
+      if (!muxSession || muxSession === "unknown") return;
+
+      // Emit "idle" to clear the unseen flag for this specific thread
+      this.ctx.emit({
+        agent: "amp",
+        session: muxSession,
+        status: "idle",
+        ts: Date.now(),
+        threadId,
+        threadName: snapshot.title,
+      });
+    } catch {
+      // session.json unreadable; ignore
+    }
+  }
+}

package/plugins/tt-agentboard/packages/runtime/src/agents/watchers/claude-code.ts

@@ -0,0 +1,374 @@
+/**
+ * Claude Code agent watcher
+ *
+ * Watches ~/.claude/projects/ for JSONL file changes,
+ * determines agent status from journal entries, and emits events
+ * mapped to mux sessions via the project directory encoded in folder names.
+ *
+ * Directory structure: ~/.claude/projects/<encoded-path>/<session-id>.jsonl
+ * Encoded path: /Users/foo/myproject → -Users-foo-myproject
+ *
+ * All file I/O is async to avoid blocking the server event loop.
+ */
+
+import { watch } from "node:fs";
+import type { FSWatcher } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import type { AgentStatus } from "../../contracts/agent";
+import type { AgentWatcher, AgentWatcherContext } from "../../contracts/agent-watcher";
+
+// --- Types ---
+
+interface ContentItem {
+  type?: string;
+  text?: string;
+}
+
+interface JournalEntry {
+  type?: string;
+  message?: {
+    role?: string;
+    content?: ContentItem[] | string;
+  };
+}
+
+interface SessionState {
+  status: AgentStatus;
+  fileSize: number;
+  threadName?: string;
+  projectDir?: string;
+}
+
+const POLL_MS = 2000;
+const STALE_MS = 5 * 60 * 1000;
+
+// --- Status detection ---
+
+export function determineStatus(entry: JournalEntry): AgentStatus {
+  const msg = entry.message;
+  if (!msg?.role) return "idle";
+
+  const content = msg.content;
+  const items: ContentItem[] = Array.isArray(content)
+    ? content
+    : typeof content === "string"
+      ? [{ type: "text", text: content }]
+      : [];
+
+  if (msg.role === "assistant") {
+    const hasToolUse = items.some((c) => c.type === "tool_use");
+    return hasToolUse ? "running" : "done";
+  }
+
+  if (msg.role === "user") return "running";
+
+  return "idle";
+}
+
+function extractThreadName(entry: JournalEntry): string | undefined {
+  const msg = entry.message;
+  if (msg?.role !== "user") return undefined;
+
+  const content = msg.content;
+  let text: string | undefined;
+
+  if (typeof content === "string") {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content.find((c) => c.type === "text" && c.text)?.text;
+  }
+
+  if (!text) return undefined;
+  // Skip system/internal messages
+  if (text.startsWith("<") || text.startsWith("{")) return undefined;
+  return text.slice(0, 80);
+}
+
+/** Decode Claude's encoded project dir name back to a path.
+ * Claude Code encodes `/` as `-` with no escape for literal dashes,
+ * so paths like `/home/user/my-project` are ambiguous with `/home/user/my/project`.
+ * This is a known Claude Code limitation. */
+function decodeProjectDir(encoded: string): string {
+  return encoded.replace(/-/g, "/");
+}
+
+// --- Watcher implementation ---
+
+export class ClaudeCodeAgentWatcher implements AgentWatcher {
+  readonly name = "claude-code";
+
+  private sessions = new Map<string, SessionState>();
+  private fsWatchers: FSWatcher[] = [];
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private ctx: AgentWatcherContext | null = null;
+  private projectsDir: string;
+  private scanning = false;
+  private seeded = false;
+
+  constructor() {
+    this.projectsDir = join(homedir(), ".claude", "projects");
+  }
+
+  start(ctx: AgentWatcherContext): void {
+    this.ctx = ctx;
+    this.setupWatchers();
+    setTimeout(() => this.scan(), 50);
+    this.pollTimer = setInterval(() => this.scan(), POLL_MS);
+  }
+
+  stop(): void {
+    for (const w of this.fsWatchers) {
+      try {
+        w.close();
+      } catch {}
+    }
+    this.fsWatchers = [];
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    this.ctx = null;
+  }
+
+  private async processFile(filePath: string, projectDir: string): Promise<void> {
+    if (!this.ctx) return;
+
+    let size: number;
+    try {
+      size = (await stat(filePath)).size;
+    } catch {
+      return;
+    }
+
+    const threadId = basename(filePath, ".jsonl");
+    const prev = this.sessions.get(threadId);
+
+    if (prev && size === prev.fileSize) return;
+
+    // Seed mode: read last entry to capture real status for post-seed emit
+    if (!this.seeded) {
+      let text: string;
+      try {
+        text = await Bun.file(filePath).text();
+      } catch {
+        return;
+      }
+
+      const lines = text.split("\n").filter(Boolean);
+      let latestStatus: AgentStatus = "idle";
+      let threadName: string | undefined;
+
+      for (const line of lines) {
+        let entry: JournalEntry;
+        try {
+          entry = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (!threadName) {
+          const name = extractThreadName(entry);
+          if (name) threadName = name;
+        }
+        latestStatus = determineStatus(entry);
+      }
+
+      // If "running" but journal file is stale, the process likely exited
+      if (latestStatus === "running") {
+        try {
+          const mtime = (await stat(filePath)).mtimeMs;
+          if (Date.now() - mtime > 10_000) latestStatus = "idle";
+        } catch {}
+      }
+
+      this.sessions.set(threadId, { status: latestStatus, fileSize: size, threadName, projectDir });
+      return;
+    }
+
+    const offset = prev?.fileSize ?? 0;
+    if (size <= offset) return;
+
+    let text: string;
+    try {
+      const buf = await Bun.file(filePath).arrayBuffer();
+      text = new TextDecoder().decode(new Uint8Array(buf).subarray(offset, size));
+    } catch {
+      return;
+    }
+
+    const lines = text.split("\n").filter(Boolean);
+    let latestStatus: AgentStatus = prev?.status ?? "idle";
+    let threadName = prev?.threadName;
+
+    for (const line of lines) {
+      let entry: JournalEntry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (!threadName) {
+        const name = extractThreadName(entry);
+        if (name) threadName = name;
+      }
+
+      latestStatus = determineStatus(entry);
+    }
+
+    const prevStatus = prev?.status;
+    this.sessions.set(threadId, { status: latestStatus, fileSize: size, threadName, projectDir });
+
+    if (latestStatus !== prevStatus) {
+      const session = this.ctx.resolveSession(projectDir);
+      if (session) {
+        this.ctx.emit({
+          agent: "claude-code",
+          session,
+          status: latestStatus,
+          ts: Date.now(),
+          threadId,
+          threadName,
+        });
+      }
+    }
+  }
+
+  private async scan(): Promise<void> {
+    if (this.scanning || !this.ctx) return;
+    this.scanning = true;
+
+    try {
+      let dirs: string[];
+      try {
+        dirs = await readdir(this.projectsDir);
+      } catch {
+        return;
+      }
+      const now = Date.now();
+
+      for (const dir of dirs) {
+        const dirPath = join(this.projectsDir, dir);
+        try {
+          if (!(await stat(dirPath)).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+
+        const projectDir = decodeProjectDir(dir);
+
+        let files: string[];
+        try {
+          files = await readdir(dirPath);
+        } catch {
+          continue;
+        }
+
+        for (const file of files) {
+          if (!file.endsWith(".jsonl")) continue;
+          const filePath = join(dirPath, file);
+          let fileStat;
+          try {
+            fileStat = await stat(filePath);
+          } catch {
+            continue;
+          }
+          if (now - fileStat.mtimeMs > STALE_MS) continue;
+          // Lazily watch dirs that become active
+          this.watchDir(dirPath);
+          await this.processFile(filePath, projectDir);
+        }
+      }
+    } finally {
+      if (!this.seeded) {
+        this.seeded = true;
+        // Emit seeded sessions with non-idle status (like amp watcher does)
+        for (const [threadId, state] of this.sessions) {
+          if (state.status === "idle" || !state.projectDir) continue;
+          const session = this.ctx?.resolveSession(state.projectDir);
+          if (!session) continue;
+          this.ctx?.emit({
+            agent: "claude-code",
+            session,
+            status: state.status,
+            ts: Date.now(),
+            threadId,
+            threadName: state.threadName,
+          });
+        }
+      }
+      this.scanning = false;
+    }
+  }
+
+  private watchedDirs = new Set<string>();
+
+  private watchDir(dirPath: string): void {
+    if (this.watchedDirs.has(dirPath)) return;
+    const projectDir = decodeProjectDir(basename(dirPath));
+    try {
+      const w = watch(dirPath, (_eventType, filename) => {
+        if (!filename?.endsWith(".jsonl")) return;
+        this.processFile(join(dirPath, filename), projectDir);
+      });
+      this.fsWatchers.push(w);
+      this.watchedDirs.add(dirPath);
+    } catch {}
+  }
+
+  private hasRecentFiles(dirPath: string): boolean {
+    const fs = require("node:fs") as typeof import("node:fs");
+    try {
+      const files = fs.readdirSync(dirPath);
+      const now = Date.now();
+      for (const file of files) {
+        if (!file.endsWith(".jsonl")) continue;
+        try {
+          const s = fs.statSync(join(dirPath, file));
+          if (now - s.mtimeMs < STALE_MS) return true;
+        } catch {}
+      }
+    } catch {}
+    return false;
+  }
+
+  private setupWatchers(): void {
+    let dirs: string[];
+    try {
+      dirs = require("node:fs").readdirSync(this.projectsDir);
+    } catch {
+      return;
+    }
+
+    const fs = require("node:fs") as typeof import("node:fs");
+    for (const dir of dirs) {
+      const dirPath = join(this.projectsDir, dir);
+      try {
+        if (!fs.statSync(dirPath).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+
+      // Only watch directories that have recently-modified files
+      if (this.hasRecentFiles(dirPath)) {
+        this.watchDir(dirPath);
+      }
+    }
+
+    // Watch projects dir for new project directories
+    try {
+      const w = watch(this.projectsDir, (eventType, filename) => {
+        if (eventType !== "rename" || !filename) return;
+        const dirPath = join(this.projectsDir, filename);
+        try {
+          if (!fs.statSync(dirPath).isDirectory()) return;
+        } catch {
+          return;
+        }
+        this.watchDir(dirPath);
+      });
+      this.fsWatchers.push(w);
+    } catch {}
+  }
+}