@bastani/atomic 0.9.5-alpha.1 → 0.9.5-alpha.10

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

@@ -1,75 +1,17 @@
 import net from "net";
 import { writeFileSync, unlinkSync, mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
 import { randomUUID } from "crypto";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
 import { writeMessage, createMessageReader } from "./framing.js";
-import { getBrokerSocketPath } from "./paths.js";
-import type { SessionInfo, Message, Attachment, BrokerMessage } from "../types.js";
+import { getBrokerPidPath, getBrokerSocketPath, getIntercomDirPath } from "./paths.js";
+import type { SessionInfo, BrokerMessage } from "../types.js";
+import { DeliveredMessageCache } from "./delivered-message-cache.js";
+import { handleBrokerSend, type BrokerConnectedSession } from "./send-handler.js";
 
-const INTERCOM_DIR = join(homedir(), CONFIG_DIR_NAME, "agent", "intercom");
+const INTERCOM_DIR = getIntercomDirPath();
 const SOCKET_PATH = getBrokerSocketPath();
-const PID_PATH = join(INTERCOM_DIR, "broker.pid");
+const PID_PATH = getBrokerPidPath();
 
-interface ConnectedSession {
-  socket: net.Socket;
-  info: SessionInfo;
-}
-
-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));
-}
+type ConnectedSession = BrokerConnectedSession;
 
 function isSessionRegistration(value: unknown): value is Omit<SessionInfo, "id"> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -99,6 +41,7 @@ class IntercomBroker {
   private sessions = new Map<string, ConnectedSession>();
   private server: net.Server;
   private shutdownTimer: NodeJS.Timeout | null = null;
+  private deliveredMessages = new DeliveredMessageCache();
 
   constructor() {
     mkdirSync(INTERCOM_DIR, { recursive: true });
@@ -220,52 +163,7 @@ class IntercomBroker {
       }
 
       case "send": {
-        const message = clientMessage.message;
-        const messageId = isMessage(message) ? message.id : "unknown";
-
-        if (typeof clientMessage.to !== "string" || !isMessage(message)) {
-          writeMessage(socket, {
-            type: "delivery_failed",
-            messageId,
-            reason: "Invalid message format",
-          });
-          break;
-        }
-
-        const targets = this.findSessions(clientMessage.to);
-        if (targets.length === 1) {
-          const fromSession = this.sessions.get(currentId);
-          if (!fromSession) {
-            writeMessage(socket, {
-              type: "delivery_failed",
-              messageId: message.id,
-              reason: "Sender session not found",
-            });
-            break;
-          }
-          writeMessage(targets[0].socket, {
-            type: "message",
-            from: fromSession.info,
-            message,
-          });
-          writeMessage(socket, { type: "delivered", messageId: message.id });
-          break;
-        }
-
-        if (targets.length > 1) {
-          writeMessage(socket, {
-            type: "delivery_failed",
-            messageId: message.id,
-            reason: `Multiple sessions named \"${clientMessage.to}\" are connected. Use the session ID instead.`,
-          });
-          break;
-        }
-
-        writeMessage(socket, {
-          type: "delivery_failed",
-          messageId: message.id,
-          reason: "Session not found",
-        });
+        handleBrokerSend(socket, clientMessage, currentId, this.sessions, this.deliveredMessages, writeMessage);
         break;
       }
 
@@ -301,15 +199,6 @@ class IntercomBroker {
     }
   }
 
-  private findSessions(nameOrId: string): ConnectedSession[] {
-    const byId = this.sessions.get(nameOrId);
-    if (byId) {
-      return [byId];
-    }
-
-    const lowerName = nameOrId.toLowerCase();
-    return Array.from(this.sessions.values()).filter(session => session.info.name?.toLowerCase() === lowerName);
-  }
 
   private broadcast(msg: BrokerMessage, exclude?: string): void {
     for (const [id, session] of this.sessions) {

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/paths.ts

@@ -1,6 +1,31 @@
-import { join } from "path";
 import { homedir } from "os";
-import { CONFIG_DIR_NAME } from "@bastani/atomic";
+import { join } from "path";
+
+function getHomeDir(): string {
+  if (process.platform === "win32") {
+    if (process.env.USERPROFILE) return process.env.USERPROFILE;
+    if (process.env.HOMEDRIVE && process.env.HOMEPATH) return `${process.env.HOMEDRIVE}${process.env.HOMEPATH}`;
+    if (process.env.HOME) return process.env.HOME;
+    return homedir();
+  }
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+
+function expandTildePath(path: string): string {
+  if (path === "~") return getHomeDir();
+  if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
+    return join(getHomeDir(), path.slice(2));
+  }
+  return path;
+}
+
+function getAgentDir(): string {
+  const atomicAgentDir = process.env.ATOMIC_CODING_AGENT_DIR;
+  if (atomicAgentDir) return expandTildePath(atomicAgentDir);
+  const piAgentDir = process.env.PI_CODING_AGENT_DIR;
+  if (piAgentDir) return expandTildePath(piAgentDir);
+  return join(getHomeDir(), ".atomic", "agent");
+}
 
 function sanitizePipeSegment(value: string): string {
   return value
@@ -9,13 +34,25 @@ function sanitizePipeSegment(value: string): string {
     .toLowerCase() || "default";
 }
 
+export function getIntercomDirPath(agentDir: string = getAgentDir()): string {
+  return join(agentDir, "intercom");
+}
+
+export function getBrokerPidPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker.pid");
+}
+
+export function getBrokerSpawnLockPath(agentDir: string = getAgentDir()): string {
+  return join(getIntercomDirPath(agentDir), "broker.spawn.lock");
+}
+
 export function getBrokerSocketPath(
   platform: NodeJS.Platform = process.platform,
-  homeDir: string = homedir(),
+  agentDir: string = getAgentDir(),
 ): string {
   if (platform === "win32") {
-    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(homeDir)}`;
+    return `\\\\.\\pipe\\pi-intercom-${sanitizePipeSegment(agentDir)}`;
   }
 
-  return join(homeDir, CONFIG_DIR_NAME, "agent", "intercom", "broker.sock");
+  return join(getIntercomDirPath(agentDir), "broker.sock");
 }

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,
+  });
+}