pi-sessions 0.8.0 → 0.10.0

package/extensions/subagents/cancel.ts

@@ -0,0 +1,111 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { CancelSessionResult } from "../session-messaging/install.ts";
+import type { SubagentState } from "./classify.ts";
+import {
+  findOwnedSubagentLaunch,
+  SUBAGENT_CANCELLED_CUSTOM_TYPE,
+  type SubagentLaunched,
+} from "./ledger.ts";
+import type { ReconcileResult } from "./reconcile.ts";
+
+export interface ManagedSubagentCancelResult {
+  kind: "managed";
+  accepted: true;
+  target: {
+    sessionId: string;
+    sessionName?: string;
+    cwd?: string;
+  };
+  state: SubagentState;
+  cancelId?: string;
+  relation?: string;
+}
+
+export type SubagentCancelResult = CancelSessionResult | ManagedSubagentCancelResult;
+
+export interface CancelParentSession {
+  sessionId: string;
+  epoch: number;
+  getBranch(): readonly SessionEntry[];
+}
+
+interface CancelMessaging {
+  cancelSession(sessionId: string): Promise<CancelSessionResult>;
+  listSessions(): Promise<string[]>;
+}
+
+interface CancelActions {
+  appendEntry(customType: string, data: unknown): void;
+}
+
+interface CancelReconciler {
+  reconcile(): Promise<ReconcileResult>;
+}
+
+export class SubagentCancellationRouter {
+  constructor(
+    private readonly executor: CancelActions,
+    private readonly messaging: CancelMessaging,
+    private readonly reconciler: CancelReconciler,
+    private readonly getParent: () => CancelParentSession | undefined,
+    private readonly isCurrent: (epoch: number) => boolean,
+  ) {}
+
+  async cancelSession(sessionId: string): Promise<SubagentCancelResult> {
+    const parent = this.getParent();
+    const launch = parent
+      ? findOwnedSubagentLaunch(parent.getBranch(), parent.sessionId, sessionId)
+      : undefined;
+    if (!parent || !launch) {
+      return this.messaging.cancelSession(sessionId);
+    }
+
+    return this.cancelOwned(parent, launch);
+  }
+
+  private async cancelOwned(
+    parent: CancelParentSession,
+    launch: SubagentLaunched,
+  ): Promise<ManagedSubagentCancelResult> {
+    this.requireCurrent(parent);
+    this.executor.appendEntry(SUBAGENT_CANCELLED_CUSTOM_TYPE, {
+      writerSessionId: parent.sessionId,
+      childSessionId: launch.childSessionId,
+    });
+
+    let brokerResult: CancelSessionResult | undefined;
+    if ((await this.messaging.listSessions()).includes(launch.childSessionId)) {
+      this.requireCurrent(parent);
+      brokerResult = await this.messaging.cancelSession(launch.childSessionId);
+    }
+
+    const reconciliation = await this.reconciler.reconcile();
+    return buildManagedResult(launch, brokerResult, reconciliation);
+  }
+
+  private requireCurrent(parent: CancelParentSession): void {
+    if (!this.isCurrent(parent.epoch)) {
+      throw new Error("The parent session changed while cancelling its subagent.");
+    }
+  }
+}
+
+function buildManagedResult(
+  launch: SubagentLaunched,
+  brokerResult: CancelSessionResult | undefined,
+  reconciliation: ReconcileResult,
+): ManagedSubagentCancelResult {
+  const delivered = brokerResult?.delivered ? brokerResult : undefined;
+  return {
+    kind: "managed",
+    accepted: true,
+    target: {
+      sessionId: launch.childSessionId,
+      sessionName: delivered?.target.sessionName ?? launch.title,
+      ...(delivered?.target.cwd ? { cwd: delivered.target.cwd } : {}),
+    },
+    state: reconciliation.states.get(launch.childSessionId) ?? "unknown",
+    ...(brokerResult ? { cancelId: brokerResult.cancelId } : {}),
+    ...(delivered?.relation ? { relation: delivered.relation } : {}),
+  };
+}

package/extensions/subagents/classify.ts

@@ -0,0 +1,58 @@
+export type SubagentState =
+  | "starting"
+  | "busy"
+  | "active"
+  | "completed"
+  | "stopping"
+  | "stopped"
+  | "suspended"
+  | "interrupted"
+  | "unknown";
+
+const RUNNING_SUBAGENT_STATES: ReadonlySet<SubagentState> = new Set(["starting", "busy", "active"]);
+
+export interface SubagentEvidence {
+  hasWindow: boolean;
+  brokerLive: boolean;
+  hasRegistered: boolean;
+  awaitingKickoff: boolean;
+  cancelled: boolean;
+  suspended: boolean;
+  hasReportOrClosure: boolean;
+  childReadable: boolean;
+}
+
+export function isRunningSubagentState(state: SubagentState): boolean {
+  return RUNNING_SUBAGENT_STATES.has(state);
+}
+
+export function classifySubagent(evidence: SubagentEvidence): SubagentState {
+  if (!evidence.childReadable) {
+    return "unknown";
+  }
+  if (evidence.hasWindow && evidence.cancelled) {
+    return "stopping";
+  }
+  if (evidence.awaitingKickoff) {
+    return "starting";
+  }
+  if (evidence.hasWindow && !evidence.hasRegistered) {
+    return "starting";
+  }
+  if (evidence.hasWindow) {
+    return "busy";
+  }
+  if (evidence.brokerLive) {
+    return "active";
+  }
+  if (evidence.hasReportOrClosure) {
+    return "completed";
+  }
+  if (evidence.cancelled) {
+    return "stopped";
+  }
+  if (evidence.suspended) {
+    return "suspended";
+  }
+  return "interrupted";
+}

package/extensions/subagents/install.ts

@@ -0,0 +1,229 @@
+import type { ExtensionAPI, SessionTreeNode } from "@earendil-works/pi-coding-agent";
+import type { HandoffLaunchTarget } from "../session-handoff/launch-target.ts";
+import type {
+  MessagingHandle,
+  SendMessageRequest,
+  SendMessageResult,
+} from "../session-messaging/install.ts";
+import type { SessionLifecycle } from "../shared/composition.ts";
+import type { SessionSettings } from "../shared/settings.ts";
+import { isTmuxInstalled } from "../shared/tmux.ts";
+import { SubagentCancellationRouter, type SubagentCancelResult } from "./cancel.ts";
+import { createSubagentLaunchTarget, type SubagentLaunchState } from "./launch-target.ts";
+import {
+  hasSubagentLaunchEntries,
+  SUBAGENT_LAUNCHED_CUSTOM_TYPE,
+  SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE,
+  SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE,
+} from "./ledger.ts";
+import { openReconcileSession, SubagentReconciler } from "./reconcile.ts";
+import {
+  buildIncomingSubagentReport,
+  createSubmitTaskReportTool,
+  type SubagentParentSession,
+} from "./report.ts";
+import { renderSubagentReportMessage } from "./report-message-renderer.ts";
+import { openRosterSession, type SubagentRoster, TranscriptSubagentRoster } from "./roster.ts";
+import {
+  countSubagentReports,
+  createSettledChildLifecycle,
+  findSelfSubagentIdentity,
+  type SubagentChildSessionState,
+} from "./settle.ts";
+import { SubagentMessageRouter } from "./wake.ts";
+
+interface ParentSessionState extends SubagentParentSession {
+  getSessionName(): string | undefined;
+  launchState: SubagentLaunchState;
+  tmuxInstalled: boolean;
+  getTree(): SessionTreeNode[];
+  hasPendingMessages(): boolean;
+  shutdown(): void;
+}
+
+interface CurrentSubagentSession {
+  parent: ParentSessionState;
+  child?: SubagentChildSessionState | undefined;
+}
+
+export interface SubagentsHandle extends SessionLifecycle {
+  roster: SubagentRoster;
+  getLaunchTargets(): readonly HandoffLaunchTarget[];
+  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  cancelSession(sessionId: string): Promise<SubagentCancelResult>;
+}
+
+export function installSubagents(
+  pi: ExtensionAPI,
+  deps: { settings: SessionSettings; messaging: MessagingHandle },
+): SubagentsHandle {
+  pi.registerMessageRenderer(SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE, renderSubagentReportMessage);
+
+  let epoch = 0;
+  let current: CurrentSubagentSession | undefined;
+
+  const isCurrentSession = (candidateEpoch: number): boolean =>
+    current?.parent.epoch === candidateEpoch;
+  const reconciler = new SubagentReconciler({
+    executor: pi,
+    messaging: deps.messaging,
+    getParent: () => current?.parent,
+    isCurrent: isCurrentSession,
+    openSession: openReconcileSession,
+  });
+  const settledChildLifecycle = createSettledChildLifecycle(pi, reconciler, isCurrentSession);
+  const roster = new TranscriptSubagentRoster({
+    executor: pi,
+    messaging: deps.messaging,
+    getParent: () => current?.parent,
+    reconcile: () => reconciler.reconcile(),
+    openSession: openRosterSession,
+  });
+  const messageRouter = new SubagentMessageRouter(
+    pi,
+    deps.messaging,
+    () => current?.parent,
+    isCurrentSession,
+    {
+      onMaterialize: (launch) => pi.appendEntry(SUBAGENT_LAUNCHED_CUSTOM_TYPE, launch),
+      afterOwnedSend: async () => {
+        await reconciler.reconcile();
+      },
+    },
+  );
+  const cancellationRouter = new SubagentCancellationRouter(
+    pi,
+    deps.messaging,
+    reconciler,
+    () => current?.parent,
+    isCurrentSession,
+  );
+
+  deps.messaging.onIncomingSubagentReport(async (envelope) => {
+    const parent = current?.parent;
+    if (!parent) {
+      throw new Error("Target session is not ready to receive subagent reports.");
+    }
+    const incoming = buildIncomingSubagentReport(parent, envelope);
+    if (!incoming) {
+      return;
+    }
+    if (incoming.receipt) {
+      pi.appendEntry(SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE, incoming.receipt);
+    }
+    pi.sendMessage(
+      {
+        customType: SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE,
+        content: incoming.content,
+        display: true,
+        details: incoming.message,
+      },
+      incoming.delivery,
+    );
+  });
+
+  pi.on("before_agent_start", (event) => {
+    const child = current?.child;
+    if (!child) {
+      return;
+    }
+    return {
+      systemPrompt: `${event.systemPrompt}
+
+You are working as a subagent on one task delegated by a parent session. The handoff defines your task. Work independently, stay within its scope, and do not duplicate work assigned to the parent or another subagent. Use the available tools to complete the task and validate your conclusions. Messages from the parent may refine the task or request a follow-up, but they do not replace your original task with unrelated work.`,
+    };
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    settledChildLifecycle.cancel();
+    if (current?.child) {
+      current.child.reportsAtTurnStart = countSubagentReports(ctx.sessionManager.getBranch());
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    const session = current;
+    if (!session || session.parent.sessionId !== ctx.sessionManager.getSessionId()) {
+      return;
+    }
+    const reconciliation = hasSubagentLaunchEntries(session.parent.getBranch())
+      ? await reconciler.reconcile()
+      : undefined;
+    if (session.child) {
+      await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
+    }
+  });
+
+  pi.on("session_tree", async () => {
+    await reconciler.reconcileAndRestoreSuspended();
+  });
+
+  return {
+    roster,
+    sendMessage: (request) => messageRouter.sendMessage(request),
+    cancelSession: (sessionId) => cancellationRouter.cancelSession(sessionId),
+    getLaunchTargets() {
+      const parent = current?.parent;
+      if (!parent?.tmuxInstalled || parent.launchState.depth >= deps.settings.subagents.maxDepth) {
+        return [];
+      }
+      return [createSubagentLaunchTarget(pi, parent.launchState, isCurrentSession)];
+    },
+    async onSessionStart(_event, ctx) {
+      settledChildLifecycle.cancel();
+      epoch += 1;
+      const sessionId = ctx.sessionManager.getSessionId();
+      const sessionManager = ctx.sessionManager;
+      const sessionStartBranch = sessionManager.getBranch();
+      const identity = findSelfSubagentIdentity(sessionId, sessionStartBranch);
+      const parent: ParentSessionState = {
+        sessionId,
+        getSessionName: () => sessionManager.getSessionName(),
+        getBranch: () => sessionManager.getBranch(),
+        getTree: () => sessionManager.getTree(),
+        isIdle: ctx.isIdle,
+        hasPendingMessages: ctx.hasPendingMessages,
+        shutdown: ctx.shutdown,
+        epoch,
+        launchState: { sessionId, depth: identity?.depth ?? 0, epoch },
+        tmuxInstalled: await isTmuxInstalled(pi, ctx.cwd),
+      };
+      reconciler.beginSession();
+      current = {
+        parent,
+        ...(identity
+          ? {
+              child: {
+                identity,
+                requestResponse: identity.requestResponse,
+                reportsAtTurnStart: countSubagentReports(sessionStartBranch),
+              },
+            }
+          : {}),
+      };
+      if (identity) {
+        pi.registerTool(
+          createSubmitTaskReportTool(pi, deps.messaging, () => {
+            const session = current;
+            return session?.child
+              ? { ...session.parent, identity: session.child.identity }
+              : undefined;
+          }),
+        );
+      }
+      if (_event.reason === "reload") {
+        await reconciler.reconcile();
+      } else {
+        await reconciler.reconcileAndRestoreSuspended();
+      }
+    },
+    async onSessionShutdown(event) {
+      settledChildLifecycle.cancel();
+      if (current && event.reason !== "reload") {
+        await reconciler.suspendForShutdown();
+      }
+      epoch += 1;
+      current = undefined;
+    },
+  };
+}

package/extensions/subagents/launch-target.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "../session-handoff/launch-target.ts";
+import { formatError } from "../shared/errors.ts";
+import { createTmuxWindow, tmuxSessionName } from "../shared/tmux.ts";
+import { SUBAGENT_LAUNCHED_CUSTOM_TYPE, type SubagentLaunched } from "./ledger.ts";
+
+export interface SubagentLaunchState {
+  sessionId: string;
+  depth: number;
+  epoch: number;
+}
+
+export function createSubagentLaunchTarget(
+  pi: ExtensionAPI,
+  state: SubagentLaunchState,
+  isCurrent: (epoch: number) => boolean,
+): HandoffLaunchTarget {
+  return {
+    value: SUBAGENT_LAUNCH,
+    description:
+      "'subagent' delegates one task to a detached tmux worker and requests a report by default.",
+    requestResponseDefault: true,
+    bootstrapMode: "automatic",
+    describeSubagentChild(input) {
+      return {
+        childSessionId: input.childSessionId,
+        ownerSessionId: input.ownerSessionId,
+        depth: state.depth + 1,
+        requestResponse: input.requestResponse,
+      };
+    },
+    prepareChild(input) {
+      requireCurrentParent(state, input.parentSessionId, isCurrent);
+    },
+    async launch(input) {
+      requireCurrentParent(state, input.parentSessionId, isCurrent);
+      const launched: SubagentLaunched = {
+        writerSessionId: state.sessionId,
+        childSessionId: input.prepared.sessionId,
+        childSessionFile: input.prepared.sessionFile,
+        title: input.title,
+        goal: input.goal,
+        requestResponse: input.requestResponse,
+        model: input.model,
+        cwd: input.cwd,
+        resumeCommand: input.prepared.resumeCommand,
+        depth: state.depth + 1,
+      };
+      pi.appendEntry(SUBAGENT_LAUNCHED_CUSTOM_TYPE, launched);
+
+      try {
+        await createTmuxWindow(pi, {
+          tmuxSession: tmuxSessionName(state.sessionId),
+          name: input.title,
+          cwd: input.cwd,
+          command: input.prepared.resumeCommand,
+          piSessionId: input.prepared.sessionId,
+        });
+        return { success: true, backend: "tmux" };
+      } catch (error) {
+        return { success: false, error: formatError(error) };
+      }
+    },
+  };
+}
+
+function requireCurrentParent(
+  state: SubagentLaunchState,
+  parentSessionId: string,
+  isCurrent: (epoch: number) => boolean,
+): void {
+  if (!isCurrent(state.epoch) || state.sessionId !== parentSessionId) {
+    throw new Error("The parent session changed before subagent launch completed.");
+  }
+}

package/extensions/subagents/ledger.ts

@@ -0,0 +1,217 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { TASK_REPORT_SCHEMA } from "../shared/session-broker/protocol.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
+
+export const SUBAGENT_LAUNCHED_CUSTOM_TYPE = "pi-sessions.subagent_launched";
+export const SUBAGENT_REPORT_CUSTOM_TYPE = "pi-sessions.subagent_report";
+export const SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE = "pi-sessions.subagent_report_received";
+export const SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE = "pi-sessions.subagent_report_message";
+export const SUBAGENT_CLOSED_CUSTOM_TYPE = "pi-sessions.subagent_closed";
+export const SUBAGENT_REPORT_REMINDER_MESSAGE_CUSTOM_TYPE = "pi-sessions.report_reminder_message";
+export const SUBAGENT_DISOWNED_MESSAGE_CUSTOM_TYPE = "pi-sessions.subagent_disowned_message";
+export const SUBAGENT_CANCELLED_CUSTOM_TYPE = "pi-sessions.subagent_cancelled";
+export const SUBAGENT_SUSPENDED_CUSTOM_TYPE = "pi-sessions.subagent_suspended";
+
+export const SUBAGENT_LAUNCHED_SCHEMA = Type.Object({
+  writerSessionId: Type.String(),
+  childSessionId: Type.String(),
+  childSessionFile: Type.String(),
+  title: Type.String(),
+  goal: Type.String(),
+  requestResponse: Type.Boolean(),
+  model: Type.Optional(Type.String()),
+  cwd: Type.String(),
+  resumeCommand: Type.String(),
+  depth: Type.Integer({ minimum: 1 }),
+});
+
+export const SUBAGENT_REPORT_SCHEMA = Type.Intersect([
+  Type.Object({ reportId: Type.String() }),
+  TASK_REPORT_SCHEMA,
+]);
+
+export const SUBAGENT_REPORT_RECEIVED_SCHEMA = Type.Object({
+  writerSessionId: Type.String(),
+  childSessionId: Type.String(),
+  reportId: Type.String(),
+});
+
+export const SUBAGENT_REPORT_MESSAGE_SCHEMA = Type.Intersect([
+  Type.Object({
+    writerSessionId: Type.String(),
+    childSessionId: Type.String(),
+    reportId: Type.String(),
+    title: Type.Optional(Type.String()),
+    provenance: Type.Union([Type.Literal("live"), Type.Literal("recovered")]),
+  }),
+  TASK_REPORT_SCHEMA,
+]);
+
+export const SUBAGENT_CLOSED_SCHEMA = Type.Object({
+  reason: Type.Union([
+    Type.Literal("no_response_expected"),
+    Type.Literal("no_report_after_reminder"),
+  ]),
+});
+
+export const SUBAGENT_CANCELLED_SCHEMA = Type.Object({
+  writerSessionId: Type.String(),
+  childSessionId: Type.String(),
+});
+export const SUBAGENT_SUSPENDED_SCHEMA = Type.Object({
+  writerSessionId: Type.String(),
+  childSessionIds: Type.Array(Type.String()),
+});
+export const SUBAGENT_DISOWNED_MESSAGE_SCHEMA = Type.Object({
+  writerSessionId: Type.String(),
+});
+
+export type SubagentLaunched = Static<typeof SUBAGENT_LAUNCHED_SCHEMA>;
+export type SubagentReport = Static<typeof SUBAGENT_REPORT_SCHEMA>;
+export type SubagentReportReceived = Static<typeof SUBAGENT_REPORT_RECEIVED_SCHEMA>;
+export type SubagentReportMessage = Static<typeof SUBAGENT_REPORT_MESSAGE_SCHEMA>;
+export type SubagentClosed = Static<typeof SUBAGENT_CLOSED_SCHEMA>;
+
+export interface ChildSubagentLifecycle {
+  reports: readonly SubagentReport[];
+  closed: SubagentClosed | undefined;
+  hasReminder: boolean;
+}
+
+export interface ParentSubagentLaunch extends SubagentLaunched {
+  launchedAt: string;
+}
+
+export interface ParentSubagentLedger {
+  launches: readonly ParentSubagentLaunch[];
+  cancelledChildIds: ReadonlySet<string>;
+  suspendedChildIds: ReadonlySet<string>;
+  receivedReportIds: ReadonlySet<string>;
+  deliveredReportIds: ReadonlySet<string>;
+  hasForeignLaunch: boolean;
+  hasDisownedNotice: boolean;
+}
+
+export function hasSubagentLaunchEntries(branch: readonly SessionEntry[]): boolean {
+  return branch.some(
+    (entry) => entry.type === "custom" && entry.customType === SUBAGENT_LAUNCHED_CUSTOM_TYPE,
+  );
+}
+
+export function findOwnedSubagentLaunch(
+  branch: readonly SessionEntry[],
+  ownerSessionId: string,
+  childSessionId: string,
+): ParentSubagentLaunch | undefined {
+  return collectParentLedger(branch, ownerSessionId).launches.find(
+    (launch) => launch.childSessionId === childSessionId,
+  );
+}
+
+export function collectParentLedger(
+  branch: readonly SessionEntry[],
+  ownerSessionId: string,
+): ParentSubagentLedger {
+  const launches = new Map<string, ParentSubagentLaunch>();
+  const cancelledChildIds = new Set<string>();
+  const suspendedChildIds = new Set<string>();
+  const receivedReportIds = new Set<string>();
+  const deliveredReportIds = new Set<string>();
+  let hasForeignLaunch = false;
+  let hasDisownedNotice = false;
+
+  for (const entry of branch) {
+    if (entry.type === "custom_message") {
+      if (entry.customType === SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE) {
+        const report = safeParseTypeBoxValue(SUBAGENT_REPORT_MESSAGE_SCHEMA, entry.details);
+        if (report?.writerSessionId === ownerSessionId) {
+          deliveredReportIds.add(report.reportId);
+        }
+      } else if (entry.customType === SUBAGENT_DISOWNED_MESSAGE_CUSTOM_TYPE) {
+        const notice = safeParseTypeBoxValue(SUBAGENT_DISOWNED_MESSAGE_SCHEMA, entry.details);
+        hasDisownedNotice ||= notice?.writerSessionId === ownerSessionId;
+      }
+      continue;
+    }
+    if (entry.type !== "custom") {
+      continue;
+    }
+
+    if (entry.customType === SUBAGENT_LAUNCHED_CUSTOM_TYPE) {
+      const launch = safeParseTypeBoxValue(SUBAGENT_LAUNCHED_SCHEMA, entry.data);
+      if (!launch) {
+        continue;
+      }
+      if (launch.writerSessionId !== ownerSessionId) {
+        hasForeignLaunch = true;
+        continue;
+      }
+      launches.set(launch.childSessionId, { ...launch, launchedAt: entry.timestamp });
+      cancelledChildIds.delete(launch.childSessionId);
+      suspendedChildIds.delete(launch.childSessionId);
+      continue;
+    }
+
+    if (entry.customType === SUBAGENT_CANCELLED_CUSTOM_TYPE) {
+      const cancellation = safeParseTypeBoxValue(SUBAGENT_CANCELLED_SCHEMA, entry.data);
+      if (cancellation?.writerSessionId === ownerSessionId) {
+        cancelledChildIds.add(cancellation.childSessionId);
+      }
+      continue;
+    }
+
+    if (entry.customType === SUBAGENT_SUSPENDED_CUSTOM_TYPE) {
+      const suspension = safeParseTypeBoxValue(SUBAGENT_SUSPENDED_SCHEMA, entry.data);
+      if (suspension?.writerSessionId === ownerSessionId) {
+        for (const childSessionId of suspension.childSessionIds) {
+          suspendedChildIds.add(childSessionId);
+        }
+      }
+      continue;
+    }
+
+    if (entry.customType === SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE) {
+      const receipt = safeParseTypeBoxValue(SUBAGENT_REPORT_RECEIVED_SCHEMA, entry.data);
+      if (receipt?.writerSessionId === ownerSessionId) {
+        receivedReportIds.add(receipt.reportId);
+      }
+    }
+  }
+
+  return {
+    launches: [...launches.values()],
+    cancelledChildIds,
+    suspendedChildIds,
+    receivedReportIds,
+    deliveredReportIds,
+    hasForeignLaunch,
+    hasDisownedNotice,
+  };
+}
+
+export function getChildSubagentLifecycle(branch: readonly SessionEntry[]): ChildSubagentLifecycle {
+  const reports = new Map<string, SubagentReport>();
+  let closed: SubagentClosed | undefined;
+  let hasReminder = false;
+
+  for (const entry of branch) {
+    if (entry.type === "custom_message") {
+      hasReminder ||= entry.customType === SUBAGENT_REPORT_REMINDER_MESSAGE_CUSTOM_TYPE;
+      continue;
+    }
+    if (entry.type !== "custom") {
+      continue;
+    }
+    if (entry.customType === SUBAGENT_REPORT_CUSTOM_TYPE) {
+      const report = safeParseTypeBoxValue(SUBAGENT_REPORT_SCHEMA, entry.data);
+      if (report) {
+        reports.set(report.reportId, report);
+      }
+    } else if (entry.customType === SUBAGENT_CLOSED_CUSTOM_TYPE) {
+      closed = safeParseTypeBoxValue(SUBAGENT_CLOSED_SCHEMA, entry.data) ?? closed;
+    }
+  }
+
+  return { reports: [...reports.values()], closed, hasReminder };
+}