pi-sessions 0.7.2 → 0.9.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,52 @@
+export type SubagentState =
+  | "starting"
+  | "busy"
+  | "active"
+  | "completed"
+  | "stopping"
+  | "stopped"
+  | "suspended"
+  | "interrupted"
+  | "unknown";
+
+export interface SubagentEvidence {
+  hasWindow: boolean;
+  brokerLive: boolean;
+  hasRegistered: boolean;
+  awaitingKickoff: boolean;
+  cancelled: boolean;
+  suspended: boolean;
+  hasReportOrClosure: boolean;
+  childReadable: boolean;
+}
+
+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,344 @@
+import type { ExtensionAPI, SessionEntry, SessionTreeNode } from "@earendil-works/pi-coding-agent";
+import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "../session-handoff/launch-target.ts";
+import {
+  getHandoffMetadataFromEntries,
+  type HandoffSubagent,
+} from "../session-handoff/metadata.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 { hasAttachedTmuxClients, isTmuxInstalled, tmuxSessionName } from "../shared/tmux.ts";
+import { SubagentCancellationRouter, type SubagentCancelResult } from "./cancel.ts";
+import { createSubagentLaunchTarget, type SubagentLaunchState } from "./launch-target.ts";
+import {
+  getChildSubagentLifecycle,
+  hasSubagentLaunchEntries,
+  SUBAGENT_CLOSED_CUSTOM_TYPE,
+  SUBAGENT_LAUNCHED_CUSTOM_TYPE,
+  SUBAGENT_REPORT_MESSAGE_CUSTOM_TYPE,
+  SUBAGENT_REPORT_RECEIVED_CUSTOM_TYPE,
+  SUBAGENT_REPORT_REMINDER_MESSAGE_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 { SubagentMessageRouter } from "./wake.ts";
+
+const LINGER_POLL_MS = 1_000;
+
+interface ParentSessionState extends SubagentParentSession {
+  getSessionName(): string | undefined;
+  launchState: SubagentLaunchState;
+  tmuxInstalled: boolean;
+  getTree(): SessionTreeNode[];
+  hasPendingMessages(): boolean;
+  shutdown(): void;
+}
+
+interface ChildSessionState {
+  identity: HandoffSubagent;
+  requestResponse: boolean;
+  reportsAtTurnStart: number;
+}
+
+interface CurrentSubagentSession {
+  parent: ParentSessionState;
+  child?: ChildSessionState | 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;
+  let lingerTimer: NodeJS.Timeout | undefined;
+
+  const isCurrentSession = (candidateEpoch: number): boolean =>
+    current?.parent.epoch === candidateEpoch;
+  const clearLinger = (): void => {
+    if (lingerTimer) {
+      clearTimeout(lingerTimer);
+      lingerTimer = undefined;
+    }
+  };
+  const reconciler = new SubagentReconciler({
+    executor: pi,
+    messaging: deps.messaging,
+    getParent: () => current?.parent,
+    isCurrent: isCurrentSession,
+    openSession: openReconcileSession,
+  });
+  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) => {
+    clearLinger();
+    if (current?.child) {
+      current.child.reportsAtTurnStart = countReports(ctx.sessionManager.getBranch());
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    const session = current;
+    if (!session || session.parent.sessionId !== ctx.sessionManager.getSessionId()) {
+      return;
+    }
+    if (hasSubagentLaunchEntries(session.parent.getBranch())) {
+      await reconciler.reconcile();
+    }
+    if (session.child) {
+      if (ctx.hasPendingMessages()) {
+        return;
+      }
+      const shouldExit = settleChild(pi, session.child, ctx.sessionManager.getBranch());
+      if (!shouldExit) {
+        return;
+      }
+      await exitWhenUnobserved(
+        pi,
+        session.parent,
+        session.child.identity,
+        isCurrentSession,
+        (timer) => {
+          clearLinger();
+          lingerTimer = timer;
+        },
+      );
+      return;
+    }
+  });
+
+  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) {
+      clearLinger();
+      epoch += 1;
+      const sessionId = ctx.sessionManager.getSessionId();
+      const identity = findSelfSubagentIdentity(ctx.sessionManager);
+      const sessionManager = ctx.sessionManager;
+      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: countReports(sessionManager.getBranch()),
+              },
+            }
+          : {}),
+      };
+      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) {
+      clearLinger();
+      if (current && event.reason !== "reload") {
+        await reconciler.suspendForShutdown();
+      }
+      epoch += 1;
+      current = undefined;
+    },
+  };
+}
+
+function settleChild(
+  pi: ExtensionAPI,
+  child: ChildSessionState,
+  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;
+}
+
+function countReports(branch: readonly SessionEntry[]): number {
+  return getChildSubagentLifecycle(branch).reports.length;
+}
+
+function findSelfSubagentIdentity(session: {
+  getSessionId(): string;
+  getBranch(): readonly SessionEntry[];
+}): HandoffSubagent | undefined {
+  const metadata = getHandoffMetadataFromEntries(session.getBranch());
+  if (metadata?.launch !== SUBAGENT_LAUNCH) {
+    return undefined;
+  }
+  return metadata.subagent.childSessionId === session.getSessionId()
+    ? metadata.subagent
+    : undefined;
+}
+
+async function exitWhenUnobserved(
+  executor: ExtensionAPI,
+  parent: ParentSessionState,
+  identity: HandoffSubagent,
+  isCurrentSession: (epoch: number) => boolean,
+  setTimer: (timer: NodeJS.Timeout) => void,
+): Promise<void> {
+  const check = async (): Promise<void> => {
+    if (!isCurrentSession(parent.epoch) || parent.hasPendingMessages() || !parent.isIdle()) {
+      return;
+    }
+
+    let attached = false;
+    try {
+      attached = await hasAttachedTmuxClients(executor, tmuxSessionName(identity.ownerSessionId));
+    } catch {
+      attached = false;
+    }
+    if (!isCurrentSession(parent.epoch)) {
+      return;
+    }
+    if (!attached) {
+      parent.shutdown();
+      return;
+    }
+    setTimer(setTimeout(() => void check(), LINGER_POLL_MS));
+  };
+
+  await check();
+}

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