@fitchmultz/pi-subagents 0.50.0 → 0.52.0

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,38 @@ interface LastPeer {
   readonly socket: net.Socket;
   readonly info: SessionInfo;
   readonly lastMessages: boolean;
+  readonly receiptReads: boolean;
+  readonly parked?: { readonly closed: boolean };
 }
 interface PendingLast {
   readonly fromId: string;
   readonly toId: string;
+  /** A parked child's main answers from the child's captured native history. */
+  readonly via?: string;
   readonly requestId: string;
-  readonly query: LastMessageQuery;
+  readonly query: NativeReadQuery;
   readonly timer: NodeJS.Timeout;
 }
+/** An exited parked child answers nothing itself; only its main holds the captured history. */
+function exitedRefusal(
+  target: LastPeer,
+  query: NativeReadQuery,
+  via?: LastPeer,
+): string | undefined {
+  if (target.parked?.closed !== true) {
+    return undefined;
+  }
+  // No loaded journal owner answers receipts, with or without its main.
+  if ("messageId" in query) {
+    return "publication_unavailable";
+  }
+  return via === undefined ? "Parked session history is unavailable." : undefined;
+}
 function unavailable(
   targets: readonly LastPeer[],
   name: string,
   pending: number,
+  { query, via }: { readonly query: NativeReadQuery; readonly via?: LastPeer },
 ): string | undefined {
   if (targets.length === 0) {
     return "Session not found";
@@ -84,26 +138,65 @@ function unavailable(
   if (targets.length > 1) {
     return `Multiple sessions named "${name}" are connected. Use the session ID instead.`;
   }
+  const exited = exitedRefusal(targets[0], query, via);
+  if (exited !== undefined) {
+    return exited;
+  }
   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)
   );
 }
 
+function lastRequest(message: UnknownRecord): {
+  readonly requestId: string;
+  readonly to: string;
+  readonly query: NativeReadQuery;
+} {
+  const { requestId, to, query } = message;
+  if (typeof requestId !== "string" || typeof to !== "string" || !isNativeReadQuery(query)) {
+    throw new Error("Invalid last message request");
+  }
+  return { requestId, to, query };
+}
 /** Correlation belongs to the broker, not the requester or the recipient's model queue. */
 export class LastMessageRelay {
   private readonly pending = new Map<string, PendingLast>();
@@ -112,42 +205,36 @@ export class LastMessageRelay {
     this.sessions = sessions;
   }
 
-  request(fromId: string, message: UnknownRecord): void {
-    if (
-      typeof message.requestId !== "string" ||
-      typeof message.to !== "string" ||
-      !isLastMessageQuery(message.query)
-    ) {
-      throw new Error("Invalid last message request");
-    }
+  /** `reader` names another peer that answers for an exited target from its captured history. */
+  request(
+    fromId: string,
+    input: UnknownRecord,
+    reader: (id: string) => LastPeer | undefined,
+  ): void {
+    const message = lastRequest(input);
     const targets = findSessions(this.sessions, message.to, fromId);
     const target = targets[0];
     const from = this.sessions.get(fromId);
     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 via = targets.length === 1 ? reader(target.info.id) : undefined;
     const frame = {
       type: "last_request" as const,
       requestId: token,
       from: messageSender(from.info),
       query: message.query,
+      parked: via && messageSender(target.info),
     };
-    const invalid = validateIntercomMessageSize(frame);
-    if (invalid) {
+    const error =
+      unavailable(targets, message.to, this.pending.size, { query: message.query, via }) ??
+      validateIntercomMessageSize(frame)?.message;
+    if (error !== undefined) {
       writeMessage(from.socket, {
         type: "last_response",
         requestId: message.requestId,
-        result: { error: invalid.message },
+        result: { error },
       });
       return;
     }
@@ -159,12 +246,13 @@ export class LastMessageRelay {
     this.pending.set(token, {
       fromId,
       toId: target.info.id,
+      via: via?.info.id,
       requestId: message.requestId,
       query: message.query,
       timer,
     });
     try {
-      writeMessage(target.socket, frame);
+      writeMessage((via ?? target).socket, frame);
     } catch {
       this.finish(token, { error: "Recipient disconnected before last-message read" });
     }
@@ -175,13 +263,13 @@ export class LastMessageRelay {
       throw new Error("Invalid last message response");
     }
     const pending = this.pending.get(message.requestId);
-    if (!pending || pending.toId !== fromId) {
+    if (!pending || (pending.via ?? pending.toId) !== fromId) {
       return;
     }
     const result = message.result;
     this.finish(
       message.requestId,
-      isLastMessageResult(result) && matchesPage(result, pending, fromId)
+      isNativeReadResult(result) && matchesPage(result, pending, pending.toId)
         ? result
         : { error: "Recipient returned an invalid last-message page" },
     );
@@ -189,13 +277,13 @@ export class LastMessageRelay {
 
   disconnected(sessionId: string): void {
     for (const [token, pending] of this.pending) {
-      if (pending.fromId === sessionId || pending.toId === sessionId) {
+      if ([pending.fromId, pending.toId, pending.via].includes(sessionId)) {
         this.finish(token, { error: "Peer disconnected during last-message read" });
       }
     }
   }
 
-  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/parked.ts

@@ -0,0 +1,130 @@
+import type net from "net";
+import { randomUUID } from "crypto";
+import type { Message, SessionInfo } from "../types.ts";
+import { nativePeerId } from "../session-targets.ts";
+import { writeMessage } from "./framing.ts";
+
+type Retained = Array<{ readonly from: SessionInfo; readonly message: Message }>;
+interface Parked {
+  readonly retained: Retained;
+  /** The fenced actor's socket closed: input waits for its restored replacement. */
+  closed: boolean;
+}
+export interface ParkablePeer {
+  readonly socket: net.Socket;
+  readonly info: SessionInfo;
+  /** This client can park itself, or wake and answer for its parked children. */
+  readonly parking: boolean;
+  parked?: Parked;
+}
+export function reachable<T extends ParkablePeer>(target?: T): target is T {
+  const socket = target?.socket;
+  return socket !== undefined && !socket.destroyed && socket.writable && !socket.writableEnded;
+}
+type Deliver = (id: string, from: SessionInfo, message: Message) => string | null;
+function requested(id: unknown): string | undefined {
+  return typeof id === "string" && /^[a-zA-Z0-9_-]{8,80}$/.test(id) ? id : undefined;
+}
+
+/** A fenced child keeps its identity and queued input; it never departs while parked. */
+export class ParkedSessions<T extends ParkablePeer> {
+  private readonly sessions: ReadonlyMap<string, T>;
+  private readonly deliver: Deliver;
+  constructor(sessions: ReadonlyMap<string, T>, deliver: Deliver) {
+    this.sessions = sessions;
+    this.deliver = deliver;
+  }
+  park(socket: net.Socket, id: string, on: boolean): void {
+    const session = this.sessions.get(id);
+    if (on && session?.parking === true) {
+      session.parked ??= { retained: [], closed: false };
+      // Frames already written to this socket precede the acknowledgement.
+      writeMessage(socket, { type: "parked" });
+    } else if (!on && session?.parked?.closed === false) {
+      const { retained } = session.parked;
+      session.parked = undefined;
+      this.flush(id, retained);
+    }
+  }
+  /**
+   * Delivers retained input in order. A transport that fails mid-flush keeps the rest for its
+   * next generation; delivery refusals on a live transport follow resident delivery.
+   */
+  private flush(id: string, retained: Retained): void {
+    for (const [index, { from, message }] of retained.entries()) {
+      const session = this.sessions.get(id);
+      if (this.deliver(id, from, message) !== null && session?.socket.writable === false) {
+        session.parked = { retained: retained.slice(index), closed: false };
+        return;
+      }
+    }
+  }
+  /** A free requested identity, or a parked one resumed by the same child lineage. */
+  claim(requestedId: unknown, next: Omit<SessionInfo, "id">): { id: string; resumed?: T } {
+    const id = requested(requestedId);
+    const previous = id === undefined ? undefined : this.sessions.get(id);
+    const resumes =
+      previous?.parked !== undefined &&
+      previous.info.rootSessionId === next.rootSessionId &&
+      previous.info.parentSessionId === next.parentSessionId;
+    if (id === undefined || (previous && !resumes)) {
+      return { id: randomUUID() };
+    }
+    previous?.socket.destroy();
+    return { id, resumed: previous };
+  }
+  /** Flushes a restored child's input and re-sends wakes owed to a (re)registered main. */
+  registered(id: string, previous?: T): void {
+    this.flush(id, previous?.parked?.retained ?? []);
+    for (const child of this.sessions.values()) {
+      if (nativePeerId(child.info.rootSessionId ?? "") === id) {
+        this.wake(child);
+      }
+    }
+  }
+  /** A transport handoff, not a departure: no session_left and queued input stays. */
+  closed(session: T): boolean {
+    const { parked } = session;
+    if (parked) {
+      parked.closed = true;
+      this.wake(session);
+    }
+    return parked !== undefined;
+  }
+  /**
+   * Exited parked children keep identities while some live session remains. Input already
+   * admitted for one keeps the broker until a returning main wakes it.
+   */
+  get exited(): boolean {
+    return [...this.sessions.values()].every(
+      ({ parked }) => parked?.closed === true && parked.retained.length === 0,
+    );
+  }
+  retain(target: T | undefined, from: SessionInfo, message: Message): boolean {
+    target?.parked?.retained.push({ from, message });
+    if (target) {
+      this.wake(target);
+    }
+    return target?.parked !== undefined;
+  }
+  /** Reads of an exited parked child go to its main, which answers from captured history. */
+  reader(id: string): T | undefined {
+    const child = this.sessions.get(id);
+    return child?.parked?.closed === true ? this.main(child) : undefined;
+  }
+  // Passive breadcrumbs and topic updates wait for a genuine wake; they never spawn the child.
+  private wake(child: T): void {
+    const main = this.main(child);
+    const wakes = child.parked?.retained.some(
+      ({ message }) =>
+        message.passive !== true && message.delivery !== "passive" && message.topic === undefined,
+    );
+    if (main && child.parked?.closed === true && wakes === true) {
+      writeMessage(main.socket, { type: "wake", sessionId: child.info.id });
+    }
+  }
+  private main(child: T): T | undefined {
+    const main = this.sessions.get(nativePeerId(child.info.rootSessionId ?? ""));
+    return main?.parking === true && main.parked === undefined ? main : undefined;
+  }
+}

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,
@@ -12,7 +37,7 @@ type ClientMessageHandler = (
 export function acceptBrokerConnection(
   socket: net.Socket,
   handleMessage: ClientMessageHandler,
-  disconnected: (sessionId: string) => void,
+  disconnected: (sessionId: string, socket: net.Socket) => void,
 ): void {
   let sessionId: string | null = null;
   socket.on(
@@ -29,7 +54,7 @@ export function acceptBrokerConnection(
   );
   socket.on("close", () => {
     if (sessionId !== null) {
-      disconnected(sessionId);
+      disconnected(sessionId, socket);
     }
   });
   socket.on("error", (error: Error) => {