pi-sessions 0.5.0 → 0.6.0

package/extensions/session-messaging/pi/incoming-runtime.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionLineageRelation } from "../../shared/session-index/index.ts";
+import { safeParseTypeBoxValue } from "../../shared/typebox.ts";
+import type { SessionMessagePayload } from "../shared/protocol.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(
+    message: SessionMessagePayload,
+    relation: SessionLineageRelation | undefined,
+  ): DeliveryResult {
+    const ctx = this.context;
+    if (!ctx) {
+      return { delivered: false, error: "Target session is not ready." };
+    }
+
+    try {
+      const received = buildReceivedMessageEntry(message, relation);
+      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 buildReceivedMessageEntry(
+  message: SessionMessagePayload,
+  relation: SessionLineageRelation | undefined,
+): ReceivedMessageEntry {
+  return {
+    ...message,
+    receivedAt: new Date().toISOString(),
+    ...(relation === undefined ? {} : { relation }),
+  };
+}
+
+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,37 @@
+import { type Static, Type } from "typebox";
+
+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: Type.Object({
+    sessionId: Type.String(),
+    sessionName: Type.Optional(Type.String()),
+    cwd: Type.String(),
+  }),
+  target: Type.Object({
+    sessionId: Type.String(),
+    sessionName: Type.Optional(Type.String()),
+    cwd: Type.String(),
+  }),
+  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 ReceivedMessageEntry = Static<typeof RECEIVED_MESSAGE_ENTRY_SCHEMA>;

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

@@ -0,0 +1,120 @@
+import { Box, type Component, getKeybindings, type Keybinding, Text } from "@earendil-works/pi-tui";
+import type { ReceivedMessageEntry } from "./message-contracts.ts";
+
+const COLLAPSED_MESSAGE_LINES = 10;
+
+interface MessageViewTheme {
+  bold(text: string): string;
+  fg(token: string, text: string): string;
+  bg(token: string, text: string): string;
+}
+
+interface MessageViewOptions {
+  expanded: boolean;
+  status: "sending" | "received";
+  targetSessionId?: string | undefined;
+  sourceSessionId?: string | undefined;
+  message: string;
+  requestResponse?: boolean | undefined;
+  relation?: string | undefined;
+}
+
+export function renderSessionMessageView(
+  options: MessageViewOptions,
+  theme: MessageViewTheme,
+): string {
+  const header = formatHeader(options, theme);
+  const body = formatMessageBody(options.message, options.expanded, theme);
+  return body ? `${header}\n\n${body}` : header;
+}
+
+export function createReceivedSessionMessageComponent(
+  received: ReceivedMessageEntry,
+  expanded: boolean,
+  theme: MessageViewTheme,
+): Component {
+  const box = new Box(1, 1, (text: string) => theme.bg("toolSuccessBg", text));
+  box.addChild(
+    new Text(
+      renderSessionMessageView(
+        {
+          expanded,
+          status: "received",
+          sourceSessionId: received.source.sessionId,
+          message: received.body,
+          requestResponse: received.requestResponse,
+          relation: received.relation,
+        },
+        theme,
+      ),
+      0,
+      0,
+    ),
+  );
+  return box;
+}
+
+export function formatSendMessageCall(
+  args: { session?: string; message?: string; requestResponse?: boolean } | undefined,
+  expanded: boolean,
+  status: "sending",
+  theme: MessageViewTheme,
+  relation?: string | undefined,
+): string {
+  return renderSessionMessageView(
+    {
+      expanded,
+      status,
+      targetSessionId: args?.session,
+      message: args?.message ?? "",
+      requestResponse: args?.requestResponse,
+      relation,
+    },
+    theme,
+  );
+}
+
+function formatHeader(options: MessageViewOptions, theme: MessageViewTheme): string {
+  const toolName = options.status === "received" ? "incoming_message" : "session_send_message";
+  const name = theme.fg("toolTitle", theme.bold(toolName));
+  const metadata = [
+    options.relation,
+    options.requestResponse ? "response requested" : undefined,
+  ].filter((item): item is string => Boolean(item));
+  const metadataHint = metadata.length > 0 ? theme.fg("muted", ` (${metadata.join(", ")})`) : "";
+  switch (options.status) {
+    case "received":
+      return `${name} ${theme.fg("muted", `from ${options.sourceSessionId ?? "[source unknown]"}`)}${metadataHint}`;
+    case "sending":
+      return `${name} ${theme.fg("muted", `to ${options.targetSessionId ?? "[target pending]"}`)}${metadataHint}`;
+  }
+}
+
+function formatKeyHint(
+  keybinding: Keybinding,
+  description: string,
+  theme: MessageViewTheme,
+): string {
+  const keyText = getKeybindings().getKeys(keybinding).join("/");
+  return `${theme.fg("dim", keyText)}${theme.fg("muted", ` ${description}`)}`;
+}
+
+function formatMessageBody(message: string, expanded: boolean, theme: MessageViewTheme): string {
+  if (!message) {
+    return "";
+  }
+
+  const lines = message.replaceAll("\t", "  ").split("\n");
+  const maxLines = expanded ? lines.length : COLLAPSED_MESSAGE_LINES;
+  const visibleLines = lines.slice(0, maxLines);
+  const remaining = lines.length - visibleLines.length;
+  const body = visibleLines.map((line) => theme.fg("toolOutput", line)).join("\n");
+  if (remaining <= 0) {
+    return body;
+  }
+
+  return `${body}${theme.fg(
+    "muted",
+    `\n... (${remaining} more lines, ${lines.length} total,`,
+  )} ${formatKeyHint("app.tools.expand", "to expand", theme)}${theme.fg("muted", ")")}`;
+}

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

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { safeParseTypeBoxValue } from "../../shared/typebox.ts";
+import { SESSION_MESSAGE_CUSTOM_TYPE } from "./incoming-runtime.ts";
+import { RECEIVED_MESSAGE_ENTRY_SCHEMA } from "./message-contracts.ts";
+import { createReceivedSessionMessageComponent } from "./message-view.ts";
+
+export function registerSessionMessagingRenderer(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer(SESSION_MESSAGE_CUSTOM_TYPE, (message, options, theme) => {
+    const details = safeParseTypeBoxValue(RECEIVED_MESSAGE_ENTRY_SCHEMA, message.details);
+    if (!details) {
+      return undefined;
+    }
+
+    return createReceivedSessionMessageComponent(details, options.expanded, theme);
+  });
+}

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

@@ -0,0 +1,315 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionLineageRelation } from "../../shared/session-index/index.ts";
+import {
+  getIndexStatus,
+  getLineageRelationMap,
+  INDEX_SCHEMA_VERSION,
+  openIndexDatabase,
+} from "../../shared/session-index/index.ts";
+import { spawnSessionMessagingBrokerIfNeeded } from "../broker/spawn.ts";
+import type { SessionMessagePayload, SessionMessagingSessionInfo } from "../shared/protocol.ts";
+import {
+  INCOMING_SESSION_MESSAGE_EVENT,
+  type SessionMessageSendResult,
+  SessionMessagingClient,
+} from "./client.ts";
+import type { IncomingSessionMessageRuntime } from "./incoming-runtime.ts";
+
+export const MESSAGE_SENT_CUSTOM_TYPE = "pi-sessions.message_sent";
+
+const RECONNECT_DELAYS_MS = [250, 500, 1_000, 2_000, 5_000, 10_000, 30_000] as const;
+
+export interface LiveSessionRow extends SessionMessagingSessionInfo {
+  relation?: SessionLineageRelation | undefined;
+}
+
+export interface SendMessageRequest {
+  target: string;
+  body: string;
+  requestResponse?: boolean | undefined;
+  sourceToolCallId?: string | undefined;
+}
+
+export class SessionMessagingService {
+  private readonly indexPath: string;
+  private readonly incomingRuntime: IncomingSessionMessageRuntime;
+  private readonly appendEntry: (customType: string, data: unknown) => void;
+  private relationBySessionId = new Map<string, SessionLineageRelation | undefined>();
+  private readonly connection = new BrokerConnection((requestId, message) =>
+    this.handleIncoming(requestId, message),
+  );
+
+  constructor(
+    indexPath: string,
+    incomingRuntime: IncomingSessionMessageRuntime,
+    appendEntry: (customType: string, data: unknown) => void,
+  ) {
+    this.indexPath = indexPath;
+    this.incomingRuntime = incomingRuntime;
+    this.appendEntry = appendEntry;
+  }
+
+  async start(ctx: ExtensionContext): Promise<void> {
+    this.refreshCachedRelations(ctx.sessionManager.getSessionId());
+    await this.connection.start(buildSessionInfo(ctx));
+  }
+
+  stop(): void {
+    this.relationBySessionId.clear();
+    this.connection.stop();
+  }
+
+  async listLiveSessions(ctx: ExtensionContext): Promise<LiveSessionRow[]> {
+    const sessions = await this.connection.listSessions();
+    this.refreshCachedRelations(ctx.sessionManager.getSessionId());
+    const currentSessionId = ctx.sessionManager.getSessionId();
+    return sessions
+      .filter((session) => session.sessionId !== currentSessionId)
+      .map(
+        (session): LiveSessionRow => ({
+          ...session,
+          relation: this.getCachedRelationTo(session.sessionId),
+        }),
+      );
+  }
+
+  async sendMessage(request: SendMessageRequest): Promise<SessionMessageSendResult> {
+    const relation = this.getCachedRelationTo(request.target, true);
+    const sentAt = new Date().toISOString();
+    const messageId = randomUUID();
+    const result = await this.connection.sendMessage({
+      messageId,
+      target: request.target,
+      body: request.body,
+      sentAt,
+      requestResponse: request.requestResponse,
+      sourceToolCallId: request.sourceToolCallId,
+    });
+
+    if (result.delivered) {
+      this.appendEntry(MESSAGE_SENT_CUSTOM_TYPE, {
+        messageId: result.messageId,
+        target: request.target,
+        body: request.body,
+        requestResponse: request.requestResponse,
+        sourceToolCallId: request.sourceToolCallId,
+        sentAt,
+        ...(relation === undefined ? {} : { relation }),
+      });
+    }
+
+    return result;
+  }
+
+  private handleIncoming(requestId: string, message: SessionMessagePayload): void {
+    const relation = this.getCachedRelationTo(message.source.sessionId, true);
+    const result = this.incomingRuntime.deliver(message, relation);
+    this.connection.acknowledgeIncoming(requestId, message.messageId, result);
+  }
+
+  getCachedRelationTo(
+    sessionId: string | undefined,
+    refresh = false,
+  ): SessionLineageRelation | undefined {
+    if (!sessionId) {
+      return undefined;
+    }
+
+    if (this.relationBySessionId.has(sessionId)) {
+      return this.relationBySessionId.get(sessionId);
+    }
+
+    if (!refresh) {
+      return undefined;
+    }
+
+    const identity = this.connection.currentIdentity;
+    if (!identity) {
+      throw new Error("Session messaging is not active.");
+    }
+
+    this.refreshCachedRelations(identity.sessionId);
+    if (!this.relationBySessionId.has(sessionId)) {
+      this.relationBySessionId.set(sessionId, undefined);
+    }
+
+    return this.relationBySessionId.get(sessionId);
+  }
+
+  private refreshCachedRelations(currentSessionId: string): void {
+    const previousRelations = this.relationBySessionId;
+    const nextRelations = getRelationMapForSession(this.indexPath, currentSessionId);
+
+    for (const [sessionId, relation] of previousRelations) {
+      if (relation === undefined && !nextRelations.has(sessionId)) {
+        nextRelations.set(sessionId, undefined);
+      }
+    }
+
+    this.relationBySessionId = nextRelations;
+  }
+}
+
+class BrokerConnection {
+  private client: SessionMessagingClient | undefined;
+  private identity: SessionMessagingSessionInfo | undefined;
+  private active = false;
+  private reconnectTimer: NodeJS.Timeout | undefined;
+  private reconnectDelayIndex = 0;
+  private connectPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly onIncoming: (requestId: string, message: SessionMessagePayload) => void,
+  ) {}
+
+  get currentIdentity(): SessionMessagingSessionInfo | undefined {
+    return this.identity;
+  }
+
+  async start(identity: SessionMessagingSessionInfo): Promise<void> {
+    this.active = true;
+    this.identity = identity;
+    await this.ensureConnectedNow();
+  }
+
+  stop(): void {
+    this.active = false;
+    this.identity = undefined;
+    this.clearReconnectTimer();
+    this.client?.disconnect();
+    this.client = undefined;
+    this.connectPromise = undefined;
+  }
+
+  async listSessions(): Promise<SessionMessagingSessionInfo[]> {
+    await this.ensureConnectedNow();
+    return this.requireClient().listSessions();
+  }
+
+  async sendMessage(options: {
+    messageId: string;
+    target: string;
+    body: string;
+    sentAt: string;
+    requestResponse?: boolean | undefined;
+    sourceToolCallId?: string | undefined;
+  }): Promise<SessionMessageSendResult> {
+    await this.ensureConnectedNow();
+    return this.requireClient().sendMessage(options);
+  }
+
+  acknowledgeIncoming(
+    requestId: string,
+    messageId: string,
+    result: { delivered: true } | { delivered: false; error: string },
+  ): void {
+    try {
+      this.requireClient().acknowledgeIncoming(requestId, messageId, result);
+    } catch {}
+  }
+
+  private async ensureConnectedNow(): Promise<void> {
+    if (this.client?.isConnected) {
+      return;
+    }
+    if (!this.active || !this.identity) {
+      throw new Error("Session messaging is not active.");
+    }
+    this.clearReconnectTimer();
+
+    if (!this.connectPromise) {
+      this.connectPromise = this.connect().finally(() => {
+        this.connectPromise = undefined;
+      });
+    }
+
+    try {
+      await this.connectPromise;
+    } catch (error) {
+      this.scheduleReconnect();
+      throw error;
+    }
+  }
+
+  private async connect(): Promise<void> {
+    const identity = this.identity;
+    if (!identity) {
+      throw new Error("Session messaging is not active.");
+    }
+
+    this.client?.disconnect();
+    this.client = undefined;
+
+    await spawnSessionMessagingBrokerIfNeeded();
+    const client = new SessionMessagingClient();
+    client.on(INCOMING_SESSION_MESSAGE_EVENT, this.onIncoming);
+    client.on("disconnect", () => {
+      if (this.client === client) {
+        this.client = undefined;
+        this.scheduleReconnect();
+      }
+    });
+
+    await client.connect(identity);
+    this.client = client;
+    this.reconnectDelayIndex = 0;
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.active || this.reconnectTimer) {
+      return;
+    }
+
+    const delay = RECONNECT_DELAYS_MS[this.reconnectDelayIndex] ?? 30_000;
+    this.reconnectDelayIndex = Math.min(
+      this.reconnectDelayIndex + 1,
+      RECONNECT_DELAYS_MS.length - 1,
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.ensureConnectedNow().catch(() => {});
+    }, delay);
+  }
+
+  private clearReconnectTimer(): void {
+    if (!this.reconnectTimer) {
+      return;
+    }
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+  }
+
+  private requireClient(): SessionMessagingClient {
+    if (!this.client?.isConnected) {
+      throw new Error("Session messaging is not connected.");
+    }
+    return this.client;
+  }
+}
+
+function buildSessionInfo(ctx: ExtensionContext): SessionMessagingSessionInfo {
+  const sessionName = ctx.sessionManager.getSessionName()?.trim();
+  return {
+    sessionId: ctx.sessionManager.getSessionId(),
+    ...(sessionName ? { sessionName } : {}),
+    cwd: ctx.cwd,
+  };
+}
+
+function getRelationMapForSession(
+  indexPath: string,
+  sessionId: string,
+): Map<string, SessionLineageRelation | undefined> {
+  const status = getIndexStatus(indexPath);
+  if (!status.exists || status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    return new Map();
+  }
+
+  const db = openIndexDatabase(status.dbPath, { create: false });
+  try {
+    return new Map(getLineageRelationMap(db, sessionId));
+  } finally {
+    db.close();
+  }
+}