pi-sessions 0.7.2 → 0.9.0

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");
+}

package/extensions/subagents/roster.ts

@@ -0,0 +1,262 @@
+import {
+  type SessionEntry,
+  SessionManager,
+  type SessionTreeNode,
+} from "@earendil-works/pi-coding-agent";
+import { isSessionStarting } from "../session-handoff/metadata.ts";
+import { listTmuxWindows, type TmuxExecutor, tmuxSessionName } from "../shared/tmux.ts";
+import { classifySubagent, type SubagentState } from "./classify.ts";
+import {
+  type ChildSubagentLifecycle,
+  collectParentLedger,
+  getChildSubagentLifecycle,
+  type ParentSubagentLaunch,
+  type ParentSubagentLedger,
+} from "./ledger.ts";
+import type { ReconcileResult } from "./reconcile.ts";
+
+export type SubagentRelationScope = "branch" | "tree";
+
+export interface SubagentRosterEntry {
+  sessionId: string;
+  sessionFile: string;
+  ownerSessionId: string;
+  ownerTitle: string;
+  ownerIsCurrentSession: boolean;
+  title: string;
+  goal: string;
+  model?: string | undefined;
+  cwd: string;
+  resumeCommand: string;
+  launchedAt: string;
+  depth: number;
+  state: SubagentState;
+  onActiveBranch: boolean;
+  managedLive: boolean;
+  tmuxWindowId?: string | undefined;
+}
+
+export interface SubagentRosterResult {
+  entries: readonly SubagentRosterEntry[];
+  total: number;
+}
+
+export interface SubagentRoster {
+  resolve(scope: SubagentRelationScope): Promise<SubagentRosterResult>;
+}
+
+interface RosterSession {
+  sessionId: string;
+  getSessionName(): string | undefined;
+  getBranch(fromId?: string): readonly SessionEntry[];
+  getTree(): readonly SessionTreeNode[];
+}
+
+interface RosterParentSession extends RosterSession {
+  epoch: number;
+}
+
+interface RosterDependencies {
+  executor: TmuxExecutor;
+  messaging: { listSessions(): Promise<string[]> };
+  getParent(): RosterParentSession | undefined;
+  reconcile(): Promise<ReconcileResult>;
+  openSession(path: string): RosterSession;
+}
+
+interface TraversedSubagent {
+  launch: ParentSubagentLaunch;
+  ownerSessionId: string;
+  ownerTitle: string;
+  ownerIsCurrentSession: boolean;
+  ownerActiveLedger: ParentSubagentLedger;
+  onActiveBranch: boolean;
+  lifecycle: ChildSubagentLifecycle | undefined;
+  awaitingKickoff: boolean;
+}
+
+export class TranscriptSubagentRoster implements SubagentRoster {
+  constructor(private readonly deps: RosterDependencies) {}
+
+  async resolve(scope: SubagentRelationScope): Promise<SubagentRosterResult> {
+    const parent = this.deps.getParent();
+    if (!parent) {
+      throw new Error("Subagent roster is unavailable before session start.");
+    }
+
+    const reconciliation = await this.deps.reconcile();
+    const traversed = this.traverse(parent, scope);
+    const brokerLive = new Set(await this.deps.messaging.listSessions());
+
+    const ownerSessionIds = [...new Set(traversed.map((child) => child.ownerSessionId))];
+    const windowsByOwner = new Map(
+      await Promise.all(
+        ownerSessionIds.map(async (ownerSessionId) => {
+          const windows = await listTmuxWindows(
+            this.deps.executor,
+            tmuxSessionName(ownerSessionId),
+          );
+          return [
+            ownerSessionId,
+            new Map(windows.map((window) => [window.piSessionId, window])),
+          ] as const;
+        }),
+      ),
+    );
+
+    const entries = traversed.map((child): SubagentRosterEntry => {
+      const childSessionId = child.launch.childSessionId;
+      const window = windowsByOwner.get(child.ownerSessionId)?.get(childSessionId);
+      const hasWindow = window !== undefined;
+      const isBrokerLive = brokerLive.has(childSessionId);
+      const activeLedger = child.ownerActiveLedger;
+      const lifecycle = child.lifecycle;
+      const state =
+        reconciliation.states.get(childSessionId) ??
+        classifySubagent({
+          hasWindow,
+          brokerLive: isBrokerLive,
+          hasRegistered: reconciliation.registered.has(childSessionId),
+          awaitingKickoff: child.awaitingKickoff,
+          cancelled: activeLedger.cancelledChildIds.has(childSessionId),
+          suspended: activeLedger.suspendedChildIds.has(childSessionId),
+          hasReportOrClosure: Boolean(lifecycle?.reports.length || lifecycle?.closed),
+          childReadable: lifecycle !== undefined,
+        });
+
+      return {
+        sessionId: childSessionId,
+        sessionFile: child.launch.childSessionFile,
+        ownerSessionId: child.ownerSessionId,
+        ownerTitle: child.ownerTitle,
+        ownerIsCurrentSession: child.ownerIsCurrentSession,
+        title: child.launch.title,
+        goal: child.launch.goal,
+        ...(child.launch.model ? { model: child.launch.model } : {}),
+        cwd: child.launch.cwd,
+        resumeCommand: child.launch.resumeCommand,
+        launchedAt: child.launch.launchedAt,
+        depth: child.launch.depth,
+        state,
+        onActiveBranch: child.onActiveBranch,
+        managedLive: hasWindow || isBrokerLive,
+        ...(window ? { tmuxWindowId: window.windowId } : {}),
+      };
+    });
+
+    return { entries, total: entries.length };
+  }
+
+  private traverse(root: RosterSession, scope: SubagentRelationScope): TraversedSubagent[] {
+    const results = new Map<string, TraversedSubagent>();
+    const openedChildren = new Map<string, RosterSession | undefined>();
+    const visitedOwners = new Set<string>();
+    const queue: RosterSession[] = [root];
+
+    while (queue.length > 0) {
+      const owner = queue.shift();
+      if (!owner || visitedOwners.has(owner.sessionId)) {
+        continue;
+      }
+      visitedOwners.add(owner.sessionId);
+
+      const activeBranch = owner.getBranch();
+      const activeLedger = collectParentLedger(activeBranch, owner.sessionId);
+      const activeChildIds = new Set(activeLedger.launches.map((launch) => launch.childSessionId));
+      const launches =
+        scope === "branch" ? activeLedger.launches : collectTreeLaunches(owner, owner.sessionId);
+
+      for (const launch of launches) {
+        let child: RosterSession | undefined;
+        let lifecycle: ChildSubagentLifecycle | undefined;
+        let awaitingKickoff = false;
+        try {
+          if (openedChildren.has(launch.childSessionId)) {
+            child = openedChildren.get(launch.childSessionId);
+          } else {
+            child = this.deps.openSession(launch.childSessionFile);
+            if (child.sessionId !== launch.childSessionId) {
+              child = undefined;
+            }
+            openedChildren.set(launch.childSessionId, child);
+          }
+
+          const childBranch = child?.getBranch();
+          if (!childBranch) {
+            child = undefined;
+          } else {
+            lifecycle = getChildSubagentLifecycle(childBranch);
+            awaitingKickoff = isSessionStarting(childBranch);
+          }
+        } catch {
+          child = undefined;
+          openedChildren.set(launch.childSessionId, undefined);
+        }
+
+        const existing = results.get(launch.childSessionId);
+        const candidate: TraversedSubagent = {
+          launch,
+          ownerSessionId: owner.sessionId,
+          ownerTitle: owner.getSessionName()?.trim() || "Untitled session",
+          ownerIsCurrentSession: owner.sessionId === root.sessionId,
+          ownerActiveLedger: activeLedger,
+          onActiveBranch: activeChildIds.has(launch.childSessionId),
+          lifecycle,
+          awaitingKickoff,
+        };
+        if (!existing || candidate.launch.depth < existing.launch.depth) {
+          results.set(launch.childSessionId, candidate);
+        }
+        if (child && !visitedOwners.has(child.sessionId)) {
+          queue.push(child);
+        }
+      }
+    }
+
+    return [...results.values()];
+  }
+}
+
+export function openRosterSession(path: string): RosterSession {
+  const manager = SessionManager.open(path);
+  return {
+    sessionId: manager.getSessionId(),
+    getSessionName: () => manager.getSessionName(),
+    getBranch: (fromId) => manager.getBranch(fromId),
+    getTree: () => manager.getTree(),
+  };
+}
+
+function collectTreeLaunches(
+  session: RosterSession,
+  ownerSessionId: string,
+): ParentSubagentLaunch[] {
+  const launches = new Map<string, ParentSubagentLaunch>();
+  for (const leafId of collectLeafIds(session.getTree())) {
+    const ledger = collectParentLedger(session.getBranch(leafId), ownerSessionId);
+    for (const launch of ledger.launches) {
+      const existing = launches.get(launch.childSessionId);
+      if (!existing || launch.launchedAt > existing.launchedAt) {
+        launches.set(launch.childSessionId, launch);
+      }
+    }
+  }
+  return [...launches.values()];
+}
+
+function collectLeafIds(roots: readonly SessionTreeNode[]): string[] {
+  const leafIds: string[] = [];
+  const stack = [...roots];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) {
+      continue;
+    }
+    if (node.children.length === 0) {
+      leafIds.push(node.entry.id);
+    } else {
+      stack.push(...node.children);
+    }
+  }
+  return leafIds;
+}

package/extensions/subagents/wake.ts

@@ -0,0 +1,173 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { SendMessageRequest, SendMessageResult } from "../session-messaging/install.ts";
+import {
+  createTmuxWindow,
+  killTmuxWindow,
+  listTmuxWindows,
+  type TmuxExecutor,
+  tmuxSessionName,
+} from "../shared/tmux.ts";
+import { findOwnedSubagentLaunch, type SubagentLaunched } from "./ledger.ts";
+
+const SESSION_READY_TIMEOUT_MS = 30_000;
+
+export interface WakeParentSession {
+  sessionId: string;
+  epoch: number;
+  getBranch(): readonly SessionEntry[];
+}
+
+interface WakeMessaging {
+  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  listSessions(): Promise<string[]>;
+  waitForSession(sessionId: string, timeoutMs: number): Promise<boolean>;
+}
+
+export interface SubagentMessageRouterOptions {
+  readyTimeoutMs?: number;
+  onMaterialize?(launch: SubagentLaunched): void;
+  afterOwnedSend?(): Promise<void> | void;
+}
+
+export class SubagentMessageRouter {
+  private readonly wakeBySessionId = new Map<string, Promise<void>>();
+
+  constructor(
+    private readonly executor: TmuxExecutor,
+    private readonly messaging: WakeMessaging,
+    private readonly getParent: () => WakeParentSession | undefined,
+    private readonly isCurrent: (epoch: number) => boolean,
+    private readonly options: SubagentMessageRouterOptions = {},
+  ) {}
+
+  async sendMessage(request: SendMessageRequest): Promise<SendMessageResult> {
+    let failedLiveSend: SendMessageResult | undefined;
+    if (await this.isLive(request.target)) {
+      const result = await this.messaging.sendMessage(request);
+      if (result.delivered || !isTargetDeparture(result)) {
+        return result;
+      }
+      failedLiveSend = result;
+    }
+
+    const parent = this.getParent();
+    const launch = parent
+      ? findOwnedSubagentLaunch(parent.getBranch(), parent.sessionId, request.target)
+      : undefined;
+    if (!parent || !launch) {
+      return failedLiveSend ?? this.messaging.sendMessage(request);
+    }
+
+    try {
+      await this.wake(parent, launch);
+      const result = await this.sendOwned(parent, request);
+      if (result.delivered || !isTargetDeparture(result)) {
+        return result;
+      }
+
+      await this.wake(parent, launch);
+      return this.sendOwned(parent, request);
+    } finally {
+      await this.options.afterOwnedSend?.();
+    }
+  }
+
+  private async wake(parent: WakeParentSession, launch: SubagentLaunched): Promise<void> {
+    const existing = this.wakeBySessionId.get(launch.childSessionId);
+    if (existing) {
+      return existing;
+    }
+
+    const wake = this.ensureReady(parent, launch).finally(() => {
+      if (this.wakeBySessionId.get(launch.childSessionId) === wake) {
+        this.wakeBySessionId.delete(launch.childSessionId);
+      }
+    });
+    this.wakeBySessionId.set(launch.childSessionId, wake);
+    return wake;
+  }
+
+  private async ensureReady(parent: WakeParentSession, launch: SubagentLaunched): Promise<void> {
+    if (await this.isLive(launch.childSessionId)) {
+      return;
+    }
+
+    const tmuxSession = tmuxSessionName(parent.sessionId);
+    const hasWindow = (await listTmuxWindows(this.executor, tmuxSession)).some(
+      (window) => window.piSessionId === launch.childSessionId,
+    );
+
+    if (!hasWindow) {
+      await this.createWindow(parent, launch, tmuxSession);
+    }
+    if (
+      await this.messaging.waitForSession(
+        launch.childSessionId,
+        this.options.readyTimeoutMs ?? SESSION_READY_TIMEOUT_MS,
+      )
+    ) {
+      return;
+    }
+
+    this.requireCurrent(parent);
+    const killed = await killTmuxWindow(this.executor, tmuxSession, launch.childSessionId);
+    if (!killed) {
+      throw new Error(
+        `Subagent ${launch.childSessionId} did not register and its stale tmux window could not be stopped.`,
+      );
+    }
+
+    await this.createWindow(parent, launch, tmuxSession);
+    if (
+      !(await this.messaging.waitForSession(
+        launch.childSessionId,
+        this.options.readyTimeoutMs ?? SESSION_READY_TIMEOUT_MS,
+      ))
+    ) {
+      throw new Error(
+        `Subagent ${launch.childSessionId} was restarted but did not register for messaging.`,
+      );
+    }
+  }
+
+  private async createWindow(
+    parent: WakeParentSession,
+    launch: SubagentLaunched,
+    tmuxSession: string,
+  ): Promise<void> {
+    if (await this.isLive(launch.childSessionId)) {
+      return;
+    }
+    this.requireCurrent(parent);
+    this.options.onMaterialize?.(launch);
+    await createTmuxWindow(this.executor, {
+      tmuxSession,
+      name: launch.title,
+      cwd: launch.cwd,
+      command: launch.resumeCommand,
+      piSessionId: launch.childSessionId,
+    });
+  }
+
+  private sendOwned(
+    parent: WakeParentSession,
+    request: SendMessageRequest,
+  ): Promise<SendMessageResult> {
+    this.requireCurrent(parent);
+    return this.messaging.sendMessage(request);
+  }
+
+  private async isLive(sessionId: string): Promise<boolean> {
+    return (await this.messaging.listSessions()).includes(sessionId);
+  }
+
+  private requireCurrent(parent: WakeParentSession): void {
+    if (!this.isCurrent(parent.epoch)) {
+      throw new Error("The parent session changed while waking its subagent.");
+    }
+  }
+}
+
+function isTargetDeparture(result: SendMessageResult): boolean {
+  return !result.delivered && (result.reason === "no_session" || result.reason === "disconnected");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -24,13 +24,7 @@
   ],
   "pi": {
     "extensions": [
-      "./extensions/session-ask.ts",
-      "./extensions/session-auto-title.ts",
-      "./extensions/session-handoff.ts",
-      "./extensions/session-hooks.ts",
-      "./extensions/session-index.ts",
-      "./extensions/session-messaging.ts",
-      "./extensions/session-search.ts"
+      "./extensions/pi-sessions.ts"
     ]
   },
   "scripts": {
@@ -46,10 +40,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.80.2",
-    "@earendil-works/pi-ai": "^0.80.2",
-    "@earendil-works/pi-coding-agent": "^0.80.2",
-    "@earendil-works/pi-tui": "^0.80.2",
+    "@earendil-works/pi-agent-core": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
     "@types/node": "^25.6.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.3",
@@ -57,10 +51,10 @@
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.80.2",
-    "@earendil-works/pi-ai": ">=0.80.2",
-    "@earendil-works/pi-coding-agent": ">=0.80.2",
-    "@earendil-works/pi-tui": ">=0.80.2"
+    "@earendil-works/pi-agent-core": ">=0.80.10",
+    "@earendil-works/pi-ai": ">=0.80.10",
+    "@earendil-works/pi-coding-agent": ">=0.80.10",
+    "@earendil-works/pi-tui": ">=0.80.10"
   },
   "lint-staged": {
     "*.{js,cjs,mjs,jsx,ts,tsx,json,jsonc}": "biome check --write --no-errors-on-unmatched"