@versdotsh/reef 0.1.2

package/examples/services/usage/behaviors.ts

@@ -0,0 +1,166 @@
+/**
+ * Usage behaviors — accumulate tokens/cost across turns, post session summary,
+ * track VM lifecycle, publish agent_stopped to feed with cost data.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+
+export function registerBehaviors(pi: ExtensionAPI, client: FleetClient) {
+  let sessionId = "";
+  let model = "";
+  let startedAt = "";
+  let turns = 0;
+  let tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+  let cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+  let toolCalls: Record<string, number> = {};
+
+  function reset() {
+    startedAt = new Date().toISOString();
+    turns = 0;
+    tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    toolCalls = {};
+  }
+
+  pi.on("agent_start", async (_event, ctx) => {
+    reset();
+    sessionId = ctx.sessionManager.getSessionId();
+    model = ctx.model?.id || "unknown";
+  });
+
+  pi.on("turn_end", async (event, ctx) => {
+    turns++;
+    model = ctx.model?.id || model;
+
+    const msg = event.message as any;
+    if (msg?.role === "assistant" && msg?.usage) {
+      const u = msg.usage;
+      tokens.input += u.input || 0;
+      tokens.output += u.output || 0;
+      tokens.cacheRead += u.cacheRead || 0;
+      tokens.cacheWrite += u.cacheWrite || 0;
+      tokens.total += u.totalTokens || 0;
+
+      if (u.cost) {
+        cost.input += u.cost.input || 0;
+        cost.output += u.cost.output || 0;
+        cost.cacheRead += u.cost.cacheRead || 0;
+        cost.cacheWrite += u.cost.cacheWrite || 0;
+        cost.total += u.cost.total || 0;
+      }
+
+      // Live token update to feed
+      if (client.getBaseUrl()) {
+        const tokensThisTurn = (u.input || 0) + (u.output || 0);
+        client.api("POST", "/feed/events", {
+          type: "token_update",
+          agent: client.agentName,
+          summary: `${tokensThisTurn} tokens`,
+          detail: JSON.stringify({
+            agent: client.agentName,
+            tokensThisTurn,
+            totalTokens: tokens.total,
+            inputTokens: u.input || 0,
+            outputTokens: u.output || 0,
+            timestamp: Date.now(),
+          }),
+        }).catch(() => {});
+      }
+    }
+  });
+
+  // Count tool calls
+  pi.on("tool_result", async (event) => {
+    const name = event.toolName;
+    toolCalls[name] = (toolCalls[name] || 0) + 1;
+
+    // Track VM lifecycle from vers tool results
+    if (!client.getBaseUrl() || event.isError) return;
+
+    try {
+      const text = event.content
+        ?.filter((c: any) => c.type === "text")
+        .map((c: any) => c.text)
+        .join("");
+
+      if (name === "vers_vm_create" || name === "vers_vm_restore") {
+        const vmIdMatch = text?.match(/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})/);
+        if (vmIdMatch) {
+          await client.api("POST", "/usage/vms", {
+            vmId: vmIdMatch[1],
+            role: (event.input as any)?.role || "worker",
+            agent: client.agentName,
+            commitId: (event.input as any)?.commitId,
+            createdAt: new Date().toISOString(),
+          });
+        }
+      } else if (name === "vers_vm_delete") {
+        const vmId = (event.input as any)?.vmId || text?.match(/([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})/)?.[1];
+        if (vmId) {
+          await client.api("POST", "/usage/vms", {
+            vmId, role: "worker", agent: client.agentName,
+            createdAt: new Date().toISOString(),
+            destroyedAt: new Date().toISOString(),
+          });
+        }
+      } else if (name === "vers_vm_commit") {
+        const inputVmId = (event.input as any)?.vmId;
+        if (inputVmId) {
+          const commitMatch = text?.match(/"commitId"\s*:\s*"([^"]+)"/);
+          await client.api("POST", "/usage/vms", {
+            vmId: inputVmId, role: "golden", agent: client.agentName,
+            commitId: commitMatch?.[1],
+            createdAt: new Date().toISOString(),
+          });
+        }
+      }
+    } catch {
+      // best-effort
+    }
+  });
+
+  // Post session summary + agent_stopped event on agent end
+  pi.on("agent_end", async () => {
+    if (!client.getBaseUrl()) return;
+
+    const endedAt = new Date().toISOString();
+
+    // Post session usage
+    try {
+      const roundedCost = {
+        input: Math.round(cost.input * 1e6) / 1e6,
+        output: Math.round(cost.output * 1e6) / 1e6,
+        cacheRead: Math.round(cost.cacheRead * 1e6) / 1e6,
+        cacheWrite: Math.round(cost.cacheWrite * 1e6) / 1e6,
+        total: Math.round(cost.total * 1e6) / 1e6,
+      };
+      await client.api("POST", "/usage/sessions", {
+        sessionId: sessionId || `session-${Date.now()}`,
+        agent: client.agentName,
+        parentAgent: process.env.VERS_PARENT_AGENT || null,
+        model,
+        tokens: { ...tokens },
+        cost: roundedCost,
+        turns,
+        toolCalls: { ...toolCalls },
+        startedAt: startedAt || endedAt,
+        endedAt,
+      });
+    } catch {
+      // best-effort
+    }
+
+    // Publish agent_stopped with cost data to feed
+    try {
+      const costStr = (Math.round(cost.total * 100) / 100).toFixed(2);
+      await client.api("POST", "/feed/events", {
+        agent: client.agentName,
+        type: "agent_stopped",
+        summary: `Agent ${client.agentName} finished (${turns} turns, ${tokens.total} tokens, $${costStr})`,
+      });
+    } catch {
+      // best-effort
+    }
+  });
+}

package/examples/services/usage/index.ts

@@ -0,0 +1,19 @@
+import type { ServiceModule } from "../src/core/types.js";
+import { UsageStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+import { registerTools } from "./tools.js";
+import { registerBehaviors } from "./behaviors.js";
+
+const store = new UsageStore();
+
+const usage: ServiceModule = {
+  name: "usage",
+  description: "Cost & token tracking",
+  routes: createRoutes(store),
+  store: { close: () => { store.close(); return Promise.resolve(); } },
+  registerTools,
+  registerBehaviors,
+  dependencies: ["feed"], // publishes agent_stopped to feed
+};
+
+export default usage;

package/examples/services/usage/routes.ts

@@ -0,0 +1,53 @@
+import { Hono } from "hono";
+import type { UsageStore } from "./store.js";
+import { ValidationError } from "./store.js";
+
+export function createRoutes(store: UsageStore): Hono {
+  const routes = new Hono();
+
+  routes.get("/", (c) => {
+    const range = c.req.query("range") || "7d";
+    return c.json(store.summary(range));
+  });
+
+  routes.post("/sessions", async (c) => {
+    try {
+      const body = await c.req.json();
+      const record = store.recordSession(body);
+      return c.json(record, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/sessions", (c) => {
+    const sessions = store.listSessions({
+      agent: c.req.query("agent") || undefined,
+      range: c.req.query("range") || undefined,
+    });
+    return c.json({ sessions, count: sessions.length });
+  });
+
+  routes.post("/vms", async (c) => {
+    try {
+      const body = await c.req.json();
+      const record = store.recordVM(body);
+      return c.json(record, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/vms", (c) => {
+    const vms = store.listVMs({
+      role: c.req.query("role") || undefined,
+      agent: c.req.query("agent") || undefined,
+      range: c.req.query("range") || undefined,
+    });
+    return c.json({ vms, count: vms.length });
+  });
+
+  return routes;
+}

package/examples/services/usage/store.ts

@@ -0,0 +1,341 @@
+/**
+ * Usage store — token/cost tracking. Uses Bun's built-in SQLite.
+ */
+
+import { ulid } from "ulid";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// --- Types ---
+
+export interface TokenCounts {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
+export interface CostBreakdown {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
+export interface SessionRecord {
+  id: string;
+  sessionId: string;
+  agent: string;
+  parentAgent: string | null;
+  model: string;
+  tokens: TokenCounts;
+  cost: CostBreakdown;
+  turns: number;
+  toolCalls: Record<string, number>;
+  startedAt: string;
+  endedAt: string;
+  recordedAt: string;
+}
+
+export interface SessionInput {
+  sessionId: string;
+  agent: string;
+  parentAgent?: string | null;
+  model: string;
+  tokens: TokenCounts;
+  cost: CostBreakdown;
+  turns: number;
+  toolCalls?: Record<string, number>;
+  startedAt: string;
+  endedAt: string;
+}
+
+export interface VMRecord {
+  id: string;
+  vmId: string;
+  role: string;
+  agent: string;
+  commitId?: string;
+  createdAt: string;
+  destroyedAt?: string;
+  recordedAt: string;
+}
+
+export interface VMInput {
+  vmId: string;
+  role: string;
+  agent: string;
+  commitId?: string;
+  createdAt: string;
+  destroyedAt?: string;
+}
+
+export interface AgentUsage {
+  tokens: number;
+  cost: number;
+  sessions: number;
+}
+
+export interface UsageSummary {
+  range: string;
+  totals: { tokens: number; cost: number; sessions: number; vms: number };
+  byAgent: Record<string, AgentUsage>;
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) { super(message); this.name = "ValidationError"; }
+}
+
+function parseDurationMs(duration: string): number | null {
+  const match = duration.match(/^(\d+)(h|d)$/);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  if (unit === "h") return value * 3600_000;
+  if (unit === "d") return value * 86400_000;
+  return null;
+}
+
+// --- Store ---
+
+export class UsageStore {
+  private db: Database;
+
+  constructor(dbPath = "data/usage.sqlite") {
+    const dir = dirname(dbPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    this.db = new Database(dbPath);
+    this.db.exec("PRAGMA journal_mode=WAL");
+    this.initTables();
+  }
+
+  private initTables(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        agent TEXT NOT NULL,
+        parent_agent TEXT,
+        model TEXT NOT NULL,
+        tokens_input INTEGER NOT NULL,
+        tokens_output INTEGER NOT NULL,
+        tokens_cache_read INTEGER NOT NULL,
+        tokens_cache_write INTEGER NOT NULL,
+        tokens_total INTEGER NOT NULL,
+        cost_input REAL NOT NULL,
+        cost_output REAL NOT NULL,
+        cost_cache_read REAL NOT NULL,
+        cost_cache_write REAL NOT NULL,
+        cost_total REAL NOT NULL,
+        turns INTEGER NOT NULL,
+        tool_calls TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        ended_at TEXT NOT NULL,
+        recorded_at TEXT NOT NULL
+      )
+    `);
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS vm_records (
+        id TEXT PRIMARY KEY,
+        vm_id TEXT NOT NULL,
+        role TEXT NOT NULL,
+        agent TEXT NOT NULL,
+        commit_id TEXT,
+        created_at TEXT NOT NULL,
+        destroyed_at TEXT,
+        recorded_at TEXT NOT NULL
+      )
+    `);
+  }
+
+  recordSession(input: SessionInput): SessionRecord {
+    if (!input.sessionId?.trim()) throw new ValidationError("sessionId is required");
+    if (!input.agent?.trim()) throw new ValidationError("agent is required");
+    if (!input.model?.trim()) throw new ValidationError("model is required");
+    if (typeof input.turns !== "number" || input.turns < 0) throw new ValidationError("turns must be non-negative");
+    if (!input.startedAt) throw new ValidationError("startedAt is required");
+    if (!input.endedAt) throw new ValidationError("endedAt is required");
+
+    const id = ulid();
+    const now = new Date().toISOString();
+    const toolCalls = input.toolCalls || {};
+
+    this.db.run(
+      `INSERT INTO sessions VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id, input.sessionId.trim(), input.agent.trim(),
+        input.parentAgent?.trim() || null, input.model.trim(),
+        input.tokens.input, input.tokens.output, input.tokens.cacheRead,
+        input.tokens.cacheWrite, input.tokens.total,
+        input.cost.input, input.cost.output, input.cost.cacheRead,
+        input.cost.cacheWrite, input.cost.total,
+        input.turns, JSON.stringify(toolCalls),
+        input.startedAt, input.endedAt, now,
+      ],
+    );
+
+    return {
+      id, sessionId: input.sessionId.trim(), agent: input.agent.trim(),
+      parentAgent: input.parentAgent?.trim() || null, model: input.model.trim(),
+      tokens: input.tokens, cost: input.cost, turns: input.turns,
+      toolCalls, startedAt: input.startedAt, endedAt: input.endedAt, recordedAt: now,
+    };
+  }
+
+  listSessions(filters?: { agent?: string; range?: string }): SessionRecord[] {
+    let sql = "SELECT * FROM sessions";
+    const conditions: string[] = [];
+    const params: any[] = [];
+
+    if (filters?.agent) {
+      conditions.push("agent = ?");
+      params.push(filters.agent);
+    }
+    if (filters?.range) {
+      const ms = parseDurationMs(filters.range);
+      if (ms !== null) {
+        conditions.push("started_at >= ?");
+        params.push(new Date(Date.now() - ms).toISOString());
+      }
+    }
+
+    if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
+    sql += " ORDER BY started_at DESC";
+
+    return this.db.query(sql).all(...params).map(rowToSession);
+  }
+
+  recordVM(input: VMInput): VMRecord {
+    if (!input.vmId?.trim()) throw new ValidationError("vmId is required");
+    if (!input.agent?.trim()) throw new ValidationError("agent is required");
+    if (!input.createdAt) throw new ValidationError("createdAt is required");
+
+    // Check for destroy update
+    if (input.destroyedAt) {
+      const existing = this.db.query(
+        "SELECT * FROM vm_records WHERE vm_id = ? ORDER BY recorded_at DESC LIMIT 1"
+      ).get(input.vmId.trim()) as any;
+
+      if (existing) {
+        this.db.run("UPDATE vm_records SET destroyed_at = ? WHERE id = ?", [input.destroyedAt, existing.id]);
+        const updated = rowToVM(existing);
+        updated.destroyedAt = input.destroyedAt;
+        return updated;
+      }
+    }
+
+    const id = ulid();
+    const now = new Date().toISOString();
+
+    this.db.run(
+      "INSERT INTO vm_records VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      [id, input.vmId.trim(), input.role || "worker", input.agent.trim(),
+       input.commitId?.trim() || null, input.createdAt, input.destroyedAt || null, now],
+    );
+
+    return {
+      id, vmId: input.vmId.trim(), role: input.role || "worker",
+      agent: input.agent.trim(), commitId: input.commitId?.trim(),
+      createdAt: input.createdAt, destroyedAt: input.destroyedAt, recordedAt: now,
+    };
+  }
+
+  listVMs(filters?: { role?: string; agent?: string; range?: string }): VMRecord[] {
+    let sql = "SELECT * FROM vm_records";
+    const conditions: string[] = [];
+    const params: any[] = [];
+
+    if (filters?.role) { conditions.push("role = ?"); params.push(filters.role); }
+    if (filters?.agent) { conditions.push("agent = ?"); params.push(filters.agent); }
+    if (filters?.range) {
+      const ms = parseDurationMs(filters.range);
+      if (ms !== null) {
+        conditions.push("created_at >= ?");
+        params.push(new Date(Date.now() - ms).toISOString());
+      }
+    }
+
+    if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
+    sql += " ORDER BY created_at DESC";
+
+    return this.db.query(sql).all(...params).map(rowToVM);
+  }
+
+  summary(range = "7d"): UsageSummary {
+    const ms = parseDurationMs(range);
+    const cutoff = ms !== null ? new Date(Date.now() - ms).toISOString() : new Date(0).toISOString();
+
+    const agentRows = this.db.query(`
+      SELECT agent, SUM(tokens_total) as tokens, ROUND(SUM(cost_total), 2) as cost, COUNT(*) as sessions
+      FROM sessions WHERE started_at >= ? GROUP BY agent ORDER BY cost DESC
+    `).all(cutoff) as any[];
+
+    const totalRow = this.db.query(`
+      SELECT COALESCE(SUM(tokens_total), 0) as tokens, ROUND(COALESCE(SUM(cost_total), 0), 2) as cost, COUNT(*) as sessions
+      FROM sessions WHERE started_at >= ?
+    `).get(cutoff) as any;
+
+    const vmRow = this.db.query(
+      "SELECT COUNT(*) as vms FROM vm_records WHERE created_at >= ?"
+    ).get(cutoff) as any;
+
+    const byAgent: Record<string, AgentUsage> = {};
+    for (const row of agentRows) {
+      byAgent[row.agent] = {
+        tokens: Number(row.tokens),
+        cost: Number(row.cost),
+        sessions: Number(row.sessions),
+      };
+    }
+
+    return {
+      range,
+      totals: {
+        tokens: Number(totalRow?.tokens || 0),
+        cost: Number(totalRow?.cost || 0),
+        sessions: Number(totalRow?.sessions || 0),
+        vms: Number(vmRow?.vms || 0),
+      },
+      byAgent,
+    };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+function rowToSession(row: any): SessionRecord {
+  return {
+    id: row.id, sessionId: row.session_id, agent: row.agent,
+    parentAgent: row.parent_agent || null, model: row.model,
+    tokens: {
+      input: row.tokens_input, output: row.tokens_output,
+      cacheRead: row.tokens_cache_read, cacheWrite: row.tokens_cache_write,
+      total: row.tokens_total,
+    },
+    cost: {
+      input: row.cost_input, output: row.cost_output,
+      cacheRead: row.cost_cache_read, cacheWrite: row.cost_cache_write,
+      total: row.cost_total,
+    },
+    turns: row.turns,
+    toolCalls: JSON.parse(row.tool_calls || "{}"),
+    startedAt: row.started_at, endedAt: row.ended_at, recordedAt: row.recorded_at,
+  };
+}
+
+function rowToVM(row: any): VMRecord {
+  const record: VMRecord = {
+    id: row.id, vmId: row.vm_id, role: row.role, agent: row.agent,
+    createdAt: row.created_at, recordedAt: row.recorded_at,
+  };
+  if (row.commit_id) record.commitId = row.commit_id;
+  if (row.destroyed_at) record.destroyedAt = row.destroyed_at;
+  return record;
+}

package/examples/services/usage/tools.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "usage_summary",
+    label: "Usage: Summary",
+    description: "Get cost & token usage summary across the agent fleet.",
+    parameters: Type.Object({
+      range: Type.Optional(Type.String({ description: 'Time range, e.g. "7d", "30d", "24h" (default: "7d")' })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.range) qs.set("range", params.range);
+        const query = qs.toString();
+        const result = await client.api("GET", `/usage${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "usage_sessions",
+    label: "Usage: Sessions",
+    description: "List session usage records — tokens, cost, turns, tool calls per session.",
+    parameters: Type.Object({
+      agent: Type.Optional(Type.String({ description: "Filter by agent name" })),
+      range: Type.Optional(Type.String({ description: 'Time range, e.g. "7d", "30d", "24h"' })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.agent) qs.set("agent", params.agent);
+        if (params.range) qs.set("range", params.range);
+        const query = qs.toString();
+        const result = await client.api("GET", `/usage/sessions${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "usage_vms",
+    label: "Usage: VMs",
+    description: "List VM lifecycle records — creation, commit, destruction events.",
+    parameters: Type.Object({
+      role: Type.Optional(StringEnum(["orchestrator", "lieutenant", "worker", "infra", "golden"] as const)),
+      agent: Type.Optional(Type.String({ description: "Filter by agent name" })),
+      range: Type.Optional(Type.String({ description: 'Time range, e.g. "7d", "30d", "24h"' })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.role) qs.set("role", params.role);
+        if (params.agent) qs.set("agent", params.agent);
+        if (params.range) qs.set("range", params.range);
+        const query = qs.toString();
+        const result = await client.api("GET", `/usage/vms${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}