@fradser/pi-agent-teams 0.8.2 → 0.9.0

package/src/index.ts

@@ -5,44 +5,60 @@
  * passive widget and console live in ui.ts.
  */
 
-import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, keyHint, ToolExecutionComponent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { buildTeamLeaderGuidance, TEAMMATE_SPAWN_GUIDANCE, WORKER_GUIDANCE } from "./guidance.ts";
+import { buildIdleLeaderGuidance, buildTeamLeaderGuidance, WORKER_GUIDANCE } from "./guidance.ts";
 import { clearSessionAgents } from "./agents.ts";
-import { formatSilenceDuration, initTeamMachine, markTeammateFinished, removeRuntimeDir, shutdownTeamMachine, teardownTeammates } from "./team-machine.ts";
+import { getConfirmedStopTime, initTeamMachine, markTeammateFinished, removeRuntimeDir, shutdownTeamMachine, syncLeaderContext, teardownTeammates } from "./team-machine.ts";
 import { cleanupExpiredStateDirs } from "./statefile.ts";
 import { livingTeammates, listTasks, resetState } from "./state.ts";
 import { ensureTeamWidget, refreshTeamUI, stopUiTimers } from "./ui.ts";
-import { refreshLeaderToolDisclosure, registerLeaderTools, registerTeamCommand } from "./tools.ts";
+import { registerLeaderTools, registerTeamCommand } from "./tools.ts";
 import { registerWorkerCapabilities, workerBinding } from "./worker.ts";
-import { agentColor, clearPiStatus, createStaticToolLifecycleMessageRenderer, eventToolLifecycle, formatAgentMessagePrefix, notifyPi, renderAgentMessageBand } from "@fradser/pi-kit";
-import { FollowUpQueue, groupReportsByTeammate, TEAMMATE_HARNESS_MESSAGE_TYPE, TEAMMATE_REPORT_MESSAGE_TYPE, type FollowUpReport } from "./follow-up-queue.ts";
-import { Box, Markdown, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { plainText } from "./tool-copy.ts";
+import { agentColor, bindLifecycleRenderers, clearPiStatus, createToolExecutionWrapper, eventToolLifecycle, formatAgentMessagePrefix, notifyPi, renderAgentMessageBand } from "@fradser/pi-kit";
+import { annotateReportDelivery, formatReports, groupReportsByTeammate, TEAMMATE_HARNESS_MESSAGE_TYPE, TEAMMATE_REPORT_MESSAGE_TYPE, type LeaderReport } from "./leader-reports.ts";
+import { Box, Markdown, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Geometry bound once: harness event rows share hint and wrapping. */
+const harnessRows = bindLifecycleRenderers({
+  fit: truncateToWidth,
+  visibleWidth,
+  wrapDetail: (line, width) => wrapTextWithAnsi(line, Math.max(1, width)),
+  expandHint: () => keyHint("app.tools.expand", "to expand"),
+});
 
 const STATE_DIR_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
 let leaderPi: ExtensionAPI | undefined;
 let leaderCtx: ExtensionContext | undefined;
-let followUpQueue: FollowUpQueue | undefined;
 
 export const TEAMMATE_FINISHED_ENTRY_TYPE = "agent-teams-teammate-finished";
-export const TEAMMATE_HEALTH_MESSAGE_TYPE = "agent-teams-health";
 
-function sendMainSessionFollowUp(report: FollowUpReport): void {
-  followUpQueue?.enqueue(report);
-}
-
-function extractHealthReport(details: unknown): FollowUpReport | undefined {
-  const report = details as FollowUpReport | undefined;
-  return report?.health?.state === "stalled" ? report : undefined;
+function sendLeaderReport(report: LeaderReport): void {
+  try {
+    leaderPi?.sendMessage({
+      customType: report.origin === "harness" || report.harnessEvent
+        ? TEAMMATE_HARNESS_MESSAGE_TYPE
+        : TEAMMATE_REPORT_MESSAGE_TYPE,
+      content: formatReports([report]),
+      display: true,
+      details: report,
+    }, { triggerTurn: true, deliverAs: "steer" });
+  } catch (error) {
+    if (leaderCtx) {
+      const detail = error instanceof Error ? error.message : String(error);
+      notifyPi(leaderCtx.ui, `Agent Teams report delivery failed: ${detail}. The report remains in /agent-teams.`, "warning");
+    }
+  }
 }
 
 export function hasActiveTeamState(): boolean {
   return livingTeammates().length > 0 || listTasks().length > 0;
 }
 
-function extractHarnessReport(details: unknown): FollowUpReport | undefined {
-  const report = details as FollowUpReport | undefined;
+function extractHarnessReport(details: unknown): LeaderReport | undefined {
+  const report = details as LeaderReport | undefined;
   return report?.origin === "harness" || report?.harnessEvent ? report : undefined;
 }
 
@@ -63,135 +79,137 @@ export default function (pi: ExtensionAPI) {
   }
 
   leaderPi = pi;
+  const deliveries = new WeakMap<object, LeaderReport[]>();
   pi.registerEntryRenderer(TEAMMATE_FINISHED_ENTRY_TYPE, (entry, _options, theme) => {
     const data = entry.data as { teammate?: string; agent?: string } | undefined;
     const name = data?.teammate ?? data?.agent ?? "teammate";
-    return new Text(theme.fg("success", `Teammate @${name} finished.`), 0, 0);
-  });
-  pi.registerMessageRenderer(TEAMMATE_HEALTH_MESSAGE_TYPE, (message, { expanded }, theme) => {
-    const healthReport = extractHealthReport(message.details);
-    const health = healthReport?.health;
-    if (!health || !healthReport) return new Text(String(message.content), 0, 0);
-    const subject = `@${healthReport.teammate} ${health.state} · silent ${formatSilenceDuration(health.silenceMs)}`;
-    return createStaticToolLifecycleMessageRenderer({
-      createSpec: () => eventToolLifecycle("agent", subject, {
-        details: healthReport.body.split("\n").filter((line) => line.trim()),
-      }),
-      expandHint: keyHint("app.tools.expand", "to expand"),
-      fit: truncateToWidth,
-      visibleWidth,
-    })(message, { expanded }, theme);
+    return new Text(theme.fg("success", `Assignment for @${name} finished.`), 0, 0);
   });
   pi.registerMessageRenderer(TEAMMATE_HARNESS_MESSAGE_TYPE, (message, { expanded }, theme) => {
     const report = extractHarnessReport(message.details);
     if (!report) return new Text(String(message.content), 0, 0);
     const event = report.harnessEvent;
-    return createStaticToolLifecycleMessageRenderer({
-      createSpec: () => eventToolLifecycle("agent", event?.subject ?? "Agent Teams event"),
-      expandHint: keyHint("app.tools.expand", "to expand"),
-      fit: truncateToWidth,
-      visibleWidth,
-    })(message, { expanded }, theme);
+    return harnessRows.message(
+      () => eventToolLifecycle("agent", plainText(event?.subject ?? "Agent Teams event")),
+      { hostComponent: ToolExecutionComponent, ui: leaderCtx?.ui, cwd: leaderCtx?.cwd },
+    )(message, { expanded }, theme);
   });
   pi.registerMessageRenderer(TEAMMATE_REPORT_MESSAGE_TYPE, (message, { expanded, outputPad }, theme) => {
-    const reports = extractReports(message.details);
-    const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
+    const reports = deliveries.get(message) ?? extractReports(message.details);
     if (reports.length === 0) {
+      const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
       box.addChild(new Markdown(String(message.content), 0, 0, getMarkdownTheme()));
       return box;
     }
-    if (!expanded) {
-      const groups = groupReportsByTeammate(reports);
-      return renderAgentMessageBand(
-        groups.map((group) => ({ direction: "from", teammate: group.teammate, count: group.reports.length })),
-        { theme, fit: truncateToWidth, expandHint: keyHint("app.tools.expand", "to expand") },
-      );
-    }
-    for (const [index, report] of reports.entries()) {
-      const teammate = report.teammate ?? report.agent ?? "teammate";
-      const prefix = theme.fg("customMessageLabel", theme.bold(formatAgentMessagePrefix("from")));
-      const name = theme.fg(agentColor(teammate), `@${teammate}`);
-      box.addChild(new Text(`${prefix}${name}`, 0, 0));
-      box.addChild(new Markdown(report.body, 0, 0, getMarkdownTheme(), {
-        color: (text) => theme.fg("customMessageText", text),
-      }));
-      if (index < reports.length - 1) box.addChild(new Text("", 0, 0));
-    }
-    return box;
+
+    return createToolExecutionWrapper(
+      (opt, currentTheme) => {
+        const effTheme = currentTheme ?? theme;
+        if (!opt.expanded) {
+          const groups = groupReportsByTeammate(reports);
+          const band = renderAgentMessageBand(
+            groups.map((group) => ({ direction: "from", teammate: group.teammate, count: group.reports.length })),
+            { theme: effTheme, fit: truncateToWidth, visibleWidth, wrapDetail: wrapTextWithAnsi, expandHint: keyHint("app.tools.expand", "to expand") },
+          );
+          if (!reports.some((report) => report.deliveredAfterStop)) return band;
+          const box = new Box(0, 0);
+          box.addChild(band);
+          box.addChild(new Text(effTheme.fg("warning", "Late delivery: process already stopped."), 0, 0));
+          return box;
+        }
+        const box = new Box(outputPad, 1, (text) => effTheme.bg("customMessageBg", text));
+        for (const [index, report] of reports.entries()) {
+          const teammate = report.teammate ?? report.agent ?? "teammate";
+          const prefix = effTheme.fg("customMessageLabel", effTheme.bold(formatAgentMessagePrefix("from")));
+          const name = effTheme.fg(agentColor(teammate), `@${teammate}`);
+          const delivery = report.deliveredAfterStop ? effTheme.fg("warning", " (late delivery; process stopped)") : "";
+          box.addChild(new Text(`${prefix}${name}${delivery}`, 0, 0));
+          box.addChild(new Markdown(report.body, 0, 0, getMarkdownTheme(), {
+            color: (text) => effTheme.fg("customMessageText", text),
+          }));
+          if (index < reports.length - 1) box.addChild(new Text("", 0, 0));
+        }
+        return box;
+      },
+      {
+        hostComponent: ToolExecutionComponent,
+        toolName: "message",
+        expanded,
+        ui: leaderCtx?.ui,
+        cwd: leaderCtx?.cwd,
+      },
+      theme,
+    );
   });
   registerLeaderTools(pi);
   registerTeamCommand(pi);
 
+  pi.on("message_start", (event) => {
+    if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
+    const deliveredAt = Date.now();
+    deliveries.set(event.message, extractReports(event.message.details).map((report) => annotateReportDelivery(
+      report, deliveredAt, report.spawnId ? getConfirmedStopTime(report.spawnId) : undefined,
+    )));
+  });
+
   pi.on("message_end", async (event) => {
     if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
-    const reports = extractReports(event.message.details);
+    const deliveredAt = Date.now();
+    const reports = deliveries.get(event.message) ?? extractReports(event.message.details).map((report) => annotateReportDelivery(
+      report, deliveredAt, report.spawnId ? getConfirmedStopTime(report.spawnId) : undefined,
+    ));
+    if (reports.length === 0) return;
     for (const report of reports) {
       if (!markTeammateFinished(report)) continue;
       pi.appendEntry(TEAMMATE_FINISHED_ENTRY_TYPE, {
         teammate: report.teammate ?? report.agent,
         agent: report.agent,
+        assignmentId: report.assignmentId,
+        workId: report.workId,
+        spawnId: report.spawnId,
       });
     }
+    return {
+      message: { ...event.message, content: formatReports(reports), details: reports.length === 1 ? reports[0] : { reports } },
+    };
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    leaderCtx = ctx;
+    syncLeaderContext(ctx);
+  });
+
+  pi.on("thinking_level_select", async (_event, ctx) => {
+    leaderCtx = ctx;
+    syncLeaderContext(ctx);
   });
 
   pi.on("session_start", async (_event, ctx) => {
     clearSessionAgents();
     resetState();
-    refreshLeaderToolDisclosure();
-    followUpQueue?.reset();
     leaderCtx = ctx;
-    followUpQueue = new FollowUpQueue({
-      isIdle: () => Boolean(leaderCtx?.isIdle()),
-      prepareOnDispatch: true,
-      dispatch: (reports, content) => leaderPi?.sendMessage({
-        customType: reports.length === 1 && reports[0]?.health
-          ? TEAMMATE_HEALTH_MESSAGE_TYPE
-          : reports.length === 1 && (reports[0]?.origin === "harness" || reports[0]?.harnessEvent)
-            ? TEAMMATE_HARNESS_MESSAGE_TYPE
-            : TEAMMATE_REPORT_MESSAGE_TYPE,
-        // Health remains a compact diagnostic for its dedicated renderer;
-        // other harness events retain their explicit envelope in model context.
-        content: reports.length === 1 && reports[0]?.health ? reports[0].body : content,
-        display: true,
-        details: reports.length === 1 ? reports[0] : { reports },
-      }, { triggerTurn: true, deliverAs: "followUp" }),
-      onFailure: (message) => {
-        if (leaderCtx) notifyPi(leaderCtx.ui, message, "warning");
-      },
-    });
     ensureTeamWidget(ctx);
     initTeamMachine(ctx, {
-      sendUpdate: sendMainSessionFollowUp,
-      archiveQueuedReports: (spawnId) => followUpQueue?.archiveSpawn(spawnId) ?? [],
+      sendUpdate: sendLeaderReport,
       notifyChange: () => {
         refreshTeamUI(leaderCtx);
-        refreshLeaderToolDisclosure();
       },
     });
     clearPiStatus(ctx.ui, "teammate");
     refreshTeamUI(ctx);
-    refreshLeaderToolDisclosure();
     void cleanupExpiredStateDirs(STATE_DIR_MAX_AGE_MS);
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    followUpQueue?.onBeforeAgentStart(event.prompt);
+    leaderCtx = ctx;
     const teamIsActive = hasActiveTeamState();
     return {
       systemPrompt: event.systemPrompt + (teamIsActive
         ? buildTeamLeaderGuidance(ctx?.cwd ?? process.cwd())
-        : TEAMMATE_SPAWN_GUIDANCE),
+        : buildIdleLeaderGuidance(ctx?.cwd ?? process.cwd())),
     };
   });
 
-  pi.on("agent_start", async () => {
-    followUpQueue?.onAgentStart();
-  });
-
-  pi.on("agent_settled", async () => {
-    followUpQueue?.onAgentSettled();
-  });
-
   pi.on("session_shutdown", async (_event, ctx) => {
     stopUiTimers();
     const diagnostics = await teardownTeammates();
@@ -200,18 +218,16 @@ export default function (pi: ExtensionAPI) {
     }
     shutdownTeamMachine();
     removeRuntimeDir(ctx);
-    followUpQueue?.reset();
-    followUpQueue = undefined;
     leaderPi = undefined;
     leaderCtx = undefined;
     resetState();
-    refreshLeaderToolDisclosure();
   });
 }
 
-function extractReports(details: unknown): FollowUpReport[] {
-  const typed = details as FollowUpReport | { reports?: FollowUpReport[] } | undefined;
+function extractReports(details: unknown): LeaderReport[] {
+  if (Array.isArray(details)) return details as LeaderReport[];
+  const typed = details as LeaderReport | { reports?: LeaderReport[] } | undefined;
   if (typed && "reports" in typed && Array.isArray(typed.reports)) return typed.reports;
-  if (typed && "teammate" in typed) return [typed as FollowUpReport];
+  if (typed && "teammate" in typed) return [typed as LeaderReport];
   return [];
 }

package/src/leader-reports.ts

@@ -0,0 +1,92 @@
+export const TEAMMATE_REPORT_MESSAGE_TYPE = "agent-teams-report";
+export const TEAMMATE_HARNESS_MESSAGE_TYPE = "agent-teams-harness";
+
+export interface LeaderReport {
+  teammate?: string;
+  agent?: string;
+  spawnId?: string;
+  assignmentId?: string;
+  workId?: string;
+  body: string;
+  /** Worker-authored reports are the default; harness events use a separate envelope. */
+  origin?: "teammate" | "harness";
+  harnessEvent?: {
+    type: string;
+    subject: string;
+  };
+  finished?: boolean;
+  /** Original append-only outbox event identifier, retained for session forensics. */
+  eventId?: string;
+  /** Original worker status, including omitted status, retained for session forensics. */
+  status?: "in_progress" | "completed" | "failed" | "inform" | "request" | "handoff";
+  runId?: string;
+  /** Wall-clock time the message was authored, not when Pi consumed it. */
+  timestamp?: number;
+  deliveredAt?: number;
+  processStoppedAt?: number;
+  deliveredAfterStop?: boolean;
+}
+
+export interface LeaderReportGroup {
+  teammate: string;
+  reports: LeaderReport[];
+}
+
+export function groupReportsByTeammate(reports: LeaderReport[]): LeaderReportGroup[] {
+  const groups = new Map<string, LeaderReportGroup>();
+  for (const report of reports) {
+    const teammate = report.teammate ?? report.agent ?? "teammate";
+    if (report.origin === "harness" || report.harnessEvent) {
+      groups.set(`harness:${groups.size}:${teammate}`, { teammate, reports: [report] });
+      continue;
+    }
+    const key = `message:${teammate}`;
+    const group = groups.get(key);
+    if (group) {
+      group.reports.push(report);
+    } else {
+      groups.set(key, { teammate, reports: [report] });
+    }
+  }
+  return [...groups.values()];
+}
+
+export function annotateReportDelivery(report: LeaderReport, deliveredAt: number, processStoppedAt?: number): LeaderReport {
+  if (processStoppedAt === undefined || deliveredAt < processStoppedAt) return { ...report, deliveredAt };
+  return { ...report, deliveredAt, processStoppedAt, deliveredAfterStop: true };
+}
+
+function timestampAttribute(name: string, timestamp: number | undefined): string {
+  return timestamp !== undefined && Number.isFinite(timestamp)
+    ? ` ${name}="${new Date(timestamp).toISOString()}"`
+    : "";
+}
+
+export function formatReports(reports: LeaderReport[]): string {
+  return reports
+    .map((report) => {
+      const { teammate, body, timestamp, origin, harnessEvent } = report;
+      const at = timestampAttribute("at", timestamp);
+      if (origin === "harness" || harnessEvent) {
+        const type = escapeAttribute(harnessEvent?.type ?? "event");
+        const subject = escapeAttribute(harnessEvent?.subject ?? "Agent Teams event");
+        return `<harness-event type="${type}" subject="${subject}"${at}>\n${body}\n</harness-event>`;
+      }
+      const name = teammate ?? "teammate";
+      const delivery = timestampAttribute("delivered-at", report.deliveredAt);
+      const stopped = timestampAttribute("process-stopped-at", report.processStoppedAt);
+      const late = report.deliveredAfterStop ? ' delivery="after-stop"' : "";
+      const work = report.workId ? ` work="${escapeAttribute(report.workId)}"` : "";
+      const assignment = report.assignmentId ? ` assignment="${escapeAttribute(report.assignmentId)}"` : "";
+      const status = report.status ? ` status="${escapeAttribute(report.status)}"` : "";
+      const note = report.deliveredAfterStop
+        ? "Delivery note: this report was queued before shutdown and delivered after the process stopped. It does not reopen the assignment.\n\n"
+        : "";
+      return `<agent-message from="${escapeAttribute(name)}"${at}${delivery}${stopped}${late}${work}${assignment}${status}>\n${note}${body}\n</agent-message>`;
+    })
+    .join("\n\n");
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/src/recipient.ts

@@ -0,0 +1,44 @@
+import type { Teammate } from "./types.ts";
+
+export function sessionRoute(name: string): string {
+  return `session:${name}`;
+}
+
+export function exactSessionRoute(name: string, spawnId: string): string {
+  return `session:${name}:${spawnId}`;
+}
+
+export function parseExactSessionRoute(route: string): { name: string; spawnId: string } | undefined {
+  const match = /^session:([^:]+):([^:]+)$/.exec(route);
+  return match ? { name: match[1], spawnId: match[2] } : undefined;
+}
+
+export function resolveExactSession(route: string, roster: readonly Teammate[]): Teammate | undefined {
+  const parsed = parseExactSessionRoute(route);
+  if (!parsed) return undefined;
+  return roster.find((teammate) => teammate.name === parsed.name && teammate.spawnId === parsed.spawnId && teammate.status !== "stopped");
+}
+
+/** Resolve a model-facing recipient route to its live roster entry. The entry's
+ *  spawn id travels with the message so a later replacement resident of the same
+ *  name cannot consume mail addressed to its predecessor. */
+export function resolveRecipient(
+  to: string,
+  roster: ReadonlyArray<{ name: string; agent: string; status: string; spawnId?: string }>,
+): { name: string; spawnId?: string } {
+  const exact = parseExactSessionRoute(to);
+  if (exact) {
+    const matched = roster.find((entry) => entry.name === exact.name && entry.spawnId === exact.spawnId && entry.status !== "stopped");
+    if (matched) return { name: matched.name, spawnId: matched.spawnId };
+    throw new Error(`No living session named "${to}".`);
+  }
+  const explicit = to.startsWith("session:");
+  const name = explicit ? to.slice("session:".length) : to;
+  const living = roster.filter((entry) => entry.status !== "stopped");
+  const recipients = living.filter((entry) => entry.name === name || (!explicit && entry.agent === to));
+  if (recipients.length > 1) {
+    throw new Error(`Ambiguous Agent @${to}. Use a precise route: ${recipients.map((entry) => entry.spawnId ? exactSessionRoute(entry.name, entry.spawnId) : sessionRoute(entry.name)).join(", ")}.`);
+  }
+  if (recipients.length === 1) return { name: recipients[0].name, spawnId: recipients[0].spawnId };
+  throw new Error(`No living teammate named "${to}".`);
+}