@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/subagents/src/tool-handler.ts

@@ -1,1144 +0,0 @@
-/**
- * @pi-unipi/subagents — spawn_helper parity handler
- *
- * Routes the extended spawn_helper surface: management actions, workflowScript
- * execution, and legacy single-child launches (type/prompt aliases). Applies
- * the Phase 2 libraries: agent resolution + aliases, enablement, budgets,
- * depth guard, context policy, spawn budgets, timeout defaults, and output
- * truncation. The render/notify plumbing stays in index.ts — this module only
- * decides and executes.
- */
-
-import { existsSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AgentManager } from "./agent-manager.js";
-import type { SubagentsConfig, AgentConfig } from "./types.js";
-import { SUBAGENT_ACTIONS } from "./parity-types.js";
-import { runWorkflowScript, type WorkflowScriptChildResult } from "./workflow-script.js";
-import {
-  resolveTurnBudgetConfig,
-  validateToolBudgetConfig,
-  validateUsageBudgetConfig,
-  appendTurnBudgetSystemPrompt,
-} from "./budgets.js";
-import {
-  createRunFanoutBudget,
-  claimRunFanoutBatch,
-  getRunFanoutBudgetSnapshot,
-  formatRunFanoutBudget,
-} from "./run-fanout-budget.js";
-import { truncateOutput, resolveMaxOutput } from "./output-limits.js";
-import {
-  resolveContext,
-  assertForegroundContextSupported,
-  resolveMaxSubagentDepth,
-  depthExceeded,
-  isFanoutChild,
-  withChildBoundaryInstructions,
-} from "./child-safety.js";
-import { listRetainedChildren, formatRetainedChildren, resolveResumeTarget } from "./retained-children.js";
-import { ASYNC_DIR, TEMP_ROOT_DIR, RESULTS_DIR } from "./parity-types.js";
-import { buildGuideText } from "./guide.js";
-import { ScheduledRunManager } from "./scheduled-runs.js";
-import {
-  validateAcceptanceInput,
-  normalizeAcceptanceInput,
-  normalizeGateAcceptance,
-  evaluateAcceptance,
-  stripAcceptanceReport,
-} from "./acceptance.js";
-import type { AcceptanceConfig } from "./acceptance.js";
-import {
-  resolveMissionStoreLocation,
-  createMission,
-  readMission,
-  listMissions,
-  updateMission,
-  MissionNotFoundError,
-  type MissionStoreConfig,
-  type MissionStatus,
-} from "./mission-store.js";
-
-export interface HandlerDeps {
-  pi: ExtensionAPI;
-  manager: AgentManager;
-  config: SubagentsConfig;
-  /** Legacy single-child spawn (foreground). */
-  spawnForeground: (
-    ctx: ExtensionContext,
-    agentName: string,
-    prompt: string,
-    options: {
-      description?: string;
-      maxTurns?: number;
-      modelInput?: string;
-      thinkingLevel?: unknown;
-      signal?: AbortSignal;
-    },
-  ) => Promise<{ ok: boolean; output: string; error?: string; toolUses: number; durationMs: number }>;
-  /** Legacy single-child spawn (background). */
-  spawnBackground: (
-    ctx: ExtensionContext,
-    agentName: string,
-    prompt: string,
-    options: {
-      description?: string;
-      maxTurns?: number;
-      modelInput?: string;
-      thinkingLevel?: unknown;
-    },
-  ) => string;
-  /** Session-wide cumulative spawn accounting (maxSubagentSpawnsPerSession). */
-  spawnAccounting?: {
-    used(): number;
-    cap(): number | undefined;
-    consume(count: number): void;
-  };
-  /** Depth env for the recursion guard. */
-  env?: NodeJS.ProcessEnv;
-  /** Retained-children dir override (defaults to our async temp root). */
-  retainedDir?: string;
-  /** Mission store config (from OUR subagents.json). */
-  missionConfig?: MissionStoreConfig;
-  /** Project root for mission records. */
-  projectRoot?: string;
-  /** Async process runner (Phase 3). When present, background launches and
-   *  fork contexts run as child pi processes; when absent they error with
-   *  guidance (test environments). */
-  runAsync?: (launch: {
-    agentName: string;
-    task: string;
-    description?: string;
-    model?: string;
-    thinking?: string | false;
-    context: "fresh" | "fork";
-    timeoutMs?: number;
-    maxTurns?: number;
-    /** Resume: continue a retained child in its stored session. */
-    resumeSessionFile?: string;
-    /** Worktree isolation: launch the child in a managed git worktree. */
-    worktree?: boolean;
-  }) => Promise<{
-    runId: string;
-    status: string;
-    output?: string;
-    error?: string;
-  }>;
-}
-
-function textResult(msg: string, details?: unknown) {
-  return { content: [{ type: "text" as const, text: msg }], details };
-}
-
-/**
- * Resolve the effective acceptance config: explicit gate shorthand wins over
- * acceptance; agent-level defaultAcceptance fills gaps. Returns undefined for
- * no gate. Errors are visible strings.
- */
-function resolveEffectiveAcceptance(
-  args: Record<string, unknown>,
-): { ok: true; acceptance?: AcceptanceConfig } | { ok: false; error: string } {
-  if (args.gate !== undefined && args.acceptance !== undefined) {
-    return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
-  }
-  if (args.gate !== undefined) {
-    const normalized = normalizeGateAcceptance(args.gate);
-    if (!normalized) return { ok: false, error: "gate must be a non-empty command string." };
-    return { ok: true, acceptance: normalized };
-  }
-  if (args.acceptance === undefined) return { ok: true, acceptance: undefined };
-  const errors = validateAcceptanceInput(args.acceptance);
-  if (errors.length > 0) return { ok: false, error: errors.join(" ") };
-  return { ok: true, acceptance: normalizeAcceptanceInput(args.acceptance) };
-}
-
-/** Post-run acceptance evaluation wrapper. */
-async function evaluateRunAcceptance(
-  acceptance: AcceptanceConfig | undefined,
-  output: string,
-  cwd: string,
-): Promise<{ output: string; ledger?: Awaited<ReturnType<typeof evaluateAcceptance>> }> {
-  if (!acceptance || acceptance.level === "auto") return { output };
-  const ledger = await evaluateAcceptance({ acceptance, output, cwd });
-  const cleanOutput = stripAcceptanceReport(output);
-  if (ledger.status === "rejected") {
-    return { output: cleanOutput, ledger };
-  }
-  return { output: cleanOutput, ledger };
-}
-
-/** Parse + validate everything, resolve the agent, or return an error result. */
-function preflight(
-  deps: HandlerDeps,
-  args: Record<string, unknown>,
-): { ok: true; agent: AgentConfig; agentName: string; prompt: string } | { ok: false; error: string } {
-  const agentNameRaw = (args.agent ?? args.type) as string | undefined;
-  const prompt = (args.task ?? args.prompt) as string | undefined;
-
-  if (!agentNameRaw || typeof agentNameRaw !== "string") {
-    return { ok: false, error: "spawn_helper requires an agent (or legacy type) parameter." };
-  }
-
-  const agentName = deps.manager.resolveAlias(agentNameRaw);
-  const agent = deps.manager.getAgentConfig(agentName);
-  if (!agent) {
-    const known = deps.manager.getKnownTypes().join(", ");
-    return { ok: false, error: `Unknown agent type "${agentNameRaw}". Known types: ${known}` };
-  }
-  if (!deps.manager.isTypeEnabled(agentName)) {
-    return { ok: false, error: `Agent type "${agentName}" is disabled by configuration.` };
-  }
-
-  // Depth guard
-  const env = deps.env ?? process.env;
-  const maxDepth = resolveMaxSubagentDepth(agent, deps.config, env);
-  if (depthExceeded(env, maxDepth)) {
-    return {
-      ok: false,
-      error: `Subagent depth cap reached (maxSubagentDepth ${maxDepth}). This child cannot spawn further subagents for its assigned fanout.`,
-    };
-  }
-
-  if (!prompt || typeof prompt !== "string" || !prompt.trim()) {
-    return { ok: false, error: "spawn_helper requires a task (or legacy prompt) parameter." };
-  }
-
-  return { ok: true, agent, agentName, prompt };
-}
-
-/**
- * Main entry: route a spawn_helper invocation.
- * Returns a tool result; never throws.
- */
-export async function handleSpawnHelper(
-  deps: HandlerDeps,
-  ctx: ExtensionContext,
-  args: Record<string, unknown>,
-  signal?: AbortSignal,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
-  try {
-    // ---- Management actions ----
-    const action = args.action as string | undefined;
-    if (action !== undefined) {
-      return await handleAction(deps, ctx, action, args);
-    }
-
-    // ---- workflowScript execution ----
-    const workflowScript = args.workflowScript as string | undefined;
-    if (workflowScript !== undefined) {
-      return await handleWorkflowScript(deps, ctx, workflowScript, args, signal);
-    }
-
-    // ---- Single-child launch (legacy + reference params) ----
-    return await handleSingleChild(deps, ctx, args, signal);
-  } catch (error) {
-    return textResult(
-      `spawn_helper failed: ${error instanceof Error ? error.message : String(error)}`,
-      { status: "error", error: error instanceof Error ? error.message : String(error) },
-    );
-  }
-}
-
-// ============================================================================
-// Management actions
-// ============================================================================
-
-async function handleAction(
-  deps: HandlerDeps,
-  _ctx: ExtensionContext,
-  action: string,
-  args: Record<string, unknown>,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
-  if (!(SUBAGENT_ACTIONS as readonly string[]).includes(action)) {
-    return textResult(
-      `Unknown action "${action}". Supported actions: ${SUBAGENT_ACTIONS.join(", ")}.`,
-      { status: "error" },
-    );
-  }
-
-  switch (action) {
-    case "list": {
-      const types = deps.manager.getKnownTypes();
-      const lines = types.map((type) => {
-        const agent = deps.manager.getAgentConfig(type);
-        const enabled = deps.manager.isTypeEnabled(type);
-        const scope = agent?.source ?? "config";
-        const desc = agent?.description ?? "";
-        return `- ${type}${agent?.aliases?.length ? ` (aliases: ${agent.aliases.join(", ")})` : ""} [${scope}]${enabled ? "" : " [disabled]"}: ${desc}`;
-      });
-      return textResult(`Available subagents:\n${lines.join("\n")}`);
-    }
-
-    case "get": {
-      const target = (args.agent ?? args.type ?? args.id) as string | undefined;
-      if (!target) return textResult("action 'get' requires an agent name.");
-      const agentName = deps.manager.resolveAlias(target);
-      const agent = deps.manager.getAgentConfig(agentName);
-      if (!agent) return textResult(`Unknown agent "${target}".`);
-      return textResult(
-        [
-          `Agent: ${agent.name}`,
-          ...(agent.aliases?.length ? [`Aliases: ${agent.aliases.join(", ")}`] : []),
-          `Description: ${agent.description}`,
-          `Source: ${agent.source ?? "builtin"}`,
-          `Tools: ${agent.builtinToolNames?.join(", ") || "(all builtins)"}`,
-          ...(agent.disallowedTools?.length ? [`Disallowed: ${agent.disallowedTools.join(", ")}`] : []),
-          `Prompt mode: ${agent.promptMode}`,
-          ...(agent.model ? [`Model: ${agent.model}`] : []),
-          ...(agent.thinking !== undefined ? [`Thinking: ${String(agent.thinking)}`] : []),
-          ...(agent.defaultContext ? [`Default context: ${agent.defaultContext}`] : []),
-          ...(agent.timeoutMs ? [`Timeout: ${agent.timeoutMs}ms`] : []),
-          `Enabled: ${deps.manager.isTypeEnabled(agentName)}`,
-        ].join("\n"),
-      );
-    }
-
-    case "status": {
-      const accounting = deps.spawnAccounting;
-      const sessionCap = accounting?.cap();
-      const used = accounting?.used() ?? 0;
-      const lines = [
-        `Active agents: ${deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued").length}`,
-        `Max concurrent: ${deps.manager.getMaxConcurrent()}`,
-      ];
-      if (sessionCap !== undefined) {
-        lines.push(
-          `Session spawn budget: ${used}/${sessionCap} used, ${Math.max(0, sessionCap - used)} remaining`,
-        );
-      } else {
-        lines.push("Session spawn budget: unlimited");
-      }
-      const running = deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued");
-      for (const record of running) {
-        lines.push(`- ${record.id} [${record.type}] ${record.status}: ${record.description}`);
-      }
-      return textResult(lines.join("\n"));
-    }
-
-    case "children.list": {
-      const retained = listRetainedChildren(deps.retainedDir ?? ASYNC_DIR);
-      if (retained.length === 0) {
-        // Fall back to in-process completed agents from this session.
-        const recent = deps.manager
-          .listAgents()
-          .filter((a) => a.status !== "running" && a.status !== "queued")
-          .slice(-10);
-        if (recent.length === 0) return textResult("No completed children in this session yet.");
-        return textResult(
-          recent.map((r) => `- ${r.id} [${r.type}] ${r.status}: ${r.description}`).join("\n"),
-        );
-      }
-      return textResult(formatRetainedChildren(retained));
-    }
-
-    case "resume": {
-      const id = args.id as string | undefined;
-      const message = args.message as string | undefined;
-      if (!id) return textResult("action 'resume' requires an id (retained run id or prefix).");
-      if (!message || !message.trim()) return textResult("action 'resume' requires a non-empty follow-up message.");
-      if (!deps.runAsync) {
-        return textResult("action 'resume' requires the background process runner, which is unavailable in this host.", { status: "error" });
-      }
-      const target = resolveResumeTarget(deps.retainedDir ?? ASYNC_DIR, id);
-      if (!target.ok) return textResult(target.error, { status: "error" });
-      const result = await deps.runAsync({
-        agentName: target.agent,
-        task: message.trim(),
-        description: `resume ${target.runId.slice(-8)}`,
-        context: "fresh",
-        resumeSessionFile: target.sessionFile,
-      });
-      return textResult(
-        `Resumed ${target.runId} as ${result.runId} (agent: ${target.agent}, stored session contract kept).\nUse get_helper_result to retrieve results.`,
-        { status: "background", runId: result.runId },
-      );
-    }
-
-    case "stop": {
-      const id = args.id as string | undefined;
-      if (!id) return textResult("action 'stop' requires an id.");
-      const record = deps.manager.getRecord(id);
-      if (!record) return textResult(`Run not found: "${id}".`);
-      record.abortController?.abort();
-      return textResult(`Stop requested for ${id} (${record.type}, ${record.status}).`);
-    }
-
-    case "grant-spawn-budget": {
-      const accounting = deps.spawnAccounting;
-      if (!accounting) return textResult("Spawn budget accounting is unavailable in this host.");
-      const cap = accounting.cap();
-      if (cap === undefined) return textResult("Session spawn budget is unlimited; nothing to grant.");
-      const additional = args.additional as number | undefined;
-      if (typeof additional !== "number" || !Number.isInteger(additional) || additional < 1) {
-        return textResult("action 'grant-spawn-budget' requires a positive integer 'additional'.");
-      }
-      // Grants require interactive confirmation — delegated to the host via pi.
-      return textResult(
-        `grant-spawn-budget requires native user confirmation; requested +${additional} against cap ${cap}. ` +
-          `This action needs the interactive parent; run it from the root session.`,
-      );
-    }
-
-    case "doctor": {
-      const lines: string[] = [
-        "Subagents doctor report",
-        "",
-        "Runtime",
-        `- cwd: ${process.cwd()}`,
-        `- async runner: ${deps.runAsync ? "available (child pi processes)" : "unavailable"}`,
-        "",
-        "Filesystem",
-        `- temp root: ${TEMP_ROOT_DIR}${existsSync(TEMP_ROOT_DIR) ? "" : " (created on first run)"}`,
-        `- async runs: ${ASYNC_DIR}`,
-        `- results: ${RESULTS_DIR}`,
-        "",
-        "Discovery",
-        `- known agent types: ${deps.manager.getKnownTypes().length}`,
-        ...deps.manager.getKnownTypes().map((type) => {
-          const agent = deps.manager.getAgentConfig(type);
-          const enabled = deps.manager.isTypeEnabled(type);
-          return `  - ${type} [${agent?.source ?? "config"}]${enabled ? "" : " [disabled]"}${agent?.aliases?.length ? ` (aliases: ${agent.aliases.join(", ")})` : ""}`;
-        }),
-        "",
-        "Budgets",
-        `- run timeout default: ${deps.config.timeoutMs ?? "30min (default)"}`,
-        `- tool timeout: ${deps.config.toolTimeoutMs ?? "env/known-fast defaults"}`,
-        `- spawn caps: run=${deps.config.maxSubagentSpawnsPerRun ?? 64}, session=${deps.config.maxSubagentSpawnsPerSession ?? "unlimited"}, active-async=${deps.config.maxActiveAsyncRunsPerSession ?? "unlimited"}`,
-        `- depth cap: ${resolveMaxSubagentDepth(undefined, deps.config, deps.env ?? process.env)}`,
-        "",
-        "Concurrency",
-        `- maxConcurrent: ${deps.config.maxConcurrent}`,
-        `- active in-process: ${deps.manager.listAgents().filter((a) => a.status === "running" || a.status === "queued").length}`,
-        `- retained children: ${listRetainedChildren(deps.retainedDir ?? ASYNC_DIR).length}`,
-      ];
-      return textResult(lines.join("\n"));
-    }
-
-    case "guide": {
-      const topic = (args.topic as string | undefined) ?? "overview";
-      return textResult(buildGuideText(topic));
-    }
-
-    case "mission.create": {
-      const location = resolveMissionStoreLocation({
-        projectRoot: deps.projectRoot ?? process.cwd(),
-        config: deps.missionConfig,
-      });
-      const missionInput = (args.mission ?? {}) as Record<string, unknown>;
-      const title = (missionInput.title ?? args.name) as string | undefined;
-      if (!title || typeof title !== "string" || !title.trim()) {
-        return textResult("action 'mission.create' requires mission.title (or name).", { status: "error" });
-      }
-      const objective = (missionInput.objective as string | undefined) ?? `${title}`;
-      try {
-        const record = createMission(location, {
-          title: title.trim(),
-          objective: objective.trim(),
-          ...(missionInput.goal === true ? { goal: true } : {}),
-          ...(missionInput.budget ? { budget: missionInput.budget as { tokens: number } } : {}),
-          ...(typeof missionInput.labels === "object" ? { labels: missionInput.labels as string[] } : {}),
-        });
-        return textResult(
-          `Mission created: ${record.id}\nTitle: ${record.title}\nStatus: ${record.status}\nAttach runs with missionId: ${record.id}`,
-          { status: "completed", missionId: record.id },
-        );
-      } catch (error) {
-        return textResult(`mission.create failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
-      }
-    }
-
-    case "mission.list": {
-      const location = resolveMissionStoreLocation({
-        projectRoot: deps.projectRoot ?? process.cwd(),
-        config: deps.missionConfig,
-      });
-      const { records, warnings } = listMissions(location);
-      if (records.length === 0) return textResult("No missions for this project.");
-      const lines = records.map((r) => `- ${r.id} [${r.status}] ${r.title}${r.summary ? ` — ${r.summary.slice(0, 80)}` : ""}`);
-      return textResult(
-        [`Missions (${records.length}):`, ...lines, ...(warnings.length ? ["", ...warnings] : [])].join("\n"),
-      );
-    }
-
-    case "mission.show":
-    case "mission.update":
-    case "mission.resolve-decision":
-    case "mission.attach-run":
-    case "mission.close": {
-      const missionId = args.missionId as string | undefined;
-      if (!missionId) return textResult(`action '${action}' requires missionId.`, { status: "error" });
-      const location = resolveMissionStoreLocation({
-        projectRoot: deps.projectRoot ?? process.cwd(),
-        config: deps.missionConfig,
-      });
-      try {
-        if (action === "mission.show") {
-          const record = readMission(location, missionId);
-          return textResult(
-            [
-              `Mission ${record.id} [${record.status}]`,
-              `Title: ${record.title}`,
-              `Objective: ${record.objective}`,
-              ...(record.goal ? [`Goal: ${record.goal.status}${record.budget ? ` (${record.usage?.tokens ?? 0}/${record.budget.tokens} tokens)` : ""}`] : []),
-              `Runs: ${record.runs.length} | Decisions: ${record.decisions.filter((d) => d.status === "open").length} open / ${record.decisions.length} total`,
-              ...(record.summary ? [`Summary: ${record.summary}`] : []),
-              ...(record.runs.length ? ["", "Runs:", ...record.runs.map((r) => `- ${r.runId}${r.agent ? ` (${r.agent})` : ""} ${r.status ?? ""}`)] : []),
-            ].join("\n"),
-          );
-        }
-        if (action === "mission.close") {
-          const summary = args.summary as string | undefined;
-          const status: MissionStatus = (args.missionStatus as MissionStatus | undefined) ?? (summary ? "completed" : "cancelled");
-          const record = updateMission(location, missionId, { status, ...(summary ? { summary } : {}) });
-          return textResult(`Mission ${record.id} closed as ${record.status}.`, { status: "completed", missionId: record.id });
-        }
-        if (action === "mission.attach-run") {
-          const runId = (args.runId ?? args.id) as string | undefined;
-          if (!runId) return textResult("mission.attach-run requires runId (or id).", { status: "error" });
-          const record = updateMission(location, missionId, {
-            addRun: { runId, ...(typeof args.missionStatus === "string" ? { status: args.missionStatus } : {}) },
-          });
-          return textResult(`Run ${runId} attached to mission ${record.id}.`, { status: "completed", missionId: record.id });
-        }
-        if (action === "mission.resolve-decision") {
-          const decisionId = args.id as string | undefined;
-          const resolution = args.message as string | undefined;
-          if (!decisionId || !resolution) {
-            return textResult("mission.resolve-decision requires id (decision id) and message (resolution).", { status: "error" });
-          }
-          const record = updateMission(location, missionId, { resolveDecision: { id: decisionId, resolution } });
-          return textResult(`Decision ${decisionId} resolved on mission ${record.id}.`, { status: "completed" });
-        }
-        // mission.update: generic field updates
-        const record = updateMission(location, missionId, {
-          ...(typeof args.summary === "string" ? { summary: args.summary } : {}),
-          ...(typeof args.missionStatus === "string" ? { status: args.missionStatus as MissionStatus } : {}),
-        });
-        return textResult(`Mission ${record.id} updated.`, { status: "completed", missionId: record.id });
-      } catch (error) {
-        if (error instanceof MissionNotFoundError) return textResult(error.message, { status: "error" });
-        return textResult(`${action} failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
-      }
-    }
-
-    case "schedule.create":
-    case "schedule.list":
-    case "schedule.show":
-    case "schedule.history":
-    case "schedule.pause":
-    case "schedule.resume":
-    case "schedule.run":
-    case "schedule.run-due":
-    case "schedule.delete": {
-      if (!deps.runAsync) {
-        return textResult("Schedule actions require the background process runner, which is unavailable in this host.", { status: "error" });
-      }
-      const manager = new ScheduledRunManager(deps.projectRoot ?? process.cwd(), {
-        storeRoot: deps.config.scheduledRuns?.storeRoot,
-        maxPending: deps.config.scheduledRuns?.maxPending,
-        launch: async (record) => {
-          const result = await deps.runAsync!({
-            agentName: record.agent,
-            task: record.task,
-            description: `schedule: ${record.name}`,
-            context: "fresh",
-            timeoutMs: record.timeoutMs,
-          });
-          return result.runId;
-        },
-      });
-
-      try {
-        switch (action) {
-          case "schedule.create": {
-            const record = manager.create({
-              name: (args.name as string | undefined) ?? `schedule-${Date.now().toString(36)}`,
-              agent: (args.agent ?? args.type) as string,
-              task: (args.task ?? args.prompt) as string,
-              at: args.at as string | undefined,
-              every: args.every as string | undefined,
-              catchUp: args.catchUp as "none" | "latest" | undefined,
-              timeoutMs: args.timeoutMs as number | undefined,
-            });
-            const next = record.trigger.kind === "once"
-              ? new Date(record.trigger.atMs).toISOString()
-              : record.trigger.nextRunAt;
-            return textResult(
-              `Schedule created: ${record.id}\nName: ${record.name}\nAgent: ${record.agent}\nTrigger: ${record.trigger.kind === "once" ? `once at ${next}` : `every ${record.trigger.every}`}\nNext run: ${next}`,
-              { status: "completed", scheduleId: record.id },
-            );
-          }
-          case "schedule.list": {
-            const all = manager.list();
-            if (all.length === 0) return textResult("No schedules for this project.");
-            return textResult(
-              [
-                `Schedules (${all.length}):`,
-                ...all.map((r) => {
-                  const next = r.trigger.kind === "once" ? r.trigger.atMs : r.trigger.nextRunAt;
-                  return `- ${r.id} "${r.name}" [${r.paused ? "paused" : "active"}] ${r.trigger.kind} → ${r.agent}: ${r.trigger.kind === "once" ? new Date(next).toISOString() : `every ${r.trigger.every}`}`;
-                }),
-              ].join("\n"),
-            );
-          }
-          case "schedule.show": {
-            const id = args.id as string | undefined;
-            if (!id) return textResult("schedule.show requires id.", { status: "error" });
-            const record = manager.show(id);
-            if (!record) return textResult(`No schedule matches "${id}".`, { status: "error" });
-            const history = manager.readHistory(id);
-            return textResult(
-              [
-                `Schedule ${record.id} "${record.name}" [${record.paused ? "paused" : "active"}]`,
-                `Agent: ${record.agent}`,
-                `Task: ${record.task.slice(0, 200)}`,
-                `Trigger: ${record.trigger.kind === "once" ? `once at ${record.trigger.at}` : `every ${record.trigger.every}`}`,
-                `Overlap: ${record.overlap} | catchUp: ${record.catchUp}`,
-                `Runs: ${history.length}`,
-                ...history.slice(-5).map((r) => `- ${r.id} ${r.state}${r.error ? ` (${r.error})` : ""}`),
-              ].join("\n"),
-            );
-          }
-          case "schedule.history": {
-            const id = args.id as string | undefined;
-            if (!id) return textResult("schedule.history requires id.", { status: "error" });
-            const history = manager.readHistory(id);
-            if (history.length === 0) return textResult("No runs recorded for this schedule.");
-            return textResult(
-              ["Schedule runs (newest last):", ...history.map((r) => `- ${r.id} ${r.state} ${r.plannedAt}${r.error ? ` (${r.error})` : ""}`)].join("\n"),
-            );
-          }
-          case "schedule.pause":
-          case "schedule.resume": {
-            const id = args.id as string | undefined;
-            if (!id) return textResult(`${action} requires id.`, { status: "error" });
-            const record = manager.setPaused(id, action === "schedule.pause");
-            return textResult(`Schedule ${record.id} "${record.name}" ${record.paused ? "paused" : "resumed"}.`);
-          }
-          case "schedule.run": {
-            const id = args.id as string | undefined;
-            if (!id) return textResult("schedule.run requires id.", { status: "error" });
-            const run = await manager.runNow(id);
-            return textResult(
-              run.state === "completed"
-                ? `Schedule ran: async run ${run.asyncRunId}`
-                : `Schedule run ${run.state}${run.error ? `: ${run.error}` : ""}`,
-              { status: run.state === "completed" ? "completed" : "error" },
-            );
-          }
-          case "schedule.run-due": {
-            const runs = await manager.runDue();
-            return textResult(`${runs.length} due schedule(s) executed.`);
-          }
-          case "schedule.delete": {
-            const id = args.id as string | undefined;
-            if (!id) return textResult("schedule.delete requires id.", { status: "error" });
-            const removed = manager.delete(id);
-            return textResult(removed ? `Schedule ${id} deleted.` : `No schedule matches "${id}".`, { status: removed ? "completed" : "error" });
-          }
-          default:
-            return textResult(`Unknown schedule action.`, { status: "error" });
-        }
-      } catch (error) {
-        return textResult(`${action} failed: ${error instanceof Error ? error.message : String(error)}`, { status: "error" });
-      }
-    }
-
-    default:
-      // Actions that belong to later phases report their status clearly.
-      return textResult(
-        `action "${action}" is recognized but not yet implemented in this build (planned phase).`,
-        { status: "error" },
-      );
-  }
-}
-
-// ============================================================================
-// workflowScript execution (foreground)
-// ============================================================================
-
-async function handleWorkflowScript(
-  deps: HandlerDeps,
-  ctx: ExtensionContext,
-  script: string,
-  args: Record<string, unknown>,
-  signal: AbortSignal | undefined,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
-  const asyncRequested = (args.async as boolean | undefined) ?? deps.config.asyncByDefault ?? true;
-  if (asyncRequested) {
-    return handleAsyncWorkflowScript(deps, ctx, script, args, signal);
-  }
-
-  // Validate call-level budgets up front (reference behavior).
-  if (args.turnBudget !== undefined) {
-    const { error } = resolveTurnBudgetConfig(args.turnBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-  if (args.toolBudget !== undefined) {
-    const { error } = validateToolBudgetConfig(args.toolBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-  if (args.usageBudget !== undefined) {
-    const { error } = validateUsageBudgetConfig(args.usageBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-
-  // Spawn budget: one fanout budget per top-level workflow run.
-  const perRunCap = deps.config.maxSubagentSpawnsPerRun ?? 64;
-  const budget = createRunFanoutBudget(`workflow-${Date.now()}`, perRunCap);
-
-  const sessionAccounting = deps.spawnAccounting;
-  const sessionCap = sessionAccounting?.cap();
-
-  const admit = (calls: Array<{ key: string; params: Record<string, unknown> }>): void => {
-    if (calls.length === 0) return;
-    // Per-run budget: atomic group admission.
-    claimRunFanoutBatch(budget, calls.map((call) => call.key));
-    // Session budget: cumulative.
-    if (sessionCap !== undefined && sessionAccounting) {
-      const used = sessionAccounting.used();
-      if (used + calls.length > sessionCap) {
-        throw new Error(
-          `Session spawn budget exhausted: ${used}/${sessionCap} used, ${calls.length} requested. ` +
-            `Use spawn_helper ({ action: "grant-spawn-budget", additional: N }) from the interactive parent to extend.`,
-        );
-      }
-      sessionAccounting.consume(calls.length);
-    }
-  };
-
-  const launch = async (
-    key: string,
-    params: Record<string, unknown>,
-    childSignal: AbortSignal,
-  ): Promise<WorkflowScriptChildResult> => {
-    const agentNameRaw = params.agent as string | undefined;
-    const task = params.task as string | undefined;
-    if (!agentNameRaw || !task) {
-      return { key, ok: false, output: "runs.run requires agent and task.", error: "missing agent/task", artifactPaths: [] };
-    }
-    const agentName = deps.manager.resolveAlias(agentNameRaw);
-    const agent = deps.manager.getAgentConfig(agentName);
-    if (!agent) {
-      return { key, ok: false, output: `Unknown agent "${agentNameRaw}".`, error: "unknown agent", artifactPaths: [] };
-    }
-    if (!deps.manager.isTypeEnabled(agentName)) {
-      return { key, ok: false, output: `Agent "${agentName}" is disabled.`, error: "disabled", artifactPaths: [] };
-    }
-
-    // Context policy (foreground = fresh only).
-    const contextMode = resolveContext(params.context as string | undefined, agent, deps.config);
-    if (contextMode === "fork") {
-      return {
-        key,
-        ok: false,
-        output: 'context "fork" requires background execution; foreground workflow children are fresh-context.',
-        error: "fork unavailable in foreground",
-        artifactPaths: [],
-      };
-    }
-
-    // Turn budget: wrap-up block in the child prompt.
-    let childTask = task;
-    const turnBudgetResult = resolveTurnBudgetConfig(params.turnBudget ?? args.turnBudget);
-    if (turnBudgetResult.turnBudget) {
-      childTask = appendTurnBudgetSystemPrompt(task, turnBudgetResult.turnBudget);
-    }
-
-    // Boundary instructions (plain or fanout child).
-    childTask = withChildBoundaryInstructions(childTask, agent);
-
-    const result = await deps.spawnForeground(ctx, agentName, childTask, {
-      description: (params.label as string | undefined) ?? key,
-      maxTurns: (params.maxTurns as number | undefined) ?? (turnBudgetResult.turnBudget?.maxTurns),
-      modelInput: (params.model as string | undefined) ?? agent.model,
-      thinkingLevel: agent.thinking,
-      signal: childSignal,
-    });
-
-    return {
-      key,
-      ok: result.ok,
-      output: result.output,
-      ...(result.error ? { error: result.error } : {}),
-      ...(agentName ? { agent: agentName } : {}),
-      artifactPaths: [],
-    };
-  };
-
-  const status = async (keyOrRunId: string): Promise<WorkflowScriptChildResult> => {
-    const record = deps.manager.getRecord(keyOrRunId);
-    if (record) {
-      return {
-        key: keyOrRunId,
-        ok: record.status === "completed",
-        output: record.result ?? record.status,
-        ...(record.error ? { error: record.error } : {}),
-        artifactPaths: [],
-      };
-    }
-    return { key: keyOrRunId, ok: true, output: "ok", artifactPaths: [] };
-  };
-
-  try {
-    const result = await runWorkflowScript({
-      script,
-      timeoutMs: args.timeoutMs as number | undefined,
-      signal,
-      admit,
-      launch,
-      status,
-    });
-
-    const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
-    const summary =
-      typeof result.value === "string"
-        ? result.value
-        : JSON.stringify(result.value, null, 2) ?? "null";
-    const truncated = truncateOutput(summary, maxOutput);
-    return textResult(truncated.text, {
-      status: "completed",
-      children: result.children.length,
-      fanout: formatRunFanoutBudget(getRunFanoutBudgetSnapshot(budget)),
-      truncated: truncated.truncated,
-    });
-  } catch (error) {
-    if (error instanceof Error && error.name === "WorkflowScriptError") {
-      const partial = (error as { partial?: { children?: unknown[] } }).partial;
-      return textResult(
-        `Workflow failed: ${error.message}`,
-        { status: "error", children: partial?.children?.length ?? 0 },
-      );
-    }
-    throw error;
-  }
-}
-
-// ============================================================================
-// Single-child launch (legacy + reference)
-// ============================================================================
-
-async function handleSingleChild(
-  deps: HandlerDeps,
-  ctx: ExtensionContext,
-  args: Record<string, unknown>,
-  signal: AbortSignal | undefined,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
-  const pre = preflight(deps, args);
-  if (!pre.ok) return textResult(pre.error, { status: "error" });
-
-  const { agent, agentName, prompt } = pre;
-  const asyncRequested =
-    (args.async as boolean | undefined) ??
-    (args.run_in_background as boolean | undefined) ??
-    agent.runInBackground ??
-    false;
-
-  // Context policy. EXPLICIT fork never silently downgrades (reference rule);
-  // implicit fork (agent/config default) falls back to fresh when the in-process
-  // path cannot fork (reference: implicit fork needs a persisted parent session,
-  // else fresh).
-  const explicitContext = args.context as string | undefined;
-  const contextMode = resolveContext(explicitContext, agent, deps.config);
-  if (contextMode === "fork" && (explicitContext === "fork" || deps.config.defaultSubagentContext === "fork")) {
-    if (!asyncRequested) {
-      return textResult(
-        'context: "fork" requires background execution (run_in_background: true); the in-process foreground path is fresh-context only.',
-        { status: "error" },
-      );
-    }
-    if (!deps.runAsync) {
-      return textResult(
-        'context: "fork" requires the background process runner, which is unavailable in this host. Re-run without context, or use context: "fresh".',
-        { status: "error" },
-      );
-    }
-  }
-
-  // Budgets: validate + decorate.
-  let childPrompt = prompt;
-  const turnBudgetResult = resolveTurnBudgetConfig(args.turnBudget);
-  if (turnBudgetResult.error) return textResult(turnBudgetResult.error, { status: "error" });
-  if (turnBudgetResult.turnBudget) {
-    childPrompt = appendTurnBudgetSystemPrompt(childPrompt, turnBudgetResult.turnBudget);
-  }
-  const toolBudgetResult = validateToolBudgetConfig(args.toolBudget);
-  if (toolBudgetResult.error) return textResult(toolBudgetResult.error, { status: "error" });
-  const usageBudgetResult = validateUsageBudgetConfig(args.usageBudget);
-  if (usageBudgetResult.error) return textResult(usageBudgetResult.error, { status: "error" });
-
-  // Acceptance gates (gate shorthand + acceptance object).
-  const acceptanceResolved = resolveEffectiveAcceptance(args);
-  if (!acceptanceResolved.ok) return textResult(acceptanceResolved.error, { status: "error" });
-
-  // Boundary instructions (unless the agent is a fanout child).
-  if (!isFanoutChild(agent)) {
-    childPrompt = withChildBoundaryInstructions(childPrompt, agent);
-  }
-
-  // Session spawn budget.
-  const sessionAccounting = deps.spawnAccounting;
-  if (sessionAccounting) {
-    const cap = sessionAccounting.cap();
-    if (cap !== undefined && sessionAccounting.used() >= cap) {
-      return textResult(
-        `Session spawn budget exhausted: ${sessionAccounting.used()}/${cap} used. ` +
-          `Use spawn_helper ({ action: "grant-spawn-budget", additional: N }) from the interactive parent to extend.`,
-        { status: "error" },
-      );
-    }
-    sessionAccounting.consume(1);
-  }
-
-  const description = (args.description as string | undefined) ?? `${agentName} task`;
-
-  if (asyncRequested) {
-    // Fork context requires the process runner; fresh background runs prefer
-    // it too when available (survives parent exit), else fall back in-process.
-    const wantsProcessRunner = contextMode === "fork" || deps.config.asyncByDefault === true;
-    if (deps.runAsync && (contextMode === "fork" || wantsProcessRunner)) {
-      const result = await deps.runAsync({
-        agentName,
-        task: childPrompt,
-        description,
-        model: (args.model as string | undefined) ?? agent.model,
-        thinking: (args.thinking as string | undefined) ?? (typeof agent.thinking === "string" ? agent.thinking : undefined),
-        context: contextMode,
-        timeoutMs: (args.timeoutMs as number | undefined) ?? agent.timeoutMs,
-        maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
-      });
-      return textResult(
-        `Agent started in background (process mode).\nRun ID: ${result.runId}\nType: ${agentName}\nDescription: ${description}\n\nYou will be notified when this agent completes.\nUse get_helper_result with the run ID to retrieve results.`,
-        { status: "background", runId: result.runId, agentId: result.runId },
-      );
-    }
-    const id = deps.spawnBackground(ctx, agentName, childPrompt, {
-      description,
-      maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
-      modelInput: (args.model as string | undefined) ?? agent.model,
-      thinkingLevel: args.thinking ?? agent.thinking,
-    });
-    return textResult(
-      `Agent started in background.\nID: ${id}\nType: ${agentName}\nDescription: ${description}\n\nYou will be notified when this agent completes.\nUse get_helper_result to retrieve full results.`,
-      { status: "background", agentId: id },
-    );
-  }
-
-  const result = await deps.spawnForeground(ctx, agentName, childPrompt, {
-    description,
-    maxTurns: (args.max_turns as number | undefined) ?? (args.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
-    modelInput: (args.model as string | undefined) ?? agent.model,
-    thinkingLevel: args.thinking ?? agent.thinking,
-    signal,
-  });
-
-  if (!result.ok) {
-    return textResult(`Agent failed: ${result.error ?? result.output}`, {
-      status: "error",
-      error: result.error,
-      toolUses: result.toolUses,
-      durationMs: result.durationMs,
-    });
-  }
-
-  // Acceptance gate evaluation (host-side verify commands + report checks).
-  let finalOutput = result.output;
-  let ledgerDetails: unknown;
-  if (acceptanceResolved.acceptance) {
-    const evaluated = await evaluateRunAcceptance(acceptanceResolved.acceptance, result.output, process.cwd());
-    finalOutput = evaluated.output;
-    ledgerDetails = evaluated.ledger;
-    if (evaluated.ledger?.status === "rejected") {
-      return textResult(
-        `Agent completed but acceptance rejected:\n${evaluated.ledger.failureMessage}\n\nOutput:\n${finalOutput.slice(0, 2000)}`,
-        { status: "error", acceptance: evaluated.ledger.status, failureMessage: evaluated.ledger.failureMessage },
-      );
-    }
-  }
-
-  // Output truncation with maxOutput config (reference default 200KB/5000 lines).
-  const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
-  const truncated = truncateOutput(finalOutput, maxOutput);
-
-  return textResult(
-    `Agent completed in ${(result.durationMs / 1000).toFixed(1)}s (${result.toolUses} tool uses).\n\n${truncated.text}`,
-    {
-      status: "completed",
-      toolUses: result.toolUses,
-      durationMs: result.durationMs,
-      ...(ledgerDetails ? { acceptance: (ledgerDetails as { status: string }).status } : {}),
-      truncated: truncated.truncated,
-      originalBytes: truncated.originalBytes,
-    },
-  );
-}
-
-
-// ============================================================================
-// Async workflowScript (process-backed children)
-// ============================================================================
-
-/**
- * Run a workflow with every child launched through the process runner
- * (child pi processes). The workflow runtime is identical; only the launch
- * transport differs. The tool call blocks until the workflow settles — the
- * parent gets the full result. (Fully detached async workflows with live
- * status polling land with the Phase 4 fleet work.)
- */
-async function handleAsyncWorkflowScript(
-  deps: HandlerDeps,
-  ctx: ExtensionContext,
-  script: string,
-  args: Record<string, unknown>,
-  signal: AbortSignal | undefined,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }> {
-  if (!deps.runAsync) {
-    return textResult(
-      "Async workflowScript requires the background process runner, which is unavailable in this host. " +
-        "Re-run with async: false to execute the workflow in-process in the foreground.",
-      { status: "error" },
-    );
-  }
-
-  // Validate call-level budgets up front.
-  if (args.turnBudget !== undefined) {
-    const { error } = resolveTurnBudgetConfig(args.turnBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-  if (args.toolBudget !== undefined) {
-    const { error } = validateToolBudgetConfig(args.toolBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-  if (args.usageBudget !== undefined) {
-    const { error } = validateUsageBudgetConfig(args.usageBudget);
-    if (error) return textResult(error, { status: "error" });
-  }
-
-  const perRunCap = deps.config.maxSubagentSpawnsPerRun ?? 64;
-  const budget = createRunFanoutBudget(`workflow-async-${Date.now()}`, perRunCap);
-  const sessionAccounting = deps.spawnAccounting;
-  const sessionCap = sessionAccounting?.cap();
-
-  const admit = (calls: Array<{ key: string; params: Record<string, unknown> }>): void => {
-    if (calls.length === 0) return;
-    claimRunFanoutBatch(budget, calls.map((call) => call.key));
-    if (sessionCap !== undefined && sessionAccounting) {
-      const used = sessionAccounting.used();
-      if (used + calls.length > sessionCap) {
-        throw new Error(
-          `Session spawn budget exhausted: ${used}/${sessionCap} used, ${calls.length} requested.`,
-        );
-      }
-      sessionAccounting.consume(calls.length);
-    }
-  };
-
-  const launch = async (
-    key: string,
-    params: Record<string, unknown>,
-    childSignal: AbortSignal,
-  ): Promise<WorkflowScriptChildResult> => {
-    const agentNameRaw = params.agent as string | undefined;
-    const task = params.task as string | undefined;
-    if (!agentNameRaw || !task) {
-      return { key, ok: false, output: "runs.run requires agent and task.", error: "missing agent/task", artifactPaths: [] };
-    }
-    const agentName = deps.manager.resolveAlias(agentNameRaw);
-    const agent = deps.manager.getAgentConfig(agentName);
-    if (!agent) {
-      return { key, ok: false, output: `Unknown agent "${agentNameRaw}".`, error: "unknown agent", artifactPaths: [] };
-    }
-    if (!deps.manager.isTypeEnabled(agentName)) {
-      return { key, ok: false, output: `Agent "${agentName}" is disabled.`, error: "disabled", artifactPaths: [] };
-    }
-
-    // Context policy: fork children get branched sessions via the process runner.
-    const contextMode = resolveContext(params.context as string | undefined, agent, deps.config);
-
-    let childTask = task;
-    const turnBudgetResult = resolveTurnBudgetConfig(params.turnBudget ?? args.turnBudget);
-    if (turnBudgetResult.turnBudget) {
-      childTask = appendTurnBudgetSystemPrompt(task, turnBudgetResult.turnBudget);
-    }
-    childTask = withChildBoundaryInstructions(childTask, agent);
-
-    try {
-      const worktreeRequested =
-        (params.worktree as boolean | undefined) ??
-        (args.worktree as boolean | undefined) ??
-        (args.isolation === "worktree" ? true : undefined);
-      const result = await deps.runAsync!({
-        agentName,
-        task: childTask,
-        description: (params.label as string | undefined) ?? key,
-        model: (params.model as string | undefined) ?? agent.model,
-        thinking: typeof agent.thinking === "string" ? agent.thinking : undefined,
-        context: contextMode,
-        timeoutMs: (params.timeoutMs as number | undefined) ?? agent.timeoutMs,
-        maxTurns: (params.maxTurns as number | undefined) ?? turnBudgetResult.turnBudget?.maxTurns,
-        ...(worktreeRequested === true ? { worktree: true } : {}),
-      });
-      void childSignal; // process-level abort handled by the runner's controller
-      return {
-        key,
-        ok: result.status === "completed",
-        output: result.output ?? result.error ?? result.status,
-        ...(result.error ? { error: result.error } : {}),
-        agent: agentName,
-        ...(result.runId ? { runId: result.runId } : {}),
-        artifactPaths: [],
-      };
-    } catch (error) {
-      const text = error instanceof Error ? error.message : String(error);
-      return { key, ok: false, output: text, error: text, artifactPaths: [] };
-    }
-  };
-
-  const status = async (keyOrRunId: string): Promise<WorkflowScriptChildResult> => {
-    const record = deps.manager.getRecord(keyOrRunId);
-    if (record) {
-      return {
-        key: keyOrRunId,
-        ok: record.status === "completed",
-        output: record.result ?? record.status,
-        ...(record.error ? { error: record.error } : {}),
-        artifactPaths: [],
-      };
-    }
-    return { key: keyOrRunId, ok: true, output: "ok", artifactPaths: [] };
-  };
-
-  try {
-    const result = await runWorkflowScript({
-      script,
-      timeoutMs: args.timeoutMs as number | undefined,
-      signal,
-      admit,
-      launch,
-      status,
-    });
-
-    const maxOutput = resolveMaxOutput(args.maxOutput as never, deps.config);
-    const summary =
-      typeof result.value === "string"
-        ? result.value
-        : JSON.stringify(result.value, null, 2) ?? "null";
-    const truncated = truncateOutput(summary, maxOutput);
-    return textResult(truncated.text, {
-      status: "completed",
-      mode: "async-workflow",
-      children: result.children.length,
-      fanout: formatRunFanoutBudget(getRunFanoutBudgetSnapshot(budget)),
-      truncated: truncated.truncated,
-    });
-  } catch (error) {
-    if (error instanceof Error && error.name === "WorkflowScriptError") {
-      const partial = (error as { partial?: { children?: unknown[] } }).partial;
-      return textResult(
-        `Workflow failed: ${error.message}`,
-        { status: "error", mode: "async-workflow", children: partial?.children?.length ?? 0 },
-      );
-    }
-    throw error;
-  }
-}