pi-sessions 0.8.0 → 0.10.0

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/settle.ts

@@ -0,0 +1,182 @@
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { SUBAGENT_LAUNCH } from "../session-handoff/launch-target.ts";
+import { findCurrentHandoffBootstrap, type HandoffSubagent } from "../session-handoff/metadata.ts";
+import { hasAttachedTmuxClients, tmuxSessionName } from "../shared/tmux.ts";
+import { isRunningSubagentState } from "./classify.ts";
+import {
+  getChildSubagentLifecycle,
+  SUBAGENT_CLOSED_CUSTOM_TYPE,
+  SUBAGENT_REPORT_REMINDER_MESSAGE_CUSTOM_TYPE,
+} from "./ledger.ts";
+import type { ReconcileResult, SubagentReconciler } from "./reconcile.ts";
+
+const LINGER_POLL_MS = 1_000;
+const OWNED_SUBAGENT_POLL_MS = 10_000;
+
+export interface SubagentChildSessionState {
+  identity: HandoffSubagent;
+  requestResponse: boolean;
+  reportsAtTurnStart: number;
+}
+
+export interface SettledChildParentSession {
+  epoch: number;
+  getBranch(): readonly SessionEntry[];
+  hasPendingMessages(): boolean;
+  isIdle(): boolean;
+  shutdown(): void;
+}
+
+export interface SettledChildLifecycle {
+  cancel(): void;
+  settle(
+    parent: SettledChildParentSession,
+    child: SubagentChildSessionState,
+    reconciliation: ReconcileResult | undefined,
+  ): Promise<void>;
+}
+
+export function createSettledChildLifecycle(
+  pi: ExtensionAPI,
+  reconciler: SubagentReconciler,
+  isCurrentSession: (epoch: number) => boolean,
+): SettledChildLifecycle {
+  let generation = 0;
+  let timer: NodeJS.Timeout | undefined;
+
+  const cancel = (): void => {
+    generation += 1;
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  return {
+    cancel,
+    async settle(parent, child, reconciliation) {
+      cancel();
+      const currentGeneration = generation;
+      let phase: "owned-subagents" | "settle" | "observer" =
+        reconciliation && hasRunningOwnedSubagents(reconciliation) ? "owned-subagents" : "settle";
+      const canAdvance = (): boolean =>
+        generation === currentGeneration &&
+        isCurrentSession(parent.epoch) &&
+        !parent.hasPendingMessages() &&
+        parent.isIdle();
+      const schedule = (delayMs: number): void => {
+        timer = setTimeout(() => {
+          timer = undefined;
+          void advance();
+        }, delayMs);
+      };
+      const advance = async (): Promise<void> => {
+        if (!canAdvance()) {
+          return;
+        }
+
+        if (phase === "owned-subagents") {
+          const result = await reconciler.reconcile();
+          if (!canAdvance()) {
+            return;
+          }
+          if (hasRunningOwnedSubagents(result)) {
+            schedule(OWNED_SUBAGENT_POLL_MS);
+            return;
+          }
+          phase = "settle";
+        }
+
+        if (phase === "settle") {
+          if (!settleChild(pi, child, parent.getBranch())) {
+            return;
+          }
+          phase = "observer";
+        }
+
+        let attached = false;
+        try {
+          attached = await hasAttachedTmuxClients(
+            pi,
+            tmuxSessionName(child.identity.ownerSessionId),
+          );
+        } catch {
+          attached = false;
+        }
+        if (!canAdvance()) {
+          return;
+        }
+        if (!attached) {
+          parent.shutdown();
+          return;
+        }
+        schedule(LINGER_POLL_MS);
+      };
+
+      if (phase === "owned-subagents") {
+        schedule(OWNED_SUBAGENT_POLL_MS);
+        return;
+      }
+      await advance();
+    },
+  };
+}
+
+export function countSubagentReports(branch: readonly SessionEntry[]): number {
+  return getChildSubagentLifecycle(branch).reports.length;
+}
+
+export function findSelfSubagentIdentity(
+  sessionId: string,
+  branch: readonly SessionEntry[],
+): HandoffSubagent | undefined {
+  const bootstrap = findCurrentHandoffBootstrap(branch);
+  if (
+    bootstrap?.launch !== SUBAGENT_LAUNCH ||
+    bootstrap.sessionId !== sessionId ||
+    bootstrap.subagent.childSessionId !== sessionId
+  ) {
+    return undefined;
+  }
+  return bootstrap.subagent;
+}
+
+function hasRunningOwnedSubagents(result: ReconcileResult): boolean {
+  return [...result.states.values()].some(isRunningSubagentState);
+}
+
+function settleChild(
+  pi: ExtensionAPI,
+  child: SubagentChildSessionState,
+  branch: readonly SessionEntry[],
+): boolean {
+  const lifecycle = getChildSubagentLifecycle(branch);
+  const reports = lifecycle.reports.length;
+  if (reports > child.reportsAtTurnStart) {
+    return true;
+  }
+  if (!child.requestResponse) {
+    pi.appendEntry(SUBAGENT_CLOSED_CUSTOM_TYPE, {
+      reason: "no_response_expected",
+    });
+    return true;
+  }
+
+  if (lifecycle.hasReminder) {
+    pi.appendEntry(SUBAGENT_CLOSED_CUSTOM_TYPE, {
+      reason: "no_report_after_reminder",
+    });
+    return true;
+  }
+
+  pi.sendMessage(
+    {
+      customType: SUBAGENT_REPORT_REMINDER_MESSAGE_CUSTOM_TYPE,
+      content:
+        "[system] Your delegated turn settled without a task report. Call submit_task_report now with done, blocked, or incomplete status.",
+      display: true,
+    },
+    { triggerTurn: true },
+  );
+  return false;
+}

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.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
@@ -19,37 +19,35 @@
     "node": ">=24 <26"
   },
   "files": [
+    "dist",
     "extensions",
     "images"
   ],
   "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": {
+    "build:broker": "tsc --project tsconfig.broker.json",
     "lint": "biome check .",
     "format": "biome format --write .",
     "typecheck": "tsc --noEmit",
+    "pretest": "npm run build:broker",
     "test": "vitest run",
-    "check": "biome check . && tsc --noEmit && vitest run",
-    "prepare": "husky || true"
+    "check": "biome check . && tsc --noEmit && npm test",
+    "prepare": "npm run build:broker && npm run prepare:husky",
+    "prepare:husky": "husky || true"
   },
   "dependencies": {
     "typebox": "^1.1.38"
   },
   "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 +55,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"