pi-sessions 0.8.0 → 0.10.0

package/extensions/session-handoff/bootstrap.ts

@@ -0,0 +1,172 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ModelRuntimeProvider } from "../shared/model-runtime.ts";
+import type { HandoffSettings } from "../shared/settings.ts";
+import { generateHandoffDraftFromSessionManager } from "./extract.ts";
+import { buildHandoffKickoffMessage, buildHandoffKickoffSource } from "./kickoff.ts";
+import {
+  type ChildGeneratedHandoffBootstrap,
+  createHandoffSessionMetadata,
+  findPendingHandoffBootstrap,
+  getHandoffMetadataFromEntries,
+  HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE,
+  HANDOFF_METADATA_CUSTOM_TYPE,
+  HANDOFF_STALE_SESSION_MESSAGE,
+  type HandoffBootstrapConsumedReason,
+  hasStartedConversation,
+} from "./metadata.ts";
+import { reviewHandoffDraftForSend } from "./review.ts";
+import { formatHandoffError, runHandoffTaskWithLoader } from "./ui.ts";
+
+export async function consumePendingHandoffBootstrap(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  getModelRuntime: ModelRuntimeProvider,
+  destinationThinkingLevel: ThinkingLevel | undefined,
+  handoffSettings: HandoffSettings,
+): Promise<void> {
+  const scan = findPendingHandoffBootstrap(ctx.sessionManager.getBranch());
+  if (!scan) {
+    return;
+  }
+
+  const consumeBootstrap = (reason: HandoffBootstrapConsumedReason): void => {
+    pi.appendEntry(HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE, {
+      bootstrapEntryId: scan.entryId,
+      reason,
+    });
+  };
+
+  if (scan.kind === "invalid") {
+    consumeBootstrap("invalid");
+    return;
+  }
+
+  const bootstrap = scan.bootstrap;
+  if (bootstrap.sessionId !== ctx.sessionManager.getSessionId()) {
+    consumeBootstrap("invalid");
+    return;
+  }
+
+  await startChildGeneratedHandoff(
+    pi,
+    ctx,
+    bootstrap,
+    scan.entryId,
+    consumeBootstrap,
+    getModelRuntime,
+    destinationThinkingLevel,
+    handoffSettings,
+  );
+}
+
+async function startChildGeneratedHandoff(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  bootstrap: ChildGeneratedHandoffBootstrap,
+  bootstrapEntryId: string,
+  consumeBootstrap: (reason: HandoffBootstrapConsumedReason) => void,
+  getModelRuntime: ModelRuntimeProvider,
+  destinationThinkingLevel: ThinkingLevel | undefined,
+  handoffSettings: HandoffSettings,
+): Promise<void> {
+  const entries = ctx.sessionManager.getEntries();
+  if (hasStartedConversation(entries)) {
+    consumeBootstrap("stale");
+    if (ctx.hasUI) {
+      ctx.ui.notify(HANDOFF_STALE_SESSION_MESSAGE, "error");
+    }
+    return;
+  }
+
+  if (!ctx.hasUI) {
+    if (bootstrap.bootstrapMode === "automatic") {
+      ctx.shutdown();
+    }
+    return;
+  }
+
+  // A thrown error leaves the bootstrap pending so the next resume offers
+  // review again; explicit user decisions consume it.
+  try {
+    const sourceSessionManager = SessionManager.open(bootstrap.parentSessionFile);
+    const modelRuntime = await getModelRuntime(ctx.modelRegistry);
+    const generatedDraft = await runHandoffTaskWithLoader(
+      ctx,
+      "Generating handoff draft...",
+      async (signal: AbortSignal) =>
+        generateHandoffDraftFromSessionManager({
+          ctx,
+          modelRuntime,
+          sourceSessionManager,
+          sourceLeafId: bootstrap.sourceLeafId,
+          goal: bootstrap.goal,
+          settings: handoffSettings,
+          destinationThinkingLevel,
+          signal,
+          requestResponse: bootstrap.requestResponse,
+        }),
+    );
+    if (!generatedDraft) {
+      consumeBootstrap("cancelled");
+      ctx.ui.notify("Cancelled", "info");
+      return;
+    }
+
+    if (generatedDraft.debugSessionPath) {
+      ctx.ui.notify(
+        `Handoff extraction session saved to ${generatedDraft.debugSessionPath}`,
+        "info",
+      );
+    }
+
+    let prompt = generatedDraft.draft;
+    if (bootstrap.bootstrapMode === "review") {
+      const review = await reviewHandoffDraftForSend(ctx.ui, generatedDraft.draft);
+      if (review.action === "prefill") {
+        consumeBootstrap("prefilled");
+        ctx.ui.setEditorText(review.prompt);
+        ctx.ui.notify("Handoff prompt ready in editor.", "info");
+        return;
+      }
+      if (review.action === "cancel") {
+        consumeBootstrap("cancelled");
+        ctx.ui.notify("Cancelled", "info");
+        return;
+      }
+      prompt = review.prompt;
+    }
+
+    // The tool-provided bootstrap title is authoritative; extraction does not
+    // replace it with a second generated title.
+    const metadata = createHandoffSessionMetadata(
+      bootstrap.goal,
+      prompt,
+      bootstrap.title,
+      bootstrap.launch,
+    );
+    if (!getHandoffMetadataFromEntries(ctx.sessionManager.getEntries())) {
+      pi.appendEntry(HANDOFF_METADATA_CUSTOM_TYPE, metadata);
+    }
+    pi.setSessionName(metadata.title);
+    const sourceSessionName = sourceSessionManager.getSessionName();
+    pi.sendMessage(
+      buildHandoffKickoffMessage({
+        prompt,
+        title: metadata.title,
+        source: buildHandoffKickoffSource({
+          sessionId: sourceSessionManager.getSessionId(),
+          ...(sourceSessionName ? { sessionName: sourceSessionName } : {}),
+        }),
+        bootstrapEntryId,
+      }),
+      { triggerTurn: true },
+    );
+  } catch (error) {
+    ctx.ui.notify(formatHandoffError(error), "error");
+    if (bootstrap.bootstrapMode === "automatic") {
+      ctx.shutdown();
+    }
+  }
+}

package/extensions/session-handoff/extract.ts

@@ -7,7 +7,11 @@ import type {
   ThinkingContent,
   ToolCall,
 } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionContext,
+  ModelRuntime,
+  SessionContext,
+} from "@earendil-works/pi-coding-agent";
 import {
   buildSessionContext,
   convertToLlm,
@@ -19,60 +23,44 @@ import {
   serializeConversation,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
+import { freshenModel } from "../shared/model-runtime.ts";
+import { getDefaultHandoffRunsDir, type HandoffSettings } from "../shared/settings.ts";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
+import { resolveModelOverride } from "./model.ts";
 
-const MAX_RELEVANT_FILES = 12;
-const MAX_OPEN_QUESTIONS = 8;
-const MAX_HANDOFF_TITLE_LENGTH = 64;
+const MAX_HANDOFF_EXTRACTION_ATTEMPTS = 3;
+const HANDOFF_EXTRACTION_RETRY_PROMPT =
+  "You did not call create_handoff_context. Call it exactly once now with the completed briefing.";
 
-const HANDOFF_SYSTEM_PROMPT = `You extract context for a deliberate session handoff.
+const HANDOFF_SYSTEM_PROMPT = `You extract supporting context for a deliberate session handoff. You are preparing a briefing for a new destination session from a snapshot of its ongoing parent session.
 
-You must call create_handoff_context exactly once.
+The Handoff Goal is the authoritative and exclusive task of the destination session, and will be directly passed into that session. Do not rewrite, expand the scope of, or replace the goal.
 
-Rules:
-- Extract only context that is relevant to the next task.
-- Keep the summary compact and concrete.
-- Prefer workspace-relative file paths when possible.
-- title must be a short session title for the new handoff thread, 64 characters or less, without prefixes like "Handoff:" or otherwise referencing the current thread.
-- nextTask must be the concrete next action for the new session.
-- openQuestions should contain only unresolved items that materially affect the next task.
-- If there are no meaningful open questions, omit openQuestions entirely.
-- Do not write the final handoff prompt yourself.`;
+The parent snapshot is reference material used only to provide evidence that supports that goal. Do not continue the parent conversation, respond to any questions in it, or carry forward parent tasks, unresolved work, instructions, or plans outside the goal. Only identify relevant context, files, constraints, and known decisions for the Handoff Goal.
+
+The parent may be coordinating several parallel sessions. Do not include any references to those other sessions.`;
 
 const HANDOFF_EXTRACTION_PARAMETERS = Type.Object({
-  title: Type.String({
-    description: "Short display title for the new handoff session.",
-  }),
   summary: Type.String({
-    description: "Only the context relevant to the next task.",
+    description:
+      "Context from the parent task that is directly relevant to the Handoff Goal. Include only details that further support the goal.",
   }),
   relevantFiles: Type.Array(Type.String(), {
-    description: "Relevant workspace-relative file paths when possible.",
-  }),
-  nextTask: Type.String({
-    description: "The concrete next task for the new session.",
+    description: "Relevant file paths.",
   }),
   openQuestions: Type.Optional(
     Type.Array(Type.String(), {
-      description: "Open questions that matter to the next task. Omit when there are none.",
+      description:
+        "Unresolved questions that materially affect the destination task. Omit when there are none.",
     }),
   ),
 });
 
 type HandoffExtractionArgs = Static<typeof HANDOFF_EXTRACTION_PARAMETERS>;
-type RequiredHandoffExtractionArgs = Static<typeof REQUIRED_HANDOFF_EXTRACTION_PARAMETERS>;
-
-const REQUIRED_HANDOFF_EXTRACTION_PARAMETERS = Type.Object({
-  title: HANDOFF_EXTRACTION_PARAMETERS.properties.title,
-  summary: HANDOFF_EXTRACTION_PARAMETERS.properties.summary,
-  nextTask: HANDOFF_EXTRACTION_PARAMETERS.properties.nextTask,
-});
 
 export interface HandoffContext {
-  title: string;
   summary: string;
   relevantFiles: string[];
-  nextTask: string;
   openQuestions: string[];
 }
 
@@ -81,57 +69,70 @@ export interface HandoffDraftResult {
   context: HandoffContext;
   sessionId: string;
   sessionPath?: string | undefined;
+  debugSessionPath?: string | undefined;
 }
 
-export async function generateHandoffDraft(
-  ctx: ExtensionContext,
-  goal: string,
-  thinkingLevel: ThinkingLevel | undefined,
-  signal?: AbortSignal,
-  requestResponse = false,
-): Promise<HandoffDraftResult | undefined> {
-  if (!ctx.model) {
-    throw new Error("No model is available for handoff.");
+/** Validate an anchored source branch and return its built context. Throws a user-facing Error otherwise. */
+export function resolveHandoffSource(
+  sessionManager: ExtensionContext["sessionManager"],
+  sourceLeafId: string,
+): SessionContext {
+  if (!sessionManager.getEntry(sourceLeafId)) {
+    throw new Error(`Handoff source snapshot entry ${sourceLeafId} was not found.`);
   }
 
-  return generateHandoffDraftFromSessionManager(
-    ctx,
-    ctx.sessionManager,
-    goal,
-    thinkingLevel,
-    signal,
-    requestResponse,
-  );
+  const sessionContext = buildSessionContext(sessionManager.getEntries(), sourceLeafId);
+  if (sessionContext.messages.length === 0) {
+    throw new Error("No conversation to hand off.");
+  }
+
+  return sessionContext;
 }
 
-export async function generateHandoffDraftFromSessionManager(
-  ctx: ExtensionContext,
-  sourceSessionManager: ExtensionContext["sessionManager"],
-  goal: string,
-  thinkingLevel: ThinkingLevel | undefined,
-  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.");
-  }
-
-  const model = ctx.model;
-  const sessionContext = buildSessionContext(
-    sourceSessionManager.getEntries(),
-    sourceSessionManager.getLeafId(),
-  );
-  if (sessionContext.messages.length === 0) {
-    throw new Error("No conversation is available to hand off.");
+}: {
+  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 thinkingLevel =
+    modelOverride?.thinkingLevel ?? settings.thinkingLevel ?? destinationThinkingLevel;
+  const sessionContext = resolveHandoffSource(sourceSessionManager, sourceLeafId);
 
   const conversationText = serializeConversation(convertToLlm(sessionContext.messages));
   const handoffContext = await runHandoffExtractionAgent(
     ctx,
+    modelRuntime,
     model,
     conversationText,
     goal,
     thinkingLevel,
+    settings.persistRuns,
     signal,
   );
   if (!handoffContext) {
@@ -142,38 +143,51 @@ export async function generateHandoffDraftFromSessionManager(
   const sessionPath = sourceSessionManager.getSessionFile();
 
   return {
-    draft: assembleHandoffDraft(sessionId, sessionPath, handoffContext, goal, requestResponse),
-    context: handoffContext,
+    draft: assembleHandoffDraft(
+      sessionId,
+      sessionPath,
+      handoffContext.context,
+      goal,
+      requestResponse,
+    ),
+    context: handoffContext.context,
     sessionId,
     sessionPath,
+    ...(handoffContext.debugSessionPath
+      ? { debugSessionPath: handoffContext.debugSessionPath }
+      : {}),
   };
 }
 
 export function buildExtractionPrompt(conversationText: string, goal: string): string {
   return [
-    "## Conversation",
+    "<conversation>",
     conversationText,
+    "</conversation>",
     "",
-    "## Goal",
+    "<handoff-goal>",
     goal,
-    "",
-    "Call create_handoff_context exactly once.",
+    "</handoff-goal>",
   ].join("\n");
 }
 
 async function runHandoffExtractionAgent(
   ctx: ExtensionContext,
+  modelRuntime: ModelRuntime,
   model: Model<Api>,
   conversationText: string,
   goal: string,
   thinkingLevel: ThinkingLevel | undefined,
+  persistRuns: boolean,
   signal?: AbortSignal,
-): Promise<HandoffContext | undefined> {
+): Promise<{ context: HandoffContext; debugSessionPath?: string | undefined } | undefined> {
   let capturedArguments: HandoffExtractionArgs | undefined;
+  // Pi does not inject promptSnippet or promptGuidelines when a custom system prompt is active.
   const createHandoffContextTool = defineTool({
     name: "create_handoff_context",
     label: "Create handoff context",
-    description: "Extract the structured handoff context for the next session.",
+    description:
+      "Submit the completed structured briefing for the destination session. Call this tool exactly once to complete extraction.",
     parameters: HANDOFF_EXTRACTION_PARAMETERS,
     execute: async (_toolCallId, params) => {
       capturedArguments = params;
@@ -191,19 +205,23 @@ async function runHandoffExtractionAgent(
     noExtensions: true,
     noPromptTemplates: true,
     noSkills: true,
-    appendSystemPromptOverride: (base) => [...base, HANDOFF_SYSTEM_PROMPT],
+    systemPromptOverride: () => HANDOFF_SYSTEM_PROMPT,
   });
   await resourceLoader.reload();
 
+  const sessionManager = persistRuns
+    ? SessionManager.create(ctx.cwd, getDefaultHandoffRunsDir())
+    : SessionManager.inMemory(ctx.cwd);
+  const debugSessionPath = persistRuns ? sessionManager.getSessionFile() : undefined;
   const { session } = await createAgentSession({
     cwd: ctx.cwd,
     model,
-    modelRegistry: ctx.modelRegistry,
+    modelRuntime,
     ...(thinkingLevel ? { thinkingLevel } : {}),
-    tools: ["read", "grep", "find", "ls", "create_handoff_context"],
+    tools: ["create_handoff_context"],
     customTools: [createHandoffContextTool],
     resourceLoader,
-    sessionManager: SessionManager.inMemory(ctx.cwd),
+    sessionManager,
   });
 
   const abortHandler = (): void => {
@@ -217,7 +235,19 @@ async function runHandoffExtractionAgent(
       return undefined;
     }
 
-    await session.prompt(buildExtractionPrompt(conversationText, goal));
+    for (let attempt = 1; attempt <= MAX_HANDOFF_EXTRACTION_ATTEMPTS; attempt += 1) {
+      if (signal?.aborted) {
+        break;
+      }
+      await session.prompt(
+        attempt === 1
+          ? buildExtractionPrompt(conversationText, goal)
+          : HANDOFF_EXTRACTION_RETRY_PROMPT,
+      );
+      if (capturedArguments) {
+        break;
+      }
+    }
   } finally {
     signal?.removeEventListener("abort", abortHandler);
     session.dispose();
@@ -231,12 +261,15 @@ async function runHandoffExtractionAgent(
     throw new Error("Handoff extraction did not return structured context.");
   }
 
-  const extraction = extractHandoffContextFromArguments(capturedArguments, goal);
+  const extraction = extractHandoffContextFromArguments(capturedArguments);
   if (!extraction.context) {
     throw new Error(extraction.error);
   }
 
-  return extraction.context;
+  return {
+    context: extraction.context,
+    ...(debugSessionPath ? { debugSessionPath } : {}),
+  };
 }
 
 export function assembleHandoffDraft(
@@ -247,10 +280,10 @@ export function assembleHandoffDraft(
   requestResponse = false,
 ): string {
   const sections = [buildContinuityLine(sessionId, sessionPath, requestResponse)];
-  const nextTask = handoffContext.nextTask.trim() || goal.trim();
+  const task = goal.trim();
 
-  if (nextTask) {
-    sections.push(["## Task", nextTask].join("\n"));
+  if (task) {
+    sections.push(["## Task", task].join("\n"));
   }
 
   if (handoffContext.relevantFiles.length > 0) {
@@ -280,24 +313,22 @@ export function assembleHandoffDraft(
 
 export function extractHandoffContext(
   response: AssistantMessage,
-  goal: string,
 ): { context: HandoffContext; error?: undefined } | { context?: undefined; error: string } {
   const toolCall = response.content.find(isCreateHandoffContextToolCall);
   if (!toolCall) {
     return { error: "Handoff extraction did not return structured context." };
   }
 
-  return extractHandoffContextFromArguments(toolCall.arguments, goal);
+  return extractHandoffContextFromArguments(toolCall.arguments);
 }
 
 function extractHandoffContextFromArguments(
   argumentsValue: unknown,
-  goal: string,
 ): { context: HandoffContext; error?: undefined } | { context?: undefined; error: string } {
-  let requiredArguments: RequiredHandoffExtractionArgs;
+  let extraction: HandoffExtractionArgs;
   try {
-    requiredArguments = parseTypeBoxValue(
-      REQUIRED_HANDOFF_EXTRACTION_PARAMETERS,
+    extraction = parseTypeBoxValue(
+      HANDOFF_EXTRACTION_PARAMETERS,
       argumentsValue,
       "Invalid create_handoff_context arguments",
     );
@@ -305,27 +336,16 @@ function extractHandoffContextFromArguments(
     return { error: "Handoff extraction did not return structured context." };
   }
 
-  const title = normalizeText(requiredArguments.title);
-  if (title.length > MAX_HANDOFF_TITLE_LENGTH) {
-    return { error: "Handoff title must be 64 characters or less." };
-  }
-
-  const summary = normalizeText(requiredArguments.summary);
-  const relevantFiles = getRelevantFiles(argumentsValue);
-  const nextTask = normalizeText(requiredArguments.nextTask) || goal.trim();
-  const openQuestions = getOpenQuestions(argumentsValue);
-
-  if (!summary || !nextTask || !title) {
+  const summary = normalizeText(extraction.summary);
+  if (!summary) {
     return { error: "Handoff extraction did not return structured context." };
   }
 
   return {
     context: {
-      title,
       summary,
-      relevantFiles,
-      nextTask,
-      openQuestions,
+      relevantFiles: normalizeStringArray(extraction.relevantFiles),
+      openQuestions: normalizeStringArray(extraction.openQuestions),
     },
   };
 }
@@ -340,10 +360,10 @@ function buildContinuityLine(
     return base;
   }
 
-  return `${base} When this work is complete, send that session a completion report with session_send_message.`;
+  return `${base} When this work is complete, send that session a completion report.`;
 }
 
-function normalizeStringArray(value: unknown, limit: number): string[] {
+function normalizeStringArray(value: unknown): string[] {
   if (!Array.isArray(value)) {
     return [];
   }
@@ -356,38 +376,15 @@ function normalizeStringArray(value: unknown, limit: number): string[] {
     }
 
     uniqueValues.add(normalized);
-    if (uniqueValues.size >= limit) {
-      break;
-    }
   }
 
   return [...uniqueValues];
 }
 
-function getRelevantFiles(argumentsValue: unknown): string[] {
-  if (!isRecord(argumentsValue)) {
-    return [];
-  }
-
-  return normalizeStringArray(argumentsValue.relevantFiles, MAX_RELEVANT_FILES);
-}
-
-function getOpenQuestions(argumentsValue: unknown): string[] {
-  if (!isRecord(argumentsValue)) {
-    return [];
-  }
-
-  return normalizeStringArray(argumentsValue.openQuestions, MAX_OPEN_QUESTIONS);
-}
-
 function normalizeText(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
 function isCreateHandoffContextToolCall(
   content: TextContent | ThinkingContent | ToolCall,
 ): content is ToolCall {