@fitchmultz/pi-subagents 0.50.0 → 0.51.0

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

@@ -5,7 +5,7 @@ import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
 import { LastMessageRequests } from "./client-last.ts";
-import { isLastMessageQuery, isLastMessageResult } from "./last.ts";
+import { isNativeReadQuery, isNativeReadResult, type NativeReadQuery } from "./last.ts";
 import {
   errorMessage,
   isRecord,
@@ -18,16 +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";
 
@@ -43,20 +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;
-}
-
 function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(errorMessage(error));
 }
@@ -79,7 +65,9 @@ export class IntercomClient extends EventEmitter {
   private _sessionId: string | null = null;
   private _topicsSupported = false;
   private lastMessagesSupported = false;
-  private readonly lastRequests = new LastMessageRequests();
+  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 }
@@ -101,6 +89,7 @@ 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 {
@@ -122,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 &&
@@ -165,6 +157,8 @@ export class IntercomClient extends EventEmitter {
           this._sessionId = null;
           this._topicsSupported = false;
           this.lastMessagesSupported = false;
+          this.receiptReadsSupported = false;
+          this.guardedDeliverySupported = false;
           this.disconnecting = false;
           this.failPending(error);
           if (established && !expected) {
@@ -181,6 +175,8 @@ export class IntercomClient extends EventEmitter {
           requestedId,
           topicFrames: true,
           lastMessages: true,
+          receiptReads: 1,
+          guardedDelivery: 1,
         });
       } catch (error) {
         if (this.connection === connection) {
@@ -266,13 +262,15 @@ 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 || !isLastMessageQuery(msg.query)) {
+    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 })) {
@@ -351,20 +349,25 @@ export class IntercomClient extends EventEmitter {
     return this.requestSessions().then((snapshot) => [...snapshot.sessions]);
   }
 
-  last(to: string, query: LastMessageQuery = {}): Promise<LastMessageResult> {
-    try {
-      const socket = this.requireActiveSocket();
-      if (!this.lastMessagesSupported) {
-        throw new Error("This broker does not support last-message reads; reload after it exits.");
-      }
-      return this.lastRequests.request(socket, to, query, this.listTimeoutMs);
-    } catch (error) {
-      return Promise.reject(toError(error));
+  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 (!isLastMessageResult(result)) {
+    if (!isNativeReadResult(result)) {
       throw new Error("Invalid last-message result");
     }
     writeMessage(this.requireActiveSocket(), { type: "last_response", requestId, result });
@@ -410,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();
@@ -434,20 +439,33 @@ 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 } : {}),
       delivery: messageDelivery(options),
@@ -460,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);
@@ -493,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/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

@@ -2,34 +2,68 @@ 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 const LAST_MESSAGE_PAGE_LIMIT = 16384;
+export type NativeReadQuery = LastMessageQuery | ReceiptQuery;
+export type NativeReadResult = LastMessageResult | ReceiptResult;
 
-function nonNegativeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export function isNativeReadQuery(value: unknown): value is NativeReadQuery {
+  return isReceiptQuery(value) || isLastMessageQuery(value);
 }
-function optionalEntryId(value: unknown): boolean {
-  return value === undefined || (typeof value === "string" && value.length > 0);
+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)
+  );
 }
-export function isLastMessageQuery(value: unknown): value is LastMessageQuery {
+function receiptPublication(value: UnknownRecord): boolean {
   return (
-    isRecord(value) &&
-    optionalEntryId(value.entryId) &&
-    (value.offset === undefined || nonNegativeInteger(value.offset)) &&
-    (value.limit === undefined ||
-      (nonNegativeInteger(value.limit) &&
-        value.limit > 0 &&
-        value.limit <= LAST_MESSAGE_PAGE_LIMIT))
+    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 &&
@@ -65,18 +99,20 @@ 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: LastMessageQuery;
+  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";
@@ -87,20 +123,44 @@ function unavailable(
   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: LastMessageResult, pending: PendingLast, fromId: string): boolean {
+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 === (pending.query.offset ?? 0) &&
-    (pending.query.entryId === undefined || result.entryId === pending.query.entryId) &&
-    result.text.length <= (pending.query.limit ?? LAST_MESSAGE_PAGE_LIMIT)
+    result.offset === (query.offset ?? 0) &&
+    (query.entryId === undefined || result.entryId === query.entryId) &&
+    result.text.length <= (query.limit ?? LAST_MESSAGE_PAGE_LIMIT)
   );
 }
 
@@ -116,7 +176,7 @@ export class LastMessageRelay {
     if (
       typeof message.requestId !== "string" ||
       typeof message.to !== "string" ||
-      !isLastMessageQuery(message.query)
+      !isNativeReadQuery(message.query)
     ) {
       throw new Error("Invalid last message request");
     }
@@ -126,15 +186,6 @@ export class LastMessageRelay {
     if (!from) {
       return;
     }
-    const error = unavailable(targets, message.to, this.pending.size);
-    if (error !== undefined) {
-      writeMessage(from.socket, {
-        type: "last_response",
-        requestId: message.requestId,
-        result: { error },
-      });
-      return;
-    }
     const token = randomUUID();
     const frame = {
       type: "last_request" as const,
@@ -142,12 +193,14 @@ export class LastMessageRelay {
       from: messageSender(from.info),
       query: message.query,
     };
-    const invalid = validateIntercomMessageSize(frame);
-    if (invalid) {
+    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: invalid.message },
+        result: { error },
       });
       return;
     }
@@ -181,7 +234,7 @@ export class LastMessageRelay {
     const result = message.result;
     this.finish(
       message.requestId,
-      isLastMessageResult(result) && matchesPage(result, pending, fromId)
+      isNativeReadResult(result) && matchesPage(result, pending, fromId)
         ? result
         : { error: "Recipient returned an invalid last-message page" },
     );
@@ -195,7 +248,7 @@ export class LastMessageRelay {
     }
   }
 
-  private finish(token: string, result: LastMessageResult): void {
+  private finish(token: string, result: NativeReadResult): void {
     const pending = this.pending.get(token);
     if (!pending) {
       return;

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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { getPiAgentDir } from "../agent-dir.ts";
 
 const MAX_UNIX_SOCKET_PATH_BYTES = 100;
@@ -36,37 +36,64 @@ export function isOwnedBrokerSocket(socketPath: string): boolean {
   }
 }
 
-/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
-export function getBrokerRuntimeDir(): string {
+function defaultRuntimeRoot(): string {
+  if (process.platform !== "android") {
+    return "/tmp";
+  }
+  return process.env.PREFIX === undefined ? tmpdir() : join(process.env.PREFIX, "tmp");
+}
+
+function runtimeDirectory(socketName: string, sibling = ""): string {
   const configured = process.env.PI_INTERCOM_RUNTIME_DIR;
   const uid = process.getuid?.();
   if (uid === undefined) {
     throw new Error("Intercom requires Unix user IDs and Unix domain sockets.");
   }
-  const directory = configured ?? join("/tmp", `pi-intercom-${uid}`);
+  const base = configured ?? join(defaultRuntimeRoot(), `pi-intercom-${uid}`);
+  const directory = isAbsolute(base) && sibling !== "" ? `${resolve(base)}${sibling}` : base;
   if (
     !isAbsolute(directory) ||
     directory.includes("\0") ||
-    Buffer.byteLength(join(directory, "broker.sock")) > MAX_UNIX_SOCKET_PATH_BYTES
+    Buffer.byteLength(join(directory, socketName)) > MAX_UNIX_SOCKET_PATH_BYTES
   ) {
     throw new Error("PI_INTERCOM_RUNTIME_DIR must be an absolute short Unix socket directory.");
   }
   return directory;
 }
 
+/** A deployment can explicitly opt out of same-user discovery with a private runtime directory. */
+export function getBrokerRuntimeDir(): string {
+  return runtimeDirectory("broker.sock");
+}
+
+/** Read-only child observation endpoints share the runtime policy, not the broker namespace.
+ * The endpoint name is a short token digest because the private runtime directory also counts
+ * toward the Unix-socket path limit; a full token made nested test/deployment roots overflow. */
+export function agentObservationSocketPath(token: string): string {
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(token)) {
+    throw new Error("Invalid actor token.");
+  }
+  const name = `obs-${createHash("sha256").update(token).digest("hex").slice(0, 16)}.sock`;
+  return join(runtimeDirectory(name, "-agents"), name);
+}
+
 export function getBrokerSocketPath(): string {
   return join(getBrokerRuntimeDir(), "broker.sock");
 }
 
-export function prepareBrokerSocketPath(): string {
-  const socketPath = getBrokerSocketPath();
-  const brokerDir = dirname(socketPath);
-  fs.mkdirSync(brokerDir, { recursive: true, mode: 0o700 });
-  const stat = fs.lstatSync(brokerDir);
+/** Create or verify an owned, non-symlink, private socket directory. */
+export function preparePrivateSocketPath(socketPath: string): string {
+  const directory = dirname(socketPath);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
   const uid = process.getuid?.();
   if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) {
-    throw new Error(`Unsafe intercom socket directory: ${brokerDir}`);
+    throw new Error(`Unsafe intercom socket directory: ${directory}`);
   }
-  fs.chmodSync(brokerDir, 0o700);
+  fs.chmodSync(directory, 0o700);
   return socketPath;
 }
+
+export function prepareBrokerSocketPath(): string {
+  return preparePrivateSocketPath(getBrokerSocketPath());
+}

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

@@ -80,6 +80,11 @@ export function brokerPidRecord(): string {
 }
 
 export function isBrokerPidReused(pid: number, record: string): boolean {
+  return isLinuxProcessReplaced(pid, record.slice(record.indexOf("\n") + 1));
+}
+
+/** True only when a live Linux PID provably names a different process than the identity. */
+export function isLinuxProcessReplaced(pid: number, identity: string): boolean {
   const current = readLinuxProcess(pid);
   if (!current) {
     return false;
@@ -87,7 +92,7 @@ export function isBrokerPidReused(pid: number, record: string): boolean {
   if (current.tgid !== pid) {
     return true;
   }
-  const saved = IDENTITY.exec(record.slice(record.indexOf("\n") + 1).trim());
+  const saved = IDENTITY.exec(identity.trim());
   const actual = IDENTITY.exec(current.identity ?? "");
   if (!saved || !actual) {
     return false;

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

@@ -1,5 +1,30 @@
 import type net from "node:net";
+import { randomUUID } from "node:crypto";
 import { createMessageReader } from "./framing.ts";
+import { assertMainParent } from "./targets.ts";
+import { isSessionRegistration, type SessionInfo } from "../types.ts";
+import type { UnknownRecord } from "../../shared/unknown.ts";
+
+export function registeredSessionInfo(
+  msg: UnknownRecord,
+  sessions: ReadonlyMap<string, { readonly info: SessionInfo }>,
+): SessionInfo {
+  if (!isSessionRegistration(msg.session)) {
+    throw new Error("Invalid register message");
+  }
+  assertMainParent(msg.session, sessions);
+  const requestedId =
+    typeof msg.requestedId === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(msg.requestedId)
+      ? msg.requestedId
+      : undefined;
+  const id = requestedId !== undefined && !sessions.has(requestedId) ? requestedId : randomUUID();
+  return {
+    ...msg.session,
+    id,
+    guardedDelivery: msg.guardedDelivery === 1 ? msg.session.guardedDelivery : undefined,
+    lastSeen: msg.session.lastSeen ?? Date.now(),
+  };
+}
 
 type ClientMessageHandler = (
   socket: net.Socket,