@towles/tool 0.0.119 → 0.0.121

package/packages/agentboard/packages/runtime/package.json

@@ -8,6 +8,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.56.0",
     "consola": "^3.4.2"
   },
   "devDependencies": {

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

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "bun:test";
-import { determineStatus } from "./claude-code";
+import { determineStatus, summaryToDetails } from "./claude-code";
+import type { ClaudeUsageSummary } from "./claude-usage";
 
 describe("determineStatus", () => {
   it("returns null when no message", () => {
@@ -61,3 +62,39 @@ describe("determineStatus", () => {
     ).toBeNull();
   });
 });
+
+describe("summaryToDetails", () => {
+  it("maps all fields including cache", () => {
+    const s: ClaudeUsageSummary = {
+      model: "claude-opus-4-6",
+      contextUsed: 1000,
+      contextMax: 200_000,
+      cacheTtlMs: 300_000,
+      cacheExpiresAt: 1_700_000_000_000,
+      lastActivityAt: 1_699_999_700_000,
+    };
+    expect(summaryToDetails(s)).toEqual({
+      model: "claude-opus-4-6",
+      contextUsed: 1000,
+      contextMax: 200_000,
+      cacheTtlMs: 300_000,
+      cacheExpiresAt: 1_700_000_000_000,
+      lastActivityAt: 1_699_999_700_000,
+    });
+  });
+
+  it("omits cache fields when null (converts to undefined)", () => {
+    const s: ClaudeUsageSummary = {
+      model: "claude-haiku-4-5",
+      contextUsed: 500,
+      contextMax: 200_000,
+      cacheTtlMs: null,
+      cacheExpiresAt: null,
+      lastActivityAt: 1_700_000_000_000,
+    };
+    const details = summaryToDetails(s);
+    expect(details.cacheTtlMs).toBeUndefined();
+    expect(details.cacheExpiresAt).toBeUndefined();
+    expect(details.model).toBe("claude-haiku-4-5");
+  });
+});

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

@@ -19,12 +19,17 @@ import { homedir } from "node:os";
 import type { AgentStatus } from "../../contracts/agent";
 import type { AgentWatcher, AgentWatcherContext } from "../../contracts/agent-watcher";
 import { JOURNAL_IDLE_TIMEOUT_MS } from "../../shared";
+import { createClaudePidLookup } from "./claude-pid";
+import type { ClaudePidLookup } from "./claude-pid";
+import { extractUsageSummary } from "./claude-usage";
+import type { ClaudeUsageSummary } from "./claude-usage";
 
 // --- Types ---
 
 interface ContentItem {
   type?: string;
   text?: string;
+  name?: string;
 }
 
 interface JournalEntry {
@@ -40,6 +45,7 @@ interface SessionState {
   fileSize: number;
   threadName?: string;
   projectDir?: string;
+  usage?: ClaudeUsageSummary;
 }
 
 const POLL_MS = 2000;
@@ -61,7 +67,7 @@ export function determineStatus(entry: JournalEntry): AgentStatus | null {
   if (msg.role === "assistant") {
     const toolUses = items.filter((c) => c.type === "tool_use");
     if (toolUses.length === 0) return "done";
-    const allAsking = toolUses.every((c) => (c as any).name === "AskUserQuestion");
+    const allAsking = toolUses.every((c) => c.name === "AskUserQuestion");
     return allAsking ? "question" : "running";
   }
 
@@ -97,6 +103,21 @@ function decodeProjectDir(encoded: string): string {
   return encoded.replace(/-/g, "/");
 }
 
+// --- Usage summary → AgentEventDetails ---
+
+export function summaryToDetails(
+  s: ClaudeUsageSummary,
+): import("../../contracts/agent").AgentEventDetails {
+  return {
+    model: s.model,
+    contextUsed: s.contextUsed,
+    contextMax: s.contextMax,
+    cacheExpiresAt: s.cacheExpiresAt ?? undefined,
+    cacheTtlMs: s.cacheTtlMs ?? undefined,
+    lastActivityAt: s.lastActivityAt,
+  };
+}
+
 // --- Watcher implementation ---
 
 export class ClaudeCodeAgentWatcher implements AgentWatcher {
@@ -109,9 +130,11 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
   private projectsDir: string;
   private scanning = false;
   private seeded = false;
+  private pidLookup: ClaudePidLookup;
 
-  constructor() {
+  constructor(pidLookup: ClaudePidLookup = createClaudePidLookup()) {
     this.projectsDir = join(homedir(), ".claude", "projects");
+    this.pidLookup = pidLookup;
   }
 
   start(ctx: AgentWatcherContext): void {
@@ -149,26 +172,36 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
     const prev = this.sessions.get(threadId);
 
     if (prev && size === prev.fileSize) {
-      // Post-seed: if status is "running" but journal hasn't been written to
-      // in >2min, the process likely exited — downgrade to "idle".
+      // Post-seed: check if the process is actually still alive.
       if (this.seeded && prev.status === "running") {
-        try {
-          const mtime = (await stat(filePath)).mtimeMs;
-          if (Date.now() - mtime > JOURNAL_IDLE_TIMEOUT_MS) {
-            prev.status = "idle";
-            const session = prev.projectDir ? this.ctx?.resolveSession(prev.projectDir) : undefined;
-            if (session) {
-              this.ctx?.emit({
-                agent: "claude-code",
-                session,
-                status: "idle",
-                ts: Date.now(),
-                threadId,
-                threadName: prev.threadName,
-              });
-            }
+        const pid = await this.pidLookup.pidForThread(threadId);
+        const processGone = pid != null && !this.pidLookup.isAlive(pid);
+
+        let becomeIdle = false;
+        if (processGone) {
+          becomeIdle = true;
+        } else {
+          try {
+            const mtime = (await stat(filePath)).mtimeMs;
+            if (Date.now() - mtime > JOURNAL_IDLE_TIMEOUT_MS) becomeIdle = true;
+          } catch {}
+        }
+
+        if (becomeIdle) {
+          prev.status = "idle";
+          const session = prev.projectDir ? this.ctx?.resolveSession(prev.projectDir) : undefined;
+          if (session) {
+            this.ctx?.emit({
+              agent: "claude-code",
+              session,
+              status: "idle",
+              ts: Date.now(),
+              threadId,
+              threadName: prev.threadName,
+              details: prev.usage ? summaryToDetails(prev.usage) : undefined,
+            });
           }
-        } catch {}
+        }
       }
       return;
     }
@@ -183,16 +216,19 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
       }
 
       const lines = text.split("\n").filter(Boolean);
-      let latestStatus: AgentStatus = "idle";
-      let threadName: string | undefined;
 
+      const parsed: JournalEntry[] = [];
       for (const line of lines) {
-        let entry: JournalEntry;
         try {
-          entry = JSON.parse(line);
+          parsed.push(JSON.parse(line) as JournalEntry);
         } catch {
           continue;
         }
+      }
+
+      let latestStatus: AgentStatus = "idle";
+      let threadName: string | undefined;
+      for (const entry of parsed) {
         if (!threadName) {
           const name = extractThreadName(entry);
           if (name) threadName = name;
@@ -200,6 +236,8 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         latestStatus = determineStatus(entry) ?? latestStatus;
       }
 
+      const usage = extractUsageSummary(parsed) ?? undefined;
+
       // If "running" but journal file is stale, the process likely exited
       if (latestStatus === "running") {
         try {
@@ -208,7 +246,13 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         } catch {}
       }
 
-      this.sessions.set(threadId, { status: latestStatus, fileSize: size, threadName, projectDir });
+      this.sessions.set(threadId, {
+        status: latestStatus,
+        fileSize: size,
+        threadName,
+        projectDir,
+        usage,
+      });
       return;
     }
 
@@ -224,27 +268,45 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
     }
 
     const lines = text.split("\n").filter(Boolean);
-    let latestStatus: AgentStatus = prev?.status ?? "idle";
-    let threadName = prev?.threadName;
 
+    const parsed: JournalEntry[] = [];
     for (const line of lines) {
-      let entry: JournalEntry;
       try {
-        entry = JSON.parse(line);
+        parsed.push(JSON.parse(line) as JournalEntry);
       } catch {
         continue;
       }
+    }
 
+    let latestStatus: AgentStatus = prev?.status ?? "idle";
+    let threadName = prev?.threadName;
+    for (const entry of parsed) {
       if (!threadName) {
         const name = extractThreadName(entry);
         if (name) threadName = name;
       }
-
       latestStatus = determineStatus(entry) ?? latestStatus;
     }
 
+    // Merge new usage summary onto the previous one (incremental reads may not include the latest assistant turn)
+    const newUsage = extractUsageSummary(parsed);
+    const usage = newUsage ?? prev?.usage;
+
+    if (latestStatus === "running") {
+      const pid = await this.pidLookup.pidForThread(threadId);
+      if (pid != null && !this.pidLookup.isAlive(pid)) {
+        latestStatus = "idle";
+      }
+    }
+
     const prevStatus = prev?.status;
-    this.sessions.set(threadId, { status: latestStatus, fileSize: size, threadName, projectDir });
+    this.sessions.set(threadId, {
+      status: latestStatus,
+      fileSize: size,
+      threadName,
+      projectDir,
+      usage,
+    });
 
     if (latestStatus !== prevStatus) {
       const session = this.ctx.resolveSession(projectDir);
@@ -256,6 +318,7 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
           ts: Date.now(),
           threadId,
           threadName,
+          details: usage ? summaryToDetails(usage) : undefined,
         });
       }
     }
@@ -264,6 +327,7 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
   private async scan(): Promise<void> {
     if (this.scanning || !this.ctx) return;
     this.scanning = true;
+    this.pidLookup.invalidate();
 
     try {
       let dirs: string[];
@@ -312,15 +376,27 @@ export class ClaudeCodeAgentWatcher implements AgentWatcher {
         // 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;
+
+          let status = state.status;
+          if (status === "running") {
+            const pid = await this.pidLookup.pidForThread(threadId);
+            if (pid != null && !this.pidLookup.isAlive(pid)) {
+              status = "idle";
+              state.status = "idle";
+              continue;
+            }
+          }
+
           const session = this.ctx?.resolveSession(state.projectDir);
           if (!session) continue;
           this.ctx?.emit({
             agent: "claude-code",
             session,
-            status: state.status,
+            status,
             ts: Date.now(),
             threadId,
             threadName: state.threadName,
+            details: state.usage ? summaryToDetails(state.usage) : undefined,
           });
         }
       }

package/packages/agentboard/packages/runtime/src/agents/watchers/claude-pid.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createClaudePidLookup } from "./claude-pid";
+
+let tmpDir: string;
+let sessionsDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "claude-pid-test-"));
+  sessionsDir = join(tmpDir, "sessions");
+  mkdirSync(sessionsDir);
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function writeSession(pid: number, sessionId: string) {
+  writeFileSync(
+    join(sessionsDir, `${pid}.json`),
+    JSON.stringify({ pid, sessionId, cwd: "/tmp", startedAt: Date.now(), kind: "interactive" }),
+  );
+}
+
+describe("claude-pid lookup", () => {
+  it("finds PID by threadId", async () => {
+    writeSession(12345, "thread-a");
+    writeSession(67890, "thread-b");
+    const lookup = createClaudePidLookup(sessionsDir);
+    expect(await lookup.pidForThread("thread-a")).toBe(12345);
+    expect(await lookup.pidForThread("thread-b")).toBe(67890);
+  });
+
+  it("returns null for unknown threadId", async () => {
+    writeSession(12345, "thread-a");
+    const lookup = createClaudePidLookup(sessionsDir);
+    expect(await lookup.pidForThread("thread-missing")).toBeNull();
+  });
+
+  it("returns null when sessions dir is missing", async () => {
+    const lookup = createClaudePidLookup(join(tmpDir, "does-not-exist"));
+    expect(await lookup.pidForThread("thread-a")).toBeNull();
+  });
+
+  it("skips invalid session JSON files", async () => {
+    writeFileSync(join(sessionsDir, "bad.json"), "not json");
+    writeSession(12345, "thread-a");
+    const lookup = createClaudePidLookup(sessionsDir);
+    expect(await lookup.pidForThread("thread-a")).toBe(12345);
+  });
+
+  it("isAlive returns true for current process pid", () => {
+    const lookup = createClaudePidLookup(sessionsDir);
+    expect(lookup.isAlive(process.pid)).toBe(true);
+  });
+
+  it("isAlive returns false for pid 999999999", () => {
+    const lookup = createClaudePidLookup(sessionsDir);
+    expect(lookup.isAlive(999_999_999)).toBe(false);
+  });
+
+  it("invalidate clears the cache so new sessions are picked up", async () => {
+    const lookup = createClaudePidLookup(sessionsDir);
+    // Prime cache with empty result
+    expect(await lookup.pidForThread("thread-a")).toBeNull();
+    writeSession(12345, "thread-a");
+    // Still null because cache is stale
+    expect(await lookup.pidForThread("thread-a")).toBeNull();
+    lookup.invalidate();
+    expect(await lookup.pidForThread("thread-a")).toBe(12345);
+  });
+});

package/packages/agentboard/packages/runtime/src/agents/watchers/claude-pid.ts

@@ -0,0 +1,57 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ClaudePidLookup {
+  pidForThread(threadId: string): Promise<number | null>;
+  isAlive(pid: number): boolean;
+  invalidate(): void;
+}
+
+const DEFAULT_SESSIONS_DIR = join(homedir(), ".claude", "sessions");
+
+export function createClaudePidLookup(sessionsDir: string = DEFAULT_SESSIONS_DIR): ClaudePidLookup {
+  let cache: Map<string, number> | null = null;
+
+  async function loadCache(): Promise<Map<string, number>> {
+    const map = new Map<string, number>();
+    let files: string[];
+    try {
+      files = await readdir(sessionsDir);
+    } catch {
+      return map;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const text = await readFile(join(sessionsDir, file), "utf-8");
+        const data = JSON.parse(text) as { pid?: number; sessionId?: string };
+        if (typeof data.pid === "number" && typeof data.sessionId === "string") {
+          map.set(data.sessionId, data.pid);
+        }
+      } catch {
+        // skip unreadable / invalid JSON
+      }
+    }
+    return map;
+  }
+
+  return {
+    async pidForThread(threadId) {
+      if (!cache) cache = await loadCache();
+      return cache.get(threadId) ?? null;
+    },
+    isAlive(pid) {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    invalidate() {
+      cache = null;
+    },
+  };
+}

package/packages/agentboard/packages/runtime/src/agents/watchers/claude-usage.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "bun:test";
+import { contextMax, contextUsed, cacheTtlMs, extractUsageSummary } from "./claude-usage";
+
+describe("contextMax", () => {
+  it("returns 1M for sonnet with [1m] suffix", () => {
+    expect(contextMax("claude-sonnet-4-5[1m]")).toBe(1_000_000);
+  });
+
+  it("returns 200K for opus", () => {
+    expect(contextMax("claude-opus-4-6")).toBe(200_000);
+  });
+
+  it("returns 200K for haiku", () => {
+    expect(contextMax("claude-haiku-4-5")).toBe(200_000);
+  });
+
+  it("returns 200K for empty or unknown model", () => {
+    expect(contextMax("")).toBe(200_000);
+    expect(contextMax("gpt-4")).toBe(200_000);
+  });
+});
+
+describe("contextUsed", () => {
+  it("sums input + output + cache_read + cache_creation", () => {
+    expect(
+      contextUsed({
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 1000,
+        cache_creation_input_tokens: 200,
+      }),
+    ).toBe(1350);
+  });
+
+  it("treats missing fields as 0", () => {
+    expect(contextUsed({ input_tokens: 10 })).toBe(10);
+    expect(contextUsed({})).toBe(0);
+  });
+
+  it("treats null cache fields as 0", () => {
+    expect(
+      contextUsed({
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: null,
+        cache_creation_input_tokens: null,
+      }),
+    ).toBe(15);
+  });
+});
+
+describe("cacheTtlMs", () => {
+  it("returns null when no cache activity", () => {
+    expect(cacheTtlMs({ input_tokens: 100, output_tokens: 50 })).toBeNull();
+  });
+
+  it("returns 1h when ephemeral_1h_input_tokens > 0", () => {
+    expect(
+      cacheTtlMs({
+        cache_creation: { ephemeral_1h_input_tokens: 100, ephemeral_5m_input_tokens: 0 },
+      }),
+    ).toBe(60 * 60 * 1000);
+  });
+
+  it("returns 5m when only 5m tokens", () => {
+    expect(
+      cacheTtlMs({
+        cache_creation: { ephemeral_1h_input_tokens: 0, ephemeral_5m_input_tokens: 100 },
+      }),
+    ).toBe(5 * 60 * 1000);
+  });
+
+  it("returns 5m when only cache_read (no creation this turn)", () => {
+    expect(cacheTtlMs({ cache_read_input_tokens: 500 })).toBe(5 * 60 * 1000);
+  });
+
+  it("prefers 1h when both present", () => {
+    expect(
+      cacheTtlMs({
+        cache_creation: { ephemeral_1h_input_tokens: 50, ephemeral_5m_input_tokens: 100 },
+      }),
+    ).toBe(60 * 60 * 1000);
+  });
+});
+
+describe("extractUsageSummary", () => {
+  const assistantEntry = (timestamp: string, model: string, usage: unknown) => ({
+    type: "assistant",
+    timestamp,
+    message: { role: "assistant", model, usage },
+  });
+
+  it("returns null for empty entries", () => {
+    expect(extractUsageSummary([])).toBeNull();
+  });
+
+  it("returns null when no assistant entry has usage", () => {
+    expect(
+      extractUsageSummary([
+        {
+          type: "user",
+          timestamp: "2026-04-12T00:00:00Z",
+          message: { role: "user", content: "hi" },
+        } as never,
+      ]),
+    ).toBeNull();
+  });
+
+  it("extracts fields from most recent assistant entry with usage", () => {
+    const entries = [
+      assistantEntry("2026-04-12T00:00:00Z", "claude-opus-4-6", {
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      }),
+      assistantEntry("2026-04-12T00:05:00Z", "claude-opus-4-6", {
+        input_tokens: 1,
+        output_tokens: 249,
+        cache_read_input_tokens: 50612,
+        cache_creation_input_tokens: 2297,
+        cache_creation: { ephemeral_1h_input_tokens: 2297, ephemeral_5m_input_tokens: 0 },
+      }),
+    ] as never[];
+
+    const result = extractUsageSummary(entries);
+    expect(result).not.toBeNull();
+    expect(result!.model).toBe("claude-opus-4-6");
+    expect(result!.contextUsed).toBe(53159);
+    expect(result!.contextMax).toBe(200_000);
+    expect(result!.cacheTtlMs).toBe(60 * 60 * 1000);
+    expect(result!.lastActivityAt).toBe(new Date("2026-04-12T00:05:00Z").getTime());
+    expect(result!.cacheExpiresAt).toBe(result!.lastActivityAt + 60 * 60 * 1000);
+  });
+
+  it("leaves cacheExpiresAt and cacheTtlMs null when no cache activity", () => {
+    const entries = [
+      assistantEntry("2026-04-12T00:00:00Z", "claude-opus-4-6", {
+        input_tokens: 100,
+        output_tokens: 50,
+      }),
+    ] as never[];
+
+    const result = extractUsageSummary(entries);
+    expect(result!.cacheExpiresAt).toBeNull();
+    expect(result!.cacheTtlMs).toBeNull();
+  });
+});

package/packages/agentboard/packages/runtime/src/agents/watchers/claude-usage.ts

@@ -0,0 +1,78 @@
+import type { Usage } from "@anthropic-ai/sdk/resources/messages/messages";
+
+type PartialUsage = Partial<Usage> & {
+  cache_creation?: {
+    ephemeral_5m_input_tokens?: number;
+    ephemeral_1h_input_tokens?: number;
+  } | null;
+};
+
+interface AssistantLikeEntry {
+  type?: string;
+  timestamp?: string;
+  message?: {
+    role?: string;
+    model?: string;
+    usage?: PartialUsage | null;
+  };
+}
+
+export interface ClaudeUsageSummary {
+  model: string;
+  contextUsed: number;
+  contextMax: number;
+  cacheTtlMs: number | null;
+  cacheExpiresAt: number | null;
+  lastActivityAt: number;
+}
+
+const FIVE_MIN_MS = 5 * 60 * 1000;
+const ONE_HOUR_MS = 60 * 60 * 1000;
+
+export function contextMax(model: string): number {
+  if (/\[1m\]$/i.test(model)) return 1_000_000;
+  return 200_000;
+}
+
+export function contextUsed(u: PartialUsage): number {
+  return (
+    (u.input_tokens ?? 0) +
+    (u.output_tokens ?? 0) +
+    (u.cache_read_input_tokens ?? 0) +
+    (u.cache_creation_input_tokens ?? 0)
+  );
+}
+
+export function cacheTtlMs(u: PartialUsage): number | null {
+  const c = u.cache_creation ?? null;
+  const h = c?.ephemeral_1h_input_tokens ?? 0;
+  const m = c?.ephemeral_5m_input_tokens ?? 0;
+  const reads = u.cache_read_input_tokens ?? 0;
+  if (h > 0) return ONE_HOUR_MS;
+  if (m > 0 || reads > 0) return FIVE_MIN_MS;
+  return null;
+}
+
+export function extractUsageSummary(entries: AssistantLikeEntry[]): ClaudeUsageSummary | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i]!;
+    if (e.message?.role !== "assistant") continue;
+    const usage = e.message.usage;
+    if (!usage) continue;
+
+    const model = e.message.model ?? "";
+    const ts = e.timestamp ? Date.parse(e.timestamp) : Number.NaN;
+    if (Number.isNaN(ts)) continue;
+
+    const ttl = cacheTtlMs(usage);
+    return {
+      model,
+      contextUsed: contextUsed(usage),
+      contextMax: contextMax(model),
+      cacheTtlMs: ttl,
+      cacheExpiresAt: ttl === null ? null : ts + ttl,
+      lastActivityAt: ts,
+    };
+  }
+  return null;
+}