pi-sessions 0.5.1 → 0.7.0

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

@@ -0,0 +1,302 @@
+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 SessionMessagingClientFrame,
+  type SessionMessagingIncomingAckClientFrame,
+  type SessionMessagingSendClientFrame,
+} from "../../shared/session-broker/protocol.ts";
+import {
+  getSessionMessagingDir,
+  getSessionMessagingSocketPath,
+} from "../../shared/session-broker/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 PendingSend {
+  source: Socket;
+  timeout: NodeJS.Timeout;
+  messageId: string;
+  targetSessionId: string;
+}
+
+const sessions = new Map<string, Socket>();
+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): { sessionId: string; socket: Socket } | { error: string } {
+  const socket = sessions.get(target);
+  if (socket) return { sessionId: target, socket };
+
+  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.sessionId);
+      if (existing && existing !== socket && !existing.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.sessionId);
+      sessions.set(message.sessionId, socket);
+      socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
+      writeFrame(socket, { type: "registered", sessionId: message.sessionId });
+      break;
+    }
+
+    case "unregister":
+      unregister(currentSessionId);
+      setSessionId(undefined);
+      socket.end();
+      break;
+
+    case "list":
+      writeFrame(socket, {
+        type: "sessions",
+        requestId: message.requestId,
+        sessionIds: [...sessions.keys()],
+      });
+      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 (!currentSessionId || !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.sessionId === currentSessionId) {
+    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.sessionId,
+  });
+
+  writeFrame(resolved.socket, {
+    type: "incoming",
+    requestId: message.requestId,
+    message: {
+      messageId,
+      source: currentSessionId,
+      target: resolved.sessionId,
+      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,164 @@
+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/session-broker/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/incoming-runtime.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { safeParseTypeBoxValue } from "../../shared/typebox.ts";
+import { RECEIVED_MESSAGE_ENTRY_SCHEMA, type ReceivedMessageEntry } from "./message-contracts.ts";
+
+export const MESSAGE_RECEIVED_CUSTOM_TYPE = "pi-sessions.message_received";
+export const SESSION_MESSAGE_CUSTOM_TYPE = "pi-sessions.session_message";
+
+type DeliveryResult = { delivered: true } | { delivered: false; error: string };
+
+interface IncomingMessageActions {
+  appendEntry(customType: string, data: unknown): void;
+  sendMessage(
+    message: {
+      customType: string;
+      content: string;
+      display: boolean;
+      details: unknown;
+    },
+    options: { triggerTurn: true } | { deliverAs: "steer" },
+  ): void;
+}
+
+export class IncomingSessionMessageRuntime {
+  private context: ExtensionContext | undefined;
+  private readonly actions: IncomingMessageActions;
+
+  constructor(pi: ExtensionAPI) {
+    this.actions = {
+      appendEntry: pi.appendEntry.bind(pi),
+      sendMessage: pi.sendMessage.bind(pi),
+    };
+
+    pi.on("session_start", (_event, ctx) => {
+      this.context = ctx;
+    });
+    pi.on("session_shutdown", () => {
+      this.context = undefined;
+    });
+  }
+
+  deliver(received: ReceivedMessageEntry): DeliveryResult {
+    const ctx = this.context;
+    if (!ctx) {
+      return { delivered: false, error: "Target session is not ready." };
+    }
+
+    try {
+      this.actions.appendEntry(MESSAGE_RECEIVED_CUSTOM_TYPE, received);
+      this.inject(ctx, received);
+      return { delivered: true };
+    } catch (error) {
+      return { delivered: false, error: formatError(error) };
+    }
+  }
+
+  replayPending(ctx: ExtensionContext): void {
+    const entries = ctx.sessionManager.getEntries();
+    const deliveredMessageIds = new Set<string>();
+    const pendingReceipts: ReceivedMessageEntry[] = [];
+
+    for (const entry of entries) {
+      if (entry.type === "custom_message" && entry.customType === SESSION_MESSAGE_CUSTOM_TYPE) {
+        const delivered = safeParseTypeBoxValue(RECEIVED_MESSAGE_ENTRY_SCHEMA, entry.details);
+        if (delivered) {
+          deliveredMessageIds.add(delivered.messageId);
+        }
+        continue;
+      }
+
+      if (entry.type !== "custom" || entry.customType !== MESSAGE_RECEIVED_CUSTOM_TYPE) {
+        continue;
+      }
+
+      const received = safeParseTypeBoxValue(RECEIVED_MESSAGE_ENTRY_SCHEMA, entry.data);
+      if (received) {
+        pendingReceipts.push(received);
+      }
+    }
+
+    for (const received of pendingReceipts) {
+      if (!deliveredMessageIds.has(received.messageId)) {
+        this.inject(ctx, received);
+      }
+    }
+  }
+
+  private inject(ctx: ExtensionContext, received: ReceivedMessageEntry): void {
+    const deliveryOptions = ctx.isIdle()
+      ? { triggerTurn: true as const }
+      : { deliverAs: "steer" as const };
+
+    this.actions.sendMessage(
+      {
+        customType: SESSION_MESSAGE_CUSTOM_TYPE,
+        content: formatIncomingMessageForModel(received),
+        display: true,
+        details: received,
+      },
+      deliveryOptions,
+    );
+  }
+}
+
+function formatIncomingMessageForModel(received: ReceivedMessageEntry): string {
+  const title = received.source.sessionName?.trim();
+  const titlePart = title ? ` "${title}"` : "";
+  const relationPart = received.relation ? `, relation: ${received.relation}` : "";
+  const responseLine = received.requestResponse ? "\n\nResponse requested." : "";
+  return `Incoming message from session${titlePart} (session: ${received.source.sessionId}${relationPart}):\n\n${received.body}${responseLine}`;
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error && error.message.trim() ? error.message : String(error);
+}

package/extensions/session-messaging/pi/message-contracts.ts

@@ -0,0 +1,36 @@
+import { type Static, Type } from "typebox";
+
+const RECEIVED_MESSAGE_ENDPOINT_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  sessionName: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+});
+
+export const SEND_MESSAGE_PARAMS = Type.Object({
+  session: Type.String({ description: "Pi session UUID." }),
+  message: Type.String({
+    description: "Message to send to the target session.",
+  }),
+  requestResponse: Type.Optional(
+    Type.Boolean({
+      description:
+        "Whether the target session should respond with completion/results back to this session.",
+    }),
+  ),
+});
+
+export const RECEIVED_MESSAGE_ENTRY_SCHEMA = Type.Object({
+  messageId: Type.String(),
+  source: RECEIVED_MESSAGE_ENDPOINT_SCHEMA,
+  target: RECEIVED_MESSAGE_ENDPOINT_SCHEMA,
+  body: Type.String(),
+  sentAt: Type.String(),
+  receivedAt: Type.String(),
+  requestResponse: Type.Optional(Type.Boolean()),
+  sourceToolCallId: Type.Optional(Type.String()),
+  relation: Type.Optional(Type.String()),
+});
+
+export type SendMessageParams = Static<typeof SEND_MESSAGE_PARAMS>;
+export type ReceivedMessageEndpoint = Static<typeof RECEIVED_MESSAGE_ENDPOINT_SCHEMA>;
+export type ReceivedMessageEntry = Static<typeof RECEIVED_MESSAGE_ENTRY_SCHEMA>;