@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/pi-intercom/broker/client.ts

@@ -1,10 +1,11 @@
 import { EventEmitter } from "events";
 import type net from "net";
 import { randomUUID } from "crypto";
-import type { NativeControlEnvelope } from "../native-control-protocol.ts";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
+import { LastMessageRequests } from "./client-last.ts";
+import { isNativeReadQuery, isNativeReadResult, type NativeReadQuery } from "./last.ts";
 import {
   errorMessage,
   isRecord,
@@ -17,14 +18,16 @@ import {
   normalizeSessionInfo,
   type SessionInfo,
   type Message,
-  type Attachment,
   type MessageDelivery,
-  type QueueMode,
-  type HumanMessageOrigin,
   type TopicUpdate,
   type TopicChange,
   type SessionSnapshot,
   type SendResult,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SendOptions,
+  type ReceiptQuery,
+  type ReceiptResult,
 } from "../types.ts";
 export type { SendResult } from "../types.ts";
 
@@ -40,21 +43,6 @@ export interface IntercomClientOptions {
   readonly listTimeoutMs?: number;
 }
 
-interface SendOptions {
-  readonly text: string;
-  readonly attachments?: readonly Attachment[];
-  readonly replyTo?: string;
-  readonly expectsReply?: boolean;
-  readonly delivery?: MessageDelivery;
-  readonly queueMode?: QueueMode;
-  readonly threadId?: string;
-  readonly passive?: boolean;
-  readonly messageId?: string;
-  readonly human?: HumanMessageOrigin;
-  readonly topic?: TopicUpdate;
-  readonly control?: NativeControlEnvelope;
-}
-
 function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(errorMessage(error));
 }
@@ -76,6 +64,10 @@ export class IntercomClient extends EventEmitter {
   private connection: BrokerConnection | null = null;
   private _sessionId: string | null = null;
   private _topicsSupported = false;
+  private lastMessagesSupported = false;
+  private receiptReadsSupported = false;
+  private guardedDeliverySupported = false;
+  private readonly lastRequests: LastMessageRequests;
   private readonly pendingSends = new Map<
     string,
     { readonly resolve: (r: SendResult) => void; readonly reject: (e: Readonly<Error>) => void }
@@ -97,9 +89,11 @@ export class IntercomClient extends EventEmitter {
     super();
     this.sendTimeoutMs = options.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
     this.listTimeoutMs = options.listTimeoutMs ?? DEFAULT_LIST_TIMEOUT_MS;
+    this.lastRequests = new LastMessageRequests(this.listTimeoutMs);
   }
 
   private failPending(error: Readonly<Error>): void {
+    this.lastRequests.fail(error);
     for (const pending of this.pendingSends.values()) {
       pending.reject(error);
     }
@@ -117,6 +111,9 @@ export class IntercomClient extends EventEmitter {
   get supportsTopics(): boolean {
     return this.isConnected() && this._topicsSupported;
   }
+  get supportsGuardedDelivery(): boolean {
+    return this.isConnected() && this.guardedDeliverySupported;
+  }
   isConnected(): boolean {
     return (
       (this._sessionId ?? "").length > 0 &&
@@ -159,6 +156,9 @@ export class IntercomClient extends EventEmitter {
           this.connection = null;
           this._sessionId = null;
           this._topicsSupported = false;
+          this.lastMessagesSupported = false;
+          this.receiptReadsSupported = false;
+          this.guardedDeliverySupported = false;
           this.disconnecting = false;
           this.failPending(error);
           if (established && !expected) {
@@ -174,6 +174,9 @@ export class IntercomClient extends EventEmitter {
           session: identity,
           requestedId,
           topicFrames: true,
+          lastMessages: true,
+          receiptReads: 1,
+          guardedDelivery: 1,
         });
       } catch (error) {
         if (this.connection === connection) {
@@ -224,6 +227,12 @@ export class IntercomClient extends EventEmitter {
       case "sessions":
         this.receiveSessions(brokerMessage);
         break;
+      case "last_request":
+        this.receiveLastRequest(brokerMessage);
+        break;
+      case "last_response":
+        this.lastRequests.receive(brokerMessage);
+        break;
       case "message":
         this.receiveMessage(brokerMessage);
         break;
@@ -252,10 +261,23 @@ export class IntercomClient extends EventEmitter {
     }
     this._sessionId = msg.sessionId;
     this._topicsSupported = msg.topicsSupported === true && msg.topicFrames === true;
+    this.lastMessagesSupported = msg.lastMessages === true;
+    this.receiptReadsSupported = msg.receiptReads === 1;
+    this.guardedDeliverySupported = msg.guardedDelivery === 1;
     this.connection?.confirmRegistration();
     this.emit("_registered", { type: "registered", sessionId: msg.sessionId });
   }
 
+  private receiveLastRequest(msg: UnknownRecord): void {
+    const from = normalizeSessionInfo(msg.from);
+    if (typeof msg.requestId !== "string" || !from || !isNativeReadQuery(msg.query)) {
+      throw new Error("Invalid last-message request");
+    }
+    if (!this.emit("last_request", { requestId: msg.requestId, from, query: msg.query })) {
+      this.respondLast(msg.requestId, { error: "Recipient has no last-message reader." });
+    }
+  }
+
   private receiveMessage(msg: UnknownRecord): void {
     const message = normalizeMessage(msg.message);
     const from = normalizeSessionInfo(msg.from);
@@ -327,6 +349,30 @@ export class IntercomClient extends EventEmitter {
     return this.requestSessions().then((snapshot) => [...snapshot.sessions]);
   }
 
+  async last(to: string, query: LastMessageQuery = {}): Promise<LastMessageResult> {
+    return await this.lastRequests.last(this.readSocket(query), to, query);
+  }
+  async receipt(to: string, query: ReceiptQuery): Promise<ReceiptResult> {
+    return await this.lastRequests.receipt(this.readSocket(query), to, query);
+  }
+  private readSocket(query: NativeReadQuery): net.Socket {
+    const socket = this.requireActiveSocket();
+    if (!this.lastMessagesSupported) {
+      throw new Error("This broker does not support last-message reads; reload after it exits.");
+    }
+    if ("messageId" in query && !this.receiptReadsSupported) {
+      throw new Error("publication_unavailable");
+    }
+    return socket;
+  }
+
+  respondLast(requestId: string, result: unknown): void {
+    if (!isNativeReadResult(result)) {
+      throw new Error("Invalid last-message result");
+    }
+    writeMessage(this.requireActiveSocket(), { type: "last_response", requestId, result });
+  }
+
   updateTopics(
     change: TopicChange,
     onAccepted?: (snapshot: SessionSnapshot) => void,
@@ -367,7 +413,9 @@ export class IntercomClient extends EventEmitter {
       const timeout = setTimeout(() => {
         if (this.pendingLists.has(requestId)) {
           this.pendingLists.delete(requestId);
-          wrappedReject(new Error("List sessions timeout"));
+          wrappedReject(
+            Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }),
+          );
         }
       }, this.listTimeoutMs);
       timeout.unref();
@@ -391,23 +439,35 @@ export class IntercomClient extends EventEmitter {
     });
   }
 
+  private requireSendSocket(options: SendOptions): net.Socket {
+    const socket = this.requireActiveSocket();
+    if (options.guard && !this.guardedDeliverySupported) {
+      throw new Error("This broker does not support guarded delivery; no message sent.");
+    }
+    return socket;
+  }
+
   send(to: string, options: SendOptions): Promise<SendResult> {
     let socket: net.Socket;
     try {
-      socket = this.requireActiveSocket();
+      socket = this.requireSendSocket(options);
     } catch (error) {
       return Promise.reject(toError(error));
     }
 
-    const messageId = options.messageId ?? randomUUID();
+    const messageId = options.messageId ?? (options.guard ? "" : randomUUID());
+    if (this.pendingSends.has(messageId)) {
+      return Promise.reject(new Error("Message ID already has a pending send"));
+    }
     const message: Message = {
       id: messageId,
       timestamp: Date.now(),
       replyTo: options.replyTo,
       expectsReply: options.expectsReply,
+      guard: options.guard,
+      replyHint: options.replyHint,
       ...(options.human ? { human: options.human } : {}),
       ...(options.topic ? { topic: options.topic } : {}),
-      ...(options.control ? { control: options.control } : {}),
       delivery: messageDelivery(options),
       queueMode: options.queueMode,
       threadId: options.threadId,
@@ -418,6 +478,9 @@ export class IntercomClient extends EventEmitter {
       },
     };
 
+    if ((options.guard || options.replyHint) && normalizeMessage(message) === null) {
+      return Promise.reject(new Error("Invalid message format"));
+    }
     return new Promise((resolve, reject) => {
       const wrappedResolve = (result: SendResult) => {
         clearTimeout(timeout);
@@ -451,6 +514,7 @@ export class IntercomClient extends EventEmitter {
   }
 
   updatePresence(updates: {
+    readonly applicationGuard?: string | null;
     readonly name?: string;
     readonly status?: string;
     readonly model?: string;

package/src/pi-intercom/broker/connection.ts

@@ -1,6 +1,6 @@
 import net from "node:net";
 import { errorMessage } from "../../shared/unknown.ts";
-import { getBrokerSocketPath, getLegacyBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
+import { getBrokerSocketPath, isOwnedBrokerSocket } from "./paths.ts";
 import { createMessageReader, writeMessage } from "./framing.ts";
 
 function connectSocket(socketPath: string, timeoutMs = 500): Promise<net.Socket> {
@@ -30,23 +30,11 @@ function connectSocket(socketPath: string, timeoutMs = 500): Promise<net.Socket>
 }
 
 export async function connectBrokerSocket(): Promise<net.Socket> {
-  const preferred = getBrokerSocketPath();
-  const legacy = getLegacyBrokerSocketPath();
-  const candidates = [preferred, ...(legacy !== preferred ? [legacy] : [])];
-  let lastError: Error | undefined;
-  for (const candidate of candidates) {
-    if (!isOwnedBrokerSocket(candidate)) {
-      continue;
-    }
-    try {
-      // Preferred and legacy sockets must be tried in order, never connected concurrently.
-      // oxlint-disable-next-line no-await-in-loop
-      return await connectSocket(candidate);
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(errorMessage(error));
-    }
+  const socketPath = getBrokerSocketPath();
+  if (!isOwnedBrokerSocket(socketPath)) {
+    throw new Error(`Intercom broker socket is unavailable: ${socketPath}`);
   }
-  throw lastError ?? new Error(`Intercom broker socket is unavailable: ${preferred}`);
+  return await connectSocket(socketPath);
 }
 
 interface ConnectionHandlers {

package/src/pi-intercom/broker/framing.ts

@@ -19,15 +19,19 @@ export function validateIntercomMessageSize(msg: unknown): Error | null {
  * Format: 4-byte big-endian length + JSON payload
  */
 export function writeMessage(socket: Socket, msg: unknown): void {
-  const json = JSON.stringify(msg);
+  writeFrame(socket, JSON.stringify(msg));
+}
+
+/** Write serialized JSON; false means Node accepted it but the caller should wait for drain. */
+export function writeFrame(socket: Socket, json: string, limit = MAX_FRAME_SIZE_BYTES): boolean {
   const size = Buffer.byteLength(json, "utf-8");
-  if (size > MAX_FRAME_SIZE_BYTES) {
-    throw new Error(`Intercom message too large (${size} bytes; max ${MAX_FRAME_SIZE_BYTES})`);
+  if (size > limit) {
+    throw new Error(`Intercom message too large (${size} bytes; max ${limit})`);
   }
   const payload = Buffer.from(json, "utf-8");
   const header = Buffer.alloc(4);
   header.writeUInt32BE(payload.length, 0);
-  socket.write(Buffer.concat([header, payload]));
+  return socket.write(Buffer.concat([header, payload]));
 }
 
 /** Retain fragments until a header or payload is complete; copy each fragmented value once. */
@@ -88,6 +92,7 @@ class MessageBuffer {
 export function createMessageReader(
   onMessage: (msg: unknown) => void,
   onError: (error: Readonly<Error>) => void,
+  limit = MAX_FRAME_SIZE_BYTES,
 ): (data: Buffer) => void {
   const buffer = new MessageBuffer();
   let length: number | undefined;
@@ -98,10 +103,8 @@ export function createMessageReader(
     while (buffer.length >= (length ?? 4)) {
       if (length === undefined) {
         length = buffer.read(4).readUInt32BE(0);
-        if (length > MAX_FRAME_SIZE_BYTES) {
-          onError(
-            new Error(`Intercom frame too large (${length} bytes; max ${MAX_FRAME_SIZE_BYTES})`),
-          );
+        if (length > limit) {
+          onError(new Error(`Intercom frame too large (${length} bytes; max ${limit})`));
           buffer.clear();
           length = undefined;
           return;

package/src/pi-intercom/broker/guard.ts

@@ -0,0 +1,33 @@
+import type { Message, SessionInfo } from "../types.ts";
+
+/** Guarded commands use an exact main, never convenience names or a replacement context. */
+export function guardedDeliveryError(
+  sessions: ReadonlyMap<string, { readonly info: SessionInfo }>,
+  to: string,
+  message: Message,
+): string | null {
+  const guard = message.guard;
+  if (!guard) {
+    return null;
+  }
+  const registered = sessions.get(to);
+  if (!registered || to !== guard.peerId) {
+    return "Guarded target not found";
+  }
+  const target = registered.info;
+  if (target.guardedDelivery !== 1) {
+    return "Recipient does not support guarded delivery";
+  }
+  if (
+    target.parentSessionId !== undefined ||
+    target.rootSessionId !== guard.rootSessionId ||
+    target.incarnation !== guard.incarnation ||
+    target.applicationGuard !== guard.applicationGuard
+  ) {
+    return "Guarded target changed";
+  }
+  const mains = [...sessions.values()].filter(
+    ({ info }) => info.rootSessionId === guard.rootSessionId && info.parentSessionId === undefined,
+  );
+  return mains.length === 1 ? null : "Guarded root is ambiguous";
+}

package/src/pi-intercom/broker/last.ts

@@ -0,0 +1,275 @@
+import type net from "node:net";
+import { randomUUID } from "node:crypto";
+import { isRecord, type UnknownRecord } from "../../shared/unknown.ts";
+import {
+  isDeliveryGuard,
+  isPublicationReplyHint,
+  isLastMessageQuery,
+  isReceiptQuery,
+  LAST_MESSAGE_PAGE_LIMIT,
+  normalizeSessionInfo,
+  type LastMessageQuery,
+  type LastMessageResult,
+  type SessionInfo,
+  type NativeReceipt,
+  type ReceiptQuery,
+  type ReceiptResult,
+} from "../types.ts";
+import { finiteNumber, nonNegativeInteger, optionalLabel, safeLabel } from "../validation.ts";
+import { validateIntercomMessageSize, writeMessage } from "./framing.ts";
+import { messageSender } from "./snapshots.ts";
+import { findSessions } from "./targets.ts";
+
+export type NativeReadQuery = LastMessageQuery | ReceiptQuery;
+export type NativeReadResult = LastMessageResult | ReceiptResult;
+
+export function isNativeReadQuery(value: unknown): value is NativeReadQuery {
+  return isReceiptQuery(value) || isLastMessageQuery(value);
+}
+function isNativeReceipt(value: unknown): value is NativeReceipt {
+  if (!isReceiptQuery(value) || !isRecord(value) || !isRecord(value.sender)) {
+    return false;
+  }
+  return (
+    value.version === 1 &&
+    safeLabel(value.sender.peerId) &&
+    [value.sender.rootSessionId, value.sender.incarnation].every(optionalLabel) &&
+    typeof value.textSha256 === "string" &&
+    /^[a-f0-9]{64}$/.test(value.textSha256) &&
+    receiptPublication(value) &&
+    receiptFacts(value)
+  );
+}
+function receiptPublication(value: UnknownRecord): boolean {
+  return (
+    typeof value.delivery === "string" &&
+    ["queue", "steer", "passive"].includes(value.delivery) &&
+    (value.guard === undefined || isDeliveryGuard(value.guard)) &&
+    (value.replyHint === undefined || isPublicationReplyHint(value.replyHint))
+  );
+}
+function receiptFacts(value: UnknownRecord): boolean {
+  return (
+    safeLabel(value.checkpointEntryId) &&
+    finiteNumber(value.receivedAt) &&
+    [value.queued, value.nativeHandoff, value.discarded].every(
+      (field) => typeof field === "boolean",
+    ) &&
+    (value.placementEntryId === null || safeLabel(value.placementEntryId))
+  );
+}
+export function isReceiptResult(value: unknown): value is ReceiptResult {
+  return isRecord(value) && (typeof value.error === "string" || isNativeReceipt(value.receipt));
+}
+export function isNativeReadResult(value: unknown): value is NativeReadResult {
+  return isReceiptResult(value) || isLastMessageResult(value);
+}
+function pageIdentity(value: UnknownRecord): boolean {
+  return (
+    normalizeSessionInfo(value.session) !== null &&
+    (value.entryId === null || (typeof value.entryId === "string" && value.entryId.length > 0)) &&
+    typeof value.text === "string" &&
+    value.text.length <= LAST_MESSAGE_PAGE_LIMIT
+  );
+}
+function pageOffsets(value: UnknownRecord): boolean {
+  if (
+    !nonNegativeInteger(value.offset) ||
+    !nonNegativeInteger(value.totalLength) ||
+    typeof value.text !== "string"
+  ) {
+    return false;
+  }
+  const end = value.offset + value.text.length;
+  if (value.entryId === null) {
+    return end === 0 && value.totalLength === 0 && value.nextOffset === undefined;
+  }
+  if (value.nextOffset === undefined) {
+    return end === value.totalLength;
+  }
+  return value.nextOffset === end && end < value.totalLength && value.text.length > 0;
+}
+export function isLastMessageResult(value: unknown): value is LastMessageResult {
+  return (
+    isRecord(value) &&
+    (typeof value.error === "string" || (pageIdentity(value) && pageOffsets(value)))
+  );
+}
+interface LastPeer {
+  readonly socket: net.Socket;
+  readonly info: SessionInfo;
+  readonly lastMessages: boolean;
+  readonly receiptReads: boolean;
+}
+interface PendingLast {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly requestId: string;
+  readonly query: NativeReadQuery;
+  readonly timer: NodeJS.Timeout;
+}
+function unavailable(
+  targets: readonly LastPeer[],
+  name: string,
+  pending: number,
+  query: NativeReadQuery,
+): string | undefined {
+  if (targets.length === 0) {
+    return "Session not found";
+  }
+  if (targets.length > 1) {
+    return `Multiple sessions named "${name}" are connected. Use the session ID instead.`;
+  }
+  if (!targets[0].lastMessages) {
+    return "Recipient does not support last-message reads; reload its extension.";
+  }
+  if (
+    "messageId" in query &&
+    (!targets[0].receiptReads || targets[0].info.rootSessionId !== query.rootSessionId)
+  ) {
+    return "publication_unavailable";
+  }
+  if (pending >= 128) {
+    return "Too many pending last-message reads; retry after they settle.";
+  }
+  return undefined;
+}
+function matchesPage(result: NativeReadResult, pending: PendingLast, fromId: string): boolean {
+  if ("error" in result) {
+    return true;
+  }
+  if ("messageId" in pending.query) {
+    return (
+      "receipt" in result &&
+      result.receipt.messageId === pending.query.messageId &&
+      result.receipt.rootSessionId === pending.query.rootSessionId
+    );
+  }
+  if ("receipt" in result) {
+    return false;
+  }
+  return matchesLastPage(result, pending.query, fromId);
+}
+
+function matchesLastPage(
+  result: Exclude<LastMessageResult, { readonly error: string }>,
+  query: LastMessageQuery,
+  fromId: string,
+): boolean {
+  return (
+    result.session.id === fromId &&
+    result.offset === (query.offset ?? 0) &&
+    (query.entryId === undefined || result.entryId === query.entryId) &&
+    result.text.length <= (query.limit ?? LAST_MESSAGE_PAGE_LIMIT)
+  );
+}
+
+/** Correlation belongs to the broker, not the requester or the recipient's model queue. */
+export class LastMessageRelay {
+  private readonly pending = new Map<string, PendingLast>();
+  private readonly sessions: ReadonlyMap<string, LastPeer>;
+  constructor(sessions: ReadonlyMap<string, LastPeer>) {
+    this.sessions = sessions;
+  }
+
+  request(fromId: string, message: UnknownRecord): void {
+    if (
+      typeof message.requestId !== "string" ||
+      typeof message.to !== "string" ||
+      !isNativeReadQuery(message.query)
+    ) {
+      throw new Error("Invalid last message request");
+    }
+    const targets = findSessions(this.sessions, message.to, fromId);
+    const target = targets[0];
+    const from = this.sessions.get(fromId);
+    if (!from) {
+      return;
+    }
+    const token = randomUUID();
+    const frame = {
+      type: "last_request" as const,
+      requestId: token,
+      from: messageSender(from.info),
+      query: message.query,
+    };
+    const error =
+      unavailable(targets, message.to, this.pending.size, message.query) ??
+      validateIntercomMessageSize(frame)?.message;
+    if (error !== undefined) {
+      writeMessage(from.socket, {
+        type: "last_response",
+        requestId: message.requestId,
+        result: { error },
+      });
+      return;
+    }
+    const timer = setTimeout(
+      () => this.finish(token, { error: "Last-message read timed out" }),
+      5000,
+    );
+    timer.unref();
+    this.pending.set(token, {
+      fromId,
+      toId: target.info.id,
+      requestId: message.requestId,
+      query: message.query,
+      timer,
+    });
+    try {
+      writeMessage(target.socket, frame);
+    } catch {
+      this.finish(token, { error: "Recipient disconnected before last-message read" });
+    }
+  }
+
+  respond(fromId: string, message: UnknownRecord): void {
+    if (typeof message.requestId !== "string") {
+      throw new Error("Invalid last message response");
+    }
+    const pending = this.pending.get(message.requestId);
+    if (!pending || pending.toId !== fromId) {
+      return;
+    }
+    const result = message.result;
+    this.finish(
+      message.requestId,
+      isNativeReadResult(result) && matchesPage(result, pending, fromId)
+        ? result
+        : { error: "Recipient returned an invalid last-message page" },
+    );
+  }
+
+  disconnected(sessionId: string): void {
+    for (const [token, pending] of this.pending) {
+      if (pending.fromId === sessionId || pending.toId === sessionId) {
+        this.finish(token, { error: "Peer disconnected during last-message read" });
+      }
+    }
+  }
+
+  private finish(token: string, result: NativeReadResult): void {
+    const pending = this.pending.get(token);
+    if (!pending) {
+      return;
+    }
+    clearTimeout(pending.timer);
+    this.pending.delete(token);
+    const from = this.sessions.get(pending.fromId);
+    if (!from) {
+      return;
+    }
+    const frame = { type: "last_response" as const, requestId: pending.requestId, result };
+    const invalid = validateIntercomMessageSize(frame);
+    writeMessage(
+      from.socket,
+      invalid
+        ? {
+            type: "last_response",
+            requestId: pending.requestId,
+            result: { error: invalid.message },
+          }
+        : frame,
+    );
+  }
+}