agent-horde 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/agent-horde"><img src="https://img.shields.io/npm/v/agent-horde" alt="npm version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/eliyastein/agent-horde" alt="MIT license"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20 or newer">
   <a href="https://pi.dev/packages"><img src="https://img.shields.io/badge/pi-package-6f42c1" alt="pi package"></a>
   <a href="https://github.com/eliyastein/agent-horde/issues"><img src="https://img.shields.io/github/issues/eliyastein/agent-horde" alt="open issues"></a>
@@ -88,7 +88,7 @@ pi install npm:agent-horde
 Or from the repository, pinned to a tag:
 
 ```
-pi install git:github.com/eliyastein/agent-horde@v0.1.0
+pi install git:github.com/eliyastein/agent-horde@v0.1.2
 ```
 
 To hack on it, clone and install in place. pi loads the files from the clone, so edits take effect

package/docs/REFERENCE.md

@@ -81,7 +81,7 @@ Every page has a JSON twin under `/api/<same path>`.
 | `/runs/<id>/sessions[/<file>[/<i>]]` | session files not mapped to a member (runs older than per-member session dirs) |
 | `/runs/<id>/files/<NAME>` | any run document; 404 until written |
 | `/runs/<id>/collaboration` | messages, review scope, artifact acceptance, resources, event audit |
-| `/runs/<id>/graph` | the run as a swimlane: one lane per member plus the parent, phase bands, every event a link to its ledger entry (`?w=<px>`, `?from=<s>&to=<s>`) |
+| `/runs/<id>/graph` | the run as a swimlane: one lane per member plus the parent, phase bands, every event a link to its ledger entry (`?w=<px>`, `?from=<s>&to=<s>`); the axis is real time until the last member exits, then the synthesis phases share a compressed tail |
 | `/runs/<id>/graph.mmd` | the same run as a Mermaid flowchart with absolute dashboard links (text/plain) |
 | `/ideas`, `/board`, `/findings`, `/claims`, `/facts`, `/resources` | the shared ledgers; `?run=<id>\|all`, `?view=clusters`, `?owner=<m>` filter them |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-horde",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Run a horde of pi agents on one task: shared ledgers, peer review, an auditable event log, and a live dashboard",
   "license": "MIT",
   "type": "module",

package/src/run-graph-svg.ts

@@ -21,6 +21,9 @@ const HEADER_H = 36;
 const AXIS_H = 18;
 const TICK_STEPS_MS = [5_000, 10_000, 15_000, 30_000, 60_000, 120_000, 300_000, 600_000, 900_000, 1_800_000, 3_600_000, 7_200_000];
 const MAX_TICKS = 14;
+/** Share of the plot for everything after the last member exits, when that tail would otherwise dominate. */
+const TAIL_FRACTION = 0.15;
+const TAIL_AXIS_H = 30;
 
 const TONE_COLORS: Record<EdgeTone, string> = {
   structure: "#000", collaboration: "#1f5fbf", verification: "#1a7f37", negative: "#c62828", lifecycle: "#888",
@@ -57,13 +60,49 @@ interface LaneBand {
 interface Layout {
   width: number;
   height: number;
+  axisH: number;
   t0: number;
   t1: number;
+  cut?: number | undefined;
   bands: LaneBand[];
   placed: Map<string, Placed>;
   x: (t: number) => number;
 }
 
+export interface TimeScale {
+  t0: number;
+  t1: number;
+  /** Where the axis switches from real time to the compressed tail; absent when the axis is linear. */
+  cut?: number | undefined;
+  x: (t: number) => number;
+}
+
+function unit(value: number): number {
+  return Math.min(Math.max(0, value), 1);
+}
+
+/**
+ * Real time until the last member exits. The synthesis that follows can outlast discovery, so it
+ * gets a fixed share of the width instead of squeezing the members' work into the left margin.
+ * The cut applies as soon as a parent phase starts after the members are done, so a live run's
+ * main axis freezes the moment synthesis begins; without such a phase only a long tail triggers it.
+ */
+export function graphTimeScale(graph: RunGraph, window: GraphWindow): TimeScale {
+  const { t0, t1 } = windowOf(graph, window);
+  const plotW = window.width;
+  const cut = graph.membersEnd;
+  const phaseAfterMembers = graph.phases.some((phase) => phase.from >= cut && phase.from < t1);
+  const longTail = (t1 - cut) / (t1 - t0) > TAIL_FRACTION;
+  if (cut <= t0 || cut >= t1 || (!phaseAfterMembers && !longTail)) {
+    return { t0, t1, x: (t) => LABEL_W + unit((t - t0) / (t1 - t0)) * plotW };
+  }
+  const mainW = plotW * (1 - TAIL_FRACTION);
+  const tailW = plotW - mainW;
+  const x = (t: number): number =>
+    t <= cut ? LABEL_W + unit((t - t0) / (cut - t0)) * mainW : LABEL_W + mainW + unit((t - cut) / (t1 - cut)) * tailW;
+  return { t0, t1, cut, x };
+}
+
 function nodeWidth(node: GraphNode): number {
   return node.marker ? DOT_R * 2 : Math.max(MIN_BOX_W, Math.round(node.label.length * CHAR_W) + 8);
 }
@@ -75,13 +114,16 @@ function windowOf(graph: RunGraph, window: GraphWindow): { t0: number; t1: numbe
   return { t0, t1: requested > t0 ? requested : t0 + 1_000 };
 }
 
-/** Rows within a lane: a node takes the first row whose last occupant ends before it starts. */
-function packLane(nodes: GraphNode[], x: (t: number) => number, top: number): { placed: Placed[]; rows: number } {
+/**
+ * Rows within a lane: a node takes the first row whose last occupant ends before it starts. A box
+ * anchored near the end of the axis is pulled left so its right edge stays inside the plot.
+ */
+function packLane(nodes: GraphNode[], x: (t: number) => number, top: number, plotEnd: number): { placed: Placed[]; rows: number } {
   const rowEnds: number[] = [];
   const placed: Placed[] = [];
   for (const node of nodes) {
     const w = nodeWidth(node);
-    const left = node.marker ? x(node.at) - DOT_R : x(node.at);
+    const left = node.marker ? x(node.at) - DOT_R : Math.min(x(node.at), plotEnd - w);
     let row = rowEnds.findIndex((end) => end + GAP <= left);
     if (row === -1) row = rowEnds.length;
     rowEnds[row] = left + w;
@@ -91,22 +133,22 @@ function packLane(nodes: GraphNode[], x: (t: number) => number, top: number): {
 }
 
 function layoutGraph(graph: RunGraph, window: GraphWindow): Layout {
-  const { t0, t1 } = windowOf(graph, window);
+  const { t0, t1, cut, x } = graphTimeScale(graph, window);
   const plotW = window.width;
-  const x = (t: number): number => LABEL_W + Math.min(Math.max(0, (t - t0) / (t1 - t0)), 1) * plotW;
   const visible = graph.nodes.filter((node) => node.at >= t0 && node.at <= t1).sort((a, b) => a.at - b.at);
   const placed = new Map<string, Placed>();
   const bands: LaneBand[] = [];
   let y = HEADER_H;
   for (const lane of graph.lanes) {
     const own = visible.filter((node) => node.lane === lane.id);
-    const packed = packLane(own, x, y);
+    const packed = packLane(own, x, y, LABEL_W + plotW);
     for (const item of packed.placed) placed.set(item.node.id, item);
     const h = PAD * 2 + packed.rows * ROW_H;
     bands.push({ lane, y, h });
     y += h;
   }
-  return { width: LABEL_W + plotW + PAD, height: y + AXIS_H, t0, t1, bands, placed, x };
+  const axisH = cut === undefined ? AXIS_H : TAIL_AXIS_H;
+  return { width: LABEL_W + plotW + PAD, height: y + axisH, axisH, t0, t1, cut, bands, placed, x };
 }
 
 function renderDefs(): string {
@@ -117,8 +159,16 @@ function renderDefs(): string {
   return `<defs>${markers.join("")}</defs>`;
 }
 
+/** The full label if the band is wide enough, else the bare id, else nothing; the band's title keeps the full text. */
+function phaseText(id: string, label: string, bandW: number): string | undefined {
+  const fits = (text: string): boolean => text.length * CHAR_W + 6 <= bandW;
+  if (fits(label)) return label;
+  if (fits(id)) return id;
+  return undefined;
+}
+
 function renderPhases(graph: RunGraph, layout: Layout): string {
-  const bottom = layout.height - AXIS_H;
+  const bottom = layout.height - layout.axisH;
   return graph.phases
     .map((phase, index) => {
       const from = Math.max(phase.from, layout.t0);
@@ -127,9 +177,10 @@ function renderPhases(graph: RunGraph, layout: Layout): string {
       const x0 = layout.x(from);
       const w = Math.max(1, layout.x(to) - x0);
       const label = `${phase.id} +${formatElapsed(phase.from - graph.start)} to +${formatElapsed(phase.to - graph.start)}`;
+      const text = phaseText(phase.id, label, w);
       return (
-        `<rect class="phase${index % 2 ? " phase-alt" : ""}" x="${px(x0)}" y="${HEADER_H - 16}" width="${px(w)}" height="${px(bottom - HEADER_H + 16)}"/>` +
-        `<text x="${px(x0 + 3)}" y="${HEADER_H - 5}" class="phase-label"><title>${e(label)}</title>${e(label)}</text>`
+        `<rect class="phase${index % 2 ? " phase-alt" : ""}" x="${px(x0)}" y="${HEADER_H - 16}" width="${px(w)}" height="${px(bottom - HEADER_H + 16)}"><title>${e(label)}</title></rect>` +
+        (text === undefined ? "" : `<text x="${px(x0 + 3)}" y="${HEADER_H - 5}" class="phase-label">${e(text)}</text>`)
       );
     })
     .join("");
@@ -146,17 +197,36 @@ function renderLanes(layout: Layout): string {
     .join("");
 }
 
+function tick(graph: RunGraph, layout: Layout, t: number, cls: string): string {
+  const x = layout.x(t);
+  const y = layout.height - layout.axisH;
+  const anchor = t >= layout.t1 ? ` text-anchor="end" x="${px(x - 2)}"` : ` x="${px(x + 2)}"`;
+  return (
+    `<line class="tick" x1="${px(x)}" y1="${HEADER_H}" x2="${px(x)}" y2="${px(y)}"/>` +
+    `<text${anchor} y="${px(y + 12)}" class="${cls}">+${e(formatElapsed(t - graph.start))}</text>`
+  );
+}
+
+/** Regular ticks up to the cut; past it only phase boundaries and the end, since the scale differs. */
 function renderAxis(graph: RunGraph, layout: Layout): string {
-  const span = layout.t1 - layout.t0;
+  const mainEnd = layout.cut ?? layout.t1;
+  const span = mainEnd - layout.t0;
   const step = TICK_STEPS_MS.find((candidate) => span / candidate <= MAX_TICKS) ?? TICK_STEPS_MS[TICK_STEPS_MS.length - 1]!;
   const firstTick = graph.start + Math.ceil((layout.t0 - graph.start) / step) * step;
   const parts: string[] = [];
-  const y = layout.height - AXIS_H;
-  for (let t = firstTick; t <= layout.t1; t += step) {
-    const x = layout.x(t);
-    parts.push(`<line class="tick" x1="${px(x)}" y1="${HEADER_H}" x2="${px(x)}" y2="${px(y)}"/>`);
-    parts.push(`<text x="${px(x + 2)}" y="${px(y + 12)}" class="tick-label">+${e(formatElapsed(t - graph.start))}</text>`);
-  }
+  for (let t = firstTick; t <= mainEnd; t += step) parts.push(tick(graph, layout, t, "tick-label"));
+  if (layout.cut === undefined) return parts.join("");
+  const bottom = layout.height - layout.axisH;
+  const cx = layout.x(layout.cut);
+  parts.push(`<line class="cut" x1="${px(cx)}" y1="${HEADER_H - 16}" x2="${px(cx)}" y2="${px(bottom)}"/>`);
+  const note = `members done +${formatElapsed(layout.cut - graph.start)}; the rest is compressed`;
+  parts.push(`<text x="${px(cx - 3)}" y="${px(bottom + 24)}" text-anchor="end" class="tick-label tail">${e(note)}</text>`);
+  // One tick per distinct second: phase boundaries and the end often sit milliseconds apart.
+  const { cut, t1 } = layout;
+  const tailTicks = new Map<string, number>();
+  const candidates = graph.phases.flatMap((phase) => [phase.from, phase.to]).filter((t) => t > cut && t < t1);
+  for (const t of [...candidates, layout.t1]) tailTicks.set(formatElapsed(t - graph.start), t);
+  for (const t of [...tailTicks.values()].sort((a, b) => a - b)) parts.push(tick(graph, layout, t, "tick-label tail"));
   return parts.join("");
 }
 
@@ -216,6 +286,7 @@ export const GRAPH_CSS =
   ".graph{overflow:auto;border:1px solid #000;margin:4px 0;background:#fff}" +
   "svg text{fill:#000}svg .phase{fill:#000;opacity:.04}svg .phase-alt{opacity:.09}svg .phase-label{font-weight:bold}" +
   "svg .lane-line{stroke:#bbb}svg .tick{stroke:#e5e5e5}svg .tick-label{fill:#555}" +
+  "svg .cut{stroke:#999;stroke-width:1.5;stroke-dasharray:4 3}svg .tail{font-style:italic}" +
   "svg .n{stroke:#000;stroke-width:1}svg .n-prior{stroke-dasharray:3 2}" +
   "svg .m{stroke:#333;stroke-width:1}svg .m-rejected{stroke:#c62828;stroke-width:2}svg .m-noop{stroke-dasharray:2 1}" +
   "svg a:hover .n,svg a:hover .m{stroke-width:2.5}svg a:hover text{text-decoration:underline}" +

package/src/run-graph.ts

@@ -54,6 +54,8 @@ export interface RunGraph {
   runId: string;
   start: number;
   end: number;
+  /** When the last member activity happened; equals `end` while members still run. */
+  membersEnd: number;
   lanes: GraphLane[];
   phases: GraphPhase[];
   nodes: GraphNode[];
@@ -553,6 +555,16 @@ function phasesOf(draft: Draft, nodes: GraphNode[], start: number, end: number):
   return phases;
 }
 
+const TERMINAL_STATUSES = new Set(["done", "failed", "stopped"]);
+
+/** The last member-lane event once every member has exited; the whole span while any still runs. */
+function membersEndOf(nodes: GraphNode[], members: GraphMember[], live: boolean, start: number, end: number): number {
+  const running = live && members.some((m) => m.status !== undefined && !TERMINAL_STATUSES.has(m.status));
+  if (running) return end;
+  const times = nodes.filter((n) => n.lane !== "parent" && !n.placeholder).map((n) => n.at);
+  return Math.min(end, Math.max(start, ...times));
+}
+
 /** Project a run's events (plus what the parent knows about its members) into lanes, phases, nodes, and edges. */
 export function buildRunGraph(input: RunGraphInput): RunGraph {
   const events = input.events.filter((event) => event.outcome !== "intent");
@@ -570,6 +582,7 @@ export function buildRunGraph(input: RunGraphInput): RunGraph {
     runId: input.runId,
     start,
     end,
+    membersEnd: membersEndOf(nodes, members, input.now !== undefined, start, end),
     lanes: lanesOf(draft, nodes, members),
     phases: phasesOf(draft, nodes, start, end),
     nodes,