pi-sessions 0.10.0 → 0.11.0

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

@@ -2,18 +2,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/session-broker/framing.ts";
-import {
-  CLIENT_FRAME_SCHEMA,
-  type OutboundSessionEnvelope,
-  type SessionEnvelope,
-  type SessionMessagingClientFrame,
-  type SessionMessagingIncomingAckClientFrame,
-  type SessionMessagingSendClientFrame,
-} from "../../shared/session-broker/protocol.ts";
 import {
   getSessionMessagingDir,
   getSessionMessagingSocketPath,
 } from "../../shared/session-broker/socket-path.ts";
+import {
+  type BrokerClientFrame,
+  type IncomingAckClientFrame,
+  parseClientFrame,
+  type RoutedEnvelope,
+  type SendClientFrame,
+} from "./client-frame.ts";
 
 const SEND_TIMEOUT_MS = 10_000;
 const EXIT_IDLE_MS = 5_000;
@@ -71,7 +70,7 @@ function resolveTarget(target: string): { sessionId: string; socket: Socket } |
 
 function handleFrame(
   socket: Socket,
-  message: SessionMessagingClientFrame,
+  message: BrokerClientFrame,
   getSessionId: () => string | undefined,
   setSessionId: (sessionId: string | undefined) => void,
 ): void {
@@ -129,7 +128,7 @@ function handleFrame(
 function handleSend(
   socket: Socket,
   currentSessionId: string | undefined,
-  message: SessionMessagingSendClientFrame,
+  message: SendClientFrame,
 ): void {
   const source = currentSessionId ? sessions.get(currentSessionId) : undefined;
 
@@ -206,7 +205,7 @@ function failPendingSendsTo(targetSessionId: string): void {
   }
 }
 
-function handleIncomingAck(socket: Socket, message: SessionMessagingIncomingAckClientFrame): void {
+function handleIncomingAck(socket: Socket, message: IncomingAckClientFrame): void {
   const pending = pendingSends.get(message.requestId);
   if (!pending || pending.target !== socket) return;
 
@@ -220,11 +219,7 @@ function handleIncomingAck(socket: Socket, message: SessionMessagingIncomingAckC
   });
 }
 
-function stampEnvelope(
-  envelope: OutboundSessionEnvelope,
-  source: string,
-  target: string,
-): SessionEnvelope {
+function stampEnvelope(envelope: RoutedEnvelope, source: string, target: string): RoutedEnvelope {
   return { ...envelope, source, target };
 }
 
@@ -251,11 +246,7 @@ async function readConnection(
   setSessionId: (sessionId: string | undefined) => void,
 ): Promise<void> {
   try {
-    for await (const frame of readFrames(
-      socket,
-      CLIENT_FRAME_SCHEMA,
-      "Invalid session messaging client frame",
-    )) {
+    for await (const frame of readFrames(socket, parseClientFrame)) {
       handleFrame(socket, frame, getSessionId, setSessionId);
     }
   } catch (error) {

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

@@ -0,0 +1,59 @@
+import { type Static, Type } from "typebox";
+
+const SCOPE_SCHEMA = Type.Union([
+  Type.Literal("user"),
+  Type.Literal("branch"),
+  Type.Literal("tree"),
+]);
+
+/** Registered when subagents are active; the roster is what makes branch/tree answerable. */
+export const SESSION_REACHABLE_PARAMS = Type.Object({
+  scope: Type.Optional(
+    Type.Union([Type.Literal("user"), Type.Literal("branch"), Type.Literal("tree")], {
+      description:
+        'Which sessions to list: "user" for live user-facing sessions, "branch" for subagents launched from the active conversation branch, "tree" for subagents launched anywhere in this session\'s conversation tree. Defaults to "user".',
+    }),
+  ),
+});
+
+/** Registered when subagents are inactive; only live user sessions can ever be returned. */
+export const SESSION_REACHABLE_USER_PARAMS = Type.Object({});
+
+const REACHABLE_USER_SESSION_SCHEMA = Type.Object({
+  kind: Type.Literal("user"),
+  sessionId: Type.String(),
+  title: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+  modifiedAt: Type.Optional(Type.String()),
+  relation: Type.Optional(Type.String()),
+  state: Type.Union([Type.Literal("live"), Type.Literal("starting")]),
+});
+
+const REACHABLE_SUBAGENT_SCHEMA = Type.Object({
+  kind: Type.Literal("subagent"),
+  sessionId: Type.String(),
+  title: Type.String(),
+  goal: Type.String(),
+  cwd: Type.String(),
+  state: Type.String(),
+  depth: Type.Number(),
+  onActiveBranch: Type.Boolean(),
+  launchedAt: Type.String(),
+  model: Type.Optional(Type.String()),
+  ownerSessionId: Type.String(),
+  ownerTitle: Type.String(),
+  ownerIsCurrentSession: Type.Boolean(),
+  resumeCommand: Type.String(),
+});
+
+export const SESSION_REACHABLE_TOOL_DETAILS_SCHEMA = Type.Object({
+  scope: SCOPE_SCHEMA,
+  sessions: Type.Array(Type.Union([REACHABLE_USER_SESSION_SCHEMA, REACHABLE_SUBAGENT_SCHEMA])),
+});
+
+export type SessionReachableScope = Static<typeof SCOPE_SCHEMA>;
+export type SessionReachableParams = Static<typeof SESSION_REACHABLE_PARAMS>;
+export type ReachableUserSession = Static<typeof REACHABLE_USER_SESSION_SCHEMA>;
+export type ReachableSubagent = Static<typeof REACHABLE_SUBAGENT_SCHEMA>;
+export type ReachableSession = ReachableUserSession | ReachableSubagent;
+export type SessionReachableToolDetails = Static<typeof SESSION_REACHABLE_TOOL_DETAILS_SCHEMA>;

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

@@ -0,0 +1,49 @@
+import type { ExpandableContentPresentation } from "../../shared/rendering/expandable-content-layout.ts";
+import type { RenderTheme } from "../../shared/rendering/theme.ts";
+import type {
+  ReachableSessionRowViewModel,
+  SessionReachableViewModel,
+} from "./reachable-view-model.ts";
+
+const COLLAPSED_ROW_COUNT = 6;
+
+export function buildSessionReachablePresentation(
+  model: SessionReachableViewModel,
+  theme: RenderTheme,
+): ExpandableContentPresentation {
+  const header = theme.fg(
+    "muted",
+    `scope: ${model.scope} • ${formatSessionCount(model.rows.length)}`,
+  );
+
+  if (model.rows.length === 0) {
+    return {
+      header,
+      metadata: [theme.fg("warning", formatEmptyText(model.scope))],
+    };
+  }
+
+  return {
+    header,
+    body: {
+      text: model.rows.map((row, index) => formatRow(row, index, theme)).join("\n"),
+      collapsedRows: COLLAPSED_ROW_COUNT,
+    },
+  };
+}
+
+function formatRow(row: ReachableSessionRowViewModel, index: number, theme: RenderTheme): string {
+  const annotations =
+    row.annotations.length > 0 ? ` ${theme.fg("dim", `[${row.annotations.join(" • ")}]`)}` : "";
+  const location = row.location ? ` ${theme.fg("dim", `(${row.location})`)}` : "";
+  const heading = `${index + 1}. ${theme.bold(row.label)}${annotations}${location}`;
+  return row.detail ? `${heading}\n${theme.fg("dim", `   ${row.detail}`)}` : heading;
+}
+
+function formatSessionCount(count: number): string {
+  return count === 1 ? "1 session" : `${count} sessions`;
+}
+
+function formatEmptyText(scope: SessionReachableViewModel["scope"]): string {
+  return scope === "user" ? "No other live sessions." : "No subagents launched from this session.";
+}

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

@@ -0,0 +1,190 @@
+import {
+  defineTool,
+  type ExtensionContext,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { isSessionStarting } from "../../session-handoff/metadata.ts";
+import { formatError } from "../../shared/errors.ts";
+import { ExpandableContentLayout } from "../../shared/rendering/expandable-content-layout.ts";
+import {
+  getSessionById,
+  type SessionLineageRow,
+  withSessionIndex,
+} from "../../shared/session-index/index.ts";
+import { safeParseTypeBoxValue } from "../../shared/typebox.ts";
+import {
+  type ReachableSubagent,
+  type ReachableUserSession,
+  SESSION_REACHABLE_PARAMS,
+  SESSION_REACHABLE_TOOL_DETAILS_SCHEMA,
+  SESSION_REACHABLE_USER_PARAMS,
+  type SessionReachableParams,
+  type SessionReachableScope,
+  type SessionReachableToolDetails,
+} from "./reachable-contract.ts";
+import { buildSessionReachablePresentation } from "./reachable-presenter.ts";
+import { buildSessionReachableView } from "./reachable-view-model.ts";
+
+/** The subagent facts this tool needs; the roster satisfies it structurally. */
+export interface ReachableSubagentEntry {
+  sessionId: string;
+  title: string;
+  goal: string;
+  cwd: string;
+  state: string;
+  depth: number;
+  onActiveBranch: boolean;
+  launchedAt: string;
+  model?: string | undefined;
+  ownerSessionId: string;
+  ownerTitle: string;
+  ownerIsCurrentSession: boolean;
+  resumeCommand: string;
+}
+
+export interface SessionReachableDeps {
+  indexPath: string;
+  listSessions(): Promise<string[]>;
+  getRelationTo(sessionId: string): string | undefined;
+  listSubagents?:
+    | ((
+        scope: Exclude<SessionReachableScope, "user">,
+      ) => Promise<readonly ReachableSubagentEntry[]>)
+    | undefined;
+}
+
+interface SessionReachableRendererState {
+  layout?: ExpandableContentLayout | undefined;
+}
+
+export function createSessionReachableTool(deps: SessionReachableDeps): ToolDefinition {
+  const subagentsAvailable = Boolean(deps.listSubagents);
+
+  return defineTool({
+    name: "session_reachable",
+    label: "Reachable Sessions",
+    description: subagentsAvailable
+      ? "List the sessions this session can address: live user sessions, or its own subagents."
+      : "List the live user sessions this session can address.",
+    promptSnippet: subagentsAvailable
+      ? "List addressable live sessions and owned subagents"
+      : "List addressable live sessions",
+    promptGuidelines: [
+      "Before session_send_message, use session_reachable to find the target session id.",
+    ],
+    parameters: subagentsAvailable ? SESSION_REACHABLE_PARAMS : SESSION_REACHABLE_USER_PARAMS,
+    renderResult(result, options, theme, context) {
+      const output = result.content.find((item) => item.type === "text")?.text ?? "";
+      if (context.isError) {
+        return new Text(output ? theme.fg("error", output) : "", 0, 0);
+      }
+
+      const details = safeParseTypeBoxValue(SESSION_REACHABLE_TOOL_DETAILS_SCHEMA, result.details);
+      if (!details) {
+        return new Text(output, 0, 0);
+      }
+
+      const state = context.state as SessionReachableRendererState;
+      const layout = state.layout ?? new ExpandableContentLayout(theme);
+      state.layout = layout;
+      layout.update(
+        buildSessionReachablePresentation(buildSessionReachableView(details), theme),
+        options.expanded,
+      );
+      return layout;
+    },
+    async execute(_toolCallId, params: SessionReachableParams, _signal, _onUpdate, ctx) {
+      const scope = params.scope ?? "user";
+      const sessions =
+        scope === "user"
+          ? await listReachableUserSessions(deps, ctx)
+          : await listReachableSubagents(deps, scope);
+
+      const details: SessionReachableToolDetails = { scope, sessions };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(details, null, 2) }],
+        details,
+      };
+    },
+  });
+}
+
+async function listReachableUserSessions(
+  deps: SessionReachableDeps,
+  ctx: ExtensionContext,
+): Promise<ReachableUserSession[]> {
+  const currentSessionId = ctx.sessionManager.getSessionId();
+  let liveSessionIds: string[];
+  try {
+    liveSessionIds = await deps.listSessions();
+  } catch (error) {
+    throw new Error(`Session messaging is unavailable: ${formatError(error)}`);
+  }
+
+  const targetIds = liveSessionIds.filter((sessionId) => sessionId !== currentSessionId);
+  return withSessionIndex(deps.indexPath, { mode: "read", required: true }, ({ db }) => {
+    const sessions: ReachableUserSession[] = [];
+    for (const sessionId of targetIds) {
+      const row = getSessionById(db, sessionId);
+      if (row?.sessionOrigin === "subagent") {
+        continue;
+      }
+      const relation = deps.getRelationTo(sessionId);
+      sessions.push({
+        kind: "user",
+        sessionId,
+        state: row && isStartingSession(row) ? "starting" : "live",
+        ...(row?.sessionName ? { title: row.sessionName } : {}),
+        ...(row?.cwd ? { cwd: row.cwd } : {}),
+        ...(row?.modifiedAt ? { modifiedAt: row.modifiedAt } : {}),
+        ...(relation === undefined ? {} : { relation }),
+      });
+    }
+    return sessions.sort(compareByModifiedDesc);
+  });
+}
+
+async function listReachableSubagents(
+  deps: SessionReachableDeps,
+  scope: Exclude<SessionReachableScope, "user">,
+): Promise<ReachableSubagent[]> {
+  if (!deps.listSubagents) {
+    throw new Error(`session_reachable scope "${scope}" requires subagents to be active.`);
+  }
+
+  try {
+    const entries = await deps.listSubagents(scope);
+    return entries.map((entry) => ({
+      kind: "subagent",
+      sessionId: entry.sessionId,
+      title: entry.title,
+      goal: entry.goal,
+      cwd: entry.cwd,
+      state: entry.state,
+      depth: entry.depth,
+      onActiveBranch: entry.onActiveBranch,
+      launchedAt: entry.launchedAt,
+      ...(entry.model === undefined ? {} : { model: entry.model }),
+      ownerSessionId: entry.ownerSessionId,
+      ownerTitle: entry.ownerTitle,
+      ownerIsCurrentSession: entry.ownerIsCurrentSession,
+      resumeCommand: entry.resumeCommand,
+    }));
+  } catch (error) {
+    throw new Error(`Subagent roster is unavailable: ${formatError(error)}`);
+  }
+}
+
+function isStartingSession(row: SessionLineageRow): boolean {
+  try {
+    return isSessionStarting(SessionManager.open(row.sessionPath).getBranch());
+  } catch {
+    return false;
+  }
+}
+
+function compareByModifiedDesc(left: ReachableUserSession, right: ReachableUserSession): number {
+  return (right.modifiedAt ?? "").localeCompare(left.modifiedAt ?? "");
+}

package/extensions/session-messaging/pi/reachable-view-model.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { formatSessionTitleOrShortId } from "../../shared/session-ui.ts";
+import { normalizeOptionalText } from "../../shared/text.ts";
+import type {
+  ReachableSession,
+  SessionReachableScope,
+  SessionReachableToolDetails,
+} from "./reachable-contract.ts";
+
+export interface ReachableSessionRowViewModel {
+  label: string;
+  sessionId: string;
+  annotations: string[];
+  location?: string | undefined;
+  detail?: string | undefined;
+}
+
+export interface SessionReachableViewModel {
+  scope: SessionReachableScope;
+  rows: ReachableSessionRowViewModel[];
+}
+
+export function buildSessionReachableView(
+  details: SessionReachableToolDetails,
+): SessionReachableViewModel {
+  return {
+    scope: details.scope,
+    rows: details.sessions.map(buildReachableSessionRow),
+  };
+}
+
+function buildReachableSessionRow(session: ReachableSession): ReachableSessionRowViewModel {
+  if (session.kind === "user") {
+    return {
+      label: formatSessionTitleOrShortId(session.title, session.sessionId),
+      sessionId: session.sessionId,
+      annotations: [session.state, ...(session.relation ? [session.relation] : [])],
+      location: formatLocation(session.cwd),
+    };
+  }
+
+  return {
+    label: formatSessionTitleOrShortId(session.title, session.sessionId),
+    sessionId: session.sessionId,
+    annotations: [
+      session.state,
+      `depth ${session.depth}`,
+      ...(session.onActiveBranch ? [] : ["history"]),
+      ...(session.ownerIsCurrentSession ? [] : [`owner ${session.ownerTitle}`]),
+    ],
+    location: formatLocation(session.cwd),
+    detail: normalizeOptionalText(session.goal),
+  };
+}
+
+function formatLocation(cwd: string | undefined): string | undefined {
+  if (!cwd) return undefined;
+  return path.basename(cwd) || cwd;
+}

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

@@ -17,7 +17,7 @@ export const renderIncomingSessionMessage: MessageRenderer = (message, options,
     buildIncomingMessagePresentation(buildIncomingMessageView(details), theme),
     options.expanded,
   );
-  const box = new Box(1, 1, (text) => theme.bg("toolSuccessBg", text));
+  const box = new Box(options.outputPad, 1, (text) => theme.bg("toolSuccessBg", text));
   box.addChild(layout);
   return box;
 };

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

@@ -66,13 +66,8 @@ export function createSessionSendMessageTool(
     ? "Send a message to another pi session or a subagent"
     : "Send a message to another live pi session";
   const promptGuidelines = options.wakeCapable
-    ? [
-        "Use session_search with live: true to discover live sessions.",
-        "It is always possible to session_send_message to an owned subagent",
-      ]
-    : [
-        "Before session_send_message, use session_search with live: true to list all live sessions and find the target.",
-      ];
+    ? ["Use session_reachable to discover live sessions and owned subagents."]
+    : ["Use session_reachable to list live sessions and find the target."];
 
   return defineTool({
     name: "session_send_message",
@@ -194,7 +189,12 @@ export function createSessionCancelTool(service: CancelSessionService): ToolDefi
           throw new Error(buildUnknownCancellationError(result.target));
         }
         return {
-          content: [{ type: "text" as const, text: buildCancelSessionModelText(details) }],
+          content: [
+            {
+              type: "text" as const,
+              text: buildCancelSessionModelText(details),
+            },
+          ],
           details,
         };
       }

package/extensions/session-search/hooks.ts

@@ -228,7 +228,7 @@ function syncSessionFileWithDb(
   const stat = statSync(sessionFile);
 
   if (baseline && isIndexCurrent(baseline, stat, sessionOrigin)) {
-    db.transaction(() => writeHookSyncMetadata(db, eventType)).immediate();
+    db.transaction(() => writeHookSyncMetadata(db, eventType));
     return true;
   }
 
@@ -279,11 +279,6 @@ function isIndexCurrent(
   );
 }
 
-// All write transactions are immediate: they read before they write, and a
-// deferred transaction whose snapshot goes stale fails with SQLITE_BUSY on the
-// read-to-write upgrade without ever invoking the busy handler. Immediate mode
-// takes the write lock at BEGIN, where busy_timeout queues us behind concurrent
-// writers from other pi processes.
 function applyFullSync(
   db: SessionIndexDatabase,
   extracted: ExtractedSessionRecord,
@@ -312,7 +307,7 @@ function applyFullSync(
     }
 
     writeHookSyncMetadata(db, eventType);
-  }).immediate();
+  });
 }
 
 function applyTailSync(
@@ -322,60 +317,58 @@ function applyTailSync(
   eventType: string,
   sessionOrigin?: SessionOrigin,
 ): boolean {
-  return db
-    .transaction((): boolean => {
-      // Another process may have advanced the index between our baseline read
-      // and this transaction; the tail deltas would then double-count.
-      const current = getSessionRowByPath(db, baseline.sessionPath);
-      if (
-        !current ||
-        current.sessionId !== baseline.sessionId ||
-        current.indexedFileSize !== baseline.indexedFileSize
-      ) {
-        return false;
-      }
+  return db.transaction((): boolean => {
+    // Another process may have advanced the index between our baseline read
+    // and this transaction; the tail deltas would then double-count.
+    const current = getSessionRowByPath(db, baseline.sessionPath);
+    if (
+      !current ||
+      current.sessionId !== baseline.sessionId ||
+      current.indexedFileSize !== baseline.indexedFileSize
+    ) {
+      return false;
+    }
 
-      const scan = tail.scan;
-      upsertSession(db, buildTailSessionRow(baseline, tail, sessionOrigin), "hook");
-
-      if (scan.sessionName !== undefined && scan.sessionName !== baseline.sessionName) {
-        clearSessionChunksBySourceKind(db, baseline.sessionId, "session_name");
-        if (scan.sessionName && scan.sessionNameEntryId) {
-          insertTextChunk(db, {
-            sessionId: baseline.sessionId,
-            ...createSessionNameChunk(
-              scan.sessionName,
-              scan.sessionNameTs ?? baseline.startedAt,
-              scan.sessionNameEntryId,
-            ),
-          });
-        }
-      }
+    const scan = tail.scan;
+    upsertSession(db, buildTailSessionRow(baseline, tail, sessionOrigin), "hook");
 
-      if (!baseline.handoffGoal && scan.handoffMetadata) {
-        const { entryId, ts, metadata } = scan.handoffMetadata;
+    if (scan.sessionName !== undefined && scan.sessionName !== baseline.sessionName) {
+      clearSessionChunksBySourceKind(db, baseline.sessionId, "session_name");
+      if (scan.sessionName && scan.sessionNameEntryId) {
         insertTextChunk(db, {
           sessionId: baseline.sessionId,
-          entryId,
-          entryType: "custom",
-          ts,
-          sourceKind: "handoff_goal",
-          text: metadata.goal,
+          ...createSessionNameChunk(
+            scan.sessionName,
+            scan.sessionNameTs ?? baseline.startedAt,
+            scan.sessionNameEntryId,
+          ),
         });
       }
+    }
 
-      for (const chunk of scan.chunks) {
-        insertTextChunk(db, { sessionId: baseline.sessionId, ...chunk });
-      }
+    if (!baseline.handoffGoal && scan.handoffMetadata) {
+      const { entryId, ts, metadata } = scan.handoffMetadata;
+      insertTextChunk(db, {
+        sessionId: baseline.sessionId,
+        entryId,
+        entryType: "custom",
+        ts,
+        sourceKind: "handoff_goal",
+        text: metadata.goal,
+      });
+    }
 
-      for (const fileTouch of scan.fileTouches) {
-        insertSessionFileTouch(db, { sessionId: baseline.sessionId, ...fileTouch });
-      }
+    for (const chunk of scan.chunks) {
+      insertTextChunk(db, { sessionId: baseline.sessionId, ...chunk });
+    }
 
-      writeHookSyncMetadata(db, eventType);
-      return true;
-    })
-    .immediate();
+    for (const fileTouch of scan.fileTouches) {
+      insertSessionFileTouch(db, { sessionId: baseline.sessionId, ...fileTouch });
+    }
+
+    writeHookSyncMetadata(db, eventType);
+    return true;
+  });
 }
 
 function buildTailSessionRow(