pi-sessions 0.9.0 → 0.10.0

package/extensions/session-handoff/extract.ts

@@ -24,8 +24,9 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { freshenModel } from "../shared/model-runtime.ts";
-import { getDefaultHandoffRunsDir } from "../shared/settings.ts";
+import { getDefaultHandoffRunsDir, type HandoffSettings } from "../shared/settings.ts";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
+import { resolveModelOverride } from "./model.ts";
 
 const MAX_HANDOFF_EXTRACTION_ATTEMPTS = 3;
 const HANDOFF_EXTRACTION_RETRY_PROMPT =
@@ -88,22 +89,39 @@ export function resolveHandoffSource(
   return sessionContext;
 }
 
-export async function generateHandoffDraftFromSessionManager(
-  ctx: ExtensionContext,
-  modelRuntime: ModelRuntime,
-  sourceSessionManager: ExtensionContext["sessionManager"],
-  sourceLeafId: string,
-  goal: string,
-  thinkingLevel: ThinkingLevel | undefined,
-  persistRuns: boolean,
-  signal?: AbortSignal,
+export async function generateHandoffDraftFromSessionManager({
+  ctx,
+  modelRuntime,
+  sourceSessionManager,
+  sourceLeafId,
+  goal,
+  settings,
+  destinationThinkingLevel,
+  signal,
   requestResponse = false,
-): Promise<HandoffDraftResult | undefined> {
-  if (!ctx.model) {
-    throw new Error("No model is available for handoff.");
+}: {
+  ctx: ExtensionContext;
+  modelRuntime: ModelRuntime;
+  sourceSessionManager: ExtensionContext["sessionManager"];
+  sourceLeafId: string;
+  goal: string;
+  settings: HandoffSettings;
+  destinationThinkingLevel: ThinkingLevel | undefined;
+  signal?: AbortSignal | undefined;
+  requestResponse?: boolean | undefined;
+}): Promise<HandoffDraftResult | undefined> {
+  const modelOverride = settings.model
+    ? resolveModelOverride(modelRuntime, settings.model, settings.thinkingLevel)
+    : undefined;
+  let model = modelOverride?.model;
+  if (!model) {
+    if (!ctx.model) {
+      throw new Error("No model is available for handoff.");
+    }
+    model = freshenModel(modelRuntime, ctx.model);
   }
-
-  const model = freshenModel(modelRuntime, ctx.model);
+  const thinkingLevel =
+    modelOverride?.thinkingLevel ?? settings.thinkingLevel ?? destinationThinkingLevel;
   const sessionContext = resolveHandoffSource(sourceSessionManager, sourceLeafId);
 
   const conversationText = serializeConversation(convertToLlm(sessionContext.messages));
@@ -114,7 +132,7 @@ export async function generateHandoffDraftFromSessionManager(
     conversationText,
     goal,
     thinkingLevel,
-    persistRuns,
+    settings.persistRuns,
     signal,
   );
   if (!handoffContext) {

package/extensions/session-handoff/install.ts

@@ -214,7 +214,7 @@ export function installHandoff(
         ctx,
         deps.getModelRuntime,
         pi.getThinkingLevel(),
-        settings.handoff.persistRuns,
+        settings.handoff,
       );
     },
   };

package/extensions/session-handoff/launch-target.ts

@@ -59,7 +59,7 @@ export interface HandoffLaunchTarget {
   description?: string | undefined;
   requestResponseDefault: boolean;
   bootstrapMode: "review" | "automatic";
-  /** Subagent launches stamp their child's identity into the durable handoff record. */
+  /** Subagent launches stamp their child's identity into the child bootstrap. */
   describeSubagentChild?(input: {
     childSessionId: string;
     ownerSessionId: string;

package/extensions/session-handoff/metadata.ts

@@ -3,6 +3,7 @@ import { type Static, Type } from "typebox";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 import { HANDOFF_KICKOFF_CUSTOM_TYPE, HANDOFF_KICKOFF_DETAILS_SCHEMA } from "./kickoff.ts";
 import {
+  HANDOFF_LAUNCH_VALUE_SCHEMA,
   HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
   type HandoffLaunchValue,
   SUBAGENT_LAUNCH,
@@ -16,7 +17,7 @@ export const HANDOFF_STALE_SESSION_MESSAGE =
 export const SESSION_STARTING_MESSAGE =
   "Target session is still starting. wait for it to show up in session_search, then resend.";
 
-// A subagent's self-knowledge, stamped into the durable handoff record so the
+// A subagent's self-knowledge, stamped into its child-local bootstrap so the
 // child never opens the parent transcript to learn who it is.
 export const HANDOFF_SUBAGENT_SCHEMA = Type.Object({
   childSessionId: Type.String(),
@@ -32,18 +33,10 @@ const HANDOFF_METADATA_BASE = {
   initial_prompt: Type.String(),
 };
 
-export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Union([
-  Type.Object({
-    ...HANDOFF_METADATA_BASE,
-    launch: Type.Literal(SUBAGENT_LAUNCH),
-    subagent: HANDOFF_SUBAGENT_SCHEMA,
-  }),
-  Type.Object({
-    ...HANDOFF_METADATA_BASE,
-    launch: HANDOFF_NON_SUBAGENT_LAUNCH_SCHEMA,
-    subagent: Type.Optional(Type.Never()),
-  }),
-]);
+export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
+  ...HANDOFF_METADATA_BASE,
+  launch: HANDOFF_LAUNCH_VALUE_SCHEMA,
+});
 
 const HANDOFF_BOOTSTRAP_BASE = {
   mode: Type.Literal("generate"),
@@ -91,21 +84,14 @@ export function createHandoffSessionMetadata(
   initialPrompt: string,
   title: string,
   launch: HandoffLaunchValue,
-  subagent: HandoffSubagent | undefined,
 ): HandoffSessionMetadata {
-  const base = {
-    origin: "handoff" as const,
+  return {
+    origin: "handoff",
     goal: goal.trim(),
     title,
     initial_prompt: initialPrompt.trim(),
+    launch,
   };
-  if (launch === SUBAGENT_LAUNCH) {
-    if (!subagent) {
-      throw new Error("A subagent handoff requires a subagent identity block.");
-    }
-    return { ...base, launch, subagent };
-  }
-  return { ...base, launch };
 }
 
 export function createChildGeneratedHandoffBootstrap(options: {
@@ -195,6 +181,69 @@ export function isSessionStarting(branch: readonly SessionEntry[]): boolean {
   return findPendingHandoffBootstrap(branch)?.kind === "pending";
 }
 
+/**
+ * Folds the bootstrap lifecycle in one transcript pass. The bootstrap owns its
+ * data; kickoff and consumed entries only establish whether it started or ended.
+ */
+export function findCurrentHandoffBootstrap(
+  branch: readonly SessionEntry[],
+): HandoffBootstrap | undefined {
+  const bootstrapsById = new Map<string, HandoffBootstrap>();
+  const bootstrapIds: string[] = [];
+  const startedBootstrapIds: string[] = [];
+  const endedBootstrapIds = new Set<string>();
+  let conversationStarted = false;
+
+  for (const entry of branch) {
+    if (entry.type === "message" && entry.message.role === "user") {
+      conversationStarted = true;
+      continue;
+    }
+    if (entry.type === "custom_message" && entry.customType === HANDOFF_KICKOFF_CUSTOM_TYPE) {
+      conversationStarted = true;
+      const details = safeParseTypeBoxValue(HANDOFF_KICKOFF_DETAILS_SCHEMA, entry.details);
+      if (details?.bootstrapEntryId) {
+        startedBootstrapIds.push(details.bootstrapEntryId);
+      }
+      continue;
+    }
+    if (entry.type !== "custom") {
+      continue;
+    }
+    if (entry.customType === HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE) {
+      const bootstrap = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, entry.data);
+      if (bootstrap) {
+        bootstrapsById.set(entry.id, bootstrap);
+        bootstrapIds.push(entry.id);
+      }
+      continue;
+    }
+    if (entry.customType === HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE) {
+      const consumed = safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_CONSUMED_SCHEMA, entry.data);
+      if (consumed) {
+        endedBootstrapIds.add(consumed.bootstrapEntryId);
+      }
+    }
+  }
+
+  for (let index = startedBootstrapIds.length - 1; index >= 0; index -= 1) {
+    const bootstrap = bootstrapsById.get(startedBootstrapIds[index] ?? "");
+    if (bootstrap) {
+      return bootstrap;
+    }
+  }
+  if (conversationStarted) {
+    return undefined;
+  }
+  for (let index = bootstrapIds.length - 1; index >= 0; index -= 1) {
+    const bootstrapId = bootstrapIds[index];
+    if (bootstrapId && !endedBootstrapIds.has(bootstrapId)) {
+      return bootstrapsById.get(bootstrapId);
+    }
+  }
+  return undefined;
+}
+
 export function parseHandoffSessionMetadata(value: unknown): HandoffSessionMetadata | undefined {
   return safeParseTypeBoxValue(HANDOFF_SESSION_METADATA_SCHEMA, value);
 }

package/extensions/session-messaging/broker/spawn.ts

@@ -34,7 +34,15 @@ export async function spawnSessionMessagingBrokerIfNeeded(): Promise<void> {
       return;
     }
 
-    const brokerPath = join(dirname(fileURLToPath(import.meta.url)), "process.ts");
+    const brokerPath = join(
+      dirname(fileURLToPath(import.meta.url)),
+      "../../../dist/session-messaging/broker/process.js",
+    );
+    if (!existsSync(brokerPath)) {
+      throw new Error(
+        `Session messaging broker build not found: ${brokerPath}. Run npm install in the pi-sessions package directory.`,
+      );
+    }
     const child = spawn(process.execPath, [brokerPath], {
       detached: true,
       stdio: "ignore",
@@ -164,15 +172,12 @@ function releaseSpawnLock(): void {
 }
 
 function brokerSpawnEnv(): NodeJS.ProcessEnv {
-  // NODE_NO_WARNINGS silences Node's experimental-TypeScript warning when the
-  // broker is launched as `node process.ts`. Redundant while stdio is ignored,
-  // but cheap insurance if that changes or an older Node revives the warning.
-  const env: NodeJS.ProcessEnv = { ...process.env, NODE_NO_WARNINGS: "1" };
+  const env: NodeJS.ProcessEnv = { ...process.env };
   // process.execPath is the Pi executable. As a Bun-compiled binary it treats a
   // positional path as a file argument to the agent, not a script to run, which
   // would relaunch a full agent session and recurse. BUN_BE_BUN makes it behave
-  // as the Bun CLI and execute process.ts directly. It is set whenever Bun is the
-  // runtime (compiled binary or `bun run`) and ignored by a plain Node launch.
+  // as the Bun CLI and execute the broker. It is set whenever Bun is the runtime
+  // (compiled binary or `bun run`) and ignored by a plain Node launch.
   if (process.versions.bun) {
     env.BUN_BE_BUN = "1";
   }

package/extensions/shared/settings.ts

@@ -27,6 +27,8 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       enable: Type.Optional(Type.Boolean()),
       pickerShortcut: Type.Optional(Type.String()),
       persistRuns: Type.Optional(Type.Boolean()),
+      model: Type.Optional(Type.String()),
+      thinkingLevel: Type.Optional(Type.String()),
       deferred: Type.Optional(
         Type.Object({
           copyToClipboard: Type.Optional(Type.Boolean()),
@@ -87,6 +89,14 @@ export interface AskSettings extends AgentModelSettings {
   persistRuns: boolean;
 }
 
+export interface HandoffSettings extends AgentModelSettings {
+  pickerShortcut: KeyId;
+  persistRuns: boolean;
+  deferred: {
+    copyToClipboard: boolean;
+  };
+}
+
 export interface FeatureToggles {
   messaging: boolean;
   subagents: boolean;
@@ -102,13 +112,7 @@ export interface SessionSettings {
   subagents: {
     maxDepth: number;
   };
-  handoff: {
-    pickerShortcut: KeyId;
-    persistRuns: boolean;
-    deferred: {
-      copyToClipboard: boolean;
-    };
-  };
+  handoff: HandoffSettings;
   index: {
     path: string;
   };
@@ -222,6 +226,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       maxDepth: fileSettings.subagents?.maxDepth ?? 2,
     },
     handoff: {
+      ...resolveAgentModelSettings(fileSettings.handoff),
       pickerShortcut: normalizePickerShortcut(fileSettings.handoff?.pickerShortcut),
       persistRuns: fileSettings.handoff?.persistRuns ?? false,
       deferred: {

package/extensions/subagents/classify.ts

@@ -9,6 +9,8 @@ export type SubagentState =
   | "interrupted"
   | "unknown";
 
+const RUNNING_SUBAGENT_STATES: ReadonlySet<SubagentState> = new Set(["starting", "busy", "active"]);
+
 export interface SubagentEvidence {
   hasWindow: boolean;
   brokerLive: boolean;
@@ -20,6 +22,10 @@ export interface SubagentEvidence {
   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";

package/extensions/subagents/install.ts

@@ -1,9 +1,5 @@
-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 { ExtensionAPI, SessionTreeNode } from "@earendil-works/pi-coding-agent";
+import type { HandoffLaunchTarget } from "../session-handoff/launch-target.ts";
 import type {
   MessagingHandle,
   SendMessageRequest,
@@ -11,17 +7,14 @@ import type {
 } 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 { isTmuxInstalled } 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 {
@@ -31,10 +24,14 @@ import {
 } 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";
 
-const LINGER_POLL_MS = 1_000;
-
 interface ParentSessionState extends SubagentParentSession {
   getSessionName(): string | undefined;
   launchState: SubagentLaunchState;
@@ -44,15 +41,9 @@ interface ParentSessionState extends SubagentParentSession {
   shutdown(): void;
 }
 
-interface ChildSessionState {
-  identity: HandoffSubagent;
-  requestResponse: boolean;
-  reportsAtTurnStart: number;
-}
-
 interface CurrentSubagentSession {
   parent: ParentSessionState;
-  child?: ChildSessionState | undefined;
+  child?: SubagentChildSessionState | undefined;
 }
 
 export interface SubagentsHandle extends SessionLifecycle {
@@ -70,16 +61,9 @@ export function installSubagents(
 
   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,
@@ -87,6 +71,7 @@ export function installSubagents(
     isCurrent: isCurrentSession,
     openSession: openReconcileSession,
   });
+  const settledChildLifecycle = createSettledChildLifecycle(pi, reconciler, isCurrentSession);
   const roster = new TranscriptSubagentRoster({
     executor: pi,
     messaging: deps.messaging,
@@ -150,9 +135,9 @@ You are working as a subagent on one task delegated by a parent session. The han
   });
 
   pi.on("agent_start", (_event, ctx) => {
-    clearLinger();
+    settledChildLifecycle.cancel();
     if (current?.child) {
-      current.child.reportsAtTurnStart = countReports(ctx.sessionManager.getBranch());
+      current.child.reportsAtTurnStart = countSubagentReports(ctx.sessionManager.getBranch());
     }
   });
 
@@ -161,28 +146,11 @@ You are working as a subagent on one task delegated by a parent session. The han
     if (!session || session.parent.sessionId !== ctx.sessionManager.getSessionId()) {
       return;
     }
-    if (hasSubagentLaunchEntries(session.parent.getBranch())) {
-      await reconciler.reconcile();
-    }
+    const reconciliation = hasSubagentLaunchEntries(session.parent.getBranch())
+      ? await reconciler.reconcile()
+      : undefined;
     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;
+      await settledChildLifecycle.settle(session.parent, session.child, reconciliation);
     }
   });
 
@@ -202,11 +170,12 @@ You are working as a subagent on one task delegated by a parent session. The han
       return [createSubagentLaunchTarget(pi, parent.launchState, isCurrentSession)];
     },
     async onSessionStart(_event, ctx) {
-      clearLinger();
+      settledChildLifecycle.cancel();
       epoch += 1;
       const sessionId = ctx.sessionManager.getSessionId();
-      const identity = findSelfSubagentIdentity(ctx.sessionManager);
       const sessionManager = ctx.sessionManager;
+      const sessionStartBranch = sessionManager.getBranch();
+      const identity = findSelfSubagentIdentity(sessionId, sessionStartBranch);
       const parent: ParentSessionState = {
         sessionId,
         getSessionName: () => sessionManager.getSessionName(),
@@ -227,7 +196,7 @@ You are working as a subagent on one task delegated by a parent session. The han
               child: {
                 identity,
                 requestResponse: identity.requestResponse,
-                reportsAtTurnStart: countReports(sessionManager.getBranch()),
+                reportsAtTurnStart: countSubagentReports(sessionStartBranch),
               },
             }
           : {}),
@@ -249,7 +218,7 @@ You are working as a subagent on one task delegated by a parent session. The han
       }
     },
     async onSessionShutdown(event) {
-      clearLinger();
+      settledChildLifecycle.cancel();
       if (current && event.reason !== "reload") {
         await reconciler.suspendForShutdown();
       }
@@ -258,87 +227,3 @@ You are working as a subagent on one task delegated by a parent session. The han
     },
   };
 }
-
-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();
-}