@eventmodelers/node-kit 0.0.2

package/templates/realtime-agent/src/index.js

@@ -0,0 +1,152 @@
+import { createClient } from '@supabase/supabase-js';
+import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { randomUUID } from 'crypto';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function loadLocalConfig() {
+  const configPath = resolve(__dirname, '../../.eventmodelers/config.json');
+  const raw = readFileSync(configPath, 'utf-8');
+  const cfg = JSON.parse(raw);
+
+  for (const key of ['token', 'orgId', 'boardId', 'baseUrl']) {
+    if (!cfg[key]) throw new Error(`Missing config field: ${key}`);
+  }
+
+  if (process.env.BASE_URL) cfg.baseUrl = process.env.BASE_URL;
+
+  return cfg;
+}
+
+async function fetchPlatformConfig(local) {
+  const res = await fetch(`${local.baseUrl}/api/config`, {
+    headers: { 'x-token': local.token },
+  });
+  if (!res.ok) throw new Error(`Failed to fetch platform config: ${res.status} / ${res.statusText} / ${await res.text()}`);
+  const remote = await res.json();
+  return { ...local, ...remote };
+}
+
+async function getRealtimeToken(cfg) {
+  const res = await fetch(`${cfg.baseUrl}/api/prompts/realtime-token`, {
+    headers: { 'x-token': cfg.token },
+  });
+  if (!res.ok) throw new Error(`Failed to get realtime token: ${res.status} / ${res.statusText} / ${await res.text()}`);
+  const { token } = await res.json();
+  return token;
+}
+
+async function fetchAndPersistSlices(cfg, cwd) {
+  const url = `${cfg.baseUrl}/api/org/${cfg.orgId}/boards/${cfg.boardId}/slicedata/slices`;
+  const res = await fetch(url, {
+    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId },
+  });
+  if (!res.ok) {
+    console.error(`[agent] Failed to fetch slices: ${res.status} ${res.statusText}`);
+    return;
+  }
+
+  const { slices } = await res.json();
+
+  const slicesDir = join(cwd, 'slices');
+  mkdirSync(slicesDir, { recursive: true });
+
+  for (const slice of slices) {
+    const filePath = join(slicesDir, `${slice.id}.json`);
+    writeFileSync(filePath, JSON.stringify(slice, null, 2), 'utf-8');
+  }
+
+  console.log(`[agent] Persisted ${slices.length} slice(s) to ${slicesDir}`);
+}
+
+async function writeTask(payload, cwd) {
+  const tasksPath = resolve(cwd, 'tasks.json');
+
+  const existing = existsSync(tasksPath)
+    ? JSON.parse(readFileSync(tasksPath, 'utf-8'))
+    : [];
+
+  const task = {
+    id: randomUUID(),
+    createdAt: new Date().toISOString(),
+    payload,
+  };
+
+  existing.push(task);
+  writeFileSync(tasksPath, JSON.stringify(existing, null, 2), 'utf-8');
+  console.log(`[agent] Task ${task.id} written — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+}
+
+async function start() {
+  const claudeCwd = process.argv[2] ?? resolve(process.cwd(), '..');
+
+  const local = loadLocalConfig();
+  const cfg = await fetchPlatformConfig(local);
+
+  console.log(`[agent] Starting — org=${cfg.orgId}, board=${cfg.boardId}, base=${cfg.baseUrl}, cwd=${claudeCwd}`);
+
+  let realtimeToken = await getRealtimeToken(cfg);
+
+  await fetchAndPersistSlices(cfg, claudeCwd).catch((err) =>
+    console.error('[agent] Initial slice fetch error:', err),
+  );
+
+  const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
+    realtime: { params: { apikey: cfg.supabaseAnonKey } },
+  });
+
+  await supabase.realtime.setAuth(realtimeToken);
+
+  const channelName = `board:${cfg.boardId}-slicechanged`;
+
+  supabase
+    .channel(channelName, { config: { private: true } })
+    .on('broadcast', { event: 'slice:changed' }, async (msg) => {
+      const payload = msg.payload;
+      console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+
+      await fetchAndPersistSlices(cfg, claudeCwd).catch((err) =>
+        console.error('[agent] Slice persist error:', err),
+      );
+
+      await writeTask(payload, claudeCwd).catch((err) =>
+        console.error('[agent] writeTask error:', err),
+      );
+    })
+    .subscribe((status) => {
+      console.log(`[agent] Realtime channel "${channelName}" status: ${status}`);
+    });
+
+  setInterval(async () => {
+    try {
+      realtimeToken = await getRealtimeToken(cfg);
+      supabase.realtime.setAuth(realtimeToken);
+      console.log('[agent] Realtime token refreshed');
+    } catch (err) {
+      console.error('[agent] Token refresh failed:', err);
+    }
+  }, 50 * 60 * 1000);
+
+  const ping = async () => {
+    try {
+      const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: cfg.token }),
+      });
+      if (!res.ok) console.error(`[agent] Ping failed: ${res.status}`);
+    } catch (err) {
+      console.error('[agent] Ping error:', err);
+    }
+  };
+
+  await ping();
+  setInterval(ping, 10 * 1000);
+}
+
+start().catch((err) => {
+  console.error('[agent] Fatal:', err);
+  process.exit(1);
+});

package/templates/root/AGENT.md

@@ -0,0 +1,37 @@
+# Agent Learnings
+
+Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+
+## tasks.json
+
+- Tasks are objects with `id`, `createdAt`, and `payload` (a `SliceChangedPayload`).
+- After completing a task, remove it from the array entirely — do not add a status field.
+- Write `[]` to `tasks.json` if the last task is completed.
+
+## SliceChangedPayload fields
+
+```
+event           always "slice:changed"
+organizationId  org UUID or null
+boardId         board UUID
+sliceId         SLICE_BORDER node UUID — use this with /load-slice
+sliceTitle      human-readable slice name (may be null)
+sliceStatus     e.g. "Created", "InProgress", "Done", "Blocked" (may be null)
+timestamp       unix ms when the change was emitted
+```
+
+## Slice files
+
+The realtime agent writes `slices/<sliceId>.json` for every slice on startup and after each `slice:changed` event. These files are always up to date — read them directly before invoking any skill.
+
+## Skill Usage
+
+- Always run `/connect` first to load credentials from `.eventmodelers/config.json` before calling any other skill.
+- `/load-slice sliceId=<uuid>` re-fetches all slices from the API, refreshes `slices/*.json`, and returns the requested slice. Use it when you need a guaranteed-fresh view of a specific slice.
+- Read `slices/<sliceId>.json` directly when you already know the ID and the file is recent enough.
+
+## Board API
+
+- The `boardId` and `organizationId` from each payload provide full context — pass them to skills.
+- Node events use `node:created`, `node:changed`, `node:deleted` — always POST to `/api/org/:orgId/boards/:boardId/nodes/events`.
+- Slice metadata (title, status) lives on the SLICE_BORDER node under `meta.sliceStatus` and `meta.title`.

package/templates/root/model.md

@@ -0,0 +1 @@
+claude

package/templates/root/prompt.md

@@ -0,0 +1,91 @@
+# Agent Task Instructions
+
+You are an autonomous agent reacting to slice status change events on an Eventmodelers board.
+
+## Your Loop
+
+1. Read `AGENT.md` to load accumulated learnings before doing anything else.
+2. Read `tasks.json` in the current directory.
+3. If `tasks.json` is empty or missing, reply with:
+   <promise>IDLE</promise>
+   and stop.
+4. Pick the **oldest task** (earliest `createdAt`).
+5. Execute the task — see the Execution section below.
+6. After execution, remove that task from the array and write `tasks.json` back.
+7. Append a progress entry to `progress.txt` (create if missing).
+8. Update `AGENT.md` with any new reusable learnings discovered this iteration.
+9. Reply normally so the next iteration can pick up the next task.
+
+## Execution
+
+Each task has a single `payload` of type `SliceChangedPayload`:
+
+```
+{
+  event:          "slice:changed"
+  organizationId: string | null
+  boardId:        string
+  sliceId:        string   ← SLICE_BORDER node UUID
+  sliceTitle:     string | null
+  sliceStatus:    string | null   ← e.g. "InProgress", "Done", "Blocked"
+  timestamp:      number
+}
+```
+
+### Step 1 — Load credentials
+
+Run `/connect` to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from `.eventmodelers/config.json`.
+
+### Step 2 — Load the slice
+
+Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title, status, raw node record).
+
+### Step 3 — Act on the change
+
+Inspect the `sliceStatus` in the payload and take appropriate action based on its value. Common responses:
+
+| Status | Example response |
+|--------|-----------------|
+| `InProgress` | Fetch the slice details and log that work has started |
+| `Done` | Summarize what was completed and update `progress.txt` |
+| `Blocked` | Log the blocker and note it in `progress.txt` |
+| `Review` | Fetch slice details and prepare a summary for review |
+| Any other | Load the slice and log the state transition |
+
+Use the skills available in `.claude/skills/` to interact with the board if needed.
+
+## Updating tasks.json
+
+After completing a task, remove it from the array and write the updated array back to `tasks.json`. If the array is now empty, write `[]`.
+
+## Progress Report Format
+
+APPEND to `progress.txt` (never replace):
+```
+## [ISO timestamp] — Task [task.id]
+
+Slice: [sliceTitle] ([sliceId])
+Status change: [sliceStatus]
+
+Action taken:
+- [what was done in response to the slice change]
+
+Learnings:
+- [any patterns, gotchas, or reusable knowledge discovered]
+---
+```
+
+## Stop Condition
+
+If `tasks.json` is empty (`[]`) or does not exist, reply with:
+<promise>IDLE</promise>
+
+## Updating AGENT.md
+
+After completing a task, add any **reusable** learnings to `AGENT.md` — patterns, gotchas, API quirks, or skill behaviour that future iterations should know. Only add things that are general and applicable beyond this single task. Do not duplicate what is already there.
+
+## Important
+
+- Process **one task per iteration**.
+- Read `AGENT.md` first — it contains patterns from previous iterations.
+- Always start with `/connect` if credentials are not yet loaded.

package/templates/root/ralph.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Eventmodelers agent loop — processes tasks.json indefinitely
+# Usage: ./ralph.sh [project_dir]
+#   project_dir defaults to the directory containing this script (the project root)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="${1:-"$SCRIPT_DIR"}"
+TASKS_FILE="$PROJECT_DIR/tasks.json"
+PROMPT_FILE="$PROJECT_DIR/prompt.md"
+MODEL_FILE="$PROJECT_DIR/model.md"
+
+if [[ ! -f "$PROJECT_DIR/.eventmodelers/config.json" ]]; then
+  echo "ERROR: No .eventmodelers/config.json found in $PROJECT_DIR"
+  exit 1
+fi
+
+if [[ ! -f "$MODEL_FILE" ]]; then
+  echo "ERROR: No model.md found in $PROJECT_DIR"
+  exit 1
+fi
+
+CLAUDE_CMD=$(head -1 "$MODEL_FILE" | tr -d '\r\n')
+
+echo "Starting agent loop — project: $PROJECT_DIR"
+echo "Using command: $CLAUDE_CMD"
+
+# ------------------------------------------------------------
+# Main loop — runs indefinitely
+# ------------------------------------------------------------
+while true; do
+  # ---- Run Claude in the project root --------------------
+  while true; do
+    (cd "$PROJECT_DIR" && $CLAUDE_CMD "$(cat "$PROMPT_FILE")") 2>&1
+    EXIT_CODE=$?
+    if [[ $EXIT_CODE -eq 0 ]]; then
+      break
+    else
+      echo
+      echo "Claude exited with an error. Waiting 1 minute before retry..."
+      sleep 60
+    fi
+  done
+
+  sleep 2
+done