@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/intercom/index-heavy.ts

@@ -14,10 +14,22 @@ import { registerIntercomLifecycle } from "./lifecycle.js";
 import { registerSubagentRelay } from "./subagent-relay.js";
 import { ForegroundDetachHandoff, handleForegroundInboundDelivery } from "./foreground-detach-handoff.js";
 import { routeIncomingReply } from "./reply-routing.js";
-import { INBOUND_FLUSH_DELAY_MS, INBOUND_IDLE_RETRY_MS, type InboundMessageEntry, buildPresenceIdentity, formatAttachments, readChildOrchestratorMetadata, toError } from "./intercom-utils.js";
+import { INBOUND_FLUSH_DELAY_MS, INBOUND_IDLE_RETRY_MS, buildPresenceIdentity, formatAttachments, readChildOrchestratorMetadata, toError } from "./intercom-utils.js";
+import { buildIncomingCustomMessage, createIncomingMessageSender } from "./incoming-message-delivery.js";
 import { InboundIdleQueue } from "./inbound-idle-queue.js";
 import { registerTerminalOrderingBarrier } from "./terminal-ordering-barrier.js";
 import { resolveSessionTargetId } from "./session-target.js";
+import { InboundMessageAdmission } from "./inbound-message-admission.js";
+import { registerLateStageMessageRouter } from "./late-stage-message-router.js";
+import { retryStableDelivery } from "./stable-delivery-retry.js";
+import type { IntercomExtensionTestOverrides } from "./intercom-test-seams.js";
+import { admitWorkflowStageInbound } from "./workflow-stage-admission.js";
+import { bindWorkflowReplyTracker, preserveWorkflowReplyTracker } from "./workflow-reply-tracker.js";
+import { routeClosedWorkflowStageMessage } from "./closed-workflow-stage-message.js";
+import { createWorkflowStageDeliveryFailureHandler } from "./workflow-stage-delivery-failure.js";
+import { resolveHomeGroup } from "./group.js";
+import { reconnectDelayMs } from "./reconnect-backoff.js";
+import { SupervisorAuthorizationRegistry } from "./supervisor-authorization-registry.js";
 if (process.env.ATOMIC_TEST_LAZY_IMPORT_SENTINEL === "1") {
   process.env.ATOMIC_INTERCOM_HEAVY_IMPORTED = "1";
 }
@@ -26,7 +38,7 @@ if (process.env.ATOMIC_TEST_LAZY_IMPORT_SENTINEL_FILE) {
 }
 
 const INTERCOM_SESSION_ID_ENV = `${APP_NAME.toUpperCase()}_INTERCOM_SESSION_ID`;
-export default function piIntercomExtension(pi: ExtensionAPI) {
+export default function piIntercomExtension(pi: ExtensionAPI, testOverrides: IntercomExtensionTestOverrides = {}) {
   const inheritedIntercomSessionId = process.env[INTERCOM_SESSION_ID_ENV];
   const restoreIntercomSessionIdEnv = (): void => {
     if (inheritedIntercomSessionId === undefined) delete process.env[INTERCOM_SESSION_ID_ENV];
@@ -34,6 +46,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   };
   let client: IntercomClient | null = null;
   const config: IntercomConfig = loadConfig();
+  const childOrchestratorMetadata = readChildOrchestratorMetadata();
   let runtimeContext: ExtensionContext | null = null;
   let currentSessionId: string | null = null;
   let currentModel = "unknown";
@@ -48,22 +61,16 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   let runtimeGeneration = 0;
   let agentRunning = false;
   const activeTools = new Map<string, string>();
-  const replyTracker = new ReplyTracker();
+  let replyTracker = new ReplyTracker();
   const replyWaiters = new ReplyWaiterSlot();
   const foregroundDetachHandoff = new ForegroundDetachHandoff(pi);
   const pendingIdleMessages = new InboundIdleQueue();
+  const inboundDeliveries = new InboundMessageAdmission();
+  const supervisorAuthorizations = new SupervisorAuthorizationRegistry();
   let inboundFlushTimer: NodeJS.Timeout | null = null;
-  function rejectReplyWaiter(error: Error): void {
-    replyWaiters.rejectCurrent(error);
-  }
-  function clearReconnectTimer(): void {
-    if (reconnectTimer) clearTimeout(reconnectTimer);
-    reconnectTimer = null;
-  }
-  function clearInboundFlushTimer(): void {
-    if (inboundFlushTimer) clearTimeout(inboundFlushTimer);
-    inboundFlushTimer = null;
-  }
+  function rejectReplyWaiter(error: Error): void { replyWaiters.rejectCurrent(error); }
+  function clearReconnectTimer(): void { if (reconnectTimer) clearTimeout(reconnectTimer); reconnectTimer = null; }
+  function clearInboundFlushTimer(): void { if (inboundFlushTimer) clearTimeout(inboundFlushTimer); inboundFlushTimer = null; }
   function getLiveContext(ctx: ExtensionContext | null = runtimeContext, generation = runtimeGeneration): ExtensionContext | null {
     if (disposed || shuttingDown || generation !== runtimeGeneration || !ctx) {
       return null;
@@ -90,10 +97,6 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       // The UI can disappear during session shutdown/reload while async overlay work is settling.
     }
   }
-  function getReconnectDelayMs(): number {
-    const backoffMs = [1000, 2000, 5000, 10000, 30000];
-    return backoffMs[Math.min(reconnectAttempt, backoffMs.length - 1)]!;
-  }
   function currentStatus(): string {
     const activeToolName = activeTools.values().next().value;
     const lifecycleStatus = activeToolName ? `tool:${activeToolName}` : agentRunning ? "thinking" : "idle";
@@ -113,6 +116,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       startedAt: sessionStartedAt,
       lastActivity: Date.now(),
       status: currentStatus(),
+      group: resolveHomeGroup(config, getLiveContext()),
     };
   }
   function syncPresenceIdentity(sessionId: string): void {
@@ -140,29 +144,14 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     return Boolean(resolvedTo && activeClient?.sessionId && resolvedTo === activeClient.sessionId)
       || targets.has(to.trim().toLowerCase());
   }
-  function buildIncomingCustomMessage(entry: InboundMessageEntry) {
-    const senderDisplay = entry.from.name || entry.from.id.slice(0, 8);
-    const replyInstruction = entry.replyCommand ? `\n\nTo reply, use the intercom tool: ${entry.replyCommand}` : "";
-    return {
-      customType: "intercom_message" as const,
-      content: `**📨 From ${senderDisplay}** (${entry.from.cwd})${replyInstruction}\n\n${entry.bodyText}`,
-      display: true as const,
-      details: entry,
-    };
-  }
-  function sendIncomingMessage(entry: InboundMessageEntry, delivery: "trigger" | "followUp" | "prelude", generation = runtimeGeneration): void {
-    if (runtimeStarted && !getLiveContext(runtimeContext, generation)) {
-      return;
-    }
-    if (delivery === "trigger") {
-      replyTracker.queueTurnContext({ from: entry.from, message: entry.message, receivedAt: Date.now() });
-    }
-    const options = delivery === "trigger"
-      ? { triggerTurn: true } as const
-      : delivery === "followUp" ? { deliverAs: "followUp" } as const : undefined;
-    pi.sendMessage(buildIncomingCustomMessage(entry), options);
-  }
-  registerTerminalOrderingBarrier(pi, {
+  registerLateStageMessageRouter(pi, inboundDeliveries, () => replyTracker, () => resolveHomeGroup(config, getLiveContext()));
+  const sendIncomingMessage = createIncomingMessageSender({
+    pi,
+    currentGeneration: () => runtimeGeneration,
+    canDeliver: (generation) => !runtimeStarted || Boolean(getLiveContext(runtimeContext, generation)),
+    queueTurnContext: (context) => replyTracker.queueTurnContext(context),
+  });
+  const unregisterTerminalOrderingBarrier = registerTerminalOrderingBarrier(pi, {
     queue: pendingIdleMessages,
     toMessage: buildIncomingCustomMessage,
     // A prelude is admitted synchronously when idle, or FIFO-queued when busy.
@@ -172,7 +161,9 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     onDrain: () => {
       if (pendingIdleMessages.size === 0) clearInboundFlushTimer();
     },
+    isCurrent: () => Boolean(getLiveContext()),
   });
+  pi.on("session_shutdown", () => { unregisterTerminalOrderingBarrier(); });
   function scheduleInboundFlush(delayMs = INBOUND_FLUSH_DELAY_MS): void {
     if (!getLiveContext()) {
       return;
@@ -208,16 +199,19 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     const first = entries[0];
     if (first) replyTracker.queueTurnContext({ from: first.from, message: first.message, receivedAt: Date.now() });
     const messages = entries.map(buildIncomingCustomMessage);
-    if (typeof pi.sendMessages === "function") pi.sendMessages(messages, { triggerTurn: true });
-    else messages.forEach((message, index) => pi.sendMessage(message, index === 0 ? { triggerTurn: true } : { deliverAs: "followUp" }));
+    void retryStableDelivery({
+      deliver: () => typeof pi.sendMessages === "function" ? Promise.resolve(pi.sendMessages(messages, { triggerTurn: true })) : Promise.all(messages.map((message, index) => pi.sendMessage(message, index === 0 ? { triggerTurn: true } : { deliverAs: "followUp" }))).then(() => {}),
+      isCurrent: () => Boolean(getLiveContext(ctx, generation)),
+    }).catch(() => {});
   }
-  function handleIncomingMessage(ctx: ExtensionContext, from: SessionInfo, message: Message): void {
+  testOverrides.captureInboundHandler?.(handleIncomingMessage);
+  function handleIncomingMessage(ctx: ExtensionContext, from: SessionInfo, message: Message, channel?: "supervisor"): void {
     const messageGeneration = runtimeGeneration;
     const liveContext = getLiveContext(ctx, messageGeneration);
     if (!liveContext) {
       return;
     }
-    if (routeIncomingReply(replyWaiters.current(), from, message)) return;
+    replyTracker = bindWorkflowReplyTracker(liveContext, replyTracker);
     const attachmentText = message.content.attachments?.length
       ? formatAttachments(message.content.attachments)
       : "";
@@ -225,64 +219,118 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     const replyCommand = config.replyHint && message.expectsReply
       ? `intercom({ action: "reply", message: "..." })`
       : undefined;
-    replyTracker.recordIncomingMessage(from, message);
-    const entry = { from, message, replyCommand, bodyText };
+    const entry = { from, message, replyCommand, bodyText, ...(channel ? { channel } : {}) };
+    const stageClosed = liveContext.orchestrationContext?.kind === "workflow-stage"
+      && liveContext.orchestrationContext.messageAdmission?.isOpen() === false;
+    if (stageClosed) {
+      routeClosedWorkflowStageMessage(
+        entry, inboundDeliveries, replyTracker, replyWaiters.current(),
+        () => sendIncomingMessage(entry, "trigger", messageGeneration, false),
+        () => client,
+        () => Boolean(getLiveContext(liveContext, messageGeneration)),
+      );
+      return;
+    }
+    const admission = inboundDeliveries.admit(from, message);
+    if (admission.kind !== "reserved") return;
+    const reservation = admission.reservation;
+    if (routeIncomingReply(replyWaiters.current(), from, message)) {
+      inboundDeliveries.commit(reservation);
+      return;
+    }
+    const replyContext = replyTracker.recordIncomingMessage(from, message);
+    const commit = (): void => { inboundDeliveries.commit(reservation); };
+    const release = createWorkflowStageDeliveryFailureHandler({
+      entry,
+      admission: inboundDeliveries,
+      reservation,
+      tracker: replyTracker,
+      replyContext,
+      currentClient: () => client,
+      commit,
+    });
+    const stageDelivery = admitWorkflowStageInbound(
+      liveContext,
+      (admissionBarrier) => {
+        replyTracker.queueTurnContext(replyContext);
+        return retryStableDelivery({
+          deliver: () => sendIncomingMessage(entry, "trigger", messageGeneration, false, undefined, admissionBarrier),
+          isCurrent: () => Boolean(getLiveContext(liveContext, messageGeneration)),
+        });
+      },
+      () => foregroundDetachHandoff.claim(from, message, messageGeneration, () => Boolean(getLiveContext(liveContext, messageGeneration))),
+      release,
+    );
+    if (stageDelivery !== false) {
+      void stageDelivery.then(commit, release);
+      return;
+    }
     void (async () => {
-      const activeContext = getLiveContext(liveContext, messageGeneration);
-      if (!activeContext) {
-        return;
-      }
-      if (!activeContext.isIdle()) {
-        if (!activeContext.hasUI) {
-          const activeClient = client;
-          if (!message.replyTo && activeClient?.isConnected()) {
-            try {
-              const result = await activeClient.send(from.id, {
-                text: "This agent is running in non-interactive mode and cannot respond to intercom messages while it is working. It will continue its current task and exit when done.",
-                replyTo: message.id,
-              });
-              if (result.delivered && getLiveContext(liveContext, messageGeneration)) {
-                replyTracker.markReplied(message.id);
+      try {
+        const activeContext = getLiveContext(liveContext, messageGeneration);
+        if (!activeContext) {
+          release(new Error("Intercom session retired before inbound delivery"));
+          return;
+        }
+        if (!activeContext.isIdle()) {
+          if (!activeContext.hasUI) {
+            const activeClient = client;
+            if (!message.replyTo && activeClient?.isConnected()) {
+              try {
+                const result = await activeClient.send(from.id, {
+                  text: "This agent is running in non-interactive mode and cannot respond to intercom messages while it is working. It will continue its current task and exit when done.",
+                  replyTo: message.id,
+                });
+                if (result.delivered && getLiveContext(liveContext, messageGeneration)) {
+                  replyTracker.markReplied(message.id);
+                }
+              } catch {
+                // Best-effort reply; keep the busy non-interactive session running either way.
               }
-            } catch {
-              // Best-effort reply; keep the busy non-interactive session running either way.
             }
+            commit();
+            return;
           }
+          // Establish queue ownership before probing asynchronously. If a terminal
+          // barrier wins the race, the later foreground callback cannot redeliver.
+          pendingIdleMessages.enqueue(entry);
+          commit();
+          await handleForegroundInboundDelivery({
+            handoff: foregroundDetachHandoff,
+            from,
+            message,
+            generation: messageGeneration,
+            surface: () => {
+              if (pendingIdleMessages.remove(entry)) {
+                replyTracker.queueTurnContext(replyContext);
+                void retryStableDelivery({ deliver: () => sendIncomingMessage(entry, "trigger", messageGeneration, false), isCurrent: () => Boolean(getLiveContext(liveContext, messageGeneration)) }).catch(() => {});
+              }
+            },
+            isCurrent: () => Boolean(getLiveContext(liveContext, messageGeneration)),
+            onUnclaimed: () => {
+              // No exact foreground owner acknowledged the target. Preserve the
+              // established background/cross-session behavior by waiting for idle.
+              if (pendingIdleMessages.has(entry)) scheduleInboundFlush(INBOUND_IDLE_RETRY_MS);
+            },
+            onDelivered: () => { pendingIdleMessages.remove(entry); },
+          });
           return;
         }
-        // Establish queue ownership before probing asynchronously. If a terminal
-        // barrier wins the race, the later foreground callback cannot redeliver.
-        pendingIdleMessages.enqueue(entry);
-        await handleForegroundInboundDelivery({
-          handoff: foregroundDetachHandoff,
-          from,
-          message,
-          generation: messageGeneration,
-          surface: () => {
-            if (pendingIdleMessages.remove(entry)) sendIncomingMessage(entry, "trigger", messageGeneration);
-          },
-          isCurrent: () => Boolean(getLiveContext(liveContext, messageGeneration)),
-          onUnclaimed: () => {
-            // No exact foreground owner acknowledged the target. Preserve the
-            // established background/cross-session behavior by waiting for idle.
-            if (pendingIdleMessages.has(entry)) scheduleInboundFlush(INBOUND_IDLE_RETRY_MS);
-          },
-          onDelivered: () => { pendingIdleMessages.remove(entry); },
-        });
-        return;
-      }
-      if (getLiveContext(liveContext, messageGeneration)) {
-        sendIncomingMessage(entry, "trigger", messageGeneration);
+        replyTracker.queueTurnContext(replyContext);
+        await retryStableDelivery({ deliver: () => sendIncomingMessage(entry, "trigger", messageGeneration, false), isCurrent: () => Boolean(getLiveContext(liveContext, messageGeneration)) });
+        commit();
+      } catch (error) {
+        release(error);
       }
     })();
   }
   function attachClientHandlers(nextClient: IntercomClient): void {
-    nextClient.on("message", (from, message) => {
+    nextClient.on("message", (from: SessionInfo, message: Message, channel?: "supervisor") => {
       const liveContext = getLiveContext();
       if (client !== nextClient || !liveContext) {
         return;
       }
-      handleIncomingMessage(liveContext, from, message);
+      handleIncomingMessage(liveContext, from, message, channel);
     });
     nextClient.on("disconnected", (error: Error) => {
       if (client !== nextClient) {
@@ -314,7 +362,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       void ensureConnected("background").catch(() => {
         // ensureConnected("background") already queued the next retry.
       });
-    }, getReconnectDelayMs());
+    }, reconnectDelayMs(reconnectAttempt));
   }
   async function ensureConnected(reason: "startup" | "background" | "tool" | "overlay"): Promise<IntercomClient> {
     if (!config.enabled) {
@@ -341,7 +389,10 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       attachClientHandlers(nextClient);
       try {
         await spawnBrokerIfNeeded(config.brokerCommand, config.brokerArgs);
-        await nextClient.connect(buildRegistration());
+        await nextClient.connect(
+          buildRegistration(), childOrchestratorMetadata?.supervisor, supervisorAuthorizations.ownerToken,
+        );
+        await supervisorAuthorizations.restore(nextClient);
         if (!getLiveContext(contextAtStart, generationAtStart)) {
           await nextClient.disconnect();
           throw new Error("Intercom runtime no longer active");
@@ -377,7 +428,9 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     currentSessionTargetMatches,
     sendIncomingMessage,
     ensureConnected,
+    authorizeSupervisorChild: (childName) => supervisorAuthorizations.authorize(childName, () => ensureConnected("background")),
     resolveSessionTarget: resolveSessionTargetId,
+    homeGroup: () => resolveHomeGroup(config, getLiveContext()),
   });
 
   registerIntercomLifecycle(pi, {
@@ -398,7 +451,9 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     activeTools,
     getLiveContext,
     rejectReplyWaiter,
-    replyTracker,
+    replyTracker: () => replyTracker,
+    bindReplyTracker: (ctx) => { replyTracker = bindWorkflowReplyTracker(ctx, replyTracker); },
+    preserveReplyTrackerOnCleanup: () => preserveWorkflowReplyTracker(runtimeContext),
     pendingIdleMessages,
     clearInboundFlushTimer,
     scheduleInboundFlush,
@@ -414,7 +469,6 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     return new InlineMessageComponent(details.from, details.message, theme, details.replyCommand, details.bodyText);
   });
 
-  const childOrchestratorMetadata = readChildOrchestratorMetadata();
   registerContactSupervisorTool(pi, {
     childOrchestratorMetadata,
     ensureConnected,
@@ -428,7 +482,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     syncPresenceIdentity,
     beginReplyWait: (from, replyTo, signal) => replyWaiters.begin(from, replyTo, signal),
     confirmSend: config.confirmSend,
-    replyTracker,
+    replyTracker: () => replyTracker,
     hasReplyWaiter: () => replyWaiters.has(),
   });
   registerIntercomOverlay(pi, {

package/dist/builtin/intercom/index.ts

@@ -36,6 +36,39 @@ interface LightweightIntercomOptions {
 }
 
 const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
+const SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT = "subagent:supervisor-authorization";
+interface SupervisorAuthorizationRequest {
+	childName?: string;
+	completion?: Promise<unknown>;
+}
+
+const WORKFLOW_STAGE_LATE_MESSAGE_EVENT = "atomic:workflow-stage-late-message";
+
+interface WorkflowStageLateMessageEvent {
+	handled?: boolean;
+	completion?: Promise<void>;
+	workflowRunId?: string;
+	workflowStageId?: string;
+	messages?: Array<{
+		customType?: string;
+		content?: string;
+		details?: { message?: { expectsReply?: boolean } };
+	}>;
+}
+
+function isCompletedStageAskRoute(event: WorkflowStageLateMessageEvent): boolean {
+	return typeof event.workflowRunId === "string"
+		&& event.workflowRunId.length > 0
+		&& typeof event.workflowStageId === "string"
+		&& event.workflowStageId.length > 0
+		&& Array.isArray(event.messages)
+		&& event.messages.length > 0
+		&& event.messages.every((message) =>
+			message.customType === "intercom_message"
+			&& typeof message.content === "string"
+			&& message.details?.message?.expectsReply === true,
+		);
+}
 const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
 
 const SUBAGENT_ENV_PREFIX = `${APP_NAME.toUpperCase()}_SUBAGENT_`;
@@ -306,6 +339,18 @@ export default function intercom(pi: ExtensionAPI, options: LightweightIntercomO
 			?? [...activeLifecycle.activeTools.values()].at(-1)?.ctx
 			?? activeLifecycle.modelSelect?.ctx;
 	}
+	pi.events.on(SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT, (payload) => {
+		if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+		const request = payload as SupervisorAuthorizationRequest;
+		if (typeof request.childName !== "string" || !request.childName.trim() || request.completion) return;
+		request.completion = loadHeavy(latestLifecycleContext()).then(async (handle) => {
+			handle.assertCurrent();
+			const forwarded: SupervisorAuthorizationRequest = { childName: request.childName };
+			await dispatchEventHandlers(handle.heavy, SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT, forwarded);
+			if (!forwarded.completion) throw new Error("Intercom supervisor authorization provider is unavailable");
+			return await forwarded.completion;
+		});
+	});
 	for (const eventName of [SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_RESULT_INTERCOM_EVENT] as const) {
 		pi.events.on(eventName, (payload) => {
 			void loadHeavy(latestLifecycleContext()).then(async (handle) => {
@@ -318,6 +363,20 @@ export default function intercom(pi: ExtensionAPI, options: LightweightIntercomO
 			});
 		});
 	}
+	pi.events.on(WORKFLOW_STAGE_LATE_MESSAGE_EVENT, (payload) => {
+		if (!payload || typeof payload !== "object") return;
+		const event = payload as WorkflowStageLateMessageEvent;
+		// A completed-stage blocking ask belongs to the workflow post-mortem
+		// router. It must remain unclaimed when Intercom registers first, while
+		// every event already claimed by an earlier listener keeps its owner.
+		if (event.handled === true || isCompletedStageAskRoute(event)) return;
+		event.handled = true;
+		event.completion = loadHeavy(latestLifecycleContext()).then(async (handle) => {
+			handle.assertCurrent();
+			await dispatchEventHandlers(handle.heavy, WORKFLOW_STAGE_LATE_MESSAGE_EVENT, payload);
+			handle.assertCurrent();
+		});
+	});
 	// Heavy Intercom state stays unloaded until the model or user invokes an
 	// Intercom tool, command, shortcut, or relay that needs it.
 	pi.registerTool({
@@ -325,14 +384,16 @@ export default function intercom(pi: ExtensionAPI, options: LightweightIntercomO
 		label: "Intercom",
 		description: `Send a message to another local agent session running on this machine.
 Use this to communicate findings, request help, or coordinate work with other sessions.
+Sessions belong to an intercom group and can ONLY message sessions in the same group; cross-group sends are rejected by the broker. Ungrouped sessions share the "default" group.
 Usage:
-  intercom({ action: "list" })                    → List active sessions
-  intercom({ action: "send", to: "session-name", message: "..." })  → Send message
+  intercom({ action: "list" })                    → List sessions in your group
+  intercom({ action: "list", group: "name" })     → Read-only peek at another group's sessions
+  intercom({ action: "send", to: "session-name", message: "..." })  → Send message (own group only)
   intercom({ action: "ask", to: "session-name", message: "..." })   → Ask and wait for reply
   intercom({ action: "reply", message: "..." })                      → Reply to the active/single pending ask
   intercom({ action: "pending" })                                      → List unresolved inbound asks
-  intercom({ action: "status" })                  → Show connection status`,
-		promptSnippet: "Use to coordinate with other local agent sessions: list peers, send updates, ask for help, or check intercom connectivity.",
+  intercom({ action: "status" })                  → Show connection status and your group`,
+		promptSnippet: "Use to coordinate with other local agent sessions in your intercom group: list peers, send updates, ask for help, or check intercom connectivity. Groups are isolated; you can only message sessions in your own group.",
 		parameters: Type.Object({
 			action: Type.String({ description: "Action: 'list', 'send', 'ask', 'reply', 'pending', or 'status'" }),
 			to: Type.Optional(Type.String({ description: "Target session name or ID (for 'send', 'ask', or disambiguating 'reply')" })),
@@ -344,6 +405,7 @@ Usage:
 				language: Type.Optional(Type.String()),
 			}))),
 			replyTo: Type.Optional(Type.String({ description: "Message ID to reply to (for threading or responding to an 'ask')" })),
+			group: Type.Optional(Type.String({ description: "Read-only group filter for 'list'/'status'; 'send'/'ask' are locked to your own group." })),
 		}),
 		execute: (...args) => executeHeavyTool(loadHeavy, "intercom", args),
 		renderResult: (...args) => renderHeavyToolResult(loadedHeavy?.heavy ?? null, "intercom", args),

package/dist/builtin/intercom/intercom-test-seams.ts

@@ -0,0 +1,6 @@
+import type { ExtensionContext } from "@bastani/atomic";
+import type { Message, SessionInfo } from "./types.js";
+
+export interface IntercomExtensionTestOverrides {
+  captureInboundHandler?: (handler: (ctx: ExtensionContext, from: SessionInfo, message: Message) => void) => void;
+}