@pi-unipi/subagents 2.6.1 → 2.6.2

package/src/scheduled-runs.ts

@@ -0,0 +1,351 @@
+/**
+ * @pi-unipi/subagents — Durable scheduled runs
+ *
+ * Ported from pi-subagents src/runs/background/scheduled-runs.ts (core).
+ * Schedules persist per project under OUR layout:
+ * ~/.unipi/schedules/<project-hash>/<id>.json. One-shot (+delay or ISO with
+ * timezone) and fixed-interval (30m/6h/2d/2w) triggers; overlap policy skip;
+* catchUp none|latest; pause/resume/run/delete; run history receipts.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+
+export type ScheduleTrigger =
+  | { kind: "once"; at: string; atMs: number }
+  | { kind: "interval"; every: string; everyMs: number; anchorAt: string; nextRunAt: string };
+
+export interface ScheduleRecord {
+  schemaVersion: 1;
+  id: string;
+  name: string;
+  cwd: string;
+  trigger: ScheduleTrigger;
+  /** Launch parameters captured for the run (agent + task). */
+  agent: string;
+  task: string;
+  overlap: "skip";
+  catchUp: "none" | "latest";
+  timeoutMs?: number;
+  paused: boolean;
+  createdAt: string;
+  updatedAt: string;
+  activeRunId?: string;
+  lastRunId?: string;
+}
+
+export interface ScheduleRunRecord {
+  schemaVersion: 1;
+  id: string;
+  scheduleId: string;
+  plannedAt: string;
+  dueReason: "timer" | "run-due" | "manual";
+  state: "pending" | "running" | "completed" | "failed" | "skipped";
+  startedAt?: string;
+  completedAt?: string;
+  asyncRunId?: string;
+  error?: string;
+}
+
+// ============================================================================
+// Parsing (reference semantics)
+// ============================================================================
+
+export function parseScheduledRunTime(at: string, now = Date.now()): number {
+  const trimmed = at.trim();
+  const relative = trimmed.match(/^\+(\d+)(s|m|h|d)$/);
+  if (relative) {
+    const amount = Number(relative[1]);
+    if (!Number.isSafeInteger(amount) || amount < 1) {
+      throw new Error(`Invalid at value "${at}". Relative delays must be positive, such as "+10m".`);
+    }
+    const unitMs = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[relative[2] as "s" | "m" | "h" | "d"];
+    const result = now + amount * unitMs;
+    if (!Number.isSafeInteger(result)) throw new Error(`Invalid at value "${at}". Relative delay is too large.`);
+    return result;
+  }
+  const iso = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/);
+  if (!iso) throw new Error(`Invalid at value "${at}". Use a one-shot delay such as "+10m" or an ISO timestamp with timezone.`);
+  const year = Number(iso[1]);
+  const month = Number(iso[2]);
+  const day = Number(iso[3]);
+  const hour = Number(iso[4]);
+  const minute = Number(iso[5]);
+  const second = iso[6] === undefined ? 0 : Number(iso[6]);
+  const zone = iso[7]!;
+  const offsetHour = zone === "Z" ? 0 : Number(zone.slice(1, 3));
+  const offsetMinute = zone === "Z" ? 0 : Number(zone.slice(4, 6));
+  const daysInMonth = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+  const parsed = Date.parse(trimmed);
+  if (
+    month < 1 || month > 12 || day < 1 || day > daysInMonth || hour > 23 || minute > 59 ||
+    second > 59 || offsetHour > 23 || offsetMinute > 59 || !Number.isFinite(parsed)
+  ) {
+    throw new Error(`Invalid at value "${at}". Use a valid ISO timestamp.`);
+  }
+  if (parsed <= now) throw new Error(`Scheduled time ${new Date(parsed).toISOString()} is in the past.`);
+  return parsed;
+}
+
+export function parseScheduleInterval(every: string): number {
+  const match = every.trim().match(/^(\d+)(m|h|d|w)$/);
+  if (!match) {
+    throw new Error(`Invalid every value "${every}". This first recurring slice supports fixed intervals such as "30m", "6h", "2d", or "2w".`);
+  }
+  const amount = Number(match[1]);
+  if (!Number.isSafeInteger(amount) || amount < 1) throw new Error(`Invalid every value "${every}". Interval must be positive.`);
+  const unitMs = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[match[2] as "m" | "h" | "d" | "w"];
+  const result = amount * unitMs;
+  if (!Number.isSafeInteger(result)) throw new Error(`Invalid every value "${every}". Interval is too large.`);
+  return result;
+}
+
+// ============================================================================
+// Store — OUR layout: ~/.unipi/schedules/<project-hash>/
+// ============================================================================
+
+export function scheduleStorePath(projectRoot: string, storeRoot?: string): string {
+  const resolved = path.resolve(projectRoot);
+  if (!storeRoot) return path.join(homedir(), ".unipi", "schedules", projectHashKey(resolved));
+  const projectKey = createHash("sha256").update(resolved).digest("hex").slice(0, 20);
+  return path.join(storeRoot.startsWith("~/") ? path.join(homedir(), storeRoot.slice(2)) : storeRoot, projectKey);
+}
+
+function projectHashKey(projectRoot: string): string {
+  return createHash("sha256").update(projectRoot).digest("hex").slice(0, 16);
+}
+
+function writeAtomic(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+export class ScheduledRunManager {
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    private projectRoot: string,
+    private opts: {
+      storeRoot?: string;
+      maxPending?: number;
+      /** Launch a due schedule. Returns the async run id. */
+      launch: (record: ScheduleRecord, dueReason: ScheduleRunRecord["dueReason"]) => Promise<string>;
+      pollIntervalMs?: number;
+    },
+  ) {}
+
+  get storeDir(): string {
+    return scheduleStorePath(this.projectRoot, this.opts.storeRoot);
+  }
+
+  private recordPath(id: string): string {
+    return path.join(this.storeDir, `${id}.json`);
+  }
+
+  private historyPath(id: string): string {
+    return path.join(this.storeDir, `${id}.runs.json`);
+  }
+
+  create(input: {
+    name: string;
+    agent: string;
+    task: string;
+    at?: string;
+    every?: string;
+    catchUp?: "none" | "latest";
+    timeoutMs?: number;
+  }, now = Date.now()): ScheduleRecord {
+    if (!input.name?.trim()) throw new Error("schedule name must be a non-empty string.");
+    if (!input.agent?.trim()) throw new Error("schedule requires an agent.");
+    if (!input.task?.trim()) throw new Error("schedule requires a task.");
+    let trigger: ScheduleTrigger;
+    if (input.at !== undefined && input.every !== undefined) {
+      throw new Error("Use either 'at' (one-shot) or 'every' (recurring), not both.");
+    }
+    if (input.at !== undefined) {
+      const atMs = parseScheduledRunTime(input.at, now);
+      trigger = { kind: "once", at: input.at.trim(), atMs };
+    } else if (input.every !== undefined) {
+      const everyMs = parseScheduleInterval(input.every);
+      trigger = {
+        kind: "interval",
+        every: input.every.trim(),
+        everyMs,
+        anchorAt: new Date(now).toISOString(),
+        nextRunAt: new Date(now + everyMs).toISOString(),
+      };
+    } else {
+      throw new Error("schedule requires 'at' (one-shot) or 'every' (recurring).");
+    }
+
+    // maxPending cap
+    const existing = this.list();
+    const maxPending = this.opts.maxPending ?? 20;
+    if (existing.filter((r) => !r.paused && r.trigger.kind === "interval").length >= maxPending) {
+      throw new Error(`Pending schedule cap reached (${maxPending}). Delete or pause schedules first.`);
+    }
+
+    const record: ScheduleRecord = {
+      schemaVersion: 1,
+      id: randomUUID(),
+      name: input.name.trim(),
+      cwd: path.resolve(this.projectRoot),
+      trigger,
+      agent: input.agent.trim(),
+      task: input.task.trim(),
+      overlap: "skip",
+      catchUp: input.catchUp ?? "latest",
+      ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+      paused: false,
+      createdAt: new Date(now).toISOString(),
+      updatedAt: new Date(now).toISOString(),
+    };
+    writeAtomic(this.recordPath(record.id), record);
+    return record;
+  }
+
+  list(): ScheduleRecord[] {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(this.storeDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const records: ScheduleRecord[] = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json") || entry.name.endsWith(".runs.json")) continue;
+      try {
+        records.push(JSON.parse(fs.readFileSync(path.join(this.storeDir, entry.name), "utf8")) as ScheduleRecord);
+      } catch {
+        // Skip corrupt records.
+      }
+    }
+    return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  show(idOrPrefix: string): ScheduleRecord | undefined {
+    return this.list().find((r) => r.id.startsWith(idOrPrefix));
+  }
+
+  private save(record: ScheduleRecord): void {
+    writeAtomic(this.recordPath(record.id), record);
+  }
+
+  setPaused(idOrPrefix: string, paused: boolean): ScheduleRecord {
+    const record = this.show(idOrPrefix);
+    if (!record) throw new Error(`No schedule matches "${idOrPrefix}".`);
+    record.paused = paused;
+    record.updatedAt = new Date().toISOString();
+    this.save(record);
+    return record;
+  }
+
+  delete(idOrPrefix: string): boolean {
+    const record = this.show(idOrPrefix);
+    if (!record) return false;
+    fs.rmSync(this.recordPath(record.id), { force: true });
+    fs.rmSync(this.historyPath(record.id), { force: true });
+    return true;
+  }
+
+  /** Run a schedule immediately (manual trigger). */
+  async runNow(idOrPrefix: string): Promise<ScheduleRunRecord> {
+    const record = this.show(idOrPrefix);
+    if (!record) throw new Error(`No schedule matches "${idOrPrefix}".`);
+    return this.execute(record, "manual");
+  }
+
+  private async execute(record: ScheduleRecord, dueReason: ScheduleRunRecord["dueReason"]): Promise<ScheduleRunRecord> {
+    // Overlap policy: skip when a run is already active.
+    if (record.activeRunId) {
+      return {
+        schemaVersion: 1,
+        id: randomUUID(),
+        scheduleId: record.id,
+        plannedAt: new Date().toISOString(),
+        dueReason,
+        state: "skipped",
+        error: "overlap: previous run still active",
+      };
+    }
+
+    const runRecord: ScheduleRunRecord = {
+      schemaVersion: 1,
+      id: randomUUID(),
+      scheduleId: record.id,
+      plannedAt: new Date().toISOString(),
+      dueReason,
+      state: "running",
+      startedAt: new Date().toISOString(),
+    };
+
+    try {
+      const asyncRunId = await this.opts.launch(record, dueReason);
+      runRecord.asyncRunId = asyncRunId;
+      runRecord.state = "completed";
+    } catch (error) {
+      runRecord.state = "failed";
+      runRecord.error = error instanceof Error ? error.message : String(error);
+    }
+    runRecord.completedAt = new Date().toISOString();
+
+    // Update the schedule + append history.
+    record.lastRunId = runRecord.id;
+    record.activeRunId = undefined;
+    record.updatedAt = new Date().toISOString();
+    if (record.trigger.kind === "interval") {
+      record.trigger.nextRunAt = new Date(Date.now() + record.trigger.everyMs).toISOString();
+    }
+    this.save(record);
+
+    const history = this.readHistory(record.id);
+    history.push(runRecord);
+    writeAtomic(this.historyPath(record.id), history);
+    return runRecord;
+  }
+
+  readHistory(idOrPrefix: string): ScheduleRunRecord[] {
+    const record = this.show(idOrPrefix);
+    if (!record) return [];
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.historyPath(record.id), "utf8")) as ScheduleRunRecord[];
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** Tick: launch all due schedules. Called by the poll timer. */
+  async runDue(): Promise<ScheduleRunRecord[]> {
+    const results: ScheduleRunRecord[] = [];
+    const now = Date.now();
+    for (const record of this.list()) {
+      if (record.paused) continue;
+      let due = false;
+      if (record.trigger.kind === "once") {
+        due = record.trigger.atMs <= now;
+      } else {
+        due = Date.parse(record.trigger.nextRunAt) <= now;
+      }
+      if (due) results.push(await this.execute(record, "timer"));
+    }
+    return results;
+  }
+
+  startPolling(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.runDue().catch(() => {});
+    }, this.opts.pollIntervalMs ?? 60_000);
+    this.timer.unref?.();
+  }
+
+  stopPolling(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+}

package/src/schemas.ts

@@ -0,0 +1,263 @@
+/**
+ * @pi-unipi/subagents — Tool parameter schemas (pi-subagents parity)
+ *
+ * Ported from nicobailon/pi-subagents src/extension/schemas.ts. Parameter
+ * names follow the reference (they are arguments, not tool names — no
+ * convention clash); our legacy spawn_helper params (type/prompt/description/
+ * run_in_background/max_turns) remain accepted as aliases.
+ */
+
+import { Type } from "typebox";
+
+const TurnBudgetOverride = Type.Object(
+  {
+    maxTurns: Type.Integer({ minimum: 1 }),
+    graceTurns: Type.Optional(Type.Integer({ minimum: 0 })),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "Optional assistant-turn budget. At maxTurns the child is asked to wrap up; after graceTurns (default 1) additional assistant turns it is aborted and partial output is returned.",
+  },
+);
+
+const ToolBudgetBlock = Type.Unsafe({
+  anyOf: [
+    { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+    { type: "string", enum: ["*"] },
+  ],
+});
+
+const ToolBudgetOverride = Type.Object(
+  {
+    soft: Type.Optional(Type.Integer({ minimum: 1 })),
+    hard: Type.Integer({ minimum: 1 }),
+    block: Type.Optional(ToolBudgetBlock),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "Optional child tool-call budget. soft nudges the child to finalize; after hard, block tools (default read/grep/find/ls, or '*' for all tools) are blocked so the child can finalize. Final assistant text is never blocked.",
+  },
+);
+
+const UsageBudgetLimitOverride = Type.Object(
+  {
+    soft: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+    hard: Type.Number({ exclusiveMinimum: 0 }),
+  },
+  { additionalProperties: false },
+);
+
+const UsageBudgetOverride = Type.Object(
+  {
+    tokens: Type.Optional(UsageBudgetLimitOverride),
+    costUsd: Type.Optional(UsageBudgetLimitOverride),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "Optional root-only reported-usage budget. Soft limits are status-only. Hard limits prevent later child launches after usage is reconciled; running children are not stopped.",
+  },
+);
+
+const MaxOutputOverride = Type.Object(
+  {
+    bytes: Type.Optional(Type.Integer({ minimum: 1 })),
+    lines: Type.Optional(Type.Integer({ minimum: 1 })),
+  },
+  { additionalProperties: false, description: "Final output truncation limits. Defaults: 200KB / 5000 lines." },
+);
+
+/**
+ * spawn_helper parameter surface. Legacy fields (type, prompt, description,
+ * run_in_background, max_turns) are the unipi convention and stay primary;
+ * reference fields (agent, task, action, workflowScript, budgets, ...) join
+ * them. Execution paths map: agent→type, task→prompt, async→run_in_background.
+ */
+export const SpawnHelperParams = Type.Object({
+  // ---- unipi legacy (preserved) ----
+  type: Type.Optional(
+    Type.String({ description: "Agent type (alias of agent). Enabled builtin or custom type." }),
+  ),
+  prompt: Type.Optional(
+    Type.String({ description: "The task for the agent to perform (alias of task)." }),
+  ),
+  description: Type.Optional(
+    Type.String({ description: "A short (3-5 word) description of the task." }),
+  ),
+  run_in_background: Type.Optional(
+    Type.Boolean({ description: "Run in background (alias of async). Returns helper ID immediately." }),
+  ),
+  max_turns: Type.Optional(
+    Type.Number({ minimum: 1, description: "Max agentic turns before stopping." }),
+  ),
+
+  // ---- reference surface ----
+  agent: Type.Optional(
+    Type.String({ description: "Agent for one-child execution, or target for management actions." }),
+  ),
+  task: Type.Optional(
+    Type.String({
+      description: "Optional one-child task. Requires agent; cannot combine with action or workflowScript.",
+    }),
+  ),
+  action: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description:
+        "Optional management/control action (list, get, status, steer, stop, doctor, ...). Omit for execution.",
+    }),
+  ),
+  id: Type.Optional(Type.String({ description: "Run id/prefix for status, interrupt, steer." })),
+  runId: Type.Optional(Type.String({ description: "Target run ID. Prefer id." })),
+  dir: Type.Optional(Type.String({ description: "Async run directory for status/stop/resume/steer." })),
+  index: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Zero-based child index for actions targeting a specific child." }),
+  ),
+  view: Type.Optional(
+    Type.String({
+      enum: ["fleet", "transcript"],
+      description: "Optional status view: fleet surface or transcript tail.",
+    }),
+  ),
+  lines: Type.Optional(
+    Type.Integer({ minimum: 1, maximum: 500, description: "Max transcript lines for status view=transcript. Default 80." }),
+  ),
+  topic: Type.Optional(Type.String({ description: "Guide topic for action=guide." })),
+  message: Type.Optional(
+    Type.String({ description: "Follow-up message for resume, live guidance for steer." }),
+  ),
+  mode: Type.Optional(
+    Type.String({
+      enum: ["steer", "follow_up", "auto"],
+      description: "Delivery mode for action=steer.",
+    }),
+  ),
+  additional: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Positive launches to add with action=grant-spawn-budget.",
+    }),
+  ),
+  missionId: Type.Optional(Type.String({ description: "Mission id." })),
+  mission: Type.Optional(
+    Type.Unsafe({
+      anyOf: [{ type: "object", additionalProperties: true }, { type: "boolean", enum: [false] }],
+      description: "Mission object, or false for no mission.",
+    }),
+  ),
+  config: Type.Optional(
+    Type.Unsafe({
+      anyOf: [{ type: "object", additionalProperties: true }, { type: "string" }],
+      description: "Agent config for create/update. Object or JSON string.",
+    }),
+  ),
+  workflowScript: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description:
+        "Trusted inline JavaScript statement body. Use await runs.run(key, {agent, task}) for one child, runs.all([...]) for parallel fanout, await runs.steer(key, message, opts) to steer. Plain helper functions or explicit Promise chains only; nested async helpers are rejected. Explicit return for output. async:true for background (default), async:false only when the parent must block.",
+    }),
+  ),
+  chatProgress: Type.Optional(
+    Type.String({
+      enum: ["auto", "off", "live-card"],
+      description: "WorkflowScript chat progress projection.",
+    }),
+  ),
+  isolation: Type.Optional(
+    Type.String({ enum: ["none", "worktree"], description: "Workflow child isolation." }),
+  ),
+  worktree: Type.Optional(
+    Type.Boolean({ description: "Managed child isolation via separate git worktrees." }),
+  ),
+  context: Type.Optional(
+    Type.String({
+      enum: ["fresh", "fork", "profile"],
+      description:
+        "'fresh' or 'fork' to branch from parent session, or 'profile' for the agent's declared defaultContext.",
+    }),
+  ),
+  async: Type.Optional(
+    Type.Boolean({ description: "Run in background. Set false only when the parent must block." }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({ minimum: 1, description: "Run-level max runtime ms. Alias maxRuntimeMs." }),
+  ),
+  maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs." })),
+  toolTimeoutMs: Type.Optional(
+    Type.Integer({ minimum: 1, description: "Optional hard per-tool-call timeout in ms." }),
+  ),
+  turnBudget: Type.Optional(TurnBudgetOverride),
+  toolBudget: Type.Optional(ToolBudgetOverride),
+  usageBudget: Type.Optional(UsageBudgetOverride),
+  agentScope: Type.Optional(
+    Type.String({
+      description: "Agent discovery scope: 'user', 'project', or 'both' (default both; project wins collisions).",
+    }),
+  ),
+  cwd: Type.Optional(Type.String({ description: "Execution cwd override." })),
+  artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts. Default true." })),
+  includeProgress: Type.Optional(
+    Type.Boolean({ description: "Include full progress in result. Default false." }),
+  ),
+  sessionDir: Type.Optional(Type.String({ description: "Directory for child session logs." })),
+  output: Type.Optional(
+    Type.Unsafe({
+      anyOf: [{ type: "string" }, { type: "boolean" }],
+      description: "Default child output file (string), or false to disable.",
+    }),
+  ),
+  outputMode: Type.Optional(
+    Type.String({
+      enum: ["inline", "file-only"],
+      description: "Return saved output inline (default) or only a concise file reference.",
+    }),
+  ),
+  model: Type.Optional(
+    Type.String({
+      description: 'Model override. "provider/modelId" or fuzzy name. Omit to inherit parent model.',
+    }),
+  ),
+  thinking: Type.Optional(
+    Type.String({
+      description: "Thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit parent.",
+    }),
+  ),
+  maxOutput: Type.Optional(MaxOutputOverride),
+});
+
+/** get_helper_result parameter surface (parity with subagent_wait). */
+export const GetHelperResultParams = Type.Object({
+  id: Type.Optional(
+    Type.String({
+      description:
+        "Helper/async run id (or prefix) to wait for. Omit to wait across every active run started in this session.",
+    }),
+  ),
+  nonBlocking: Type.Optional(
+    Type.Boolean({
+      description:
+        "When true, resolve id to one exact run, persist a wake subscription, and return immediately. The originating session is woken on completion/failure/attention. Requires id; cannot combine with all.",
+    }),
+  ),
+  all: Type.Optional(
+    Type.Boolean({
+      description:
+        "Wait for ALL active runs to finish. Default false: return when the first run finishes.",
+    }),
+  ),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Give up waiting after this many milliseconds (runs keep going). Default 1800000.",
+    }),
+  ),
+  stopOnAttention: Type.Optional(
+    Type.Boolean({
+      description:
+        "Blocking waits stop when a run needs attention by default. Set false to wait through idle or long-thinking attention.",
+    }),
+  ),
+});

package/src/slash-commands.ts

@@ -0,0 +1,77 @@
+/**
+ * @pi-unipi/subagents — /unipi:* slash commands (Phase 7)
+ *
+ * subagents-fleet: open the fleet inspector surface.
+ * subagents-doctor: run the doctor report.
+ * subagents-guide: print a guide topic.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import { listAsyncRunSummaries } from "./fleet-data.js";
+import { buildGuideText } from "./guide.js";
+
+export interface SlashDeps {
+  manager: AgentManager;
+  config: { maxConcurrent: number; enabled: boolean; types: Record<string, { enabled?: boolean }> };
+  asyncDirRoot: string;
+  retainedDir?: string;
+}
+
+export function registerSlashCommands(pi: ExtensionAPI, getCtx: () => ExtensionContext | undefined, deps: SlashDeps): void {
+  const send = (markdown: string): void => {
+    pi.sendMessage(
+      { customType: "unipi-response", content: markdown, display: true },
+      { deliverAs: "followUp" },
+    );
+  };
+
+  pi.registerCommand("unipi:subagents-fleet", {
+    description: "Show active subagent fleet (in-process + process runs)",
+    handler: async (_args, _ctx) => {
+      const inProcess = deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued");
+      const asyncRuns = listAsyncRunSummaries(deps.asyncDirRoot).filter(
+        (r) => r.state === "running" || r.state === "queued" || r.state === "pending",
+      );
+      const lines: string[] = ["Active subagent fleet:", ""];
+      if (inProcess.length === 0 && asyncRuns.length === 0) {
+        lines.push("  (no active work — use spawn_helper to delegate)");
+      } else {
+        if (inProcess.length > 0) {
+          lines.push(`In-process (${inProcess.length}):`);
+          for (const record of inProcess) {
+            lines.push(`  - ${record.id} [${record.type}] ${record.status}: ${record.description}`);
+          }
+        }
+        if (asyncRuns.length > 0) {
+          lines.push(`Process runs (${asyncRuns.length}):`);
+          for (const run of asyncRuns) {
+            lines.push(`  - ${run.runId} [${run.agent}] ${run.state}`);
+          }
+        }
+        lines.push("", "FleetView panel: ↓ to inspect · enter opens transcripts.");
+      }
+      send(lines.join("\n"));
+    },
+  });
+
+  pi.registerCommand("unipi:subagents-doctor", {
+    description: "Subagents configuration and capacity diagnosis",
+    handler: async () => {
+      send(
+        "Run the full report via spawn_helper({ action: \"doctor\" }). Quick check:\n" +
+          `- extension enabled: ${deps.config.enabled}\n` +
+          `- known agent types: ${deps.manager.getKnownTypes().length}\n` +
+          `- max concurrent: ${deps.config.maxConcurrent}`,
+      );
+    },
+  });
+
+  pi.registerCommand("unipi:subagents-guide", {
+    description: "Subagents guide (topic argument optional)",
+    handler: async (args, _ctx) => {
+      const topic = args?.trim() || "overview";
+      send(buildGuideText(topic));
+    },
+  });
+}