pi-agent-fleet 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagar Sarkale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# pi-agent-fleet
+
+DAG-of-agents fleets for [pi](https://github.com/earendil-works/pi-coding-agent). Define a fleet of worker agents as data, preview it, launch it, watch it run — with per-worker output contracts, reviewer-gated iteration loops, live cost tracking, and a machine-written report.
+
+```
+● fleet: cost-relaunch-build · iteration 1/3 · last verdict: iterate · streak 0/1 (2/3 done · $1.42)
+├─ ✓ builder-pricing (kimi-for-coding) · 32 turns · 945k tok · $0.83
+├─ ⠹ builder-relaunch (kimi-for-coding) · 12 turns · 401k tok · editing src/scheduler.ts…
+└─ ○ reviewer (k3) · waiting on builder-relaunch
+```
+
+## Why
+
+One agent is a tool. A **fleet** is a workflow: researchers feed builders, builders feed reviewers, reviewers gate quality — all visible, all recorded, all contract-checked. Fleets run in-process via pi's SDK: any provider pi is logged into (Claude, Codex, Kimi, …) works per-node.
+
+Philosophy: no auto-restart, no auto-kill, no babysitting. Failures surface; the operator decides. Contracts are checked at worker exit. The reviewer is the quality gate; you are the kill switch.
+
+## Install
+
+```bash
+pi install npm:pi-agent-fleet                    # from npm
+pi install git:github.com/sagarsrc/pi-agent-fleet # from git
+pi install /path/to/pi-agent-fleet               # local
+```
+
+## Quickstart
+
+Ask your pi session (the LLM drives the tools):
+
+> Plan and launch a fleet: two parallel writers and a combiner, all gpt-5.4-mini.
+> writer-a writes output/a.md containing "# 123", writer-b writes output/b.md containing "# 456",
+> combiner (depends on both) writes output/sum.md with the total.
+> Each declares its output as a markdown contract.
+
+The agent calls `fleet_plan` (validates + ASCII preview), you confirm, `fleet_launch` runs it. Watch the live widget; read the report at `.fleet/<name>-<ts>/report.md`.
+
+## Fleet modes
+
+**One-shot DAG** — static dependency graph, parallel layers, contracts at exit:
+
+```json
+{
+  "fleet_name": "auth-research",
+  "type": "dag",
+  "config": { "max_concurrent": 4, "model": "gpt-5.4-mini" },
+  "workers": [
+    { "id": "research", "type": "research", "task": "…",
+      "outputs": [{ "path": "output/findings.md", "kind": "markdown", "required": true }] },
+    { "id": "build", "type": "code-run", "task": "…", "depends_on": ["research"],
+      "outputs": [{ "path": "src/auth/login.ts", "kind": "file-exists", "required": true }] }
+  ]
+}
+```
+
+**Iterative fleet** — reviewer-gated replay until quality passes:
+
+```json
+{
+  "config": {
+    "loop": { "gate": "reviewer", "max_iterations": 5, "lgtm_count": 2 }
+  }
+}
+```
+
+A reviewer node writes a verdict contract (`verdict: lgtm | iterate | escalate` + actionable body). `iterate` → builders get the review injected as feedback next iteration. `lgtm` × `lgtm_count` consecutive → completed. `escalate` → fleet pauses and notifies you. `gate: "none"` → free-running loop (autoresearch pattern: eval instructions live in the worker's task text).
+
+**Worktree mode** — `worktree: true` on a node: the worker is directed to create its own git worktree at a designated path/branch. Downstream nodes see upstream worktree paths/branches in their prompts. The extension runs zero git commands; conflicts are resolved by resolver nodes you add to the DAG.
+
+**Run-once vs replay nodes** — `iterate: false`: node runs at iteration 1 only, outputs carry over (e.g. research that doesn't change).
+
+## Contracts
+
+Every worker declares `outputs[]` with kinds, verified in code at worker exit before dependents are released:
+
+| kind | check |
+|---|---|
+| `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` / `yaml` | parses |
+
+Failed required contract → `contract_failed`, dependents blocked, orchestrator notified. No silent passes.
+
+## Tools & commands
+
+| tool | purpose |
+|---|---|
+| `fleet_plan` | validate + preview a fleet definition (no launch) |
+| `fleet_launch` | launch (confirm gate, `skip_confirm` for unattended) |
+| `fleet_status` | live DAG status |
+| `fleet_pause` / `fleet_resume` | pause/resume loop fleets at iteration boundary |
+| `fleet_relaunch` | re-run a failed node (+ blocked downstream), optional model override |
+| `fleet_kill` | fleet-wide kill |
+| `fleet_report` | regenerate report.md |
+
+`/fleet viz | status | clear | pause | resume | relaunch <id> [model] | kill all`
+
+## 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.
+
+## Model selection
+
+Fleet-wide default via `config.model`; per-node override via `worker.model`. Any model pi can resolve — including any provider pi is logged into. Cheap models for trivial writers, strong models for reviewers:
+
+```json
+{ "id": "reviewer", "type": "reviewer", "model": "kimi-coding/k3", … }
+```
+
+## Development
+
+```bash
+npm install
+npm test          # 111 tests, zero-API (fake session factory)
+npm run typecheck
+```
+
+Design docs live in `docs/superpowers/specs/`; experiment history in `docs/experiments/`.
+
+## License
+
+MIT

package/examples/two-worker-fleet.json

@@ -0,0 +1,21 @@
+{
+  "fleet_name": "smoke",
+  "type": "dag",
+  "config": { "max_concurrent": 2, "model": "gpt-5.4-mini" },
+  "workers": [
+    {
+      "id": "research",
+      "type": "write",
+      "task": "Write a markdown file with a heading and exactly 3 bullet points about good CLI UX. Under 60 words total.",
+      "depends_on": [],
+      "outputs": [{ "path": "output/findings.md", "kind": "markdown", "required": true }]
+    },
+    {
+      "id": "summarize",
+      "type": "write",
+      "task": "Read the upstream findings file and write a markdown file with a heading and one sentence summary.",
+      "depends_on": ["research"],
+      "outputs": [{ "path": "output/summary.md", "kind": "markdown", "required": true }]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-agent-fleet",
+  "version": "0.2.0",
+  "description": "DAG-of-agents fleets for pi \u2014 parallel workers with contracts, reviewer-gated iteration loops, and live progress",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@earendil-works/pi-ai": "^0.80.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0",
+    "@types/node": "^22.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "license": "MIT",
+  "author": "Sagar Sarkale",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sagarsrc/pi-agent-fleet.git"
+  },
+  "bugs": "https://github.com/sagarsrc/pi-agent-fleet/issues",
+  "homepage": "https://github.com/sagarsrc/pi-agent-fleet#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "agents",
+    "multi-agent",
+    "dag",
+    "fleet",
+    "orchestration"
+  ],
+  "files": [
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/contracts.ts

@@ -0,0 +1,78 @@
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { ContractCheck, ContractOutput, ContractResult, Verdict } from "./types.js";
+
+export const VERDICT_RE = /^verdict:\s*(lgtm|iterate|escalate)\s*$/mi;
+
+function resolvePath(workerDir: string, repoCwd: string, p: string): string {
+  if (isAbsolute(p)) return p;
+  return p.startsWith("output/") ? join(workerDir, p) : join(repoCwd, p);
+}
+
+async function checkOne(workerDir: string, repoCwd: string, o: ContractOutput): Promise<ContractCheck> {
+  const full = resolvePath(workerDir, repoCwd, o.path);
+  const fail = (error: string): ContractCheck => ({ path: o.path, kind: o.kind, required: o.required, ok: false, error });
+  let content: string;
+  try {
+    const s = await stat(full);
+    if (o.kind === "file-exists") {
+      return s.size > 0
+        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
+        : fail("empty file");
+    }
+    content = await readFile(full, "utf-8");
+  } catch {
+    return fail("file not found");
+  }
+  switch (o.kind) {
+    case "markdown": {
+      const first = content.split("\n").find((l) => l.trim().length > 0) ?? "";
+      return first.startsWith("#")
+        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
+        : fail("no markdown heading");
+    }
+    case "verdict": {
+      const m = content.match(VERDICT_RE);
+      if (!m) return fail("no verdict line");
+      const body = content.slice(content.indexOf(m[0]) + m[0].length).trim();
+      return body.length > 0
+        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
+        : fail("verdict line without body");
+    }
+    case "json":
+      try {
+        JSON.parse(content);
+        return { path: o.path, kind: o.kind, required: o.required, ok: true };
+      } catch (e) {
+        return fail(`json parse error: ${(e as Error).message}`);
+      }
+    case "yaml": {
+      const bad = content.split("\n").some((l) => l.includes("\t"));
+      return content.trim().length > 0 && !bad
+        ? { path: o.path, kind: o.kind, required: o.required, ok: true }
+        : fail("empty or invalid yaml");
+    }
+    default:
+      return fail(`unknown kind`);
+  }
+}
+
+export async function verifyOutputs(opts: {
+  workerDir: string;
+  repoCwd: string;
+  outputs: ContractOutput[];
+}): Promise<ContractResult> {
+  const checks = await Promise.all(opts.outputs.map((o) => checkOne(opts.workerDir, opts.repoCwd, o)));
+  const ok = checks.every((c) => !c.required || c.ok);
+
+  const verdictCheck = checks.find((c) => c.kind === "verdict" && c.ok);
+  if (!verdictCheck) return { ok, checks };
+
+  const content = await readFile(resolvePath(opts.workerDir, opts.repoCwd, verdictCheck.path), "utf-8");
+  const m = content.match(VERDICT_RE);
+  if (!m) return { ok, checks };
+
+  const verdict = m[1].toLowerCase() as Verdict;
+  const verdict_body = content.slice(content.indexOf(m[0]) + m[0].length).trim();
+  return verdict_body.length > 0 ? { ok, checks, verdict, verdict_body } : { ok, checks };
+}

package/src/dag.ts

@@ -0,0 +1,190 @@
+import type { FleetSpec, GateKind, LoopConfig, OutputKind, WorkerSpec, WorkerType } from "./types.js";
+
+export class CycleError extends Error {
+  constructor(public remaining: string[]) {
+    super(`CYCLE:${remaining.join(",")}`);
+    this.name = "CycleError";
+  }
+}
+
+const WORKER_TYPES: WorkerType[] = ["research", "code-run", "reviewer", "write", "read-only"];
+const KINDS: OutputKind[] = ["markdown", "file-exists", "verdict", "json", "yaml"];
+const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export function topoLayers(spec: FleetSpec): string[][] {
+  const ids = spec.workers.map((w) => w.id);
+  const indeg = new Map<string, number>(ids.map((id) => [id, 0]));
+  const rev = new Map<string, string[]>(ids.map((id) => [id, []]));
+  for (const w of spec.workers) {
+    for (const d of w.depends_on) {
+      indeg.set(w.id, (indeg.get(w.id) ?? 0) + 1);
+      rev.get(d)?.push(w.id);
+    }
+  }
+  const layers: string[][] = [];
+  let current = ids.filter((id) => indeg.get(id) === 0);
+  let placed = 0;
+  while (current.length > 0) {
+    layers.push(current);
+    placed += current.length;
+    const next: string[] = [];
+    for (const n of current) {
+      for (const m of rev.get(n) ?? []) {
+        const v = (indeg.get(m) ?? 0) - 1;
+        indeg.set(m, v);
+        if (v === 0) next.push(m);
+      }
+    }
+    current = next;
+  }
+  if (placed !== ids.length) {
+    throw new CycleError(ids.filter((id) => !layers.flat().includes(id)));
+  }
+  return layers;
+}
+
+export function getDependents(spec: FleetSpec, nodeId: string): string[] {
+  return spec.workers.filter((w) => w.depends_on.includes(nodeId)).map((w) => w.id);
+}
+
+export function validateFleetSpec(
+  raw: unknown,
+): { ok: true; spec: FleetSpec; layers: string[][] } | { ok: false; errors: string[] } {
+  const errors: string[] = [];
+  const r = raw as Record<string, unknown>;
+  if (typeof r?.fleet_name !== "string" || !ID_RE.test(r.fleet_name)) {
+    errors.push("fleet_name must be non-empty kebab-case");
+  }
+  if (r?.type !== "dag") errors.push('type must be "dag"');
+  const cfg = (r?.config ?? {}) as Record<string, unknown>;
+  const maxConcurrent = typeof cfg.max_concurrent === "number" ? cfg.max_concurrent : 4;
+  if (maxConcurrent < 1) errors.push("config.max_concurrent must be >= 1");
+  const model = typeof cfg.model === "string" ? cfg.model : "gpt-5.4";
+  const warnCost = typeof cfg.warn_cost_usd === "number" ? cfg.warn_cost_usd : undefined;
+
+  const rawWorkers = Array.isArray(r?.workers) ? (r.workers as Record<string, unknown>[]) : [];
+  if (rawWorkers.length === 0) errors.push("at least one worker required");
+
+  const seen = new Set<string>();
+  const workers: WorkerSpec[] = [];
+  for (const w of rawWorkers) {
+    const id = typeof w.id === "string" ? w.id : "";
+    if (!ID_RE.test(id)) errors.push(`worker id "${id}" must match ${ID_RE}`);
+    if (seen.has(id)) errors.push(`duplicate worker id "${id}"`);
+    seen.add(id);
+    const type = w.type as WorkerType;
+    if (!WORKER_TYPES.includes(type)) errors.push(`worker "${id}": bad type "${String(w.type)}"`);
+    if (typeof w.task !== "string" || w.task.length === 0) errors.push(`worker "${id}": task required`);
+    const outputs = (Array.isArray(w.outputs) ? w.outputs : []) as Record<string, unknown>[];
+    for (const o of outputs) {
+      if (!KINDS.includes(o.kind as OutputKind)) errors.push(`worker "${id}": bad output kind "${String(o.kind)}"`);
+      if (typeof o.path !== "string" || o.path.length === 0) errors.push(`worker "${id}": output path required`);
+      if (typeof o.path === "string" && o.path.length > 0) {
+        const segments = o.path.split(/[/\\]/);
+        if (o.path.startsWith("/") || /^[A-Za-z]:/.test(o.path) || segments.includes("..")) {
+          errors.push(`worker "${id}": output path must be relative and stay within the repo`);
+        }
+      }
+    }
+    workers.push({
+      id,
+      type,
+      task: String(w.task ?? ""),
+      model: typeof w.model === "string" ? w.model : undefined,
+      depends_on: Array.isArray(w.depends_on) ? (w.depends_on as string[]) : [],
+      outputs: outputs.map((o) => ({ path: String(o.path), kind: o.kind as OutputKind, required: o.required !== false })),
+      iterate: w.iterate !== false,
+      worktree: w.worktree === true,
+    });
+  }
+  const idSet = new Set(workers.map((w) => w.id));
+  for (const w of workers) {
+    for (const d of w.depends_on) {
+      if (!idSet.has(d)) errors.push(`worker "${w.id}": unknown dependency "${d}"`);
+    }
+  }
+
+  let loopConfig: LoopConfig | undefined;
+  if (cfg.loop !== undefined && cfg.loop !== null) {
+    if (typeof cfg.loop !== "object" || Array.isArray(cfg.loop)) {
+      errors.push("config.loop must be an object");
+    } else {
+      const loop = cfg.loop as Record<string, unknown>;
+      const maxIterations = loop.max_iterations;
+      if (typeof maxIterations !== "number" || !Number.isInteger(maxIterations) || maxIterations < 1) {
+        errors.push("loop.max_iterations must be an integer >= 1");
+      }
+      const gate = loop.gate;
+      if (gate !== "reviewer" && gate !== "none") {
+        errors.push('loop.gate must be "reviewer" or "none"');
+      }
+      const lgtmCount = loop.lgtm_count;
+      const lgtmCountProvided = lgtmCount !== undefined;
+      if (lgtmCountProvided) {
+        if (typeof lgtmCount !== "number" || !Number.isInteger(lgtmCount) || lgtmCount < 1) {
+          errors.push("loop.lgtm_count must be an integer >= 1");
+        } else if (gate === "none") {
+          errors.push("loop.lgtm_count is not allowed with gate none");
+        } else if (typeof maxIterations === "number" && Number.isInteger(maxIterations) && maxIterations >= 1 && lgtmCount > maxIterations) {
+          errors.push("loop.lgtm_count must be <= max_iterations");
+        }
+      }
+      if (gate === "reviewer" && typeof maxIterations === "number" && Number.isInteger(maxIterations) && maxIterations >= 1) {
+        const verdictNodes = workers.filter((w) => w.outputs.some((o) => o.kind === "verdict"));
+        if (verdictNodes.length !== 1) {
+          errors.push(`gate reviewer requires exactly one verdict-output node, found ${verdictNodes.length}`);
+        } else {
+          const verdictNode = verdictNodes[0];
+          if (verdictNode.iterate === false) {
+            errors.push(`verdict node "${verdictNode.id}" must have iterate enabled`);
+          } else {
+            const dependents = workers.filter((w) => w.depends_on.includes(verdictNode.id));
+            if (dependents.length > 0) {
+              errors.push(`verdict node "${verdictNode.id}" must be a sink, but is depended on by ${dependents.map((w) => w.id).join(", ")}`);
+            }
+          }
+        }
+      }
+      if (gate === "none" && workers.every((w) => w.iterate === false)) {
+        errors.push("gate none requires at least one replay node (iterate: false on all nodes makes the loop a no-op)");
+      }
+      if (errors.length === 0) {
+        loopConfig = {
+          gate: gate as GateKind,
+          max_iterations: maxIterations as number,
+          lgtm_count: lgtmCountProvided ? (lgtmCount as number) : 1,
+        };
+      }
+
+      const byId = new Map(workers.map((w) => [w.id, w]));
+      for (const w of workers) {
+        if (w.iterate !== false) continue;
+        for (const d of w.depends_on) {
+          const dep = byId.get(d);
+          if (dep && dep.iterate !== false) {
+            errors.push(`run-once node "${w.id}" depends on replay node "${d}"`);
+          }
+        }
+      }
+    }
+  }
+
+  const spec: FleetSpec = {
+    fleet_name: String(r?.fleet_name ?? ""),
+    type: "dag",
+    config: { max_concurrent: maxConcurrent, model, warn_cost_usd: warnCost, loop: loopConfig },
+    workers,
+  };
+
+  let layers: string[][] = [];
+  if (errors.length === 0) {
+    try {
+      layers = topoLayers(spec);
+    } catch (e) {
+      if (e instanceof CycleError) errors.push(e.message);
+      else throw e;
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, spec, layers };
+}