pi-sessions 0.8.0 → 0.10.0

package/extensions/session-handoff/tool.ts

@@ -0,0 +1,206 @@
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { resolveHandoffSource } from "./extract.ts";
+import type { ClipboardStatus } from "./launch/backend.ts";
+import { resolveHandoffLaunchTarget } from "./launch-options.ts";
+import {
+  DEFERRED_LAUNCH,
+  type HandoffLaunchTarget,
+  type HandoffLaunchValue,
+} from "./launch-target.ts";
+import { createChildGeneratedHandoffBootstrap } from "./metadata.ts";
+import { formatModelArgument, resolveModelOverride } from "./model.ts";
+import { buildLaunchReceipt } from "./receipt.ts";
+import { formatHandoffLaunchFailure, prepareHandoffLaunch } from "./spawn.ts";
+import type { HandoffToolDetails } from "./tool-contract.ts";
+
+export type { HandoffLaunchValue } from "./launch-target.ts";
+export { DEFERRED_LAUNCH, LAUNCH_DIRECTIONS, SUBAGENT_LAUNCH } from "./launch-target.ts";
+
+export const MAX_HANDOFF_TITLE_LENGTH = 64;
+
+export interface HandoffToolParams {
+  goal: string;
+  title: string;
+  launch: HandoffLaunchValue;
+  cwd?: string | undefined;
+  requestResponse?: boolean | undefined;
+  provider?: string | undefined;
+  model?: string | undefined;
+  thinkingLevel?: ThinkingLevel | undefined;
+}
+
+export async function executeSessionHandoffTool(
+  pi: ExtensionAPI,
+  params: HandoffToolParams,
+  ctx: ExtensionContext,
+  modelRuntime: ModelRuntime,
+  launchTargets: readonly HandoffLaunchTarget[],
+  recordClipboardStatus: (sessionId: string, status: ClipboardStatus) => void,
+) {
+  const goal = params.goal.trim();
+  if (!goal) {
+    throw new Error("session_handoff requires a goal.");
+  }
+
+  const title = params.title.trim();
+  if (!title) {
+    throw new Error("session_handoff requires a title.");
+  }
+  if ([...title].length > MAX_HANDOFF_TITLE_LENGTH) {
+    throw new Error("session_handoff title must be 64 characters or less.");
+  }
+
+  if (!ctx.model) {
+    throw new Error("No model selected.");
+  }
+
+  const { target, degradedFrom } = resolveHandoffLaunchTarget(params.launch, launchTargets);
+
+  const targetCwd = resolveHandoffCwd(ctx.cwd, params.cwd);
+  if (targetCwd.error) {
+    throw new Error(targetCwd.message);
+  }
+
+  const parentSessionFile = ctx.sessionManager.getSessionFile();
+  if (!parentSessionFile) {
+    throw new Error("Handoff requires a persisted current session.");
+  }
+
+  // Tools execute in parallel, so the leaf is still the invoking assistant turn; its parent is the
+  // last settled entry. Anchoring there keeps the launch receipt this handoff produces out of the snapshot.
+  const invocationLeafId = ctx.sessionManager.getLeafId();
+  const sourceLeafId = invocationLeafId
+    ? ctx.sessionManager.getEntry(invocationLeafId)?.parentId
+    : undefined;
+  if (!sourceLeafId) {
+    throw new Error("No conversation to hand off.");
+  }
+
+  resolveHandoffSource(ctx.sessionManager, sourceLeafId);
+
+  const requestResponse = params.requestResponse ?? target.requestResponseDefault;
+  const provider = params.provider?.trim();
+  const modelId = params.model?.trim();
+  if (Boolean(provider) !== Boolean(modelId)) {
+    throw new Error("session_handoff requires provider and model together, or neither.");
+  }
+  const override =
+    provider && modelId
+      ? resolveModelOverride(modelRuntime, `${provider}/${modelId}`, params.thinkingLevel)
+      : undefined;
+  const childModel = override?.model ?? ctx.model;
+  const thinkingLevel = override?.thinkingLevel ?? params.thinkingLevel ?? pi.getThinkingLevel();
+  const model = formatModelArgument(childModel, thinkingLevel);
+  if (!model) {
+    throw new Error("No active model is available for the handoff.");
+  }
+  const prepared = prepareHandoffLaunch({
+    targetCwd: targetCwd.path,
+    parentCwd: ctx.cwd,
+    parentSessionDir: ctx.sessionManager.getSessionDir(),
+    parentSessionFile,
+    title,
+    model,
+    buildBootstrap: (sessionId) =>
+      createChildGeneratedHandoffBootstrap({
+        sessionId,
+        goal,
+        title,
+        parentSessionFile,
+        sourceLeafId,
+        requestResponse,
+        bootstrapMode: target.bootstrapMode,
+        launch: target.value,
+        subagent: target.describeSubagentChild?.({
+          childSessionId: sessionId,
+          ownerSessionId: ctx.sessionManager.getSessionId(),
+          requestResponse,
+        }),
+      }),
+    prepareChild: (manager, childSessionId) =>
+      target.prepareChild({
+        manager,
+        childSessionId,
+        parentSessionId: ctx.sessionManager.getSessionId(),
+        parentSessionFile,
+        requestResponse,
+      }),
+  });
+  const outcome = await target.launch({
+    prepared,
+    parentSessionId: ctx.sessionManager.getSessionId(),
+    title,
+    goal,
+    requestResponse,
+    model,
+    cwd: targetCwd.path,
+  });
+
+  if (!outcome.success) {
+    throw new Error(formatHandoffLaunchFailure(outcome.error, prepared));
+  }
+  if (outcome.clipboardStatus) {
+    recordClipboardStatus(prepared.sessionId, outcome.clipboardStatus);
+  }
+
+  const details: HandoffToolDetails = {
+    ...buildLaunchReceipt({
+      sessionId: prepared.sessionId,
+      childSessionFile: prepared.sessionFile,
+      title,
+      launch: target.value,
+      resumeCommand: prepared.resumeCommand,
+      backend: target.value === DEFERRED_LAUNCH ? undefined : outcome.backend,
+      targetCwd: targetCwd.path,
+      parentCwd: ctx.cwd,
+      childModel: model,
+      childProvider: childModel.provider,
+      childModelName: childModel.name || childModel.id,
+      thinkingLevel,
+    }),
+    ...(degradedFrom ? { degradedFrom } : {}),
+  };
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ ...details, requestResponse }, null, 2),
+      },
+    ],
+    details,
+  };
+}
+
+function resolveHandoffCwd(
+  currentCwd: string,
+  requestedCwd: string | undefined,
+): { path: string; error?: undefined } | { error: true; message: string } {
+  const rawPath = requestedCwd?.trim();
+  const resolvedPath = rawPath ? resolveRequestedPath(currentCwd, rawPath) : currentCwd;
+
+  if (!existsSync(resolvedPath)) {
+    return { error: true, message: `Handoff cwd does not exist: ${resolvedPath}` };
+  }
+  if (!statSync(resolvedPath).isDirectory()) {
+    return { error: true, message: `Handoff cwd is not a directory: ${resolvedPath}` };
+  }
+  return { path: resolvedPath };
+}
+
+function resolveRequestedPath(currentCwd: string, requestedPath: string): string {
+  if (requestedPath === "~") {
+    return homedir();
+  }
+  if (requestedPath.startsWith("~/")) {
+    return resolve(homedir(), requestedPath.slice(2));
+  }
+  if (isAbsolute(requestedPath)) {
+    return requestedPath;
+  }
+  return resolve(currentCwd, requestedPath);
+}

package/extensions/session-handoff/ui.ts

@@ -0,0 +1,66 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { renderStrongModal } from "./strong-modal.ts";
+
+export async function runHandoffTaskWithLoader<T>(
+  ctx: { ui: ExtensionUIContext },
+  label: string,
+  task: (signal: AbortSignal) => Promise<T>,
+): Promise<T | undefined> {
+  let taskError: unknown;
+
+  const result = await ctx.ui.custom<T | undefined>(
+    (tui, theme, _keybindings, done) => {
+      const abortController = new AbortController();
+
+      task(abortController.signal)
+        .then(done)
+        .catch((error: unknown) => {
+          if (!abortController.signal.aborted) {
+            taskError = error;
+          }
+          done(undefined);
+        });
+
+      return {
+        render(width: number): string[] {
+          return renderStrongModal(
+            [theme.fg("accent", theme.bold(label)), "", theme.fg("muted", "Press Esc to cancel.")],
+            width,
+            theme,
+          );
+        },
+        invalidate(): void {},
+        handleInput(data: string): void {
+          if (matchesKey(data, Key.escape)) {
+            abortController.abort();
+            done(undefined);
+            tui.requestRender();
+          }
+        },
+      };
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "70%",
+        maxHeight: "40%",
+        margin: 2,
+      },
+    },
+  );
+
+  if (taskError) {
+    throw taskError;
+  }
+
+  return result;
+}
+
+export function formatHandoffError(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  return "Handoff generation failed.";
+}

package/extensions/session-hooks/install.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  findPendingHandoffBootstrap,
+  getHandoffMetadataFromEntries,
+} from "../session-handoff/metadata.ts";
+import { createSessionHookController } from "../session-search/hooks.ts";
+import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
+import type { SessionSettings } from "../shared/settings.ts";
+
+export function installHooks(
+  pi: ExtensionAPI,
+  deps: { settings: SessionSettings; index: IndexHandle },
+): SessionLifecycle {
+  const controller = createSessionHookController({ indexPath: deps.index.path });
+
+  pi.on("tool_call", async (event, ctx) => {
+    controller.handleToolCall(event, ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("tool_result", async (event) => {
+    controller.handleToolResult(event);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    await controller.handleTurnEnd(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    await controller.handleSessionTree(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    await controller.handleSessionCompact(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  return {
+    async onSessionStart(event, ctx) {
+      const { reason, previousSessionFile } = event;
+      const sessionFile = ctx.sessionManager.getSessionFile();
+
+      switch (reason) {
+        case "new":
+        case "resume":
+          await controller.handleSessionSwitch(
+            previousSessionFile,
+            sessionFile,
+            ctx.cwd,
+            getSessionStartOrigin(ctx),
+          );
+          break;
+        case "fork":
+          await controller.handleSessionFork(previousSessionFile, sessionFile, ctx.cwd);
+          break;
+        default:
+          await controller.handleSessionStart(sessionFile, ctx.cwd);
+          break;
+      }
+    },
+    async onSessionShutdown(_event, ctx) {
+      await controller.handleSessionShutdown(ctx.sessionManager.getSessionFile(), ctx.cwd);
+    },
+  };
+}
+
+function getSessionStartOrigin(ctx: ExtensionContext): "handoff" | undefined {
+  const entries = ctx.sessionManager.getEntries();
+  if (getHandoffMetadataFromEntries(entries)) {
+    return "handoff";
+  }
+
+  const scan = findPendingHandoffBootstrap(ctx.sessionManager.getBranch());
+  return scan?.kind === "pending" && scan.bootstrap.sessionId === ctx.sessionManager.getSessionId()
+    ? "handoff"
+    : undefined;
+}

package/extensions/{session-index.ts → session-index/install.ts}

@@ -5,15 +5,16 @@ 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.ts";
-import { isTuiMode } from "./shared/pi-mode.ts";
-import { getIndexStatus, type SessionIndexStatus } from "./shared/session-index/index.ts";
-import { loadSettings } from "./shared/settings.ts";
+import { type ReindexResult, rebuildSessionIndex } from "../session-search/reindex.ts";
+import type { IndexHandle } from "../shared/composition.ts";
+import { isTuiMode } from "../shared/pi-mode.ts";
+import { getIndexStatus, type SessionIndexStatus } from "../shared/session-index/index.ts";
+import type { SessionSettings } from "../shared/settings.ts";
 
 type SessionIndexAction = "reindex" | undefined;
 
-export default function sessionIndexExtension(pi: ExtensionAPI): void {
-  const settings = loadSettings();
+export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings }): IndexHandle {
+  const indexPath = deps.settings.index.path;
 
   pi.registerCommand("session-index", {
     description: "Open the session index control panel",
@@ -23,7 +24,6 @@ export default function sessionIndexExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const indexPath = settings.index.path;
       const status = getIndexStatus(indexPath);
       const action = await ctx.ui.custom<SessionIndexAction>(
         (_tui, theme, _keybindings, done) => new SessionIndexPanel(theme, status, done),
@@ -62,6 +62,8 @@ export default function sessionIndexExtension(pi: ExtensionAPI): void {
       );
     },
   });
+
+  return { path: indexPath };
 }
 
 class SessionIndexPanel implements Focusable {

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

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { readFrames, writeFrame } from "../../shared/session-broker/framing.ts";
 import {
   CLIENT_FRAME_SCHEMA,
+  type OutboundSessionEnvelope,
+  type SessionEnvelope,
   type SessionMessagingClientFrame,
   type SessionMessagingIncomingAckClientFrame,
   type SessionMessagingSendClientFrame,
@@ -23,8 +25,8 @@ const pidPath = join(messagingDir, "broker.pid");
 
 interface PendingSend {
   source: Socket;
+  target: Socket;
   timeout: NodeJS.Timeout;
-  messageId: string;
   targetSessionId: string;
 }
 
@@ -119,7 +121,7 @@ function handleFrame(
       break;
 
     case "incoming_ack":
-      handleIncomingAck(message);
+      handleIncomingAck(socket, message);
       break;
   }
 }
@@ -130,13 +132,11 @@ function handleSend(
   message: SessionMessagingSendClientFrame,
 ): void {
   const source = currentSessionId ? sessions.get(currentSessionId) : undefined;
-  const { messageId } = message;
 
   if (!currentSessionId || !source) {
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
-      messageId,
       delivered: false,
       error: "Sender session is not registered.",
     });
@@ -148,8 +148,8 @@ function handleSend(
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
-      messageId,
       delivered: false,
+      reason: "no_session",
       error: resolved.error,
     });
     return;
@@ -159,9 +159,8 @@ function handleSend(
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
-      messageId,
       delivered: false,
-      error: "Cannot send a session message to the current session.",
+      error: "Cannot send a session envelope to the current session.",
     });
     return;
   }
@@ -171,34 +170,21 @@ function handleSend(
     writeFrame(socket, {
       type: "send_result",
       requestId: message.requestId,
-      messageId,
       delivered: false,
-      error: "Timed out waiting for target session to accept the message.",
+      error: "Timed out waiting for target session to accept the envelope.",
     });
   }, SEND_TIMEOUT_MS);
   pendingSends.set(message.requestId, {
     source: socket,
+    target: resolved.socket,
     timeout,
-    messageId,
     targetSessionId: resolved.sessionId,
   });
 
   writeFrame(resolved.socket, {
     type: "incoming",
     requestId: message.requestId,
-    message: {
-      messageId,
-      source: currentSessionId,
-      target: resolved.sessionId,
-      body: message.body,
-      ...(message.requestResponse === undefined
-        ? {}
-        : { requestResponse: message.requestResponse }),
-      sentAt: message.sentAt,
-      ...(message.sourceToolCallId === undefined
-        ? {}
-        : { sourceToolCallId: message.sourceToolCallId }),
-    },
+    envelope: stampEnvelope(message.envelope, currentSessionId, resolved.sessionId),
   });
 }
 
@@ -213,28 +199,35 @@ function failPendingSendsTo(targetSessionId: string): void {
     writeFrame(pending.source, {
       type: "send_result",
       requestId,
-      messageId: pending.messageId,
       delivered: false,
-      error: "Target disconnected before accepting the message.",
+      reason: "disconnected",
+      error: "Target disconnected before accepting the envelope.",
     });
   }
 }
 
-function handleIncomingAck(message: SessionMessagingIncomingAckClientFrame): void {
+function handleIncomingAck(socket: Socket, message: SessionMessagingIncomingAckClientFrame): void {
   const pending = pendingSends.get(message.requestId);
-  if (!pending) return;
+  if (!pending || pending.target !== socket) return;
 
   clearTimeout(pending.timeout);
   pendingSends.delete(message.requestId);
   writeFrame(pending.source, {
     type: "send_result",
     requestId: message.requestId,
-    messageId: message.messageId,
     delivered: message.delivered,
     ...(message.error === undefined ? {} : { error: message.error }),
   });
 }
 
+function stampEnvelope(
+  envelope: OutboundSessionEnvelope,
+  source: string,
+  target: string,
+): SessionEnvelope {
+  return { ...envelope, source, target };
+}
+
 function handleConnection(socket: Socket): void {
   let sessionId: string | undefined;
   socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);

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

@@ -34,7 +34,15 @@ export async function spawnSessionMessagingBrokerIfNeeded(): Promise<void> {
       return;
     }
 
-    const brokerPath = join(dirname(fileURLToPath(import.meta.url)), "process.ts");
+    const brokerPath = join(
+      dirname(fileURLToPath(import.meta.url)),
+      "../../../dist/session-messaging/broker/process.js",
+    );
+    if (!existsSync(brokerPath)) {
+      throw new Error(
+        `Session messaging broker build not found: ${brokerPath}. Run npm install in the pi-sessions package directory.`,
+      );
+    }
     const child = spawn(process.execPath, [brokerPath], {
       detached: true,
       stdio: "ignore",
@@ -164,15 +172,12 @@ function releaseSpawnLock(): void {
 }
 
 function brokerSpawnEnv(): NodeJS.ProcessEnv {
-  // NODE_NO_WARNINGS silences Node's experimental-TypeScript warning when the
-  // broker is launched as `node process.ts`. Redundant while stdio is ignored,
-  // but cheap insurance if that changes or an older Node revives the warning.
-  const env: NodeJS.ProcessEnv = { ...process.env, NODE_NO_WARNINGS: "1" };
+  const env: NodeJS.ProcessEnv = { ...process.env };
   // process.execPath is the Pi executable. As a Bun-compiled binary it treats a
   // positional path as a file argument to the agent, not a script to run, which
   // would relaunch a full agent session and recurse. BUN_BE_BUN makes it behave
-  // as the Bun CLI and execute process.ts directly. It is set whenever Bun is the
-  // runtime (compiled binary or `bun run`) and ignored by a plain Node launch.
+  // as the Bun CLI and execute the broker. It is set whenever Bun is the runtime
+  // (compiled binary or `bun run`) and ignored by a plain Node launch.
   if (process.versions.bun) {
     env.BUN_BE_BUN = "1";
   }

package/extensions/session-messaging/install.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
+import type { SessionSettings } from "../shared/settings.ts";
+import {
+  IncomingSessionMessageRuntime,
+  SESSION_MESSAGE_CUSTOM_TYPE,
+} from "./pi/incoming-runtime.ts";
+import { renderIncomingSessionMessage } from "./pi/renderer.ts";
+import {
+  type CancelSessionResult,
+  type IncomingCancelHandler,
+  type IncomingMessageHandler,
+  type IncomingSubagentReportHandler,
+  type SendMessageRequest,
+  type SendMessageResult,
+  type SendSubagentReportRequest,
+  type SendSubagentReportResult,
+  SessionMessagingService,
+} from "./pi/service.ts";
+
+export type {
+  CancelSessionResult,
+  SendMessageRequest,
+  SendMessageResult,
+} from "./pi/service.ts";
+
+/** The live surface the messaging feature exposes to other features (search, subagents). */
+export interface MessagingHandle {
+  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  sendSubagentReport(request: SendSubagentReportRequest): Promise<SendSubagentReportResult>;
+  cancelSession(sessionId: string): Promise<CancelSessionResult>;
+  listSessions(): Promise<string[]>;
+  waitForSession(sessionId: string, timeoutMs: number): Promise<boolean>;
+  getCachedRelationTo(sessionId: string | undefined): string | undefined;
+  onIncomingMessage(handler: IncomingMessageHandler): void;
+  onIncomingCancel(handler: IncomingCancelHandler): void;
+  onIncomingSubagentReport(handler: IncomingSubagentReportHandler): void;
+}
+
+export function installMessaging(
+  pi: ExtensionAPI,
+  deps: { settings: SessionSettings; index: IndexHandle },
+): MessagingHandle & SessionLifecycle {
+  const incomingRuntime = new IncomingSessionMessageRuntime(pi);
+  const service = new SessionMessagingService(deps.index.path);
+
+  service.onIncomingMessage((envelope) => {
+    incomingRuntime.deliver(service.buildReceivedMessage(envelope));
+  });
+  service.onIncomingCancel(() => {
+    incomingRuntime.cancel();
+  });
+
+  pi.registerMessageRenderer(SESSION_MESSAGE_CUSTOM_TYPE, renderIncomingSessionMessage);
+
+  return {
+    sendMessage: (request) => service.sendMessage(request),
+    sendSubagentReport: (request) => service.sendSubagentReport(request),
+    cancelSession: (sessionId) => service.cancelSession(sessionId),
+    listSessions: () => service.listSessions(),
+    waitForSession: (sessionId, timeoutMs) => service.waitForSession(sessionId, timeoutMs),
+    getCachedRelationTo: (sessionId) => service.getCachedRelationTo(sessionId),
+    onIncomingMessage: (handler) => service.onIncomingMessage(handler),
+    onIncomingCancel: (handler) => service.onIncomingCancel(handler),
+    onIncomingSubagentReport: (handler) => service.onIncomingSubagentReport(handler),
+    async onSessionStart(_event, ctx) {
+      incomingRuntime.bindContext(ctx);
+      incomingRuntime.replayPending(ctx);
+      try {
+        await service.start(ctx);
+      } catch {}
+    },
+    onSessionShutdown() {
+      incomingRuntime.clearContext();
+      service.stop();
+    },
+  };
+}