pi-sessions 0.2.2 → 0.3.0

package/extensions/session-handoff/extract.ts

@@ -18,6 +18,7 @@ import { parseTypeBoxValue } from "../shared/typebox.js";
 
 const MAX_RELEVANT_FILES = 12;
 const MAX_OPEN_QUESTIONS = 8;
+const MAX_HANDOFF_TITLE_LENGTH = 64;
 
 const HANDOFF_SYSTEM_PROMPT = `You extract context for a deliberate session handoff.
 
@@ -27,12 +28,16 @@ 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.`;
 
 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.",
   }),
@@ -58,11 +63,13 @@ const HANDOFF_EXTRACTION_TOOL: Tool<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;
@@ -139,11 +146,13 @@ export async function generateHandoffDraft(
     throw new Error(response.errorMessage ?? "Handoff generation failed.");
   }
 
-  const handoffContext = extractHandoffContext(response, goal);
-  if (!handoffContext) {
-    throw new Error("Handoff extraction did not return structured context.");
+  const extraction = extractHandoffContext(response, goal);
+  if (!extraction.context) {
+    throw new Error(extraction.error);
   }
 
+  const handoffContext = extraction.context;
+
   const sessionId = ctx.sessionManager.getSessionId();
   const sessionPath = ctx.sessionManager.getSessionFile();
 
@@ -208,10 +217,10 @@ export function assembleHandoffDraft(
 export function extractHandoffContext(
   response: AssistantMessage,
   goal: string,
-): HandoffContext | undefined {
+): { context: HandoffContext; error?: undefined } | { context?: undefined; error: string } {
   const toolCall = response.content.find(isCreateHandoffContextToolCall);
   if (!toolCall) {
-    return undefined;
+    return { error: "Handoff extraction did not return structured context." };
   }
 
   let requiredArguments: RequiredHandoffExtractionArgs;
@@ -222,7 +231,12 @@ export function extractHandoffContext(
       "Invalid create_handoff_context arguments",
     );
   } catch {
-    return undefined;
+    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);
@@ -230,15 +244,18 @@ export function extractHandoffContext(
   const nextTask = normalizeText(requiredArguments.nextTask) || goal.trim();
   const openQuestions = normalizeStringArray(toolCall.arguments.openQuestions, MAX_OPEN_QUESTIONS);
 
-  if (!summary || !nextTask) {
-    return undefined;
+  if (!summary || !nextTask || !title) {
+    return { error: "Handoff extraction did not return structured context." };
   }
 
   return {
-    summary,
-    relevantFiles,
-    nextTask,
-    openQuestions,
+    context: {
+      title,
+      summary,
+      relevantFiles,
+      nextTask,
+      openQuestions,
+    },
   };
 }
 

package/extensions/session-handoff/metadata.ts

@@ -12,6 +12,7 @@ export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
   origin: Type.Literal("handoff"),
   goal: Type.String(),
   nextTask: Type.String(),
+  title: Type.String(),
   initial_prompt: Type.String(),
 });
 
@@ -19,6 +20,7 @@ export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
   sessionId: Type.String(),
   goal: Type.String(),
   nextTask: Type.String(),
+  title: Type.String(),
   initialPrompt: Type.String(),
 });
 
@@ -29,6 +31,7 @@ export function createHandoffSessionMetadata(
   goal: string,
   nextTask: string,
   initialPrompt: string,
+  title: string,
 ): HandoffSessionMetadata {
   const normalizedGoal = goal.trim();
   const normalizedNextTask = nextTask.trim() || normalizedGoal;
@@ -37,6 +40,7 @@ export function createHandoffSessionMetadata(
     origin: "handoff",
     goal: normalizedGoal,
     nextTask: normalizedNextTask,
+    title,
     initial_prompt: initialPrompt.trim(),
   };
 }
@@ -49,6 +53,7 @@ export function createHandoffBootstrap(
     sessionId,
     goal: metadata.goal,
     nextTask: metadata.nextTask,
+    title: metadata.title,
     initialPrompt: metadata.initial_prompt,
   };
 }

package/extensions/session-handoff/spawn.ts

@@ -6,6 +6,7 @@ import {
   type ExtensionAPI,
   type ExtensionCommandContext,
   type SessionHeader,
+  type SessionInfoEntry,
 } from "@earendil-works/pi-coding-agent";
 import { HANDOFF_BOOTSTRAP_ENV } from "./metadata.js";
 
@@ -44,6 +45,7 @@ export function createHandoffSession(options: {
   cwd: string;
   sessionDir: string;
   parentSessionFile: string;
+  title: string;
 }): CreatedHandoffSession {
   const sessionId = randomUUID();
   const timestamp = new Date().toISOString();
@@ -59,7 +61,18 @@ export function createHandoffSession(options: {
     parentSession: options.parentSessionFile,
   };
 
-  writeFileSync(sessionFile, `${JSON.stringify(header)}\n`);
+  const titleEntry: SessionInfoEntry = {
+    type: "session_info",
+    id: randomUUID(),
+    parentId: null,
+    timestamp,
+    name: options.title,
+  };
+
+  writeFileSync(
+    sessionFile,
+    `${[JSON.stringify(header), JSON.stringify(titleEntry)].join("\n")}\n`,
+  );
 
   return { sessionId, sessionFile };
 }
@@ -72,12 +85,14 @@ export async function launchSplitHandoffSession(
     direction: HandoffSplitDirection;
     sessionId: string;
     bootstrapValue: string;
+    title: string;
   },
 ): Promise<{ success: true } | { success: false; error: string }> {
   const piCommand = buildPiLaunchCommand(
     options.sessionDir,
     options.sessionId,
     options.bootstrapValue,
+    options.title,
   );
   const escapedCwd = escapeAppleScriptString(options.cwd);
   const escapedCommand = escapeAppleScriptString(piCommand);
@@ -113,23 +128,29 @@ export function buildPiResumeCommand(
   sessionDir: string,
   sessionId: string,
   bootstrapValue: string,
+  title: string,
 ): string {
-  return [
+  const args = [
     `${HANDOFF_BOOTSTRAP_ENV}=${shellQuote(bootstrapValue)}`,
     "pi",
     "--session-dir",
     shellQuote(sessionDir),
-    "--session",
+    "--session-id",
     shellQuote(sessionId),
-  ].join(" ");
+    "--name",
+    shellQuote(title),
+  ];
+
+  return args.join(" ");
 }
 
 export function buildPiLaunchCommand(
   sessionDir: string,
   sessionId: string,
   bootstrapValue: string,
+  title: string,
 ): string {
-  const payload = `${buildPiResumeCommand(sessionDir, sessionId, bootstrapValue)}; exec /bin/zsh -il`;
+  const payload = `${buildPiResumeCommand(sessionDir, sessionId, bootstrapValue, title)}; exec /bin/zsh -il`;
   return `/bin/zsh -ilc ${shellQuote(payload)}`;
 }
 

package/extensions/session-handoff.ts

@@ -27,6 +27,11 @@ import { loadSettings } from "./shared/settings.js";
 
 const HANDOFF_USAGE = "Usage: /handoff [--left|--right|--up|--down] <goal for new thread>";
 
+interface HandoffPromptContext {
+  ui: ExtensionCommandContext["ui"];
+  sendUserMessage(content: string): Promise<void>;
+}
+
 export default function sessionHandoffExtension(pi: ExtensionAPI): void {
   const settings = loadSettings();
 
@@ -99,28 +104,30 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         parsedArgs.goal,
         generatedDraft.context.nextTask,
         approvedDraft,
+        generatedDraft.context.title,
       );
-      const createdSession = createHandoffSession({
-        cwd: ctx.cwd,
-        sessionDir: ctx.sessionManager.getSessionDir(),
-        parentSessionFile,
-      });
-      const bootstrapValue = encodeHandoffBootstrap(
-        createHandoffBootstrap(createdSession.sessionId, handoffMetadata),
-      );
-
       if (parsedArgs.splitDirection) {
+        const createdSession = createHandoffSession({
+          cwd: ctx.cwd,
+          sessionDir: ctx.sessionManager.getSessionDir(),
+          parentSessionFile,
+          title: handoffMetadata.title,
+        });
+        const bootstrapValue = encodeHandoffBootstrap(
+          createHandoffBootstrap(createdSession.sessionId, handoffMetadata),
+        );
         const launchResult = await launchSplitHandoffSession(pi, {
           cwd: ctx.cwd,
           sessionDir: ctx.sessionManager.getSessionDir(),
           direction: parsedArgs.splitDirection,
           sessionId: createdSession.sessionId,
           bootstrapValue,
+          title: handoffMetadata.title,
         });
 
         if (!launchResult.success) {
           ctx.ui.notify(
-            `${launchResult.error} Created handoff session ${createdSession.sessionId}; start it manually with: ${buildPiResumeCommand(ctx.sessionManager.getSessionDir(), createdSession.sessionId, bootstrapValue)}`,
+            `${launchResult.error} Created handoff session ${createdSession.sessionId}; start it manually with: ${buildPiResumeCommand(ctx.sessionManager.getSessionDir(), createdSession.sessionId, bootstrapValue, handoffMetadata.title)}`,
             "error",
           );
           return;
@@ -130,10 +137,14 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const switchResult = await ctx.switchSession(createdSession.sessionFile, {
+      const switchResult = await ctx.newSession({
+        parentSession: parentSessionFile,
+        setup: async (sessionManager) => {
+          sessionManager.appendSessionInfo(handoffMetadata.title);
+          sessionManager.appendCustomEntry(HANDOFF_METADATA_CUSTOM_TYPE, handoffMetadata);
+        },
         withSession: async (nextCtx) => {
-          await nextCtx.sendUserMessage(approvedDraft);
-          nextCtx.ui.notify("Handoff started in a new session.", "info");
+          startHandoffPromptAfterSessionRender(nextCtx, approvedDraft);
         },
       });
 
@@ -191,10 +202,19 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
       if (!getHandoffMetadataFromEntries(entries)) {
         pi.appendEntry(
           HANDOFF_METADATA_CUSTOM_TYPE,
-          createHandoffSessionMetadata(bootstrap.goal, bootstrap.nextTask, bootstrap.initialPrompt),
+          createHandoffSessionMetadata(
+            bootstrap.goal,
+            bootstrap.nextTask,
+            bootstrap.initialPrompt,
+            bootstrap.title,
+          ),
         );
       }
 
+      if (!ctx.sessionManager.getSessionName()) {
+        pi.setSessionName(bootstrap.title);
+      }
+
       pi.sendUserMessage(bootstrap.initialPrompt);
     } finally {
       delete process.env[HANDOFF_BOOTSTRAP_ENV];
@@ -266,6 +286,23 @@ async function runWithLoader<T>(
   return result;
 }
 
+function startHandoffPromptAfterSessionRender(
+  ctx: HandoffPromptContext,
+  approvedDraft: string,
+): void {
+  // ctx.newSession() renders the replacement session only after withSession returns.
+  setImmediate(() => {
+    void (async () => {
+      try {
+        await ctx.sendUserMessage(approvedDraft);
+        ctx.ui.notify("Handoff started in a new session.", "info");
+      } catch (error) {
+        ctx.ui.notify(formatHandoffError(error), "error");
+      }
+    })();
+  });
+}
+
 function formatHandoffError(error: unknown): string {
   if (error instanceof Error && error.message.trim()) {
     return error.message;

package/extensions/shared/settings.ts

@@ -6,6 +6,7 @@ import { type Static, Type } from "typebox";
 import { parseTypeBoxValue } from "./typebox.js";
 
 export const DEFAULT_AUTO_TITLE_REFRESH_TURNS = 4;
+export const DEFAULT_AUTO_TITLE_PROMPT = `Name this coding session (under 80 chars). Be specific to what is being discussed. Your exact output will be displayed to the user, so make sure that it contains ONLY the title itself and nothing else.`;
 const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
   handoff: Type.Optional(
     Type.Object({
@@ -21,6 +22,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
     Type.Object({
       refreshTurns: Type.Optional(Type.Integer({ minimum: 1 })),
       model: Type.Optional(Type.String()),
+      prompt: Type.Optional(Type.String()),
     }),
   ),
 });
@@ -42,6 +44,7 @@ export class ModelReference {
 export interface AutoTitleSettings {
   refreshTurns: number;
   model: ModelReference | undefined;
+  prompt: string;
 }
 
 export interface SessionSettings {
@@ -113,6 +116,11 @@ function parseModelReference(value: string | undefined): ModelReference | undefi
   return new ModelReference(trimmed.slice(0, slashIndex), trimmed.slice(slashIndex + 1));
 }
 
+function normalizeAutoTitlePrompt(value: string | undefined): string {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : DEFAULT_AUTO_TITLE_PROMPT;
+}
+
 function loadSessionFileSettings(): SessionFileSettings {
   const globalSettings = SettingsManager.create(process.cwd()).getGlobalSettings();
   const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, globalSettings, "Invalid settings");
@@ -132,6 +140,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
     autoTitle: {
       refreshTurns: fileSettings.autoTitle?.refreshTurns ?? DEFAULT_AUTO_TITLE_REFRESH_TURNS,
       model: parseModelReference(fileSettings.autoTitle?.model),
+      prompt: normalizeAutoTitlePrompt(fileSettings.autoTitle?.prompt),
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, auto-titling, and indexing tools",
   "license": "MIT",
@@ -42,10 +42,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.6.2",
     "husky": "^9.1.7",
@@ -55,10 +55,10 @@
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.74.0",
-    "@earendil-works/pi-ai": ">=0.74.0",
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": ">=0.74.0",
+    "@earendil-works/pi-agent-core": ">=0.78.0",
+    "@earendil-works/pi-ai": ">=0.78.0",
+    "@earendil-works/pi-coding-agent": ">=0.78.0",
+    "@earendil-works/pi-tui": ">=0.78.0",
     "typebox": ">=1.1.24"
   },
   "lint-staged": {

package/extensions/session-auto-title/prompt.ts

@@ -1,54 +0,0 @@
-import type { AutoTitleContext } from "./context.js";
-import type { AutoTitleTrigger } from "./state.js";
-
-const AUTO_TITLE_CHAR_MAX = 120;
-
-export const AUTO_TITLE_SYSTEM_PROMPT = `You generate concrete coding session titles from the conversation provided.
-
-Return title text only.
-
-Rules:
-- Prefer 3-15 words.
-- Maximum 120 characters.
-- Use the full conversation, while letting the most recent work refine the title when needed.
-- Describe the current task, bug, feature, or investigation on the active branch.
-- Mention specific subsystem or file only when it improves clarity.
-- No quotes, markdown, emojis, prefixes, or explanations.
-- No trailing punctuation.
-- Avoid generic titles like Coding help or Working on project.`;
-
-export function buildAutoTitlePrompt(context: AutoTitleContext, trigger: AutoTitleTrigger): string {
-  const sections = [
-    ["## Trigger", trigger],
-    ["## Current Title", context.currentTitle ?? "(none)"],
-    ["## Counts", formatCounts(context)],
-    ["## Conversation", context.conversationText || "(none)"],
-  ];
-
-  if (context.cwd) {
-    sections.unshift(["## Cwd", context.cwd]);
-  }
-
-  return sections.map(([heading, body]) => `${heading}\n${body}`).join("\n\n");
-}
-
-export function normalizeGeneratedAutoTitle(value: string): string | undefined {
-  const withoutQuotes = value.trim().replace(/^["'`]+|["'`]+$/g, "");
-  const collapsed = withoutQuotes
-    .replace(/\s+/g, " ")
-    .replace(/[.!?]+$/g, "")
-    .trim();
-  if (!collapsed) {
-    return undefined;
-  }
-
-  const truncated = collapsed.slice(0, AUTO_TITLE_CHAR_MAX).trim();
-  return truncated || undefined;
-}
-
-function formatCounts(context: AutoTitleContext): string {
-  return [
-    `user_turns: ${context.userTurnCount}`,
-    `assistant_turns: ${context.assistantTurnCount}`,
-  ].join("\n");
-}