@bastani/atomic 0.9.16-alpha.8 → 0.9.16

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

@@ -3,12 +3,14 @@ import net from "net";
 import { randomUUID } from "crypto";
 import { writeMessage, createMessageReader } from "./framing.js";
 import { getBrokerSocketPath } from "./paths.js";
-import type { SessionInfo, Message, Attachment, SupervisorRegistration } from "../types.js";
+import type { SessionInfo, Message, Attachment, GroupSummary, SupervisorRegistration } from "../types.js";
 import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry.js";
 import { readSubagentMessageSource } from "../source-ownership.js";
 import { isMessage, isSessionInfo } from "./client-message-validation.js";
+import { normalizeGroups } from "../group.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
+const GROUP_REQUEST_TIMEOUT_MS = 5000;
 const PRESENCE_ACK_TIMEOUT_MS = 5000;
 
 
@@ -58,6 +60,7 @@ export interface PresenceUpdates {
   name?: string;
   status?: string;
   model?: string;
+  groups?: string[];
   group?: string;
 }
 
@@ -79,8 +82,15 @@ export class IntercomClient extends EventEmitter {
   /** Source identity is captured once at connect, never read from env per message. */
   private _messageSource: Message["source"] | undefined;
   private pendingSends = new PendingSendRegistry();
+  private pendingGroupLists = new Map<string, { resolve: (groups: GroupSummary[]) => void; reject: (error: Error) => void }>();
   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 pendingPresence = new Map<string, {
+    resolve: (group: string) => void;
+    reject: (error: Error) => void;
+    groups?: string[];
+  }>();
+  private pendingMemberships = new Map<string, { resolve: (groups: string[]) => void; reject: (error: Error) => void }>();
+  private _groups = normalizeGroups();
   private pendingLiveWorkflowStageRoutes = new Map<string, { resolve(): void; reject(error: Error): void }>();
 
   private pendingSupervisorAuthorizations = new Map<string, {
@@ -98,13 +108,17 @@ export class IntercomClient extends EventEmitter {
 
   private failPending(error: Error): void {
     this.pendingSends.rejectAll(error);
+    for (const pending of this.pendingGroupLists.values()) pending.reject(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);
+    for (const pending of this.pendingMemberships.values()) pending.reject(error);
     for (const pending of this.pendingLiveWorkflowStageRoutes.values()) pending.reject(error);
     this.pendingLists.clear();
+    this.pendingGroupLists.clear();
     this.pendingSupervisorAuthorizations.clear();
     this.pendingPresence.clear();
+    this.pendingMemberships.clear();
     this.pendingLiveWorkflowStageRoutes.clear();
   }
 
@@ -115,6 +129,10 @@ export class IntercomClient extends EventEmitter {
   get supervisorSessionId(): string | null {
     return this._supervisorSessionId;
   }
+  get groups(): string[] {
+    return [...this._groups];
+  }
+
 
 
   isConnected(): boolean {
@@ -149,6 +167,7 @@ export class IntercomClient extends EventEmitter {
       return Promise.reject(new Error("Already connected"));
     }
     this._messageSource = messageSource ?? readSubagentMessageSource();
+    this._groups = normalizeGroups(session.groups, session.group);
 
     return new Promise((resolve, reject) => {
       const socket = net.connect(BROKER_SOCKET);
@@ -323,6 +342,27 @@ export class IntercomClient extends EventEmitter {
         pending.resolve(sessions);
         break;
       }
+      case "groups": {
+        const { requestId, groups } = brokerMessage;
+        if (
+          typeof requestId !== "string" ||
+          !Array.isArray(groups) ||
+          !groups.every((summary) =>
+            typeof summary === "object" &&
+            summary !== null &&
+            typeof summary.group === "string" &&
+            typeof summary.sessionCount === "number" &&
+            typeof summary.member === "boolean"
+          )
+        ) {
+          throw new Error("Invalid groups message");
+        }
+        const pending = this.pendingGroupLists.get(requestId);
+        if (!pending) return;
+        this.pendingGroupLists.delete(requestId);
+        pending.resolve(groups as GroupSummary[]);
+        break;
+      }
       case "supervisor_authorized": {
         const { requestId, capability, supervisorSessionId, childName } = brokerMessage;
         if (typeof requestId !== "string" || typeof capability !== "string"
@@ -465,17 +505,39 @@ export class IntercomClient extends EventEmitter {
         const pending = this.pendingPresence.get(brokerMessage.requestId);
         if (!pending) return;
         this.pendingPresence.delete(brokerMessage.requestId);
+        this._groups = pending.groups === undefined
+          ? normalizeGroups(undefined, brokerMessage.group)
+          : normalizeGroups(pending.groups);
         pending.resolve(brokerMessage.group);
         break;
       }
+      case "membership_ack": {
+        const { requestId, groups } = brokerMessage;
+        if (typeof requestId !== "string" || !Array.isArray(groups) || !groups.every((group) => typeof group === "string")) {
+          throw new Error("Invalid membership_ack message");
+        }
+        const pending = this.pendingMemberships.get(requestId);
+        if (!pending) return;
+        this.pendingMemberships.delete(requestId);
+        const normalizedGroups = [...normalizeGroups(groups)];
+        this._groups = new Set(normalizedGroups);
+        pending.resolve(normalizedGroups);
+        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));
+        const presence = this.pendingPresence.get(brokerMessage.requestId);
+        if (presence) {
+          this.pendingPresence.delete(brokerMessage.requestId);
+          presence.reject(new Error(brokerMessage.reason));
+          break;
+        }
+        const membership = this.pendingMemberships.get(brokerMessage.requestId);
+        if (!membership) return;
+        this.pendingMemberships.delete(brokerMessage.requestId);
+        membership.reject(new Error(brokerMessage.reason));
         break;
       }
       case "peer_disconnected": {
@@ -573,6 +635,69 @@ export class IntercomClient extends EventEmitter {
       }
     });
   }
+  listGroups(): Promise<GroupSummary[]> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    const requestId = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        if (!this.pendingGroupLists.delete(requestId)) return;
+        reject(new Error("List groups timeout"));
+      }, GROUP_REQUEST_TIMEOUT_MS);
+      this.pendingGroupLists.set(requestId, {
+        resolve: (groups) => { clearTimeout(timeout); resolve(groups); },
+        reject: (error) => { clearTimeout(timeout); reject(error); },
+      });
+      try {
+        writeMessage(socket, { type: "list_groups", requestId });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingGroupLists.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
+
+  joinGroup(group: string): Promise<string[]> {
+    return this.updateMembership("join_group", group);
+  }
+
+  leaveGroup(group?: string): Promise<string[]> {
+    return this.updateMembership("leave_group", group);
+  }
+
+  private updateMembership(type: "join_group" | "leave_group", group?: string): 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 timeout = setTimeout(() => {
+        if (!this.pendingMemberships.delete(requestId)) return;
+        reject(new Error("Membership update timeout"));
+      }, GROUP_REQUEST_TIMEOUT_MS);
+      this.pendingMemberships.set(requestId, {
+        resolve: (groups) => { clearTimeout(timeout); resolve(groups); },
+        reject: (error) => { clearTimeout(timeout); reject(error); },
+      });
+      try {
+        writeMessage(socket, group === undefined ? { type, requestId } : { type, requestId, group });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingMemberships.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
+
+
   authorizeSupervisorChild(childName: string, capability?: string): Promise<SupervisorAuthorization> {
     let socket: net.Socket;
     try {
@@ -728,6 +853,8 @@ export class IntercomClient extends EventEmitter {
       return false;
     }
     writeMessage(socket, { type: "presence", ...updates });
+    if (updates.groups !== undefined) this._groups = normalizeGroups(updates.groups, updates.group);
+    else if (updates.group !== undefined) this._groups = normalizeGroups(undefined, updates.group);
     return true;
   }
 
@@ -752,7 +879,11 @@ export class IntercomClient extends EventEmitter {
         if (!this.pendingPresence.delete(requestId)) return;
         reject(new Error("Presence update timeout"));
       }, PRESENCE_ACK_TIMEOUT_MS);
-      this.pendingPresence.set(requestId, { resolve: wrappedResolve, reject: wrappedReject });
+      this.pendingPresence.set(requestId, {
+        resolve: wrappedResolve,
+        reject: wrappedReject,
+        ...(updates.groups === undefined ? {} : { groups: [...updates.groups] }),
+      });
       try {
         writeMessage(socket, { type: "presence", ...updates, requestId });
       } catch (error) {

package/dist/builtin/intercom/broker/group-isolation.ts

@@ -1,10 +1,10 @@
 import type { SessionInfo } from "../types.js";
-import { normalizeGroup } from "../group.js";
 import type { SupervisorChannelCache } from "./supervisor-channel.js";
+import { sessionsShareGroup } from "./group-membership.js";
 
-/** Two sessions share a group when their normalized group ids are equal. */
+/** Two sessions share a group when any normalized membership intersects. */
 export function sameGroup(a: SessionInfo, b: SessionInfo): boolean {
-  return normalizeGroup(a.group) === normalizeGroup(b.group);
+	return sessionsShareGroup(a, b);
 }
 
 export interface VerticalBypassInput {

package/dist/builtin/intercom/broker/group-membership.ts

@@ -0,0 +1,55 @@
+import { hasGroup, normalizeGroup, normalizeGroups } from "../group.js";
+import type { GroupSummary, SessionInfo } from "../types.js";
+import type { BrokerConnectedSession } from "./send-handler.js";
+
+/** Return the normalized memberships carried by a wire session. */
+export function sessionGroups(session: SessionInfo): Set<string> {
+	return normalizeGroups(session.groups, session.group);
+}
+
+/** Persist normalized memberships while retaining the legacy single-group field. */
+export function setSessionGroups(session: SessionInfo, groups: ReadonlySet<string>, legacyGroup?: string): void {
+	const normalized = normalizeGroups(groups);
+	session.groups = [...normalized];
+	const firstGroup = normalized.values().next().value ?? normalizeGroup();
+	session.group = legacyGroup !== undefined && normalized.has(normalizeGroup(legacyGroup))
+		? normalizeGroup(legacyGroup)
+		: firstGroup;
+}
+
+/** Sessions can route to each other when any normalized membership intersects. */
+export function sessionsShareGroup(a: SessionInfo, b: SessionInfo): boolean {
+	const bGroups = sessionGroups(b);
+	return [...sessionGroups(a)].some((group) => bGroups.has(group));
+}
+
+/** Return each session visible through at least one of the requester's memberships. */
+export function sessionsVisibleTo(
+	sessions: ReadonlyMap<string, BrokerConnectedSession>,
+	requester: SessionInfo,
+): SessionInfo[] {
+	return [...sessions.values()].map(({ info }) => info).filter((info) => sessionsShareGroup(requester, info));
+}
+
+/** Return sessions that belong to one explicit group. */
+export function sessionsInGroup(
+	sessions: ReadonlyMap<string, BrokerConnectedSession>,
+	group: string | undefined,
+): SessionInfo[] {
+	return [...sessions.values()].map(({ info }) => info).filter((info) => hasGroup(sessionGroups(info), group));
+}
+
+/** Summarize every group currently represented by a connected session. */
+export function knownGroupSummaries(
+	sessions: ReadonlyMap<string, BrokerConnectedSession>,
+	requester: SessionInfo,
+): GroupSummary[] {
+	const counts = new Map<string, number>();
+	for (const { info } of sessions.values()) {
+		for (const group of sessionGroups(info)) counts.set(group, (counts.get(group) ?? 0) + 1);
+	}
+	const requesterGroups = sessionGroups(requester);
+	return [...counts]
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([group, sessionCount]) => ({ group, sessionCount, member: requesterGroups.has(group) }));
+}

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

@@ -1,6 +1,7 @@
 import type net from "node:net";
+import { addGroup, normalizeGroups, removeGroup, validateRuntimeGroup } from "../group.js";
 import type { BrokerMessage } from "../types.js";
-import { normalizeGroup, validateRuntimeGroup } from "../group.js";
+import { sessionGroups, sessionsShareGroup, setSessionGroups } from "./group-membership.js";
 import type { BrokerConnectedSession } from "./send-handler.js";
 
 interface PresenceClientMessage extends Record<string, unknown> {
@@ -9,22 +10,28 @@ interface PresenceClientMessage extends Record<string, unknown> {
 
 type WriteMessage = (socket: net.Socket, message: BrokerMessage) => void;
 
-function broadcastToGroup(
+function broadcastMembershipChange(
 	sessions: Map<string, BrokerConnectedSession>,
 	write: WriteMessage,
-	message: BrokerMessage,
-	group: string | undefined,
-	exclude?: string,
+	session: BrokerConnectedSession,
+	previous: ReadonlySet<string>,
 ): void {
-	const target = normalizeGroup(group);
-	for (const [id, session] of sessions) {
-		if (id !== exclude && normalizeGroup(session.info.group) === target) {
-			write(session.socket, message);
+	const previousInfo = { ...session.info, groups: [...previous], group: previous.values().next().value };
+	for (const [id, peer] of sessions) {
+		if (id === session.info.id) continue;
+		const sharedBefore = sessionsShareGroup(previousInfo, peer.info);
+		const sharedAfter = sessionsShareGroup(session.info, peer.info);
+		if (!sharedBefore && sharedAfter) {
+			write(peer.socket, { type: "session_joined", session: session.info });
+		} else if (sharedBefore && !sharedAfter) {
+			write(peer.socket, { type: "session_left", sessionId: session.info.id });
+		} else if (sharedAfter) {
+			write(peer.socket, { type: "presence_update", session: session.info });
 		}
 	}
 }
 
-/** Apply one presence update and notify only the affected group members. */
+/** Apply one presence or membership update and notify every affected group member. */
 export function handleBrokerPresence(
 	socket: net.Socket,
 	clientMessage: PresenceClientMessage,
@@ -37,67 +44,72 @@ export function handleBrokerPresence(
 		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);
+	const session = currentId === null ? undefined : sessions.get(currentId);
 	if (!session) {
-		if (requestId !== undefined) {
-			write(socket, { type: "presence_failed", requestId, reason: "Session not found" });
-		}
+		if (requestId !== undefined) write(socket, { type: "presence_failed", requestId, reason: "Session not found" });
 		return;
 	}
 
-	const fail = (reason: string): boolean => {
+	const fail = (reason: string): true => {
 		if (requestId === undefined) throw new Error(reason);
 		write(socket, { type: "presence_failed", requestId, reason });
 		return true;
 	};
+	const previousGroups = sessionGroups(session.info);
+	let nextGroups = new Set(previousGroups);
+	let legacyGroup = session.info.group;
 
-	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;
+	try {
+		if (clientMessage.type === "join_group") {
+			nextGroups = addGroup(previousGroups, clientMessage.group);
+		} else if (clientMessage.type === "leave_group") {
+			if (clientMessage.group === undefined) {
+				nextGroups = normalizeGroups(undefined, session.registrationGroup);
+				legacyGroup = session.registrationGroup;
+			} else {
+				if (typeof clientMessage.group !== "string") return void fail("Invalid presence group");
+				const group = validateRuntimeGroup(clientMessage.group);
+				nextGroups = removeGroup(previousGroups, group);
+				if (legacyGroup === group) legacyGroup = undefined;
+			}
 		} else {
-			try {
-				nextGroup = validateRuntimeGroup(rawGroup);
-			} catch (error) {
-				const reason = error instanceof Error ? error.message : String(error);
-				if (fail(`Invalid presence group: ${reason}`)) return;
+			const rawGroups = clientMessage.groups;
+			if (rawGroups !== undefined) {
+				if (!Array.isArray(rawGroups) || !rawGroups.every((group) => typeof group === "string")) {
+					return void fail("Invalid presence groups");
+				}
+				nextGroups = normalizeGroups(rawGroups.map(validateRuntimeGroup));
+				legacyGroup = nextGroups.values().next().value;
+			} else if (clientMessage.group !== undefined) {
+				if (typeof clientMessage.group !== "string") return void fail("Invalid presence group");
+				legacyGroup = validateRuntimeGroup(clientMessage.group);
+				nextGroups = new Set([legacyGroup]);
 			}
 		}
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return void fail(`Invalid presence group: ${reason}`);
 	}
+
 	const name = clientMessage.name;
-	if (name !== undefined && typeof name !== "string") {
-		if (fail("Invalid presence name")) return;
-	}
+	if (name !== undefined && typeof name !== "string") return void fail("Invalid presence name");
 	const status = clientMessage.status;
-	if (status !== undefined && typeof status !== "string") {
-		if (fail("Invalid presence status")) return;
-	}
+	if (status !== undefined && typeof status !== "string") return void fail("Invalid presence status");
 	const model = clientMessage.model;
-	if (model !== undefined && typeof model !== "string") {
-		if (fail("Invalid presence model")) return;
-	}
+	if (model !== undefined && typeof model !== "string") return void fail("Invalid presence model");
 
 	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;
+	setSessionGroups(session.info, nextGroups, legacyGroup);
 	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);
-	}
+	broadcastMembershipChange(sessions, write, session, previousGroups);
+
 	if (requestId !== undefined) {
-		write(socket, { type: "presence_ack", requestId, group: nextGroup });
+		if (clientMessage.type === "join_group" || clientMessage.type === "leave_group") {
+			write(socket, { type: "membership_ack", requestId, groups: session.info.groups ?? [] });
+		} else {
+			write(socket, { type: "presence_ack", requestId, group: session.info.group ?? "default" });
+		}
 	}
 }

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

@@ -6,7 +6,7 @@ import { DeliveredMessageCache } from "./delivered-message-cache.js";
 import { buildMessageSendSignature } from "./send-signature.js";
 import { SupervisorChannelCache } from "./supervisor-channel.js";
 import { isVerticalBypass, sameGroup } from "./group-isolation.js";
-import { normalizeGroup } from "../group.js";
+import { sessionsShareGroup } from "./group-membership.js";
 import { PendingQuestionIndex } from "./pending-question-index.js";
 
 export interface BrokerConnectedSession {
@@ -139,12 +139,11 @@ export function handleBrokerSend(
   // supervisor frame or an exact recorded reply may resolve across groups.
 	const liveWorkflowTarget = sessions.has(trimmedTo) ? undefined : resolveLiveWorkflowStage?.(trimmedTo);
 	const exactIdTarget = sessions.get(trimmedTo) ?? liveWorkflowTarget;
-  const senderGroup = normalizeGroup(fromSession.info.group);
   const reachableAcrossGroups = supervisorSend || Boolean(message.replyTo);
   const candidates = reachableAcrossGroups
     ? Array.from(sessions.values(), (session) => session.info)
     : Array.from(sessions.values(), (session) => session.info).filter(
-        (info) => normalizeGroup(info.group) === senderGroup,
+        (info) => sessionsShareGroup(info, fromSession.info),
       );
   const resolution = exactIdTarget
     ? ({ kind: "resolved", session: exactIdTarget.info } as const)

package/dist/builtin/intercom/group.ts

@@ -20,6 +20,11 @@ export const DEFAULT_GROUP = "default";
 
 const RESERVED_RUNTIME_GROUPS = new Set(["true", "auto"]);
 
+/** Runtime representation of a session's normalized group memberships. */
+export type GroupMemberships = ReadonlySet<string>;
+
+type GroupMembershipInput = readonly (string | null | undefined)[] | ReadonlySet<string | null | undefined>;
+
 /**
  * Normalize an intercom group id. Undefined, empty, or whitespace-only values
  * collapse to the shared {@link DEFAULT_GROUP} so ungrouped sessions all compare
@@ -31,6 +36,22 @@ export function normalizeGroup(value?: string | null): string {
 	return trimmed.length > 0 ? trimmed : DEFAULT_GROUP;
 }
 
+/**
+ * Normalize serialized group memberships into a non-empty set. Duplicate names
+ * collapse, and an absent or empty collection retains legacy default membership.
+ * A legacy `group` value is merged so single-group clients remain authoritative.
+ */
+export function normalizeGroups(
+	values?: GroupMembershipInput | null,
+	legacyGroup?: string | null,
+): Set<string> {
+	const groups = new Set<string>();
+	for (const value of values ?? []) groups.add(normalizeGroup(value));
+	if (legacyGroup !== undefined) groups.add(normalizeGroup(legacyGroup));
+	if (groups.size === 0) groups.add(DEFAULT_GROUP);
+	return groups;
+}
+
 /**
  * Validate a group requested by the runtime join action. `default` is a real,
  * explicit group name; `true` and `auto` remain reserved for subagent auto-grouping.
@@ -46,6 +67,25 @@ export function validateRuntimeGroup(value: unknown): string {
 	return group;
 }
 
+/** Add one validated runtime group to a normalized membership set. */
+export function addGroup(groups: GroupMemberships, value: unknown): Set<string> {
+	const next = normalizeGroups(groups);
+	next.add(validateRuntimeGroup(value));
+	return next;
+}
+
+/** Remove one normalized group while retaining default membership when none remain. */
+export function removeGroup(groups: GroupMemberships, value?: string | null): Set<string> {
+	const next = normalizeGroups(groups);
+	next.delete(normalizeGroup(value));
+	return normalizeGroups(next);
+}
+
+/** Test a normalized group membership. */
+export function hasGroup(groups: GroupMemberships, value?: string | null): boolean {
+	return normalizeGroups(groups).has(normalizeGroup(value));
+}
+
 interface HomeGroupContext {
 	orchestrationContext?: { intercomGroup?: string } | undefined;
 	subagentPolicy?: { intercomGroup?: string } | undefined;