@bastani/atomic 0.9.19-alpha.1 → 0.9.19-alpha.3

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

@@ -14,6 +14,7 @@ import type {
 	WorkflowStageRosterEntry,
 	WorkflowFutureStageRosterEntry,
 	WorkflowPossibleStageAnnouncement,
+	WorkflowRunParentAnnouncement,
 } from "../types.js";
 import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry.js";
 import { readSubagentMessageSource } from "../source-ownership.js";
@@ -37,6 +38,8 @@ export interface SendOptions {
   logicalTarget?: string;
   /** Public reply must use the broker's exact pending reverse question route. */
   requirePendingReply?: true;
+  /** Broker-authorized identity for a canonical-path ask, delivered before its recipient can reply. */
+  onReplyTarget?: (sessionId: string) => void;
 }
 
 export interface SendResult {
@@ -92,6 +95,7 @@ export interface PresenceUpdates {
   model?: string;
   groups?: string[];
   group?: string;
+  replyCapability?: SessionInfo["replyCapability"];
 }
 
 
@@ -151,6 +155,7 @@ 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 pendingReplyTargets = new Map<string, { messageId: string; bind(sessionId: string): void }>();
   private pendingGroupLists = new Map<string, { resolve: (groups: GroupSummary[]) => void; reject: (error: Error) => void }>();
   private pendingLists = new Map<string, { resolve: (directory: SessionDirectory) => void; reject: (e: Error) => void }>();
   private pendingPresence = new Map<string, {
@@ -413,6 +418,15 @@ export class IntercomClient extends EventEmitter {
         this.emit("_registration_failed", new Error(brokerMessage.reason));
         break;
       }
+      case "question_target": {
+        const { messageId, attemptId, sessionId } = brokerMessage;
+        if (typeof messageId !== "string" || typeof attemptId !== "string" || typeof sessionId !== "string") {
+          throw new Error("Invalid question_target message");
+        }
+        const pending = this.pendingReplyTargets.get(attemptId);
+        if (pending?.messageId === messageId) pending.bind(sessionId);
+        break;
+      }
       case "sessions": {
 		const { requestId, sessions, workflowStages, workflowFutureStages } = brokerMessage;
 		if (
@@ -855,6 +869,7 @@ export class IntercomClient extends EventEmitter {
 	capability: string,
 	stages?: WorkflowStageRosterAnnouncement[],
 	possibleStages?: WorkflowPossibleStageAnnouncement[],
+	parent?: WorkflowRunParentAnnouncement,
   ): void {
 	writeMessage(this.requireActiveSocket(), {
 		type: "register_pending_stage_route",
@@ -863,6 +878,7 @@ export class IntercomClient extends EventEmitter {
 		capability,
 		stages,
 		possibleStages,
+		...(parent === undefined ? {} : { parent }),
 	});
   }
 
@@ -985,12 +1001,16 @@ export class IntercomClient extends EventEmitter {
       source: this._messageSource,
       content: { text: options.text, attachments: options.attachments },
     };
+    if (options.onReplyTarget !== undefined) {
+      this.pendingReplyTargets.set(acquired.attempt.attemptId, { messageId, bind: options.onReplyTarget });
+    }
     try {
 		writeMessage(socket, {
 			type,
 			to,
 			...(options.logicalTarget === undefined ? {} : { logicalTarget: options.logicalTarget }),
 			...(options.requirePendingReply === undefined ? {} : { requirePendingReply: options.requirePendingReply }),
+      ...(options.onReplyTarget === undefined ? {} : { resolveReplyTarget: true as const }),
 			message,
 			attemptId: acquired.attempt.attemptId,
 			...extra,
@@ -998,6 +1018,8 @@ export class IntercomClient extends EventEmitter {
     } catch (error) {
       this.pendingSends.reject(acquired.attempt, toError(error));
     }
+    const clearReplyTarget = () => { this.pendingReplyTargets.delete(acquired.attempt.attemptId); };
+    void acquired.attempt.promise.then(clearReplyTarget, clearReplyTarget);
     return acquired.attempt.promise;
   }
   updatePresence(updates: PresenceUpdates): boolean {

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

@@ -1,5 +1,8 @@
 import type { Socket } from "net";
 
+/** JSON values at the framing boundary, before protocol-specific validation. */
+export type JsonWireValue = string | number | boolean | null | JsonWireValue[] | { [key: string]: JsonWireValue };
+
 /**
  * Write a length-prefixed message to a socket.
  * Format: 4-byte big-endian length + JSON payload
@@ -20,7 +23,7 @@ export function writeMessage(socket: Socket, msg: unknown, callback?: (error?: E
  * Protocol or handler errors are reported to onError so the caller can close the socket.
  */
 export function createMessageReader(
-  onMessage: (msg: unknown) => void,
+  onMessage: (msg: JsonWireValue) => void,
   onError: (error: Error) => void,
 ) {
   let buffer = Buffer.alloc(0);
@@ -38,7 +41,7 @@ export function createMessageReader(
       const payload = buffer.subarray(4, 4 + length);
       buffer = buffer.subarray(4 + length);
 
-      let msg: unknown;
+      let msg: JsonWireValue;
       try {
         msg = JSON.parse(payload.toString("utf-8"));
       } catch (error) {

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

@@ -1,6 +1,7 @@
 import { hasGroup, normalizeGroup, normalizeGroups } from "../group.js";
 import type { GroupSummary, SessionInfo } from "../types.js";
 import type { BrokerConnectedSession } from "./send-handler.js";
+import { isAgentRecipient } from "../recipient-purpose.js";
 
 /** Return the normalized memberships carried by a wire session. */
 export function sessionGroups(session: SessionInfo): Set<string> {
@@ -28,7 +29,7 @@ export function sessionsVisibleTo(
 	sessions: ReadonlyMap<string, BrokerConnectedSession>,
 	requester: SessionInfo,
 ): SessionInfo[] {
-	return [...sessions.values()].map(({ info }) => info).filter((info) => sessionsShareGroup(requester, info));
+	return [...sessions.values()].map(({ info }) => info).filter((info) => isAgentRecipient(info) && sessionsShareGroup(requester, info));
 }
 
 /** Return sessions that belong to one explicit group. */
@@ -36,7 +37,7 @@ export function sessionsInGroup(
 	sessions: ReadonlyMap<string, BrokerConnectedSession>,
 	group: string | undefined,
 ): SessionInfo[] {
-	return [...sessions.values()].map(({ info }) => info).filter((info) => hasGroup(sessionGroups(info), group));
+	return [...sessions.values()].map(({ info }) => info).filter((info) => isAgentRecipient(info) && hasGroup(sessionGroups(info), group));
 }
 
 /** Summarize every group currently represented by a connected session. */
@@ -46,6 +47,7 @@ export function knownGroupSummaries(
 ): GroupSummary[] {
 	const counts = new Map<string, number>();
 	for (const { info } of sessions.values()) {
+		if (!isAgentRecipient(info)) continue;
 		for (const group of sessionGroups(info)) counts.set(group, (counts.get(group) ?? 0) + 1);
 	}
 	const requesterGroups = sessionGroups(requester);

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

@@ -3,6 +3,9 @@ import { addGroup, normalizeGroups, removeGroup, validateRuntimeGroup } from "..
 import type { BrokerMessage } from "../types.js";
 import { sessionGroups, sessionsShareGroup, setSessionGroups } from "./group-membership.js";
 import type { BrokerConnectedSession } from "./send-handler.js";
+import { isAgentRecipient } from "../recipient-purpose.js";
+import type { PendingQuestionIndex } from "./pending-question-index.js";
+import { failTerminalQuestions } from "./terminal-questions.js";
 
 interface PresenceClientMessage extends Record<string, unknown> {
 	type: string;
@@ -16,6 +19,7 @@ function broadcastMembershipChange(
 	session: BrokerConnectedSession,
 	previous: ReadonlySet<string>,
 ): void {
+	if (!isAgentRecipient(session.info)) return;
 	const previousInfo = { ...session.info, groups: [...previous], group: previous.values().next().value };
 	for (const [id, peer] of sessions) {
 		if (id === session.info.id) continue;
@@ -38,6 +42,7 @@ export function handleBrokerPresence(
 	currentId: string | null,
 	sessions: Map<string, BrokerConnectedSession>,
 	write: WriteMessage,
+	pendingQuestions?: PendingQuestionIndex,
 ): void {
 	const rawRequestId = clientMessage.requestId;
 	if (rawRequestId !== undefined && typeof rawRequestId !== "string") {
@@ -97,10 +102,19 @@ export function handleBrokerPresence(
 	if (status !== undefined && typeof status !== "string") return void fail("Invalid presence status");
 	const model = clientMessage.model;
 	if (model !== undefined && typeof model !== "string") return void fail("Invalid presence model");
+	const capability = clientMessage.replyCapability;
+	if (capability !== undefined && capability !== "live" && capability !== "terminal") {
+		return void fail("Invalid reply capability");
+	}
+	if (capability === "live" && session.info.replyCapability === "terminal") {
+		return void fail("Terminal reply capability cannot be revived");
+	}
 
 	if (typeof name === "string") session.info.name = name;
 	if (typeof status === "string") session.info.status = status;
 	if (typeof model === "string") session.info.model = model;
+	if (capability === "live" || capability === "terminal") session.info.replyCapability = capability;
+	if (capability === "terminal" && pendingQuestions) failTerminalQuestions(session, sessions, pendingQuestions, write);
 	setSessionGroups(session.info, nextGroups, legacyGroup);
 	session.info.lastActivity = Date.now();
 	broadcastMembershipChange(sessions, write, session, previousGroups);

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

@@ -1,3 +1,4 @@
+import { TERMINAL_CHILD_ASK_REFUSAL } from "../recipient-purpose.js";
 import type net from "node:net";
 import type { BrokerMessage, Message, SessionInfo } from "../types.js";
 import {
@@ -14,6 +15,7 @@ import { SupervisorChannelCache } from "./supervisor-channel.js";
 import { isVerticalBypass, sameGroup } from "./group-isolation.js";
 import { sessionGroups, sessionsShareGroup } from "./group-membership.js";
 import { PendingQuestionIndex } from "./pending-question-index.js";
+import { isAgentRecipient, NON_AGENT_RECIPIENT_REFUSAL } from "../recipient-purpose.js";
 
 export interface BrokerConnectedSession {
   socket: net.Socket;
@@ -57,6 +59,7 @@ export interface PendingStageRoute {
   readonly attemptId?: string;
 	readonly liveTargetId?: string;
 	readonly signature?: string;
+	readonly resolveReplyTarget?: true;
 }
 
 export type PendingStageRouter = (route: PendingStageRoute) => boolean;
@@ -111,6 +114,7 @@ export function handleBrokerSend(
 	canControlLiveWorkflowStage?: LiveWorkflowStageController,
 	resolveLegacyWorkflowStageTarget?: LegacyWorkflowStageTargetResolver,
 	writeConfirmed?: ConfirmedMessageWriter,
+	isNonAgentWorkflowTarget?: (target: string) => boolean,
 ): void {
   const message = clientMessage.message;
   const messageId = wireMessageId(message);
@@ -175,6 +179,10 @@ export function handleBrokerSend(
     return;
   }
 	const workflowTarget = parseWorkflowStageTarget(trimmedTo);
+	if (isNonAgentWorkflowTarget?.(trimmedTo)) {
+		write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: NON_AGENT_RECIPIENT_REFUSAL });
+		return;
+	}
 	// Slice 3 (D3): asks to pattern/future stage targets stay refused; `send` is queued
 	// sticky by the workflow host, so the refusal must happen before any live delivery.
 	if (workflowTarget !== undefined && workflowTarget.kind !== "path" && message.expectsReply === true) {
@@ -206,11 +214,10 @@ export function handleBrokerSend(
 	const liveWorkflowTarget = sessions.has(trimmedTo) ? undefined : resolveLiveWorkflowStage?.(trimmedTo);
 	const exactIdTarget = sessions.get(trimmedTo) ?? liveWorkflowTarget;
   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) => sessionsShareGroup(info, fromSession.info),
-      );
+  const visibleCandidates = Array.from(sessions.values(), (session) => session.info).filter(
+	(info) => reachableAcrossGroups || sessionsShareGroup(info, fromSession.info),
+  );
+  const candidates = visibleCandidates.filter(isAgentRecipient);
   const resolution = exactIdTarget
     ? ({ kind: "resolved", session: exactIdTarget.info } as const)
     : resolveSessionTarget(candidates, trimmedTo);
@@ -226,6 +233,10 @@ export function handleBrokerSend(
       });
       return;
     }
+	if (!isAgentRecipient(target.info)) {
+		write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: NON_AGENT_RECIPIENT_REFUSAL });
+		return;
+	}
     if (target.info.id === fromSession.info.id) {
       write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Cannot message the current session" });
       return;
@@ -295,6 +306,10 @@ export function handleBrokerSend(
       });
       return;
     }
+  if (message.expectsReply === true && target.info.replyCapability === "terminal") {
+    write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: TERMINAL_CHILD_ASK_REFUSAL });
+    return;
+  }
 	if (deliveredMatch === "match") {
 		if (message.expectsReply === true) {
 			const acceptedQuestionTarget = deliveredMessages.lookupQuestionTarget(
@@ -312,6 +327,8 @@ export function handleBrokerSend(
 				return;
 			}
 			pendingQuestions.record(fromSession.info.id, target.info.id, message.id);
+			if (clientMessage.resolveReplyTarget === true && attemptId !== undefined)
+				write(socket, { type: "question_target", messageId: message.id, attemptId, sessionId: target.info.id });
 		}
 		write(socket, { type: "delivered", messageId: message.id, attemptId });
 		return;
@@ -355,6 +372,7 @@ export function handleBrokerSend(
 				...(attemptId ? { attemptId } : {}),
 				liveTargetId: target.info.id,
 				signature,
+				...(clientMessage.resolveReplyTarget === true ? { resolveReplyTarget: true } : {}),
 			})
 		) {
 			return;
@@ -402,6 +420,8 @@ export function handleBrokerSend(
 			return;
 		}
 		if (message.expectsReply === true) pendingQuestions.record(fromSession.info.id, target.info.id, message.id);
+		if (message.expectsReply === true && clientMessage.resolveReplyTarget === true && attemptId !== undefined)
+			write(socket, { type: "question_target", messageId: message.id, attemptId, sessionId: target.info.id });
 		write(socket, { type: "delivered", messageId: message.id, attemptId });
 		return;
 	}
@@ -419,6 +439,8 @@ export function handleBrokerSend(
 		});
 		return;
 	}
+	if (message.expectsReply === true && clientMessage.resolveReplyTarget === true && attemptId !== undefined)
+		write(socket, { type: "question_target", messageId: message.id, attemptId, sessionId: target.info.id });
     const finishDelivery = (): void => {
 	  let accepted: ReturnType<DeliveredMessageCache["accept"]>;
 	  try {
@@ -442,6 +464,17 @@ export function handleBrokerSend(
 		});
 		return;
 	  }
+      // A terminal presence frame can arrive while the socket write callback is pending.
+      // Retain accepted-delivery authority, but never open a reply route after termination.
+      if (message.expectsReply === true && target.info.replyCapability === "terminal") {
+        write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: TERMINAL_CHILD_ASK_REFUSAL });
+        return;
+      }
+      if (message.expectsReply === true && sessions.get(target.info.id) !== target) {
+        write(socket, { type: "delivery_failed", messageId: message.id, attemptId,
+          reason: `Session "${target.info.name ?? target.info.id}" disconnected before replying` });
+        return;
+      }
       if (message.expectsReply === true) {
         pendingQuestions.record(fromSession.info.id, target.info.id, message.id);
 	  }
@@ -467,6 +500,10 @@ export function handleBrokerSend(
     finishDelivery();
     return;
   }
+	if (resolution.kind === "not_found" && visibleCandidates.some((info) => !isAgentRecipient(info) && info.name?.toLowerCase() === trimmedTo.toLowerCase())) {
+		write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: NON_AGENT_RECIPIENT_REFUSAL });
+		return;
+	}
 	if (
 		resolution.kind === "not_found" &&
 		!supervisorSend &&
@@ -479,6 +516,7 @@ export function handleBrokerSend(
 			message,
 			...(attemptId ? { attemptId } : {}),
 			signature,
+			...(clientMessage.resolveReplyTarget === true ? { resolveReplyTarget: true } : {}),
 		})
 	) {
 		return;

package/dist/builtin/intercom/broker/terminal-questions.ts

@@ -0,0 +1,29 @@
+import type net from "node:net";
+import { TERMINAL_CHILD_ASK_REFUSAL } from "../recipient-purpose.js";
+import type { BrokerMessage } from "../types.js";
+import type { PendingQuestionIndex } from "./pending-question-index.js";
+import type { BrokerConnectedSession } from "./send-handler.js";
+
+/** Settle only questions already admitted to this exact execution's registration. */
+export function failTerminalQuestions(
+  target: BrokerConnectedSession,
+  sessions: Map<string, BrokerConnectedSession>,
+  pending: PendingQuestionIndex,
+  write: (socket: net.Socket, message: BrokerMessage) => void,
+): void {
+  for (const question of pending.takeForTarget(target.info.id)) {
+    const sender = sessions.get(question.senderSessionId);
+    if (!sender) continue;
+    write(sender.socket, {
+      type: "message",
+      from: target.info,
+      message: {
+        id: `terminal:${question.messageId}`,
+        timestamp: Date.now(),
+        replyTo: question.messageId,
+        replyError: TERMINAL_CHILD_ASK_REFUSAL,
+        content: { text: TERMINAL_CHILD_ASK_REFUSAL },
+      },
+    });
+  }
+}