@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/builtin/intercom/closed-workflow-stage-message.ts

@@ -0,0 +1,66 @@
+import type { IntercomClient } from "./broker/client.js";
+import type { InboundMessageAdmission } from "./inbound-message-admission.js";
+import type { InboundMessageEntry } from "./intercom-utils.js";
+import { routeIncomingReply } from "./reply-routing.js";
+import type { ReplyTracker } from "./reply-tracker.js";
+import type { ReplyWaiterRecord } from "./reply-waiter.js";
+import { retryStableDelivery } from "./stable-delivery-retry.js";
+import { sendWorkflowStageDeliveryFailure } from "./workflow-stage-delivery-failure.js";
+
+/**
+ * Owns late ingress after a workflow stage seals its active generation.
+ * Blocking asks are handed to workflow post-mortem routing once and receive a
+ * correlated remote tool error if revival fails. Ordinary late notifications
+ * retain the stable parent-route retry used before completed-stage asks existed.
+ */
+export function routeClosedWorkflowStageMessage(
+  entry: InboundMessageEntry,
+  admission: InboundMessageAdmission,
+  tracker: ReplyTracker,
+  waiter: ReplyWaiterRecord | null,
+  deliver: () => Promise<void>,
+  currentClient: () => IntercomClient | null,
+  isCurrent: () => boolean,
+): void {
+  if (entry.message.expectsReply !== true) {
+    void retryStableDelivery({ deliver, isCurrent }).catch(() => {});
+    return;
+  }
+  const admitted = admission.admit(entry.from, entry.message);
+  if (admitted.kind !== "reserved") return;
+  if (routeIncomingReply(waiter, entry.from, entry.message)) {
+    admission.commit(admitted.reservation);
+    return;
+  }
+  const replyContext = tracker.recordIncomingMessage(entry.from, entry.message);
+  tracker.queueTurnContext(replyContext);
+  const delivery = invoke(deliver);
+  void delivery.then(
+    () => { admission.commit(admitted.reservation); },
+    async (error: unknown) => {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      tracker.forgetIncomingMessage(replyContext);
+      if (entry.message.expectsReply === true
+        && await sendWorkflowStageDeliveryFailure(
+          entry,
+          failure,
+          tracker,
+          currentClient,
+          isCurrent,
+          "Completed workflow stage could not process intercom ask",
+        )) {
+        admission.commit(admitted.reservation);
+        return;
+      }
+      admission.release(admitted.reservation, failure);
+    },
+  ).catch(() => {});
+}
+
+function invoke(deliver: () => Promise<void>): Promise<void> {
+  try {
+    return Promise.resolve(deliver());
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}

package/dist/builtin/intercom/config.ts

@@ -19,6 +19,9 @@ export interface IntercomConfig {
 
   /** Show reply hint in incoming messages (default: true) */
   replyHint: boolean;
+
+  /** Default intercom home group for this session (overridden by env/orchestrator). */
+  group?: string;
 }
 
 const CONFIG_PATHS = getAgentConfigPaths("intercom", "config.json");
@@ -103,6 +106,13 @@ export function loadConfig(): IntercomConfig {
       config.status = parsedConfig.status;
     }
 
+    if (Object.hasOwn(parsedConfig, "group")) {
+      if (typeof parsedConfig.group !== "string") {
+        throw new Error(`"group" must be a string`);
+      }
+      config.group = parsedConfig.group;
+    }
+
     return config;
   } catch (error) {
     console.error(`Failed to load intercom config at ${CONFIG_PATH}:`, error);

package/dist/builtin/intercom/contact-supervisor-tool.ts

@@ -118,14 +118,18 @@ export function registerContactSupervisorTool(pi: ExtensionAPI, deps: ContactSup
 
         const metadata = childOrchestratorMetadata;
         let sendTo: string;
-        try {
-          sendTo = await resolveSessionTarget(connectedClient, metadata.orchestratorTarget) ?? metadata.orchestratorTarget;
-        } catch (error) {
-          return {
-            content: [{ type: "text", text: `Failed to resolve supervisor target: ${getErrorMessage(error)}` }],
-            isError: true,
-            details: { error: true },
-          };
+        if (connectedClient.supervisorSessionId || metadata.supervisor) {
+          sendTo = connectedClient.supervisorSessionId ?? metadata.supervisor!.supervisorSessionId;
+        } else {
+          try {
+            sendTo = await resolveSessionTarget(connectedClient, metadata.orchestratorTarget) ?? metadata.orchestratorTarget;
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: `Failed to resolve supervisor target: ${getErrorMessage(error)}` }],
+              isError: true,
+              details: { error: true },
+            };
+          }
         }
         if (signal?.aborted) {
           return {
@@ -145,7 +149,7 @@ export function registerContactSupervisorTool(pi: ExtensionAPI, deps: ContactSup
         if (reason === "progress_update") {
           const message = params.message as string;
           try {
-            const result = await connectedClient.send(sendTo, {
+            const result = await connectedClient.sendToSupervisor(sendTo, {
               text: formatChildOrchestratorMessage("update", metadata, message),
             });
             if (!result.delivered) {
@@ -200,7 +204,7 @@ export function registerContactSupervisorTool(pi: ExtensionAPI, deps: ContactSup
           const requestText = reason === "interview_request"
             ? formatChildOrchestratorMessage("interview", metadata, formatSupervisorInterviewRequest(supervisorInterview!, typeof params.message === "string" ? params.message : undefined))
             : formatChildOrchestratorMessage("ask", metadata, params.message as string);
-          const sendResult = await connectedClient.send(sendTo, {
+          const sendResult = await connectedClient.sendToSupervisor(sendTo, {
             messageId: questionId,
             text: requestText,
             expectsReply: true,

package/dist/builtin/intercom/foreground-detach-handoff.ts

@@ -13,7 +13,7 @@ interface DetachHandshake {
   runtimeGeneration: number;
 }
 
-type ForegroundDeliveryDisposition = "delivered" | "unclaimed" | "abandoned";
+export type ForegroundDeliveryDisposition = "delivered" | "unclaimed" | "abandoned";
 
 /** Claims a busy inbound message only when its exact foreground owner acknowledges it. */
 export class ForegroundDetachHandoff {
@@ -49,6 +49,15 @@ export class ForegroundDetachHandoff {
     return attempt;
   }
 
+  claim(
+    from: SessionInfo,
+    message: Message,
+    generation: number,
+    isCurrent: () => boolean,
+  ): Promise<ForegroundDeliveryDisposition> {
+    return this.deliver({ from, message, generation, isCurrent, surface: () => {} });
+  }
+
   reset(): void { this.resetForGeneration(-1); }
 
   private async claimAndDeliver(
@@ -69,7 +78,8 @@ export class ForegroundDetachHandoff {
     if (probed === "timed-out") return "unclaimed";
 
     const committed = await this.awaitAcknowledgement({ ...route, phase: "commit" }, signal);
-    if (committed !== "acknowledged" || !input.isCurrent() || this.generation !== input.generation) return "abandoned";
+    if (committed === "cancelled" || !input.isCurrent() || this.generation !== input.generation) return "abandoned";
+    if (committed === "timed-out") return "unclaimed";
     input.surface();
     this.delivered.add(deliveryKey);
     return "delivered";

package/dist/builtin/intercom/group.ts

@@ -0,0 +1,46 @@
+import { getEnvValue } from "@bastani/atomic";
+
+/** The implicit group every ungrouped session belongs to. */
+export const DEFAULT_GROUP = "default";
+
+/**
+ * Normalize an intercom group id. Undefined, empty, or whitespace-only values
+ * collapse to the shared {@link DEFAULT_GROUP} so ungrouped sessions all compare
+ * equal and can still talk to each other (backward compatible).
+ */
+export function normalizeGroup(value?: string | null): string {
+  if (typeof value !== "string") return DEFAULT_GROUP;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : DEFAULT_GROUP;
+}
+
+/** `getEnvValue("ATOMIC_INTERCOM_GROUP")` also resolves the legacy `PI_INTERCOM_GROUP`. */
+const INTERCOM_GROUP_ENV = "ATOMIC_INTERCOM_GROUP";
+
+interface HomeGroupContext {
+  orchestrationContext?: { intercomGroup?: string } | undefined;
+}
+
+/**
+ * Resolve a session's home intercom group with precedence (most specific first):
+ * per-session orchestrationContext.intercomGroup (in-process workflow stages) >
+ * env ATOMIC_INTERCOM_GROUP (also PI_INTERCOM_GROUP legacy) > config.json "group" >
+ * "default". Always returns a concrete normalized string.
+ */
+export function resolveHomeGroup(
+  config: { group?: string } | undefined,
+  ctx?: HomeGroupContext | null,
+): string {
+  const fromContext = ctx?.orchestrationContext?.intercomGroup;
+  if (typeof fromContext === "string" && fromContext.trim().length > 0) {
+    return normalizeGroup(fromContext);
+  }
+  const fromEnv = getEnvValue(INTERCOM_GROUP_ENV);
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+    return normalizeGroup(fromEnv);
+  }
+  if (config && typeof config.group === "string" && config.group.trim().length > 0) {
+    return normalizeGroup(config.group);
+  }
+  return DEFAULT_GROUP;
+}

package/dist/builtin/intercom/inbound-message-admission.ts

@@ -0,0 +1,79 @@
+import { DeliveredMessageCache } from "./broker/delivered-message-cache.js";
+import type { Message, SessionInfo } from "./types.js";
+
+export interface InboundMessageReservation {
+  readonly messageId: string;
+  readonly signature: string;
+  readonly token: symbol;
+}
+
+export type InboundMessageAdmissionResult =
+  | { readonly kind: "reserved"; readonly reservation: InboundMessageReservation }
+  | { readonly kind: "pending"; readonly completion: Promise<void> }
+  | { readonly kind: "duplicate" };
+
+interface PendingInboundMessage {
+  readonly reservation: InboundMessageReservation;
+  readonly completion: Promise<void>;
+  readonly resolve: () => void;
+  readonly reject: (error: Error) => void;
+  delivering: boolean;
+}
+
+/** Deduplicates broker deliveries before reply-tracker or turn-context side effects. */
+export class InboundMessageAdmission {
+  private readonly delivered = new DeliveredMessageCache();
+  private readonly pending = new Map<string, PendingInboundMessage>();
+
+  admit(from: SessionInfo, message: Message): InboundMessageAdmissionResult {
+    const signature = JSON.stringify({ from: from.id, message });
+    if (this.delivered.lookup(message.id, signature) !== "miss") return { kind: "duplicate" };
+    const pending = this.pending.get(message.id);
+    if (pending) {
+      if (pending.reservation.signature !== signature || pending.delivering) return { kind: "duplicate" };
+      return { kind: "pending", completion: pending.completion };
+    }
+    const reservation = { messageId: message.id, signature, token: Symbol(message.id) };
+    const deferred = Promise.withResolvers<void>();
+    void deferred.promise.catch(() => {});
+    this.pending.set(message.id, { reservation, completion: deferred.promise, resolve: deferred.resolve, reject: deferred.reject, delivering: false });
+    return { kind: "reserved", reservation };
+  }
+
+  reserve(from: SessionInfo, message: Message): InboundMessageReservation | undefined {
+    const result = this.admit(from, message);
+    return result.kind === "reserved" ? result.reservation : undefined;
+  }
+
+  beginDelivery(reservation: InboundMessageReservation): void {
+    const pending = this.pending.get(reservation.messageId);
+    if (pending?.reservation === reservation) pending.delivering = true;
+  }
+
+  endDelivery(reservation: InboundMessageReservation): void {
+    const pending = this.pending.get(reservation.messageId);
+    if (pending?.reservation === reservation) pending.delivering = false;
+  }
+
+  commit(reservation: InboundMessageReservation): void {
+    const pending = this.pending.get(reservation.messageId);
+    if (pending?.reservation !== reservation) return;
+    this.pending.delete(reservation.messageId);
+    this.delivered.record(reservation.messageId, reservation.signature);
+    pending.resolve();
+  }
+
+  release(reservation: InboundMessageReservation, error = new Error("Inbound message admission released")): void {
+    const pending = this.pending.get(reservation.messageId);
+    if (pending?.reservation !== reservation) return;
+    this.pending.delete(reservation.messageId);
+    pending.reject(error);
+  }
+
+  accept(from: SessionInfo, message: Message): boolean {
+    const reservation = this.reserve(from, message);
+    if (!reservation) return false;
+    this.commit(reservation);
+    return true;
+  }
+}

package/dist/builtin/intercom/incoming-message-delivery.ts

@@ -0,0 +1,49 @@
+import type { ExtensionAPI } from "@bastani/atomic";
+import type { InboundMessageEntry } from "./intercom-utils.js";
+import type { IntercomContext } from "./reply-tracker.js";
+
+export type IncomingMessageDelivery = "trigger" | "followUp" | "prelude";
+export type IncomingMessageSender = (
+  entry: InboundMessageEntry,
+  delivery: IncomingMessageDelivery,
+  generation?: number,
+  trackReplyContext?: boolean,
+  turnContext?: IntercomContext,
+  stageAdmissionBarrier?: () => Promise<void>,
+) => Promise<void>;
+
+/** Creates generation-safe Intercom delivery into the Atomic custom-message API. */
+export function createIncomingMessageSender(input: {
+  pi: Pick<ExtensionAPI, "sendMessage">;
+  currentGeneration: () => number;
+  canDeliver: (generation: number) => boolean;
+  queueTurnContext: (context: IntercomContext) => void;
+}): IncomingMessageSender {
+  return (entry, delivery, generation = input.currentGeneration(), trackReplyContext = true, turnContext, stageAdmissionBarrier) => {
+    if (!input.canDeliver(generation)) {
+      return Promise.reject(new Error("Intercom session retired before inbound delivery"));
+    }
+    if (delivery === "trigger" && trackReplyContext) {
+      input.queueTurnContext(turnContext ?? { from: entry.from, message: entry.message, receivedAt: Date.now() });
+    }
+    const baseOptions = {
+      stageAdmissionKey: `intercom:${entry.message.id}`,
+      ...(stageAdmissionBarrier ? { stageAdmissionBarrier } : {}),
+    } as const;
+    const options = delivery === "trigger"
+      ? { ...baseOptions, triggerTurn: true } as const
+      : delivery === "followUp" ? { ...baseOptions, deliverAs: "followUp" } as const : baseOptions;
+    return Promise.resolve(input.pi.sendMessage(buildIncomingCustomMessage(entry), options));
+  };
+}
+
+export 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,
+  };
+}