@versdotsh/reef 0.1.2

package/examples/services/feed/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Feed service module — activity event stream for coordination and observability.
+ *
+ * Listens to server-side events from other modules and auto-publishes
+ * them as feed events:
+ *   board:task_created  → feed event "task_started"
+ *   board:task_updated  → feed event "task_completed" (if status=done)
+ *   board:task_deleted  → (ignored)
+ */
+
+import type { ServiceModule, ServiceContext, FleetClient } from "../src/core/types.js";
+import { FeedStore } from "./store.js";
+import { createRoutes } from "./routes.js";
+import { registerTools } from "./tools.js";
+import { registerBehaviors } from "./behaviors.js";
+
+const store = new FeedStore();
+
+const feed: ServiceModule = {
+  name: "feed",
+  description: "Activity event stream",
+  routes: createRoutes(store),
+  registerTools,
+  registerBehaviors,
+
+  routeDocs: {
+    "POST /events": {
+      summary: "Publish an event to the feed",
+      body: {
+        agent: { type: "string", required: true, description: "Agent name that produced the event" },
+        type: { type: "string", required: true, description: "task_started | task_completed | task_failed | blocker_found | question | finding | skill_proposed | file_changed | cost_update | agent_started | agent_stopped | token_update | custom" },
+        summary: { type: "string", required: true, description: "Short human-readable summary" },
+        detail: { type: "string", description: "Longer detail or structured JSON string" },
+        metadata: { type: "object", description: "Arbitrary key-value metadata" },
+      },
+      response: "The created event with generated ID and timestamp",
+    },
+    "GET /events": {
+      summary: "List recent events with optional filters",
+      query: {
+        agent: { type: "string", description: "Filter by agent name" },
+        type: { type: "string", description: "Filter by event type" },
+        since: { type: "string", description: "ULID or ISO timestamp — return events after this point" },
+        limit: { type: "number", description: "Max events to return. Default: 50" },
+      },
+      response: "Array of feed events, most recent last",
+    },
+    "GET /events/:id": {
+      summary: "Get a single event by ID",
+      params: { id: { type: "string", required: true, description: "Event ID (ULID)" } },
+    },
+    "DELETE /events": {
+      summary: "Clear all events",
+      detail: "Destructive — removes all events from memory and disk. Use with caution.",
+      response: "{ ok: true }",
+    },
+    "GET /stats": {
+      summary: "Get feed statistics",
+      response: "{ total, byAgent: { [name]: count }, byType: { [type]: count }, latestPerAgent: { [name]: Event } }",
+    },
+    "GET /stream": {
+      summary: "Server-Sent Events stream of new events in real time",
+      detail: "Connect with EventSource. Pass ?since=<ulid> to replay missed events on reconnect. Pass ?agent=<name> to filter by agent. Sends heartbeat comments every 15s.",
+      query: {
+        agent: { type: "string", description: "Filter to events from this agent only" },
+        since: { type: "string", description: "ULID — replay events since this ID before streaming" },
+      },
+      response: "SSE stream. Each message data is a JSON-encoded FeedEvent.",
+    },
+  },
+
+  init(ctx: ServiceContext) {
+    ctx.events.on("board:task_created", (data: any) => {
+      const task = data.task;
+      store.publish({
+        agent: task.createdBy || "unknown",
+        type: "task_started",
+        summary: `Task created: ${task.title}`,
+        metadata: { taskId: task.id, status: task.status },
+      });
+    });
+
+    ctx.events.on("board:task_updated", (data: any) => {
+      const task = data.task;
+      const changes = data.changes || {};
+
+      if (changes.status === "done") {
+        store.publish({
+          agent: task.assignee || task.createdBy || "unknown",
+          type: "task_completed",
+          summary: `Task completed: ${task.title}`,
+          metadata: { taskId: task.id },
+        });
+      } else if (changes.status === "blocked") {
+        store.publish({
+          agent: task.assignee || task.createdBy || "unknown",
+          type: "blocker_found",
+          summary: `Task blocked: ${task.title}`,
+          metadata: { taskId: task.id },
+        });
+      }
+    });
+  },
+
+  widget: {
+    async getLines(client: FleetClient) {
+      try {
+        const stats = await client.api<{ total: number }>("GET", "/feed/stats");
+        return [`Feed: ${stats.total} events`];
+      } catch {
+        return [];
+      }
+    },
+  },
+};
+
+export default feed;

package/examples/services/feed/routes.ts

@@ -0,0 +1,224 @@
+/**
+ * Feed HTTP routes — event publishing, listing, SSE streaming.
+ */
+
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import type { FeedStore, PublishInput, FeedEvent } from "./store.js";
+import { VALID_EVENT_TYPES } from "./store.js";
+
+export function createRoutes(store: FeedStore): Hono {
+  const routes = new Hono();
+
+  // Publish an event
+  routes.post("/events", async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+
+    const input = body as Record<string, unknown>;
+    if (!input.agent || typeof input.agent !== "string") {
+      return c.json({ error: "Missing or invalid 'agent' field" }, 400);
+    }
+    if (!input.type || !VALID_EVENT_TYPES.has(input.type as string)) {
+      return c.json(
+        { error: `Invalid 'type'. Must be one of: ${[...VALID_EVENT_TYPES].join(", ")}` },
+        400,
+      );
+    }
+    if (!input.summary || typeof input.summary !== "string") {
+      return c.json({ error: "Missing or invalid 'summary' field" }, 400);
+    }
+
+    const event = store.publish({
+      agent: input.agent as string,
+      type: input.type as PublishInput["type"],
+      summary: input.summary as string,
+      detail: input.detail as string | undefined,
+      metadata: input.metadata as Record<string, unknown> | undefined,
+    });
+    return c.json(event, 201);
+  });
+
+  // List events
+  routes.get("/events", (c) => {
+    const agent = c.req.query("agent");
+    const type = c.req.query("type");
+    const since = c.req.query("since");
+    const limitStr = c.req.query("limit");
+    const limit = limitStr ? parseInt(limitStr, 10) : 50;
+
+    const events = store.list({ agent: agent || undefined, type: type || undefined, since: since || undefined, limit });
+    return c.json(events);
+  });
+
+  // Get a single event
+  routes.get("/events/:id", (c) => {
+    const event = store.get(c.req.param("id"));
+    if (!event) return c.json({ error: "Event not found" }, 404);
+    return c.json(event);
+  });
+
+  // Clear all events
+  routes.delete("/events", (c) => {
+    store.clear();
+    return c.json({ ok: true });
+  });
+
+  // Stats
+  routes.get("/stats", (c) => c.json(store.stats()));
+
+  // SSE stream
+  routes.get("/stream", (c) => {
+    const agent = c.req.query("agent") || undefined;
+    const sinceId = c.req.query("since");
+
+    return streamSSE(c, async (stream) => {
+      // Replay missed events on reconnect
+      if (sinceId) {
+        const missed = store.eventsSince(sinceId, agent);
+        for (const event of missed) {
+          await stream.writeSSE({ data: JSON.stringify(event) });
+        }
+      }
+
+      const unsubscribe = store.subscribe((event: FeedEvent) => {
+        if (agent && event.agent !== agent) return;
+        stream.writeSSE({ data: JSON.stringify(event) }).catch(() => {});
+      });
+
+      const heartbeat = setInterval(() => {
+        stream.write(": heartbeat\n\n").catch(() => {});
+      }, 15000);
+
+      stream.onAbort(() => {
+        unsubscribe();
+        clearInterval(heartbeat);
+      });
+
+      await new Promise<void>((resolve) => {
+        stream.onAbort(() => resolve());
+      });
+
+      unsubscribe();
+      clearInterval(heartbeat);
+    });
+  });
+
+  // ─── UI Panel ───
+
+  routes.get("/_panel", (c) => {
+    return c.html(`
+<style>
+.panel-feed { height: 100%; overflow-y: auto; }
+.panel-feed .event {
+  padding: 8px 16px; border-bottom: 1px solid var(--border, #2a2a2a);
+  font-size: 12px; animation: feedFadeIn 0.2s;
+}
+@keyframes feedFadeIn { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; } }
+.panel-feed .ev-header { display: flex; gap: 8px; align-items: center; margin-bottom: 2px; }
+.panel-feed .ev-agent { color: var(--purple, #a7f); font-weight: 500; }
+.panel-feed .ev-type {
+  font-size: 10px; padding: 1px 6px; border-radius: 3px; font-weight: 600;
+  background: #333; color: var(--text, #ccc);
+}
+.panel-feed .ev-time { color: var(--text-dim, #666); font-size: 10px; margin-left: auto; }
+.panel-feed .ev-summary { color: var(--text, #ccc); }
+.panel-feed .empty { color: var(--text-dim, #666); font-style: italic; padding: 20px; text-align: center; }
+.panel-feed .live-dot {
+  display: inline-block; width: 6px; height: 6px; border-radius: 50%;
+  background: var(--accent, #4f9); margin-right: 6px; animation: feedPulse 2s infinite;
+}
+@keyframes feedPulse { 0%,100% { opacity: 1; } 50% { opacity: 0.3; } }
+.panel-feed .feed-header {
+  padding: 8px 16px; border-bottom: 1px solid var(--border, #2a2a2a);
+  font-size: 11px; color: var(--text-dim, #666); background: var(--bg-panel, #111);
+  position: sticky; top: 0; z-index: 1;
+}
+</style>
+
+<div class="panel-feed" id="feed-root">
+  <div class="feed-header"><span class="live-dot"></span>Live feed</div>
+  <div id="feed-events"><div class="empty">Loading…</div></div>
+</div>
+
+<script>
+(function() {
+  const container = document.getElementById('feed-events');
+  const API = typeof PANEL_API !== 'undefined' ? PANEL_API : '/ui/api';
+
+  function esc(s) { const d = document.createElement('div'); d.textContent = s || ''; return d.innerHTML; }
+  function ago(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    if (ms < 60000) return Math.floor(ms/1000) + 's ago';
+    if (ms < 3600000) return Math.floor(ms/60000) + 'm ago';
+    return Math.floor(ms/3600000) + 'h ago';
+  }
+
+  function renderEvent(evt) {
+    const el = document.createElement('div');
+    el.className = 'event';
+    el.innerHTML = '<div class="ev-header">'
+      + '<span class="ev-agent">' + esc(evt.agent) + '</span>'
+      + '<span class="ev-type">' + esc(evt.type) + '</span>'
+      + '<span class="ev-time">' + (evt.timestamp ? ago(evt.timestamp) : '') + '</span>'
+      + '</div><div class="ev-summary">' + esc(evt.summary) + '</div>';
+    return el;
+  }
+
+  async function loadInitial() {
+    try {
+      const res = await fetch(API + '/feed/events?limit=100');
+      if (!res.ok) throw new Error(res.status);
+      const data = await res.json();
+      const events = Array.isArray(data) ? data : (data.events || []);
+      events.reverse();
+      container.innerHTML = '';
+      events.forEach(e => container.appendChild(renderEvent(e)));
+      if (!events.length) container.innerHTML = '<div class="empty">No events yet</div>';
+    } catch (e) {
+      container.innerHTML = '<div class="empty">Feed unavailable: ' + esc(e.message) + '</div>';
+    }
+  }
+
+  // SSE for live updates
+  function startSSE() {
+    fetch(API + '/feed/stream').then(res => {
+      if (!res.ok) return;
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      let buf = '';
+      (async function read() {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          const lines = buf.split('\\n');
+          buf = lines.pop() || '';
+          for (const line of lines) {
+            if (line.startsWith('data: ')) {
+              try {
+                const evt = JSON.parse(line.slice(6));
+                const empty = container.querySelector('.empty');
+                if (empty) empty.remove();
+                container.prepend(renderEvent(evt));
+              } catch {}
+            }
+          }
+        }
+      })().catch(() => setTimeout(startSSE, 5000));
+    }).catch(() => setTimeout(startSSE, 5000));
+  }
+
+  loadInitial();
+  startSSE();
+})();
+</script>
+`);
+  });
+
+  return routes;
+}

package/examples/services/feed/store.ts

@@ -0,0 +1,194 @@
+/**
+ * Feed store — append-only event stream with in-memory index and pub/sub.
+ */
+
+import { ulid } from "ulid";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type FeedEventType =
+  | "task_started"
+  | "task_completed"
+  | "task_failed"
+  | "blocker_found"
+  | "question"
+  | "finding"
+  | "skill_proposed"
+  | "file_changed"
+  | "cost_update"
+  | "agent_started"
+  | "agent_stopped"
+  | "token_update"
+  | "custom";
+
+export const VALID_EVENT_TYPES = new Set<string>([
+  "task_started",
+  "task_completed",
+  "task_failed",
+  "blocker_found",
+  "question",
+  "finding",
+  "skill_proposed",
+  "file_changed",
+  "cost_update",
+  "agent_started",
+  "agent_stopped",
+  "token_update",
+  "custom",
+]);
+
+export interface FeedEvent {
+  id: string;
+  agent: string;
+  type: FeedEventType;
+  summary: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+  timestamp: string;
+}
+
+export interface PublishInput {
+  agent: string;
+  type: FeedEventType;
+  summary: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface FilterOptions {
+  agent?: string;
+  type?: string;
+  since?: string;
+  limit?: number;
+}
+
+type Subscriber = (event: FeedEvent) => void;
+
+// =============================================================================
+// Store
+// =============================================================================
+
+export class FeedStore {
+  private events: FeedEvent[] = [];
+  private subscribers = new Set<Subscriber>();
+  private filePath: string;
+  private maxInMemory: number;
+
+  constructor(filePath = "data/feed.jsonl", maxInMemory = 10000) {
+    this.filePath = filePath;
+    this.maxInMemory = maxInMemory;
+    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.events.push(JSON.parse(line));
+      } catch {
+        // skip malformed
+      }
+    }
+
+    if (this.events.length > this.maxInMemory) {
+      this.events = this.events.slice(-this.maxInMemory);
+    }
+  }
+
+  publish(input: PublishInput): FeedEvent {
+    const event: FeedEvent = {
+      id: ulid(),
+      agent: input.agent,
+      type: input.type,
+      summary: input.summary,
+      timestamp: new Date().toISOString(),
+    };
+    if (input.detail !== undefined) event.detail = input.detail;
+    if (input.metadata !== undefined) event.metadata = input.metadata;
+
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(this.filePath, JSON.stringify(event) + "\n");
+
+    this.events.push(event);
+    if (this.events.length > this.maxInMemory) {
+      this.events = this.events.slice(-this.maxInMemory);
+    }
+
+    for (const sub of this.subscribers) {
+      try { sub(event); } catch { /* ignore */ }
+    }
+
+    return event;
+  }
+
+  get(id: string): FeedEvent | undefined {
+    return this.events.find((e) => e.id === id);
+  }
+
+  list(opts: FilterOptions = {}): FeedEvent[] {
+    let result = this.events;
+
+    if (opts.agent) result = result.filter((e) => e.agent === opts.agent);
+    if (opts.type) result = result.filter((e) => e.type === opts.type);
+
+    if (opts.since) {
+      const since = opts.since;
+      if (/^[0-9A-Z]{26}$/i.test(since)) {
+        result = result.filter((e) => e.id > since);
+      } else {
+        const sinceTime = new Date(since).getTime();
+        result = result.filter((e) => new Date(e.timestamp).getTime() > sinceTime);
+      }
+    }
+
+    const limit = opts.limit ?? 50;
+    if (limit > 0) result = result.slice(-limit);
+
+    return result;
+  }
+
+  subscribe(fn: Subscriber): () => void {
+    this.subscribers.add(fn);
+    return () => { this.subscribers.delete(fn); };
+  }
+
+  eventsSince(sinceId: string, agent?: string): FeedEvent[] {
+    let result = this.events.filter((e) => e.id > sinceId);
+    if (agent) result = result.filter((e) => e.agent === agent);
+    return result;
+  }
+
+  stats() {
+    const byAgent: Record<string, number> = {};
+    const byType: Record<string, number> = {};
+    const latestPerAgent: Record<string, FeedEvent> = {};
+
+    for (const event of this.events) {
+      byAgent[event.agent] = (byAgent[event.agent] || 0) + 1;
+      byType[event.type] = (byType[event.type] || 0) + 1;
+      latestPerAgent[event.agent] = event;
+    }
+
+    return { total: this.events.length, byAgent, byType, latestPerAgent };
+  }
+
+  clear(): void {
+    this.events = [];
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.filePath, "");
+  }
+
+  get size(): number {
+    return this.events.length;
+  }
+}

package/examples/services/feed/tools.ts

@@ -0,0 +1,83 @@
+/**
+ * Feed tools — publish events, list events, get stats.
+ */
+
+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: "feed_publish",
+    label: "Feed: Publish Event",
+    description:
+      "Publish an event to the activity feed. Used for coordination, progress reporting, and audit trails.",
+    parameters: Type.Object({
+      type: StringEnum(
+        [
+          "task_started", "task_completed", "task_failed",
+          "blocker_found", "question", "finding",
+          "skill_proposed", "file_changed", "cost_update",
+          "agent_started", "agent_stopped", "custom",
+        ] as const,
+        { description: "Event type" },
+      ),
+      summary: Type.String({ description: "Short human-readable summary" }),
+      detail: Type.Optional(Type.String({ description: "Longer detail or structured data" })),
+    }),
+    async execute(_id, params) {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const event = await client.api("POST", "/feed/events", {
+          ...params,
+          agent: client.agentName,
+        });
+        return client.ok(JSON.stringify(event, null, 2), { event });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "feed_list",
+    label: "Feed: List Events",
+    description: "List recent activity feed events. Optionally filter by agent, type, or limit.",
+    parameters: Type.Object({
+      agent: Type.Optional(Type.String({ description: "Filter by agent name" })),
+      type: Type.Optional(Type.String({ description: "Filter by event type" })),
+      limit: Type.Optional(Type.Number({ description: "Max events to return (default 50)" })),
+    }),
+    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.type) qs.set("type", params.type);
+        if (params.limit) qs.set("limit", String(params.limit));
+        const query = qs.toString();
+        const result = await client.api("GET", `/feed/events${query ? `?${query}` : ""}`);
+        return client.ok(JSON.stringify(result, null, 2), { result });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "feed_stats",
+    label: "Feed: Stats",
+    description: "Get summary statistics of the activity feed.",
+    parameters: Type.Object({}),
+    async execute() {
+      if (!client.getBaseUrl()) return client.noUrl();
+      try {
+        const stats = await client.api("GET", "/feed/stats");
+        return client.ok(JSON.stringify(stats, null, 2), { stats });
+      } catch (e: any) {
+        return client.err(e.message);
+      }
+    },
+  });
+}

package/examples/services/journal/index.ts

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

package/examples/services/journal/journal.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { createTestHarness, type TestHarness } from "../../../src/core/testing.js";
+import journal from "./index.js";
+
+let t: TestHarness;
+const setup = (async () => {
+  t = await createTestHarness({ services: [journal] });
+})();
+afterAll(() => t?.cleanup());
+
+describe("journal", () => {
+  test("writes an entry", async () => {
+    await setup;
+    const { status, data } = await t.json("/journal", {
+      method: "POST",
+      auth: true,
+      body: { text: "Feeling good about progress", author: "agent-1", mood: "optimistic" },
+    });
+    expect(status).toBe(201);
+    expect(data.text).toBe("Feeling good about progress");
+    expect(data.mood).toBe("optimistic");
+    expect(data.timestamp).toBeDefined();
+  });
+
+  test("lists entries", async () => {
+    await setup;
+    const { status, data } = await t.json<{ entries: any[]; count: number }>("/journal", {
+      auth: true,
+    });
+    expect(status).toBe(200);
+    expect(data.entries.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("returns raw text format", async () => {
+    await setup;
+    const res = await t.fetch("/journal/raw", { auth: true });
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).toContain("Feeling good about progress");
+  });
+
+  test("requires text field", async () => {
+    await setup;
+    const { status } = await t.json("/journal", {
+      method: "POST",
+      auth: true,
+      body: { author: "test" },
+    });
+    expect(status).toBe(400);
+  });
+
+  test("requires auth", async () => {
+    await setup;
+    const { status } = await t.json("/journal");
+    expect(status).toBe(401);
+  });
+});