pi-sessions 0.7.1 → 0.8.0

package/README.md

@@ -190,6 +190,7 @@ To change auto-titling settings, edit `~/.pi/agent/settings.json`:
   "sessions": {
     "autoTitle": {
       "refreshTurns": 4,
+      "timeoutSecs": 15,
       "model": "anthropic/claude-haiku-4-5",
       "prompt": "Custom prompt that overrides the default."
     }

package/extensions/session-ask.ts

@@ -39,9 +39,8 @@ export default function sessionAskExtension(pi: ExtensionAPI): void {
     name: "session_ask",
     label: "Session Ask",
     description: "Interrogate a Pi session",
-    promptSnippet:
-      "Use when you have a session id and want to recall information, decisions, reasoning, etc from it",
-    promptGuidelines: ["Prefer focused follow-up questions over broad recap requests"],
+    promptSnippet: "Recall information, decisions, or reasoning from a Pi session by id",
+    promptGuidelines: ["Use session_ask with focused questions rather than broad recap requests."],
     parameters: Type.Object({
       session: Type.String({
         description: "Bare UUID for the session",

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

@@ -7,7 +7,6 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutoTitleContext } from "./context.ts";
 import type { AutoTitleTrigger } from "./state.ts";
 
-const AUTO_TITLE_REQUEST_TIMEOUT_MS = 15_000;
 const AUTO_TITLE_MAX_TOKENS = 64;
 const AUTO_TITLE_CHAR_MAX = 80;
 
@@ -34,6 +33,7 @@ export async function generateAutoTitle(
   context: AutoTitleContext,
   trigger: AutoTitleTrigger,
   systemPrompt: string,
+  timeoutMs: number,
 ): Promise<AutoTitleGenerationResult> {
   if (!context.conversationText) {
     return {
@@ -64,7 +64,7 @@ export async function generateAutoTitle(
   };
 
   const abortController = new AbortController();
-  const timeoutId = setTimeout(() => abortController.abort(), AUTO_TITLE_REQUEST_TIMEOUT_MS);
+  const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
 
   try {
     const requestContext = {

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

@@ -58,6 +58,7 @@ export async function runBulkRetitle(
   mode: RetitleMode,
   getSessionEpoch: () => number,
   systemPrompt: string,
+  timeoutMs: number,
 ): Promise<BulkRetitleResult> {
   const result: BulkRetitleResult = {
     attempted: 0,
@@ -85,6 +86,7 @@ export async function runBulkRetitle(
         model,
         isManual: true,
         systemPrompt,
+        timeoutMs,
         getSessionEpoch,
         notifyOnSuccess: false,
       });
@@ -92,7 +94,7 @@ export async function runBulkRetitle(
       continue;
     }
 
-    const outcome = await retitleStoredSession(ctx, model, session.path, systemPrompt);
+    const outcome = await retitleStoredSession(ctx, model, session.path, systemPrompt, timeoutMs);
     result[outcome] += 1;
   }
 
@@ -165,6 +167,7 @@ export interface RetitlePlanOptions {
   model: Model<Api> | undefined;
   isManual: boolean;
   systemPrompt: string;
+  timeoutMs: number;
   existingPlan?: AutoTitleTriggerPlan;
   getSessionEpoch?: () => number;
   notifyOnSuccess?: boolean;
@@ -173,8 +176,17 @@ export interface RetitlePlanOptions {
 export async function runRetitlePlan(
   options: RetitlePlanOptions,
 ): Promise<AutoTitleGenerationResult> {
-  const { pi, controller, ctx, model, isManual, systemPrompt, existingPlan, getSessionEpoch } =
-    options;
+  const {
+    pi,
+    controller,
+    ctx,
+    model,
+    isManual,
+    systemPrompt,
+    timeoutMs,
+    existingPlan,
+    getSessionEpoch,
+  } = options;
   const notifyOnSuccess = options.notifyOnSuccess ?? isManual;
 
   const plan = existingPlan ?? controller.handleManualRetitle(ctx);
@@ -211,6 +223,7 @@ export async function runRetitlePlan(
     titleContext,
     plan.reason,
     systemPrompt,
+    timeoutMs,
   );
   if (!generatedTitle.ok) {
     return generatedTitle;
@@ -257,6 +270,7 @@ async function retitleStoredSession(
   model: Model<Api>,
   sessionPath: string,
   systemPrompt: string,
+  timeoutMs: number,
 ): Promise<"retitled" | "unchanged" | "failed"> {
   const sessionManager = SessionManager.open(sessionPath);
   const currentTitle = sessionManager.getSessionName();
@@ -279,6 +293,7 @@ async function retitleStoredSession(
     titleContext,
     plan.reason,
     systemPrompt,
+    timeoutMs,
   );
   if (!generatedTitle.ok) {
     return "failed";

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

@@ -57,6 +57,7 @@ export async function showRetitleWizard(
   model: Model<Api> | undefined,
   getSessionEpoch: () => number,
   systemPrompt: string,
+  timeoutMs: number,
   options?: RetitleWizardOptions,
 ): Promise<RetitleCommandOutcome> {
   return ctx.ui.custom<RetitleCommandOutcome>(
@@ -70,6 +71,7 @@ export async function showRetitleWizard(
         model,
         getSessionEpoch,
         systemPrompt,
+        timeoutMs,
         done,
         options,
       ),
@@ -99,6 +101,7 @@ class RetitleWizardPanel implements Focusable {
     private readonly model: Model<Api> | undefined,
     private readonly getSessionEpoch: () => number,
     private readonly systemPrompt: string,
+    private readonly timeoutMs: number,
     private readonly done: (result: RetitleCommandOutcome) => void,
     options?: RetitleWizardOptions,
   ) {
@@ -250,6 +253,7 @@ class RetitleWizardPanel implements Focusable {
       model: this.model,
       isManual: true,
       systemPrompt: this.systemPrompt,
+      timeoutMs: this.timeoutMs,
       getSessionEpoch: this.getSessionEpoch,
     });
     if (result.ok) {
@@ -310,6 +314,7 @@ class RetitleWizardPanel implements Focusable {
       mode,
       this.getSessionEpoch,
       this.systemPrompt,
+      this.timeoutMs,
     );
     notifyBulkRetitleResult(this.ctx, scan, mode, result);
     this.done(

package/extensions/session-auto-title.ts

@@ -75,6 +75,7 @@ export default function sessionAutoTitleExtension(pi: ExtensionAPI): void {
           model,
           invocation,
           settings.autoTitle.prompt,
+          settings.autoTitle.timeoutMs,
         );
       },
     ),
@@ -104,6 +105,7 @@ export default function sessionAutoTitleExtension(pi: ExtensionAPI): void {
       getSessionEpoch: () => sessionEpoch,
       notifyOnSuccess: false,
       systemPrompt: settings.autoTitle.prompt,
+      timeoutMs: settings.autoTitle.timeoutMs,
     })
       .then((outcome) => {
         if (outcome.ok) {
@@ -139,6 +141,7 @@ async function handleTitleInvocation(
   model: Model<Api> | undefined,
   invocation: RetitleCommandInvocation,
   systemPrompt: string,
+  timeoutMs: number,
 ): Promise<RetitleCommandOutcome> {
   const retitleOpts = {
     pi,
@@ -147,6 +150,7 @@ async function handleTitleInvocation(
     model,
     isManual: true,
     systemPrompt,
+    timeoutMs,
     getSessionEpoch: state.getSessionEpoch,
   };
 
@@ -165,7 +169,15 @@ async function handleTitleInvocation(
       return retitleCurrentSession();
     }
 
-    return showRetitleWizard(pi, state.controller, ctx, model, state.getSessionEpoch, systemPrompt);
+    return showRetitleWizard(
+      pi,
+      state.controller,
+      ctx,
+      model,
+      state.getSessionEpoch,
+      systemPrompt,
+      timeoutMs,
+    );
   }
 
   if (invocation.scope === "this") {
@@ -180,6 +192,7 @@ async function handleTitleInvocation(
       model,
       state.getSessionEpoch,
       systemPrompt,
+      timeoutMs,
       {
         initialInvocation: {
           scope: invocation.scope,
@@ -201,6 +214,7 @@ async function handleTitleInvocation(
       mode,
       state.getSessionEpoch,
       systemPrompt,
+      timeoutMs,
     );
     notifyBulkRetitleResult(ctx, scan, mode, result);
     return "success";

package/extensions/session-handoff.ts

@@ -87,16 +87,15 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         "Start a background pi session in a terminal split based on the current session",
       promptGuidelines: [
         "Use session_handoff only when it is clear the work should be forked to a new context.",
-        "Prefer using session_handoff by direction of the user, not as an unsolicited default.",
-        "The goal should capture enough detail to encompass the ask and include any directions the next sessions should consider.",
-        "Only request a response when there is a specific ask-and-response expectation: the user asked for a report back, or the current session needs the child result before it can continue. Do not set requestResponse for independent or unrelated background work; most split-off tasks should run without reporting back.",
-        "Only capable of a background handoff; to replace the current session, tell the user to run /handoff instead.",
+        "Reach for session_handoff by direction of the user, not as an unsolicited default.",
+        "session_handoff should only request a response when there is a specific ask-and-response expectation: the user asked for a report back, or this session needs the child result to continue. Leave it off by default and for independent background work.",
+        "session_handoff can only fork a background session; to replace the current session, tell the user to run /handoff instead.",
       ],
       executionMode: "sequential",
       parameters: Type.Object({
         goal: Type.String({
           description:
-            "Goal for the new session, including enough detail to capture the user's ask and any directions the next prompt should consider.",
+            "Goal for the new session. Capture enough detail to encompass the ask and any directions the next session should consider.",
         }),
         splitDirection: Type.Union(
           [Type.Literal("left"), Type.Literal("right"), Type.Literal("up"), Type.Literal("down")],

package/extensions/session-messaging/pi/tools.ts

@@ -14,7 +14,7 @@ export function registerSessionMessagingTools(
     description: "Send a message to another live pi session",
     promptSnippet: "Send a message to another live pi session",
     promptGuidelines: [
-      "Use session_search with live: true to discover targetable sessions. Usually it is best to exclude all other filters and simply get a list of all live sessions",
+      "Before session_send_message, use session_search with live: true (no other filters) to list all live sessions and find the target.",
     ],
     parameters: SEND_MESSAGE_PARAMS,
     renderCall(args, theme, context) {

package/extensions/session-search.ts

@@ -64,10 +64,10 @@ export default function sessionSearchExtension(
     name: "session_search",
     label: "Session Search",
     description: "Search Pi sessions",
-    promptSnippet: "Use when you need to locate a session to do a detailed follow-up",
+    promptSnippet: "Locate Pi sessions for follow-up",
     promptGuidelines: [
-      "Omit query to list matching sessions chronologically",
-      "Once you have the right session id, switch to session_ask for questions about that session",
+      "Omit queries in session_search to list matching sessions chronologically.",
+      "After session_search finds a session id, switch to session_ask for questions about it.",
     ],
     parameters: Type.Object({
       query: Type.Optional(

package/extensions/shared/settings.ts

@@ -7,6 +7,7 @@ import { type Static, Type } from "typebox";
 import { parseTypeBoxValue } from "./typebox.ts";
 
 export const DEFAULT_AUTO_TITLE_REFRESH_TURNS = 4;
+export const DEFAULT_AUTO_TITLE_TIMEOUT_SECONDS = 15;
 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(
@@ -22,6 +23,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
   autoTitle: Type.Optional(
     Type.Object({
       refreshTurns: Type.Optional(Type.Integer({ minimum: 1 })),
+      timeoutSecs: Type.Optional(Type.Integer({ minimum: 1 })),
       model: Type.Optional(Type.String()),
       thinkingLevel: Type.Optional(Type.String()),
       prompt: Type.Optional(Type.String()),
@@ -57,6 +59,7 @@ export interface AgentModelSettings {
 
 export interface AutoTitleSettings extends AgentModelSettings {
   refreshTurns: number;
+  timeoutMs: number;
   prompt: string;
 }
 
@@ -193,6 +196,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
     autoTitle: {
       ...resolveAgentModelSettings(fileSettings.autoTitle),
       refreshTurns: fileSettings.autoTitle?.refreshTurns ?? DEFAULT_AUTO_TITLE_REFRESH_TURNS,
+      timeoutMs: (fileSettings.autoTitle?.timeoutSecs ?? DEFAULT_AUTO_TITLE_TIMEOUT_SECONDS) * 1000,
       prompt: normalizeAutoTitlePrompt(fileSettings.autoTitle?.prompt),
     },
     ask: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",