@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/dist/builtin/intercom/broker/bounded-stderr.ts

@@ -0,0 +1,132 @@
+import { format } from "node:util";
+
+/**
+ * Physical cap for `broker.log`, enforced inside the broker process.
+ *
+ * The parent hands the detached broker an already-open descriptor and then exits; nothing on
+ * the parent side can bound what the child appends afterwards. Truncating the file from outside
+ * does not help either: a POSIX `O_APPEND` descriptor simply writes at the new end of file, and
+ * on Windows the inherited append handle has no truncate right. So the limit is applied where
+ * the bytes originate, inside the broker.
+ */
+export const BROKER_LOG_MAX_BYTES = 8 * 1024;
+
+interface WritableLike {
+  write(chunk: string | Uint8Array, ...rest: never[]): boolean;
+}
+
+interface ConsoleLike {
+  error(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+}
+interface FatalHandlerHost {
+  on(event: "uncaughtException" | "unhandledRejection", listener: (value: unknown) => void): unknown;
+  off?(event: "uncaughtException" | "unhandledRejection", listener: (value: unknown) => void): unknown;
+  exit(code?: number): never;
+}
+
+export interface BoundedStderrOptions {
+  readonly maxBytes?: number;
+  readonly stream?: WritableLike;
+  readonly console?: ConsoleLike;
+  /** Host for the fatal-error handlers. Pass `null` to skip installing them. */
+  readonly process?: FatalHandlerHost | null;
+}
+
+export interface BoundedStderrHandle {
+  /** Bytes accepted so far, for tests and diagnostics. */
+  readonly writtenBytes: () => number;
+  /** Bounded writer, for callers that must report something without breaking the cap. */
+  readonly write: (text: string) => void;
+  /** Undo every patch this installation made. */
+  readonly restore: () => void;
+}
+
+/**
+ * Cap everything this process can append to its stderr.
+ *
+ * Three routes reach the log and each needs its own patch:
+ *
+ * 1. `process.stderr.write` — the stream itself.
+ * 2. `console.error` / `console.warn` — Bun's console is native and writes to the file
+ *    descriptor directly, so patching the stream alone leaves it uncapped. Measured: a Bun
+ *    child with only the stream patched wrote 1001 bytes against a 100-byte cap.
+ * 3. Node's and Bun's default fatal printing for an uncaught exception or an unhandled
+ *    rejection, which does not go through the stream either. Measured under Node: a fatal
+ *    error produced a 20 KiB log despite the stream patch.
+ *
+ * Bytes are counted rather than characters, only the portion that still fits is forwarded, and
+ * writes past the cap report success and run their callbacks without writing. No "limit
+ * reached" notice is emitted: such a notice would itself have to exceed the cap it announces.
+ *
+ * A native addon writing straight to file descriptor 2, or a child process of the broker, would
+ * bypass this. The broker's own module graph contains neither.
+ */
+export function installBoundedStderr(options: BoundedStderrOptions = {}): BoundedStderrHandle {
+  const maxBytes = options.maxBytes ?? BROKER_LOG_MAX_BYTES;
+  const stream: WritableLike = options.stream ?? process.stderr;
+  const consoleObject: ConsoleLike = options.console ?? console;
+  const fatalHost = options.process === undefined ? (process as unknown as FatalHandlerHost) : options.process;
+
+  const originalWrite = stream.write.bind(stream) as WritableLike["write"];
+  const originalError = consoleObject.error.bind(consoleObject);
+  const originalWarn = consoleObject.warn.bind(consoleObject);
+  let written = 0;
+
+  /** Forward at most the remaining budget; returns whether anything reached the stream. */
+  const forward = (buffer: Buffer, callback?: (error?: Error | null) => void): boolean => {
+    const remaining = maxBytes - written;
+    if (remaining <= 0) {
+      callback?.(null);
+      return true;
+    }
+    const slice = buffer.length <= remaining ? buffer : buffer.subarray(0, remaining);
+    written += slice.length;
+    return callback
+      ? (originalWrite as (chunk: Uint8Array, cb: (error?: Error | null) => void) => boolean)(slice, callback)
+      : originalWrite(slice);
+  };
+
+  const boundedWrite = (
+    chunk: string | Uint8Array,
+    encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+    maybeCallback?: (error?: Error | null) => void,
+  ): boolean => {
+    const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+    const callback = typeof encodingOrCallback === "function" ? encodingOrCallback : maybeCallback;
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk, encoding ?? "utf-8") : Buffer.from(chunk);
+    return forward(buffer, callback);
+  };
+
+  const writeText = (text: string): void => {
+    forward(Buffer.from(text, "utf-8"));
+  };
+
+  // The casts keep the public `write`/`console` signatures intact for callers.
+  stream.write = boundedWrite as unknown as WritableLike["write"];
+  consoleObject.error = (...args: unknown[]): void => {
+    writeText(`${format(...args)}\n`);
+  };
+  consoleObject.warn = consoleObject.error;
+
+  const onFatal = (value: unknown): void => {
+    writeText(`${value instanceof Error ? (value.stack ?? value.message) : format(value)}\n`);
+    fatalHost?.exit(1);
+  };
+  if (fatalHost) {
+    fatalHost.on("uncaughtException", onFatal);
+    fatalHost.on("unhandledRejection", onFatal);
+  }
+
+  return {
+    writtenBytes: () => written,
+    write: writeText,
+    restore: () => {
+      stream.write = originalWrite;
+      consoleObject.error = originalError;
+      consoleObject.warn = originalWarn;
+      fatalHost?.off?.("uncaughtException", onFatal);
+      fatalHost?.off?.("unhandledRejection", onFatal);
+    },
+  };
+}

package/dist/builtin/intercom/broker/broker.ts

@@ -1,3 +1,6 @@
+// MUST stay first: ESM evaluates static dependencies before the importer's body, so this is the
+// only position from which the stderr cap covers the other modules' own initialization.
+import "./bounded-stderr-install.js";
 import net from "net";
 import { writeFileSync, unlinkSync, mkdirSync } from "fs";
 import { randomUUID } from "crypto";
@@ -8,6 +11,7 @@ import { DeliveredMessageCache } from "./delivered-message-cache.js";
 import { handleBrokerSend, type BrokerConnectedSession } from "./send-handler.js";
 import { SupervisorChannelCache } from "./supervisor-channel.js";
 import { normalizeGroup } from "../group.js";
+import { handleBrokerPresence } from "./presence-handler.js";
 
 const INTERCOM_DIR = getIntercomDirPath();
 const SOCKET_PATH = getBrokerSocketPath();
@@ -249,29 +253,13 @@ class IntercomBroker {
       }
 
       case "presence": {
-        const session = this.sessions.get(currentId);
-        if (session) {
-          if (clientMessage.name !== undefined) {
-            if (typeof clientMessage.name !== "string") {
-              throw new Error("Invalid presence name");
-            }
-            session.info.name = clientMessage.name;
-          }
-          if (clientMessage.status !== undefined) {
-            if (typeof clientMessage.status !== "string") {
-              throw new Error("Invalid presence status");
-            }
-            session.info.status = clientMessage.status;
-          }
-          if (clientMessage.model !== undefined) {
-            if (typeof clientMessage.model !== "string") {
-              throw new Error("Invalid presence model");
-            }
-            session.info.model = clientMessage.model;
-          }
-          session.info.lastActivity = Date.now();
-          this.broadcastToGroup({ type: "presence_update", session: session.info }, session.info.group, currentId);
-        }
+        handleBrokerPresence(
+          socket,
+          clientMessage,
+          currentId,
+          this.sessions,
+          (target, message) => writeMessage(target, message),
+        );
         break;
       }
 
@@ -314,4 +302,5 @@ class IntercomBroker {
   }
 }
 
+// The stderr cap is already in place: `./bounded-stderr-install.js` is this file's first import.
 new IntercomBroker().start();

package/dist/builtin/intercom/broker/client.ts

@@ -9,6 +9,8 @@ import { readSubagentMessageSource } from "../source-ownership.js";
 import { isMessage, isSessionInfo } from "./client-message-validation.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
+const PRESENCE_ACK_TIMEOUT_MS = 5000;
+
 
 export interface SendOptions {
   text: string;
@@ -24,6 +26,13 @@ export interface SendResult {
   delivered: boolean;
   reason?: string;
 }
+export interface PresenceUpdates {
+  name?: string;
+  status?: string;
+  model?: string;
+  group?: string;
+}
+
 
 export interface SupervisorAuthorization extends SupervisorRegistration {
   childName: string;
@@ -38,8 +47,12 @@ export class IntercomClient extends EventEmitter {
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
   private _supervisorSessionId: string | null = null;
+  /** Source identity is captured once at connect, never read from env per message. */
+  private _messageSource: Message["source"] | undefined;
   private pendingSends = new PendingSendRegistry();
   private pendingLists = new Map<string, { resolve: (sessions: SessionInfo[]) => void; reject: (e: Error) => void }>();
+  private pendingPresence = new Map<string, { resolve: (group: string) => void; reject: (error: Error) => void }>();
+
   private pendingSupervisorAuthorizations = new Map<string, {
     resolve: (authorization: SupervisorAuthorization) => void;
     reject: (error: Error) => void;
@@ -51,10 +64,13 @@ export class IntercomClient extends EventEmitter {
     this.pendingSends.rejectAll(error);
     for (const pending of this.pendingLists.values()) pending.reject(error);
     for (const pending of this.pendingSupervisorAuthorizations.values()) pending.reject(error);
+    for (const pending of this.pendingPresence.values()) pending.reject(error);
     this.pendingLists.clear();
     this.pendingSupervisorAuthorizations.clear();
+    this.pendingPresence.clear();
   }
 
+
   get sessionId(): string | null {
     return this._sessionId;
   }
@@ -85,10 +101,16 @@ export class IntercomClient extends EventEmitter {
     return socket;
   }
 
-  connect(session: Omit<SessionInfo, "id">, supervisor?: SupervisorRegistration, supervisorOwnerToken?: string): Promise<void> {
+  connect(
+    session: Omit<SessionInfo, "id">,
+    supervisor?: SupervisorRegistration,
+    supervisorOwnerToken?: string,
+    messageSource?: Message["source"],
+  ): Promise<void> {
     if (this.socket) {
       return Promise.reject(new Error("Already connected"));
     }
+    this._messageSource = messageSource ?? readSubagentMessageSource();
 
     return new Promise((resolve, reject) => {
       const socket = net.connect(BROKER_SOCKET);
@@ -141,6 +163,7 @@ export class IntercomClient extends EventEmitter {
         }
         this._sessionId = null;
         this._supervisorSessionId = null;
+        this._messageSource = undefined;
         this.disconnectError = null;
         if (connectionEstablished && !wasDisconnecting) {
           this.emit("disconnected", disconnectError);
@@ -322,6 +345,26 @@ export class IntercomClient extends EventEmitter {
         this.emit("presence_update", brokerMessage.session);
         break;
       }
+      case "presence_ack": {
+        if (typeof brokerMessage.requestId !== "string" || typeof brokerMessage.group !== "string") {
+          throw new Error("Invalid presence_ack message");
+        }
+        const pending = this.pendingPresence.get(brokerMessage.requestId);
+        if (!pending) return;
+        this.pendingPresence.delete(brokerMessage.requestId);
+        pending.resolve(brokerMessage.group);
+        break;
+      }
+      case "presence_failed": {
+        if (typeof brokerMessage.requestId !== "string" || typeof brokerMessage.reason !== "string") {
+          throw new Error("Invalid presence_failed message");
+        }
+        const pending = this.pendingPresence.get(brokerMessage.requestId);
+        if (!pending) return;
+        this.pendingPresence.delete(brokerMessage.requestId);
+        pending.reject(new Error(brokerMessage.reason));
+        break;
+      }
       case "error": {
         if (typeof brokerMessage.error !== "string") {
           throw new Error("Invalid error message");
@@ -463,7 +506,7 @@ export class IntercomClient extends EventEmitter {
       replyTo: options.replyTo,
       expectsReply: options.expectsReply,
       replyError: options.replyError,
-      source: readSubagentMessageSource(),
+      source: this._messageSource,
       content: { text: options.text, attachments: options.attachments },
     };
     try {
@@ -473,14 +516,47 @@ export class IntercomClient extends EventEmitter {
     }
     return acquired.attempt.promise;
   }
-  updatePresence(updates: { name?: string; status?: string; model?: string }): void {
+  updatePresence(updates: PresenceUpdates): boolean {
     if (this.disconnecting) {
-      return;
+      return false;
     }
     const socket = this.socket;
     if (!socket || !this._sessionId || socket.destroyed || socket.writableEnded || !socket.writable) {
-      return;
+      return false;
     }
     writeMessage(socket, { type: "presence", ...updates });
+    return true;
+  }
+
+  updatePresenceAcked(updates: PresenceUpdates): Promise<string> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      const wrappedResolve = (group: string): void => {
+        clearTimeout(timeout);
+        resolve(group);
+      };
+      const wrappedReject = (error: Error): void => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      const timeout = setTimeout(() => {
+        if (!this.pendingPresence.delete(requestId)) return;
+        reject(new Error("Presence update timeout"));
+      }, PRESENCE_ACK_TIMEOUT_MS);
+      this.pendingPresence.set(requestId, { resolve: wrappedResolve, reject: wrappedReject });
+      try {
+        writeMessage(socket, { type: "presence", ...updates, requestId });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingPresence.delete(requestId);
+        reject(toError(error));
+      }
+    });
   }
 }

package/dist/builtin/intercom/broker/paths.ts

@@ -46,6 +46,15 @@ export function getBrokerSpawnLockPath(agentDir: string = getAgentDir()): string
   return join(getIntercomDirPath(agentDir), "broker.spawn.lock");
 }
 
+/**
+ * Startup/diagnostic log for the detached broker process. The parent opens this file
+ * and hands the descriptor to the child as stderr, so a broker that dies before it can
+ * accept connections leaves a readable reason behind for whichever process inspects it.
+ */
+export function getBrokerLogPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker.log");
+}
+
 export function getBrokerSocketPath(
   platform: NodeJS.Platform = process.platform,
   agentDir: string = getAgentDir(),

package/dist/builtin/intercom/broker/presence-handler.ts

@@ -0,0 +1,103 @@
+import type net from "node:net";
+import type { BrokerMessage } from "../types.js";
+import { normalizeGroup, validateRuntimeGroup } from "../group.js";
+import type { BrokerConnectedSession } from "./send-handler.js";
+
+interface PresenceClientMessage extends Record<string, unknown> {
+	type: string;
+}
+
+type WriteMessage = (socket: net.Socket, message: BrokerMessage) => void;
+
+function broadcastToGroup(
+	sessions: Map<string, BrokerConnectedSession>,
+	write: WriteMessage,
+	message: BrokerMessage,
+	group: string | undefined,
+	exclude?: string,
+): void {
+	const target = normalizeGroup(group);
+	for (const [id, session] of sessions) {
+		if (id !== exclude && normalizeGroup(session.info.group) === target) {
+			write(session.socket, message);
+		}
+	}
+}
+
+/** Apply one presence update and notify only the affected group members. */
+export function handleBrokerPresence(
+	socket: net.Socket,
+	clientMessage: PresenceClientMessage,
+	currentId: string | null,
+	sessions: Map<string, BrokerConnectedSession>,
+	write: WriteMessage,
+): void {
+	const rawRequestId = clientMessage.requestId;
+	if (rawRequestId !== undefined && typeof rawRequestId !== "string") {
+		throw new Error("Invalid presence requestId");
+	}
+	const requestId = typeof rawRequestId === "string" ? rawRequestId : undefined;
+	if (currentId === null) {
+		if (requestId !== undefined) {
+			write(socket, { type: "presence_failed", requestId, reason: "Session not found" });
+		}
+		return;
+	}
+	const sessionId = currentId;
+	const session = sessions.get(sessionId);
+	if (!session) {
+		if (requestId !== undefined) {
+			write(socket, { type: "presence_failed", requestId, reason: "Session not found" });
+		}
+		return;
+	}
+
+	const fail = (reason: string): boolean => {
+		if (requestId === undefined) throw new Error(reason);
+		write(socket, { type: "presence_failed", requestId, reason });
+		return true;
+	};
+
+	const previousGroup = normalizeGroup(session.info.group);
+	let nextGroup = previousGroup;
+	const rawGroup = clientMessage.group;
+	if (rawGroup !== undefined) {
+		if (typeof rawGroup !== "string") {
+			if (fail("Invalid presence group")) return;
+		} else {
+			try {
+				nextGroup = validateRuntimeGroup(rawGroup);
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				if (fail(`Invalid presence group: ${reason}`)) return;
+			}
+		}
+	}
+	const name = clientMessage.name;
+	if (name !== undefined && typeof name !== "string") {
+		if (fail("Invalid presence name")) return;
+	}
+	const status = clientMessage.status;
+	if (status !== undefined && typeof status !== "string") {
+		if (fail("Invalid presence status")) return;
+	}
+	const model = clientMessage.model;
+	if (model !== undefined && typeof model !== "string") {
+		if (fail("Invalid presence model")) return;
+	}
+
+	if (typeof name === "string") session.info.name = name;
+	if (typeof status === "string") session.info.status = status;
+	if (typeof model === "string") session.info.model = model;
+	session.info.group = nextGroup;
+	session.info.lastActivity = Date.now();
+	if (nextGroup !== previousGroup) {
+		broadcastToGroup(sessions, write, { type: "session_left", sessionId }, previousGroup, sessionId);
+		broadcastToGroup(sessions, write, { type: "session_joined", session: session.info }, nextGroup, sessionId);
+	} else {
+		broadcastToGroup(sessions, write, { type: "presence_update", session: session.info }, nextGroup, sessionId);
+	}
+	if (requestId !== undefined) {
+		write(socket, { type: "presence_ack", requestId, group: nextGroup });
+	}
+}