pi-sessions 0.14.3 → 0.16.0

package/extensions/session-handoff/tool-schema.ts

@@ -1,6 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { type HandoffLaunchTarget, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import { type HandoffLaunchTarget, LAUNCH_DIRECTIONS, SUBAGENT_LAUNCH } from "./launch-target.ts";
 import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
@@ -46,11 +46,19 @@ export function buildHandoffPromptGuidelines(
   roster: HandoffRoster | undefined,
 ): string[] {
   const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
+  const hasHost = targets.some(
+    (target) =>
+      target.value !== "subagent" &&
+      target.value !== "deferred" &&
+      !LAUNCH_DIRECTIONS.some((direction) => direction === target.value),
+  );
   const selectable =
     roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
-    LAUNCH_TARGET_GUIDELINE,
+    hasHost
+      ? "Use session_handoff host or deferred launches only when the user requests one."
+      : LAUNCH_TARGET_GUIDELINE,
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
     ...(selectable.length > 0

package/extensions/session-handoff/tool.ts

@@ -108,6 +108,7 @@ export async function executeSessionHandoffTool(
     title,
     model,
     approveProjectTrust: target.approveProjectTrust,
+    useDefaultSessionDir: target.useDefaultSessionDir ?? false,
     buildBootstrap: (sessionId) =>
       createChildGeneratedHandoffBootstrap({
         sessionId,

package/extensions/session-hooks/install.ts

@@ -3,28 +3,37 @@ import {
   findPendingHandoffBootstrap,
   getHandoffMetadataFromEntries,
 } from "../session-handoff/metadata.ts";
-import { createSessionHookController } from "../session-search/hooks.ts";
 import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
+import { requestIndexRecovery } from "../shared/session-index/recovery.ts";
+import { createSessionHookController } from "../shared/session-index/sync.ts";
 
-export function installHooks(pi: ExtensionAPI, deps: { index: IndexHandle }): SessionLifecycle {
+export function installHooks(
+  pi: ExtensionAPI,
+  deps: { index: IndexHandle; turnSync: boolean },
+): SessionLifecycle {
   const controller = createSessionHookController({ indexPath: deps.index.path });
 
   pi.on("turn_end", async (_event, ctx) => {
-    await controller.handleTurnEnd(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleTurnEnd(ctx.sessionManager.getSessionFile());
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    await controller.handleSessionTree(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleSessionTree(ctx.sessionManager.getSessionFile());
   });
 
   pi.on("session_compact", async (_event, ctx) => {
-    await controller.handleSessionCompact(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleSessionCompact(ctx.sessionManager.getSessionFile());
   });
 
   return {
     async onSessionStart(event, ctx) {
       const { reason, previousSessionFile } = event;
       const sessionFile = ctx.sessionManager.getSessionFile();
+      void requestIndexRecovery(deps.index.path, true)
+        .then(() => controller.handleSessionStart(ctx.sessionManager.getSessionFile()))
+        .catch((error: unknown) =>
+          ctx.ui.notify(`Session index sync failed: ${String(error)}`, "error"),
+        );
 
       switch (reason) {
         case "new":

package/extensions/session-index/install.ts

@@ -1,15 +1,24 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { type ReindexResult, rebuildSessionIndex } from "../session-search/reindex.ts";
-import type { IndexHandle } from "../shared/composition.ts";
+import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
 import { isTuiMode } from "../shared/pi-mode.ts";
 import { getIndexStatus } from "../shared/session-index/index.ts";
+import {
+  getIndexRecoveryMessage,
+  observeIndexRecovery,
+  type ReindexResult,
+  rebuildSessionIndex,
+} from "../shared/session-index/recovery.ts";
 import type { SessionSettings } from "../shared/settings.ts";
 
 import { ReindexLoader } from "./loader.ts";
 import { type SessionIndexAction, SessionIndexPanel } from "./panel.ts";
 
-export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings }): IndexHandle {
+export function installIndex(
+  pi: ExtensionAPI,
+  deps: { settings: SessionSettings },
+): IndexHandle & SessionLifecycle {
   const indexPath = deps.settings.index.path;
+  let lastNotice: string | undefined;
 
   pi.registerCommand("session-index", {
     description: "Open the session index control panel",
@@ -20,6 +29,7 @@ export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings
       }
 
       const status = getIndexStatus(indexPath);
+      status.recoveryMessage = getIndexRecoveryMessage(indexPath);
       const action = await ctx.ui.custom<SessionIndexAction>(
         (tui, theme, _keybindings, done) =>
           new SessionIndexPanel(theme, status, done, () => tui.requestRender()),
@@ -59,7 +69,18 @@ export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings
     },
   });
 
-  return { path: indexPath };
+  return {
+    path: indexPath,
+    onSessionStart(_event, ctx) {
+      observeIndexRecovery(indexPath, (message) => {
+        ctx.ui.setStatus("session-index", message);
+        if (message && message !== lastNotice && !message.includes("in progress")) {
+          ctx.ui.notify(message, "error");
+        }
+        lastNotice = message;
+      });
+    },
+  };
 }
 
 async function runReindexWithLoader(

package/extensions/session-index/panel.ts

@@ -6,6 +6,7 @@ import {
   type TuiMouseEventResult,
   truncateToWidth,
   visibleWidth,
+  wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import { type LegendHit, LegendPointer, layoutLegend, legendHitAt } from "../shared/legend.ts";
 import type { SessionIndexStatus } from "../shared/session-index/index.ts";
@@ -73,6 +74,14 @@ export class SessionIndexPanel implements Focusable {
     lines.push(
       this.renderRow(innerWidth, ` Last full reindex: ${this.status.lastFullReindexAt ?? "n/a"}`),
     );
+    if (this.status.recoveryMessage) {
+      for (const line of wrapTextWithAnsi(
+        this.status.recoveryMessage,
+        Math.max(1, innerWidth - 2),
+      )) {
+        lines.push(this.renderRow(innerWidth, ` ${this.theme.fg("warning", line)}`));
+      }
+    }
     lines.push(this.renderRow(innerWidth, ""));
     this.renderAction(lines, innerWidth, "R", "rebuild from disk", () => this.done("reindex"));
     this.renderAction(lines, innerWidth, "Enter / Esc", "close", () => this.done(undefined));

package/extensions/session-messaging/message-router.ts

@@ -0,0 +1,91 @@
+import type { SendMessageRequest, SendMessageResult } from "./install.ts";
+
+export interface SessionWaker {
+  owns(target: string): boolean | Promise<boolean>;
+  wake(target: string): Promise<void>;
+  restart?(target: string): Promise<void>;
+  afterSend?(): Promise<void> | void;
+}
+
+export interface WakeMessaging {
+  sendMessage(request: SendMessageRequest): Promise<SendMessageResult>;
+  listSessions(): Promise<string[]>;
+  waitForSession(sessionId: string, timeoutMs: number): Promise<boolean>;
+}
+
+export class MessageRouter {
+  private readonly waking = new Map<string, Promise<void>>();
+
+  constructor(
+    private readonly messaging: WakeMessaging,
+    private readonly wakers: readonly SessionWaker[],
+    private readonly getEpoch: () => number,
+    private readonly readyTimeoutMs = 30_000,
+  ) {}
+
+  async sendMessage(request: SendMessageRequest): Promise<SendMessageResult> {
+    const epoch = this.getEpoch();
+    let failedLiveSend: SendMessageResult | undefined;
+    if (await this.isLive(request.target)) {
+      this.requireCurrent(epoch);
+      const result = await this.messaging.sendMessage(request);
+      if (!isTargetDeparture(result)) return result;
+      failedLiveSend = result;
+    }
+    let owner: SessionWaker | undefined;
+    for (const waker of this.wakers) {
+      if (await waker.owns(request.target)) {
+        owner = waker;
+        break;
+      }
+    }
+    this.requireCurrent(epoch);
+    if (!owner) return failedLiveSend ?? this.messaging.sendMessage(request);
+
+    try {
+      for (let attempt = 0; ; attempt += 1) {
+        await this.wake(request.target, owner, epoch);
+        this.requireCurrent(epoch);
+        const result = await this.messaging.sendMessage(request);
+        if (attempt === 1 || !isTargetDeparture(result)) return result;
+      }
+    } finally {
+      if (epoch === this.getEpoch()) await owner.afterSend?.();
+    }
+  }
+
+  private wake(target: string, waker: SessionWaker, epoch: number): Promise<void> {
+    const key = `${epoch}:${target}`;
+    const existing = this.waking.get(key);
+    if (existing) return existing;
+    const wake = this.ensureReady(target, waker, epoch).finally(() => this.waking.delete(key));
+    this.waking.set(key, wake);
+    return wake;
+  }
+
+  private async ensureReady(target: string, waker: SessionWaker, epoch: number): Promise<void> {
+    if (await this.isLive(target)) return;
+    this.requireCurrent(epoch);
+    await waker.wake(target);
+    if (await this.messaging.waitForSession(target, this.readyTimeoutMs)) return;
+    this.requireCurrent(epoch);
+    if (waker.restart) {
+      await waker.restart(target);
+      if (await this.messaging.waitForSession(target, this.readyTimeoutMs)) return;
+    }
+    throw new Error(`Session ${target} did not register for messaging.`);
+  }
+
+  private async isLive(target: string): Promise<boolean> {
+    return (await this.messaging.listSessions()).includes(target);
+  }
+
+  private requireCurrent(epoch: number): void {
+    if (epoch !== this.getEpoch())
+      throw new Error("The current session changed while waking a session.");
+  }
+}
+
+function isTargetDeparture(result: SendMessageResult): boolean {
+  return !result.delivered && (result.reason === "no_session" || result.reason === "disconnected");
+}

package/extensions/session-messaging/pi/reachable-contract.ts

@@ -26,7 +26,8 @@ const REACHABLE_USER_SESSION_SCHEMA = Type.Object({
   cwd: Type.Optional(Type.String()),
   modifiedAt: Type.Optional(Type.String()),
   relation: Type.Optional(Type.String()),
-  state: Type.Union([Type.Literal("live"), Type.Literal("starting")]),
+  host: Type.Optional(Type.String()),
+  state: Type.Union([Type.Literal("live"), Type.Literal("starting"), Type.Literal("dormant")]),
 });
 
 const REACHABLE_SUBAGENT_SCHEMA = Type.Object({

package/extensions/session-messaging/pi/reachable-tool.ts

@@ -5,6 +5,7 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import type { HostedSession } from "../../hosts/contract.ts";
 import { isSessionStarting } from "../../session-handoff/metadata.ts";
 import { formatError } from "../../shared/errors.ts";
 import { ExpandableContentLayout } from "../../shared/rendering/expandable-content-layout.ts";
@@ -46,7 +47,9 @@ export interface ReachableSubagentEntry {
 
 export interface SessionReachableDeps {
   indexPath: string;
+  hostedSessions?: boolean;
   listSessions(): Promise<string[]>;
+  listHostedSessions?: () => Promise<HostedSession[]>;
   getRelationTo(sessionId: string): string | undefined;
   listSubagents?:
     | ((
@@ -75,6 +78,11 @@ export function createSessionReachableTool(deps: SessionReachableDeps): ToolDefi
       : "List addressable live sessions",
     promptGuidelines: [
       "Before session_send_message, use session_reachable to find the target session id.",
+      ...(deps.hostedSessions
+        ? [
+            "User sessions include dormant hosted sessions. session_send_message wakes them automatically; the host field identifies their host.",
+          ]
+        : []),
     ],
     annotations: { readOnlyHint: true, openWorldHint: false },
     parameters: subagentsAvailable ? SESSION_REACHABLE_PARAMS : SESSION_REACHABLE_USER_PARAMS,
@@ -129,7 +137,11 @@ async function listReachableUserSessions(
   }
 
   const parentSessionId = deps.getParentSessionId?.();
-  const targetIds = liveSessionIds.filter(
+  const hostedSessions = new Map(
+    ((await deps.listHostedSessions?.()) ?? []).map((session) => [session.sessionId, session]),
+  );
+  const liveIds = new Set(liveSessionIds);
+  const targetIds = [...new Set([...liveSessionIds, ...hostedSessions.keys()])].filter(
     (sessionId) => sessionId !== currentSessionId && sessionId !== parentSessionId,
   );
   return withSessionIndex(deps.indexPath, { mode: "read", required: true }, ({ db }) => {
@@ -140,12 +152,20 @@ async function listReachableUserSessions(
         continue;
       }
       const relation = deps.getRelationTo(sessionId);
+      const hosted = hostedSessions.get(sessionId);
+      const title = hosted?.title ?? row?.sessionName;
+      const cwd = hosted?.cwd ?? row?.cwd;
       sessions.push({
         kind: "user",
         sessionId,
-        state: row && isStartingSession(row) ? "starting" : "live",
-        ...(row?.sessionName ? { title: row.sessionName } : {}),
-        ...(row?.cwd ? { cwd: row.cwd } : {}),
+        state: !liveIds.has(sessionId)
+          ? "dormant"
+          : row && isStartingSession(row)
+            ? "starting"
+            : "live",
+        ...(hosted ? { host: hosted.host } : {}),
+        ...(title ? { title } : {}),
+        ...(cwd ? { cwd } : {}),
         ...(row?.modifiedAt ? { modifiedAt: row.modifiedAt } : {}),
         ...(relation === undefined ? {} : { relation }),
       });

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

@@ -53,6 +53,7 @@ export type SessionSendMessageRole =
 
 export interface SessionSendMessageToolOptions {
   role: SessionSendMessageRole;
+  hostedSessions?: boolean;
   getCachedRelationTo(sessionId: string | undefined): string | undefined;
   /**
    * Resolved on every call: subagent identity depends on the active branch, so a rewind can
@@ -119,7 +120,14 @@ export function createSessionSendMessageTool(
     label: "Send Message to Session",
     description,
     promptSnippet,
-    promptGuidelines,
+    promptGuidelines: [
+      ...promptGuidelines,
+      ...(options.hostedSessions
+        ? [
+            "session_reachable also lists dormant hosted sessions; sending a message wakes them automatically.",
+          ]
+        : []),
+    ],
     parameters: SEND_MESSAGE_PARAMS,
     renderCall(args, theme, context) {
       const state = context.state as SendMessageRendererState;

package/extensions/shared/session-index/access.ts

@@ -6,6 +6,13 @@ import {
   type SessionIndexDatabase,
   type SessionIndexStatus,
 } from "./common.ts";
+import {
+  acquireIndexLock,
+  disableOlderIndexClient,
+  getIndexRecoveryMessage,
+  isIndexClientDisabled,
+  requestIndexRecovery,
+} from "./recovery.ts";
 import { getMetadata, openIndexDatabase } from "./schema.ts";
 
 export type SessionIndexOpenMode = "read" | "write";
@@ -67,28 +74,57 @@ function openValidatedSessionIndexInternal(
   indexPath: string,
   options: WithSessionIndexOptions,
 ): ValidSessionIndex | undefined {
+  if (isIndexClientDisabled(indexPath)) return handleUnavailableIndex(indexPath, options);
   if (!existsSync(indexPath)) {
     return handleUnavailableIndex(indexPath, options);
   }
 
   let db: SessionIndexDatabase | undefined;
+  let release: (() => void) | undefined;
   try {
+    if (options.mode === "write") {
+      release = acquireIndexLock(indexPath);
+      if (!release) return handleUnavailableIndex(indexPath, options);
+    }
     db = openIndexDatabase(indexPath, {
       create: false,
-      mode: options.mode,
+      mode: "read",
       ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     });
-    const status = getIndexStatusFromDb(indexPath, db);
-    if (status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    const version = Number(getMetadata(db, "schema_version"));
+    if (version !== INDEX_SCHEMA_VERSION) {
       const invalidDb = db;
       db = undefined;
       invalidDb.close();
+      release?.();
+      release = undefined;
+      if (version > INDEX_SCHEMA_VERSION) disableOlderIndexClient(indexPath);
       return handleUnavailableIndex(indexPath, options);
     }
-
+    const status = getIndexStatusFromDb(indexPath, db);
+    if (options.mode === "write") {
+      db.close();
+      db = undefined;
+      db = openIndexDatabase(indexPath, {
+        create: false,
+        mode: "write",
+        timeoutMs: options.timeoutMs,
+      });
+      const close = db.close;
+      const unlock = release;
+      db.close = () => {
+        try {
+          close();
+        } finally {
+          unlock?.();
+        }
+      };
+      release = undefined;
+    }
     return { db, status };
   } catch (error) {
     db?.close();
+    release?.();
     return handleUnavailableIndex(indexPath, options, error);
   }
 }
@@ -112,7 +148,7 @@ export function getIndexStatusFromDb(dbPath: string, db: SessionIndexDatabase):
 }
 
 export function formatRequiredSessionIndexError(indexPath: string): string {
-  return `Session index missing or incompatible at ${indexPath}. Run /session-index and press r to rebuild it.`;
+  return getIndexRecoveryMessage(indexPath) ?? "Session indexing in progress; try again shortly.";
 }
 
 function handleUnavailableIndex(
@@ -120,6 +156,7 @@ function handleUnavailableIndex(
   options: WithSessionIndexOptions,
   cause?: unknown,
 ): undefined {
+  if (!isIndexClientDisabled(indexPath)) void requestIndexRecovery(indexPath);
   if (!options.required) {
     return undefined;
   }

package/extensions/shared/session-index/common.ts

@@ -148,6 +148,7 @@ export interface SessionIndexStatus {
   schemaVersion?: number | undefined;
   sessionCount?: number | undefined;
   lastFullReindexAt?: string | undefined;
+  recoveryMessage?: string | undefined;
 }
 
 export type SessionIndexDatabase = SqliteDatabase;