@bermudi/pi-delegate 0.1.0

package/dispatch.ts

@@ -0,0 +1,362 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import {
+  ticketRegistry,
+  generateTicketId,
+  deliverTicketResults,
+  sweepTickets,
+  resolveFinalTicketStatus,
+  syncTicketBusyIndex,
+  notifyWaiters,
+} from "./tickets.ts";
+import { getConcurrencyLimit, getMaxAsyncTickets } from "./config.ts";
+import { getModelKey, mapConcurrentByModel } from "./concurrency.ts";
+import { sumUsage } from "./usage.ts";
+import { runResolvedTask, updateProgressFromRun } from "./lifecycle.ts";
+import { fmtDuration, formatCompletedTask, trunc } from "./format.ts";
+import { validateDelegateOperation } from "./schema.ts";
+import { validateTasks, resolveTasks } from "./task-resolution.ts";
+import type {
+  AgentConfig,
+  AsyncTicket,
+  DelegateArguments,
+  DelegateDetails,
+  DelegateToolCtx,
+  DelegateToolResult,
+  ResolvedTask,
+  TaskDef,
+  TaskProgress,
+  TaskResult,
+  TaskRunEnv,
+} from "./types.ts";
+
+/** Return the structured result for an invalid top-level operation, or null when
+ * the call may proceed to a ticket control/help/dispatch path. */
+export function validateDelegateOperationResult(
+  params: DelegateArguments,
+  parentModelId: string | undefined,
+): DelegateToolResult | null {
+  const operationError = validateDelegateOperation(params);
+  if (!operationError) return null;
+
+  return {
+    content: [
+      { type: "text", text: `Invalid delegate call: ${operationError}` },
+    ],
+    details: {
+      tasks: params.tasks ?? [],
+      results: [],
+      progress: [],
+      parentModel: parentModelId,
+    },
+  };
+}
+
+/** Build the initial per-task progress rows from resolved tasks. */
+export function initProgress(resolved: ResolvedTask[]): TaskProgress[] {
+  return resolved.map((t, i) => ({
+    index: i,
+    agent: t.agentName,
+    task: trunc(t.prompt || t.action || "", 50),
+    status: "pending" as const,
+    durationMs: 0,
+    tokens: 0,
+    toolUses: 0,
+    activities: [],
+    model: t.model?.id,
+    warnings: t.warnings.length ? [...t.warnings] : undefined,
+  }));
+}
+
+/** Construct the `fire()` updater that pushes a "Running N subagents" progress
+ *  frame to the parent TUI. Used for the initial dispatch frame and (in sync
+ *  mode) after every progress/status mutation. */
+export function makeFireUpdater(
+  onUpdate: AgentToolUpdateCallback<DelegateDetails> | undefined,
+  tasks: TaskDef[],
+  progress: TaskProgress[],
+  resolved: ResolvedTask[],
+  parentModelId: string | undefined,
+): () => void {
+  return () =>
+    onUpdate?.({
+      content: [
+        {
+          type: "text",
+          text: `Running ${resolved.length} subagent${resolved.length > 1 ? "s" : ""}…`,
+        },
+      ],
+      details: {
+        tasks,
+        results: [],
+        progress: [...progress],
+        parentModel: parentModelId,
+      },
+    });
+}
+
+/** Inputs needed by the async (fire-and-forget) dispatch path. */
+export interface AsyncDispatchInput {
+  pi: ExtensionAPI;
+  ctx: DelegateToolCtx;
+  tasks: TaskDef[];
+  resolved: ResolvedTask[];
+  progress: TaskProgress[];
+  parentModelId: string | undefined;
+}
+
+/** Inputs needed by the sync (blocking) dispatch path. */
+export interface SyncDispatchInput {
+  ctx: DelegateToolCtx;
+  tasks: TaskDef[];
+  resolved: ResolvedTask[];
+  progress: TaskProgress[];
+  parentModelId: string | undefined;
+  signal: AbortSignal | undefined;
+  fire: () => void;
+}
+
+/** Inputs for the normal task-validation, resolution, and dispatch path. */
+export interface DelegateDispatchInput {
+  pi: ExtensionAPI;
+  params: DelegateArguments;
+  ctx: DelegateToolCtx;
+  agents: Map<string, AgentConfig>;
+  parentModelId: string | undefined;
+  signal: AbortSignal | undefined;
+  onUpdate: AgentToolUpdateCallback<DelegateDetails> | undefined;
+}
+
+/** Validate, resolve, and dispatch a non-short-circuit delegate operation. */
+export async function dispatchDelegate(
+  input: DelegateDispatchInput,
+): Promise<DelegateToolResult> {
+  const { pi, params, ctx, agents, parentModelId, signal, onUpdate } = input;
+  const tasks = params.tasks ?? [];
+
+  const validationError = validateTasks(tasks, agents, parentModelId);
+  if (validationError) return validationError;
+
+  const resolved = resolveTasks(tasks, ctx, agents);
+  const progress = initProgress(resolved);
+  const fire = makeFireUpdater(
+    onUpdate,
+    tasks,
+    progress,
+    resolved,
+    parentModelId,
+  );
+  fire();
+
+  if (params.async) {
+    return dispatchAsync({
+      pi,
+      ctx,
+      tasks,
+      resolved,
+      progress,
+      parentModelId,
+    });
+  }
+
+  return dispatchSync({
+    ctx,
+    tasks,
+    resolved,
+    progress,
+    parentModelId,
+    signal,
+    fire,
+  });
+}
+
+/** Fire-and-forget background execution. Registers an `AsyncTicket`, kicks off
+ *  the concurrent run, and returns the ticket acknowledgment immediately.
+ *  Results are delivered via `deliverTicketResults` when all tasks settle. */
+export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
+  const { pi, ctx, tasks, resolved, progress, parentModelId } = input;
+
+  sweepTickets();
+  const runningCount = [...ticketRegistry.values()].filter(
+    (t) => t.status === "running" || t.status === "cancelling",
+  ).length;
+  if (runningCount >= getMaxAsyncTickets()) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Too many async tickets running or cancelling (${runningCount}/${getMaxAsyncTickets()}). Poll existing tickets or cancel one first.`,
+        },
+      ],
+      details: { tasks, results: [], progress: [], parentModel: parentModelId },
+    };
+  }
+
+  const ticketId = generateTicketId();
+  const controller = new AbortController();
+  const ticket: AsyncTicket = {
+    id: ticketId,
+    created: Date.now(),
+    tasks,
+    resolved,
+    status: "running",
+    results: new Array(resolved.length),
+    progress: [...progress],
+    controller,
+    parentModelId,
+  };
+  ticketRegistry.set(ticketId, ticket);
+
+  // Capture values for the closure — do NOT use `signal` from execute()
+  // The parent turn's signal dies when execute() returns.
+  const ticketSignal = controller.signal;
+  const modelRegistry = ctx.modelRegistry;
+
+  const asyncEnv: TaskRunEnv = {
+    signal: ticketSignal,
+    modelRegistry,
+    parentSessionManager: ctx.sessionManager,
+    ticketId,
+    delegateStartedAt: ticket.created,
+    onProgress: (p, u) => {
+      updateProgressFromRun(p, u);
+      notifyWaiters(ticket);
+    },
+    onStatusChange: () => {
+      notifyWaiters(ticket);
+    },
+  };
+
+  // Fire and forget — runs on the event loop.
+  // Worker must store the TaskResult back into ticket.results, since
+  // formatCompletedTicket/handlePoll read from there. Without the write,
+  // completed async tasks would be reported as PENDING.
+  mapConcurrentByModel(
+    resolved,
+    (t) => getModelKey(t.model),
+    getConcurrencyLimit,
+    async (t, i) => {
+      const result = await runResolvedTask(asyncEnv, t, ticket.progress[i]!, i);
+      ticket.results[i] = result;
+      return result;
+    },
+    ticketSignal,
+  )
+    .then(() => {
+      // All tasks settled — determine final ticket status.
+      // Use progress (set by runResolvedTask) for settled-ness so the
+      // status reflects work completion, not just result-array density.
+      // A partial ticket (not all settled, e.g. aborted mid-flight) must
+      // NOT be marked "done" — that would mask incomplete work as
+      // complete. resolveFinalTicketStatus returns "failed" for that
+      // case and for any case with a failed task.
+      if (ticket.status === "running") {
+        ticket.status = resolveFinalTicketStatus(ticket);
+        ticket.completedAt = Date.now();
+        syncTicketBusyIndex(ticket);
+      } else if (ticket.status === "cancelling") {
+        // Cancellation was requested while tasks were still settling. The
+        // per-task results record what actually happened; the ticket state
+        // reports that the batch was aborted by the caller.
+        ticket.status = "cancelled";
+        ticket.completedAt = Date.now();
+        syncTicketBusyIndex(ticket);
+      }
+      deliverTicketResults(pi, ticket);
+    })
+    .catch((err) => {
+      // Defense-in-depth — should not happen if individual tasks catch properly
+      if (ticket.status === "cancelling") {
+        ticket.status = "cancelled";
+      } else if (ticket.status === "running") {
+        ticket.status = "failed";
+      }
+      ticket.error = err instanceof Error ? err.message : String(err);
+      ticket.completedAt = Date.now();
+      syncTicketBusyIndex(ticket);
+      deliverTicketResults(pi, ticket);
+    });
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: [
+          `Async ticket: ${ticketId}`,
+          `${resolved.length} task(s) dispatched · ${runningCount + 1}/${getMaxAsyncTickets()} async slots in use`,
+          "",
+          "Completed task results are available via poll. Final results delivered automatically when all tasks complete.",
+          `Check progress: delegate({ action: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
+          `Cancel if needed: delegate({ action: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
+        ].join("\n"),
+      },
+    ],
+    details: {
+      tasks,
+      results: [],
+      progress: [...progress],
+      parentModel: parentModelId,
+      ticketId,
+      status: ticket.status,
+    },
+  };
+}
+
+/** Synchronous concurrent execution — awaits all tasks and formats the
+ * combined LLM-facing result. Pooled sessions remain live until closed. */
+export async function dispatchSync(
+  input: SyncDispatchInput,
+): Promise<DelegateToolResult> {
+  const { ctx, tasks, resolved, progress, parentModelId, signal, fire } = input;
+
+  const startedAt = Date.now();
+  const syncEnv: TaskRunEnv = {
+    signal,
+    modelRegistry: ctx.modelRegistry,
+    parentSessionManager: ctx.sessionManager,
+    ticketId: undefined,
+    delegateStartedAt: startedAt,
+    onProgress: (p, u) => {
+      updateProgressFromRun(p, u);
+      fire();
+    },
+    onStatusChange: () => fire(),
+  };
+
+  const results = await mapConcurrentByModel(
+    resolved,
+    (t) => getModelKey(t.model),
+    getConcurrencyLimit,
+    async (t, i) => runResolvedTask(syncEnv, t, progress[i]!, i),
+    signal,
+  );
+
+  // ── Format for LLM ────────────────────────────────────────────
+  const finalResults: TaskResult[] = results;
+  const elapsedTotal = Date.now() - startedAt;
+
+  const parts: string[] = [];
+  const succeeded = finalResults.filter((r) => !r.error).length;
+  parts.push(
+    `${succeeded}/${finalResults.length} tasks completed successfully · ${fmtDuration(elapsedTotal)} wall time\n`,
+  );
+  for (let i = 0; i < finalResults.length; i++) {
+    const r = finalResults[i]!;
+    const t = resolved[i]!;
+    parts.push(...formatCompletedTask(t, r));
+  }
+
+  return {
+    content: [{ type: "text", text: parts.join("\n\n") }],
+    details: {
+      tasks,
+      results: finalResults,
+      progress,
+      parentModel: parentModelId,
+    },
+    // Aggregate subagent spend so Pi folds it into the parent's
+    // session/footer totals. Sync dispatch only — async results arrive via a
+    // follow-up message that has no usage slot (see DelegateToolResult).
+    usage: sumUsage(finalResults.map((r) => r.usage)),
+  };
+}

package/extension.ts

@@ -0,0 +1,126 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  handleCancel,
+  handlePoll,
+  handleWait,
+  cancelTicketForShutdown,
+  ticketRegistry,
+} from "./tickets.ts";
+import { discoverAgents } from "./agents.ts";
+import { getSubagentManualMarkdown } from "./manual.ts";
+import {
+  delegateArgumentsSchema,
+  normalizeDelegateArguments,
+} from "./schema.ts";
+import {
+  dispatchDelegate,
+  validateDelegateOperationResult,
+} from "./dispatch.ts";
+import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
+import { hostCompatError } from "./host-compat.ts";
+import { closeAllPooledAgents } from "./pool.ts";
+import type { DelegateArguments } from "./types.ts";
+
+/** Register the delegate tool and clean up its parent-session resources. */
+export default function delegateExtension(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "delegate",
+    label: "Delegate to Subagents",
+    description:
+      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async returns a ticket.",
+    parameters: delegateArgumentsSchema,
+    // Runs before schema validation — recovers stringified `tasks` arrays
+    // (a common model mistake that would otherwise be rejected upstream).
+    prepareArguments: normalizeDelegateArguments,
+
+    async execute(_id, params: DelegateArguments, signal, onUpdate, ctx) {
+      // Guard against pi dropping/renaming a symbol this extension imports
+      // before any operation-specific validation or early return.
+      const compatError = hostCompatError();
+      if (compatError) return compatError;
+
+      const parentModelId = ctx.model?.id;
+      const tasks = params.tasks ?? [];
+
+      const operationResult = validateDelegateOperationResult(
+        params,
+        parentModelId,
+      );
+      if (operationResult) return operationResult;
+
+      // ── Poll action ───────────────────────────────────────────────────
+      if (params.action === "poll") {
+        return handlePoll(params, ctx);
+      }
+
+      // ── Cancel action ─────────────────────────────────────────────────
+      if (params.action === "cancel") {
+        return handleCancel(params);
+      }
+
+      // ── Wait action ────────────────────────────────────────────────────
+      if (params.action === "wait") {
+        return handleWait(params, signal, onUpdate, ctx);
+      }
+
+      // Agent discovery is intentionally parent-cwd-scoped: agent profiles are a
+      // session-level resource, not per-task. Per-task cwd governs settings,
+      // and AGENTS.md resolution (see resolveCwd below), but not which
+      // named agents exist. Changing this would let a task's throwaway cwd
+      // silently swap the agent roster.
+      const agents = discoverAgents(ctx.cwd);
+
+      // ── Help mode ─────────────────────────────────────────────────
+      if (!tasks.length) {
+        return {
+          content: [{ type: "text", text: getSubagentManualMarkdown(agents) }],
+          details: {
+            tasks: [],
+            results: [],
+            progress: [],
+            parentModel: parentModelId,
+          },
+        };
+      }
+
+      return dispatchDelegate({
+        pi,
+        params,
+        ctx,
+        agents,
+        parentModelId,
+        signal,
+        onUpdate,
+      });
+    },
+
+    renderCall: renderDelegateCall,
+    renderResult: renderDelegateResult,
+  });
+
+  // ── Session shutdown: abort tickets and dispose live pooled sessions ──
+  pi.on("session_shutdown", async () => {
+    for (const ticket of ticketRegistry.values()) {
+      cancelTicketForShutdown(ticket);
+    }
+    // Do NOT clear the ticket registry here — completed tickets are retained
+    // until their TTL cleanup. Pooled AgentSessions, however, own listeners
+    // and must be disposed before the parent session exits.
+    //
+    // closeAllPooledAgents attempts every session (Promise.allSettled) before
+    // aggregating failures into an AggregateError, so swallowing here does not
+    // abandon remaining cleanup. Catch and log so a wedged session's failure
+    // stays observable instead of becoming an unhandled rejection — pi.on is
+    // EventEmitter-style and does not surface handler rejections — and so
+    // shutdown completes even when one pooled session failed to abort/dispose.
+    try {
+      await closeAllPooledAgents();
+    } catch (error) {
+      const failures = error instanceof AggregateError ? error.errors : [error];
+      console.error(
+        "[delegate] pooled-session cleanup failed during shutdown:",
+        failures,
+      );
+    }
+  });
+}

package/file-tracking.ts

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import * as path from "node:path";
+import type { ToolActivity } from "./types.ts";
+
+/** Return absolute paths reported as changed by Git in the task cwd.
+ * Git failures degrade to an empty set because file tracking is observational. */
+export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
+  try {
+    const runGit = (args: string[]) =>
+      new Promise<string>((resolve, reject) => {
+        execFile("git", args, { cwd, timeout: 5000 }, (err, stdout) => {
+          if (err) reject(err);
+          else resolve(stdout);
+        });
+      });
+    const repoRoot = (await runGit(["rev-parse", "--show-toplevel"])).trim();
+    const result = await runGit([
+      "status",
+      "--porcelain=v1",
+      "--untracked-files=all",
+      "-z",
+    ]);
+    const files = new Set<string>();
+    const entries = result.split("\0");
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i]!;
+      if (entry.length < 4) continue;
+
+      const status = entry.slice(0, 2);
+      const rawPath = entry.slice(3);
+      const isRenameOrCopy = status.includes("R") || status.includes("C");
+      if (rawPath) files.add(path.resolve(repoRoot, rawPath));
+
+      // With -z, Git emits the destination first and the source second for
+      // rename/copy entries. Consume the source so it is not reported too.
+      if (isRenameOrCopy) i++;
+    }
+    return files;
+  } catch {
+    return new Set();
+  }
+}
+
+/** Extract file paths mutated by edit/write from the activity log. */
+export function extractTouchedFromActivities(
+  activities: ToolActivity[],
+  cwd: string,
+): string[] {
+  const files = new Set<string>();
+  for (const a of activities) {
+    if (a.name !== "edit" && a.name !== "write") continue;
+    const raw = a.args?.path ?? a.args?.file_path ?? a.args?.filePath;
+    if (typeof raw !== "string" || !raw) continue;
+    files.add(path.resolve(cwd, raw));
+  }
+  return [...files];
+}