@versdotsh/reef 0.1.2

package/examples/services/board/tools.ts

@@ -0,0 +1,214 @@
+/**
+ * Board tools — registered on the pi extension so the LLM can manage tasks.
+ */
+
+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";
+
+const STATUS_ENUM = StringEnum(
+  ["open", "in_progress", "in_review", "blocked", "done"] as const,
+  { description: "Task status" },
+);
+
+const ARTIFACT_TYPE_ENUM = StringEnum(
+  ["branch", "report", "deploy", "diff", "file", "url"] as const,
+  { description: "Artifact type" },
+);
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "board_create_task",
+    label: "Board: Create Task",
+    description:
+      "Create a new task on the shared coordination board. Returns the created task with its ID.",
+    parameters: Type.Object({
+      title: Type.String({ description: "Task title" }),
+      description: Type.Optional(Type.String({ description: "Detailed task description" })),
+      assignee: Type.Optional(Type.String({ description: "Agent or user to assign to" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Tags for categorization" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api("POST", "/board/tasks", {
+          ...params,
+          createdBy: client.agentName,
+        });
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_list_tasks",
+    label: "Board: List Tasks",
+    description:
+      "List tasks on the shared board. Optionally filter by status, assignee, or tag.",
+    parameters: Type.Object({
+      status: Type.Optional(STATUS_ENUM),
+      assignee: Type.Optional(Type.String({ description: "Filter by assignee" })),
+      tag: Type.Optional(Type.String({ description: "Filter by tag" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.status) qs.set("status", params.status);
+        if (params.assignee) qs.set("assignee", params.assignee);
+        if (params.tag) qs.set("tag", params.tag);
+        const query = qs.toString();
+        const result = await client.api("GET", `/board/tasks${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_update_task",
+    label: "Board: Update Task",
+    description:
+      "Update a task — change status, reassign, rename, or update tags.",
+    parameters: Type.Object({
+      id: Type.String({ description: "Task ID to update" }),
+      status: Type.Optional(STATUS_ENUM),
+      assignee: Type.Optional(Type.String({ description: "New assignee" })),
+      title: Type.Optional(Type.String({ description: "New title" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "New tags" })),
+    }),
+    async execute(_toolCallId, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const { id, ...updates } = params;
+        const task = await client.api("PATCH", `/board/tasks/${encodeURIComponent(id)}`, updates);
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_add_note",
+    label: "Board: Add Note",
+    description:
+      "Add a note to a task — findings, blockers, questions, or status updates.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to add the note to" }),
+      content: Type.String({ description: "Note content" }),
+      type: StringEnum(["finding", "blocker", "question", "update"] as const, {
+        description: "Note type",
+      }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const { taskId, ...body } = params;
+        const note = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(taskId)}/notes`,
+          { ...body, author: client.agentName },
+        );
+        return client.ok(JSON.stringify(note, null, 2), { note });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_submit_for_review",
+    label: "Board: Submit for Review",
+    description:
+      "Submit a task for review — sets status to in_review, adds a summary note, and optionally attaches artifacts.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to submit for review" }),
+      summary: Type.String({ description: "Review summary describing what was done" }),
+      artifacts: Type.Optional(
+        Type.Array(
+          Type.Object({
+            type: ARTIFACT_TYPE_ENUM,
+            url: Type.String({ description: "URL or path to the artifact" }),
+            label: Type.String({ description: "Human-readable label" }),
+          }),
+          { description: "Artifacts to attach" },
+        ),
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const body: Record<string, unknown> = {
+          summary: params.summary,
+          reviewedBy: client.agentName,
+        };
+        if (params.artifacts) body.artifacts = params.artifacts;
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/review`,
+          body,
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_add_artifact",
+    label: "Board: Add Artifact",
+    description:
+      "Add artifact link(s) to any task — branches, reports, deploys, diffs, files, or URLs.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID" }),
+      artifacts: Type.Array(
+        Type.Object({
+          type: ARTIFACT_TYPE_ENUM,
+          url: Type.String({ description: "URL or path" }),
+          label: Type.String({ description: "Human-readable label" }),
+        }),
+        { description: "Artifacts to attach" },
+      ),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/artifacts`,
+          { artifacts: params.artifacts.map((a) => ({ ...a, addedBy: client.agentName })) },
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "board_bump",
+    label: "Board: Bump Task",
+    description: "Bump a task's score by 1. Use to signal priority or upvote.",
+    parameters: Type.Object({
+      taskId: Type.String({ description: "Task ID to bump" }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const task = await client.api(
+          "POST",
+          `/board/tasks/${encodeURIComponent(params.taskId)}/bump`,
+        );
+        return client.ok(JSON.stringify(task, null, 2), { task });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}

package/examples/services/commits/commits.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import commits from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [commits] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("commits", () => {
+  test("records a commit", async () => {
+    await setup;
+    const { status, data } = await t.json("/commits", {
+      method: "POST",
+      auth: true,
+      body: {
+        commitId: "commit-abc",
+        vmId: "vm-001",
+        label: "golden-v1",
+        agent: "coordinator",
+      },
+    });
+    expect(status).toBe(201);
+    expect(data.commitId).toBe("commit-abc");
+    expect(data.vmId).toBe("vm-001");
+  });
+
+  test("lists commits", async () => {
+    await setup;
+    const { status, data } = await t.json<{ commits: any[]; count: number }>("/commits", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.commits.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("gets a commit by commitId", async () => {
+    await setup;
+    await t.json("/commits", {
+      method: "POST",
+      auth: true,
+      body: { commitId: "commit-get", vmId: "vm-002", agent: "test" },
+    });
+
+    const { status, data } = await t.json("/commits/commit-get", { auth: true });
+    expect(status).toBe(200);
+    expect(data.commitId).toBe("commit-get");
+  });
+
+  test("deletes a commit by commitId", async () => {
+    await setup;
+    await t.json("/commits", {
+      method: "POST",
+      auth: true,
+      body: { commitId: "commit-del", vmId: "vm-003", agent: "test" },
+    });
+
+    const { status } = await t.json("/commits/commit-del", {
+      method: "DELETE",
+      auth: true,
+    });
+    expect(status).toBe(200);
+
+    const { status: getStatus } = await t.json("/commits/commit-del", { auth: true });
+    expect(getStatus).toBe(404);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/commits");
+    expect(status).toBe(401);
+  });
+});

package/examples/services/commits/index.ts

@@ -0,0 +1,14 @@
+import type { ServiceModule } from "../src/core/types.js";
+import { CommitStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+
+const store = new CommitStore();
+
+const commits: ServiceModule = {
+  name: "commits",
+  description: "VM snapshot ledger",
+  routes: createRoutes(store),
+  store: { close: () => { store.close(); return Promise.resolve(); } },
+};
+
+export default commits;

package/examples/services/commits/routes.ts

@@ -0,0 +1,43 @@
+import { Hono } from "hono";
+import type { CommitStore } from "./store.js";
+import { ValidationError } from "./store.js";
+
+export function createRoutes(store: CommitStore): Hono {
+  const routes = new Hono();
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const record = store.record(body);
+      return c.json(record, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/", (c) => {
+    const commits = store.list({
+      tag: c.req.query("tag") || undefined,
+      agent: c.req.query("agent") || undefined,
+      label: c.req.query("label") || undefined,
+      vmId: c.req.query("vmId") || undefined,
+      since: c.req.query("since") || undefined,
+    });
+    return c.json({ commits, count: commits.length });
+  });
+
+  routes.get("/:id", (c) => {
+    const commit = store.get(c.req.param("id"));
+    if (!commit) return c.json({ error: "commit not found" }, 404);
+    return c.json(commit);
+  });
+
+  routes.delete("/:id", (c) => {
+    const deleted = store.delete(c.req.param("id"));
+    if (!deleted) return c.json({ error: "commit not found" }, 404);
+    return c.json({ deleted: true });
+  });
+
+  return routes;
+}

package/examples/services/commits/store.ts

@@ -0,0 +1,114 @@
+/**
+ * Commits store — VM snapshot ledger. Tracks golden images, rollback points.
+ */
+
+import { ulid } from "ulid";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface CommitRecord {
+  id: string;
+  commitId: string;
+  vmId: string;
+  label?: string;
+  agent?: string;
+  tags: string[];
+  createdAt: string;
+  recordedAt: string;
+}
+
+export interface CommitInput {
+  commitId: string;
+  vmId: string;
+  label?: string;
+  agent?: string;
+  tags?: string[];
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) { super(message); this.name = "ValidationError"; }
+}
+
+export class CommitStore {
+  private db: Database;
+
+  constructor(dbPath = "data/commits.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.db.exec(`
+      CREATE TABLE IF NOT EXISTS commits (
+        id TEXT PRIMARY KEY,
+        commit_id TEXT NOT NULL UNIQUE,
+        vm_id TEXT NOT NULL,
+        label TEXT,
+        agent TEXT,
+        tags TEXT NOT NULL DEFAULT '[]',
+        created_at TEXT NOT NULL,
+        recorded_at TEXT NOT NULL
+      )
+    `);
+  }
+
+  record(input: CommitInput): CommitRecord {
+    if (!input.commitId?.trim()) throw new ValidationError("commitId is required");
+    if (!input.vmId?.trim()) throw new ValidationError("vmId is required");
+
+    const id = ulid();
+    const now = new Date().toISOString();
+    const tags = input.tags || [];
+
+    this.db.run(
+      "INSERT OR REPLACE INTO commits VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+      [id, input.commitId.trim(), input.vmId.trim(), input.label?.trim() || null,
+       input.agent?.trim() || null, JSON.stringify(tags), now, now],
+    );
+
+    return {
+      id, commitId: input.commitId.trim(), vmId: input.vmId.trim(),
+      label: input.label?.trim(), agent: input.agent?.trim(),
+      tags, createdAt: now, recordedAt: now,
+    };
+  }
+
+  get(commitId: string): CommitRecord | null {
+    const row = this.db.query("SELECT * FROM commits WHERE commit_id = ?").get(commitId) as any;
+    return row ? rowToCommit(row) : null;
+  }
+
+  list(filters?: { tag?: string; agent?: string; label?: string; vmId?: string; since?: string }): CommitRecord[] {
+    let sql = "SELECT * FROM commits";
+    const conditions: string[] = [];
+    const params: any[] = [];
+
+    if (filters?.agent) { conditions.push("agent = ?"); params.push(filters.agent); }
+    if (filters?.label) { conditions.push("label = ?"); params.push(filters.label); }
+    if (filters?.vmId) { conditions.push("vm_id = ?"); params.push(filters.vmId); }
+    if (filters?.tag) { conditions.push("tags LIKE ?"); params.push(`%"${filters.tag}"%`); }
+    if (filters?.since) { conditions.push("created_at >= ?"); params.push(filters.since); }
+
+    if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
+    sql += " ORDER BY created_at DESC";
+
+    return this.db.query(sql).all(...params).map(rowToCommit);
+  }
+
+  delete(commitId: string): boolean {
+    const result = this.db.run("DELETE FROM commits WHERE commit_id = ?", [commitId]);
+    return result.changes > 0;
+  }
+
+  close(): void { this.db.close(); }
+}
+
+function rowToCommit(row: any): CommitRecord {
+  return {
+    id: row.id, commitId: row.commit_id, vmId: row.vm_id,
+    label: row.label || undefined, agent: row.agent || undefined,
+    tags: JSON.parse(row.tags || "[]"),
+    createdAt: row.created_at, recordedAt: row.recorded_at,
+  };
+}

package/examples/services/feed/behaviors.ts

@@ -0,0 +1,23 @@
+/**
+ * Feed behaviors — auto-publish agent lifecycle events.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+
+export function registerBehaviors(pi: ExtensionAPI, client: FleetClient) {
+  pi.on("agent_start", async () => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("POST", "/feed/events", {
+        agent: client.agentName,
+        type: "agent_started",
+        summary: `Agent ${client.agentName} started processing`,
+      });
+    } catch {
+      // best-effort
+    }
+  });
+
+  // agent_end publish is handled by the usage service (it has cost data to include)
+}

package/examples/services/feed/feed.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import feed from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [feed] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("feed", () => {
+  test("publishes an event", async () => {
+    await setup;
+    const { status, data } = await t.json("/feed/events", {
+      method: "POST",
+      auth: true,
+      body: { agent: "test-agent", type: "task_started", summary: "Working on it" },
+    });
+    expect(status).toBe(201);
+    expect(data.agent).toBe("test-agent");
+    expect(data.type).toBe("task_started");
+    expect(data.id).toBeDefined();
+    expect(data.timestamp).toBeDefined();
+  });
+
+  test("lists events", async () => {
+    await setup;
+    const { status, data } = await t.json<any[]>("/feed/events", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(Array.isArray(data)).toBe(true);
+    expect(data.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("filters by agent", async () => {
+    await setup;
+    await t.json("/feed/events", {
+      method: "POST",
+      auth: true,
+      body: { agent: "filter-agent", type: "finding", summary: "Found it" },
+    });
+
+    const { data } = await t.json<any[]>("/feed/events?agent=filter-agent", {
+      auth: true,
+    });
+    for (const e of data) {
+      expect(e.agent).toBe("filter-agent");
+    }
+  });
+
+  test("filters by type", async () => {
+    await setup;
+    const { data } = await t.json<any[]>("/feed/events?type=task_started", {
+      auth: true,
+    });
+    for (const e of data) {
+      expect(e.type).toBe("task_started");
+    }
+  });
+
+  test("gets event by id", async () => {
+    await setup;
+    const { data: created } = await t.json<any>("/feed/events", {
+      method: "POST",
+      auth: true,
+      body: { agent: "test", type: "custom", summary: "Get by ID" },
+    });
+
+    const { status, data } = await t.json(`/feed/events/${created.id}`, { auth: true });
+    expect(status).toBe(200);
+    expect(data.summary).toBe("Get by ID");
+  });
+
+  test("returns stats", async () => {
+    await setup;
+    const { status, data } = await t.json<any>("/feed/stats", { auth: true });
+    expect(status).toBe(200);
+    expect(data.total).toBeGreaterThanOrEqual(1);
+  });
+
+  test("limits results", async () => {
+    await setup;
+    const { data } = await t.json<any[]>("/feed/events?limit=1", { auth: true });
+    expect(data.length).toBeLessThanOrEqual(1);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/feed/events");
+    expect(status).toBe(401);
+  });
+
+  test("panel endpoint returns HTML", async () => {
+    await setup;
+    const res = await t.fetch("/feed/_panel", { auth: true });
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("panel-feed");
+  });
+});