pi-sessions 0.6.0 → 0.7.0

package/extensions/session-handoff/refs.ts

@@ -1,12 +1,10 @@
 import path from "node:path";
 import { parseSessionFile } from "../session-search/extract.ts";
 import {
-  getIndexStatus,
   getSessionById,
-  INDEX_SCHEMA_VERSION,
-  openIndexDatabase,
   type SessionLineageRow,
   type SessionOrigin,
+  withSessionIndex,
 } from "../shared/session-index/index.ts";
 
 const HANDOFF_REF_PREFIX = "@handoff/";
@@ -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.ts

@@ -9,7 +9,7 @@ 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,
@@ -62,7 +62,6 @@ interface HandoffToolParams {
 }
 
 interface HandoffToolDetails {
-  error: boolean;
   sessionId?: string | undefined;
   title?: string | undefined;
   splitDirection?: HandoffSplitDirection | undefined;
@@ -90,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",
@@ -118,6 +118,23 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
           }),
         ),
       }),
+      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);
       },
@@ -361,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(
@@ -392,7 +409,7 @@ 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;
@@ -425,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,
@@ -433,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,
@@ -454,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,
@@ -527,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-messaging/broker/process.ts

@@ -1,15 +1,17 @@
 import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { createServer, type Socket } from "node:net";
 import { join } from "node:path";
-import { readFrames, writeFrame } from "../shared/framing.ts";
+import { readFrames, writeFrame } from "../../shared/session-broker/framing.ts";
 import {
   CLIENT_FRAME_SCHEMA,
   type SessionMessagingClientFrame,
   type SessionMessagingIncomingAckClientFrame,
   type SessionMessagingSendClientFrame,
-  type SessionMessagingSessionInfo,
-} from "../shared/protocol.ts";
-import { getSessionMessagingDir, getSessionMessagingSocketPath } from "../shared/socket-path.ts";
+} from "../../shared/session-broker/protocol.ts";
+import {
+  getSessionMessagingDir,
+  getSessionMessagingSocketPath,
+} from "../../shared/session-broker/socket-path.ts";
 
 const SEND_TIMEOUT_MS = 10_000;
 const EXIT_IDLE_MS = 5_000;
@@ -19,11 +21,6 @@ const messagingDir = getSessionMessagingDir();
 const socketPath = getSessionMessagingSocketPath();
 const pidPath = join(messagingDir, "broker.pid");
 
-interface ConnectedSession {
-  socket: Socket;
-  session: SessionMessagingSessionInfo;
-}
-
 interface PendingSend {
   source: Socket;
   timeout: NodeJS.Timeout;
@@ -31,7 +28,7 @@ interface PendingSend {
   targetSessionId: string;
 }
 
-const sessions = new Map<string, ConnectedSession>();
+const sessions = new Map<string, Socket>();
 const pendingSends = new Map<string, PendingSend>();
 let idleTimer: NodeJS.Timeout | undefined;
 let server: ReturnType<typeof createServer> | undefined;
@@ -63,9 +60,9 @@ function unregister(sessionId: string | undefined): void {
   if (sessions.size === 0) scheduleIdleExit();
 }
 
-function resolveTarget(target: string): { session: ConnectedSession } | { error: string } {
-  const exact = sessions.get(target);
-  if (exact) return { session: exact };
+function resolveTarget(target: string): { sessionId: string; socket: Socket } | { error: string } {
+  const socket = sessions.get(target);
+  if (socket) return { sessionId: target, socket };
 
   return { error: `No live session found for id: ${target}` };
 }
@@ -84,8 +81,8 @@ function handleFrame(
 
   switch (message.type) {
     case "register": {
-      const existing = sessions.get(message.session.sessionId);
-      if (existing && existing.socket !== socket && !existing.socket.destroyed) {
+      const existing = sessions.get(message.sessionId);
+      if (existing && existing !== socket && !existing.destroyed) {
         writeFrame(socket, {
           type: "register_failed",
           reason:
@@ -96,10 +93,10 @@ function handleFrame(
       }
 
       clearIdleExit();
-      setSessionId(message.session.sessionId);
-      sessions.set(message.session.sessionId, { socket, session: message.session });
+      setSessionId(message.sessionId);
+      sessions.set(message.sessionId, socket);
       socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
-      writeFrame(socket, { type: "registered", session: message.session });
+      writeFrame(socket, { type: "registered", sessionId: message.sessionId });
       break;
     }
 
@@ -113,7 +110,7 @@ function handleFrame(
       writeFrame(socket, {
         type: "sessions",
         requestId: message.requestId,
-        sessions: [...sessions.values()].map(({ session }) => session),
+        sessionIds: [...sessions.keys()],
       });
       break;
 
@@ -135,7 +132,7 @@ function handleSend(
   const source = currentSessionId ? sessions.get(currentSessionId) : undefined;
   const { messageId } = message;
 
-  if (!source) {
+  if (!currentSessionId || !source) {
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
@@ -158,7 +155,7 @@ function handleSend(
     return;
   }
 
-  if (resolved.session.session.sessionId === source.session.sessionId) {
+  if (resolved.sessionId === currentSessionId) {
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
@@ -183,16 +180,16 @@ function handleSend(
     source: socket,
     timeout,
     messageId,
-    targetSessionId: resolved.session.session.sessionId,
+    targetSessionId: resolved.sessionId,
   });
 
-  writeFrame(resolved.session.socket, {
+  writeFrame(resolved.socket, {
     type: "incoming",
     requestId: message.requestId,
     message: {
       messageId,
-      source: source.session,
-      target: resolved.session.session,
+      source: currentSessionId,
+      target: resolved.sessionId,
       body: message.body,
       ...(message.requestResponse === undefined
         ? {}
@@ -274,7 +271,7 @@ async function readConnection(
 }
 
 function shutdown(): void {
-  for (const { socket } of sessions.values()) socket.end();
+  for (const socket of sessions.values()) socket.end();
   sessions.clear();
   for (const pending of pendingSends.values()) clearTimeout(pending.timeout);
   pendingSends.clear();

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

@@ -3,7 +3,10 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import net from "node:net";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getSessionMessagingDir, getSessionMessagingSocketPath } from "../shared/socket-path.ts";
+import {
+  getSessionMessagingDir,
+  getSessionMessagingSocketPath,
+} from "../../shared/session-broker/socket-path.ts";
 
 const BROKER_START_TIMEOUT_MS = 5_000;
 const BROKER_CONNECT_TIMEOUT_MS = 1_000;
@@ -107,7 +110,9 @@ async function waitForBroker(): Promise<void> {
 function acquireSpawnLock(): boolean {
   for (let attempt = 0; attempt < 5; attempt += 1) {
     try {
-      writeFileSync(brokerSpawnLockPath, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
+      writeFileSync(brokerSpawnLockPath, `${process.pid}\n${Date.now()}\n`, {
+        flag: "wx",
+      });
       return true;
     } catch (error) {
       if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") {

package/extensions/session-messaging/pi/incoming-runtime.ts

@@ -1,8 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { SessionLineageRelation } from "../../shared/session-index/index.ts";
 import { safeParseTypeBoxValue } from "../../shared/typebox.ts";
-import type { SessionMessagePayload } from "../shared/protocol.ts";
 import { RECEIVED_MESSAGE_ENTRY_SCHEMA, type ReceivedMessageEntry } from "./message-contracts.ts";
+
 export const MESSAGE_RECEIVED_CUSTOM_TYPE = "pi-sessions.message_received";
 export const SESSION_MESSAGE_CUSTOM_TYPE = "pi-sessions.session_message";
 
@@ -39,17 +38,13 @@ export class IncomingSessionMessageRuntime {
     });
   }
 
-  deliver(
-    message: SessionMessagePayload,
-    relation: SessionLineageRelation | undefined,
-  ): DeliveryResult {
+  deliver(received: ReceivedMessageEntry): DeliveryResult {
     const ctx = this.context;
     if (!ctx) {
       return { delivered: false, error: "Target session is not ready." };
     }
 
     try {
-      const received = buildReceivedMessageEntry(message, relation);
       this.actions.appendEntry(MESSAGE_RECEIVED_CUSTOM_TYPE, received);
       this.inject(ctx, received);
       return { delivered: true };
@@ -106,17 +101,6 @@ export class IncomingSessionMessageRuntime {
   }
 }
 
-function buildReceivedMessageEntry(
-  message: SessionMessagePayload,
-  relation: SessionLineageRelation | undefined,
-): ReceivedMessageEntry {
-  return {
-    ...message,
-    receivedAt: new Date().toISOString(),
-    ...(relation === undefined ? {} : { relation }),
-  };
-}
-
 function formatIncomingMessageForModel(received: ReceivedMessageEntry): string {
   const title = received.source.sessionName?.trim();
   const titlePart = title ? ` "${title}"` : "";

package/extensions/session-messaging/pi/message-contracts.ts

@@ -1,5 +1,11 @@
 import { type Static, Type } from "typebox";
 
+const RECEIVED_MESSAGE_ENDPOINT_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  sessionName: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+});
+
 export const SEND_MESSAGE_PARAMS = Type.Object({
   session: Type.String({ description: "Pi session UUID." }),
   message: Type.String({
@@ -15,16 +21,8 @@ export const SEND_MESSAGE_PARAMS = Type.Object({
 
 export const RECEIVED_MESSAGE_ENTRY_SCHEMA = Type.Object({
   messageId: Type.String(),
-  source: Type.Object({
-    sessionId: Type.String(),
-    sessionName: Type.Optional(Type.String()),
-    cwd: Type.String(),
-  }),
-  target: Type.Object({
-    sessionId: Type.String(),
-    sessionName: Type.Optional(Type.String()),
-    cwd: Type.String(),
-  }),
+  source: RECEIVED_MESSAGE_ENDPOINT_SCHEMA,
+  target: RECEIVED_MESSAGE_ENDPOINT_SCHEMA,
   body: Type.String(),
   sentAt: Type.String(),
   receivedAt: Type.String(),
@@ -34,4 +32,5 @@ export const RECEIVED_MESSAGE_ENTRY_SCHEMA = Type.Object({
 });
 
 export type SendMessageParams = Static<typeof SEND_MESSAGE_PARAMS>;
+export type ReceivedMessageEndpoint = Static<typeof RECEIVED_MESSAGE_ENDPOINT_SCHEMA>;
 export type ReceivedMessageEntry = Static<typeof RECEIVED_MESSAGE_ENTRY_SCHEMA>;

package/extensions/session-messaging/pi/message-view.ts

@@ -14,6 +14,7 @@ interface MessageViewOptions {
   status: "sending" | "received";
   targetSessionId?: string | undefined;
   sourceSessionId?: string | undefined;
+  sourceSessionName?: string | undefined;
   message: string;
   requestResponse?: boolean | undefined;
   relation?: string | undefined;
@@ -41,6 +42,7 @@ export function createReceivedSessionMessageComponent(
           expanded,
           status: "received",
           sourceSessionId: received.source.sessionId,
+          sourceSessionName: received.source.sessionName,
           message: received.body,
           requestResponse: received.requestResponse,
           relation: received.relation,
@@ -84,12 +86,21 @@ function formatHeader(options: MessageViewOptions, theme: MessageViewTheme): str
   const metadataHint = metadata.length > 0 ? theme.fg("muted", ` (${metadata.join(", ")})`) : "";
   switch (options.status) {
     case "received":
-      return `${name} ${theme.fg("muted", `from ${options.sourceSessionId ?? "[source unknown]"}`)}${metadataHint}`;
+      return `${name} ${theme.fg("muted", `from ${formatSourceLabel(options)}`)}${metadataHint}`;
     case "sending":
       return `${name} ${theme.fg("muted", `to ${options.targetSessionId ?? "[target pending]"}`)}${metadataHint}`;
   }
 }
 
+function formatSourceLabel(options: MessageViewOptions): string {
+  if (!options.sourceSessionId) {
+    return "[source unknown]";
+  }
+
+  const title = options.sourceSessionName?.trim();
+  return title ? `${title} (${options.sourceSessionId})` : options.sourceSessionId;
+}
+
 function formatKeyHint(
   keybinding: Keybinding,
   description: string,