pi-sessions 0.5.1 → 0.7.0

package/extensions/shared/session-broker/client.ts

@@ -0,0 +1,253 @@
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import net from "node:net";
+import { readFrames, writeFrame } from "./framing.ts";
+import { BROKER_FRAME_SCHEMA, type SessionMessagingBrokerFrame } from "./protocol.ts";
+import { getSessionMessagingSocketPath } from "./socket-path.ts";
+
+export const INCOMING_SESSION_MESSAGE_EVENT = "session_messaging.incoming_message";
+
+const REQUEST_TIMEOUT_MS = 10_000;
+const SOCKET_PATH = getSessionMessagingSocketPath();
+
+interface PendingListRequest {
+  resolve(sessionIds: string[]): void;
+  reject(error: Error): void;
+  timeout: NodeJS.Timeout;
+}
+
+interface PendingSendRequest {
+  resolve(result: SessionMessageSendResult): void;
+  reject(error: Error): void;
+  timeout: NodeJS.Timeout;
+}
+
+export interface SessionMessageSendResult {
+  messageId: string;
+  delivered: boolean;
+  error?: string | undefined;
+}
+
+export interface SendSessionMessageOptions {
+  messageId: string;
+  target: string;
+  body: string;
+  sentAt: string;
+  requestResponse?: boolean | undefined;
+  sourceToolCallId?: string | undefined;
+}
+
+export class SessionMessagingClient extends EventEmitter {
+  private socket: net.Socket | undefined;
+  private sessionId: string | undefined;
+  private pendingLists = new Map<string, PendingListRequest>();
+  private pendingSends = new Map<string, PendingSendRequest>();
+
+  get isConnected(): boolean {
+    return Boolean(this.socket && !this.socket.destroyed && this.socket.writable && this.sessionId);
+  }
+
+  get registeredSessionId(): string | undefined {
+    return this.sessionId;
+  }
+
+  async connect(sessionId: string): Promise<void> {
+    if (this.isConnected) {
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const socket = net.connect(SOCKET_PATH);
+      this.socket = socket;
+      let settled = false;
+
+      const timeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        socket.destroy();
+        reject(new Error("Session messaging broker connection timed out."));
+      }, REQUEST_TIMEOUT_MS);
+
+      const cleanup = (): void => {
+        clearTimeout(timeout);
+        socket.off("error", onError);
+        socket.off("close", onClose);
+        this.off("registered", onRegistered);
+        this.off("register_failed", onRegisterFailed);
+      };
+
+      const fail = (error: Error): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        socket.destroy();
+        reject(error);
+      };
+
+      const onError = (error: Error): void => fail(error);
+      const onClose = (): void =>
+        fail(new Error("Session messaging broker closed before registration."));
+      const onRegistered = (): void => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        socket.on("close", () => {
+          if (this.socket === socket) {
+            this.cleanup();
+            this.emit("disconnect");
+          }
+        });
+        resolve();
+      };
+      const onRegisterFailed = (reason: string): void => fail(new Error(reason));
+
+      socket.on("error", onError);
+      socket.on("close", onClose);
+      this.once("registered", onRegistered);
+      this.once("register_failed", onRegisterFailed);
+      void this.readSocket(socket);
+
+      socket.setKeepAlive(true, 5_000);
+      writeFrame(socket, { type: "register", sessionId });
+    });
+  }
+
+  disconnect(): void {
+    if (this.socket && !this.socket.destroyed) {
+      if (!this.socket.writableEnded) {
+        try {
+          writeFrame(this.socket, { type: "unregister" });
+        } catch {}
+      }
+      this.socket.end();
+    }
+    this.cleanup();
+  }
+
+  listSessionIds(): Promise<string[]> {
+    const socket = this.requireSocket();
+    const requestId = randomUUID();
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingLists.delete(requestId);
+        reject(new Error("Session live list timed out."));
+      }, REQUEST_TIMEOUT_MS);
+      this.pendingLists.set(requestId, { resolve, reject, timeout });
+      writeFrame(socket, { type: "list", requestId });
+    });
+  }
+
+  sendMessage(options: SendSessionMessageOptions): Promise<SessionMessageSendResult> {
+    const socket = this.requireSocket();
+    const requestId = randomUUID();
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingSends.delete(requestId);
+        reject(new Error("Session message send timed out."));
+      }, REQUEST_TIMEOUT_MS + 1_000);
+      this.pendingSends.set(requestId, { resolve, reject, timeout });
+      writeFrame(socket, {
+        type: "send",
+        requestId,
+        messageId: options.messageId,
+        target: options.target,
+        body: options.body,
+        requestResponse: options.requestResponse,
+        sourceToolCallId: options.sourceToolCallId,
+        sentAt: options.sentAt,
+      });
+    });
+  }
+
+  acknowledgeIncoming(
+    requestId: string,
+    messageId: string,
+    result: { delivered: true } | { delivered: false; error: string },
+  ): void {
+    const socket = this.requireSocket();
+    writeFrame(socket, {
+      type: "incoming_ack",
+      requestId,
+      messageId,
+      delivered: result.delivered,
+      error: result.delivered ? undefined : result.error,
+    });
+  }
+
+  private async readSocket(socket: net.Socket): Promise<void> {
+    try {
+      for await (const frame of readFrames(
+        socket,
+        BROKER_FRAME_SCHEMA,
+        "Invalid session messaging broker frame",
+      )) {
+        this.handleFrame(frame);
+      }
+    } catch (error) {
+      socket.destroy(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+
+  private handleFrame(frame: SessionMessagingBrokerFrame): void {
+    switch (frame.type) {
+      case "registered":
+        this.sessionId = frame.sessionId;
+        this.emit("registered");
+        break;
+      case "register_failed":
+        this.emit("register_failed", frame.reason);
+        break;
+      case "sessions": {
+        const pending = this.pendingLists.get(frame.requestId);
+        if (!pending) return;
+        clearTimeout(pending.timeout);
+        this.pendingLists.delete(frame.requestId);
+        pending.resolve(frame.sessionIds);
+        break;
+      }
+      case "incoming":
+        this.emit(INCOMING_SESSION_MESSAGE_EVENT, frame.requestId, frame.message);
+        break;
+      case "send_result": {
+        const pending = this.pendingSends.get(frame.requestId);
+        if (!pending) return;
+        clearTimeout(pending.timeout);
+        this.pendingSends.delete(frame.requestId);
+        pending.resolve({
+          messageId: frame.messageId,
+          delivered: frame.delivered,
+          error: frame.error,
+        });
+        break;
+      }
+      case "error":
+        this.socket?.destroy(new Error(frame.message));
+        break;
+    }
+  }
+
+  private requireSocket(): net.Socket {
+    if (!this.socket || this.socket.destroyed || !this.socket.writable || !this.sessionId) {
+      throw new Error("Session messaging is not connected.");
+    }
+
+    return this.socket;
+  }
+
+  private cleanup(): void {
+    this.sessionId = undefined;
+    for (const pending of this.pendingLists.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Session messaging disconnected."));
+    }
+    this.pendingLists.clear();
+    for (const pending of this.pendingSends.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Session messaging disconnected."));
+    }
+    this.pendingSends.clear();
+  }
+}

package/extensions/shared/session-broker/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 "../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/shared/session-broker/protocol.ts

@@ -0,0 +1,95 @@
+import { type Static, Type } from "typebox";
+
+export const SESSION_MESSAGE_PAYLOAD_SCHEMA = Type.Object({
+  messageId: Type.String(),
+  source: Type.String(),
+  target: Type.String(),
+  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"),
+  sessionId: Type.String(),
+});
+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"),
+  sessionId: Type.String(),
+});
+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(),
+  sessionIds: Type.Array(Type.String()),
+});
+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 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/shared/session-broker/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/shared/session-index/access.ts

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { parseTypeBoxValue } from "../typebox.ts";
+import {
+  INDEX_SCHEMA_VERSION,
+  ROW_COUNT_SCHEMA,
+  type SessionIndexDatabase,
+  type SessionIndexStatus,
+} from "./common.ts";
+import { getMetadata, openIndexDatabase } from "./schema.ts";
+
+export type SessionIndexOpenMode = "read" | "write";
+
+export interface WithSessionIndexOptions {
+  mode: SessionIndexOpenMode;
+  required: boolean;
+  timeoutMs?: number | undefined;
+}
+
+export interface ValidSessionIndex {
+  db: SessionIndexDatabase;
+  status: SessionIndexStatus;
+}
+
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: true },
+  read: (index: ValidSessionIndex) => T,
+): T;
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: false },
+  read: (index: ValidSessionIndex) => T,
+): T | undefined;
+export function withSessionIndex<T>(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+  read: (index: ValidSessionIndex) => T,
+): T | undefined {
+  const opened = openValidatedSessionIndexInternal(indexPath, options);
+  if (!opened) {
+    return undefined;
+  }
+
+  try {
+    return read(opened);
+  } finally {
+    opened.db.close();
+  }
+}
+
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: true },
+): ValidSessionIndex;
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions & { required: false },
+): ValidSessionIndex | undefined;
+export function openValidatedSessionIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+): ValidSessionIndex | undefined {
+  return openValidatedSessionIndexInternal(indexPath, options);
+}
+
+function openValidatedSessionIndexInternal(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+): ValidSessionIndex | undefined {
+  if (!existsSync(indexPath)) {
+    return handleUnavailableIndex(indexPath, options);
+  }
+
+  let db: SessionIndexDatabase | undefined;
+  try {
+    db = openIndexDatabase(indexPath, {
+      create: false,
+      mode: options.mode,
+      ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    });
+    const status = getIndexStatusFromDb(indexPath, db);
+    if (status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      const invalidDb = db;
+      db = undefined;
+      invalidDb.close();
+      return handleUnavailableIndex(indexPath, options);
+    }
+
+    return { db, status };
+  } catch (error) {
+    db?.close();
+    return handleUnavailableIndex(indexPath, options, error);
+  }
+}
+
+export function getIndexStatusFromDb(dbPath: string, db: SessionIndexDatabase): SessionIndexStatus {
+  const schemaVersionRaw = getMetadata(db, "schema_version");
+  const lastFullReindexAt = getMetadata(db, "indexed_at");
+  const sessionCountRow = parseTypeBoxValue(
+    ROW_COUNT_SCHEMA,
+    db.prepare(`SELECT COUNT(*) as count FROM sessions`).get(),
+    "Invalid session count row",
+  );
+
+  return {
+    dbPath,
+    exists: true,
+    schemaVersion: schemaVersionRaw ? Number(schemaVersionRaw) : undefined,
+    sessionCount: sessionCountRow.count,
+    lastFullReindexAt,
+  };
+}
+
+export function formatRequiredSessionIndexError(indexPath: string): string {
+  return `Session index missing or incompatible at ${indexPath}. Run /session-index and press r to rebuild it.`;
+}
+
+function handleUnavailableIndex(
+  indexPath: string,
+  options: WithSessionIndexOptions,
+  cause?: unknown,
+): undefined {
+  if (!options.required) {
+    return undefined;
+  }
+
+  throw new Error(formatRequiredSessionIndexError(indexPath), { cause });
+}