@bastani/atomic 0.9.5-alpha.9 → 0.9.5

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

@@ -4,6 +4,7 @@ import { randomUUID } from "crypto";
 import { writeMessage, createMessageReader } from "./framing.js";
 import { getBrokerSocketPath } from "./paths.js";
 import type { SessionInfo, Message, Attachment } from "../types.js";
+import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
 
@@ -107,19 +108,14 @@ function isSessionInfo(value: unknown): value is SessionInfo {
 export class IntercomClient extends EventEmitter {
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
-  private pendingSends = new Map<string, { resolve: (r: SendResult) => void; reject: (e: Error) => void }>();
+  private pendingSends = new PendingSendRegistry();
   private pendingLists = new Map<string, { resolve: (sessions: SessionInfo[]) => void; reject: (e: Error) => void }>();
   private disconnecting = false;
   private disconnectError: Error | null = null;
 
   private failPending(error: Error): void {
-    for (const pending of this.pendingSends.values()) {
-      pending.reject(error);
-    }
-    this.pendingSends.clear();
-    for (const pending of this.pendingLists.values()) {
-      pending.reject(error);
-    }
+    this.pendingSends.rejectAll(error);
+    for (const pending of this.pendingLists.values()) pending.reject(error);
     this.pendingLists.clear();
   }
 
@@ -314,31 +310,23 @@ export class IntercomClient extends EventEmitter {
         break;
       }
       case "delivered": {
-        const { messageId } = brokerMessage;
-        if (typeof messageId !== "string") {
+        const { messageId, attemptId } = brokerMessage;
+        if (typeof messageId !== "string" || (attemptId !== undefined && typeof attemptId !== "string")) {
           throw new Error("Invalid delivered message");
         }
-        const pending = this.pendingSends.get(messageId);
-        if (!pending) {
-          // Late send responses are harmless once the caller has already timed out.
-          return;
-        }
-        this.pendingSends.delete(messageId);
-        pending.resolve({ id: messageId, delivered: true });
+        const result = { id: messageId, delivered: true } as const;
+        if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
+        else this.pendingSends.resolve(messageId, attemptId, result);
         break;
       }
       case "delivery_failed": {
-        const { messageId, reason } = brokerMessage;
-        if (typeof messageId !== "string" || typeof reason !== "string") {
+        const { messageId, attemptId, reason } = brokerMessage;
+        if (typeof messageId !== "string" || (attemptId !== undefined && typeof attemptId !== "string") || typeof reason !== "string") {
           throw new Error("Invalid delivery_failed message");
         }
-        const pending = this.pendingSends.get(messageId);
-        if (!pending) {
-          // Late send responses are harmless once the caller has already timed out.
-          return;
-        }
-        this.pendingSends.delete(messageId);
-        pending.resolve({ id: messageId, delivered: false, reason });
+        const result = { id: messageId, delivered: false, reason } as const;
+        if (attemptId === undefined) this.pendingSends.resolveLegacy(messageId, result);
+        else this.pendingSends.resolve(messageId, attemptId, result);
         break;
       }
       case "session_joined": {
@@ -452,40 +440,27 @@ export class IntercomClient extends EventEmitter {
       return Promise.reject(toError(error));
     }
     const messageId = options.messageId ?? randomUUID();
+    let acquired;
+    try {
+      acquired = this.pendingSends.acquire(messageId, buildSendSignature(to, options), 10000);
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    if (!acquired.owner) return acquired.attempt.promise;
+
     const message: Message = {
       id: messageId,
       timestamp: Date.now(),
       replyTo: options.replyTo,
       expectsReply: options.expectsReply,
-      content: {
-        text: options.text,
-        attachments: options.attachments,
-      },
+      content: { text: options.text, attachments: options.attachments },
     };
-    return new Promise((resolve, reject) => {
-      const wrappedResolve = (result: SendResult) => {
-        clearTimeout(timeout);
-        resolve(result);
-      };
-      const wrappedReject = (error: Error) => {
-        clearTimeout(timeout);
-        reject(error);
-      };
-      const timeout = setTimeout(() => {
-        if (this.pendingSends.has(messageId)) {
-          this.pendingSends.delete(messageId);
-          wrappedReject(new Error("Send timeout"));
-        }
-      }, 10000);
-      this.pendingSends.set(messageId, { resolve: wrappedResolve, reject: wrappedReject });
-      try {
-        writeMessage(socket, { type: "send", to, message });
-      } catch (error) {
-        clearTimeout(timeout);
-        this.pendingSends.delete(messageId);
-        reject(toError(error));
-      }
-    });
+    try {
+      writeMessage(socket, { type: "send", to, message, attemptId: acquired.attempt.attemptId });
+    } catch (error) {
+      this.pendingSends.reject(acquired.attempt, toError(error));
+    }
+    return acquired.attempt.promise;
   }
   updatePresence(updates: { name?: string; status?: string; model?: string }): void {
     if (this.disconnecting) {

package/dist/builtin/intercom/broker/delivered-message-cache.ts

@@ -0,0 +1,44 @@
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+
+export type DeliveredMessageMatch = "miss" | "match" | "conflict";
+
+interface DeliveredMessage {
+  deliveredAt: number;
+  signature: string;
+}
+
+/** Bounded successful-delivery cache used to make broker and local retries idempotent. */
+export class DeliveredMessageCache {
+  private readonly delivered = new Map<string, DeliveredMessage>();
+
+  constructor(
+    private readonly ttlMs = DEFAULT_TTL_MS,
+    private readonly maxEntries = DEFAULT_MAX_ENTRIES,
+  ) {}
+
+  lookup(messageId: string, signature: string, now = Date.now()): DeliveredMessageMatch {
+    this.prune(now);
+    const delivered = this.delivered.get(messageId);
+    if (!delivered || now - delivered.deliveredAt > this.ttlMs) return "miss";
+    return delivered.signature === signature ? "match" : "conflict";
+  }
+
+  record(messageId: string, signature: string, now = Date.now()): void {
+    this.prune(now);
+    this.delivered.delete(messageId);
+    this.delivered.set(messageId, { deliveredAt: now, signature });
+    while (this.delivered.size > this.maxEntries) {
+      const oldest = this.delivered.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.delivered.delete(oldest);
+    }
+  }
+
+  private prune(now: number): void {
+    for (const [messageId, delivered] of this.delivered) {
+      if (now - delivered.deliveredAt <= this.ttlMs) break;
+      this.delivered.delete(messageId);
+    }
+  }
+}

package/dist/builtin/intercom/broker/pending-send-registry.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from "crypto";
+import type { LogicalSendOptions } from "./send-signature.js";
+export { buildSendSignature } from "./send-signature.js";
+
+const DEFAULT_GENERATION_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_GENERATIONS = 10_000;
+
+export interface SendOptionsLike extends LogicalSendOptions {}
+
+export interface SendResultLike {
+  id: string;
+  delivered: boolean;
+  reason?: string;
+}
+
+export interface PendingSendAttempt {
+  readonly messageId: string;
+  readonly attemptId: string;
+  readonly signature: string;
+  readonly promise: Promise<SendResultLike>;
+}
+
+interface OwnedPendingSend extends PendingSendAttempt {
+  legacyEligible: boolean;
+  generation: number;
+  resolve(result: SendResultLike): void;
+  reject(error: Error): void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface PendingSendAcquisition {
+  attempt: PendingSendAttempt;
+  owner: boolean;
+}
+
+interface SendGeneration {
+  generation: number;
+  touchedAt: number;
+}
+
+
+export class PendingSendRegistry {
+  private readonly attempts = new Map<string, OwnedPendingSend>();
+  private readonly generations = new Map<string, SendGeneration>();
+
+  constructor(
+    private readonly generationTtlMs = DEFAULT_GENERATION_TTL_MS,
+    private readonly maxGenerations = DEFAULT_MAX_GENERATIONS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private nextGeneration(messageId: string): number {
+    const now = this.now();
+    for (const [id, record] of this.generations) {
+      if (now - record.touchedAt <= this.generationTtlMs) break;
+      this.generations.delete(id);
+    }
+    const previous = this.generations.get(messageId);
+    const generation = previous && now - previous.touchedAt <= this.generationTtlMs ? previous.generation + 1 : 1;
+    this.generations.delete(messageId);
+    this.generations.set(messageId, { generation, touchedAt: now });
+    while (this.generations.size > Math.max(1, this.maxGenerations)) {
+      const oldest = this.generations.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.generations.delete(oldest);
+    }
+    return generation;
+  }
+
+  private touchGeneration(attempt: OwnedPendingSend): void {
+    this.generations.delete(attempt.messageId);
+    this.generations.set(attempt.messageId, { generation: attempt.generation, touchedAt: this.now() });
+    while (this.generations.size > Math.max(1, this.maxGenerations)) {
+      const oldest = this.generations.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.generations.delete(oldest);
+    }
+  }
+  acquire(messageId: string, signature: string, timeoutMs: number): PendingSendAcquisition {
+    const existing = this.attempts.get(messageId);
+    if (existing) {
+      if (existing.signature !== signature) {
+        throw new Error(`Intercom message ID '${messageId}' is already pending with a different target or payload`);
+      }
+      return { attempt: existing, owner: false };
+    }
+
+    let resolvePromise!: (result: SendResultLike) => void;
+    let rejectPromise!: (error: Error) => void;
+    const promise = new Promise<SendResultLike>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    const generation = this.nextGeneration(messageId);
+    const attempt: OwnedPendingSend = {
+      messageId,
+      attemptId: randomUUID(),
+      signature,
+      promise,
+      resolve: resolvePromise,
+      reject: rejectPromise,
+      legacyEligible: generation === 1,
+      generation,
+    };
+    attempt.timer = setTimeout(() => {
+      this.reject(attempt, new Error("Send timeout"));
+    }, timeoutMs);
+    this.attempts.set(messageId, attempt);
+    return { attempt, owner: true };
+  }
+
+  resolve(messageId: string, attemptId: string, result: SendResultLike): boolean {
+    const attempt = this.attempts.get(messageId);
+    if (!attempt || attempt.attemptId !== attemptId) return false;
+    this.attempts.delete(messageId);
+    if (attempt.timer) clearTimeout(attempt.timer);
+    this.touchGeneration(attempt);
+    attempt.resolve(result);
+    return true;
+  }
+
+  /** Resolve a pre-attemptId response only for an ID's first active generation. */
+  resolveLegacy(messageId: string, result: SendResultLike): boolean {
+    const attempt = this.attempts.get(messageId);
+    if (!attempt?.legacyEligible) return false;
+    return this.resolve(messageId, attempt.attemptId, result);
+  }
+
+  reject(attempt: PendingSendAttempt, error: Error): boolean {
+    const current = this.attempts.get(attempt.messageId);
+    if (current !== attempt) return false;
+    this.attempts.delete(attempt.messageId);
+    if (current.timer) clearTimeout(current.timer);
+    this.touchGeneration(current);
+    current.reject(error);
+    return true;
+  }
+
+  rejectAll(error: Error): void {
+    for (const attempt of [...this.attempts.values()]) this.reject(attempt, error);
+  }
+}

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

@@ -0,0 +1,106 @@
+import type net from "node:net";
+import type { Attachment, BrokerMessage, Message, SessionInfo } from "../types.js";
+import { DeliveredMessageCache } from "./delivered-message-cache.js";
+import { buildMessageSendSignature } from "./send-signature.js";
+
+export interface BrokerConnectedSession {
+  socket: net.Socket;
+  info: SessionInfo;
+}
+
+interface SendClientMessage extends Record<string, unknown> {
+  type: string;
+}
+
+function isAttachment(value: unknown): value is Attachment {
+  if (typeof value !== "object" || value === null) return false;
+  const attachment = value as Record<string, unknown>;
+  if (attachment.type !== "file" && attachment.type !== "snippet" && attachment.type !== "context") return false;
+  if (typeof attachment.name !== "string" || typeof attachment.content !== "string") return false;
+  return attachment.language === undefined || typeof attachment.language === "string";
+}
+
+function isMessage(value: unknown): value is Message {
+  if (typeof value !== "object" || value === null) return false;
+  const message = value as Record<string, unknown>;
+  if (typeof message.id !== "string" || typeof message.timestamp !== "number") return false;
+  if (message.replyTo !== undefined && typeof message.replyTo !== "string") return false;
+  if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") return false;
+  if (typeof message.content !== "object" || message.content === null) return false;
+  const content = message.content as Record<string, unknown>;
+  if (typeof content.text !== "string") return false;
+  return content.attachments === undefined || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
+}
+
+function findSessions(sessions: Map<string, BrokerConnectedSession>, nameOrId: string): BrokerConnectedSession[] {
+  const byId = sessions.get(nameOrId);
+  if (byId) return [byId];
+  const lowerName = nameOrId.toLowerCase();
+  return Array.from(sessions.values()).filter((session) => session.info.name?.toLowerCase() === lowerName);
+}
+
+/** Validate and route one wire-level send request. */
+export function handleBrokerSend(
+  socket: net.Socket,
+  clientMessage: SendClientMessage,
+  currentId: string | null,
+  sessions: Map<string, BrokerConnectedSession>,
+  deliveredMessages: DeliveredMessageCache,
+  write: (target: net.Socket, message: BrokerMessage) => void,
+): void {
+  const message = clientMessage.message;
+  const messageId = isMessage(message) ? message.id : "unknown";
+  const hasAttemptId = Object.prototype.hasOwnProperty.call(clientMessage, "attemptId");
+  if (hasAttemptId && typeof clientMessage.attemptId !== "string") {
+    write(socket, {
+      type: "delivery_failed",
+      messageId,
+      reason: "Invalid attemptId format",
+    });
+    return;
+  }
+  const attemptId = typeof clientMessage.attemptId === "string" ? clientMessage.attemptId : undefined;
+  if (typeof clientMessage.to !== "string" || !isMessage(message)) {
+    write(socket, { type: "delivery_failed", messageId, attemptId, reason: "Invalid message format" });
+    return;
+  }
+
+  const signature = buildMessageSendSignature(clientMessage.to, message);
+  const deliveredMatch = deliveredMessages.lookup(message.id, signature);
+  if (deliveredMatch === "match") {
+    write(socket, { type: "delivered", messageId: message.id, attemptId });
+    return;
+  }
+  if (deliveredMatch === "conflict") {
+    write(socket, {
+      type: "delivery_failed",
+      messageId: message.id,
+      attemptId,
+      reason: `Intercom message ID '${message.id}' was already delivered with a different target or payload`,
+    });
+    return;
+  }
+
+  const targets = findSessions(sessions, clientMessage.to);
+  if (targets.length === 1) {
+    const fromSession = currentId ? sessions.get(currentId) : undefined;
+    if (!fromSession) {
+      write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Sender session not found" });
+      return;
+    }
+    write(targets[0].socket, { type: "message", from: fromSession.info, message });
+    deliveredMessages.record(message.id, signature);
+    write(socket, { type: "delivered", messageId: message.id, attemptId });
+    return;
+  }
+  if (targets.length > 1) {
+    write(socket, {
+      type: "delivery_failed",
+      messageId: message.id,
+      attemptId,
+      reason: `Multiple sessions named \"${clientMessage.to}\" are connected. Use the session ID instead.`,
+    });
+    return;
+  }
+  write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Session not found" });
+}

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

@@ -0,0 +1,37 @@
+import type { Attachment, Message } from "../types.js";
+
+export interface LogicalSendOptions {
+  text: string;
+  attachments?: Attachment[];
+  replyTo?: string;
+  expectsReply?: boolean;
+}
+
+function normalizeAttachments(attachments: Attachment[] | undefined): Array<Record<string, string>> | undefined {
+  return attachments?.map((attachment) => ({
+    type: attachment.type,
+    name: attachment.name,
+    content: attachment.content,
+    ...(attachment.language === undefined ? {} : { language: attachment.language }),
+  }));
+}
+
+/** Canonical identity for one logical send; transport attempt metadata is deliberately excluded. */
+export function buildSendSignature(to: string, options: LogicalSendOptions): string {
+  return JSON.stringify({
+    to,
+    text: options.text,
+    attachments: normalizeAttachments(options.attachments) ?? [],
+    replyTo: options.replyTo ?? null,
+    expectsReply: options.expectsReply ?? false,
+  });
+}
+
+export function buildMessageSendSignature(to: string, message: Message): string {
+  return buildSendSignature(to, {
+    text: message.content.text,
+    attachments: message.content.attachments,
+    replyTo: message.replyTo,
+    expectsReply: message.expectsReply,
+  });
+}

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

@@ -0,0 +1,136 @@
+import type { ExtensionAPI } from "@bastani/atomic";
+import type { Message, SessionInfo } from "./types.js";
+
+export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
+export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
+
+interface DetachHandshake {
+  phase: "probe" | "commit";
+  requestId: string;
+  messageId: string;
+  childIntercomTarget: string;
+  senderId: string;
+  runtimeGeneration: number;
+}
+
+type ForegroundDeliveryDisposition = "delivered" | "unclaimed" | "abandoned";
+
+/** Claims a busy inbound message only when its exact foreground owner acknowledges it. */
+export class ForegroundDetachHandoff {
+  private generation = -1;
+  private readonly delivered = new Set<string>();
+  private readonly pending = new Map<string, Promise<ForegroundDeliveryDisposition>>();
+  private generationCancellation = new AbortController();
+
+  constructor(
+    private readonly pi: Pick<ExtensionAPI, "events">,
+    private readonly ackTimeoutMs = 50,
+  ) {}
+
+  deliver(input: {
+    from: SessionInfo;
+    message: Message;
+    generation: number;
+    surface: () => void;
+    isCurrent: () => boolean;
+  }): Promise<ForegroundDeliveryDisposition> {
+    if (!input.isCurrent()) return Promise.resolve("abandoned");
+    if (this.generation !== input.generation) this.resetForGeneration(input.generation);
+    const deliveryKey = `${input.from.id}\0${input.message.id}`;
+    const pendingKey = `${input.generation}\0${deliveryKey}`;
+    if (this.delivered.has(deliveryKey)) return Promise.resolve("delivered");
+    const existing = this.pending.get(pendingKey);
+    if (existing) return existing;
+
+    const attempt = this.claimAndDeliver(input, deliveryKey).finally(() => {
+      if (this.pending.get(pendingKey) === attempt) this.pending.delete(pendingKey);
+    });
+    this.pending.set(pendingKey, attempt);
+    return attempt;
+  }
+
+  reset(): void { this.resetForGeneration(-1); }
+
+  private async claimAndDeliver(
+    input: { from: SessionInfo; message: Message; generation: number; surface: () => void; isCurrent: () => boolean },
+    deliveryKey: string,
+  ): Promise<ForegroundDeliveryDisposition> {
+    const route: DetachHandshake = {
+      phase: "probe",
+      requestId: input.message.id,
+      messageId: input.message.id,
+      childIntercomTarget: input.from.name || input.from.id,
+      senderId: input.from.id,
+      runtimeGeneration: input.generation,
+    };
+    const signal = this.generationCancellation.signal;
+    const probed = await this.awaitAcknowledgement(route, signal);
+    if (probed === "cancelled" || !input.isCurrent() || this.generation !== input.generation) return "abandoned";
+    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";
+    input.surface();
+    this.delivered.add(deliveryKey);
+    return "delivered";
+  }
+
+  private awaitAcknowledgement(
+    route: DetachHandshake,
+    signal: AbortSignal,
+  ): Promise<"acknowledged" | "timed-out" | "cancelled"> {
+    return new Promise((resolve) => {
+      let settled = false;
+      let unsubscribe: (() => void) | undefined;
+      let timeout: ReturnType<typeof setTimeout> | undefined;
+      const finish = (disposition: "acknowledged" | "timed-out" | "cancelled") => {
+        if (settled) return;
+        settled = true;
+        if (timeout) clearTimeout(timeout);
+        unsubscribe?.();
+        signal.removeEventListener("abort", cancel);
+        resolve(disposition);
+      };
+      const cancel = () => finish("cancelled");
+      unsubscribe = this.pi.events?.on(INTERCOM_DETACH_RESPONSE_EVENT, (payload) => {
+        if (!payload || typeof payload !== "object") return;
+        const response = payload as Partial<DetachHandshake> & { accepted?: unknown };
+        if (response.accepted === true
+          && response.phase === route.phase
+          && response.requestId === route.requestId
+          && response.messageId === route.messageId
+          && response.childIntercomTarget === route.childIntercomTarget
+          && response.senderId === route.senderId
+          && response.runtimeGeneration === route.runtimeGeneration) finish("acknowledged");
+      });
+      signal.addEventListener("abort", cancel, { once: true });
+      timeout = setTimeout(() => finish("timed-out"), this.ackTimeoutMs);
+      if (signal.aborted) {
+        cancel();
+        return;
+      }
+      this.pi.events?.emit(INTERCOM_DETACH_REQUEST_EVENT, route);
+    });
+  }
+
+  private resetForGeneration(generation: number): void {
+    this.generationCancellation.abort();
+    this.generationCancellation = new AbortController();
+    this.pending.clear();
+    this.delivered.clear();
+    this.generation = generation;
+  }
+}
+
+export async function handleForegroundInboundDelivery(input: {
+  handoff: ForegroundDetachHandoff;
+  from: SessionInfo;
+  message: Message;
+  generation: number;
+  surface: () => void;
+  isCurrent: () => boolean;
+  onUnclaimed: () => void;
+}): Promise<void> {
+  const disposition = await input.handoff.deliver(input);
+  if (disposition === "unclaimed" && input.isCurrent()) input.onUnclaimed();
+}