@versdotsh/reef 0.1.2

package/examples/services/journal/routes.ts

@@ -0,0 +1,45 @@
+import { Hono } from "hono";
+import type { JournalStore } from "./store.js";
+import { ValidationError } from "./store.js";
+
+export function createRoutes(store: JournalStore): Hono {
+  const routes = new Hono();
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const entry = store.append(body);
+      return c.json(entry, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/", (c) => {
+    const entries = store.query({
+      since: c.req.query("since") || undefined,
+      until: c.req.query("until") || undefined,
+      last: c.req.query("last") || undefined,
+      author: c.req.query("author") || undefined,
+      tag: c.req.query("tag") || undefined,
+    });
+    if (c.req.query("raw") === "true") {
+      return c.text(store.formatRaw(entries));
+    }
+    return c.json({ entries, count: entries.length });
+  });
+
+  routes.get("/raw", (c) => {
+    const entries = store.query({
+      since: c.req.query("since") || undefined,
+      until: c.req.query("until") || undefined,
+      last: c.req.query("last") || undefined,
+      author: c.req.query("author") || undefined,
+      tag: c.req.query("tag") || undefined,
+    });
+    return c.text(store.formatRaw(entries));
+  });
+
+  return routes;
+}

package/examples/services/journal/store.ts

@@ -0,0 +1,119 @@
+/**
+ * Journal store — personal narrative log. Thoughts, vibes, intuitions.
+ */
+
+import { ulid } from "ulid";
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface JournalEntry {
+  id: string;
+  timestamp: string;
+  text: string;
+  author: string;
+  mood?: string;
+  tags: string[];
+}
+
+export interface AppendInput {
+  text: string;
+  author: string;
+  mood?: string;
+  tags?: string[];
+}
+
+export interface QueryOptions {
+  since?: string;
+  until?: string;
+  last?: string;
+  author?: string;
+  tag?: string;
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) { super(message); this.name = "ValidationError"; }
+}
+
+function parseDuration(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;
+}
+
+export class JournalStore {
+  private entries: JournalEntry[] = [];
+  private filePath: string;
+
+  constructor(filePath = "data/journal.jsonl") {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    const content = readFileSync(this.filePath, "utf-8").trim();
+    if (!content) return;
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try { this.entries.push(JSON.parse(line)); } catch { /* skip */ }
+    }
+  }
+
+  append(input: AppendInput): JournalEntry {
+    if (!input.text?.trim()) throw new ValidationError("text is required");
+    if (!input.author?.trim()) throw new ValidationError("author is required");
+
+    const entry: JournalEntry = {
+      id: ulid(),
+      timestamp: new Date().toISOString(),
+      text: input.text.trim(),
+      author: input.author.trim(),
+      tags: input.tags || [],
+    };
+    if (input.mood?.trim()) entry.mood = input.mood.trim();
+
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(this.filePath, JSON.stringify(entry) + "\n");
+    this.entries.push(entry);
+    return entry;
+  }
+
+  query(opts: QueryOptions = {}): JournalEntry[] {
+    let sinceTime: number | undefined;
+    let untilTime: number | undefined;
+
+    if (opts.last) {
+      const ms = parseDuration(opts.last);
+      if (ms !== null) sinceTime = Date.now() - ms;
+    }
+    if (opts.since) sinceTime = new Date(opts.since).getTime();
+    if (opts.until) untilTime = new Date(opts.until).getTime();
+    if (sinceTime === undefined && untilTime === undefined) {
+      sinceTime = Date.now() - 86400_000;
+    }
+
+    let result = this.entries;
+    if (sinceTime !== undefined) result = result.filter((e) => new Date(e.timestamp).getTime() >= sinceTime!);
+    if (untilTime !== undefined) result = result.filter((e) => new Date(e.timestamp).getTime() <= untilTime!);
+    if (opts.author) result = result.filter((e) => e.author === opts.author);
+    if (opts.tag) result = result.filter((e) => e.tags.includes(opts.tag!));
+    return result;
+  }
+
+  formatRaw(entries: JournalEntry[]): string {
+    return entries
+      .map((e) => {
+        const mood = e.mood ? ` [${e.mood}]` : "";
+        const tags = e.tags.length ? ` #${e.tags.join(" #")}` : "";
+        return `[${e.timestamp}] (${e.author})${mood}${tags} ${e.text}`;
+      })
+      .join("\n");
+  }
+
+  get size(): number { return this.entries.length; }
+}

package/examples/services/journal/tools.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+import { Type } from "@sinclair/typebox";
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "journal_entry",
+    label: "Journal: Write Entry",
+    description:
+      "Write a personal journal entry — thoughts, vibes, product intuitions, feelings. NOT for operational tasks (use log_append for that).",
+    parameters: Type.Object({
+      text: Type.String({ description: "Journal entry text" }),
+      mood: Type.Optional(Type.String({ description: "Optional mood/vibe tag" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Optional tags" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const body: Record<string, unknown> = {
+          text: params.text,
+          author: client.agentName,
+        };
+        if (params.mood) body.mood = params.mood;
+        if (params.tags) body.tags = params.tags;
+        const entry = await client.api("POST", "/journal", body);
+        return client.ok(JSON.stringify(entry, null, 2), { entry });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}

package/examples/services/log/index.ts

@@ -0,0 +1,15 @@
+import type { ServiceModule } from "../src/core/types.js";
+import { LogStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+import { registerTools } from "./tools.js";
+
+const store = new LogStore();
+
+const log: ServiceModule = {
+  name: "log",
+  description: "Append-only work log",
+  routes: createRoutes(store),
+  registerTools,
+};
+
+export default log;

package/examples/services/log/log.test.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import log from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [log] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("log", () => {
+  test("appends an entry", async () => {
+    await setup;
+    const { status, data } = await t.json("/log", {
+      method: "POST",
+      auth: true,
+      body: { text: "Did some work", agent: "test-agent" },
+    });
+    expect(status).toBe(201);
+    expect(data.text).toBe("Did some work");
+    expect(data.agent).toBe("test-agent");
+    expect(data.timestamp).toBeDefined();
+  });
+
+  test("lists entries", async () => {
+    await setup;
+    const { status, data } = await t.json<{ entries: any[]; count: number }>("/log", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.entries.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("filters by last duration", async () => {
+    await setup;
+    const { status, data } = await t.json<{ entries: any[] }>("/log?last=1h", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    // All entries should be within the last hour
+    const oneHourAgo = Date.now() - 3600000;
+    for (const e of data.entries) {
+      expect(new Date(e.timestamp).getTime()).toBeGreaterThan(oneHourAgo);
+    }
+  });
+
+  test("returns raw text format", async () => {
+    await setup;
+    const res = await t.fetch("/log/raw", { auth: true });
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).toContain("Did some work");
+  });
+
+  test("requires text field", async () => {
+    await setup;
+    const { status } = await t.json("/log", {
+      method: "POST",
+      auth: true,
+      body: { agent: "test" },
+    });
+    expect(status).toBe(400);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/log");
+    expect(status).toBe(401);
+  });
+});

package/examples/services/log/routes.ts

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+import type { LogStore } from "./store.js";
+import { ValidationError } from "./store.js";
+
+export function createRoutes(store: LogStore): Hono {
+  const routes = new Hono();
+
+  routes.post("/", async (c) => {
+    try {
+      const body = await c.req.json();
+      const entry = store.append(body);
+      return c.json(entry, 201);
+    } catch (e) {
+      if (e instanceof ValidationError) return c.json({ error: e.message }, 400);
+      throw e;
+    }
+  });
+
+  routes.get("/", (c) => {
+    const since = c.req.query("since");
+    const until = c.req.query("until");
+    const last = c.req.query("last");
+    const entries = store.query({
+      since: since || undefined,
+      until: until || undefined,
+      last: last || undefined,
+    });
+    return c.json({ entries, count: entries.length });
+  });
+
+  routes.get("/raw", (c) => {
+    const since = c.req.query("since");
+    const until = c.req.query("until");
+    const last = c.req.query("last");
+    const entries = store.query({
+      since: since || undefined,
+      until: until || undefined,
+      last: last || undefined,
+    });
+    return c.text(store.formatRaw(entries));
+  });
+
+  return routes;
+}

package/examples/services/log/store.ts

@@ -0,0 +1,105 @@
+/**
+ * Log store — append-only work log. Carmack .plan style.
+ */
+
+import { ulid } from "ulid";
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface LogEntry {
+  id: string;
+  timestamp: string;
+  text: string;
+  agent?: string;
+}
+
+export interface AppendInput {
+  text: string;
+  agent?: string;
+}
+
+export interface QueryOptions {
+  since?: string;
+  until?: string;
+  last?: string;
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) { super(message); this.name = "ValidationError"; }
+}
+
+function parseDuration(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;
+}
+
+export class LogStore {
+  private entries: LogEntry[] = [];
+  private filePath: string;
+
+  constructor(filePath = "data/log.jsonl") {
+    this.filePath = filePath;
+    this.load();
+  }
+
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    const content = readFileSync(this.filePath, "utf-8").trim();
+    if (!content) return;
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try { this.entries.push(JSON.parse(line)); } catch { /* skip */ }
+    }
+  }
+
+  append(input: AppendInput): LogEntry {
+    if (!input.text?.trim()) throw new ValidationError("text is required");
+
+    const entry: LogEntry = {
+      id: ulid(),
+      timestamp: new Date().toISOString(),
+      text: input.text.trim(),
+    };
+    if (input.agent?.trim()) entry.agent = input.agent.trim();
+
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(this.filePath, JSON.stringify(entry) + "\n");
+    this.entries.push(entry);
+    return entry;
+  }
+
+  query(opts: QueryOptions = {}): LogEntry[] {
+    let sinceTime: number | undefined;
+    let untilTime: number | undefined;
+
+    if (opts.last) {
+      const ms = parseDuration(opts.last);
+      if (ms !== null) sinceTime = Date.now() - ms;
+    }
+    if (opts.since) sinceTime = new Date(opts.since).getTime();
+    if (opts.until) untilTime = new Date(opts.until).getTime();
+
+    if (sinceTime === undefined && untilTime === undefined) {
+      sinceTime = Date.now() - 86400_000; // default: last 24h
+    }
+
+    let result = this.entries;
+    if (sinceTime !== undefined) result = result.filter((e) => new Date(e.timestamp).getTime() >= sinceTime!);
+    if (untilTime !== undefined) result = result.filter((e) => new Date(e.timestamp).getTime() <= untilTime!);
+    return result;
+  }
+
+  formatRaw(entries: LogEntry[]): string {
+    return entries
+      .map((e) => `[${e.timestamp}]${e.agent ? ` (${e.agent})` : ""} ${e.text}`)
+      .join("\n");
+  }
+
+  get size(): number { return this.entries.length; }
+}

package/examples/services/log/tools.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+import { Type } from "@sinclair/typebox";
+
+export function registerTools(pi: ExtensionAPI, client: FleetClient) {
+  pi.registerTool({
+    name: "log_append",
+    label: "Log: Append Entry",
+    description: "Append a work log entry — timestamped, append-only. Like Carmack's .plan file.",
+    parameters: Type.Object({
+      text: Type.String({ description: "Log entry text" }),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const entry = await client.api("POST", "/log", {
+          text: params.text,
+          agent: client.agentName,
+        });
+        return client.ok(JSON.stringify(entry, null, 2), { entry });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "log_query",
+    label: "Log: Query Entries",
+    description:
+      "Query the work log. Returns timestamped entries filtered by time range. Use raw=true for plain text output.",
+    parameters: Type.Object({
+      since: Type.Optional(Type.String({ description: "Start time (ISO timestamp)" })),
+      until: Type.Optional(Type.String({ description: "End time (ISO timestamp)" })),
+      last: Type.Optional(Type.String({ description: 'Duration shorthand, e.g. "24h", "7d"' })),
+      raw: Type.Optional(Type.Boolean({ description: "Return plain text instead of JSON" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const qs = new URLSearchParams();
+        if (params.since) qs.set("since", params.since);
+        if (params.until) qs.set("until", params.until);
+        if (params.last) qs.set("last", params.last);
+        const query = qs.toString();
+        const endpoint = params.raw ? "/log/raw" : "/log";
+        const result = await client.api("GET", `${endpoint}${query ? `?${query}` : ""}`);
+        if (params.raw && typeof result === "string") {
+          return client.ok(result || "(no entries)");
+        }
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}

package/examples/services/registry/behaviors.ts

@@ -0,0 +1,128 @@
+/**
+ * Registry behaviors — auto-registration, heartbeat, lifecycle event handling.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FleetClient } from "../src/core/types.js";
+
+export function registerBehaviors(pi: ExtensionAPI, client: FleetClient) {
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  // Auto-register this VM on agent start
+  pi.on("agent_start", async () => {
+    if (!client.getBaseUrl() || !client.vmId) return;
+
+    try {
+      await client.api("POST", "/registry/vms", {
+        id: client.vmId,
+        name: client.agentName,
+        role: client.agentRole,
+        address: `${client.vmId}.vm.vers.sh`,
+        registeredBy: client.agentName,
+        metadata: { pid: process.pid, startedAt: new Date().toISOString() },
+      });
+    } catch {
+      // Might already exist — try update instead
+      try {
+        await client.api("PATCH", `/registry/vms/${client.vmId}`, {
+          name: client.agentName,
+          status: "running",
+        });
+      } catch { /* best-effort */ }
+    }
+  });
+
+  // Mark stopped on agent end
+  pi.on("agent_end", async () => {
+    if (!client.getBaseUrl() || !client.vmId) return;
+    try {
+      await client.api("PATCH", `/registry/vms/${client.vmId}`, { status: "stopped" });
+    } catch { /* best-effort */ }
+  });
+
+  // Start heartbeat timer on session start
+  pi.on("session_start", async () => {
+    if (!client.getBaseUrl() || !client.vmId) return;
+
+    heartbeatTimer = setInterval(async () => {
+      try {
+        await client.api("POST", `/registry/vms/${client.vmId}/heartbeat`);
+      } catch { /* best-effort */ }
+    }, 60_000);
+  });
+
+  // Stop heartbeat on shutdown
+  pi.on("session_shutdown", async () => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  });
+
+  // Handle swarm/lieutenant lifecycle events from other extensions
+  pi.events.on("vers:agent_spawned", async (data: {
+    vmId: string; label: string; role: string; address: string; commitId?: string;
+  }) => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("POST", "/registry/vms", {
+        id: data.vmId,
+        name: data.label,
+        role: data.role || "worker",
+        address: data.address,
+        registeredBy: "reef",
+        metadata: {
+          agentId: data.label,
+          commitId: data.commitId,
+          registeredVia: "vers:agent_spawned",
+          createdAt: new Date().toISOString(),
+        },
+      });
+    } catch (err) {
+      console.error(`[registry] Registration failed for ${data.label}: ${err instanceof Error ? err.message : err}`);
+    }
+  });
+
+  pi.events.on("vers:agent_destroyed", async (data: { vmId: string; label: string }) => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("DELETE", `/registry/vms/${encodeURIComponent(data.vmId)}`);
+    } catch (err) {
+      console.error(`[registry] Delete failed for ${data.label}: ${err instanceof Error ? err.message : err}`);
+    }
+  });
+
+  pi.events.on("vers:lt_created", async (data: {
+    vmId: string; name: string; role: string; address: string;
+    ltRole?: string; commitId?: string; createdAt?: string;
+  }) => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("POST", "/registry/vms", {
+        id: data.vmId,
+        name: data.name,
+        role: data.role || "lieutenant",
+        address: data.address,
+        registeredBy: "reef",
+        metadata: {
+          agentId: data.name,
+          role: data.ltRole,
+          commitId: data.commitId,
+          createdAt: data.createdAt,
+          registeredVia: "vers:lt_created",
+        },
+      });
+    } catch (err) {
+      console.error(`[registry] LT registration failed for ${data.name}: ${err instanceof Error ? err.message : err}`);
+    }
+  });
+
+  pi.events.on("vers:lt_destroyed", async (data: { vmId: string; name: string }) => {
+    if (!client.getBaseUrl()) return;
+    try {
+      await client.api("DELETE", `/registry/vms/${encodeURIComponent(data.vmId)}`);
+    } catch (err) {
+      console.error(`[registry] LT delete failed for ${data.name}: ${err instanceof Error ? err.message : err}`);
+    }
+  });
+}

package/examples/services/registry/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Registry service module — VM service discovery for agent fleets.
+ */
+
+import type { ServiceModule, FleetClient } from "../src/core/types.js";
+import { RegistryStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+import { registerTools } from "./tools.js";
+import { registerBehaviors } from "./behaviors.js";
+
+const store = new RegistryStore();
+
+const registry: ServiceModule = {
+  name: "registry",
+  description: "VM service discovery",
+  routes: createRoutes(store),
+  store,
+  registerTools,
+  registerBehaviors,
+
+  widget: {
+    async getLines(client: FleetClient) {
+      try {
+        const res = await client.api<{ vms: { status: string }[]; count: number }>(
+          "GET",
+          "/registry/vms",
+        );
+        const running = res.vms.filter((v) => v.status === "running").length;
+        return [`Registry: ${res.count} VMs (${running} running)`];
+      } catch {
+        return [];
+      }
+    },
+  },
+};
+
+export default registry;