@eventmodelers/cli 2.0.44 → 2.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "2.0.44",
+  "version": "2.0.46",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/lib/ralph.js

@@ -14,7 +14,8 @@ import { execFileSync } from 'child_process';
 import { randomUUID } from 'crypto';
 import { createRealtimeAdapter, keepSubscribed } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
-import { adoptAgentEdits, observeBoard, projectStatus, statusOf } from './slice-projection.js';
+import { adoptAgentEdits, applyBoardStatus, observeBoard, projectStatus, statusOf } from './slice-projection.js';
+import { coalesce } from './slice-refresh.js';
 import { fold, statusKey } from './slice-state.js';
 import { readEvents } from './slice-events.js';
 import { claimSlice, recordEvent, settleSlice, settleLeftoverClaims } from './slice-run.js';
@@ -364,7 +365,18 @@ async function fetchFullSlice(cfg, kitDir, sliceId) {
   }
 }
 
-async function handleSliceChanged(payload, cfg, kitDir) {
+// Re-reads of the slice list caused by other people's changes: a burst of events (an import, a bulk status
+// change) becomes one read per agent instead of one per event.
+const SLICE_REFRESH_DELAY_MS = 1500;
+const refreshSlices = coalesce(fetchAndPersistSlices, SLICE_REFRESH_DELAY_MS);
+
+// A slice:changed that only moved a slice's status carries everything the local files need — the other
+// fields of the payload are the ones the write set, so all of them null means none was touched. Anything
+// else (a title, assignee, ticket or feature, or a slice not listed yet) is read from the board.
+const isStatusOnly = (payload) =>
+  !!payload?.sliceStatus && payload.sliceTitle == null && payload.assignee == null && payload.ticketNumber == null && payload.feature == null;
+
+export async function handleSliceChanged(payload, cfg, kitDir, refresh = refreshSlices) {
   console.log(`[agent] slice:changed — slice="${payload.sliceTitle ?? payload.sliceId}" status="${payload.sliceStatus}"`);
   // This agent's own status writes (claim → InProgress, → Done, → Blocked) come straight back
   // as slice:changed. Queuing them only buys a turn in which the agent reads its own echo and
@@ -376,9 +388,12 @@ async function handleSliceChanged(payload, cfg, kitDir) {
     console.log(`[agent] Own write — not queued (slice="${payload.sliceTitle ?? payload.sliceId}" status="${payload.sliceStatus}")`);
     return;
   }
-  await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
-    console.error('[agent] Slice persist error:', err),
-  );
+  const appliedLocally = isStatusOnly(payload) && applyBoardStatus(kitDir, payload.sliceId, payload.sliceStatus, eventMeta(cfg));
+  if (!appliedLocally) {
+    await refresh(cfg, kitDir).catch((err) =>
+      console.error('[agent] Slice persist error:', err),
+    );
+  }
   // Slices in the kit's pickup status (Planned, or Waiting for UI kits) are handled by
   // onPlannedSlice directly — no task needed.
   if (statusKey(payload.sliceStatus) !== statusKey(readPickupStatus(kitDir))) {
@@ -464,6 +479,12 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', createAdap
     },
   });
 
+  // A slice:changed that never arrived (a dropped message the reconnect logic cannot see) would leave the
+  // local copy stale until the next change — read the whole list now and then to catch it up.
+  setInterval(() => {
+    refreshSlices(cfg, kitDir).catch((err) => console.error(`[agent] ${ts()} Scheduled slice reconcile failed:`, err));
+  }, 10 * 60 * 1000);
+
   setInterval(() => {
     refreshToken('scheduled 10min refresh').catch((err) => console.error(`[agent] ${ts()} Scheduled token refresh failed:`, err));
   }, 10 * 60 * 1000);

package/shared/build-kit/lib/slice-projection.js

@@ -24,6 +24,42 @@ export function observeBoard(kitDir, boardSlices, meta, current = fold(readEvent
   return changed ? fold(readEvents(kitDir)) : state;
 }
 
+// The board's slice statuses as the slice list reports them (the backend's STATUS_MAP). 'Handover' is the
+// legacy name of Waiting. Undefined for anything else — the caller then reads the board instead of guessing.
+const BOARD_STATUSES = new Set(['Created', 'Ready', 'Done', 'InProgress', 'Blocked', 'Assigned', 'Review', 'Waiting', 'Planned', 'Informational']);
+export function normalizeBoardStatus(raw) {
+  if (raw === 'Handover') return 'Waiting';
+  return BOARD_STATUSES.has(raw) ? raw : undefined;
+}
+
+// Whether the slice is already in a context's index.json — a slice the agent has never listed has to be
+// fetched, because its title, type and context are not in a status event.
+function knowsSlice(kitDir, sliceId) {
+  const slicesDir = join(kitDir, '.slices');
+  if (!existsSync(slicesDir)) return false;
+  for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!ctx.isDirectory()) continue;
+    try {
+      const index = JSON.parse(readFileSync(join(slicesDir, ctx.name, 'index.json'), 'utf-8'));
+      if ((index.slices ?? []).some((e) => e.id === sliceId)) return true;
+    } catch { /* an unreadable index is left for the next full fetch to repair */ }
+  }
+  return false;
+}
+
+// A status change the board announced for a slice already on disk, applied without reading the board again:
+// the same two steps a full refresh takes for status — record what the board shows (observeBoard, after
+// adopting the agent's own edits), then project the log's status into the files — so a claim held here still
+// wins over the board's InProgress. Returns false when the slice is unknown or the status unrecognised; the
+// caller then falls back to a full refresh.
+export function applyBoardStatus(kitDir, sliceId, boardStatus, meta) {
+  const status = normalizeBoardStatus(boardStatus);
+  if (!sliceId || !status || !knowsSlice(kitDir, sliceId)) return false;
+  const state = observeBoard(kitDir, [{ id: sliceId, status }], meta, adoptAgentEdits(kitDir, fold(readEvents(kitDir)), meta));
+  projectStatus(kitDir, state);
+  return true;
+}
+
 // The build agent still records its outcome by editing a slice's status in index.json (until it has a
 // command of its own). While a slice is claimed the projection keeps that file equal to the log, so any
 // difference is the agent's edit — adopted as `agent-recorded`. This runs before every refresh and before

package/shared/build-kit/lib/slice-refresh.js

@@ -0,0 +1,35 @@
+// One refresh for a burst of requests. Every agent on a board re-reads the slice list when someone else
+// changes a slice, so an import or a bulk status change would otherwise read it once per event, per agent.
+//
+// request() resolves once a run that STARTED after the call has finished — a request made while a run is
+// already in flight gets a fresh run of its own, because the data that run read may predate it. Requests
+// within `delayMs` of each other share one run, which receives the arguments of the last request.
+
+export function coalesce(fn, delayMs) {
+  let waiters = [];
+  let timer = null;
+  let running = false;
+  let lastArgs = [];
+
+  const run = async () => {
+    timer = null;
+    running = true;
+    const batch = waiters;
+    waiters = [];
+    try {
+      await fn(...lastArgs);
+      for (const w of batch) w.resolve();
+    } catch (err) {
+      for (const w of batch) w.reject(err);
+    } finally {
+      running = false;
+      if (waiters.length && !timer) timer = setTimeout(run, delayMs);
+    }
+  };
+
+  return (...args) => new Promise((resolve, reject) => {
+    lastArgs = args;
+    waiters.push({ resolve, reject });
+    if (!running && !timer) timer = setTimeout(run, delayMs);
+  });
+}

package/shared/skills/learn-eventmodelers-api/references/mcp-tool-catalog.md

@@ -11,7 +11,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | Tool | Args | Purpose | REST equivalent |
 |---|---|---|---|
 | `list_boards` | — | List boards for the org | §1 `GET /api/boards` (org-scoped) |
-| `get_nodes` | `boardId`, `type?`, `name?`, `chapterId?`, `nodeIds?`, `projection?` (`"line"` \| `"fields"`) | List nodes, optionally by type and/or a partial case-insensitive title match. **Unscoped with full `meta` it is expensive** — about 2 KB per node, ~1 MB on a 500-node board — so always pass a filter or a projection. `chapterId` scopes to one timeline — prefer this over an unscoped board-wide call whenever the step is working within one chapter (the common case); `nodeIds` fetches a known, scattered subset in one call (e.g. re-verifying exactly the nodes just touched by a batch write) instead of a full `type` refetch; `projection: "line"` maps each match to `{id, type, title, fields}` — `fields` being just the attribute names; `projection: "fields"` to `{id, type, title, parentId, fields}` with the full field definitions (type, example, idAttribute, …) but no html, description, sketch or grid data. No `cellName` — an existing node is addressed by its `id`; when a cell address is needed (placing into a cell), read it from `get_board_outline`. No `sliceStatus` — take it per column from `get_board_outline` | §3 `GET .../nodes` (REST records carry no `cellName`, `projection=line`/`fields` included) |
+| `get_nodes` | `boardId`, `type?`, `name?`, `chapterId?`, `nodeIds?`, `projection?` (`"line"` \| `"fields"`) | List nodes, optionally by type and/or a partial case-insensitive title match. **A filter is required** — `type`, `name`, `chapterId` or `nodeIds`; a call without one is rejected (`NODES_FILTER_REQUIRED`) because it would load the whole board, and a `projection` alone does not count. Full `meta` is about 2 KB per node, so add a projection (`line` / `fields`) on top of the filter when you only need an overview. `chapterId` scopes to one timeline — prefer this over an unscoped board-wide call whenever the step is working within one chapter (the common case); `nodeIds` fetches a known, scattered subset in one call (e.g. re-verifying exactly the nodes just touched by a batch write) instead of a full `type` refetch; `projection: "line"` maps each match to `{id, type, title, fields}` — `fields` being just the attribute names; `projection: "fields"` to `{id, type, title, parentId, fields}` with the full field definitions (type, example, idAttribute, …) but no html, description, sketch or grid data. No `cellName` — an existing node is addressed by its `id`; when a cell address is needed (placing into a cell), read it from `get_board_outline`. No `sliceStatus` — take it per column from `get_board_outline` | §3 `GET .../nodes` (REST records carry no `cellName`, `projection=line`/`fields` included) |
 | `get_node` | `boardId`, `nodeId`, `projection?` (`"cells"` \| `"edges"`) | Get one node (no `cellName` — address it by `nodeId`; cell addresses come only from `get_board_outline`). `projection: "cells"` (CHAPTER nodes only) returns just `{rows, columns, cells}` instead of the full `timelineData` — use whenever only the grid/occupancy is needed, not the whole chapter; `projection: "edges"` returns just that node's inbound/outbound connections instead of `findNodeById`'s full record. Both are opt-in — omitting `projection` is the unchanged full response. An unknown id is a `NODE_NOT_FOUND` error | §3 `GET .../nodes/:nodeId` (REST returns the node as stored, without `cellName`; `404` carries `code: 'NODE_NOT_FOUND'`) |
 | `get_node_comments` | `boardId`, `nodeId` | List comments on a node | §1 `GET .../nodes/:nodeId/comments` |
 | `get_chat_attachment` | `boardId`, `sessionId`, `attachmentId` | The file a chat message came with — the message's `attachments` list `{id, type, ending}`. Images come back as images, a PDF as an embedded resource, csv / xml / txt / json as text. Only the agent the message was addressed to can read it (`CHAT_ATTACHMENT_NOT_FOUND`); needs the connection's `x-agent-id` (`CHAT_AGENT_REQUIRED`). Max 5 MB per file. | §15 `GET /api/org/:orgId/chat/sessions/:sessionId/attachments/:attachmentId` |

package/shared/skills/learn-eventmodelers-api/references/s03-nodes.md

@@ -66,12 +66,13 @@ interface NodeChangeEvent {
 ---
 
 ### GET `/api/org/:orgId/boards/:boardId/nodes`
-List all nodes on a board.
+List a board's nodes. **A filter is required**: a call with none of `type`, `name`, `chapterId`, `toplevel=true` or `cellId`/`colId` (with `timelineId`) is `400 NODES_FILTER_REQUIRED`, because it would load the whole board — a `projection` alone does not count. Read a board in parts: `toplevel=true` (the nodes in no chapter), then `chapterId` per chapter; or fetch known ids with `POST …/nodes/query`.
 
 **Query params** (each at most once — a repeated or nested param is `400 QUERY_PARAM_INVALID`):
 - `type?: ElementType` — exact match.
 - `name?: string` — partial, case-insensitive title match.
 - `chapterId?: string` — only nodes placed in this chapter (timeline).
+- `toplevel?: "true"` — only the nodes placed in no chapter (the chapters themselves, contexts, drawings); not combinable with `chapterId`, `cellId` or `colId` (`400 TOP_LEVEL_FILTER_CONFLICT`).
 - `projection?: "line" | "fields"` — `line`: compact `{id, type, title, fields?}` per node (`fields` = attribute names only, absent on nodes without fields); `fields`: `{id, type, title, parentId, fields?}` with the full field definitions as stored, but no html, description, sketch or grid data. Either instead of the full record. Neither form carries `cellName` — address existing nodes by `id`. Any other value is `400 PROJECTION_INVALID`.
 - `cellId?: string` — return only the node occupying this timeline cell (format `<rowId>-<colId>`). Requires `timelineId`. Empty array if the cell is unoccupied.
 - `colId?: string` — return every node occupying this column, across *all* rows of the timeline (e.g. to check for an existing COMMAND/READMODEL/SCREEN/AUTOMATION before placing one, since the server caps those at one per column even across separate lane rows). Requires `timelineId`. Combine with `type` to narrow to one element type.