pi-sessions 0.5.1 → 0.6.0

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

@@ -0,0 +1,144 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { SEND_MESSAGE_PARAMS, type SendMessageParams } from "./message-contracts.ts";
+import { formatSendMessageCall } from "./message-view.ts";
+import type { LiveSessionRow, SessionMessagingService } from "./service.ts";
+
+interface ListLiveDetails {
+  error?: boolean | undefined;
+  sessions: LiveSessionRow[];
+}
+
+export function registerSessionMessagingTools(
+  pi: ExtensionAPI,
+  service: SessionMessagingService,
+): void {
+  pi.registerTool({
+    name: "session_list_live",
+    label: "List Live Pi Sessions",
+    description: "List other Pi sessions that are currently active.",
+    promptSnippet: "List other Pi sessions that are currently active.",
+    parameters: Type.Object({}),
+    renderResult(result, _options, theme, context) {
+      if (context.isError) {
+        return new Text(`\n${theme.fg("error", getFirstText(result))}`, 0, 0);
+      }
+
+      const details = result.details as ListLiveDetails | undefined;
+      return new Text(`\n${formatLiveSessionsForDisplay(details?.sessions ?? [], theme)}`, 0, 0);
+    },
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      try {
+        const sessions = await service.listLiveSessions(ctx);
+        return {
+          content: [{ type: "text" as const, text: formatLiveSessions(sessions) }],
+          details: { sessions } satisfies ListLiveDetails,
+        };
+      } catch (error) {
+        throw new Error(formatError(error));
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "session_send_message",
+    label: "Send Message to Session",
+    description: "Send a message to another live pi session",
+    promptSnippet: "Send a message to another live pi session",
+    promptGuidelines: ["Use session_list_live to discover targetable sessions."],
+    parameters: SEND_MESSAGE_PARAMS,
+    renderCall(args, theme, context) {
+      const component = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      component.setText(
+        formatSendMessageCall(
+          args,
+          context.expanded,
+          "sending",
+          theme,
+          service.getCachedRelationTo(args?.session),
+        ),
+      );
+      return component;
+    },
+    renderResult(result, _options, theme, context) {
+      if (!context.isError) {
+        return new Text("", 0, 0);
+      }
+
+      const output = getFirstText(result);
+      return new Text(output ? `\n${theme.fg("error", output)}` : "", 0, 0);
+    },
+    async execute(toolCallId, params: SendMessageParams, _signal, _onUpdate, _ctx) {
+      const target = params.session.trim();
+      if (!target) {
+        throw new Error("session_send_message requires a target session id.");
+      }
+      if (target.startsWith("@session:")) {
+        throw new Error("Use the bare session UUID, not an @session token.");
+      }
+
+      const body = params.message.trim();
+      if (!body) {
+        throw new Error("session_send_message requires a non-empty message.");
+      }
+
+      try {
+        const result = await service.sendMessage({
+          target,
+          body,
+          requestResponse: params.requestResponse,
+          sourceToolCallId: toolCallId,
+        });
+        if (!result.delivered) {
+          throw new Error(result.error ?? "Message was not delivered.");
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Message delivered to ${target}.`,
+            },
+          ],
+          details: {
+            delivered: true,
+            messageId: result.messageId,
+            targetSessionId: target,
+          },
+        };
+      } catch (error) {
+        throw new Error(formatError(error));
+      }
+    },
+  });
+}
+
+function formatLiveSessions(sessions: LiveSessionRow[]): string {
+  return JSON.stringify({ sessions }, null, 2);
+}
+
+function formatLiveSessionsForDisplay(
+  sessions: LiveSessionRow[],
+  theme: { fg(token: string, text: string): string },
+): string {
+  if (sessions.length === 0) {
+    return "No other live sessions found.";
+  }
+
+  return sessions
+    .map((session) => {
+      const title = session.sessionName?.trim() || "[untitled]";
+      const relation = session.relation ? ` (${session.relation})` : "";
+      return `${session.sessionId}${relation} - ${title}\n${theme.fg("dim", session.cwd)}`;
+    })
+    .join("\n\n");
+}
+
+function getFirstText(result: { content: Array<{ type: string; text?: string }> }): string {
+  return result.content.find((item) => item.type === "text")?.text ?? "";
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error && error.message.trim() ? error.message : String(error);
+}

package/extensions/session-messaging/shared/framing.ts

@@ -0,0 +1,72 @@
+import type { Socket } from "node:net";
+import { createInterface } from "node:readline";
+import type { Static, TSchema } from "typebox";
+import { parseTypeBoxValue } from "../../shared/typebox.ts";
+
+const MAX_FRAME_BYTES = 256 * 1024;
+
+export function writeFrame<T>(socket: Socket, frame: T): void {
+  socket.write(`${JSON.stringify(frame)}\n`);
+}
+
+export async function* readFrames<T extends TSchema>(
+  socket: Socket,
+  schema: T,
+  context: string,
+): AsyncGenerator<Static<T>> {
+  const reader = createInterface({ input: socket, crlfDelay: Number.POSITIVE_INFINITY });
+  const lines: string[] = [];
+  const waiters: Array<() => void> = [];
+  let error: Error | undefined;
+  let closed = false;
+
+  const wake = (): void => {
+    const waiter = waiters.shift();
+    waiter?.();
+  };
+
+  reader.on("line", (line) => {
+    lines.push(line);
+    wake();
+  });
+  reader.on("error", (nextError) => {
+    error = nextError instanceof Error ? nextError : new Error(String(nextError));
+    closed = true;
+    wake();
+  });
+  reader.on("close", () => {
+    closed = true;
+    wake();
+  });
+
+  try {
+    while (true) {
+      while (lines.length === 0 && !closed) {
+        await new Promise<void>((resolve) => waiters.push(resolve));
+      }
+
+      const line = lines.shift();
+      if (line === undefined) {
+        if (error) {
+          throw error;
+        }
+        return;
+      }
+
+      if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+        throw new Error("Session messaging frame exceeds maximum size.");
+      }
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line) as unknown;
+      } catch (parseError) {
+        throw parseError instanceof Error ? parseError : new Error(String(parseError));
+      }
+
+      yield parseTypeBoxValue(schema, parsed, context);
+    }
+  } finally {
+    reader.close();
+  }
+}

package/extensions/session-messaging/shared/protocol.ts

@@ -0,0 +1,102 @@
+import { type Static, Type } from "typebox";
+
+const SESSION_INFO_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  sessionName: Type.Optional(Type.String()),
+  cwd: Type.String(),
+});
+
+export const SESSION_MESSAGE_PAYLOAD_SCHEMA = Type.Object({
+  messageId: Type.String(),
+  source: SESSION_INFO_SCHEMA,
+  target: SESSION_INFO_SCHEMA,
+  body: Type.String(),
+  requestResponse: Type.Optional(Type.Boolean()),
+  sentAt: Type.String(),
+  sourceToolCallId: Type.Optional(Type.String()),
+});
+
+const REGISTER_CLIENT_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("register"),
+  session: SESSION_INFO_SCHEMA,
+});
+const UNREGISTER_CLIENT_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("unregister"),
+});
+const LIST_CLIENT_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("list"),
+  requestId: Type.String(),
+});
+const SEND_CLIENT_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("send"),
+  requestId: Type.String(),
+  messageId: Type.String(),
+  target: Type.String(),
+  body: Type.String(),
+  requestResponse: Type.Optional(Type.Boolean()),
+  sentAt: Type.String(),
+  sourceToolCallId: Type.Optional(Type.String()),
+});
+const INCOMING_ACK_CLIENT_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("incoming_ack"),
+  requestId: Type.String(),
+  messageId: Type.String(),
+  delivered: Type.Boolean(),
+  error: Type.Optional(Type.String()),
+});
+
+const REGISTERED_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("registered"),
+  session: SESSION_INFO_SCHEMA,
+});
+const REGISTER_FAILED_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("register_failed"),
+  reason: Type.String(),
+});
+const SESSIONS_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("sessions"),
+  requestId: Type.String(),
+  sessions: Type.Array(SESSION_INFO_SCHEMA),
+});
+const INCOMING_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("incoming"),
+  requestId: Type.String(),
+  message: SESSION_MESSAGE_PAYLOAD_SCHEMA,
+});
+const SEND_RESULT_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("send_result"),
+  requestId: Type.String(),
+  messageId: Type.String(),
+  delivered: Type.Boolean(),
+  error: Type.Optional(Type.String()),
+});
+const ERROR_BROKER_FRAME_SCHEMA = Type.Object({
+  type: Type.Literal("error"),
+  message: Type.String(),
+});
+
+export const CLIENT_FRAME_SCHEMA = Type.Union([
+  REGISTER_CLIENT_FRAME_SCHEMA,
+  UNREGISTER_CLIENT_FRAME_SCHEMA,
+  LIST_CLIENT_FRAME_SCHEMA,
+  SEND_CLIENT_FRAME_SCHEMA,
+  INCOMING_ACK_CLIENT_FRAME_SCHEMA,
+]);
+
+export const BROKER_FRAME_SCHEMA = Type.Union([
+  REGISTERED_BROKER_FRAME_SCHEMA,
+  REGISTER_FAILED_BROKER_FRAME_SCHEMA,
+  SESSIONS_BROKER_FRAME_SCHEMA,
+  INCOMING_BROKER_FRAME_SCHEMA,
+  SEND_RESULT_BROKER_FRAME_SCHEMA,
+  ERROR_BROKER_FRAME_SCHEMA,
+]);
+
+export type SessionMessagingSessionInfo = Static<typeof SESSION_INFO_SCHEMA>;
+export type SessionMessagePayload = Static<typeof SESSION_MESSAGE_PAYLOAD_SCHEMA>;
+export type SessionMessagingSendClientFrame = Static<typeof SEND_CLIENT_FRAME_SCHEMA>;
+export type SessionMessagingIncomingAckClientFrame = Static<
+  typeof INCOMING_ACK_CLIENT_FRAME_SCHEMA
+>;
+export type SessionMessagingClientFrame = Static<typeof CLIENT_FRAME_SCHEMA>;
+export type SessionMessagingBrokerFrame = Static<typeof BROKER_FRAME_SCHEMA>;

package/extensions/session-messaging/shared/socket-path.ts

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function sanitizePipeSegment(value: string): string {
+  return (
+    value
+      .replace(/[^a-zA-Z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .toLowerCase() || "default"
+  );
+}
+
+export function getSessionMessagingDir(homeDir: string = homedir()): string {
+  return (
+    process.env.PI_SESSIONS_MESSAGING_DIR ??
+    join(homeDir, ".pi", "agent", "pi-sessions", "messaging")
+  );
+}
+
+export function getSessionMessagingSocketPath(
+  platform: NodeJS.Platform = process.platform,
+  homeDir: string = homedir(),
+): string {
+  const messagingDir = getSessionMessagingDir(homeDir);
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\pi-sessions-messaging-${sanitizePipeSegment(messagingDir)}`;
+  }
+
+  return join(messagingDir, "broker.sock");
+}

package/extensions/session-messaging.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { IncomingSessionMessageRuntime } from "./session-messaging/pi/incoming-runtime.ts";
+import { registerSessionMessagingRenderer } from "./session-messaging/pi/renderer.ts";
+import { SessionMessagingService } from "./session-messaging/pi/service.ts";
+import { registerSessionMessagingTools } from "./session-messaging/pi/tools.ts";
+import { loadSettings } from "./shared/settings.ts";
+
+export default function sessionMessagingExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+  const incomingRuntime = new IncomingSessionMessageRuntime(pi);
+  const service = new SessionMessagingService(
+    settings.index.path,
+    incomingRuntime,
+    pi.appendEntry.bind(pi),
+  );
+
+  pi.on("session_start", async (_event, ctx) => {
+    incomingRuntime.replayPending(ctx);
+    try {
+      await service.start(ctx);
+    } catch {}
+  });
+
+  pi.on("session_shutdown", () => {
+    service.stop();
+  });
+
+  registerSessionMessagingTools(pi, service);
+  registerSessionMessagingRenderer(pi);
+}

package/extensions/session-search/extract.ts

@@ -23,16 +23,16 @@ import {
   HANDOFF_METADATA_CUSTOM_TYPE,
   type HandoffSessionMetadata,
   parseHandoffSessionMetadata,
-} from "../session-handoff/metadata.js";
-import type { SessionOrigin } from "../shared/session-index/index.js";
-import { safeParseTypeBoxValue } from "../shared/typebox.js";
+} from "../session-handoff/metadata.ts";
+import type { SessionOrigin } from "../shared/session-index/index.ts";
+import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 import {
   deriveSessionRepoRoots,
   type FileTouchOp,
   type FileTouchSource,
   normalizePathRecord,
   type PathScope,
-} from "./normalize.js";
+} from "./normalize.ts";
 
 export interface SearchTextChunk {
   entryId?: string | undefined;

package/extensions/session-search/hooks.ts

@@ -22,7 +22,7 @@ import {
   type SessionRow,
   setMetadata,
   upsertSession,
-} from "../shared/session-index/index.js";
+} from "../shared/session-index/index.ts";
 import {
   createSessionNameChunk,
   type ExtractedSessionRecord,
@@ -30,8 +30,8 @@ import {
   extractSessionRecord,
   extractSessionTail,
   type SessionFileTouch,
-} from "./extract.js";
-import { deriveSessionRepoRoots } from "./normalize.js";
+} from "./extract.ts";
+import { deriveSessionRepoRoots } from "./normalize.ts";
 
 const TOOL_RESULT_TEXT_LIMIT = 500;
 

package/extensions/session-search/reindex.ts

@@ -11,8 +11,8 @@ import {
   type SessionIndexDatabase,
   setMetadata,
   upsertSession,
-} from "../shared/session-index/index.js";
-import { type ExtractedSessionRecord, extractSessionRecord } from "./extract.js";
+} from "../shared/session-index/index.ts";
+import { type ExtractedSessionRecord, extractSessionRecord } from "./extract.ts";
 
 export interface ReindexOptions {
   indexPath: string;

package/extensions/session-search.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 import {
   stripSearchSnippetMarkers,
   transformSearchSnippetMatches,
-} from "./shared/search-snippet.js";
+} from "./shared/search-snippet.ts";
 import {
   getIndexStatus,
   INDEX_SCHEMA_VERSION,
@@ -14,9 +14,9 @@ import {
   type SearchSessionsParams,
   type SessionIndexStatus,
   searchSessions,
-} from "./shared/session-index/index.js";
-import { formatSessionTitleOrShortId } from "./shared/session-ui.js";
-import { loadSettings } from "./shared/settings.js";
+} from "./shared/session-index/index.ts";
+import { formatSessionTitleOrShortId } from "./shared/session-ui.ts";
+import { loadSettings } from "./shared/settings.ts";
 
 interface SessionSearchToolParams {
   query?: string;

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

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
-import type { FileTouchOp, FileTouchSource, PathScope } from "../../session-search/normalize.js";
-import { safeParseTypeBoxJson } from "../typebox.js";
-import type { SqliteDatabase } from "./sqlite.js";
+import type { FileTouchOp, FileTouchSource, PathScope } from "../../session-search/normalize.ts";
+import { safeParseTypeBoxJson } from "../typebox.ts";
+import type { SqliteDatabase } from "./sqlite.ts";
 
 export const INDEX_SCHEMA_VERSION = 8;
 

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

@@ -1,5 +1,5 @@
-export * from "./common.js";
-export * from "./lineage.js";
-export * from "./schema.js";
-export * from "./search.js";
-export * from "./store.js";
+export * from "./common.ts";
+export * from "./lineage.ts";
+export * from "./schema.ts";
+export * from "./search.ts";
+export * from "./store.ts";

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

@@ -1,5 +1,5 @@
 import { type Static, Type } from "typebox";
-import { parseTypeBoxRows, parseTypeBoxValue } from "../typebox.js";
+import { parseTypeBoxRows, parseTypeBoxValue } from "../typebox.ts";
 import {
   NULLABLE_STRING_SCHEMA,
   parseRepoRoots,
@@ -9,7 +9,7 @@ import {
   type SessionLineageRelation,
   type SessionLineageRow,
   type SessionRelatedSessionRow,
-} from "./common.js";
+} from "./common.ts";
 
 const SESSION_GRAPH_ROW_SCHEMA = Type.Object({
   sessionId: Type.String(),
@@ -160,6 +160,13 @@ export function getLineageSessions(
   return queryRelatedSessions(db, sessionId);
 }
 
+export function getLineageRelationMap(
+  db: SessionIndexDatabase,
+  sessionId: string,
+): Map<string, SessionLineageRelation> {
+  return new Map(getLineageSessions(db, sessionId).map((row) => [row.sessionId, row.relation]));
+}
+
 export function getParentSession(
   db: SessionIndexDatabase,
   sessionId: string,

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

@@ -1,13 +1,13 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { parseTypeBoxValue } from "../typebox.js";
+import { parseTypeBoxValue } from "../typebox.ts";
 import {
   INDEX_SCHEMA_VERSION,
   METADATA_ROW_SCHEMA,
   ROW_COUNT_SCHEMA,
   type SessionIndexDatabase,
   type SessionIndexStatus,
-} from "./common.js";
-import { openSqlite } from "./sqlite.js";
+} from "./common.ts";
+import { openSqlite } from "./sqlite.ts";
 
 export function ensureIndexDir(dir: string): string {
   if (!existsSync(dir)) {

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

@@ -4,13 +4,13 @@ import {
   type FileTouchOp,
   matchesRepoRoot,
   normalizeSearchPath,
-} from "../../session-search/normalize.js";
+} from "../../session-search/normalize.ts";
 import {
   SEARCH_SNIPPET_ELLIPSIS,
   SEARCH_SNIPPET_MATCH_END,
   SEARCH_SNIPPET_MATCH_START,
-} from "../search-snippet.js";
-import { parseTypeBoxRows } from "../typebox.js";
+} from "../search-snippet.ts";
+import { parseTypeBoxRows } from "../typebox.ts";
 import {
   boostIndependentHits,
   buildFtsQuery,
@@ -26,7 +26,7 @@ import {
   type SessionIndexDatabase,
   sanitizeFilterValues,
   tokenizeSearchTerms,
-} from "./common.js";
+} from "./common.ts";
 
 const SESSION_LIST_ROW_SCHEMA = Type.Object({
   sessionId: Type.String(),

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

@@ -1,5 +1,5 @@
 import { type Static, Type } from "typebox";
-import { parseTypeBoxValue } from "../typebox.js";
+import { parseTypeBoxValue } from "../typebox.ts";
 import {
   compactSessionId,
   INDEX_SCHEMA_VERSION,
@@ -10,7 +10,7 @@ import {
   type SessionIndexDatabase,
   type SessionRow,
   type SessionTextChunkRow,
-} from "./common.js";
+} from "./common.ts";
 
 const SESSION_ROW_QUERY_SCHEMA = Type.Object({
   sessionId: Type.String(),

package/extensions/shared/settings.ts

@@ -3,7 +3,7 @@ import path from "node:path";
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { KeyId } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
-import { parseTypeBoxValue } from "./typebox.js";
+import { parseTypeBoxValue } from "./typebox.ts";
 
 export const DEFAULT_AUTO_TITLE_REFRESH_TURNS = 4;
 export const DEFAULT_AUTO_TITLE_PROMPT = `Name this coding session (under 80 chars). Be specific to what is being discussed. Your exact output will be displayed to the user, so make sure that it contains ONLY the title itself and nothing else.`;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-sessions",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Pi session search, ask, handoff, auto-titling, and indexing tools",
+  "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "pi-package"
   ],
   "engines": {
-    "node": ">=20 <26"
+    "node": ">=24 <26"
   },
   "files": [
     "extensions",
@@ -29,6 +29,7 @@
       "./extensions/session-handoff.ts",
       "./extensions/session-hooks.ts",
       "./extensions/session-index.ts",
+      "./extensions/session-messaging.ts",
       "./extensions/session-search.ts"
     ]
   },