pi-sessions 0.5.1 → 0.6.0

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

@@ -0,0 +1,305 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer, type Socket } from "node:net";
+import { join } from "node:path";
+import { readFrames, writeFrame } from "../shared/framing.ts";
+import {
+  CLIENT_FRAME_SCHEMA,
+  type SessionMessagingClientFrame,
+  type SessionMessagingIncomingAckClientFrame,
+  type SessionMessagingSendClientFrame,
+  type SessionMessagingSessionInfo,
+} from "../shared/protocol.ts";
+import { getSessionMessagingDir, getSessionMessagingSocketPath } from "../shared/socket-path.ts";
+
+const SEND_TIMEOUT_MS = 10_000;
+const EXIT_IDLE_MS = 5_000;
+const KEEPALIVE_DELAY_MS = 5_000;
+
+const messagingDir = getSessionMessagingDir();
+const socketPath = getSessionMessagingSocketPath();
+const pidPath = join(messagingDir, "broker.pid");
+
+interface ConnectedSession {
+  socket: Socket;
+  session: SessionMessagingSessionInfo;
+}
+
+interface PendingSend {
+  source: Socket;
+  timeout: NodeJS.Timeout;
+  messageId: string;
+  targetSessionId: string;
+}
+
+const sessions = new Map<string, ConnectedSession>();
+const pendingSends = new Map<string, PendingSend>();
+let idleTimer: NodeJS.Timeout | undefined;
+let server: ReturnType<typeof createServer> | undefined;
+
+function closeWithError(socket: Socket, message: string): void {
+  try {
+    writeFrame(socket, { type: "error", message });
+  } catch {}
+  socket.destroy();
+}
+
+function scheduleIdleExit(): void {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => {
+    if (sessions.size === 0) shutdown();
+  }, EXIT_IDLE_MS);
+}
+
+function clearIdleExit(): void {
+  if (!idleTimer) return;
+  clearTimeout(idleTimer);
+  idleTimer = undefined;
+}
+
+function unregister(sessionId: string | undefined): void {
+  if (!sessionId) return;
+  sessions.delete(sessionId);
+  failPendingSendsTo(sessionId);
+  if (sessions.size === 0) scheduleIdleExit();
+}
+
+function resolveTarget(target: string): { session: ConnectedSession } | { error: string } {
+  const exact = sessions.get(target);
+  if (exact) return { session: exact };
+
+  return { error: `No live session found for id: ${target}` };
+}
+
+function handleFrame(
+  socket: Socket,
+  message: SessionMessagingClientFrame,
+  getSessionId: () => string | undefined,
+  setSessionId: (sessionId: string | undefined) => void,
+): void {
+  const currentSessionId = getSessionId();
+  if (!currentSessionId && message.type !== "register") {
+    closeWithError(socket, `Received ${message.type} before register.`);
+    return;
+  }
+
+  switch (message.type) {
+    case "register": {
+      const existing = sessions.get(message.session.sessionId);
+      if (existing && existing.socket !== socket && !existing.socket.destroyed) {
+        writeFrame(socket, {
+          type: "register_failed",
+          reason:
+            "Session messaging unavailable: this session is already registered by another live Pi process.",
+        });
+        socket.end();
+        return;
+      }
+
+      clearIdleExit();
+      setSessionId(message.session.sessionId);
+      sessions.set(message.session.sessionId, { socket, session: message.session });
+      socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
+      writeFrame(socket, { type: "registered", session: message.session });
+      break;
+    }
+
+    case "unregister":
+      unregister(currentSessionId);
+      setSessionId(undefined);
+      socket.end();
+      break;
+
+    case "list":
+      writeFrame(socket, {
+        type: "sessions",
+        requestId: message.requestId,
+        sessions: [...sessions.values()].map(({ session }) => session),
+      });
+      break;
+
+    case "send":
+      handleSend(socket, currentSessionId, message);
+      break;
+
+    case "incoming_ack":
+      handleIncomingAck(message);
+      break;
+  }
+}
+
+function handleSend(
+  socket: Socket,
+  currentSessionId: string | undefined,
+  message: SessionMessagingSendClientFrame,
+): void {
+  const source = currentSessionId ? sessions.get(currentSessionId) : undefined;
+  const { messageId } = message;
+
+  if (!source) {
+    writeFrame(socket, {
+      type: "send_result",
+      requestId: message.requestId,
+      messageId,
+      delivered: false,
+      error: "Sender session is not registered.",
+    });
+    return;
+  }
+
+  const resolved = resolveTarget(message.target);
+  if ("error" in resolved) {
+    writeFrame(socket, {
+      type: "send_result",
+      requestId: message.requestId,
+      messageId,
+      delivered: false,
+      error: resolved.error,
+    });
+    return;
+  }
+
+  if (resolved.session.session.sessionId === source.session.sessionId) {
+    writeFrame(socket, {
+      type: "send_result",
+      requestId: message.requestId,
+      messageId,
+      delivered: false,
+      error: "Cannot send a session message to the current session.",
+    });
+    return;
+  }
+
+  const timeout = setTimeout(() => {
+    pendingSends.delete(message.requestId);
+    writeFrame(socket, {
+      type: "send_result",
+      requestId: message.requestId,
+      messageId,
+      delivered: false,
+      error: "Timed out waiting for target session to accept the message.",
+    });
+  }, SEND_TIMEOUT_MS);
+  pendingSends.set(message.requestId, {
+    source: socket,
+    timeout,
+    messageId,
+    targetSessionId: resolved.session.session.sessionId,
+  });
+
+  writeFrame(resolved.session.socket, {
+    type: "incoming",
+    requestId: message.requestId,
+    message: {
+      messageId,
+      source: source.session,
+      target: resolved.session.session,
+      body: message.body,
+      ...(message.requestResponse === undefined
+        ? {}
+        : { requestResponse: message.requestResponse }),
+      sentAt: message.sentAt,
+      ...(message.sourceToolCallId === undefined
+        ? {}
+        : { sourceToolCallId: message.sourceToolCallId }),
+    },
+  });
+}
+
+function failPendingSendsTo(targetSessionId: string): void {
+  for (const [requestId, pending] of pendingSends) {
+    if (pending.targetSessionId !== targetSessionId) {
+      continue;
+    }
+
+    clearTimeout(pending.timeout);
+    pendingSends.delete(requestId);
+    writeFrame(pending.source, {
+      type: "send_result",
+      requestId,
+      messageId: pending.messageId,
+      delivered: false,
+      error: "Target disconnected before accepting the message.",
+    });
+  }
+}
+
+function handleIncomingAck(message: SessionMessagingIncomingAckClientFrame): void {
+  const pending = pendingSends.get(message.requestId);
+  if (!pending) return;
+
+  clearTimeout(pending.timeout);
+  pendingSends.delete(message.requestId);
+  writeFrame(pending.source, {
+    type: "send_result",
+    requestId: message.requestId,
+    messageId: message.messageId,
+    delivered: message.delivered,
+    ...(message.error === undefined ? {} : { error: message.error }),
+  });
+}
+
+function handleConnection(socket: Socket): void {
+  let sessionId: string | undefined;
+  socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
+  void readConnection(
+    socket,
+    () => sessionId,
+    (nextSessionId) => {
+      sessionId = nextSessionId;
+    },
+  );
+
+  socket.on("close", () => {
+    unregister(sessionId);
+  });
+  socket.on("error", () => {});
+}
+
+async function readConnection(
+  socket: Socket,
+  getSessionId: () => string | undefined,
+  setSessionId: (sessionId: string | undefined) => void,
+): Promise<void> {
+  try {
+    for await (const frame of readFrames(
+      socket,
+      CLIENT_FRAME_SCHEMA,
+      "Invalid session messaging client frame",
+    )) {
+      handleFrame(socket, frame, getSessionId, setSessionId);
+    }
+  } catch (error) {
+    closeWithError(socket, error instanceof Error ? error.message : String(error));
+  }
+}
+
+function shutdown(): void {
+  for (const { socket } of sessions.values()) socket.end();
+  sessions.clear();
+  for (const pending of pendingSends.values()) clearTimeout(pending.timeout);
+  pendingSends.clear();
+  if (server) server.close();
+  if (process.platform !== "win32") {
+    try {
+      unlinkSync(socketPath);
+    } catch {}
+  }
+  try {
+    unlinkSync(pidPath);
+  } catch {}
+  process.exit(0);
+}
+
+mkdirSync(messagingDir, { recursive: true, mode: 0o700 });
+if (process.platform !== "win32") {
+  try {
+    unlinkSync(socketPath);
+  } catch {}
+}
+server = createServer(handleConnection);
+server.listen(socketPath, () => {
+  writeFileSync(pidPath, String(process.pid));
+});
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

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

@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getSessionMessagingDir, getSessionMessagingSocketPath } from "../shared/socket-path.ts";
+
+const BROKER_START_TIMEOUT_MS = 5_000;
+const BROKER_CONNECT_TIMEOUT_MS = 1_000;
+const BROKER_SPAWN_LOCK_STALE_MS = 10_000;
+
+const brokerDir = getSessionMessagingDir();
+const brokerSocketPath = getSessionMessagingSocketPath();
+const brokerPidPath = join(brokerDir, "broker.pid");
+const brokerSpawnLockPath = join(brokerDir, "broker.spawn.lock");
+
+export async function spawnSessionMessagingBrokerIfNeeded(): Promise<void> {
+  mkdirSync(brokerDir, { recursive: true, mode: 0o700 });
+
+  if (await isBrokerRunning()) {
+    return;
+  }
+
+  if (!acquireSpawnLock()) {
+    await waitForBroker();
+    return;
+  }
+
+  try {
+    if (await isBrokerRunning()) {
+      return;
+    }
+
+    const brokerPath = join(dirname(fileURLToPath(import.meta.url)), "process.ts");
+    const child = spawn(process.execPath, [brokerPath], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: process.platform === "win32",
+      env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
+    child.unref();
+    await waitForBroker();
+  } finally {
+    releaseSpawnLock();
+  }
+}
+
+async function isBrokerRunning(): Promise<boolean> {
+  if (await canConnectToBroker()) {
+    return true;
+  }
+
+  if (!existsSync(brokerPidPath)) {
+    return false;
+  }
+
+  try {
+    const pid = Number.parseInt(readFileSync(brokerPidPath, "utf8").trim(), 10);
+    if (!Number.isFinite(pid)) {
+      return false;
+    }
+    process.kill(pid, 0);
+    return canConnectToBroker();
+  } catch {
+    return false;
+  }
+}
+
+function canConnectToBroker(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect(brokerSocketPath);
+    const finish = (connected: boolean): void => {
+      clearTimeout(timeout);
+      socket.off("connect", onConnect);
+      socket.off("error", onError);
+      resolve(connected);
+    };
+    const onConnect = (): void => {
+      socket.end();
+      finish(true);
+    };
+    const onError = (): void => {
+      socket.destroy();
+      finish(false);
+    };
+    const timeout = setTimeout(() => {
+      socket.destroy();
+      finish(false);
+    }, BROKER_CONNECT_TIMEOUT_MS);
+    socket.on("connect", onConnect);
+    socket.on("error", onError);
+  });
+}
+
+async function waitForBroker(): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < BROKER_START_TIMEOUT_MS) {
+    if (await canConnectToBroker()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  throw new Error("Session messaging broker failed to start.");
+}
+
+function acquireSpawnLock(): boolean {
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      writeFileSync(brokerSpawnLockPath, `${process.pid}\n${Date.now()}\n`, { flag: "wx" });
+      return true;
+    } catch (error) {
+      if (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (isSpawnLockStale()) {
+        try {
+          unlinkSync(brokerSpawnLockPath);
+        } catch {}
+        continue;
+      }
+      return false;
+    }
+  }
+
+  return false;
+}
+
+function isSpawnLockStale(): boolean {
+  if (!existsSync(brokerSpawnLockPath)) {
+    return false;
+  }
+
+  try {
+    const [pidLine = "", createdAtLine = "0"] = readFileSync(brokerSpawnLockPath, "utf8")
+      .trim()
+      .split("\n");
+    const pid = Number.parseInt(pidLine, 10);
+    const createdAt = Number.parseInt(createdAtLine, 10);
+
+    if (Number.isFinite(pid)) {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        return true;
+      }
+    }
+
+    return !Number.isFinite(createdAt) || Date.now() - createdAt > BROKER_SPAWN_LOCK_STALE_MS;
+  } catch {
+    return true;
+  }
+}
+
+function releaseSpawnLock(): void {
+  try {
+    unlinkSync(brokerSpawnLockPath);
+  } catch {}
+}

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

@@ -0,0 +1,256 @@
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import net from "node:net";
+import { readFrames, writeFrame } from "../shared/framing.ts";
+import {
+  BROKER_FRAME_SCHEMA,
+  type SessionMessagingBrokerFrame,
+  type SessionMessagingSessionInfo,
+} from "../shared/protocol.ts";
+import { getSessionMessagingSocketPath } from "../shared/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(sessions: SessionMessagingSessionInfo[]): 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 session: SessionMessagingSessionInfo | 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.session);
+  }
+
+  get registeredSession(): SessionMessagingSessionInfo | undefined {
+    return this.session;
+  }
+
+  async connect(session: SessionMessagingSessionInfo): 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", session });
+    });
+  }
+
+  disconnect(): void {
+    if (this.socket && !this.socket.destroyed) {
+      if (!this.socket.writableEnded) {
+        try {
+          writeFrame(this.socket, { type: "unregister" });
+        } catch {}
+      }
+      this.socket.end();
+    }
+    this.cleanup();
+  }
+
+  listSessions(): Promise<SessionMessagingSessionInfo[]> {
+    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.session = frame.session;
+        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.sessions);
+        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.session) {
+      throw new Error("Session messaging is not connected.");
+    }
+
+    return this.socket;
+  }
+
+  private cleanup(): void {
+    this.session = 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();
+  }
+}