@bastani/atomic 0.9.18-alpha.4 → 0.9.18-alpha.6

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

@@ -12,11 +12,14 @@ import type {
 	SessionDirectory,
 	WorkflowStageRosterAnnouncement,
 	WorkflowStageRosterEntry,
+	WorkflowFutureStageRosterEntry,
+	WorkflowPossibleStageAnnouncement,
 } 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";
+import { IntercomClientDisconnectedError } from "../recoverable-disconnect.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
 const GROUP_REQUEST_TIMEOUT_MS = 5000;
@@ -30,6 +33,10 @@ export interface SendOptions {
   expectsReply?: boolean;
   replyError?: string;
   messageId?: string;
+  /** Internal caller-issued target identity; transport still uses the `to` argument. */
+  logicalTarget?: string;
+  /** Public reply must use the broker's exact pending reverse question route. */
+  requirePendingReply?: true;
 }
 
 export interface SendResult {
@@ -37,23 +44,32 @@ export interface SendResult {
   delivered: boolean;
   queued?: boolean;
   reason?: string;
-	reasonCode?: "message_id_conflict";
-  runId?: string;
-  stageKey?: string;
+	reasonCode?: "message_id_conflict" | "session_not_found";
+	target?: string;
   position?: number;
+  /** D4 speculative accept: the sticky target is not in the run's persisted possible-stage set. */
+  notInKnownSet?: true;
 }
 
 export interface PendingStageMessageRequest {
 	readonly requestId: string;
 	readonly from: SessionInfo;
 	readonly runId: string;
-	readonly stageKey: string;
+	readonly target: string;
 	readonly message: Message;
 	readonly senderRegistrationName?: string;
 	readonly senderReturnAddress?: string;
 	readonly live?: boolean;
 }
 
+/** Broker → route owner: the live stage targets a sticky broadcast was actually written to. */
+export interface StickyLiveDeliveredNotice {
+	readonly runId: string;
+	readonly messageId: string;
+	readonly target: string;
+	readonly deliveredTargets: readonly string[];
+}
+
 export interface PendingStageNotificationRequest {
 	readonly requestId: string;
 	readonly from: SessionInfo;
@@ -61,9 +77,14 @@ export interface PendingStageNotificationRequest {
 }
 
 export type PendingStageMessageResult =
-	| { readonly outcome: "queued"; readonly position: number }
+	| {
+			readonly outcome: "queued";
+			readonly position: number;
+			readonly notInKnownSet?: true;
+			readonly forwardTargets?: readonly string[];
+	  }
 	| { readonly outcome: "delivered" }
-	| { readonly outcome: "forward" }
+	| { readonly outcome: "forward"; readonly target: string }
 	| { readonly outcome: "refused"; readonly reason: string; readonly reasonCode?: "message_id_conflict" };
 export interface PresenceUpdates {
   name?: string;
@@ -83,6 +104,24 @@ function toError(error: unknown): Error {
 }
 
 
+
+function isWorkflowFutureStageRosterEntries(value: unknown): value is WorkflowFutureStageRosterEntry[] {
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(entry) =>
+				typeof entry === "object" &&
+				entry !== null &&
+				(entry as WorkflowFutureStageRosterEntry).kind === "workflow-future-stage" &&
+				typeof (entry as WorkflowFutureStageRosterEntry).runId === "string" &&
+				typeof (entry as WorkflowFutureStageRosterEntry).target === "string" &&
+				typeof (entry as WorkflowFutureStageRosterEntry).queuedCount === "number" &&
+				Number.isInteger((entry as WorkflowFutureStageRosterEntry).queuedCount) &&
+				(entry as WorkflowFutureStageRosterEntry).queuedCount >= 0 &&
+				typeof (entry as WorkflowFutureStageRosterEntry).group === "string",
+		)
+	);
+}
 function isWorkflowStageRosterEntries(value: unknown): value is WorkflowStageRosterEntry[] {
 	return (
 		Array.isArray(value) &&
@@ -181,7 +220,7 @@ export class IntercomClient extends EventEmitter {
     }
 
     if (socket.destroyed || socket.writableEnded || !socket.writable) {
-      throw new Error("Client disconnected");
+      throw new IntercomClientDisconnectedError();
     }
 
     return socket;
@@ -240,7 +279,7 @@ export class IntercomClient extends EventEmitter {
       const onClose = () => {
         const wasConnecting = !settled && !this._sessionId;
         const wasDisconnecting = this.disconnecting;
-        const disconnectError = this.disconnectError ?? new Error("Client disconnected");
+        const disconnectError = this.disconnectError ?? new IntercomClientDisconnectedError();
         this.disconnecting = false;
         cleanupConnectionAttempt();
         cleanupSocketListeners();
@@ -262,7 +301,21 @@ export class IntercomClient extends EventEmitter {
 
       const onSocketError = (err: Error) => {
         if (connectionEstablished) {
-          this.disconnectError = err;
+          // A transport error on an already-registered socket (ECONNRESET, EPIPE,
+          // ETIMEDOUT, or a write-after-end from our own write) is a *recoverable*
+          // disconnect: the broker connection is gone, and the lightweight wrapper
+          // re-imports and reconnects on the next call. Record it as the typed
+          // recoverable error so `onClose` rejects pending work and emits
+          // `disconnected` with something the classifier recognizes, and keep the
+          // raw transport error as `cause` so the code is still diagnosable.
+          //
+          // `??=`, not `=`: `onReaderError` records a protocol error and then
+          // destroys the socket, and a socket 'error' can still follow. Overwriting
+          // would silently downgrade a non-recoverable protocol failure into a
+          // recoverable one. First error recorded wins.
+          this.disconnectError ??= new IntercomClientDisconnectedError({ cause: err });
+          // The raw error keeps flowing to `error` listeners: that channel exists for
+          // diagnosis, and the transport code is what a debugger wants to see.
           this.emit("error", err);
         }
       };
@@ -359,19 +412,24 @@ export class IntercomClient extends EventEmitter {
         break;
       }
       case "sessions": {
-		const { requestId, sessions, workflowStages } = brokerMessage;
+		const { requestId, sessions, workflowStages, workflowFutureStages } = brokerMessage;
 		if (
 			typeof requestId !== "string" ||
 			!Array.isArray(sessions) ||
 			!sessions.every(isSessionInfo) ||
-			(workflowStages !== undefined && !isWorkflowStageRosterEntries(workflowStages))
+			(workflowStages !== undefined && !isWorkflowStageRosterEntries(workflowStages)) ||
+			(workflowFutureStages !== undefined && !isWorkflowFutureStageRosterEntries(workflowFutureStages))
 		) {
 			throw new Error("Invalid sessions message");
 		}
 		const pending = this.pendingLists.get(requestId);
 		if (!pending) return;
 		this.pendingLists.delete(requestId);
-		pending.resolve({ sessions, workflowStages: workflowStages ?? [] });
+		pending.resolve({
+			sessions,
+			workflowStages: workflowStages ?? [],
+			workflowFutureStages: workflowFutureStages ?? [],
+		});
 		break;
 	  }
       case "groups": {
@@ -416,14 +474,14 @@ export class IntercomClient extends EventEmitter {
         break;
       }
 		case "pending_stage_message": {
-			const { requestId, from, senderRegistrationName, senderReturnAddress, runId, stageKey, message, live } = brokerMessage;
+			const { requestId, from, senderRegistrationName, senderReturnAddress, runId, target, message, live } = brokerMessage;
 			if (
 				typeof requestId !== "string" ||
 				!isSessionInfo(from) ||
 				(senderRegistrationName !== undefined && typeof senderRegistrationName !== "string") ||
 				(senderReturnAddress !== undefined && typeof senderReturnAddress !== "string") ||
 				typeof runId !== "string" ||
-				typeof stageKey !== "string" ||
+				typeof target !== "string" ||
 				!isMessage(message) ||
 				(live !== undefined && typeof live !== "boolean")
 			) {
@@ -435,7 +493,7 @@ export class IntercomClient extends EventEmitter {
 				...(senderRegistrationName === undefined ? {} : { senderRegistrationName }),
 				...(senderReturnAddress === undefined ? {} : { senderReturnAddress }),
 				runId,
-				stageKey,
+				target,
 				message,
 				...(live === true ? { live: true } : {}),
 			} satisfies PendingStageMessageRequest);
@@ -453,6 +511,25 @@ export class IntercomClient extends EventEmitter {
 			} satisfies PendingStageNotificationRequest);
 			break;
 		}
+		case "sticky_live_delivered": {
+			const { runId, messageId, target, deliveredTargets } = brokerMessage;
+			if (
+				typeof runId !== "string" ||
+				typeof messageId !== "string" ||
+				typeof target !== "string" ||
+				!Array.isArray(deliveredTargets) ||
+				!deliveredTargets.every((entry) => typeof entry === "string")
+			) {
+				throw new Error("Invalid sticky live-delivery event");
+			}
+			this.emit("sticky_live_delivered", {
+				runId,
+				messageId,
+				target,
+				deliveredTargets,
+			} satisfies StickyLiveDeliveredNotice);
+			break;
+		}
       case "live_workflow_stage_route_registered": {
         const { requestId } = brokerMessage;
         if (typeof requestId !== "string") throw new Error("Invalid live workflow-stage route registration");
@@ -463,18 +540,25 @@ export class IntercomClient extends EventEmitter {
         break;
       }
       case "queued": {
-        const { messageId, attemptId, runId, stageKey, position } = brokerMessage;
+		const { messageId, attemptId, target, position, notInKnownSet } = brokerMessage;
         if (
           typeof messageId !== "string" ||
           (attemptId !== undefined && typeof attemptId !== "string") ||
-          typeof runId !== "string" ||
-          typeof stageKey !== "string" ||
+			typeof target !== "string" ||
           typeof position !== "number" ||
-          position < 1
+          position < 1 ||
+			(notInKnownSet !== undefined && notInKnownSet !== true)
         ) {
           throw new Error("Invalid queued message");
         }
-        const result = { id: messageId, delivered: false, queued: true, runId, stageKey, position } as const;
+		const result = {
+			id: messageId,
+			delivered: false,
+			queued: true,
+			target,
+			position,
+			...(notInKnownSet === true ? { notInKnownSet: true as const } : {}),
+		} as const;
         if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
         else this.pendingSends.resolve(messageId, attemptId, result);
         break;
@@ -495,7 +579,7 @@ export class IntercomClient extends EventEmitter {
 			typeof messageId !== "string" ||
 			(attemptId !== undefined && typeof attemptId !== "string") ||
 			typeof reason !== "string" ||
-			(reasonCode !== undefined && reasonCode !== "message_id_conflict")
+			(reasonCode !== undefined && reasonCode !== "message_id_conflict" && reasonCode !== "session_not_found")
 		) {
 			throw new Error("Invalid delivery_failed message");
 		}
@@ -603,7 +687,7 @@ export class IntercomClient extends EventEmitter {
     }
     this.disconnecting = true;
     this.disconnectError = null;
-    this.failPending(new Error("Client disconnected"));
+    this.failPending(new IntercomClientDisconnectedError());
     await new Promise<void>((resolve) => {
       let settled = false;
       const finish = () => {
@@ -768,8 +852,16 @@ export class IntercomClient extends EventEmitter {
 	group: string,
 	capability: string,
 	stages?: WorkflowStageRosterAnnouncement[],
+	possibleStages?: WorkflowPossibleStageAnnouncement[],
   ): void {
-	writeMessage(this.requireActiveSocket(), { type: "register_pending_stage_route", runId, group, capability, stages });
+	writeMessage(this.requireActiveSocket(), {
+		type: "register_pending_stage_route",
+		runId,
+		group,
+		capability,
+		stages,
+		possibleStages,
+	});
   }
 
   registerLiveWorkflowStageRoute(runId: string, stageKeys: readonly string[], capability: string): Promise<void> {
@@ -802,16 +894,25 @@ export class IntercomClient extends EventEmitter {
 		writeMessage(
 			socket,
 			result.outcome === "queued"
-				? { type: "pending_stage_message_result", requestId, outcome: "queued", position: result.position }
-				: result.outcome === "refused"
-					? {
-							type: "pending_stage_message_result",
-							requestId,
-							outcome: "refused",
-							reason: result.reason,
-							...(result.reasonCode === undefined ? {} : { reasonCode: result.reasonCode }),
-						}
-					: { type: "pending_stage_message_result", requestId, outcome: result.outcome },
+				? {
+						type: "pending_stage_message_result",
+						requestId,
+						outcome: "queued",
+						position: result.position,
+						...(result.notInKnownSet === true ? { notInKnownSet: true as const } : {}),
+						...(result.forwardTargets === undefined ? {} : { forwardTargets: [...result.forwardTargets] }),
+					}
+				: result.outcome === "forward"
+					? { type: "pending_stage_message_result", requestId, outcome: "forward", target: result.target }
+					: result.outcome === "refused"
+						? {
+								type: "pending_stage_message_result",
+								requestId,
+								outcome: "refused",
+								reason: result.reason,
+								...(result.reasonCode === undefined ? {} : { reasonCode: result.reasonCode }),
+							}
+						: { type: "pending_stage_message_result", requestId, outcome: result.outcome },
 		);
 	}
 
@@ -863,7 +964,12 @@ export class IntercomClient extends EventEmitter {
     const messageId = options.messageId ?? randomUUID();
     let acquired;
     try {
-      acquired = this.pendingSends.acquire(messageId, buildSendSignature(to, options), 10000);
+		const pendingSignature = JSON.stringify({
+			transportTarget: to,
+			logicalSignature: buildSendSignature(options.logicalTarget ?? to, options),
+			requirePendingReply: options.requirePendingReply ?? false,
+		});
+		acquired = this.pendingSends.acquire(messageId, pendingSignature, 10000);
     } catch (error) {
       return Promise.reject(toError(error));
     }
@@ -878,7 +984,15 @@ export class IntercomClient extends EventEmitter {
       content: { text: options.text, attachments: options.attachments },
     };
     try {
-		writeMessage(socket, { type, to, message, attemptId: acquired.attempt.attemptId, ...extra });
+		writeMessage(socket, {
+			type,
+			to,
+			...(options.logicalTarget === undefined ? {} : { logicalTarget: options.logicalTarget }),
+			...(options.requirePendingReply === undefined ? {} : { requirePendingReply: options.requirePendingReply }),
+			message,
+			attemptId: acquired.attempt.attemptId,
+			...extra,
+		});
     } catch (error) {
       this.pendingSends.reject(acquired.attempt, toError(error));
     }