pi-agent-fleet 0.4.0 → 0.5.0

package/README.md

@@ -42,7 +42,13 @@ Ask your pi session (the LLM drives the tools):
 > combiner (depends on both) writes output/sum.md with the total.
 > Each declares its output as a markdown contract.
 
-The agent calls `fleet_design` (if you describe it in prose) or `fleet_plan` (if you already have JSON), you confirm the preview, then `fleet_launch` runs it. Watch the live widget or open the browser canvas; read the report at `.fleet/<name>-<ts>/report.md`.
+The agent calls `fleet_design` (if you describe it in prose) or `fleet_plan` (if you already have JSON), you confirm the preview, then `fleet_launch` runs it. Plan and launch responses include a fleet canvas link by default; the in-chat widget is hidden until you run `/fleet viz`. Read the report at `.fleet/<name>-<ts>/report.md`.
+
+JSON pipeline variant — a numeric handoff chain where workers pass typed JSON, verified by schemas at contract check:
+
+> Plan and launch the fleet defined in `examples/json-number-pipeline.json`.
+
+One writer emits `{"values":[3,5,8]}`, two parallel consumers add and subtract, a synthesizer combines the results — each output declared as a `json` contract with a `schema` naming its required and numeric keys.
 
 ## Writing a fleet
 
@@ -78,7 +84,7 @@ The agent calls `fleet_design` (if you describe it in prose) or `fleet_plan` (if
 
 - `config.model` / `config.effort` — fleet-wide defaults; per-worker `model` and `effort` override.
 - `effort` maps to pi thinking levels: `off | minimal | low | medium | high | xhigh | max`.
-- `config.warn_cost_usd` — soft cost guardrail surfaced in the live widget.
+- `config.warn_cost_usd` — soft cost guardrail surfaced in the canvas and report.
 - `iterate: false` — run the node once at iteration 1 and carry its outputs forward.
 - `worktree: true` — run the node in a dedicated git worktree.
 - Worker types `research`, `code-run`, `reviewer`, `write`, `read-only` each get a tailored tool set.
@@ -112,9 +118,16 @@ Every worker declares `outputs[]` with kinds, verified in code at worker exit be
 | `markdown` | exists, non-empty, starts with `#` |
 | `file-exists` | exists, non-empty (repo-relative paths = code edits) |
 | `verdict` | `verdict: lgtm\|iterate\|escalate` line + non-empty body |
-| `json` | parses as JSON |
+| `json` | parses as JSON; optional `schema` checks (below) |
 | `yaml` | parses as YAML |
 
+JSON outputs may declare a `schema` with `required_keys` (keys that must exist) and `number_keys` (keys that must be numbers or arrays of numbers). Schemas are only allowed on `kind: "json"` outputs, are injected into the worker's prompt, and are enforced at contract check. When a `schema` is present, the JSON must be a top-level object (arrays and scalars fail):
+
+```json
+{ "path": "output/sum.json", "kind": "json", "required": true,
+  "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }
+```
+
 Failed required contract → `contract_failed`, dependents blocked, orchestrator notified. No silent passes.
 
 ## Tools & commands
@@ -123,8 +136,10 @@ Failed required contract → `contract_failed`, dependents blocked, orchestrator
 |---|---|
 | `fleet_design` | draft a fleet DAG from plain-language requirements (planner agent → validated JSON + preview) |
 | `fleet_plan` | validate + preview a fleet definition (no launch) |
+| `fleet_models` | list available model refs (provider/id) from the live registry — call before `fleet_plan` if you don't know exact model IDs |
 | `fleet_launch` | launch the planned fleet after user confirmation; `skip_confirm` for unattended runs |
-| `fleet_status` | live DAG status and widget lines |
+| `fleet_status` | live DAG status and text summary |
+| `fleet_continue` | resume a failed/killed fleet from current state without restarting completed nodes |
 | `fleet_pause` / `fleet_resume` | pause/resume loop fleets at the next iteration boundary |
 | `fleet_kill` | kill all, or kill a single node by worker id |
 | `fleet_relaunch` | re-run a failed/killed node and its blocked downstream; optional model override |
@@ -133,7 +148,7 @@ Failed required contract → `contract_failed`, dependents blocked, orchestrator
 | `fleet_report` | regenerate the fleet markdown report |
 | `fleet_canvas` | open a browser canvas; `?demo=1` shows synthetic data for UI iteration |
 
-`/fleet viz | status | clear | pause | resume | kill all|<node_id> | relaunch <id> [model] | add <json> | edit <node_id>|config ... | configure [show|set k v] | canvas [open|url|stop]`
+`/fleet viz | status | clear | pause | resume | continue | kill all|<node_id> | relaunch <id> [model] | add <json> | edit <node_id>|config ... | configure [show|set k v] | canvas [open|url|stop]`
 
 ## Runtime mutation
 
@@ -156,7 +171,7 @@ These are merged into `fleet_plan` results. Manage them with `/fleet configure s
 
 ## Records
 
-Everything lands in `.fleet/<name>-<ts>/` (git-ignored): `state.json` (single source of truth, atomic writes), per-worker `prompt.md` + `session.jsonl` + outputs, per-iteration archives, and a machine-written `report.md` with per-worker turns/tokens/cost, contract results, verdict history, and git diff stats. Completed nodes keep their stats visible in the widget and report after the fleet ends.
+Everything lands in `.fleet/<name>-<ts>/` (git-ignored): `state.json` (single source of truth, atomic writes), per-worker `prompt.md` + `session.jsonl` + outputs, per-iteration archives, and a machine-written `report.md` with per-worker turns/tokens/cost, contract results, verdict history, and git diff stats. Completed nodes keep their stats visible in the canvas and report after the fleet ends.
 
 ## Model selection and effort
 
@@ -172,11 +187,11 @@ Model refs are validated at plan and launch time so bad names fail fast. There i
 
 ```bash
 npm install
-npm test          # 232 tests, zero-API (fake session factory)
+npm test          # 274 tests, zero-API (fake session factory)
 npm run typecheck
 ```
 
-Design docs live in `docs/superpowers/specs/`; experiment history in `docs/experiments/`.
+Design docs are archived locally under `.archive/docs/superpowers/` (not tracked); experiment history in `docs/experiments/`.
 
 ## License
 

package/examples/json-number-pipeline.json

@@ -0,0 +1,35 @@
+{
+  "fleet_name": "json-number-pipeline",
+  "type": "dag",
+  "config": { "max_concurrent": 2 },
+  "workers": [
+    {
+      "id": "write-numbers",
+      "type": "write",
+      "task": "Write output/numbers.json containing exactly {\"values\":[3,5,8]}. No markdown. No commentary.",
+      "depends_on": [],
+      "outputs": [{ "path": "output/numbers.json", "kind": "json", "required": true, "schema": { "required_keys": ["values"], "number_keys": ["values"] } }]
+    },
+    {
+      "id": "add-numbers",
+      "type": "write",
+      "task": "Read output/numbers.json from write-numbers. Write output/sum.json containing {\"operation\":\"add\",\"result\":16}.",
+      "depends_on": ["write-numbers"],
+      "outputs": [{ "path": "output/sum.json", "kind": "json", "required": true, "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }]
+    },
+    {
+      "id": "subtract-numbers",
+      "type": "write",
+      "task": "Read output/numbers.json from write-numbers. Write output/difference.json containing {\"operation\":\"subtract\",\"result\":-10} using first value minus the rest.",
+      "depends_on": ["write-numbers"],
+      "outputs": [{ "path": "output/difference.json", "kind": "json", "required": true, "schema": { "required_keys": ["operation", "result"], "number_keys": ["result"] } }]
+    },
+    {
+      "id": "synthesize",
+      "type": "write",
+      "task": "Read output/sum.json and output/difference.json. Write output/final.json containing {\"sum\":16,\"difference\":-10,\"combined\":6} where combined = sum + difference.",
+      "depends_on": ["add-numbers", "subtract-numbers"],
+      "outputs": [{ "path": "output/final.json", "kind": "json", "required": true, "schema": { "required_keys": ["sum", "difference", "combined"], "number_keys": ["sum", "difference", "combined"] } }]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-fleet",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "DAG-of-agents fleets for pi — parallel workers with contracts, reviewer-gated iteration loops, and live progress",
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/sagarsrc/pi-agent-fleet/v0.4.0/assets/canvas.png"
+    "image": "https://raw.githubusercontent.com/sagarsrc/pi-agent-fleet/v0.5.0/assets/canvas.png"
   },
   "license": "MIT",
   "author": "Sagar Sarkale",

package/src/canvas-client.tsx

@@ -54,7 +54,26 @@ interface CanvasPayload {
 }
 interface FleetInfo { name: string; status: string }
 interface SessionEntry { role: string; text: string }
-interface SessionResp { entries: SessionEntry[]; task?: string }
+interface ActionView {
+  type: "tool_call" | "tool_result" | "model_change" | "thinking_level_change" | "complete";
+  name?: string;
+  toolName?: string;
+  arguments?: Record<string, unknown>;
+  provider?: string;
+  modelId?: string;
+  thinkingLevel?: string;
+  stopReason?: string;
+  isError?: boolean;
+  timestamp?: string;
+}
+type TimelineEvent =
+  | { type: "message"; role: string; text: string; timestamp?: string }
+  | { type: "tool_call"; name: string; arguments?: Record<string, unknown>; timestamp?: string }
+  | { type: "tool_result"; toolName?: string; isError?: boolean; text?: string; timestamp?: string }
+  | { type: "model_change"; provider: string; modelId: string; timestamp?: string }
+  | { type: "thinking_level_change"; thinkingLevel: string; timestamp?: string }
+  | { type: "complete"; stopReason: string; timestamp?: string };
+interface SessionResp { entries: SessionEntry[]; actions: ActionView[]; events: TimelineEvent[]; task?: string }
 
 /* ---------- helpers ---------- */
 const NODE_W = 284;
@@ -202,6 +221,134 @@ function FleetNode({ data }: NodeProps<Node<FleetNodeData>>) {
 const nodeTypes = { fleet: FleetNode };
 
 /* ---------- side panel ---------- */
+function CollapsiblePrompt({ title, text }: { title: string; text: string }) {
+  const [open, setOpen] = useState(true);
+  if (!text) return null;
+  return (
+    <div className={"collapsible" + (open ? "" : " collapsed")}>
+      <button className="collapsible-head" onClick={() => setOpen((v) => !v)} aria-expanded={open}>
+        <span className="chevron">{open ? "-" : "+"}</span>
+        <span>{title}</span>
+      </button>
+      <div className="collapsible-body">{text}</div>
+    </div>
+  );
+}
+
+function formatActionDetail(a: { arguments?: Record<string, unknown> }): string {
+  const args = a.arguments || {};
+  if (typeof args.path === "string") return args.path;
+  if (typeof args.command === "string") return args.command;
+  if (Array.isArray(args.queries)) return String(args.queries[0]);
+  const keys = Object.keys(args);
+  if (keys[0]) return `${keys[0]}: ${JSON.stringify(args[keys[0]]).slice(0, 40)}`;
+  return "";
+}
+
+function TimelineItem({ event }: { event: TimelineEvent }) {
+  const [open, setOpen] = useState(event.isError ? true : false);
+  const ts = event.timestamp ? new Date(event.timestamp).toLocaleTimeString([], { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" }) : "";
+  if (event.type === "message") {
+    return (
+      <div className={"timeline-msg" + (event.role === "assistant" ? " assistant" : event.role === "user" ? " user" : "")}>
+        <div className="timeline-meta">
+          <span className="role">{event.role}</span>
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+        <div className="timeline-text">{event.text}</div>
+      </div>
+    );
+  }
+  if (event.type === "tool_call") {
+    const detail = formatActionDetail(event);
+    const hasArgs = !!event.arguments && Object.keys(event.arguments).length > 0;
+    return (
+      <div className={"timeline-action" + (open ? " open" : "")}>
+        <div className="timeline-row">
+          <button className="activity-toggle" onClick={() => setOpen((v) => !v)} aria-expanded={open} title={open ? "collapse" : "expand"}>{open ? "-" : "+"}</button>
+          <span className="action-icon">call</span>
+          <span className="action-name">{event.name}</span>
+          {detail && <span className="action-detail" title={detail}>{detail}</span>}
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+        {open && hasArgs && (
+          <div className="activity-body">
+            <pre>{JSON.stringify(event.arguments, null, 2)}</pre>
+          </div>
+        )}
+      </div>
+    );
+  }
+  if (event.type === "tool_result") {
+    const hasText = !!event.text && event.text.length > 0;
+    const expanded = open;
+    return (
+      <div className={"timeline-action" + (event.isError ? " action-error" : "") + (expanded ? " open" : "")}>
+        <div className="timeline-row">
+          <button className="activity-toggle" onClick={() => setOpen((v) => !v)} aria-expanded={expanded} title={expanded ? "collapse" : "expand"}>{expanded ? "-" : "+"}</button>
+          <span className={"action-icon" + (event.isError ? " action-error" : "")}>{event.isError ? "err" : "ok"}</span>
+          <span className="action-name">{event.toolName || "result"}</span>
+          {event.text && <span className={"action-detail" + (event.isError ? " action-error" : "")} title={event.text}>{event.isError ? "Error: " : ""}{event.text}</span>}
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+        {expanded && hasText && (
+          <div className="activity-body">
+            {event.isError ? <strong>Error: </strong> : null}
+            {event.text}
+          </div>
+        )}
+      </div>
+    );
+  }
+  if (event.type === "model_change") {
+    return (
+      <div className="timeline-action">
+        <div className="timeline-row">
+          <span className="action-icon">mdl</span>
+          <span className="action-name">model</span>
+          <span className="action-detail">{event.provider}/{event.modelId}</span>
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+      </div>
+    );
+  }
+  if (event.type === "thinking_level_change") {
+    return (
+      <div className="timeline-action">
+        <div className="timeline-row">
+          <span className="action-icon">think</span>
+          <span className="action-name">thinking</span>
+          <span className="action-detail">{event.thinkingLevel}</span>
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+      </div>
+    );
+  }
+  if (event.type === "complete") {
+    return (
+      <div className="timeline-action">
+        <div className="timeline-row">
+          <span className="action-icon">done</span>
+          <span className="action-name">done</span>
+          {event.stopReason !== "complete" && event.stopReason !== "stop" && <span className="action-detail">{event.stopReason}</span>}
+          {ts && <span className="ts">{ts}</span>}
+        </div>
+      </div>
+    );
+  }
+  return null;
+}
+
+function Timeline({ events }: { events: TimelineEvent[] }) {
+  const visible = events.filter((e) => e.type !== "model_change" && e.type !== "thinking_level_change");
+  if (!visible.length) return <div className="timeline-empty">No session data yet.</div>;
+  return (
+    <div className="timeline" aria-label="Agent session timeline">
+      {visible.map((e, i) => <TimelineItem event={e} key={e.type + (e.timestamp || "") + "-" + i} />)}
+    </div>
+  );
+}
+
 function SidePanel({ fleet, demo, selected, task, onClose }: { fleet: string | null; demo: boolean; selected: string | null; task: string | null; onClose: () => void }) {
   const [resp, setResp] = useState<SessionResp | null>(null);
   const boxRef = useRef<HTMLDivElement>(null);
@@ -214,11 +361,12 @@ function SidePanel({ fleet, demo, selected, task, onClose }: { fleet: string | n
   };
 
   useEffect(() => {
-    if (!selected || demo) { setResp(null); return; }
+    if (!selected) { setResp(null); return; }
     let alive = true;
     const load = () => {
       const q = fleet ? "&fleet=" + encodeURIComponent(fleet) : "";
-      j<SessionResp>("/api/session/" + selected + "?tail=30" + q).then((r) => alive && setResp(r)).catch(() => {});
+      const demoQ = demo ? "&demo=1" : "";
+      j<SessionResp>("/api/session/" + selected + "?tail=30" + q + demoQ).then((r) => alive && setResp(r)).catch(() => {});
     };
     load();
     const t = setInterval(load, 2000);
@@ -246,26 +394,29 @@ function SidePanel({ fleet, demo, selected, task, onClose }: { fleet: string | n
     if (nearBottom) el.scrollTop = el.scrollHeight;
   }, [resp]);
 
+  const latestModel = resp?.events?.slice().reverse().find((e): e is TimelineEvent & { type: "model_change" } => e.type === "model_change");
+  const latestThinking = resp?.events?.slice().reverse().find((e): e is TimelineEvent & { type: "thinking_level_change" } => e.type === "thinking_level_change");
   if (!selected) return null;
   return (
-    <div id="side" className="open" ref={boxRef} tabIndex={-1} role="complementary" aria-label={`${selected} session`}>
+    <div id="side" className="open" role="complementary" aria-label={`${selected} session`}>
       <div className="side-head">
-        <span className="meta"># {selected} — session</span>
+        <span className="meta"><span className="side-hash">#</span> <strong className="side-id">{selected}</strong> — session</span>
         <button className="icon-btn" onClick={closeAndRestore} aria-label="Close session panel" title="Close (Esc)">×</button>
+        {(!!latestModel || !!latestThinking) && (
+          <div className="side-meta">
+            {latestModel && <span className="side-meta-chip">{latestModel.provider}/{latestModel.modelId}</span>}
+            {latestThinking && <span className="side-meta-chip">thinking: {latestThinking.thinkingLevel}</span>}
+          </div>
+        )}
+      </div>
+      <div className="side-body" ref={boxRef} tabIndex={-1}>
+        <CollapsiblePrompt title="Instructions" text={resp?.task || task || ""} />
+        {resp === null ? (
+          <div className="timeline-loading"><span className="spinner" aria-hidden="true" /> Loading session…</div>
+        ) : (
+          <Timeline events={resp.events ?? []} />
+        )}
       </div>
-      {(resp?.task || task) && (
-        <div className="taskbox-side">
-          <div className="taskbox-side-label">task</div>
-          {resp?.task || task}
-        </div>
-      )}
-      {demo && <div className="msg">Session transcripts hidden in demo mode.</div>}
-      {(resp?.entries ?? []).map((e, i) => (
-        <div className="msg" key={i}>
-          <div className={"role role-" + e.role}>{e.role}</div>
-          {e.text}
-        </div>
-      ))}
     </div>
   );
 }