crewforth 3.1.0-rc.3 → 3.1.0-rc.4

package/kit/studio/web/graph-plan.js

@@ -22,6 +22,7 @@ import { typeOf, roleName, shownType } from './names.js';
 export const SIZE = {
   padX: 24, padY: 16,          // the canvas's own margin
   colGap: 56,                  // between one depth and the next
+  waveGap: 148,                // between one wave and the next: room for the words on an inferred wire
   rowGap: 12,                  // between siblings
   session: { w: 200, h: 84 },
   card: { w: 248, h: 64 },     // an agent, and a folded group
@@ -48,7 +49,7 @@ export const AUTO = {
   stackAt: 3,
 };
 
-export const GROUPINGS = ['run', 'type', 'parent', 'none'];
+export const GROUPINGS = ['run', 'type', 'parent', 'order', 'none'];
 export const DENSITIES = ['auto', 'comfortable', 'compact'];
 
 // The handful of things a status means to a reader. `killed` and `stopped` come off the transcript verbatim and
@@ -227,6 +228,8 @@ function groupItem(id, type, members, anchor, via, depth, seq, extra) {
     via,
     depth,
     seq: Math.min(...members.map((m) => seq.get(m.id) ?? 0), Infinity),
+    // The group stands where its first member does in the order the session called its agents.
+    first: members.filter((m) => m.order != null).sort((a, b) => a.order - b.order)[0] ?? null,
     ...extra,
   };
 }
@@ -248,6 +251,7 @@ function groupItem(id, type, members, anchor, via, depth, seq, extra) {
 export function plan(nodes, opts = {}) {
   const group = GROUPINGS.includes(opts.group) ? opts.group : 'run';
   const asked = DENSITIES.includes(opts.density) ? opts.density : 'auto';
+  if (group === 'order') return planOrder(nodes, asked, opts);
   const seq = opts.seq ?? sequence(nodes);
   const open = opts.open ?? new Map();
   const pinned = opts.pinned ?? new Map();
@@ -422,6 +426,107 @@ export function plan(nodes, opts = {}) {
   };
 }
 
+/* ---------------------------------------------------------------- order --- */
+
+// What the wire from an agent to a later wave is called, and what it is: a reading of the order of events.
+export const INFERRED_NOTE = 'Inferred from the order of events: this wave was called after that agent reported. It is not a call from one agent to another; the session calls every agent.';
+
+/**
+ * The same agents by when the session called them.
+ *
+ * Every agent is called by the session, so the tree is one level deep and says nothing of sequence. Here a
+ * column is a WAVE: the agents called in one assistant message, which is what "started together" means. Waves
+ * run left to right in the order the messages were written, and a wave's agents stack in the order of the calls.
+ * Agents the session's transcript did not call (a workflow's) have no wave and take a last column of their own.
+ *
+ * Two kinds of wire. The session is wired to the first wave: it called it. A later wave is wired, dotted, from
+ * each agent that reported after the wave before it was called and before this one was — an inference from the
+ * order of events, drawn as one and labelled as one. A wave nothing reported before has no wire.
+ */
+function planOrder(nodes, asked, opts) {
+  const pinned = opts.pinned ?? new Map();
+  const session = nodes.find((n) => n.kind === 'session') ?? null;
+  const agents = nodes.filter((n) => n.kind === 'agent');
+  const called = agents.filter((n) => n.wave != null);
+  const waveIds = [...new Set(called.map((n) => n.wave))].sort((a, b) => a - b);
+  const byOrder = (a, b) => (a.order ?? 0) - (b.order ?? 0) || String(a.id).localeCompare(String(b.id));
+  const columns = waveIds.map((w) => ({ wave: w, members: called.filter((n) => n.wave === w).sort(byOrder) }));
+  for (const c of columns) c.calledAt = Math.min(...c.members.map((m) => m.calledAt ?? Infinity));
+  const rest = agents.filter((n) => n.wave == null)
+    .sort((a, b) => (a.startedAt ?? Infinity) - (b.startedAt ?? Infinity) || String(a.id).localeCompare(String(b.id)));
+  if (rest.length) columns.push({ wave: null, members: rest, calledAt: Infinity });
+
+  const lay = (compact) => {
+    const sz = compact ? SIZE.chip : SIZE.card;
+    const items = [];
+    const x0 = SIZE.padX + (session ? SIZE.session.w + SIZE.colGap : 0);
+    let height = 0;
+    columns.forEach((col, i) => {
+      col.members.forEach((n, j) => {
+        items.push({
+          id: n.id, kind: 'agent', node: n, parent: null, via: null, depth: i + 1, seq: n.order ?? j, compact,
+          wave: col.wave, w: sz.w, h: sz.h, x: x0 + i * (sz.w + SIZE.waveGap), y: SIZE.padY + j * (sz.h + SIZE.rowGap),
+        });
+      });
+      height = Math.max(height, SIZE.padY * 2 + col.members.length * (sz.h + SIZE.rowGap) - SIZE.rowGap);
+    });
+    const width = x0 + Math.max(0, columns.length * (sz.w + SIZE.waveGap) - SIZE.waveGap) + SIZE.padX;
+    return { items, width, height };
+  };
+  let compact = asked === 'compact';
+  let box = lay(compact);
+  if (asked === 'auto' && box.height > AUTO.tallest) { compact = true; box = lay(true); }
+  const { items } = box;
+  let { height } = box;
+
+  let sessionY = opts.sessionY ?? null;
+  if (session) {
+    const first = items.filter((it) => it.depth === 1);
+    if (sessionY == null) {
+      const bottom = first.length ? Math.max(...first.map((it) => it.y + it.h)) : SIZE.padY + SIZE.session.h;
+      sessionY = Math.max(SIZE.padY, Math.round((SIZE.padY + bottom) / 2 - SIZE.session.h / 2));
+    }
+    items.unshift({ id: session.id, kind: 'session', node: session, parent: null, depth: 0, w: SIZE.session.w, h: SIZE.session.h, x: SIZE.padX, y: sessionY });
+    height = Math.max(height, sessionY + SIZE.session.h + SIZE.padY);
+  }
+  for (const it of items) {
+    const p = pinned.get(it.id);
+    if (p) { it.x = p.x; it.y = p.y; it.pinned = true; }
+  }
+
+  const at = new Map(items.map((it) => [it.id, it]));
+  const edges = [];
+  const wire = (from, to, extra) => edges.push({
+    key: `${from.id}\u0000${to.id}`, source: from.id, target: to.id,
+    from: { x: from.x + from.w, y: from.y + from.h / 2 }, to: { x: to.x, y: to.y + to.h / 2 },
+    status: to.node.status ?? 'unknown', state: stateOf(to.node.status), ...extra,
+  });
+  const waves = columns.filter((c) => c.wave != null);
+  if (session && waves.length) for (const m of waves[0].members) wire(at.get(session.id), at.get(m.id), {});
+  // An agent's report belongs to the first wave called after it: the one that could have been waiting for it.
+  for (let i = 1; i < waves.length; i += 1) {
+    const since = waves[i - 1].calledAt;
+    const reporters = called.filter((n) => n.reportedAt != null && n.reportedAt > since && n.reportedAt <= waves[i].calledAt
+      && n.wave < waves[i].wave).sort(byOrder);
+    waves[i].after = reporters;
+    for (const r of reporters) {
+      waves[i].members.forEach((m, k) => wire(at.get(r.id), at.get(m.id), {
+        kind: 'inferred', state: 'inferred',
+        // Said once for a reporter, on the wire to the wave's first agent; the others carry it on hover.
+        label: k === 0 ? `after ${shownType(r)} reported` : null,
+        title: `after ${shownType(r)} reported\n${INFERRED_NOTE}`,
+      }));
+    }
+    for (const m of waves[i].members) at.get(m.id).after = reporters.map((r) => shownType(r));
+  }
+
+  return {
+    items, edges, width: Math.max(box.width, SIZE.padX * 2), height: Math.max(height, SIZE.padY * 2),
+    drawn: agents.length, density: compact ? 'compact' : 'comfortable', group: 'order', stacked: false, aside: false,
+    waves: waves.length, sessionY,
+  };
+}
+
 /**
  * Which open groups to fold when a session first opens too tall even as chips: the largest first, until the
  * picture is short enough to read or there is nothing left to fold. Returns the ids to fold; an empty list when

package/kit/studio/web/names.js

@@ -31,3 +31,14 @@ export const shownType = (n) => roleName(typeOf(n));
 
 /** What hovering an agent says: the type as it is declared, and its task in full, since both are cut on screen. */
 export const hoverOf = (n) => [n?.agentType ?? null, n?.description ?? null].filter(Boolean).join('\n');
+
+/**
+ * Where an agent stands among the ones the session called, as a tag: "#3 · 09:14". The number is the order of
+ * the calls; the time is when the call was made, in the viewer's own zone. An agent the session's transcript did
+ * not call has no place to state, and gets no tag.
+ * @param clock  (ms) => "HH:MM"
+ */
+export function orderTag(n, clock = null) {
+  if (n?.order == null) return '';
+  return `#${n.order}${clock && n.calledAt != null ? ` · ${clock(n.calledAt)}` : ''}`;
+}

package/kit/studio/web/style.css

@@ -836,6 +836,21 @@ button.tl-lab { cursor: pointer; }
 }
 
 /* Working. The brightest and the only one that travels. */
+/* A wire that is an inference, not a call: dotted, still, and it can be hovered for what it means. A working wire
+   is dashed and moves; this one is neither. */
+.cv-edge[data-kind="inferred"] {
+  stroke: var(--ink-faint);
+  stroke-dasharray: 1.5 5;
+  pointer-events: stroke;
+}
+.cv-edge-label { font-size: 10px; fill: var(--ink-faint); pointer-events: none; }
+/* "#3 · 09:14": where a card stands in the order the session called its agents. */
+.cv-under { display: flex; align-items: baseline; min-width: 0; }
+.cv-under .cv-task { flex: 1 1 auto; min-width: 0; }
+.cv-order { flex: none; margin-left: 6px; font-family: var(--font-mono); font-size: 10px; color: var(--ink-faint); font-variant-numeric: tabular-nums; white-space: nowrap; }
+.cv-order[hidden] { display: none; }
+.cv-chip .cv-order, .cv-member .cv-order { margin-left: 0; margin-right: 6px; }
+
 .cv-edge[data-state="live"] {
   stroke: var(--status-busy);
   opacity: var(--cv-edge-live);
@@ -1086,6 +1101,7 @@ button.tl-lab { cursor: pointer; }
 .cv-legend-line[data-state="live"] { border-top: 1.5px dashed var(--status-busy); }
 .cv-legend-line[data-state="waiting"] { border-top: 1.5px dashed var(--status-waiting); }
 .cv-legend-line[data-state="failed"] { border-top-color: var(--cv-fail); }
+.cv-legend-line[data-state="inferred"] { border-top: 1.5px dotted var(--ink-faint); }
 .cv-x {
   width: 20px; height: 20px; padding: 0; display: inline-flex; align-items: center; justify-content: center;
   background: none; border: 0; border-radius: var(--radius-sm); color: var(--ink-dim); cursor: pointer;

package/kit/studio/web/timeline-plan.js

@@ -120,6 +120,8 @@ export function groupsOf(nodes, grouping) {
       return { id: `parent:${p.id}`, label: p.kind === 'workflow' ? (p.workflowId ?? p.id) : `under ${shownType(p)}` };
     }
     if (grouping === 'none') return { id: 'all', label: null };
+    // `order`: the agents called in one assistant message are a wave, and a wave is a group.
+    if (grouping === 'order') return n.wave != null ? { id: `wave:${n.wave}`, label: `Wave ${n.wave}` } : { id: 'wave:none', label: 'Not called by the session' };
     // `run`: a workflow run is a group; everything the session started itself is another.
     if (n.workflow) return { id: `run:${n.workflow}`, label: String(n.workflow) };
     return { id: 'direct', label: 'Session · direct' };
@@ -135,6 +137,12 @@ export function groupsOf(nodes, grouping) {
   for (const g of out) g.members.sort((a, b) => (a.startedAt ?? Infinity) - (b.startedAt ?? Infinity) || String(a.id).localeCompare(String(b.id)));
   // What the session did itself comes first; the rest in the order they began.
   out.sort((a, b) => Number(b.id === 'direct') - Number(a.id === 'direct') || first(a) - first(b) || a.id.localeCompare(b.id));
+  // Waves are in the order they were called, which is not always the order their agents first wrote.
+  if (grouping === 'order') {
+    const wave = (g) => g.members[0].wave ?? Infinity;
+    out.sort((a, b) => wave(a) - wave(b));
+    for (const g of out) g.members.sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity));
+  }
   return out;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewforth",
-  "version": "3.1.0-rc.3",
+  "version": "3.1.0-rc.4",
   "description": "Crewforth — your engineering crew for Claude Code: agents, skills and tool-level gates, in any stack.",
   "bin": {
     "crewforth": "bin/cli.js"