pi-sessions 0.5.1 → 0.7.0

package/extensions/session-handoff/picker.ts

@@ -11,11 +11,12 @@ import {
 import {
   stripSearchSnippetMarkers,
   transformSearchSnippetMatches,
-} from "../shared/search-snippet.js";
-import { listSessionPickerItems, normalizeDisplayText, type SessionPickerItem } from "./query.js";
+} from "../shared/search-snippet.ts";
+import { listSessionPickerItems, normalizeDisplayText, type SessionPickerItem } from "./query.ts";
 
 const MAX_VISIBLE_BROWSE_ROWS = 10;
 const MAX_VISIBLE_SEARCH_ROWS = 4;
+const SEARCH_RELOAD_DEBOUNCE_MS = 200;
 
 interface PickerRightColumnWidths {
   marker: number;
@@ -65,6 +66,7 @@ export class SessionReferencePickerComponent implements Focusable {
   private includeAll = false;
   private items: SessionPickerItem[] = [];
   private selectedIndex = 0;
+  private searchReloadTimer: ReturnType<typeof setTimeout> | undefined;
 
   get focused(): boolean {
     return this._focused;
@@ -89,17 +91,18 @@ export class SessionReferencePickerComponent implements Focusable {
 
   handleInput(data: string): void {
     if (matchesKey(data, this.options.shortcut)) {
-      this.done({ kind: "cancel" });
+      this.finish({ kind: "cancel" });
       return;
     }
 
     if (this.keybindings.matches(data, "tui.select.cancel")) {
-      this.done({ kind: "cancel" });
+      this.finish({ kind: "cancel" });
       return;
     }
 
     if (this.keybindings.matches(data, "tui.input.tab")) {
       this.includeAll = !this.includeAll;
+      this.cancelSearchReload();
       this.reload();
       this.tui.requestRender();
       return;
@@ -130,9 +133,10 @@ export class SessionReferencePickerComponent implements Focusable {
     }
 
     if (this.keybindings.matches(data, "tui.select.confirm")) {
+      this.flushSearchReload();
       const selected = this.items[this.selectedIndex];
       if (selected?.kind === "session") {
-        this.done({ kind: "insert-session-token", sessionId: selected.sessionId });
+        this.finish({ kind: "insert-session-token", sessionId: selected.sessionId });
       }
       return;
     }
@@ -140,7 +144,7 @@ export class SessionReferencePickerComponent implements Focusable {
     const before = this.input.getValue();
     this.input.handleInput(data);
     if (this.input.getValue() !== before) {
-      this.reload();
+      this.reloadAfterInputChange();
       this.tui.requestRender();
     }
   }
@@ -284,6 +288,48 @@ export class SessionReferencePickerComponent implements Focusable {
       .trim();
   }
 
+  private reloadAfterInputChange(): void {
+    if (!this.input.getValue().trim()) {
+      this.cancelSearchReload();
+      this.reload();
+      return;
+    }
+
+    this.scheduleSearchReload();
+  }
+
+  private scheduleSearchReload(): void {
+    this.cancelSearchReload();
+    this.searchReloadTimer = setTimeout(() => {
+      this.searchReloadTimer = undefined;
+      this.reload();
+      this.tui.requestRender();
+    }, SEARCH_RELOAD_DEBOUNCE_MS);
+  }
+
+  private flushSearchReload(): void {
+    if (!this.searchReloadTimer) {
+      return;
+    }
+
+    this.cancelSearchReload();
+    this.reload();
+  }
+
+  private cancelSearchReload(): void {
+    if (!this.searchReloadTimer) {
+      return;
+    }
+
+    clearTimeout(this.searchReloadTimer);
+    this.searchReloadTimer = undefined;
+  }
+
+  private finish(result: SessionPickerResult): void {
+    this.cancelSearchReload();
+    this.done(result);
+  }
+
   private reload(): void {
     this.items = listSessionPickerItems({
       currentSessionPath: this.options.getCurrentSessionPath(),

package/extensions/session-handoff/query.ts

@@ -1,17 +1,15 @@
-import { stripSearchSnippetMarkers } from "../shared/search-snippet.js";
+import { stripSearchSnippetMarkers } from "../shared/search-snippet.ts";
 import {
-  getIndexStatus,
-  getLineageSessions,
   getSessionByPath,
-  INDEX_SCHEMA_VERSION,
-  openIndexDatabase,
   type SearchSessionResult,
   type SessionIndexDatabase,
   type SessionLineageRelation,
   searchSessions,
-} from "../shared/session-index/index.js";
-import { shortenSessionId } from "../shared/session-ui.js";
-import { formatCompactRelativeTime } from "../shared/time.js";
+  withSessionIndex,
+} from "../shared/session-index/index.ts";
+import { SearchQuerySyntaxError } from "../shared/session-index/query/ast.ts";
+import { shortenSessionId } from "../shared/session-ui.ts";
+import { formatCompactRelativeTime } from "../shared/time.ts";
 
 export const SESSION_TOKEN_PREFIX = "@session:";
 
@@ -19,7 +17,6 @@ const MAX_TREE_DEPTH = 3;
 
 interface SessionPickerPresentationContext {
   currentSessionId?: string | undefined;
-  relationBySessionId: Map<string, SessionLineageRelation>;
 }
 
 export interface SessionPickerSessionItem {
@@ -32,7 +29,7 @@ export interface SessionPickerSessionItem {
   modifiedAtText?: string | undefined;
   prefix: string;
   snippet?: string | undefined;
-  relation?: SessionLineageRelation | "self" | undefined;
+  relation?: SessionLineageRelation | undefined;
 }
 
 export interface SessionPickerNoticeItem {
@@ -69,69 +66,75 @@ export function listSessionPickerItems(
 ): SessionPickerQueryResult {
   const scopeMode = options.includeAll ? "all" : "default";
   const defaultScopeLabel = options.currentCwd ? "current folder" : undefined;
-  const status = getIndexStatus(options.indexPath);
-  if (!status.exists || status.schemaVersion !== INDEX_SCHEMA_VERSION) {
-    return {
-      items: [buildIndexErrorItem()],
-      scopeMode,
-      defaultScopeLabel,
-    };
-  }
-
-  const db = openIndexDatabase(status.dbPath, { create: false });
   try {
-    const currentSession = options.currentSessionPath
-      ? getSessionByPath(db, options.currentSessionPath)
-      : undefined;
-    const context = buildPresentationContext(db, currentSession?.sessionId);
-    const rankedResults = prioritizeSessionResults(
-      searchSessions(
-        db,
-        {
-          cwd: options.includeAll ? undefined : options.currentCwd,
-          query: options.mode === "search" ? options.query : undefined,
-          limit: options.limit,
-        },
-        { defaultLimit: undefined },
-      ),
-      context,
+    return (
+      withSessionIndex(options.indexPath, { mode: "read", required: false }, ({ db }) => {
+        const currentSession = options.currentSessionPath
+          ? getSessionByPath(db, options.currentSessionPath)
+          : undefined;
+        const context = buildPresentationContext(currentSession?.sessionId);
+        const searchResults = searchSessionsSafely(db, options, currentSession?.sessionId);
+        const rankedResults =
+          options.mode === "browse"
+            ? prioritizeSessionResults(searchResults, context)
+            : searchResults;
+
+        if (rankedResults.length === 0) {
+          return {
+            items: [buildEmptyResultItem(options.mode)],
+            scopeMode,
+            defaultScopeLabel,
+          };
+        }
+
+        const sessionItems =
+          options.mode === "browse"
+            ? buildBrowseSessionItems(rankedResults, context)
+            : rankedResults.map((result) =>
+                buildSessionItem(result, context, "", getBestTextSnippet(result)),
+              );
+
+        return {
+          items: sessionItems,
+          scopeMode,
+          defaultScopeLabel,
+        };
+      }) ?? {
+        items: [buildIndexErrorItem()],
+        scopeMode,
+        defaultScopeLabel,
+      }
     );
-
-    if (rankedResults.length === 0) {
+  } catch (error) {
+    if (error instanceof SearchQuerySyntaxError) {
       return {
-        items: [buildEmptyResultItem(options.mode)],
+        items: [buildSearchSyntaxErrorItem(error)],
         scopeMode,
         defaultScopeLabel,
       };
     }
 
-    const sessionItems =
-      options.mode === "browse"
-        ? buildBrowseSessionItems(rankedResults, context)
-        : rankedResults.map((result) => buildSessionItem(result, context, "", result.snippet));
-
-    return {
-      items: sessionItems,
-      scopeMode,
-      defaultScopeLabel,
-    };
-  } finally {
-    db.close();
+    throw error;
   }
 }
 
-function buildPresentationContext(
+function searchSessionsSafely(
   db: SessionIndexDatabase,
+  options: ListSessionPickerItemsOptions,
+  currentSessionId?: string | undefined,
+): SearchSessionResult[] {
+  return searchSessions(db, {
+    cwd: options.includeAll ? undefined : options.currentCwd,
+    query: options.mode === "search" ? options.query : undefined,
+    limit: options.limit,
+    relativeToSessionId: currentSessionId,
+  });
+}
+
+function buildPresentationContext(
   currentSessionId?: string | undefined,
 ): SessionPickerPresentationContext {
-  return {
-    currentSessionId,
-    relationBySessionId: currentSessionId
-      ? new Map(
-          getLineageSessions(db, currentSessionId).map((row) => [row.sessionId, row.relation]),
-        )
-      : new Map<string, SessionLineageRelation>(),
-  };
+  return { currentSessionId };
 }
 
 function prioritizeSessionResults(
@@ -253,13 +256,18 @@ function buildSessionItem(
   };
 }
 
+function getBestTextSnippet(result: SearchSessionResult): string | undefined {
+  const textEvidence = result.evidence.find((evidence) => evidence.kind === "text");
+  return textEvidence?.kind === "text" ? textEvidence.snippet : undefined;
+}
+
 function getSessionTitle(result: SearchSessionResult): string {
   return (
     normalizeDisplayText(result.sessionName) ??
     normalizeDisplayText(result.handoffNextTask) ??
     normalizeDisplayText(result.handoffGoal) ??
     normalizeDisplayText(result.firstUserPrompt) ??
-    normalizeDisplayText(stripSearchSnippetMarkers(result.snippet)) ??
+    normalizeDisplayText(stripSearchSnippetMarkers(getBestTextSnippet(result))) ??
     shortenSessionId(result.sessionId)
   );
 }
@@ -276,12 +284,12 @@ export function normalizeDisplayText(value?: string): string | undefined {
 function getSessionRelation(
   result: SearchSessionResult,
   context: SessionPickerPresentationContext,
-): SessionLineageRelation | "self" | undefined {
+): SessionLineageRelation | undefined {
   if (context.currentSessionId && result.sessionId === context.currentSessionId) {
     return "self";
   }
 
-  return context.relationBySessionId.get(result.sessionId);
+  return result.relation;
 }
 
 function getSessionMarker(
@@ -310,6 +318,14 @@ function buildIndexErrorItem(): SessionPickerNoticeItem {
   };
 }
 
+function buildSearchSyntaxErrorItem(error: SearchQuerySyntaxError): SessionPickerNoticeItem {
+  return {
+    kind: "error",
+    title: "Invalid search query",
+    description: error.message,
+  };
+}
+
 function buildEmptyResultItem(mode: "browse" | "search"): SessionPickerNoticeItem {
   return {
     kind: "empty",

package/extensions/session-handoff/refs.ts

@@ -1,13 +1,11 @@
 import path from "node:path";
-import { parseSessionFile } from "../session-search/extract.js";
+import { parseSessionFile } from "../session-search/extract.ts";
 import {
-  getIndexStatus,
   getSessionById,
-  INDEX_SCHEMA_VERSION,
-  openIndexDatabase,
   type SessionLineageRow,
   type SessionOrigin,
-} from "../shared/session-index/index.js";
+  withSessionIndex,
+} from "../shared/session-index/index.ts";
 
 const HANDOFF_REF_PREFIX = "@handoff/";
 const SESSION_REFERENCE_HELP =
@@ -103,24 +101,20 @@ function resolveIndexedReference(
     return { error: `Invalid session reference: ${input}. ${SESSION_REFERENCE_HELP}` };
   }
 
-  const status = getIndexStatus(options.indexPath);
-  if (!status.exists || status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+  try {
+    return withSessionIndex(options.indexPath, { mode: "read", required: true }, ({ db }) => {
+      const exactMatch = getSessionById(db, value);
+      if (exactMatch) {
+        return { resolved: buildResolvedReference(input, kind, exactMatch) };
+      }
+
+      return { error: `No session found for reference: ${input}. ${SESSION_REFERENCE_HELP}` };
+    });
+  } catch {
     return {
-      error: `Session reference resolution requires a current index at ${status.dbPath}. Run /session-index and press r to rebuild it.`,
+      error: `Session reference resolution requires a current index at ${options.indexPath}. Run /session-index and press r to rebuild it.`,
     };
   }
-
-  const db = openIndexDatabase(status.dbPath, { create: false });
-  try {
-    const exactMatch = getSessionById(db, value);
-    if (exactMatch) {
-      return { resolved: buildResolvedReference(input, kind, exactMatch) };
-    }
-
-    return { error: `No session found for reference: ${input}. ${SESSION_REFERENCE_HELP}` };
-  } finally {
-    db.close();
-  }
 }
 
 function buildResolvedReference(

package/extensions/session-handoff/spawn.ts

@@ -8,7 +8,7 @@ import {
   type SessionHeader,
   type SessionInfoEntry,
 } from "@earendil-works/pi-coding-agent";
-import { HANDOFF_BOOTSTRAP_ENV } from "./metadata.js";
+import { HANDOFF_BOOTSTRAP_ENV } from "./metadata.ts";
 
 const GHOSTTY_MACOS_ONLY_MESSAGE = "Split handoff currently supports Ghostty on macOS only.";
 const GHOSTTY_REQUIRED_MESSAGE = "Split handoff requires running inside Ghostty.";

package/extensions/session-handoff.ts

@@ -9,13 +9,13 @@ import type {
   ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 import { buildSessionContext, SessionManager } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { Key, matchesKey, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
   generateHandoffDraft,
   generateHandoffDraftFromSessionManager,
   type HandoffDraftResult,
-} from "./session-handoff/extract.js";
+} from "./session-handoff/extract.ts";
 import {
   type ChildGeneratedHandoffBootstrap,
   createChildGeneratedHandoffBootstrap,
@@ -29,14 +29,14 @@ import {
   hasUserMessages,
   isChildGeneratedHandoffBootstrap,
   parseHandoffBootstrap,
-} from "./session-handoff/metadata.js";
-import { openSessionReferencePicker } from "./session-handoff/picker.js";
-import { SESSION_TOKEN_PREFIX } from "./session-handoff/query.js";
+} from "./session-handoff/metadata.ts";
+import { openSessionReferencePicker } from "./session-handoff/picker.ts";
+import { SESSION_TOKEN_PREFIX } from "./session-handoff/query.ts";
 import {
   renderStrongModal,
   reviewHandoffDraft,
   reviewHandoffDraftForSend,
-} from "./session-handoff/review.js";
+} from "./session-handoff/review.ts";
 import {
   buildPiResumeCommand,
   createHandoffSession,
@@ -45,9 +45,9 @@ import {
   isGhosttyHandoffAvailable,
   launchSplitHandoffSession,
   validateSplitHandoffPrerequisites,
-} from "./session-handoff/spawn.js";
-import { isTuiMode } from "./shared/pi-mode.js";
-import { loadSettings } from "./shared/settings.js";
+} from "./session-handoff/spawn.ts";
+import { isTuiMode } from "./shared/pi-mode.ts";
+import { loadSettings } from "./shared/settings.ts";
 
 const HANDOFF_USAGE = "Usage: /handoff [--left|--right|--up|--down] <goal for new thread>";
 const TOOL_HANDOFF_PROVISIONAL_TITLE = "Session handoff";
@@ -58,10 +58,10 @@ interface HandoffToolParams {
   goal: string;
   splitDirection: HandoffSplitDirection;
   cwd?: string | undefined;
+  requestResponse?: boolean | undefined;
 }
 
 interface HandoffToolDetails {
-  error: boolean;
   sessionId?: string | undefined;
   title?: string | undefined;
   splitDirection?: HandoffSplitDirection | undefined;
@@ -89,6 +89,7 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         "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.",
       ],
       executionMode: "sequential",
@@ -110,7 +111,30 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
               "Optional target working directory. Relative paths resolve from the current session cwd.",
           }),
         ),
+        requestResponse: Type.Optional(
+          Type.Boolean({
+            description:
+              "Whether the child session should report completion/results of its task back to this session.",
+          }),
+        ),
       }),
+      renderResult(result, _options, theme, context) {
+        const text = getFirstText(result);
+        if (context.isError) {
+          return new Text(theme.fg("error", text), 0, 0);
+        }
+
+        const details = result.details as HandoffToolDetails | undefined;
+        if (!details?.sessionId || !details.splitDirection || !details.cwd) {
+          return new Text(text, 0, 0);
+        }
+
+        return new Text(
+          `Started handoff session ${theme.bold(details.sessionId)} (${details.splitDirection}) in ${theme.fg("dim", details.cwd)}.`,
+          0,
+          0,
+        );
+      },
       async execute(_toolCallId, params: HandoffToolParams, _signal, _onUpdate, ctx) {
         return executeSessionHandoffTool(pi, params, ctx, identifiedGhosttyTerminalId);
       },
@@ -354,30 +378,30 @@ async function executeSessionHandoffTool(
 ) {
   const goal = params.goal.trim();
   if (!goal) {
-    return createHandoffToolError("session_handoff requires a goal.");
+    throw new Error("session_handoff requires a goal.");
   }
 
   if (!ctx.model) {
-    return createHandoffToolError("No model selected.");
+    throw new Error("No model selected.");
   }
 
   const preflightError = await validateSplitHandoffPrerequisites(pi, ctx);
   if (preflightError) {
-    return createHandoffToolError(preflightError);
+    throw new Error(preflightError);
   }
 
   if (!terminalId) {
-    return createHandoffToolError(NO_IDENTIFIED_TERMINAL_MESSAGE);
+    throw new Error(NO_IDENTIFIED_TERMINAL_MESSAGE);
   }
 
   const targetCwd = resolveHandoffCwd(ctx.cwd, params.cwd);
   if (targetCwd.error) {
-    return createHandoffToolError(targetCwd.message);
+    throw new Error(targetCwd.message);
   }
 
   const parentSessionFile = ctx.sessionManager.getSessionFile();
   if (!parentSessionFile) {
-    return createHandoffToolError("Handoff requires a persisted current session.");
+    throw new Error("Handoff requires a persisted current session.");
   }
 
   const sessionContext = buildSessionContext(
@@ -385,9 +409,10 @@ async function executeSessionHandoffTool(
     ctx.sessionManager.getLeafId(),
   );
   if (sessionContext.messages.length === 0) {
-    return createHandoffToolError("No conversation to hand off.");
+    throw new Error("No conversation to hand off.");
   }
 
+  const requestResponse = params.requestResponse ?? false;
   const createdSession = createHandoffSession({
     cwd: targetCwd.path,
     sessionDir: ctx.sessionManager.getSessionDir(),
@@ -400,6 +425,7 @@ async function executeSessionHandoffTool(
       goal,
       title: TOOL_HANDOFF_PROVISIONAL_TITLE,
       parentSessionFile,
+      requestResponse,
     }),
   );
   const model = formatModelArgument(ctx.model, pi.getThinkingLevel());
@@ -416,7 +442,7 @@ async function executeSessionHandoffTool(
   });
 
   if (!launchResult.success) {
-    return createHandoffToolError(
+    throw new Error(
       `${launchResult.error} Created handoff session ${createdSession.sessionId}; start it manually with: ${buildPiResumeCommand(
         ctx.sessionManager.getSessionDir(),
         createdSession.sessionId,
@@ -424,17 +450,10 @@ async function executeSessionHandoffTool(
         TOOL_HANDOFF_PROVISIONAL_TITLE,
         model,
       )}`,
-      {
-        sessionId: createdSession.sessionId,
-        title: TOOL_HANDOFF_PROVISIONAL_TITLE,
-        splitDirection: params.splitDirection,
-        cwd: targetCwd.path,
-      },
     );
   }
 
   const details: HandoffToolDetails = {
-    error: false,
     sessionId: createdSession.sessionId,
     title: TOOL_HANDOFF_PROVISIONAL_TITLE,
     splitDirection: params.splitDirection,
@@ -445,7 +464,7 @@ async function executeSessionHandoffTool(
     content: [
       {
         type: "text" as const,
-        text: `Started handoff session ${createdSession.sessionId} (${params.splitDirection}) in ${targetCwd.path}.`,
+        text: formatHandoffToolResultForModel(details, requestResponse),
       },
     ],
     details,
@@ -482,6 +501,7 @@ async function startChildGeneratedHandoff(
           bootstrap.goal,
           thinkingLevel,
           signal,
+          bootstrap.requestResponse ?? false,
         ),
     );
     if (!generatedDraft) {
@@ -517,16 +537,15 @@ async function startChildGeneratedHandoff(
   }
 }
 
-function createHandoffToolError(message: string, details: Partial<HandoffToolDetails> = {}) {
-  const resultDetails: HandoffToolDetails = {
-    error: true,
-    ...details,
-  };
+function formatHandoffToolResultForModel(
+  details: HandoffToolDetails,
+  requestResponse: boolean,
+): string {
+  return JSON.stringify({ ...details, requestResponse }, null, 2);
+}
 
-  return {
-    content: [{ type: "text" as const, text: message }],
-    details: resultDetails,
-  };
+function getFirstText(result: { content: Array<{ type: string; text?: string }> }): string {
+  return result.content.find((item) => item.type === "text")?.text ?? "";
 }
 
 function resolveHandoffCwd(

package/extensions/session-hooks.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { HANDOFF_BOOTSTRAP_ENV, parseHandoffBootstrap } from "./session-handoff/metadata.js";
-import { createSessionHookController } from "./session-search/hooks.js";
-import { loadSettings } from "./shared/settings.js";
+import { HANDOFF_BOOTSTRAP_ENV, parseHandoffBootstrap } from "./session-handoff/metadata.ts";
+import { createSessionHookController } from "./session-search/hooks.ts";
+import { loadSettings } from "./shared/settings.ts";
 
 interface SessionStartLifecycleEvent {
   reason?: "startup" | "reload" | "new" | "resume" | "fork";

package/extensions/session-index.ts

@@ -5,10 +5,10 @@ import {
   type Theme,
 } from "@earendil-works/pi-coding-agent";
 import { type Focusable, matchesKey, visibleWidth } from "@earendil-works/pi-tui";
-import { type ReindexResult, rebuildSessionIndex } from "./session-search/reindex.js";
-import { isTuiMode } from "./shared/pi-mode.js";
-import { getIndexStatus, type SessionIndexStatus } from "./shared/session-index/index.js";
-import { loadSettings } from "./shared/settings.js";
+import { type ReindexResult, rebuildSessionIndex } from "./session-search/reindex.ts";
+import { isTuiMode } from "./shared/pi-mode.ts";
+import { getIndexStatus, type SessionIndexStatus } from "./shared/session-index/index.ts";
+import { loadSettings } from "./shared/settings.ts";
 
 type SessionIndexAction = "reindex" | undefined;