@getpipher/armory-fleet 0.2.0

package/src/panel/fleet-panel.ts

@@ -0,0 +1,227 @@
+// src/panel/fleet-panel.ts
+import { DynamicBorder, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  SelectList,
+  Spacer,
+  Text,
+  matchesKey,
+  type SelectItem,
+} from "@earendil-works/pi-tui";
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { RunRecord } from "../engine/run-registry.ts";
+import { fleetRow, agentsRow, agentInfo } from "./rows.ts";
+import { spawnSubagent, type ChildSessionFactory, type SpawnResult } from "../engine/spawnSubagent.ts";
+import type { RunRegistry } from "../engine/run-registry.ts";
+import type { SingleSlotLock } from "../engine/concurrency-lock.ts";
+import type { TodoSyncPort } from "../todo-sync/port.ts";
+
+type View = "fleet" | "agents";
+
+export interface FleetPanelDeps {
+  registry: Map<string, AgentDef>;
+  runRegistry: RunRegistry;
+  lock: SingleSlotLock;
+  todoSync: TodoSyncPort;
+  childFactory: ChildSessionFactory;
+  parentModel: { provider: string; id: string };
+  parentCwd: string;
+}
+
+export interface FleetPanelOpts {
+  theme: Theme;
+  deps: FleetPanelDeps;
+  onDone: () => void;
+  onNotify: (msg: string, type?: "info" | "warning" | "error") => void;
+}
+
+export class FleetPanel extends Container {
+  private readonly theme: Theme;
+  private readonly deps: FleetPanelDeps;
+  private readonly onDone: () => void;
+  private readonly onNotify: (msg: string, type?: "info" | "warning" | "error") => void;
+  private view: View = "fleet";
+  private list: SelectList;
+  private runMode = false;
+  private taskInput: Input | null = null;
+  private linkInput: Input | null = null;
+  private linkPhase: "task" | "link" = "task";
+  private infoAgent: AgentDef | null = null;
+
+  constructor(opts: FleetPanelOpts) {
+    super();
+    this.theme = opts.theme;
+    this.deps = opts.deps;
+    this.onDone = opts.onDone;
+    this.onNotify = opts.onNotify;
+
+    const accent = (s: string): string => this.theme.fg("accent", s);
+    this.addChild(new DynamicBorder(accent));
+    this.addChild(new Spacer(1));
+    this.list = this.buildList();
+    this.renderShell();
+  }
+
+  private buildList(): SelectList {
+    const items: SelectItem[] =
+      this.view === "fleet"
+        ? this.deps.runRegistry.list().map((r: RunRecord) => ({ value: r.runId, label: fleetRow(r) }))
+        : [...this.deps.registry.values()].map((a: AgentDef) => ({ value: a.name, label: agentsRow(a) }));
+    const fresh = new SelectList(items, 12, {
+      selectedPrefix: (s: string) => this.theme.fg("accent", s),
+      selectedText: (s: string) => this.theme.fg("accent", s),
+      description: (s: string) => this.theme.fg("muted", s),
+      scrollInfo: (s: string) => this.theme.fg("dim", s),
+      noMatch: (s: string) => this.theme.fg("warning", s),
+    });
+    fresh.onSelect = (item: SelectItem) => this.onSelect(item.value);
+    fresh.onCancel = () => this.onDone();
+    return fresh;
+  }
+
+  private renderShell(): void {
+    const keep = this.children.slice(0, 2);
+    this.children.length = 0;
+    this.children.push(...keep);
+    const accent = (s: string): string => this.theme.fg("accent", s);
+    const tabs = (["fleet", "agents"] as View[])
+      .map((v) => (v === this.view ? this.theme.fg("accent", this.theme.bold(`[${v}]`)) : this.theme.fg("dim", v)))
+      .join("  ");
+    this.addChild(new Text(accent(this.theme.bold("  FLEET")) + "  " + tabs, 0, 0));
+    this.addChild(new Spacer(1));
+
+    if (this.runMode && (this.taskInput || this.linkInput)) {
+      const prompt = this.linkPhase === "task" ? "  task> " : "  link to todo? (id or blank to create fleet task): ";
+      this.addChild(new Text(this.theme.fg("accent", prompt), 0, 0));
+      this.addChild(this.linkPhase === "task" ? this.taskInput! : this.linkInput!);
+      this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
+    } else if (this.infoAgent) {
+      // i:Info read-only detail pane (agents view)
+      for (const line of agentInfo(this.infoAgent).split("\n")) {
+        this.addChild(new Text(this.theme.fg("text", line), 0, 0));
+      }
+    } else {
+      this.addChild(this.list);
+    }
+
+    this.addChild(new Spacer(1));
+    const hint =
+      this.infoAgent
+        ? "  esc:Back"
+        : this.view === "fleet"
+          ? "  r:Run-new  s:Stop  o:Open-todo  tab:Agents  q:Quit"
+          : "  r:Run  e:Edit  i:Info  d:Reload  tab:Fleet  q:Quit";
+    this.addChild(new Text(this.theme.fg("dim", hint), 0, 0));
+    this.addChild(new Spacer(1));
+    this.addChild(new DynamicBorder(accent));
+    this.invalidate();
+  }
+
+  private onSelect(value: string): void {
+    if (this.view === "agents") this.startRun(value);
+    // Fleet view: selection is informational; actions are the `r`/`s`/`o` keys.
+    void value;
+  }
+
+  private startRun(agentName: string): void {
+    this.linkPhase = "task";
+    this.taskInput = new Input();
+    this.taskInput.onSubmit = (task: string) => {
+      if (!task.trim()) { this.cancelRun(); return; }
+      this.linkPhase = "link";
+      this.linkInput = new Input();
+      this.linkInput.onSubmit = (todoIdRaw: string) => {
+        void this.executeRun(agentName, task.trim(), todoIdRaw.trim() || undefined);
+      };
+      this.linkInput.onEscape = () => { void this.executeRun(agentName, task.trim(), undefined); };
+      this.renderShell();
+    };
+    this.taskInput.onEscape = () => this.cancelRun();
+    this.runMode = true;
+    this.renderShell();
+  }
+
+  private async executeRun(agent: string, task: string, todoId?: string): Promise<void> {
+    this.runMode = false;
+    this.taskInput = null;
+    this.linkInput = null;
+    this.renderShell();
+    const res: SpawnResult = await spawnSubagent({
+      agent, task, todoId, track: true,
+      registry: this.deps.registry, todoSync: this.deps.todoSync,
+      runRegistry: this.deps.runRegistry, lock: this.deps.lock,
+      childFactory: this.deps.childFactory,
+      parentModel: this.deps.parentModel, parentCwd: this.deps.parentCwd,
+      // live Fleet row during the run (SPEC-1 §4c) — re-render on each turn_end
+      onEvent: (e) => {
+        if (e.type === "turn_end") {
+          this.list = this.buildList();
+          this.renderShell();
+        }
+      },
+    });
+    this.list = this.buildList();
+    this.renderShell();
+    this.onNotify(
+      `${res.status}: ${res.runId}${res.error ? " — " + res.error : ""}`,
+      res.status === "completed" ? "info" : "warning",
+    );
+  }
+
+  private cancelRun(): void {
+    this.runMode = false;
+    this.taskInput = null;
+    this.linkInput = null;
+    this.renderShell();
+  }
+
+  private switchView(): void {
+    this.view = this.view === "fleet" ? "agents" : "fleet";
+    this.list = this.buildList();
+    this.renderShell();
+  }
+
+  handleInput(data: string): void {
+    if (this.infoAgent) {
+      if (matchesKey(data, "escape")) { this.infoAgent = null; this.renderShell(); }
+      return;
+    }
+    if (this.runMode && (this.taskInput || this.linkInput)) {
+      if (matchesKey(data, "escape")) { this.cancelRun(); return; }
+      (this.linkPhase === "task" ? this.taskInput! : this.linkInput!).handleInput(data);
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, "escape")) { this.onDone(); return; }
+    if (matchesKey(data, "tab")) { this.switchView(); return; }
+    if (matchesKey(data, "q")) { this.onDone(); return; }
+    if (matchesKey(data, "r") && this.view === "agents") {
+      const sel = this.list.getSelectedItem();
+      if (sel) this.startRun(sel.value);
+      return;
+    }
+    if (matchesKey(data, "i") && this.view === "agents") {
+      const sel = this.list.getSelectedItem();
+      if (sel) { this.infoAgent = this.deps.registry.get(sel.value) ?? null; this.renderShell(); }
+      return;
+    }
+    this.list.handleInput(data);
+    this.invalidate();
+  }
+}
+
+/** Factory used by src/index.ts to open the panel via ctx.ui.custom. */
+export function openFleetPanel(
+  deps: FleetPanelDeps,
+  ctx: {
+    ui: {
+      custom: (factory: (tui: unknown, theme: Theme, kb: unknown, done: () => void) => Container) => void;
+      notify: (m: string, t?: "info" | "warning" | "error") => void;
+    };
+  },
+): void {
+  ctx.ui.custom((_tui, theme, _kb, done) => {
+    return new FleetPanel({ theme, deps, onDone: done, onNotify: (m, t) => ctx.ui.notify(m, t) });
+  });
+}

package/src/panel/rows.ts

@@ -0,0 +1,53 @@
+// src/panel/rows.ts
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { FleetRunStatus } from "../todo-sync/port.ts";
+import type { RunRecord } from "../engine/run-registry.ts";
+
+export function fmtDuration(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${s % 60}s`;
+}
+
+const STATUS_GLYPH: Record<FleetRunStatus, string> = {
+  running: "▶",
+  completed: "✓",
+  failed: "✗",
+  aborted: "✗",
+};
+
+export function fleetRow(run: RunRecord, ctxPercent?: number): string {
+  const dur = run.endedAt ? fmtDuration(run.endedAt - run.startedAt) : "—";
+  const todo = run.todoId ? `  ${run.todoId}` : "";
+  const summary = run.resultSummary ? `  "${run.resultSummary}"` : "";
+  const ctx = ctxPercent !== undefined ? `  ${ctxPercent}% ctx` : "";
+  return `${STATUS_GLYPH[run.status]} ${run.runId}  ${run.agent}  ${run.status}  ${dur}${ctx}${todo}${summary}`;
+}
+
+export function agentsRow(agent: AgentDef): string {
+  const model = agent.model ?? "(default)";
+  const chip = `armory:[t${agent.todoSync ? "✓" : "✗"} m${agent.memoryHydrate ? "✓" : "✗"} v${agent.vision ? "✓" : "✗"}]`;
+  const skills = agent.skills?.length ? `  skills: ${agent.skills.join(",")}` : "";
+  const tools = agent.tools?.length ? `  tools: ${agent.tools.join(",")}` : "";
+  return `${agent.name}  [${agent.source}]  ${model}${tools}${skills}  ${chip}`;
+}
+
+export function agentInfo(agent: AgentDef): string {
+  const lines = [
+    `name: ${agent.name}`,
+    `source: ${agent.source}`,
+    `model: ${agent.model ?? "(default)"}`,
+    `thinkingLevel: ${agent.thinkingLevel ?? "(model default)"}`,
+    `tools: ${agent.tools?.length ? agent.tools.join(", ") : "(pi default)"}`,
+    `skills: ${agent.skills?.length ? agent.skills.join(", ") : "(none)"}`,
+    `todoSync: ${agent.todoSync ? "✓" : "✗"}`,
+    `memoryHydrate: ${agent.memoryHydrate ? "✓" : "✗"}`,
+    `vision: ${agent.vision ? "✓" : "✗"}`,
+    `file: ${agent.filePath}`,
+    "",
+    "── role prompt ──",
+    agent.rolePrompt.trim(),
+  ];
+  return lines.join("\n");
+}

package/src/registry/discovery.ts

@@ -0,0 +1,83 @@
+// src/registry/discovery.ts
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { parseAgentFile, type AgentDef, FrontmatterError } from "./frontmatter.ts";
+
+export interface DiscoverOpts {
+  projectDir: string | null;
+  globalDir: string | null;
+  builtinDir: string | null;
+}
+
+export interface DiscoverResult {
+  agents: Map<string, AgentDef>;
+  warnings: string[];
+  errors: string[];
+}
+
+/** Recursively collect *.md file paths under dir, with a realpath visited-set
+ *  guard against symlink cycles (trusted dev env, but cheap insurance). */
+function collectMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  const visited = new Set<string>();
+  const walk = (d: string): void => {
+    if (!existsSync(d)) return;
+    let real: string;
+    try {
+      real = realpathSync(d);
+    } catch {
+      return;
+    }
+    if (visited.has(real)) return;
+    visited.add(real);
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        out.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** Load order: builtin -> global -> project (later wins on name; same-scope dup = error). */
+export function discoverAgents(opts: DiscoverOpts): DiscoverResult {
+  const agents = new Map<string, AgentDef>();
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  const loadScope = (dir: string | null, source: AgentDef["source"]): void => {
+    if (!dir) return;
+    const files = collectMarkdown(dir).sort(); // stable order for collision reporting
+    for (const f of files) {
+      let content: string;
+      try {
+        content = readFileSync(f, "utf8");
+      } catch {
+        warnings.push(`${f}: unreadable file, skipped`);
+        continue;
+      }
+      try {
+        const def = parseAgentFile(content, f, source);
+        const existing = agents.get(def.name);
+        if (existing && existing.source === source) {
+          errors.push(`duplicate agent '${def.name}' in ${source} scope (${f}); first kept`);
+          continue;
+        }
+        // cross-scope override (project over global/builtin) is fine
+        agents.set(def.name, def);
+      } catch (e) {
+        if (e instanceof FrontmatterError) warnings.push(e.message);
+        else warnings.push(`${f}: ${String(e)}`);
+      }
+    }
+  };
+
+  loadScope(opts.builtinDir, "builtin");
+  loadScope(opts.globalDir, "global");
+  loadScope(opts.projectDir, "project"); // project overrides
+  return { agents, warnings, errors };
+}

package/src/registry/frontmatter.ts

@@ -0,0 +1,69 @@
+// src/registry/frontmatter.ts
+import { parse as parseYaml } from "yaml";
+import { basename, extname } from "node:path";
+
+export type AgentSource = "builtin" | "project" | "global";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export interface AgentDef {
+  name: string;
+  description: string;
+  model?: string;
+  thinkingLevel?: ThinkingLevel;
+  tools?: string[];
+  skills?: string[];
+  rolePrompt: string;
+  todoSync: boolean;
+  memoryHydrate: boolean;
+  vision: boolean;
+  source: AgentSource;
+  filePath: string;
+}
+
+export class FrontmatterError extends Error {
+  override name = "FrontmatterError" as const;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+export function parseAgentFile(content: string, filePath: string, source: AgentSource): AgentDef {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m || m[1] === undefined || m[2] === undefined) {
+    throw new FrontmatterError(`${filePath}: missing --- frontmatter delimiters`);
+  }
+  let raw: Record<string, unknown>;
+  try {
+    raw = (parseYaml(m[1]) ?? {}) as Record<string, unknown>;
+  } catch (e) {
+    throw new FrontmatterError(`${filePath}: invalid YAML (${(e as Error).message})`);
+  }
+  const body = m[2];
+
+  const name = typeof raw.name === "string" && raw.name.trim()
+    ? raw.name.trim()
+    : basename(filePath, extname(filePath));
+  const description = typeof raw.description === "string" ? raw.description.trim() : "";
+  if (!description) throw new FrontmatterError(`${filePath}: description is required`);
+
+  const strList = (v: unknown): string[] | undefined =>
+    Array.isArray(v) ? v.map((x) => String(x)) : undefined;
+
+  const todoSync = raw.todoSync === undefined ? true : Boolean(raw.todoSync);
+  const memoryHydrate = raw.memoryHydrate === undefined ? true : Boolean(raw.memoryHydrate);
+  const vision = raw.vision === undefined ? true : Boolean(raw.vision);
+
+  return {
+    name,
+    description,
+    model: typeof raw.model === "string" ? raw.model : undefined,
+    thinkingLevel: typeof raw.thinkingLevel === "string" ? (raw.thinkingLevel as ThinkingLevel) : undefined,
+    tools: strList(raw.tools),
+    skills: strList(raw.skills),
+    rolePrompt: body,
+    todoSync,
+    memoryHydrate,
+    vision,
+    source,
+    filePath,
+  };
+}

package/src/todo-sync/adapter.ts

@@ -0,0 +1,84 @@
+// src/todo-sync/adapter.ts
+import {
+  addTodo,
+  getTodo,
+  updateTodo,
+  type Status,
+} from "@getpipher/armory-todo";
+import type { LinkResult, RunMeta, TodoSyncPort } from "./port.ts";
+
+const FLEET_PROJECT = "fleet";
+const FLEET_SOURCE = "armory-fleet";
+const FLEET_TAG = "fleet-run";
+const OPEN_STATES: Status[] = ["open", "in_progress"];
+
+function titleFor(run: RunMeta): string {
+  const raw = `[${run.agent}] ${run.task}`.trim();
+  return raw.length > 120 ? raw.slice(0, 117) + "…" : raw;
+}
+
+/** Append a note line to a todo (read-then-write; updateTodo replaces notes). */
+function appendNote(id: string, line: string): void {
+  const t = getTodo(id);
+  const sep = t.notes ? "\n\n" : "";
+  updateTodo(id, { notes: t.notes + sep + line });
+}
+
+/** Add the fleet-run tag if missing (read-then-write; updateTodo replaces tags). */
+function ensureFleetTag(id: string): void {
+  const t = getTodo(id);
+  if (!t.tags.includes(FLEET_TAG)) updateTodo(id, { tags: [...t.tags, FLEET_TAG] });
+}
+
+export class ArmoryTodoAdapter implements TodoSyncPort {
+  async linkOrCreateRunTodo(run: RunMeta): Promise<LinkResult> {
+    if (!run.track) return { todoId: null };
+
+    if (run.todoId) {
+      const t = getTodo(run.todoId);
+      if (!OPEN_STATES.includes(t.status)) {
+        throw new Error(
+          `linked todo ${run.todoId} is ${t.status}; cannot start run against a closed todo`,
+        );
+      }
+      const priorStatus = t.status;
+      ensureFleetTag(run.todoId);
+      appendNote(run.todoId, `fleet-run:${run.runId}`);
+      updateTodo(run.todoId, { status: "in_progress" });
+      return { todoId: run.todoId, priorStatus: String(priorStatus) };
+    }
+
+    const created = addTodo({
+      title: titleFor(run),
+      project: FLEET_PROJECT,
+      source: FLEET_SOURCE,
+      priority: "med",
+      tags: [FLEET_TAG],
+      notes: `fleet-run:${run.runId}\n\nTask: ${run.task}`,
+    });
+    updateTodo(created.id, { status: "in_progress" });
+    return { todoId: created.id }; // priorStatus undefined -> created
+  }
+
+  async markRunTodoDone(todoId: string | null, priorStatus: string | undefined, result: string): Promise<void> {
+    if (!todoId) return;
+    if (priorStatus === undefined) {
+      // fleet-created -> fleet closes it
+      updateTodo(todoId, { status: "done" });
+    } else {
+      // linked -> restore prior (user owns the close)
+      updateTodo(todoId, { status: priorStatus as Status });
+    }
+    appendNote(todoId, `fleet-run done: ${result}`);
+  }
+
+  async markRunTodoReverted(todoId: string | null, priorStatus: string | undefined, reason: string): Promise<void> {
+    if (!todoId) return;
+    if (priorStatus === undefined) {
+      updateTodo(todoId, { status: "open" }); // created -> retryable
+    } else {
+      updateTodo(todoId, { status: priorStatus as Status });
+    }
+    appendNote(todoId, `fleet-run reverted: ${reason}`);
+  }
+}

package/src/todo-sync/port.ts

@@ -0,0 +1,41 @@
+// src/todo-sync/port.ts
+/**
+ * Fleet-owned todo-sync contract. Fleet core depends only on this port;
+ * ArmoryTodoAdapter (src/todo-sync/adapter.ts) is the sole importer of
+ * @getpipher/armory-todo. This insulation is what makes armory-todo
+ * evolution safe — see SPEC-1 §6 / §2.2.
+ */
+
+export type FleetRunStatus = "running" | "completed" | "failed" | "aborted";
+
+/** Minimum info the engine passes the port to link-or-create a run's todo. */
+export interface RunMeta {
+  runId: string;
+  agent: string;
+  task: string;
+  /** explicit link to an existing open/in_progress todo; undefined = create. */
+  todoId?: string;
+  /** tracked-by-default (SPEC-1 Q3b); false = do not touch armory-todo. */
+  track: boolean;
+}
+
+/**
+ * Implementations return the linked/created todoId (or null when untracked)
+ * and, for a linked todo, its prior status so the engine can restore it.
+ * priorStatus is a string (armory-todo's Status union) to keep the port
+ * decoupled from armory-todo's types.
+ */
+export interface LinkResult {
+  todoId: string | null;
+  /** undefined when the todo was freshly created (no prior status exists). */
+  priorStatus?: string;
+}
+
+export interface TodoSyncPort {
+  /** Before the run: link to todoId (validate open/in_progress) or create a fleet task. */
+  linkOrCreateRunTodo(run: RunMeta): Promise<LinkResult>;
+  /** After a completed run: fleet-created -> done; linked -> restore prior + result note. */
+  markRunTodoDone(todoId: string | null, priorStatus: string | undefined, result: string): Promise<void>;
+  /** After a failed/aborted run: fleet-created -> open; linked -> restore prior. + reason note. */
+  markRunTodoReverted(todoId: string | null, priorStatus: string | undefined, reason: string): Promise<void>;
+}

package/src/tools/subagent.ts

@@ -0,0 +1,75 @@
+// src/tools/subagent.ts
+import { Type, type Static } from "typebox";
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { TodoSyncPort } from "../todo-sync/port.ts";
+import type { RunRegistry } from "../engine/run-registry.ts";
+import type { SingleSlotLock } from "../engine/concurrency-lock.ts";
+import type { ChildSessionFactory, SpawnResult } from "../engine/spawnSubagent.ts";
+import { spawnSubagent } from "../engine/spawnSubagent.ts";
+
+export const subagentParams = Type.Object({
+  agent: Type.String({ description: "Agent name from the registry (builtin, project, or global)." }),
+  task: Type.String({ description: "The prompt to hand the child subagent." }),
+  todoId: Type.Optional(Type.String({ description: "Explicit link to an existing open/in_progress armory-todo todo. Omit to create a fleet task." })),
+  track: Type.Optional(Type.Boolean({ description: "Default true. Pass false only for throwaway lookups that don't represent real work." })),
+  model: Type.Optional(Type.String({ description: 'Override the agent model, e.g. "anthropic/claude-sonnet-4".' })),
+});
+
+export type SubagentInput = Static<typeof subagentParams>;
+
+export interface SubagentToolDeps {
+  registry: Map<string, AgentDef>;
+  runRegistry: RunRegistry;
+  lock: SingleSlotLock;
+  todoSync: TodoSyncPort;
+  childFactory: ChildSessionFactory;
+  parentModel: { provider: string; id: string };
+  parentCwd: string;
+}
+
+/** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
+export function createSubagentTool(deps: SubagentToolDeps) {
+  return {
+    name: "subagent",
+    label: "Subagent",
+    description: "Delegate a task to a named armory-native subagent (foreground, synchronous). The run is tracked in armory-todo by default.",
+    promptSnippet: "Delegate a focused task to a subagent",
+    promptGuidelines: [
+      "Use subagent to delegate an isolated, well-scoped task to a named agent; it runs in the foreground and returns the result + a runId.",
+      "Pass todoId to link the run to an existing open todo you see in the Open TODOs block; otherwise fleet creates a tracked fleet task.",
+      "Pass track:false only for trivial throwaway lookups that don't represent real work.",
+    ],
+    parameters: subagentParams,
+    async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      const res: SpawnResult = await spawnSubagent({
+        agent: params.agent,
+        task: params.task,
+        todoId: params.todoId,
+        track: params.track,
+        model: params.model,
+        registry: deps.registry,
+        todoSync: deps.todoSync,
+        runRegistry: deps.runRegistry,
+        lock: deps.lock,
+        childFactory: deps.childFactory,
+        parentModel: deps.parentModel,
+        parentCwd: deps.parentCwd,
+        signal,
+        onEvent: (e) => {
+          if (ctx?.ui?.setWidget && e.type === "turn_end") {
+            ctx.ui.setWidget("fleet", [`▶ ${params.agent} · running`]);
+          }
+        },
+      });
+      const isError = res.status === "failed" || res.status === "aborted";
+      return {
+        content: [{ type: "text" as const, text: isError ? (res.error ?? res.status) : res.finalText }],
+        details: {
+          runId: res.runId, todoId: res.todoId, agent: res.agent, model: res.model,
+          status: res.status, durationMs: res.durationMs, tokenTotal: res.tokenTotal,
+        },
+        isError,
+      };
+    },
+  };
+}

package/src/vision/adapter.ts

@@ -0,0 +1,51 @@
+// src/vision/adapter.ts — ONLY file importing @getpipher/vision.
+import {
+  isMultimodal,
+  createVisionDelegator,
+  type VisionConfig,
+  type DelegateResult,
+  type ModelRegistryLike,
+} from "@getpipher/vision";
+import type { Model } from "@earendil-works/pi-ai";
+import type { VisionPort, VisionDelegateParams, VisionDelegateResult } from "./port.ts";
+
+export interface ArmoryVisionAdapterDeps {
+  /** A ModelRegistry (or the { find, getApiKeyAndHeaders } slice). Fleet constructs new ModelRegistry(modelRuntime). */
+  modelRegistry: ModelRegistryLike;
+  /** The cwd for image path resolution. */
+  cwd: string;
+  /** The pi agent dir (where vision.json lives). */
+  agentDir: string;
+}
+
+export class ArmoryVisionAdapter implements VisionPort {
+  private readonly delegator: ReturnType<typeof createVisionDelegator>;
+  constructor(deps: ArmoryVisionAdapterDeps) {
+    this.delegator = createVisionDelegator({ modelRegistry: deps.modelRegistry, cwd: deps.cwd, agentDir: deps.agentDir });
+  }
+  isMultimodal(model: Model<any> | undefined): boolean {
+    return isMultimodal(model);
+  }
+  isConfigured(): boolean {
+    const c = this.delegator.config as VisionConfig;
+    return Boolean(c.enabled && c.provider && c.model);
+  }
+  async delegate(params: VisionDelegateParams, signal?: AbortSignal): Promise<VisionDelegateResult> {
+    if (!this.isConfigured()) {
+      return {
+        ok: false,
+        error: "no vision model configured; run `/vision model <id>` in the host or set `vision: false` on this agent.",
+      };
+    }
+    const result: DelegateResult = await this.delegator.delegate(
+      {
+        image_path: params.imagePath,
+        prompt: params.prompt ?? "",
+        compress: true,
+        reasoning: this.delegator.config.defaultReasoningEffort ?? "off",
+      },
+      signal,
+    );
+    return result.ok ? { ok: true, text: result.text } : { ok: false, error: result.error.message };
+  }
+}