pi-agent-fleet 0.2.0 → 0.4.0

package/src/scheduler.ts

@@ -3,18 +3,23 @@ import { join } from "node:path";
 import { 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 } from "./types.js";
+import type { FleetSpec, FleetState, IterationSnapshot, NodeState, Verdict, WorkerSpec } from "./types.js";
+import { commitWorktree, createWorktree, prepareIntegratorWorktree } from "./worktree.js";
 
 export type SpawnFn = (nodeId: string) => Promise<{ ok: boolean; turns: number; tokens: number; cost?: number; error?: string }>;
 
 export interface RunFleetOpts {
   spec: FleetSpec;
   fleetRoot: string;
+  baseRepo?: string;
   repoCwd: string | ((nodeId: string) => string);
   spawn: SpawnFn;
   onNodeChange?: (nodeId: string, s: NodeState) => void;
+  onNodeAdded?: (worker: WorkerSpec) => void | Promise<void>;
+  onNodeCompleted?: (nodeId: string) => Promise<string | undefined | void>;
   killSwitch?: { killed: boolean };
   pauseSwitch?: { paused: boolean };
+  nodeKills?: ReadonlySet<string>;
   resumeFrom?: FleetState;
   continuePass?: boolean;
   onIterationEnd?: (snap: IterationSnapshot) => void;
@@ -24,7 +29,10 @@ export interface RunFleetOpts {
 const FAILED: ReadonlySet<string> = new Set(["failed", "contract_failed", "killed", "blocked"]);
 
 function allNodesTerminal(state: FleetState, spec: FleetSpec): boolean {
-  return spec.workers.every((w) => TERMINAL_NODE_STATUSES.has(state.nodes[w.id].status));
+  return spec.workers.every((w) => {
+    const n = state.nodes[w.id];
+    return !!n && TERMINAL_NODE_STATUSES.has(n.status);
+  });
 }
 
 async function cleanReplayOutputs(spec: FleetSpec, fleetRoot: string): Promise<void> {
@@ -66,20 +74,71 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
   const repoCwdFor = (nodeId: string): string =>
     typeof opts.repoCwd === "function" ? opts.repoCwd(nodeId) : opts.repoCwd;
 
+  const baseRepo = (): string | undefined =>
+    opts.baseRepo ?? (typeof opts.repoCwd === "string" ? opts.repoCwd : undefined);
+
+  function orderedWorktreeBranches(spec: FleetSpec): string[] {
+    const ids = spec.workers.filter((w) => w.worktree).map((w) => w.id);
+    const set = new Set(ids);
+    const indeg = new Map(ids.map((id) => [id, 0]));
+    const rev = new Map(ids.map((id) => [id, [] as string[]]));
+    for (const w of spec.workers) {
+      if (!set.has(w.id)) continue;
+      for (const d of w.depends_on) {
+        if (set.has(d)) {
+          indeg.set(w.id, (indeg.get(w.id) ?? 0) + 1);
+          rev.get(d)?.push(w.id);
+        }
+      }
+    }
+    const sorted: string[] = [];
+    let current = ids.filter((id) => indeg.get(id) === 0);
+    while (current.length > 0) {
+      sorted.push(...current);
+      const next: string[] = [];
+      for (const id of current) {
+        for (const m of rev.get(id) ?? []) {
+          const v = (indeg.get(m) ?? 0) - 1;
+          indeg.set(m, v);
+          if (v === 0) next.push(m);
+        }
+      }
+      current = next;
+    }
+    if (sorted.length !== ids.length) sorted.push(...ids.filter((id) => !sorted.includes(id)));
+    return sorted.map((id) => `fleet/${spec.fleet_name}/${id}`);
+  }
+
   const runPass = async (): Promise<void> => {
     while (true) {
+      // auto-initialize workers inserted into the spec after the run started
+      for (const w of spec.workers) {
+        if (!state.nodes[w.id]) {
+          state = {
+            ...state,
+            nodes: {
+              ...state.nodes,
+              [w.id]: { status: "pending", turns: 0, tokens: 0, cost_usd_estimate: 0, produced_outputs: [] },
+            },
+          };
+          await writeState(fleetRoot, state);
+          await opts.onNodeAdded?.(w);
+          opts.onNodeChange?.(w.id, state.nodes[w.id]);
+        }
+      }
       // block nodes whose deps failed
       for (const w of spec.workers) {
         const n = state.nodes[w.id];
+        if (!n) continue;
         if (n.status !== "pending" && n.status !== "ready") continue;
-        if (w.depends_on.some((d) => FAILED.has(state.nodes[d].status))) {
+        if (w.depends_on.some((d) => FAILED.has(state.nodes[d]?.status ?? ""))) {
           await patch(w.id, { status: "blocked", ended_at: new Date().toISOString() });
         }
       }
       if (opts.killSwitch?.killed) {
         for (const w of spec.workers) {
           const n = state.nodes[w.id];
-          if (!TERMINAL_NODE_STATUSES.has(n.status)) {
+          if (!n || !TERMINAL_NODE_STATUSES.has(n.status)) {
             await patch(w.id, { status: "killed", ended_at: new Date().toISOString() });
           }
         }
@@ -91,17 +150,102 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
       for (const w of spec.workers) {
         if (slots <= 0) break;
         const n = state.nodes[w.id];
+        if (!n) continue;
         if (n.status !== "pending" && n.status !== "ready") continue;
-        const depsDone = w.depends_on.every((d) => state.nodes[d].status === "completed");
+        if (opts.nodeKills?.has(w.id)) {
+          await patch(w.id, { status: "killed", ended_at: new Date().toISOString() });
+          continue;
+        }
+        const depsDone = w.depends_on.every((d) => state.nodes[d]?.status === "completed");
         if (!depsDone) continue;
         slots--;
+
+        if (w.worktree) {
+          const repo = baseRepo();
+          if (!repo) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: "worktree worker requires a baseRepo",
+            });
+            continue;
+          }
+          try {
+            await createWorktree({
+              baseRepo: repo,
+              fleetName: spec.fleet_name,
+              nodeId: w.id,
+              fleetRoot,
+            });
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: `worktree creation failed: ${msg}`,
+            });
+            continue;
+          }
+        }
+
+        if (w.id === "fleet-integrator") {
+          const repo = baseRepo();
+          if (!repo) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: "integrator requires a baseRepo",
+            });
+            continue;
+          }
+          const prep = await prepareIntegratorWorktree({
+            baseRepo: repo,
+            fleetName: spec.fleet_name,
+            fleetRoot,
+            branches: orderedWorktreeBranches(spec),
+          });
+          if (!prep.ok) {
+            await patch(w.id, {
+              status: "failed",
+              ended_at: new Date().toISOString(),
+              status_note: prep.conflict,
+            });
+            continue;
+          }
+        }
+
         await patch(w.id, { status: "running", started_at: new Date().toISOString() });
         const p = opts.spawn(w.id).then(async (res) => {
           if (opts.killSwitch?.killed) return;
+          if (opts.nodeKills?.has(w.id)) {
+            await patch(w.id, { status: "killed", ended_at: new Date().toISOString(), turns: res.turns, tokens: res.tokens, cost_usd_estimate: res.cost ?? 0 });
+            return;
+          }
           if (!res.ok) {
             await patch(w.id, { status: "failed", ended_at: new Date().toISOString(), turns: res.turns, tokens: res.tokens, cost_usd_estimate: res.cost ?? 0 });
             return;
           }
+          if (w.worktree) {
+            try {
+              await commitWorktree({
+                worktreePath: repoCwdFor(w.id),
+                nodeId: w.id,
+                fleetName: spec.fleet_name,
+                iteration: state.iteration,
+              });
+            } catch (e) {
+              const msg = e instanceof Error ? e.message : String(e);
+              await patch(w.id, {
+                status: "failed",
+                ended_at: new Date().toISOString(),
+                turns: res.turns,
+                tokens: res.tokens,
+                cost_usd_estimate: res.cost ?? 0,
+                status_note: `commit failed: ${msg}`,
+              });
+              return;
+            }
+          }
           const contract = await verifyOutputs({
             workerDir: `${fleetRoot}/workers/${w.id}`,
             repoCwd: repoCwdFor(w.id),
@@ -116,12 +260,19 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
             contract_result: contract,
             produced_outputs: contract.checks.filter((c) => c.ok).map((c) => c.path),
           });
+          if (contract.ok) {
+            const note = await opts.onNodeCompleted?.(w.id);
+            if (note) await patch(w.id, { status_note: note });
+          }
         }).finally(() => running.delete(p));
         running.add(p);
       }
       if (running.size > 0) {
         await Promise.race(running);
-      } else if (spec.workers.every((w) => TERMINAL_NODE_STATUSES.has(state.nodes[w.id].status))) {
+      } else if (spec.workers.every((w) => {
+        const n = state.nodes[w.id];
+        return !!n && TERMINAL_NODE_STATUSES.has(n.status);
+      })) {
         break;
       }
     }
@@ -131,7 +282,7 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
   if (!loop) {
     await runPass();
     const anyFailed = spec.workers.some((w) =>
-      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+      ["failed", "contract_failed"].includes(state.nodes[w.id]?.status ?? ""));
     const finalStatus = opts.killSwitch?.killed ? "killed" : anyFailed ? "failed" : "completed";
     state = { ...state, status: finalStatus };
     await writeState(fleetRoot, state);
@@ -181,7 +332,7 @@ export async function runFleet(opts: RunFleetOpts): Promise<FleetState> {
     }
 
     const anyFailed = spec.workers.some((w) =>
-      ["failed", "contract_failed"].includes(state.nodes[w.id].status));
+      ["failed", "contract_failed"].includes(state.nodes[w.id]?.status ?? ""));
     if (anyFailed) {
       state = { ...state, status: "failed" };
       await writeState(fleetRoot, state);

package/src/tools.ts

@@ -0,0 +1,348 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { validateFleetSpec } from "./dag.js";
+import { insertWorkers } from "./insert.js";
+import { loadPreferences, mergeFleetConfig } from "./preferences.js";
+import { activeFleet, currentState, dagPreview, ensureCanvas, killFleet, prepareRelaunch, startLoop, statusText, stopCanvas, updateWidget } from "./controller.js";
+import { openInBrowser, listFleetRoots } from "./canvas.js";
+import { editConfig, editNode, type ConfigEditKey, type NodeEditKey } from "./edits.js";
+import { ensureFleetGitignore, fleetRootFor, isInsideGitRepo, writePlanFiles, writeWorkerPrompts } from "./fleet-store.js";
+import { resolveModelReference, validateFleetModels } from "./model-resolution.js";
+import { runFleetDesign, slugifyFleetName } from "./planner.js";
+import { writeReport } from "./report.js";
+import { initFleetState, resetForRelaunch, writeState } from "./state.js";
+import { renderDag } from "./viz.js";
+
+export function textResult(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+export function registerFleetTools(pi: ExtensionAPI): void {
+  const OutputSchema = Type.Object({
+    path: Type.String({ description: 'output/... paths resolve under the worker dir; anything else is repo-relative (code edits)' }),
+    kind: Type.Union([
+      Type.Literal("markdown"), Type.Literal("file-exists"),
+      Type.Literal("verdict"), Type.Literal("json"), Type.Literal("yaml"),
+    ]),
+    required: Type.Optional(Type.Boolean()),
+  });
+  const EffortSchema = Type.Union([
+    Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"),
+    Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh"), Type.Literal("max"),
+  ], { description: "Thinking effort level" });
+  const WorkerSchema = Type.Object({
+    id: Type.String({ description: "kebab-case, e.g. counter-a" }),
+    type: Type.Union([
+      Type.Literal("research"), Type.Literal("code-run"),
+      Type.Literal("reviewer"), Type.Literal("write"), Type.Literal("read-only"),
+    ]),
+    task: Type.String({ description: "Full task instructions for the worker" }),
+    model: Type.Optional(Type.String({ description: "Per-worker model override, e.g. provider/model-id" })),
+    effort: Type.Optional(EffortSchema),
+    depends_on: Type.Optional(Type.Array(Type.String())),
+    outputs: Type.Optional(Type.Array(OutputSchema)),
+    iterate: Type.Optional(Type.Boolean({ description: "Replay node on each loop iteration" })),
+    worktree: Type.Optional(Type.Boolean({ description: "Run in a dedicated git worktree" })),
+  });
+  const FleetSchema = Type.Object({
+    fleet_name: Type.String({ description: "kebab-case" }),
+    type: Type.Literal("dag"),
+    config: Type.Optional(Type.Object({
+      max_concurrent: Type.Optional(Type.Number()),
+      model: Type.Optional(Type.String({ description: "Fleet-wide default model" })),
+      effort: Type.Optional(EffortSchema),
+      warn_cost_usd: Type.Optional(Type.Number()),
+      loop: Type.Optional(Type.Object({
+        gate: Type.Union([Type.Literal("reviewer"), Type.Literal("none")]),
+        max_iterations: Type.Number(),
+        lgtm_count: Type.Optional(Type.Number()),
+      })),
+    })),
+    workers: Type.Array(WorkerSchema, { minItems: 1 }),
+  });
+
+  pi.registerTool({
+    name: "fleet_plan",
+    label: "Fleet Plan",
+    description:
+      "Validate a fleet DAG definition, create its fleet root, and return an ASCII preview. Does NOT launch. PREREQUISITE: if the user's request is prose requirements or a goal rather than an explicit fleet definition, you MUST call fleet_design first and pass its drafted definition here — do not hand-write the fleet JSON yourself. Present the preview to the user; call fleet_launch only after they explicitly confirm. Choose models by task difficulty: cheap/fast models for trivial writers and validators, mid-tier coding models for code-run workers, strongest reasoning models for reviewers and synthesizers. When several models fit a tier, vary providers across nodes instead of defaulting to one family. Set worker.model per node to override config.model. All model refs are validated against the live registry — planning fails if any model is unavailable.",
+    promptSnippet: "Plan a DAG-of-agents fleet from a fleet definition without launching it.",
+    parameters: Type.Object({
+      fleet: FleetSchema,
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const prefs = await loadPreferences();
+      const v = validateFleetSpec(mergeFleetConfig(params.fleet, prefs));
+      if (!v.ok) return textResult(`Invalid fleet:\n${v.errors.join("\n")}`);
+
+      const modelCheck = validateFleetModels(v.spec, ctx.modelRegistry);
+      if (!modelCheck.ok) return textResult(`Invalid fleet:\n${modelCheck.errors.join("\n")}`);
+
+      const fleetRoot = fleetRootFor(ctx.cwd, v.spec.fleet_name);
+      const state = initFleetState(v.spec);
+      await ensureFleetGitignore(ctx.cwd);
+      await writePlanFiles(fleetRoot, v.spec, state);
+      const active = activeFleet.current = { spec: v.spec, fleetRoot, state, killSwitch: { killed: false }, pauseSwitch: { paused: false }, running: false, costWarned: false, sessions: new Map(), killedNodes: new Set() };
+      updateWidget(ctx, active);
+
+      const dag = await dagPreview(v.spec, undefined, fleetRoot);
+      return textResult(`${dag}\n\nfleet root: ${fleetRoot}\nShow this preview to the user. Call fleet_launch only after they explicitly confirm.`, { fleetRoot, layers: v.layers });
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_launch",
+    label: "Fleet Launch",
+    description: "Launch the active planned fleet after the user has confirmed the plan preview. Runs the DAG in the background and updates the live fleet widget. Pass skip_confirm: true only when the user already approved this exact plan (e.g. unattended runs); otherwise the interactive confirmation is shown.",
+    promptSnippet: "Launch the currently planned fleet after preview confirmation.",
+    parameters: Type.Object({
+      skip_confirm: Type.Optional(Type.Boolean({ description: "Skip the interactive launch confirmation dialog" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      if (active.running) return textResult("fleet already running");
+      const fleet = active;
+
+      const modelCheck = validateFleetModels(fleet.spec, ctx.modelRegistry);
+      if (!modelCheck.ok) {
+        return textResult(`Cannot launch — unresolvable models:\n${modelCheck.errors.join("\n")}`);
+      }
+
+      if (fleet.spec.workers.some((w) => w.worktree === true)) {
+        if (!(await isInsideGitRepo(ctx.cwd))) {
+          return textResult(`worktree workers require a git repo; none found above ${ctx.cwd}`);
+        }
+      }
+
+      if (ctx.hasUI && !params.skip_confirm) {
+        const ok = await ctx.ui.confirm("Launch fleet?", renderDag(fleet.spec));
+        if (!ok) return textResult("fleet launch aborted");
+      }
+
+      await writeWorkerPrompts(fleet);
+      void startLoop(fleet, ctx, false);
+      return textResult("fleet launched");
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_status",
+    label: "Fleet Status",
+    description: "Show the current active fleet DAG and live widget lines.",
+    promptSnippet: "Show current active fleet status.",
+    parameters: Type.Object({}),
+    async execute() {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      return textResult(await statusText(active));
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_kill",
+    label: "Fleet Kill",
+    description: "Request a fleet-wide kill (target \"all\") or kill a single node by worker id. Killing a running node aborts its session; killing a pending node marks it killed at the next dispatch pass. Killed nodes can be revived with fleet_relaunch.",
+    promptSnippet: "Kill the whole fleet or a single node by worker id.",
+    parameters: Type.Object({ target: Type.String({ description: "all or a worker id" }) }),
+    async execute(_id, params) {
+      return textResult(await killFleet(params.target));
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_pause",
+    label: "Fleet Pause",
+    description: "Request a pause of the active running loop fleet. The pause takes effect at the next iteration boundary.",
+    promptSnippet: "Pause the active fleet at the next iteration boundary.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      if (!active.spec.config.loop) return textResult("fleet has no loop; pause is a loop-fleet operation");
+      if (!active.running) return textResult("fleet not running");
+      active.pauseSwitch.paused = true;
+      active.state = { ...active.state, paused: true };
+      await writeState(active.fleetRoot, active.state);
+      updateWidget(ctx, active);
+      return textResult("pause requested (takes effect at next iteration boundary)");
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_resume",
+    label: "Fleet Resume",
+    description: "Resume a paused loop fleet from the current iteration.",
+    promptSnippet: "Resume the paused active fleet.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      if (active.state.status !== "paused") return textResult("fleet is not paused");
+      if (active.running) return textResult("fleet already running");
+      active.pauseSwitch.paused = false;
+      void startLoop(active, ctx, true);
+      return textResult("fleet resumed");
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_relaunch",
+    label: "Fleet Relaunch",
+    description: "Relaunch a failed node and any blocked downstream dependents. Optionally override the worker model for this run.",
+    promptSnippet: "Relaunch a failed fleet node.",
+    parameters: Type.Object({
+      node_id: Type.String({ description: "Worker id to relaunch" }),
+      model: Type.Optional(Type.String({ description: "Optional model override for this run, e.g. provider/model-id" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      if (active.running) return textResult("fleet is running");
+      const fleet = active;
+      await currentState(fleet);
+      if (fleet.state.status === "completed") return textResult("fleet completed, nothing to relaunch");
+      const worker = fleet.spec.workers.find((w) => w.id === params.node_id);
+      if (!worker) return textResult(`unknown node "${params.node_id}"`);
+      const node = fleet.state.nodes[params.node_id];
+      const relaunchable: ReadonlySet<string> = new Set(["failed", "contract_failed", "killed"]);
+      if (!node || !relaunchable.has(node.status)) {
+        return textResult(`node "${params.node_id}" status ${node?.status ?? "missing"} cannot be relaunched; must be failed, contract_failed, or killed`);
+      }
+      if (params.model) {
+        const resolved = resolveModelReference(ctx.modelRegistry, params.model);
+        if (!resolved.ok) return textResult(resolved.error);
+        const canonical = `${resolved.model.provider}/${resolved.model.id}`;
+        fleet.spec.workers = fleet.spec.workers.map((w) => w.id === params.node_id ? { ...w, model: canonical } : w);
+        await writeFile(join(fleet.fleetRoot, "fleet.json"), `${JSON.stringify(fleet.spec, null, 2)}\n`, "utf-8");
+      }
+      fleet.state = resetForRelaunch(fleet.state, fleet.spec, params.node_id);
+      await writeState(fleet.fleetRoot, fleet.state);
+      prepareRelaunch(fleet, params.node_id);
+      void startLoop(fleet, ctx, false, true);
+      return textResult(`fleet relaunch requested for ${params.node_id}`);
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_add_node",
+    label: "Fleet Add Node",
+    description: "Insert one or more worker nodes into the active fleet's DAG on the fly. The merged graph is validated (unique ids, known deps, acyclic, loop-gate rules); inserted nodes start as pending and dispatch as soon as their deps complete — including mid-run. Refused on completed fleets.",
+    promptSnippet: "Add worker nodes to the active fleet DAG.",
+    parameters: Type.Object({
+      workers: Type.Array(WorkerSchema, { minItems: 1 }),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      await currentState(active);
+      const r = await insertWorkers(active, params.workers, ctx.modelRegistry);
+      if (r.ok) updateWidget(ctx, active);
+      return textResult(r.message, { inserted: r.inserted ?? [] });
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_design",
+    label: "Fleet Design",
+    description: "Draft a fleet DAG from plain-language requirements — this is the REQUIRED first step whenever the user describes a goal in prose instead of giving an explicit fleet definition. Spawns a planner agent that writes a fleet.json definition, validates it, and returns an ASCII preview with the JSON. Does NOT plan or launch anything. After the user approves the preview, pass the drafted definition to fleet_plan.",
+    promptSnippet: "Draft a fleet DAG from plain-language requirements.",
+    parameters: Type.Object({
+      requirements: Type.String({ description: "Plain-language description of the goal" }),
+      fleet_name: Type.Optional(Type.String({ description: "kebab-case; derived from requirements when omitted" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const fleetName = params.fleet_name ?? slugifyFleetName(params.requirements);
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(fleetName)) {
+        return textResult(`fleet_name "${fleetName}" must be kebab-case`);
+      }
+      const ts = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+      const designRoot = join(ctx.cwd, ".fleet", `design-${fleetName}-${ts}`);
+      await ensureFleetGitignore(ctx.cwd);
+      const result = await runFleetDesign({
+        requirements: params.requirements,
+        fleetName,
+        designRoot,
+        repoCwd: ctx.cwd,
+      });
+      if (!result.ok) return textResult(`fleet design failed: ${result.error}`);
+      const v = validateFleetSpec(result.draft);
+      if (!v.ok) {
+        return textResult(
+          `planner produced an invalid fleet:\n${v.errors.join("\n")}\n\ndraft JSON:\n${JSON.stringify(result.draft, null, 2)}\n\nFix the JSON and call fleet_plan directly, or retry fleet_design with clearer requirements.`,
+        );
+      }
+      const dag = renderDag(v.spec);
+      return textResult(
+        `${dag}\n\nrationale: ${join(designRoot, "planner", "output", "rationale.md")}\n\nfleet JSON:\n${JSON.stringify(result.draft, null, 2)}\n\nShow this preview to the user. If they approve, call fleet_plan with this definition (fleet_launch only after their explicit confirmation).`,
+        { designRoot },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_report",
+    label: "Fleet Report",
+    description: "Regenerate and return the active fleet markdown report from current state.",
+    promptSnippet: "Regenerate the active fleet report.",
+    parameters: Type.Object({}),
+    async execute(_id, _params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      const state = await currentState(active);
+      const report = await writeReport({ spec: active.spec, state, fleetRoot: active.fleetRoot, repoCwd: ctx.cwd });
+      return textResult(report, { reportPath: join(active.fleetRoot, "report.md") });
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_edit",
+    label: "Fleet Edit",
+    description: "Edit the active fleet: a pending node's model, effort, or task — or fleet config (max_concurrent, warn_cost_usd, model, effort) when node_id is omitted. Changes persist to fleet.json and apply to nodes not yet dispatched. Refuses edits to nodes already running or terminal.",
+    promptSnippet: "Edit a pending fleet node or fleet config.",
+    parameters: Type.Object({
+      node_id: Type.Optional(Type.String({ description: "Worker id to edit; omit for fleet config edits" })),
+      key: Type.String({ description: "Node keys: model, effort, task. Config keys: max_concurrent, warn_cost_usd, model, effort" }),
+      value: Type.String({ description: "New value" }),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const active = activeFleet.current;
+      if (!active) return textResult("no fleet planned yet");
+      await currentState(active);
+      const r = params.node_id
+        ? await editNode(active, params.node_id, params.key as NodeEditKey, params.value, ctx.modelRegistry)
+        : await editConfig(active, params.key as ConfigEditKey, params.value, ctx.modelRegistry);
+      if (r.ok) updateWidget(ctx, active);
+      return textResult(r.message);
+    },
+  });
+
+  pi.registerTool({
+    name: "fleet_canvas",
+    label: "Fleet Canvas",
+    description: "Open a local browser canvas for the active fleet: live DAG with per-node stats and a click-to-peek view of each node's recent agent session. Read-only, binds 127.0.0.1 on an ephemeral port. action 'url' (default) returns the URL without opening a browser; 'open' opens it; 'stop' shuts the server down.",
+    promptSnippet: "Open the fleet browser canvas.",
+    parameters: Type.Object({
+      action: Type.Optional(Type.Union([Type.Literal("open"), Type.Literal("stop"), Type.Literal("url")])),
+      fleet: Type.Optional(Type.String({ description: "Fleet root dir basename under .fleet to visualize (e.g. energy-brief-20260803000000); omit for the live fleet" })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const action = params.action ?? "url";
+      if (action === "stop") {
+        await stopCanvas();
+        return textResult("fleet canvas stopped");
+      }
+      const server = await ensureCanvas(ctx);
+      let url = server.url;
+      if (params.fleet) {
+        const roots = await listFleetRoots(ctx.cwd);
+        if (!roots.some((r) => r.name === params.fleet)) return textResult(`unknown fleet "${params.fleet}"`);
+        url = `${url}?fleet=${encodeURIComponent(params.fleet)}`;
+      }
+      if (action === "open") await openInBrowser(url);
+      return textResult(`fleet canvas: ${url}`, { url: url });
+    },
+  });
+}

package/src/types.ts

@@ -11,6 +11,10 @@ export type WorkerType = "research" | "code-run" | "reviewer" | "write" | "read-
 export type GateKind = "reviewer" | "none";
 export type Verdict = "lgtm" | "iterate" | "escalate";
 
+export type ThinkingLevelName = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export const THINKING_LEVELS: readonly ThinkingLevelName[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
 export interface LoopConfig {
   gate: GateKind;
   max_iterations: number;
@@ -22,6 +26,7 @@ export interface WorkerSpec {
   type: WorkerType;
   task: string;
   model?: string;
+  effort?: ThinkingLevelName;
   depends_on: string[];
   outputs: ContractOutput[];
   iterate?: boolean;
@@ -30,7 +35,8 @@ export interface WorkerSpec {
 
 export interface FleetConfig {
   max_concurrent: number;
-  model: string;
+  model?: string;
+  effort?: ThinkingLevelName;
   warn_cost_usd?: number;
   loop?: LoopConfig;
 }