pi-agent-fleet 0.4.0 → 0.5.0

package/src/controller.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { writeWorkerPrompts } from "./fleet-store.js";
+import { recoverLatestFleet } from "./fleet-recovery.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { insertWorkers } from "./insert.js";
 import { writeReport } from "./report.js";
@@ -25,6 +26,7 @@ export interface ActiveFleet {
   costWarned?: boolean;
   sessions: Map<string, AgentSessionLike>;
   killedNodes: Set<string>;
+  widgetVisible?: boolean;
 }
 
 export interface ActiveFleetCell {
@@ -34,7 +36,7 @@ export interface ActiveFleetCell {
 export const activeFleet: ActiveFleetCell = { current: undefined };
 
 export function updateWidget(ctx: ExtensionContext, fleet: ActiveFleet, spinnerFrame?: number): void {
-  if (ctx.hasUI) ctx.ui.setWidget("fleet", buildWidgetLines(fleet.spec, fleet.state, { spinnerFrame }));
+  if (ctx.hasUI && fleet.widgetVisible) ctx.ui.setWidget("fleet", buildWidgetLines(fleet.spec, fleet.state, { spinnerFrame }));
 }
 
 export function startSpinner(ctx: ExtensionContext, fleet: ActiveFleet, intervalMs = 150): () => void {
@@ -60,7 +62,14 @@ export async function currentState(fleet: ActiveFleet): Promise<FleetState> {
 
 export async function statusText(fleet: ActiveFleet): Promise<string> {
   const state = await currentState(fleet);
-  return renderDag(fleet.spec, state);
+  const reportPath = join(fleet.fleetRoot, "report.md");
+  const failed = Object.entries(state.nodes).find(([, n]) => n.status === "failed" || n.status === "contract_failed");
+  const next = state.status === "planned" ? "next: fleet_launch"
+    : state.status === "running" ? "next: fleet_status, fleet_canvas, or fleet_kill <id>|all"
+    : failed ? `next: fleet_relaunch ${failed[0]}`
+    : state.status === "completed" ? `next: read report ${reportPath}`
+    : `next: inspect ${join(fleet.fleetRoot, "state.json")}`;
+  return `${renderDag(fleet.spec, state)}\n\nreport: ${reportPath}\n${next}`;
 }
 
 export async function dagPreview(spec: FleetSpec, state: FleetState | undefined, fleetRoot: string): Promise<string> {
@@ -263,9 +272,21 @@ export async function startLoop(fleet: ActiveFleet, ctx: ExtensionContext, resum
   }
 }
 
-export async function killFleet(target: string): Promise<string> {
-  const active = activeFleet.current;
+export async function killFleet(target: string, cwd?: string): Promise<string> {
+  const active = activeFleet.current ?? (cwd ? await recoverLatestFleet(cwd) : undefined);
+  if (active) activeFleet.current ??= active;
   if (!active) return "no fleet planned yet";
+  if (!active.running) {
+    try {
+      active.state = await readState(active.fleetRoot);
+    } catch {
+      // keep in-memory state
+    }
+    if (active.state.status === "running") {
+      const where = target === "all" ? "fleet" : `node "${target}"`;
+      return `${where} not killed: fleet state on disk is "running" — it appears to be running in another live session; kill it there (this session holds no live scheduler, so a kill here would silently no-op)`;
+    }
+  }
   if (target === "all") {
     active.killSwitch.killed = true;
     return "fleet kill requested";

package/src/dag.ts

@@ -1,4 +1,4 @@
-import type { FleetSpec, GateKind, LoopConfig, OutputKind, ThinkingLevelName, WorkerSpec, WorkerType } from "./types.js";
+import type { ContractOutput, FleetSpec, GateKind, JsonOutputSchema, LoopConfig, OutputKind, ThinkingLevelName, WorkerSpec, WorkerType } from "./types.js";
 import { THINKING_LEVELS } from "./types.js";
 
 export class CycleError extends Error {
@@ -49,10 +49,9 @@ export function getDependents(spec: FleetSpec, nodeId: string): string[] {
   return spec.workers.filter((w) => w.depends_on.includes(nodeId)).map((w) => w.id);
 }
 
-function findWorktreeOwnershipConflicts(workers: WorkerSpec[]): string[] {
-  const worktrees = workers.filter((w) => w.worktree);
+export function findRepoOutputOwnershipConflicts(workers: WorkerSpec[]): string[] {
   const claims = new Map<string, string[]>();
-  for (const w of worktrees) {
+  for (const w of workers) {
     for (const o of w.outputs) {
       if (!o.path.startsWith("output/")) {
         const list = claims.get(o.path) ?? [];
@@ -71,7 +70,7 @@ function findWorktreeOwnershipConflicts(workers: WorkerSpec[]): string[] {
         const aBeforeB = byId.get(a)!.depends_on.includes(b);
         const bBeforeA = byId.get(b)!.depends_on.includes(a);
         if (!aBeforeB && !bBeforeA) {
-          errors.push(`worktree ownership conflict: "${path}" claimed by "${a}" and "${b}" without ordered handoff`);
+          errors.push(`repo output ownership conflict: "${path}" claimed by "${a}" and "${b}" without ordered handoff`);
         }
       }
     }
@@ -132,6 +131,21 @@ export function validateFleetSpec(
           errors.push(`worker "${id}": output path must be relative and stay within the repo`);
         }
       }
+      if (o.schema !== undefined) {
+        if (o.kind !== "json") {
+          errors.push(`worker "${id}": output schema only allowed with kind "json"`);
+        } else if (typeof o.schema !== "object" || o.schema === null || Array.isArray(o.schema)) {
+          errors.push(`worker "${id}": output schema must be an object`);
+        } else {
+          const s = o.schema as Record<string, unknown>;
+          for (const name of ["required_keys", "number_keys"] as const) {
+            const keys = s[name];
+            if (keys !== undefined && (!Array.isArray(keys) || keys.some((k) => typeof k !== "string" || k.length === 0))) {
+              errors.push(`worker "${id}": schema.${name} must be an array of non-empty strings`);
+            }
+          }
+        }
+      }
     }
     const wEffort = typeof w.effort === "string" ? w.effort as ThinkingLevelName : undefined;
     if (wEffort !== undefined && !THINKING_LEVELS.includes(wEffort)) {
@@ -144,7 +158,18 @@ export function validateFleetSpec(
       model: typeof w.model === "string" ? w.model : undefined,
       effort: wEffort,
       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 })),
+      outputs: outputs.map((o) => {
+        const out: ContractOutput = { path: String(o.path), kind: o.kind as OutputKind, required: o.required !== false };
+        const s = o.schema;
+        if (o.kind === "json" && typeof s === "object" && s !== null && !Array.isArray(s)) {
+          const rec = s as Record<string, unknown>;
+          const schema: JsonOutputSchema = {};
+          if (Array.isArray(rec.required_keys)) schema.required_keys = rec.required_keys as string[];
+          if (Array.isArray(rec.number_keys)) schema.number_keys = rec.number_keys as string[];
+          out.schema = schema;
+        }
+        return out;
+      }),
       iterate: w.iterate !== false,
       worktree: w.worktree === true,
     });
@@ -170,8 +195,8 @@ export function validateFleetSpec(
     if (!hasIntegratorPath(workers)) {
       errors.push("multiple worktree workers require an integrator that depends on all worktree workers");
     }
-    errors.push(...findWorktreeOwnershipConflicts(workers));
   }
+  errors.push(...findRepoOutputOwnershipConflicts(workers));
 
   let loopConfig: LoopConfig | undefined;
   if (cfg.loop !== undefined && cfg.loop !== null) {

package/src/edits.ts

@@ -1,10 +1,11 @@
 import { rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ActiveFleet } from "./controller.js";
+import { persistFleetJson } from "./fleet-store.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { buildWorkerPrompt } from "./prompts.js";
+import type { NodeStatus, ThinkingLevelName } from "./types.js";
 import { THINKING_LEVELS } from "./types.js";
-import type { ThinkingLevelName } from "./types.js";
 
 export type NodeEditKey = "model" | "effort" | "task";
 export type ConfigEditKey = "max_concurrent" | "warn_cost_usd" | "model" | "effort";
@@ -14,9 +15,7 @@ export interface EditResult {
   message: string;
 }
 
-async function persistSpec(fleet: ActiveFleet): Promise<void> {
-  await writeFile(join(fleet.fleetRoot, "fleet.json"), `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
-}
+const EDITABLE_NODE_STATUSES: ReadonlySet<NodeStatus> = new Set(["pending", "ready", "failed", "contract_failed", "killed"]);
 
 export async function editNode(
   fleet: ActiveFleet,
@@ -28,9 +27,9 @@ export async function editNode(
   const worker = fleet.spec.workers.find((w) => w.id === nodeId);
   const node = fleet.state.nodes[nodeId];
   if (!worker || !node) return { ok: false, message: `unknown node "${nodeId}"` };
-  if (node.status !== "pending" && node.status !== "ready") {
-    return { ok: false, message: `node "${nodeId}" is ${node.status}; only pending nodes can be edited` };
-  }
+  if (!EDITABLE_NODE_STATUSES.has(node.status)) {
+      return { ok: false, message: `node "${nodeId}" is ${node.status}; only pending, failed, contract_failed, or killed nodes can be edited` };
+    }
   switch (key) {
     case "model": {
       const r = resolveModelReference(registry, value);
@@ -63,7 +62,7 @@ export async function editNode(
     default:
       return { ok: false, message: `unknown node edit key "${String(key)}" (keys: model, effort, task)` };
   }
-  await persistSpec(fleet);
+  await persistFleetJson(fleet);
   return { ok: true, message: `node "${nodeId}" ${key} updated` };
 }
 
@@ -102,6 +101,6 @@ export async function editConfig(
     default:
       return { ok: false, message: `unknown config key "${String(key)}" (keys: max_concurrent, warn_cost_usd, model, effort)` };
   }
-  await persistSpec(fleet);
+  await persistFleetJson(fleet);
   return { ok: true, message: `config.${key} updated` };
 }

package/src/fleet-recovery.ts

@@ -0,0 +1,73 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActiveFleet } from "./controller.js";
+import { readState } from "./state.js";
+import type { FleetSpec, FleetState } from "./types.js";
+
+export interface FleetRootInfo {
+  name: string;
+  root: string;
+  status: string;
+  created_at: string;
+}
+
+export async function readDiskFleet(fleetRoot: string): Promise<ActiveFleet> {
+  const spec = JSON.parse(await readFile(join(fleetRoot, "fleet.json"), "utf-8")) as FleetSpec;
+  const state = await readState(fleetRoot);
+  return {
+    spec,
+    fleetRoot,
+    state,
+    killSwitch: { killed: false },
+    pauseSwitch: { paused: false },
+    running: false,
+    sessions: new Map(),
+    killedNodes: new Set(),
+  };
+}
+
+export async function listFleetRoots(cwd: string): Promise<FleetRootInfo[]> {
+  const base = join(cwd, ".fleet");
+  let entries: string[];
+  try {
+    entries = await readdir(base);
+  } catch {
+    return [];
+  }
+  const out: FleetRootInfo[] = [];
+  for (const name of entries) {
+    const root = join(base, name);
+    try {
+      const s = await stat(join(root, "fleet.json"));
+      if (!s.isFile()) continue;
+      const state = JSON.parse(await readFile(join(root, "state.json"), "utf-8")) as Partial<FleetState>;
+      out.push({
+        name,
+        root,
+        status: typeof state.status === "string" ? state.status : "unknown",
+        created_at: typeof state.created_at === "string" ? state.created_at : new Date(s.mtimeMs).toISOString(),
+      });
+    } catch {
+      // not a fleet root (no fleet.json) or unreadable state — skip or mark unknown
+      try {
+        await stat(join(root, "fleet.json"));
+        out.push({ name, root, status: "unknown", created_at: "" });
+      } catch {
+        // not a fleet root
+      }
+    }
+  }
+  out.sort((a, b) => b.created_at.localeCompare(a.created_at));
+  return out;
+}
+
+export async function recoverLatestFleet(cwd: string): Promise<ActiveFleet | undefined> {
+  const roots = await listFleetRoots(cwd);
+  const latest = roots.find((r) => r.status !== "unknown") ?? roots[0];
+  if (!latest) return undefined;
+  try {
+    return await readDiskFleet(latest.root);
+  } catch {
+    return undefined;
+  }
+}

package/src/fleet-store.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildWorkerPrompt } from "./prompts.js";
 import { writeState } from "./state.js";
@@ -47,9 +47,18 @@ export async function writePlanFiles(fleetRoot: string, spec: FleetSpec, state:
   await writeState(fleetRoot, state);
 }
 
+export async function persistFleetJson(fleet: { fleetRoot: string; spec: FleetSpec }): Promise<void> {
+  const path = join(fleet.fleetRoot, "fleet.json");
+  const tmp = join(fleet.fleetRoot, `.fleet.json.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  await writeFile(tmp, `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
+  await rename(tmp, path);
+}
+
 export async function writeWorkerPrompts(fleet: { spec: FleetSpec; state: FleetState; fleetRoot: string }): Promise<void> {
   await Promise.all(fleet.spec.workers.map(async (w) => {
+    const dir = join(fleet.fleetRoot, "workers", w.id);
+    await mkdir(dir, { recursive: true });
     const prompt = buildWorkerPrompt({ spec: fleet.spec, state: fleet.state, workerId: w.id, fleetRoot: fleet.fleetRoot });
-    await writeFile(join(fleet.fleetRoot, "workers", w.id, "prompt.md"), prompt, "utf-8");
+    await writeFile(join(dir, "prompt.md"), prompt, "utf-8");
   }));
 }

package/src/insert.ts

@@ -1,7 +1,8 @@
-import { mkdir, rename, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { ActiveFleet } from "./controller.js";
 import { validateFleetSpec } from "./dag.js";
+import { persistFleetJson } from "./fleet-store.js";
 import { resolveModelReference, type ModelRegistryLike } from "./model-resolution.js";
 import { buildWorkerPrompt } from "./prompts.js";
 import { writeState } from "./state.js";
@@ -12,13 +13,6 @@ export interface InsertResult {
   inserted?: string[];
 }
 
-async function persistFleetJson(fleet: ActiveFleet): Promise<void> {
-  const path = join(fleet.fleetRoot, "fleet.json");
-  const tmp = join(fleet.fleetRoot, `.fleet.json.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-  await writeFile(tmp, `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
-  await rename(tmp, path);
-}
-
 async function insertWorkersSerialized(
   fleet: ActiveFleet,
   raw: unknown,

package/src/model-resolution.ts

@@ -16,6 +16,32 @@ export function aliasesFor(model: Model<Api>): string[] {
   ];
 }
 
+export function canonicalModelRef(model: Model<Api>): string {
+  return `${model.provider}/${model.id}`;
+}
+
+export function listModelRefs(registry: ModelRegistryLike, limit = 40): string[] {
+  const models = registry.getAvailable().length > 0 ? registry.getAvailable() : registry.getAll();
+  return [...new Map(models.map((m) => [canonicalModelRef(m), m])).keys()].slice(0, limit);
+}
+
+export function suggestModelRefs(registry: ModelRegistryLike, ref: string, limit = 8): string[] {
+  const needle = ref.toLowerCase();
+  return listModelRefs(registry, 200)
+    .filter((r) => r.toLowerCase().includes(needle) || needle.split(/[/-]/).some((p) => p.length > 2 && r.toLowerCase().includes(p)))
+    .slice(0, limit);
+}
+
+export function formatModelError(registry: ModelRegistryLike, label: string, ref: string, error: string): string {
+  const suggestions = suggestModelRefs(registry, ref);
+  const available = listModelRefs(registry);
+  return [
+    `${label}: ${error}`,
+    suggestions.length > 0 ? `suggestions: ${suggestions.join(", ")}` : undefined,
+    `available models: ${available.join(", ")}`,
+  ].filter(Boolean).join("\n");
+}
+
 export function resolveModelReference(
   registry: ModelRegistryLike,
   ref: string,
@@ -36,7 +62,6 @@ export function resolveModelReference(
   tiers.push(pool.filter((m) => m.id.toLowerCase() === needle));
   tiers.push(pool.filter((m) => byAlias(m, (a) => a === needle)));
   tiers.push(pool.filter((m) => byAlias(m, (a) => a.startsWith(needle))));
-  tiers.push(pool.filter((m) => byAlias(m, (a) => a.includes(needle))));
 
   for (const tier of tiers) {
     const unique = [...new Map(tier.map((m) => [`${m.provider}/${m.id}`, m])).values()];
@@ -67,7 +92,7 @@ export function validateFleetModels(
     if (seen.has(key)) continue;
     seen.add(key);
     const r = resolveModelReference(registry, ref);
-    if (!r.ok) errors.push(`${label}: ${r.error}`);
+    if (!r.ok) errors.push(formatModelError(registry, label, ref, r.error));
   }
   return errors.length > 0 ? { ok: false, errors } : { ok: true };
 }

package/src/preferences.ts

@@ -1,6 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { canonicalModelRef, formatModelError, resolveModelReference } from "./model-resolution.js";
+import type { ModelRegistryLike } from "./model-resolution.js";
 import { THINKING_LEVELS } from "./types.js";
 import type { ThinkingLevelName } from "./types.js";
 
@@ -59,6 +61,7 @@ export function mergeFleetConfig(raw: unknown, prefs: FleetPreferences): unknown
 export function validatePreferenceValue(
   key: string,
   value: string,
+  registry?: ModelRegistryLike,
 ): { ok: true; parsed: number | string } | { ok: false; error: string } {
   switch (key) {
     case "max_concurrent": {
@@ -79,6 +82,11 @@ export function validatePreferenceValue(
     }
     case "model": {
       if (value.trim().length === 0) return { ok: false, error: "model must be non-empty" };
+      if (registry) {
+        const r = resolveModelReference(registry, value.trim());
+        if (!r.ok) return { ok: false, error: formatModelError(registry, "preference model", value.trim(), r.error) };
+        return { ok: true, parsed: canonicalModelRef(r.model) };
+      }
       return { ok: true, parsed: value.trim() };
     }
     default:
@@ -90,8 +98,9 @@ export function setPreference(
   prefs: FleetPreferences,
   key: string,
   value: string,
+  registry?: ModelRegistryLike,
 ): { ok: true; prefs: FleetPreferences } | { ok: false; error: string } {
-  const v = validatePreferenceValue(key, value);
+  const v = validatePreferenceValue(key, value, registry);
   if (!v.ok) return v;
   return { ok: true, prefs: { ...prefs, [key]: v.parsed } };
 }

package/src/prompts.ts

@@ -100,6 +100,16 @@ export function buildWorkerPrompt(opts: {
   } else {
     for (const o of worker.outputs) {
       out.push(`- ${o.path} (${o.kind}${o.required ? ", REQUIRED" : ", optional"})`);
+      if (o.kind === "json" && o.schema) {
+        const bits: string[] = [];
+        if (o.schema.required_keys && o.schema.required_keys.length > 0) {
+          bits.push(`must be a JSON object containing keys: ${o.schema.required_keys.join(", ")}`);
+        }
+        if (o.schema.number_keys && o.schema.number_keys.length > 0) {
+          bits.push(`these keys must be numbers or arrays of numbers: ${o.schema.number_keys.join(", ")}`);
+        }
+        if (bits.length > 0) out.push(`  - ${bits.join("; ")}`);
+      }
     }
     out.push("");
   }

package/src/report.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import type { FleetSpec, FleetState } from "./types.js";
@@ -72,6 +72,33 @@ export async function writeReport(opts: {
       if (w.worktree) lines.push(`- fleet/${base}/${w.id}`);
     }
   }
+  lines.push("", "## Next steps", "");
+  const reportPath = join(fleetRoot, "report.md");
+  const failed = Object.entries(state.nodes).find(([, n]) => n.status === "failed" || n.status === "contract_failed");
+  const next = state.status === "planned" ? "fleet_launch"
+    : state.status === "running" ? "fleet_status, fleet_canvas, or fleet_kill <id>|all"
+    : failed ? `fleet_relaunch ${failed[0]}`
+    : state.status === "completed" ? `read report ${reportPath}`
+    : `inspect ${join(fleetRoot, "state.json")}`;
+  lines.push(`- next: ${next}`);
+  lines.push("", "## JSON outputs", "");
+  let anyJson = false;
+  for (const w of spec.workers) {
+    const n = state.nodes[w.id];
+    for (const out of n?.produced_outputs ?? []) {
+      if (!out.startsWith("output/") || !out.endsWith(".json") || out.includes("..")) continue;
+      anyJson = true;
+      let content: string;
+      try {
+        const raw = await readFile(join(fleetRoot, "workers", w.id, out), "utf-8");
+        content = raw.length > 4096 ? `${raw.slice(0, 4096)}\n... (truncated)` : raw;
+      } catch {
+        content = "(unreadable)";
+      }
+      lines.push(`### ${w.id}: ${out}`, "", "```json", content.trimEnd(), "```", "");
+    }
+  }
+  if (!anyJson) lines.push("(none)", "");
   lines.push("", "## Code changes", "", "```", await gitDiffStat(repoCwd, state.created_at), "```", "");
   lines.push("## Artifacts", "", `- state: ${join(fleetRoot, "state.json")}`,
     `- sessions: ${join(fleetRoot, "workers", "<id>", "session.jsonl")}`, "");

package/src/scheduler.ts

@@ -1,6 +1,6 @@
 import { mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { verifyOutputs } from "./contracts.js";
+import { contractFailureNote, verifyOutputs } from "./contracts.js";
 import { archiveIteration, initFleetState, patchNode, resetForIteration, snapshotIteration, writeState } from "./state.js";
 import { TERMINAL_NODE_STATUSES } from "./types.js";
 import type { FleetSpec, FleetState, IterationSnapshot, NodeState, Verdict, WorkerSpec } from "./types.js";
@@ -258,7 +258,8 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
             tokens: res.tokens,
             cost_usd_estimate: res.cost ?? 0,
             contract_result: contract,
-            produced_outputs: contract.checks.filter((c) => c.ok).map((c) => c.path),
+            produced_outputs: contract.checks.filter((c) => c.ok || c.actualPath).map((c) => c.path),
+            status_note: contract.ok ? undefined : contractFailureNote(contract.checks),
           });
           if (contract.ok) {
             const note = await opts.onNodeCompleted?.(w.id);