pi-sessions 0.8.0 → 0.10.0

package/extensions/subagents/reconcile.ts

@@ -0,0 +1,386 @@
+import { type SessionEntry, SessionManager } from "@earendil-works/pi-coding-agent";
+import { isSessionStarting } from "../session-handoff/metadata.ts";
+import {
+  createTmuxWindow,
+  killTmuxSession,
+  killTmuxWindow,
+  listTmuxWindows,
+  type TmuxExecutor,
+  tmuxSessionName,
+} from "../shared/tmux.ts";
+import { classifySubagent, type SubagentEvidence, type SubagentState } from "./classify.ts";
+import {
+  type ChildSubagentLifecycle,
+  collectParentLedger,
+  getChildSubagentLifecycle,
+  type ParentSubagentLedger,
+  SUBAGENT_DISOWNED_MESSAGE_CUSTOM_TYPE,
+  SUBAGENT_LAUNCHED_CUSTOM_TYPE,
+  SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE,
+  SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE,
+  SUBAGENT_SUSPENDED_CUSTOM_TYPE,
+  type SubagentLaunched,
+  type SubagentReport,
+  type SubagentReportMessage,
+} from "./ledger.ts";
+import { formatReportForModel } from "./report.ts";
+
+export interface ReconcileParentSession {
+  sessionId: string;
+  epoch: number;
+  getBranch(): readonly SessionEntry[];
+  isIdle(): boolean;
+}
+
+export interface ReconcileSessionManager {
+  getBranch(): readonly SessionEntry[];
+}
+
+export interface ReconcileMessaging {
+  listSessions(): Promise<string[]>;
+}
+
+export interface ReconcileActions extends TmuxExecutor {
+  appendEntry(customType: string, data: unknown): void;
+  sendMessage(
+    message: { customType: string; content: string; display: boolean; details: unknown },
+    options?: { triggerTurn: true } | { deliverAs: "steer" },
+  ): void;
+}
+
+export interface ReconcileDependencies {
+  executor: ReconcileActions;
+  messaging: ReconcileMessaging;
+  getParent(): ReconcileParentSession | undefined;
+  isCurrent(epoch: number): boolean;
+  openSession(path: string): ReconcileSessionManager;
+}
+
+interface ChildLifecycle extends ChildSubagentLifecycle {
+  awaitingKickoff: boolean;
+  readable: boolean;
+}
+
+interface ChildEvidence {
+  launch: SubagentLaunched;
+  classification: SubagentEvidence;
+  state: SubagentState;
+  reports: readonly SubagentReport[];
+}
+
+export interface ReconcileResult {
+  states: ReadonlyMap<string, SubagentState>;
+  registered: ReadonlySet<string>;
+}
+
+/**
+ * Converges the runtime view of a parent's owned subagents from their durable ledgers.
+ * It intentionally does not cache child files: every trigger observes current branch truth.
+ */
+export class SubagentReconciler {
+  private inFlight: Promise<ReconcileResult> | undefined;
+  private dirty = false;
+  private restoreSuspended = false;
+  private shuttingDown = false;
+  private registered: { epoch: number; sessionIds: Set<string> } | undefined;
+  private latestResult: ReconcileResult = emptyReconcileResult();
+
+  constructor(private readonly deps: ReconcileDependencies) {}
+
+  beginSession(): void {
+    this.shuttingDown = false;
+    this.dirty = false;
+    this.restoreSuspended = false;
+    this.registered = undefined;
+    this.latestResult = emptyReconcileResult();
+  }
+
+  reconcile(): Promise<ReconcileResult> {
+    return this.requestReconciliation(false);
+  }
+
+  reconcileAndRestoreSuspended(): Promise<ReconcileResult> {
+    return this.requestReconciliation(true);
+  }
+
+  private requestReconciliation(restoreSuspended: boolean): Promise<ReconcileResult> {
+    if (this.shuttingDown) {
+      return this.inFlight ?? Promise.resolve(this.latestResult);
+    }
+    this.dirty = true;
+    this.restoreSuspended ||= restoreSuspended;
+    if (this.inFlight) {
+      return this.inFlight;
+    }
+
+    const run = this.run().finally(() => {
+      if (this.inFlight === run) {
+        this.inFlight = undefined;
+      }
+    });
+    this.inFlight = run;
+    return run;
+  }
+
+  async suspendForShutdown(): Promise<void> {
+    this.shuttingDown = true;
+    await this.inFlight;
+
+    const parent = this.deps.getParent();
+    if (!parent) {
+      return;
+    }
+
+    const tmuxSession = tmuxSessionName(parent.sessionId);
+    const ledger = collectParentLedger(parent.getBranch(), parent.sessionId);
+    const windows = await listTmuxWindows(this.deps.executor, tmuxSession);
+    const ownedChildIds = new Set(ledger.launches.map((launch) => launch.childSessionId));
+    const childSessionIds = windows
+      .map((window) => window.piSessionId)
+      .filter((childSessionId) => ownedChildIds.has(childSessionId));
+
+    if (childSessionIds.length > 0) {
+      this.append(parent, SUBAGENT_SUSPENDED_CUSTOM_TYPE, {
+        writerSessionId: parent.sessionId,
+        childSessionIds,
+      });
+    }
+    this.requireCurrent(parent);
+    await killTmuxSession(this.deps.executor, tmuxSession);
+  }
+
+  private async run(): Promise<ReconcileResult> {
+    while (this.dirty && !this.shuttingDown) {
+      this.dirty = false;
+      const restoreSuspended = this.restoreSuspended;
+      this.restoreSuspended = false;
+      this.latestResult = await this.reconcileOnce(restoreSuspended);
+    }
+    return this.latestResult;
+  }
+
+  private async reconcileOnce(restoreSuspended: boolean): Promise<ReconcileResult> {
+    const parent = this.deps.getParent();
+    if (!parent) {
+      return emptyReconcileResult();
+    }
+
+    const branch = parent.getBranch();
+    const ledger = collectParentLedger(branch, parent.sessionId);
+    const tmuxSession = tmuxSessionName(parent.sessionId);
+    const [windows, liveSessionIds] = await Promise.all([
+      listTmuxWindows(this.deps.executor, tmuxSession),
+      this.deps.messaging.listSessions(),
+    ]);
+    const liveSessions = new Set(liveSessionIds);
+    const registered = this.getRegistered(parent.epoch);
+    for (const sessionId of liveSessionIds) {
+      registered.add(sessionId);
+    }
+    const windowSessionIds = new Set(windows.map((window) => window.piSessionId));
+    const evidence = ledger.launches.map((launch) =>
+      this.readChildEvidence(
+        launch,
+        ledger,
+        windowSessionIds.has(launch.childSessionId),
+        liveSessions.has(launch.childSessionId),
+        registered.has(launch.childSessionId),
+      ),
+    );
+
+    let runtimeChanged = false;
+
+    if (ledger.hasForeignLaunch && !ledger.hasDisownedNotice) {
+      this.sendDisownedMessage(parent);
+    }
+
+    for (const child of evidence) {
+      if (child.state === "unknown") {
+        continue;
+      }
+
+      for (const report of child.reports) {
+        if (!ledger.receivedReportIds.has(report.reportId)) {
+          this.append(parent, SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE, {
+            writerSessionId: parent.sessionId,
+            childSessionId: child.launch.childSessionId,
+            reportId: report.reportId,
+          });
+        }
+        if (!ledger.deliveredReportIds.has(report.reportId)) {
+          this.deliverRecoveredReport(parent, child.launch, report);
+        }
+      }
+
+      if (child.state === "suspended" && restoreSuspended) {
+        this.append(parent, SUBAGENT_LAUNCHED_CUSTOM_TYPE, child.launch);
+        await createTmuxWindow(this.deps.executor, {
+          tmuxSession,
+          name: child.launch.title,
+          cwd: child.launch.cwd,
+          command: child.launch.resumeCommand,
+          piSessionId: child.launch.childSessionId,
+        });
+        child.classification = {
+          ...child.classification,
+          cancelled: false,
+          suspended: false,
+        };
+        runtimeChanged = true;
+      } else if (child.state === "stopping") {
+        this.requireCurrent(parent);
+        await killTmuxWindow(this.deps.executor, tmuxSession, child.launch.childSessionId);
+        runtimeChanged = true;
+      }
+    }
+
+    const ownedIds = new Set(ledger.launches.map((launch) => launch.childSessionId));
+    for (const window of windows) {
+      if (!ownedIds.has(window.piSessionId)) {
+        this.requireCurrent(parent);
+        await killTmuxWindow(this.deps.executor, tmuxSession, window.piSessionId);
+        runtimeChanged = true;
+      }
+    }
+
+    if (runtimeChanged) {
+      const [currentWindows, currentLiveSessionIds] = await Promise.all([
+        listTmuxWindows(this.deps.executor, tmuxSession),
+        this.deps.messaging.listSessions(),
+      ]);
+      const currentWindowSessionIds = new Set(currentWindows.map((window) => window.piSessionId));
+      const currentLiveSessions = new Set(currentLiveSessionIds);
+      for (const sessionId of currentLiveSessionIds) {
+        registered.add(sessionId);
+      }
+      for (const child of evidence) {
+        child.classification = {
+          ...child.classification,
+          hasWindow: currentWindowSessionIds.has(child.launch.childSessionId),
+          brokerLive: currentLiveSessions.has(child.launch.childSessionId),
+          hasRegistered: registered.has(child.launch.childSessionId),
+          awaitingKickoff: child.classification.awaitingKickoff,
+        };
+        child.state = classifySubagent(child.classification);
+      }
+    }
+
+    return {
+      states: new Map(evidence.map((child) => [child.launch.childSessionId, child.state])),
+      registered: new Set(registered),
+    };
+  }
+
+  private readChildEvidence(
+    launch: SubagentLaunched,
+    ledger: ParentSubagentLedger,
+    hasWindow: boolean,
+    brokerLive: boolean,
+    hasRegistered: boolean,
+  ): ChildEvidence {
+    const lifecycle = this.readChildLifecycle(launch.childSessionFile);
+    const classification: SubagentEvidence = {
+      hasWindow,
+      brokerLive,
+      hasRegistered,
+      awaitingKickoff: lifecycle.awaitingKickoff,
+      cancelled: ledger.cancelledChildIds.has(launch.childSessionId),
+      suspended: ledger.suspendedChildIds.has(launch.childSessionId),
+      hasReportOrClosure: lifecycle.reports.length > 0 || lifecycle.closed !== undefined,
+      childReadable: lifecycle.readable,
+    };
+    return {
+      launch,
+      classification,
+      reports: lifecycle.reports,
+      state: classifySubagent(classification),
+    };
+  }
+
+  private readChildLifecycle(path: string): ChildLifecycle {
+    try {
+      const branch = this.deps.openSession(path).getBranch();
+      return {
+        ...getChildSubagentLifecycle(branch),
+        awaitingKickoff: isSessionStarting(branch),
+        readable: true,
+      };
+    } catch {
+      return {
+        reports: [],
+        closed: undefined,
+        hasReminder: false,
+        awaitingKickoff: false,
+        readable: false,
+      };
+    }
+  }
+
+  private getRegistered(epoch: number): Set<string> {
+    if (this.registered?.epoch !== epoch) {
+      this.registered = { epoch, sessionIds: new Set() };
+    }
+    return this.registered.sessionIds;
+  }
+
+  private append(parent: ReconcileParentSession, customType: string, data: unknown): void {
+    this.requireCurrent(parent);
+    this.deps.executor.appendEntry(customType, data);
+  }
+
+  private deliverRecoveredReport(
+    parent: ReconcileParentSession,
+    launch: SubagentLaunched,
+    report: SubagentReport,
+  ): void {
+    const message: SubagentReportMessage = {
+      writerSessionId: parent.sessionId,
+      childSessionId: launch.childSessionId,
+      title: launch.title,
+      ...report,
+      provenance: "recovered",
+    };
+    this.sendMessage(parent, {
+      customType: SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE,
+      content: formatReportForModel(launch.title, message),
+      display: true,
+      details: message,
+    });
+  }
+
+  private sendDisownedMessage(parent: ReconcileParentSession): void {
+    this.requireCurrent(parent);
+    this.deps.executor.sendMessage({
+      customType: SUBAGENT_DISOWNED_MESSAGE_CUSTOM_TYPE,
+      content:
+        "[system] copied subagent records belong to the original session; this fork owns none.",
+      display: true,
+      details: { writerSessionId: parent.sessionId },
+    });
+  }
+
+  private sendMessage(
+    parent: ReconcileParentSession,
+    message: { customType: string; content: string; display: boolean; details: unknown },
+  ): void {
+    this.requireCurrent(parent);
+    const delivery = parent.isIdle()
+      ? { triggerTurn: true as const }
+      : { deliverAs: "steer" as const };
+    this.deps.executor.sendMessage(message, delivery);
+  }
+
+  private requireCurrent(parent: ReconcileParentSession): void {
+    if (!this.deps.isCurrent(parent.epoch)) {
+      throw new Error("The parent session changed during subagent reconciliation.");
+    }
+  }
+}
+
+export function openReconcileSession(path: string): ReconcileSessionManager {
+  return SessionManager.open(path);
+}
+
+function emptyReconcileResult(): ReconcileResult {
+  return { states: new Map(), registered: new Set() };
+}

package/extensions/subagents/report-message-presenter.ts

@@ -0,0 +1,36 @@
+import type { RenderTheme } from "../shared/rendering/theme.ts";
+import type { SubagentReportMessageViewModel } from "./report-message-view-model.ts";
+
+export function presentSubagentReportMessage(
+  report: SubagentReportMessageViewModel,
+  theme: RenderTheme,
+): string {
+  const status = report.status === "done" ? "" : `[${report.status}] `;
+  const sections = [
+    theme.fg("toolTitle", theme.bold(`Report from subagent ${status}“${report.title}”`)),
+    presentSection("Summary", report.summary, theme),
+  ];
+
+  if (report.details) {
+    sections.push(presentSection("Details", report.details, theme));
+  }
+  if (report.references.length > 0) {
+    const references = report.references.map((reference) =>
+      reference.description
+        ? `- ${reference.reference} — ${reference.description}`
+        : `- ${reference.reference}`,
+    );
+    sections.push(presentSection("References", references.join("\n"), theme));
+  }
+  if (report.nextSteps.length > 0) {
+    sections.push(
+      presentSection("Next steps", report.nextSteps.map((step) => `- ${step}`).join("\n"), theme),
+    );
+  }
+
+  return sections.join("\n\n");
+}
+
+function presentSection(heading: string, body: string, theme: RenderTheme): string {
+  return `${theme.fg("toolTitle", theme.bold(heading))}\n${theme.fg("toolOutput", body)}`;
+}

package/extensions/subagents/report-message-renderer.ts

@@ -0,0 +1,21 @@
+import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+import { SUBAGENT_REPORT_MESSAGE_SCHEMA } from "./ledger.ts";
+import { presentSubagentReportMessage } from "./report-message-presenter.ts";
+import { buildSubagentReportMessageView } from "./report-message-view-model.ts";
+
+export const renderSubagentReportMessage: MessageRenderer = (message, _options, theme) => {
+  const details = safeParseTypeBoxValue(SUBAGENT_REPORT_MESSAGE_SCHEMA, message.details);
+  if (!details) {
+    return undefined;
+  }
+  const report = buildSubagentReportMessageView(details);
+  if (!report) {
+    return undefined;
+  }
+
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(presentSubagentReportMessage(report, theme), 0, 0));
+  return box;
+};

package/extensions/subagents/report-message-view-model.ts

@@ -0,0 +1,29 @@
+import type { TaskReportReference } from "../shared/session-broker/protocol.ts";
+import type { SubagentReportMessage } from "./ledger.ts";
+
+export interface SubagentReportMessageViewModel {
+  title: string;
+  status: SubagentReportMessage["status"];
+  summary: string;
+  details?: string | undefined;
+  references: readonly TaskReportReference[];
+  nextSteps: readonly string[];
+}
+
+export function buildSubagentReportMessageView(
+  report: SubagentReportMessage,
+): SubagentReportMessageViewModel | undefined {
+  const title = report.title?.trim();
+  if (!title) {
+    return undefined;
+  }
+
+  return {
+    title,
+    status: report.status,
+    summary: report.summary,
+    details: report.details,
+    references: report.references ?? [],
+    nextSteps: report.nextSteps ?? [],
+  };
+}

package/extensions/subagents/report.ts

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import { defineTool, type ExtensionAPI, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { HandoffSubagent } from "../session-handoff/metadata.ts";
+import type { MessagingHandle } from "../session-messaging/install.ts";
+import { formatError } from "../shared/errors.ts";
+import {
+  type SessionSubagentReportEnvelope,
+  TASK_REPORT_SCHEMA,
+} from "../shared/session-broker/protocol.ts";
+import {
+  collectParentLedger,
+  SUBAGENT_REPORT_CUSTOM_TYPE,
+  type SubagentReport,
+  type SubagentReportMessage,
+  type SubagentReportReceived,
+} from "./ledger.ts";
+
+export interface SubagentParentSession {
+  sessionId: string;
+  getBranch(): readonly SessionEntry[];
+  isIdle(): boolean;
+  epoch: number;
+}
+
+export interface ReportingSubagentSession extends SubagentParentSession {
+  identity: HandoffSubagent;
+}
+
+export interface IncomingSubagentReport {
+  receipt: SubagentReportReceived | undefined;
+  message: SubagentReportMessage;
+  content: string;
+  delivery: { triggerTurn: true } | { deliverAs: "steer" };
+}
+
+export function createSubmitTaskReportTool(
+  pi: ExtensionAPI,
+  messaging: MessagingHandle,
+  getSession: () => ReportingSubagentSession | undefined,
+) {
+  return defineTool({
+    name: "submit_task_report",
+    label: "Submit task report",
+    description:
+      "Send a report to the parent session and end the current turn. Use it when the delegated task or requested follow-up is done, blocked, or cannot be completed.",
+    promptSnippet: "Submit the current task report to the parent session and end the turn",
+    promptGuidelines: [
+      "Call submit_task_report exactly once as the final tool call for every delegated task or follow-up that expects a response.",
+      "Do not send task results through session_send_message; submit_task_report is the only supported means to send final results to the parent.",
+      "If you receive steering instructions from the parent via session_send_message, you may optionally reply to the parent using the session_send_message tool if the parent's message calls for something that is out of band of what would be included in the report.",
+    ],
+    parameters: TASK_REPORT_SCHEMA,
+    async execute(_toolCallId, params) {
+      const session = getSession();
+      if (!session) {
+        throw new Error("submit_task_report is available only in its original subagent session.");
+      }
+      const summary = params.summary.trim();
+      if (!summary) {
+        throw new Error("submit_task_report requires a summary.");
+      }
+
+      const durableReport: SubagentReport = {
+        reportId: randomUUID(),
+        status: params.status,
+        summary,
+        ...(params.details ? { details: params.details } : {}),
+        ...(params.references ? { references: params.references } : {}),
+        ...(params.nextSteps ? { nextSteps: params.nextSteps } : {}),
+      };
+      pi.appendEntry(SUBAGENT_REPORT_CUSTOM_TYPE, durableReport);
+
+      let delivered = false;
+      let deliveryError: string | undefined;
+      try {
+        const result = await messaging.sendSubagentReport({
+          target: session.identity.ownerSessionId,
+          ...durableReport,
+        });
+        delivered = result.delivered;
+        deliveryError = result.delivered ? undefined : result.error;
+      } catch (error) {
+        deliveryError = formatError(error);
+      }
+
+      const delivery = delivered
+        ? "Report delivered to the parent."
+        : `Report saved for later recovery${deliveryError ? `: ${deliveryError}` : "."}`;
+      return {
+        content: [{ type: "text" as const, text: `${delivery} Stopping.` }],
+        details: { ...durableReport, delivered },
+        terminate: true,
+      };
+    },
+  });
+}
+
+export function buildIncomingSubagentReport(
+  session: SubagentParentSession,
+  envelope: SessionSubagentReportEnvelope,
+): IncomingSubagentReport | undefined {
+  const ownerSessionId = session.sessionId;
+  const ledger = collectParentLedger(session.getBranch(), ownerSessionId);
+  const launch = ledger.launches.find((candidate) => candidate.childSessionId === envelope.source);
+  if (!launch) {
+    throw new Error("Report source is not an owned subagent on the active branch.");
+  }
+  if (ledger.deliveredReportIds.has(envelope.reportId)) {
+    return undefined;
+  }
+
+  const receipt = ledger.receivedReportIds.has(envelope.reportId)
+    ? undefined
+    : {
+        writerSessionId: ownerSessionId,
+        childSessionId: envelope.source,
+        reportId: envelope.reportId,
+      };
+  const message: SubagentReportMessage = {
+    writerSessionId: ownerSessionId,
+    childSessionId: envelope.source,
+    reportId: envelope.reportId,
+    title: launch.title,
+    status: envelope.status,
+    summary: envelope.summary,
+    ...(envelope.details ? { details: envelope.details } : {}),
+    ...(envelope.references ? { references: envelope.references } : {}),
+    ...(envelope.nextSteps ? { nextSteps: envelope.nextSteps } : {}),
+    provenance: "live",
+  };
+  return {
+    receipt,
+    message,
+    content: formatReportForModel(launch.title, message),
+    delivery: session.isIdle() ? { triggerTurn: true } : { deliverAs: "steer" },
+  };
+}
+
+export function formatReportForModel(title: string, report: SubagentReportMessage): string {
+  const sections = [
+    `Subagent report from "${title}" (session: ${report.childSessionId}, status: ${report.status})`,
+    `Summary\n\n${report.summary}`,
+  ];
+  if (report.details) {
+    sections.push(`Details\n\n${report.details}`);
+  }
+  if (report.references?.length) {
+    const references = report.references.map((reference) =>
+      reference.description
+        ? `- ${reference.reference} — ${reference.description}`
+        : `- ${reference.reference}`,
+    );
+    sections.push(`References\n\n${references.join("\n")}`);
+  }
+  if (report.nextSteps?.length) {
+    sections.push(`Next steps\n\n${report.nextSteps.map((step) => `- ${step}`).join("\n")}`);
+  }
+  return sections.join("\n\n");
+}