pi-sessions 0.9.0 → 0.11.0

package/extensions/session-messaging/broker/client-frame.ts

@@ -0,0 +1,113 @@
+// The broker runs as a detached raw-Node process with nothing installed next to
+// it, so client frames are validated by hand rather than against the TypeBox
+// schemas in shared/session-broker/protocol.ts. The broker only routes
+// envelopes, so it validates the routing fields and treats `envelope` as an
+// opaque object; the receiving client validates the envelope body in full.
+
+export interface RoutedEnvelope {
+  [key: string]: unknown;
+}
+
+export interface RegisterClientFrame {
+  type: "register";
+  sessionId: string;
+}
+
+export interface UnregisterClientFrame {
+  type: "unregister";
+}
+
+export interface ListClientFrame {
+  type: "list";
+  requestId: string;
+}
+
+export interface SendClientFrame {
+  type: "send";
+  requestId: string;
+  target: string;
+  envelope: RoutedEnvelope;
+}
+
+export interface IncomingAckClientFrame {
+  type: "incoming_ack";
+  requestId: string;
+  delivered: boolean;
+  error?: string;
+}
+
+export type BrokerClientFrame =
+  | RegisterClientFrame
+  | UnregisterClientFrame
+  | ListClientFrame
+  | SendClientFrame
+  | IncomingAckClientFrame;
+
+const CONTEXT = "Invalid session messaging client frame";
+
+export function parseClientFrame(value: unknown): BrokerClientFrame {
+  const frame = requireObject(value, "/");
+
+  switch (frame.type) {
+    case "register":
+      return { type: "register", sessionId: requireString(frame.sessionId, "/sessionId") };
+    case "unregister":
+      return { type: "unregister" };
+    case "list":
+      return { type: "list", requestId: requireString(frame.requestId, "/requestId") };
+    case "send":
+      return {
+        type: "send",
+        requestId: requireString(frame.requestId, "/requestId"),
+        target: requireString(frame.target, "/target"),
+        envelope: requireObject(frame.envelope, "/envelope"),
+      };
+    case "incoming_ack": {
+      const error = optionalString(frame.error, "/error");
+      return {
+        type: "incoming_ack",
+        requestId: requireString(frame.requestId, "/requestId"),
+        delivered: requireBoolean(frame.delivered, "/delivered"),
+        ...(error === undefined ? {} : { error }),
+      };
+    }
+    default:
+      throw invalid("/type", "expected a known client frame type");
+  }
+}
+
+function requireObject(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalid(path, "expected an object");
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, path: string): string {
+  if (typeof value !== "string") {
+    throw invalid(path, "expected a string");
+  }
+
+  return value;
+}
+
+function requireBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== "boolean") {
+    throw invalid(path, "expected a boolean");
+  }
+
+  return value;
+}
+
+function optionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return requireString(value, path);
+}
+
+function invalid(path: string, message: string): Error {
+  return new Error(`${CONTEXT}: ${path} ${message}`);
+}

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/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/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,
         };
       }