@versdotsh/reef 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.1.4
+
+- Add updater service — auto-update reef from npm
+  - `GET /updater/status` — current version, latest available, update history
+  - `POST /updater/check` — check npm for newer version
+  - `POST /updater/apply` — apply update and restart
+  - Optional polling with `UPDATE_POLL_INTERVAL` (minutes)
+  - Optional auto-apply with `UPDATE_AUTO_APPLY=true`
+- 126 tests, 324 assertions
+
+## 0.1.3
+
+- Add READMEs to all example services (board, commits, feed, journal, log, registry, reports, ui, usage)
+
+## 0.1.2
+
+- Switch to npm trusted publishing via OIDC — no tokens needed
+- Scope package under `@versdotsh/reef`
+
+## 0.1.1
+
+- Add GitHub Actions CI (test & publish on push to main)
+- Add `.gitignore` for `data/` directory
+- Add test harness (`src/core/testing.ts`) — `createTestHarness()` for isolated service testing
+- Add tests for all example services (board, commits, feed, journal, log, registry, reports, usage)
+- Add UI panels section and testing section to create-service skill
+- 122 tests, 304 assertions
+
+## 0.1.0
+
+- Initial release
+- Core: dynamic dispatch server, module discovery with topo-sort, bearer token auth
+- Infrastructure services: agent, docs, installer, services manager
+- Agent service: fire-and-forget tasks via `pi -p`, interactive sessions via `pi --mode rpc`, SSE streaming
+- Installer: git clone, local symlink, fleet-to-fleet tarball install/update
+- Docs service: auto-generated API docs from `routeDocs` metadata
+- Services manager: list, reload, unload modules at runtime
+- Example services: board, commits, feed, journal, log, registry, reports, ui, usage
+- Dynamic panel system: services serve `GET /_panel` HTML fragments, UI discovers and injects them
+- UI service: web dashboard with magic link auth, API proxy, chat interface
+- Pi extension: `filterClientModules()` for client-side tool/behavior registration
+- Create-service skill for teaching agents to write new modules
+- 60 core tests

package/examples/services/board/README.md

@@ -0,0 +1,36 @@
+# board
+
+Shared task tracking for agent fleets. Tasks move through a review workflow: `open` → `in_progress` → `in_review` → `done`. Agents claim tasks, add notes and artifacts, bump priority, and submit work for review.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/board/tasks` | Create a task |
+| `GET` | `/board/tasks` | List tasks (filter: `?status=`, `?assignee=`, `?tag=`) |
+| `GET` | `/board/tasks/:id` | Get a task |
+| `PATCH` | `/board/tasks/:id` | Update a task |
+| `DELETE` | `/board/tasks/:id` | Delete a task |
+| `POST` | `/board/tasks/:id/bump` | Bump priority score |
+| `POST` | `/board/tasks/:id/notes` | Add a note |
+| `GET` | `/board/tasks/:id/notes` | List notes |
+| `POST` | `/board/tasks/:id/artifacts` | Attach an artifact |
+| `POST` | `/board/tasks/:id/review` | Submit for review |
+| `POST` | `/board/tasks/:id/approve` | Approve (sets status to `done`) |
+| `POST` | `/board/tasks/:id/reject` | Reject (sets status back to `open`) |
+| `GET` | `/board/review` | List tasks awaiting review |
+| `GET` | `/board/_panel` | UI panel (HTML fragment) |
+
+## Tools
+
+- `board_create_task` — create a task with title, description, assignee, tags
+- `board_list_tasks` — list/filter tasks
+- `board_update_task` — update status, assignee, title, tags
+- `board_add_note` — add a finding, question, or update note
+
+## Events
+
+Emits to the server-side event bus:
+- `board:task_created` — `{ task }`
+- `board:task_updated` — `{ task, changes }`
+- `board:task_deleted` — `{ taskId }`

package/examples/services/commits/README.md

@@ -0,0 +1,12 @@
+# commits
+
+VM snapshot ledger. Records which VMs were committed, when, by whom, and with what labels. Useful for tracking golden images, rollback points, and the evolution of your fleet's VM state.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/commits` | Record a commit (`{ commitId, vmId, label?, agent, tags? }`) |
+| `GET` | `/commits` | List commits (filter: `?tag=`, `?agent=`, `?label=`, `?vmId=`) |
+| `GET` | `/commits/:commitId` | Get a commit by commitId |
+| `DELETE` | `/commits/:commitId` | Delete a commit record |

package/examples/services/feed/README.md

@@ -0,0 +1,29 @@
+# feed
+
+Activity event stream for coordination and observability. Services publish events, agents and dashboards consume them. Supports SSE streaming for real-time updates.
+
+Automatically listens for server-side events from other modules:
+- `board:task_created` → feed event `task_started`
+- `board:task_updated` → feed event `task_completed` (when status becomes `done`)
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/feed/events` | Publish an event |
+| `GET` | `/feed/events` | List events (filter: `?agent=`, `?type=`, `?since=`, `?limit=`) |
+| `GET` | `/feed/events/:id` | Get an event |
+| `DELETE` | `/feed/events` | Clear all events |
+| `GET` | `/feed/stats` | Event count statistics |
+| `GET` | `/feed/stream` | SSE stream of new events |
+| `GET` | `/feed/_panel` | UI panel (HTML fragment) |
+
+## Tools
+
+- `feed_publish` — publish an event with agent, type, summary, and optional detail
+- `feed_list` — list/filter recent events
+- `feed_stats` — get summary statistics
+
+## Behaviors
+
+Auto-publishes feed events when board tasks are created or completed.

package/examples/services/journal/README.md

@@ -0,0 +1,15 @@
+# journal
+
+Personal narrative log for agents. Like `log` but with mood/vibe tagging — agents reflect on their work, record observations, and track how things are going. Useful for building agent personality and self-awareness over time.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/journal` | Write an entry (`{ text, author, mood?, tags? }`) |
+| `GET` | `/journal` | List entries |
+| `GET` | `/journal/raw` | Plain text format |
+
+## Tools
+
+- `journal_entry` — write a journal entry with optional mood and tags

package/examples/services/log/README.md

@@ -0,0 +1,16 @@
+# log
+
+Append-only work log. Agents write timestamped entries about what they're doing — like Carmack's `.plan` file. Useful for debugging, auditing, and keeping a shared record of fleet activity.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/log` | Append an entry (`{ text, agent }`) |
+| `GET` | `/log` | List entries (filter: `?last=1h`, `?last=7d`) |
+| `GET` | `/log/raw` | Plain text format |
+
+## Tools
+
+- `log_append` — append a work log entry
+- `log_query` — query entries by time range (`since`, `until`, `last`)

package/examples/services/registry/README.md

@@ -0,0 +1,26 @@
+# registry
+
+VM service discovery for agent fleets. Agents register themselves with a role, address, and capabilities. Other agents discover peers by role. Heartbeats keep registrations alive.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/registry/vms` | Register a VM |
+| `GET` | `/registry/vms` | List VMs (filter: `?role=`, `?status=`) |
+| `GET` | `/registry/vms/:id` | Get a VM |
+| `PATCH` | `/registry/vms/:id` | Update a VM |
+| `DELETE` | `/registry/vms/:id` | Deregister a VM |
+| `POST` | `/registry/vms/:id/heartbeat` | Send heartbeat |
+| `GET` | `/registry/discover/:role` | Discover VMs by role |
+
+## Tools
+
+- `registry_list` — list VMs, optionally filter by role or status
+- `registry_register` — register a VM with id, name, role, address, services
+- `registry_discover` — find VMs by role (worker, lieutenant, etc.)
+- `registry_heartbeat` — keep a registration alive
+
+## Behaviors
+
+Auto-registers and auto-heartbeats when running as part of a fleet.

package/examples/services/reports/README.md

@@ -0,0 +1,12 @@
+# reports
+
+Markdown reports. Agents write structured reports — sprint summaries, investigation findings, status updates. Stored with title, author, tags, and timestamp.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/reports` | Create a report (`{ title, content, author, tags? }`) |
+| `GET` | `/reports` | List reports |
+| `GET` | `/reports/:id` | Get a report |
+| `DELETE` | `/reports/:id` | Delete a report |

package/examples/services/ui/README.md

@@ -0,0 +1,22 @@
+# ui
+
+Web dashboard with magic link auth, dynamic panel discovery, and chat interface. Mounts at root — serves `/ui/*` and `/auth/*`.
+
+The UI discovers panels from other services at runtime. Any service that serves `GET /_panel` gets a tab in the dashboard. The chat tab connects to the agent service via SSE for streaming conversations with pi.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/auth/magic-link` | Generate a one-time login URL |
+| `GET` | `/ui/login` | Magic link landing page (sets session cookie) |
+| `GET` | `/ui/` | Dashboard shell |
+| `GET` | `/ui/static/:file` | Static assets (JS, CSS) |
+| `ALL` | `/ui/api/*` | Auth proxy — injects bearer token so the browser never needs it |
+
+## How it works
+
+1. **Auth**: `POST /auth/magic-link` with bearer token → returns a URL. Opening it sets a 24h session cookie.
+2. **Panel discovery**: The dashboard polls `GET /services` every 30s, fetches `GET /<service>/_panel` for each, and injects the HTML as tabs.
+3. **Chat**: Creates a pi RPC session via the agent service, streams responses via SSE, renders markdown with collapsible tool calls.
+4. **API proxy**: All requests to `/ui/api/*` are forwarded with the bearer token from the session, so panel scripts and chat can call any service endpoint without exposing the token to the browser.

package/examples/services/usage/README.md

@@ -0,0 +1,25 @@
+# usage
+
+Cost and token tracking for agent fleets. Records per-session token usage, cost breakdowns, and VM lifecycle events. Provides summaries by agent and time range.
+
+Depends on `feed` — publishes `agent_stopped` events when sessions end.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/usage` | Usage summary (filter: `?range=7d`) |
+| `POST` | `/usage/sessions` | Record a session |
+| `GET` | `/usage/sessions` | List sessions (filter: `?agent=`, `?range=`) |
+| `POST` | `/usage/vms` | Record a VM lifecycle event |
+| `GET` | `/usage/vms` | List VM records |
+
+## Tools
+
+- `usage_summary` — get cost & token totals by agent and time range
+- `usage_sessions` — list session records with tokens, cost, turns, tool calls
+- `usage_vms` — list VM lifecycle records
+
+## Behaviors
+
+Auto-records usage data from feed events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versdotsh/reef",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Self-improving fleet infrastructure — the minimum kernel agents need to build their own tools",
   "type": "module",
   "scripts": {

package/services/updater/README.md

@@ -0,0 +1,40 @@
+# updater
+
+Auto-update the reef server from npm. Checks for new versions of `@versdotsh/reef`, downloads updates, and restarts the process.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/updater/status` | Current version, latest available, poll config, update history |
+| `POST` | `/updater/check` | Check npm for a newer version |
+| `POST` | `/updater/apply` | Apply the update and restart the server |
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `UPDATE_POLL_INTERVAL` | `0` | Check interval in minutes (0 = manual only) |
+| `UPDATE_AUTO_APPLY` | `false` | Automatically apply updates when found |
+
+## Usage
+
+**Manual update:**
+```bash
+# Check for updates
+curl -X POST http://localhost:3000/updater/check -H "Authorization: Bearer $TOKEN"
+
+# Apply if available
+curl -X POST http://localhost:3000/updater/apply -H "Authorization: Bearer $TOKEN"
+```
+
+**Auto-update every 30 minutes:**
+```bash
+UPDATE_POLL_INTERVAL=30 UPDATE_AUTO_APPLY=true bun run start
+```
+
+## How it works
+
+1. **Check** — fetches `https://registry.npmjs.org/@versdotsh/reef/latest` and compares versions
+2. **Apply** — runs `bun update @versdotsh/reef`, then spawns a new server process and exits the current one
+3. **Poll** — if `UPDATE_POLL_INTERVAL` is set, checks on a timer; if `UPDATE_AUTO_APPLY` is also set, applies automatically

package/services/updater/index.ts

@@ -0,0 +1,289 @@
+/**
+ * Updater service module — auto-update the reef server.
+ *
+ * Checks npm for new versions of @versdotsh/reef and applies updates.
+ * Can run on a schedule (poll interval) or be triggered manually via API.
+ *
+ * Routes:
+ *   GET  /updater/status  — current version, latest available, update history
+ *   POST /updater/check   — check for updates now
+ *   POST /updater/apply   — download and apply the latest version, then restart
+ *
+ * Env vars:
+ *   UPDATE_POLL_INTERVAL — check interval in minutes (default: 0 = disabled)
+ *   UPDATE_AUTO_APPLY    — automatically apply updates when found (default: false)
+ */
+
+import { Hono } from "hono";
+import { execSync, spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ServiceModule, ServiceContext } from "../../src/core/types.js";
+
+interface UpdateRecord {
+  from: string;
+  to: string;
+  timestamp: string;
+  status: "applied" | "failed";
+  error?: string;
+}
+
+const PACKAGE_NAME = "@versdotsh/reef";
+
+let currentVersion: string = "unknown";
+let latestVersion: string | null = null;
+let lastChecked: string | null = null;
+let updateAvailable = false;
+let checking = false;
+let applying = false;
+let pollTimer: ReturnType<typeof setInterval> | null = null;
+let history: UpdateRecord[] = [];
+
+function loadCurrentVersion(): string {
+  try {
+    // Walk up from services/updater to find package.json
+    const paths = [
+      join(import.meta.dir, "..", "..", "package.json"),
+      join(process.cwd(), "package.json"),
+    ];
+    for (const p of paths) {
+      try {
+        const pkg = JSON.parse(readFileSync(p, "utf-8"));
+        if (pkg.name === PACKAGE_NAME || pkg.name === "reef") {
+          return pkg.version;
+        }
+      } catch {}
+    }
+    // Fallback: ask bun
+    const out = execSync("bun pm ls 2>/dev/null | grep reef || true", {
+      encoding: "utf-8",
+      timeout: 5000,
+    }).trim();
+    const match = out.match(/@[\d.]+/);
+    return match ? match[0].slice(1) : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+async function checkForUpdate(): Promise<{
+  current: string;
+  latest: string;
+  updateAvailable: boolean;
+}> {
+  checking = true;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10000),
+    });
+
+    if (!res.ok) {
+      throw new Error(`npm registry returned ${res.status}`);
+    }
+
+    const data = (await res.json()) as { version: string };
+    latestVersion = data.version;
+    lastChecked = new Date().toISOString();
+    updateAvailable = latestVersion !== currentVersion;
+
+    return {
+      current: currentVersion,
+      latest: latestVersion,
+      updateAvailable,
+    };
+  } finally {
+    checking = false;
+  }
+}
+
+async function applyUpdate(): Promise<UpdateRecord> {
+  if (!latestVersion || !updateAvailable) {
+    throw new Error("No update available — run check first");
+  }
+
+  applying = true;
+  const from = currentVersion;
+  const to = latestVersion;
+
+  try {
+    // Update the package
+    execSync(`bun update ${PACKAGE_NAME}`, {
+      encoding: "utf-8",
+      timeout: 60000,
+      cwd: process.cwd(),
+      stdio: "pipe",
+    });
+
+    const record: UpdateRecord = {
+      from,
+      to,
+      timestamp: new Date().toISOString(),
+      status: "applied",
+    };
+    history.push(record);
+
+    // Schedule restart — give time for the response to be sent
+    setTimeout(() => {
+      console.log(`  [updater] restarting after update ${from} → ${to}`);
+
+      // Spawn a new process with the same args, then exit
+      const child = spawn(process.argv[0], process.argv.slice(1), {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: "inherit",
+        detached: true,
+      });
+      child.unref();
+
+      // Give the child a moment to start, then exit
+      setTimeout(() => process.exit(0), 500);
+    }, 1000);
+
+    return record;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const record: UpdateRecord = {
+      from,
+      to,
+      timestamp: new Date().toISOString(),
+      status: "failed",
+      error: msg,
+    };
+    history.push(record);
+    throw new Error(`Update failed: ${msg}`);
+  } finally {
+    applying = false;
+  }
+}
+
+// Routes
+const routes = new Hono();
+
+routes.get("/status", (c) =>
+  c.json({
+    package: PACKAGE_NAME,
+    current: currentVersion,
+    latest: latestVersion,
+    updateAvailable,
+    lastChecked,
+    checking,
+    applying,
+    pollInterval: parseInt(process.env.UPDATE_POLL_INTERVAL || "0", 10),
+    autoApply: process.env.UPDATE_AUTO_APPLY === "true",
+    history,
+  }),
+);
+
+routes.post("/check", async (c) => {
+  if (checking) {
+    return c.json({ error: "Already checking" }, 409);
+  }
+
+  try {
+    const result = await checkForUpdate();
+    return c.json(result);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return c.json({ error: msg }, 502);
+  }
+});
+
+routes.post("/apply", async (c) => {
+  if (applying) {
+    return c.json({ error: "Already applying an update" }, 409);
+  }
+
+  if (!updateAvailable) {
+    // Check first
+    try {
+      await checkForUpdate();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return c.json({ error: `Check failed: ${msg}` }, 502);
+    }
+
+    if (!updateAvailable) {
+      return c.json({
+        message: "Already up to date",
+        current: currentVersion,
+      });
+    }
+  }
+
+  try {
+    const record = await applyUpdate();
+    return c.json({
+      message: `Updated ${record.from} → ${record.to} — restarting...`,
+      ...record,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return c.json({ error: msg }, 500);
+  }
+});
+
+// Module definition
+const updater: ServiceModule = {
+  name: "updater",
+  description: "Auto-update reef from npm",
+  routes,
+
+  routeDocs: {
+    "GET /status": {
+      description: "Current version, latest available, update history",
+      response: "{ package, current, latest, updateAvailable, lastChecked, checking, applying, pollInterval, autoApply, history }",
+    },
+    "POST /check": {
+      description: "Check npm for a newer version",
+      response: "{ current, latest, updateAvailable }",
+    },
+    "POST /apply": {
+      description: "Apply the latest update and restart the server",
+      response: "{ message, from, to, timestamp, status }",
+    },
+  },
+
+  init(ctx: ServiceContext) {
+    currentVersion = loadCurrentVersion();
+
+    const pollMinutes = parseInt(process.env.UPDATE_POLL_INTERVAL || "0", 10);
+    const autoApply = process.env.UPDATE_AUTO_APPLY === "true";
+
+    if (pollMinutes > 0) {
+      console.log(
+        `  [updater] polling every ${pollMinutes}m${autoApply ? " (auto-apply)" : ""}`,
+      );
+
+      pollTimer = setInterval(async () => {
+        try {
+          const result = await checkForUpdate();
+          if (result.updateAvailable) {
+            console.log(
+              `  [updater] new version available: ${result.current} → ${result.latest}`,
+            );
+            if (autoApply) {
+              console.log(`  [updater] auto-applying update...`);
+              await applyUpdate();
+            }
+          }
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.error(`  [updater] check failed: ${msg}`);
+        }
+      }, pollMinutes * 60 * 1000);
+    }
+  },
+
+  store: {
+    close() {
+      if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+      }
+      return Promise.resolve();
+    },
+  },
+};
+
+export default updater;

package/services/updater/updater.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../src/core/testing.js";
+import updater from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [updater] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("updater", () => {
+  test("returns status", async () => {
+    await setup;
+    const { status, data } = await t.json<any>("/updater/status", { auth: true });
+    expect(status).toBe(200);
+    expect(data.package).toBe("@versdotsh/reef");
+    expect(data.current).toBeDefined();
+    expect(data.updateAvailable).toBe(false);
+    expect(data.checking).toBe(false);
+    expect(data.applying).toBe(false);
+    expect(data.history).toEqual([]);
+  });
+
+  test("checks for updates from npm", async () => {
+    await setup;
+    const { status, data } = await t.json<any>("/updater/check", {
+      method: "POST",
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.current).toBeDefined();
+    expect(data.latest).toBeDefined();
+    expect(typeof data.updateAvailable).toBe("boolean");
+  });
+
+  test("apply when already up to date returns message", async () => {
+    await setup;
+    // After check, if versions match, apply should say "already up to date"
+    const { data: checkData } = await t.json<any>("/updater/check", {
+      method: "POST",
+      auth: true,
+    });
+
+    // Only test the "already up to date" path — don't actually apply
+    if (!checkData.updateAvailable) {
+      const { status, data } = await t.json<any>("/updater/apply", {
+        method: "POST",
+        auth: true,
+      });
+      expect(status).toBe(200);
+      expect(data.message).toContain("up to date");
+    }
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status: s1 } = await t.json("/updater/status");
+    expect(s1).toBe(401);
+    const { status: s2 } = await t.json("/updater/check", { method: "POST" });
+    expect(s2).toBe(401);
+    const { status: s3 } = await t.json("/updater/apply", { method: "POST" });
+    expect(s3).toBe(401);
+  });
+});