crewforth 3.1.0-rc.2 → 3.1.0-rc.4

package/kit/studio/web/canvas.js

@@ -11,9 +11,11 @@
 //   A status is never colour alone: every dot has its word beside it.
 //   A poll that changed nothing writes nothing. Each element remembers what it last drew.
 import {
-  plan, sequence, crowdFolds, fitZoom, stateOf, ZOOM, GROUPINGS, DENSITIES,
+  plan, sequence, crowdFolds, fitZoom, stateOf, ZOOM, GROUPINGS, DENSITIES, INFERRED_NOTE,
 } from './graph-plan.js';
+import { clock } from './timeline-plan.js';
 import { agentStatus } from './nav.js';
+import { roleName, shownType, hoverOf, orderTag } from './names.js';
 
 // How long an arriving wire takes to draw itself toward its new card. Short on purpose: this is a status panel,
 // and anything a viewer has to wait through is a cost they pay on every spawn.
@@ -84,6 +86,7 @@ export class Canvas {
     this.mapRects = new Map();   // drawn item id -> its box on the minimap
     this.seq = new Map();        // id -> arrival number (see graph-plan.js)
     this.open = new Map();       // group id -> the viewer's own fold
+    this.aside = false;          // an agent group opens into the next column, not downward
     // Ids that arrived on the last poll. A wire into one of these draws itself; every other wire is left alone,
     // so opening a group of 105 does not set 105 animations running at once.
     this.newborn = new Set();
@@ -139,11 +142,53 @@ export class Canvas {
     this.mapEl.append(this.mapSvg);
 
     this.legendEl = this.#legend();
+    this.spendEl = this.#spend();
     this.tipEl = mk('div', 'cv-tip');
     this.tipEl.setAttribute('role', 'tooltip');
     this.tipEl.hidden = true;
 
-    this.root.append(this.viewport, this.emptyEl, this.mapEl, this.legendEl, this.tipEl);
+    this.root.append(this.viewport, this.emptyEl, this.mapEl, this.legendEl, this.spendEl, this.tipEl);
+  }
+
+  /** What the session spent: time, tokens and an estimate of the cost. Closed, it stays closed until asked for. */
+  #spend() {
+    const box = mk('div', 'cv-legend cv-spend');
+    box.setAttribute('aria-label', 'Session summary');
+    const head = mk('div', 'cv-legend-head');
+    head.append(mk('span', 'cv-label', 'Session'));
+    const close = mk('button', 'cv-x');
+    close.type = 'button';
+    close.setAttribute('aria-label', 'Close the session summary');
+    close.innerHTML = MARK.close;
+    close.addEventListener('click', () => this.showSpend(false));
+    head.append(close);
+    this.spendRows = mk('dl', 'cv-spend-rows');
+    box.append(head, this.spendRows);
+    this.spendOpen = readFlag('crewforth-studio-spend') !== 'closed';
+    box.hidden = true;                       // until there is a session's usage to show
+    return box;
+  }
+
+  showSpend(on) {
+    this.spendOpen = Boolean(on);
+    writeFlag('crewforth-studio-spend', on ? 'open' : 'closed');
+    this.spendEl.hidden = !on || !this.spendCount;
+  }
+
+  /** The rows to show: [label, value, note], from usage.js `summaryRows`. An empty list hides the box. */
+  setSpend(rows) {
+    const sig = JSON.stringify(rows ?? []);
+    if (sig === this.spendSig) return;
+    this.spendSig = sig;
+    this.spendCount = (rows ?? []).length;
+    this.spendRows.replaceChildren(...(rows ?? []).flatMap(([label, value, note]) => {
+      const dd = mk('dd', null, value ?? '');
+      dd.title = note ?? '';
+      const dt = mk('dt', null, label);
+      dt.title = note ?? '';
+      return [dt, dd];
+    }));
+    this.spendEl.hidden = !this.spendOpen || !this.spendCount;
   }
 
   /** What the lines and the two marks mean. Shown until it is closed, and then not again unless asked for. */
@@ -169,6 +214,10 @@ export class Canvas {
     const rows = mk('div', 'cv-legend-grid');
     rows.append(line('live', 'working now'), line('waiting', 'needs you'), line('done', 'finished'), line('failed', 'failed'));
     box.append(rows);
+    // The one wire that is not a call: in the Order view, from an agent to the wave called after it reported.
+    const inferred = line('inferred', 'after it reported (inferred, not a call)');
+    inferred.title = INFERRED_NOTE;
+    box.append(inferred);
     const marks = mk('div', 'cv-legend-grid');
     this.legendBuiltin = mk('span', 'cv-tile cv-tile-sm');
     const crew = mk('span', 'cv-tile cv-tile-sm');
@@ -196,7 +245,7 @@ export class Canvas {
     this.root.addEventListener('pointerdown', (e) => {
       if (e.button !== 0) return;                 // right/middle must not pan
       const t = e.target;
-      if (t.closest?.('.cv-node') || t.closest?.('.cv-minimap') || t.closest?.('.cv-legend')) return;
+      if (t.closest?.('.cv-node') || t.closest?.('.cv-minimap') || t.closest?.('.cv-legend')) return;   // the summary box is a .cv-legend too
       panning = { px: e.clientX, py: e.clientY, x: this.view.x, y: this.view.y };
       this.root.setPointerCapture(e.pointerId);
       this.root.classList.add('cv-panning');
@@ -303,7 +352,7 @@ export class Canvas {
       drawnAs: this.lastPlan?.density ?? null,
       stacked: Boolean(this.lastPlan?.stacked),
       drawn: this.drawn,
-      focus: this.focusId ? (this.nodes.get(this.focusId)?.agentType ?? this.focusId) : null,
+      focus: this.focusId ? (roleName(this.nodes.get(this.focusId)?.agentType) || this.focusId) : null,
       groups: (this.lastPlan?.items ?? []).filter((it) => it.kind === 'group').length,
     };
   }
@@ -384,12 +433,14 @@ export class Canvas {
   }
 
   expandAll() {
-    for (const it of this.lastPlan?.items ?? []) if (it.kind === 'group') this.open.set(it.id, true);
+    // Beside itself an agent group opens one at a time, by its own card; "all" is then every other kind of group.
+    const mine = (it) => it.kind === 'group' && !(this.aside && it.type === 'type');
+    for (const it of this.lastPlan?.items ?? []) if (mine(it)) this.open.set(it.id, true);
     // Opening one level can reveal groups inside it; open those too.
     for (let i = 0; i < 4; i += 1) {
       const p = this.#plan();
       let more = false;
-      for (const it of p.items) if (it.kind === 'group' && !it.open) { this.open.set(it.id, true); more = true; }
+      for (const it of p.items) if (mine(it) && !it.open) { this.open.set(it.id, true); more = true; }
       if (!more) break;
     }
     this.sessionY = null;
@@ -443,6 +494,7 @@ export class Canvas {
   #plan() {
     return plan(this.#visibleNodes(), {
       group: this.group, density: this.density, seq: this.seq, open: this.open, pinned: this.pinned, sessionY: this.sessionY,
+      aside: this.aside,
     });
   }
 
@@ -569,7 +621,7 @@ export class Canvas {
 
   #drawItem(it, liveCells) {
     let el = this.els.get(it.id);
-    const shape = it.kind === 'group' ? `group:${it.open ? `open:${it.grid ? 'grid' : 'rows'}` : 'folded'}`
+    const shape = it.kind === 'group' ? `group:${it.boxed ? `open:${it.grid ? 'grid' : 'rows'}` : 'folded'}`
       : `${it.kind}:${it.compact ? 'chip' : 'card'}`;
     // A card that changes what it IS (an agent that becomes a chip, a group that opens) is rebuilt; one that only
     // changes what it says is updated in place.
@@ -600,7 +652,7 @@ export class Canvas {
     el.classList.toggle('cv-pinned', Boolean(it.pinned));
     if (it.kind === 'session') this.#fillSession(el, it);
     else if (it.kind === 'group') this.#fillGroup(el, it, liveCells);
-    else this.#fillAgent(el, it.node, it.compact);
+    else this.#fillAgent(el, it.node, it.compact, it.after ?? null);
   }
 
   /** The skeleton of a card: the parts it will fill. */
@@ -627,7 +679,7 @@ export class Canvas {
       p.head.append(p.tile, p.name, mk('span', 'cv-fill'), p.sub, p.fold);
       p.bar = mk('div', 'cv-bar');
       p.count = mk('span', 'cv-sub');
-      if (it.open) {
+      if (it.boxed) {
         el.classList.add('cv-open');
         el.append(p.head, p.bar);
       } else {
@@ -639,18 +691,24 @@ export class Canvas {
     } else if (it.compact) {
       el.classList.add('cv-chip');
       p.dot = mk('span', 'dot');
+      p.order = mk('span', 'cv-order');
       p.name = mk('span', 'cv-name');
       p.task = mk('span', 'cv-task');
       p.word = mk('span', 'cv-word');
-      el.append(p.dot, p.name, p.task, p.word);
+      el.append(p.dot, p.order, p.name, p.task, p.word);
     } else {
       p.tile = mk('span', 'cv-tile');
       p.name = mk('span', 'cv-name');
+      p.order = mk('span', 'cv-order');
       p.pill = this.#pill();
       const row = mk('div', 'cv-row');
       row.append(p.tile, p.name, mk('span', 'cv-fill'), p.pill.el);
-      p.task = mk('div', 'cv-task cv-indent');
-      el.append(row, p.task);
+      // The second line: the task, and at its end where the card stands in the order of the calls. The name
+      // keeps the first line to itself.
+      p.task = mk('span', 'cv-task');
+      const under = mk('div', 'cv-under cv-indent');
+      under.append(p.task, p.order);
+      el.append(row, under);
     }
     el.parts = p;
   }
@@ -701,7 +759,8 @@ export class Canvas {
   #fillSession(el, it) {
     const n = it.node;
     const st = this.sessionState;
-    const sig = JSON.stringify([n.gitBranch, n.cwd, n.turns, n.tokens, st?.word, st?.tone]);
+    const bg = n.backgroundNow?.length ?? 0;
+    const sig = JSON.stringify([n.gitBranch, n.cwd, n.turns, n.tokens, st?.word, st?.tone, bg]);
     if (el.sig === sig) return;
     el.sig = sig;
     const p = el.parts;
@@ -712,18 +771,23 @@ export class Canvas {
     p.name.textContent = n.gitBranch || shortPath(n.cwd) || n.sessionId || '';
     const bits = [`${n.turns ?? 0} ${n.turns === 1 ? 'turn' : 'turns'}`];
     if (n.tokens != null) bits.push(`${fmtTokens(n.tokens)} ctx`);
+    // What the session has running that is not an agent: commands sent to the background.
+    if (bg) bits.push(`${bg} in background`);
     p.sub.textContent = bits.join(' · ');
+    p.sub.title = bg ? n.backgroundNow.map((c) => `In the background: ${c.toolName}${c.detail ? ` · ${c.detail}` : ''}`).join('\n') : '';
     el.title = 'Click to inspect this session';
     el.setAttribute('aria-label', `Session, ${st?.word ?? 'state not measured'}, ${p.name.textContent}, ${p.sub.textContent}`);
   }
 
-  #fillAgent(el, n, compact) {
+  #fillAgent(el, n, compact, after = null) {
     const st = this.#statusOf(n);
     const who = compact ? this.#identity(n) : this.#fillTile(el.parts.tile, n);
-    const type = n.kind === 'workflow' ? (n.workflowId ?? 'workflow run') : (n.agentType ?? 'unknown agent');
+    const type = n.kind === 'workflow' ? (n.workflowId ?? 'workflow run') : shownType(n);
     const task = n.kind === 'workflow' ? `${n.members ?? 0} agents` : (n.description ?? '');
     const dim = this.dimmed(n);
-    const sig = JSON.stringify([type, task, st.word, st.tone, st.state, who.source, dim, n.status]);
+    // Its place in the order the session called its agents, and when: "#3 · 09:14". A chip has room for the number.
+    const tag = orderTag(n, compact ? null : clock);
+    const sig = JSON.stringify([type, task, st.word, st.tone, st.state, who.source, dim, n.status, tag, after]);
     if (el.sig === sig) return;
     el.sig = sig;
     const p = el.parts;
@@ -735,6 +799,14 @@ export class Canvas {
     el.classList.toggle('cv-dim', dim);
     p.name.textContent = type;
     p.task.textContent = task;
+    // Both are cut to the card's width; hovering says them whole, and the type as it is declared.
+    p.name.title = n.kind === 'workflow' ? '' : (n.agentType ?? '');
+    p.task.title = task;
+    p.order.textContent = tag;
+    p.order.hidden = !tag;
+    p.order.title = tag ? `Called ${orderTag(n, clock)} by the session` : '';
+    // In the Order view: what had reported before this wave was called. A reading of the order of events.
+    el.title = after?.length ? `Called after ${after.join(', ')} reported.\n${INFERRED_NOTE}` : '';
     if (compact) {
       p.dot.dataset.tone = st.tone ?? 'none';
       p.word.textContent = st.word;
@@ -752,19 +824,28 @@ export class Canvas {
     const p = el.parts;
     const counts = it.counts;
     const says = Object.entries(counts).map(([s, c]) => `${c} ${agentStatus(s).word}`).join(' · ');
-    const sig = JSON.stringify([it.label, says, it.open, it.type, it.status]);
+    const sig = JSON.stringify([it.label, says, it.open, it.boxed, it.type, it.status, it.first?.order ?? null]);
     if (el.sig !== sig) {
       el.sig = sig;
       el.dataset.state = stateOf(it.status);
       el.dataset.status = it.status;
       el.dataset.group = it.type;
       el.dataset.open = String(Boolean(it.open));
+      // Open beside itself: the card stays a card and its agents are the next column.
+      el.dataset.aside = String(Boolean(it.open && !it.boxed));
       p.name.textContent = it.label;
+      p.name.title = it.real ?? '';
       if (it.type === 'run') { p.tile.innerHTML = MARK.run; p.tile.title = 'Workflow run'; }
       else this.#fillTile(p.tile, it.type === 'type' ? { agentType: it.agentType } : (it.of ?? {}));
-      p.sub.textContent = it.type === 'type' ? '' : `${it.members.length} ${it.members.length === 1 ? 'agent' : 'agents'}`;
-      p.fold.innerHTML = it.open ? MARK.down : MARK.chevron;
-      p.fold.setAttribute('aria-label', `${it.open ? 'Fold' : 'Open'} ${it.label}`);
+      // Several agents of one type: the number is a badge beside the role. Any other group says how many it holds.
+      const size = it.type === 'type' ? `× ${it.count}` : `${it.members.length} ${it.members.length === 1 ? 'agent' : 'agents'}`;
+      // The group stands where its first member does in the order of the calls.
+      p.sub.textContent = [orderTag(it.first), size].filter(Boolean).join(' · ');
+      p.sub.classList.toggle('cv-times', it.type === 'type');
+      p.fold.innerHTML = it.boxed ? MARK.down : MARK.chevron;
+      // Read aloud, the badge is part of the name.
+      const said = it.type === 'type' ? `${it.label} × ${it.count}` : it.label;
+      p.fold.setAttribute('aria-label', `${it.open ? 'Fold' : 'Open'} ${said}`);
       p.fold.setAttribute('aria-expanded', String(Boolean(it.open)));
       // The bar: how the group went, in the order the eye wants it.
       const order = ['done', 'running', 'starting', 'failed', 'killed', 'stopped', 'stale', 'ended'];
@@ -776,11 +857,11 @@ export class Canvas {
         return seg;
       }));
       p.bar.title = says;
-      if (!it.open) p.count.textContent = says;
-      el.title = it.open ? '' : `Click to show ${it.members.length} agents`;
-      el.setAttribute('aria-label', `${it.label}, ${says}, ${it.open ? 'open' : 'folded'}`);
+      if (!it.boxed) p.count.textContent = says;
+      el.title = it.boxed ? '' : (it.open ? 'Click to fold' : `Click to show ${it.members.length} agents`);
+      el.setAttribute('aria-label', `${said}, ${says}, ${it.open ? 'open' : 'folded'}`);
     }
-    if (!it.open) return;
+    if (!it.boxed) return;
 
     for (const cell of it.cells) {
       liveCells.add(cell.id);
@@ -795,8 +876,9 @@ export class Canvas {
         c.tabIndex = 0;
         const q = {};
         if (!it.grid) { q.tile = mk('span', 'cv-tile'); c.append(q.tile); } else { q.dot = mk('span', 'dot'); c.append(q.dot); }
+        q.order = mk('span', 'cv-order');
         q.name = mk('span', 'cv-name');
-        c.append(q.name);
+        c.append(q.order, q.name);
         if (!it.grid) { c.append(mk('span', 'cv-fill')); q.dot = mk('span', 'dot'); c.append(q.dot); }
         q.word = mk('span', 'cv-word');
         c.append(q.word);
@@ -816,9 +898,10 @@ export class Canvas {
       const st = this.#statusOf(n);
       const who = it.grid ? this.#identity(n) : this.#fillTile(c.parts.tile, n);
       // Inside a group of one type the type is the group's name, so a member is told apart by its task.
-      const text = it.type === 'type' ? (n.description || n.agentType || n.id) : (n.agentType ?? 'unknown agent');
+      const text = it.type === 'type' ? (n.description || shownType(n) || n.id) : shownType(n);
       const dim = this.dimmed(n);
-      const csig = JSON.stringify([text, st.word, st.tone, st.state, dim, this.selected === n.id]);
+      const ctag = orderTag(n, it.grid ? null : clock);
+      const csig = JSON.stringify([text, st.word, st.tone, st.state, dim, this.selected === n.id, ctag]);
       if (c.sig === csig) continue;
       c.sig = csig;
       c.dataset.state = st.state;
@@ -826,12 +909,39 @@ export class Canvas {
       c.classList.toggle('cv-dim', dim);
       c.classList.toggle('cv-selected', this.selected === n.id);
       c.parts.name.textContent = text;
+      c.parts.order.textContent = ctag;
+      c.parts.order.hidden = !ctag;
+      c.title = hoverOf(n);
       c.parts.dot.dataset.tone = st.tone ?? 'none';
       c.parts.word.textContent = st.word;
-      c.setAttribute('aria-label', `${n.agentType ?? 'unknown agent'}, ${st.word}${n.description ? `, ${n.description}` : ''} (${who.title})`);
+      c.setAttribute('aria-label', `${shownType(n)}, ${st.word}${n.description ? `, ${n.description}` : ''} (${who.title})`);
     }
   }
 
+  /** What an inferred wire says: on hover that it is an inference, and once per reporter, in words beside it. */
+  #edgeWords(path, e, c) {
+    const title = e.title ?? '';
+    if (path.said !== title) {
+      path.said = title;
+      path.querySelector?.('title')?.remove();
+      if (title) {
+        const t = document.createElementNS(SVG, 'title');
+        t.textContent = title;
+        path.append(t);
+      }
+    }
+    if (!e.label) { path.label?.remove(); path.label = null; return; }
+    if (!path.label) {
+      path.label = document.createElementNS(SVG, 'text');
+      path.label.setAttribute('class', 'cv-edge-label');
+      this.edgeG.append(path.label);
+    }
+    path.label.textContent = e.label;
+    // Just off the reporter's edge, above the wire, where it does not sit on a card.
+    path.label.setAttribute('x', String(e.from.x + 8));
+    path.label.setAttribute('y', String(e.from.y - 6));
+  }
+
   // Wires are kept and updated, never rebuilt.
   //
   // Replacing the whole layer each pass was the reason motion could not live here: a CSS animation restarts when
@@ -870,9 +980,13 @@ export class Canvas {
 
       const target = this.nodes.get(e.target);
       const waiting = target && this.waiting.has(target.id);
-      const state = waiting ? 'waiting' : e.state;
+      // A wire that is a reading of the order of events says nothing about what its target is doing now.
+      const inferred = e.kind === 'inferred';
+      const state = inferred ? 'inferred' : (waiting ? 'waiting' : e.state);
       path.dataset.status = e.status;
       path.dataset.state = state;
+      path.dataset.kind = inferred ? 'inferred' : 'call';
+      this.#edgeWords(path, e, c);
       path.classList.toggle('cv-dim', Boolean(target) && this.dimmed(target));
       path.classList.toggle('cv-path', onPath.has(e.target));
 
@@ -888,6 +1002,7 @@ export class Canvas {
 
     for (const [key, path] of this.edgeEls) {
       if (alive.has(key)) continue;
+      path.label?.remove();
       path.remove();
       this.edgeEls.delete(key);
     }
@@ -986,11 +1101,23 @@ export class Canvas {
     const it = this.lastPlan?.items.find((x) => x.id === groupId);
     if (!it || it.kind !== 'group') return;
     this.open.set(groupId, !it.open);
+    // Beside itself, one agent's tasks at a time: a second column of them from two groups reads as one list.
+    if (!it.open && it.type === 'type' && this.aside) {
+      for (const other of this.lastPlan.items) if (other.kind === 'group' && other.type === 'type' && other.id !== groupId) this.open.set(other.id, false);
+    }
     this.sessionY = null;
     this.#persist();
     this.#redraw();
   }
 
+  /** Whether an agent group opens into the next column (a window with room) or downward (a narrow one). */
+  setAside(on) {
+    if (this.aside === Boolean(on)) return;
+    this.aside = Boolean(on);
+    this.sessionY = null;
+    if (this.lastPlan) this.#redraw({ fit: true });
+  }
+
   /** Drop the selection without pretending a card was clicked. */
   clearSelection() {
     this.selected = null;
@@ -1141,7 +1268,8 @@ export class Canvas {
         if (n.tokens != null) bits.push(`${fmtTokens(n.tokens)} tokens`);
         if (n.errors) bits.push(`${n.errors} ${n.errors === 1 ? 'error' : 'errors'}`);
         this.tipEl.replaceChildren(
-          mk('strong', null, n.agentType ?? 'unknown agent'),
+          mk('strong', null, shownType(n)),
+          mk('div', 'cv-sub cv-real', n.agentType ?? ''),
           mk('div', null, n.description || 'No task recorded'),
           mk('div', 'cv-sub', bits.length ? bits.join(' · ') : 'No numbers yet'),
         );

package/kit/studio/web/chat.js

@@ -375,6 +375,7 @@ class Pane {
     node.sig = sig;
     const text = el('span', 'deleg-text');
     text.append(el('span', 'deleg-type', card.type), el('span', 'deleg-task', card.task));
+    text.title = [card.real, card.task].filter(Boolean).join('\n');
     const parts = [];
     const tile = card.agentId ? this.hooks.tileOf?.(this.id, card.agentId) : null;
     if (tile) parts.push(tile);

package/kit/studio/web/convo.js

@@ -3,6 +3,7 @@
 // The same shapes come from two places: the server's reading of a transcript (history, and sessions Studio only
 // watches) and the live stream of a session started here. Both go through these functions, so a tool row reads
 // the same whichever way it arrived.
+import { roleName } from './names.js';
 
 // How much of a tool's output the page keeps for a live result: the same tail the server keeps for history.
 const RESULT_TAIL = 4096;
@@ -76,7 +77,8 @@ export function outputOf(block) {
 export function delegationCard(block, nodes) {
   const node = block.id ? (nodes ?? []).find((n) => n.kind === 'agent' && n.toolUseId === block.id) ?? null : null;
   return {
-    type: block.subagentType ?? node?.agentType ?? 'agent',
+    type: roleName(block.subagentType ?? node?.agentType ?? 'agent'),
+    real: block.subagentType ?? node?.agentType ?? null,
     task: block.label ?? node?.description ?? '',
     agentId: node?.id ?? null,
     status: node?.status ?? null,
@@ -121,7 +123,7 @@ export function refusals(denials, wasAllowed, resultOf = () => null) {
 export function reminderOf(waiting) {
   const list = waiting ?? [];
   if (!list.length) return null;
-  const who = list[0].agentType ?? 'This session';
+  const who = list[0].agentType ? roleName(list[0].agentType) : 'This session';
   const more = list.length - 1;
   return `${who} is waiting for approval${more > 0 ? `, and ${more} more ${more === 1 ? 'request is' : 'requests are'}` : ''}`;
 }

package/kit/studio/web/dock.js

@@ -184,6 +184,7 @@ export class Dock {
     p.word.textContent = 'Needs you';
 
     p.who.textContent = asker(item);
+    p.who.title = item.agentType ? `${item.agentType} — show on the canvas` : 'Show on the canvas';
     p.tool.textContent = item.toolName;
     const where = this.where(item);
     p.where.hidden = !where;