agent-inbox 0.2.2 → 0.2.4

package/src/mail/types.ts

@@ -0,0 +1,221 @@
+/**
+ * Mail interop type contract.
+ *
+ * Defines the `MailTransport` interface and its envelope types — the backend-
+ * agnostic contract every mail backend (self-hosted SMTP, managed provider)
+ * must satisfy. See docs/MAIL-INTEROP-PLAN.md for the design rationale.
+ *
+ * Phase 1 lands the types only; no backend, gateway, or router wiring yet.
+ */
+
+// ---------------------------------------------------------------------------
+// Capabilities & lifecycle
+// ---------------------------------------------------------------------------
+
+/** What a backend can do. The gateway adapts to these instead of assuming. */
+export interface MailCapabilities {
+  /**
+   * How outbound mail leaves: direct to arbitrary public MX (self-hosted SMTP),
+   * via a configured smarthost relay, or via the backend's own API. Informational.
+   */
+  outbound: "mx" | "relay" | "api";
+  /** Backend signs DKIM itself (provider) or we must sign before handing off. */
+  signsDkim: boolean;
+  /** Backend verifies SPF/DKIM/DMARC on inbound and reports results. */
+  verifiesInboundAuth: boolean;
+  /** Inbound arrives via a long-lived listener (SMTP) or a push webhook. */
+  inbound: "listener" | "webhook" | "none";
+  /** Max message size the backend will accept, bytes. */
+  maxMessageBytes: number;
+}
+
+export type MailTransportState =
+  | "stopped"
+  | "starting"
+  | "ready"
+  | "degraded"
+  | "stopping";
+
+export interface MailHealth {
+  state: MailTransportState;
+  /** Human-readable detail for health endpoints / logs. */
+  detail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Addresses & attachments
+// ---------------------------------------------------------------------------
+
+export interface MailAddress {
+  /** RFC 5322 addr-spec, e.g. "bob@example.com". */
+  address: string;
+  /** Optional display name. */
+  name?: string;
+}
+
+export interface MailAttachment {
+  filename?: string;
+  contentType: string;
+  /** Content-ID for inline html parts. */
+  contentId?: string;
+  /** Opaque handle into an AttachmentStore — the envelope carries a ref, not bytes. */
+  contentRef: string;
+  sizeBytes: number;
+}
+
+// ---------------------------------------------------------------------------
+// Outbound
+// ---------------------------------------------------------------------------
+
+export interface OutboundMail {
+  /** Stable key for idempotent send. Derived from the inbox Message.id. */
+  idempotencyKey: string;
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  bcc?: MailAddress[];
+  subject?: string;
+  /** Rendered bodies. At least one of text/html should be present. */
+  text?: string;
+  html?: string;
+  /** RFC 5322 threading headers, already computed by the mapper. */
+  headers: {
+    messageId: string;
+    inReplyTo?: string;
+    references?: string[];
+  };
+  attachments?: MailAttachment[];
+  /** Opaque passthrough for backend-specific knobs (provider tags, etc.). */
+  backendHints?: Record<string, unknown>;
+}
+
+export type MailSendDisposition = "delivered" | "transient" | "permanent";
+
+/**
+ * Result of a send attempt. Backends collapse their native failure modes into
+ * these three dispositions so the retry/queue layer needs no backend knowledge.
+ */
+export interface MailSendResult {
+  disposition: MailSendDisposition;
+  /** Provider/SMTP id when delivered, for correlating DSNs/bounces. */
+  remoteMessageId?: string;
+  /** Numeric SMTP-style code when available (e.g. 250, 451, 550). */
+  code?: number;
+  /** Human-readable, for logs only — never parsed for control flow. */
+  detail?: string;
+  /** For transient failures: hint for next attempt (e.g. greylist retry-after). */
+  retryAfterMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Inbound
+// ---------------------------------------------------------------------------
+
+export interface InboundAuthResults {
+  spf: "pass" | "fail" | "softfail" | "neutral" | "none";
+  dkim: "pass" | "fail" | "none";
+  dmarc: "pass" | "fail" | "none";
+}
+
+/**
+ * Bounce/DSN classification, parsed from RFC 3464 delivery-status reports.
+ * Present when an inbound message is a bounce, so the gateway can correlate it
+ * to the failed outbound send instead of treating it as a fresh message.
+ */
+export interface InboundBounce {
+  /** "failed" (permanent), "delayed" (transient), "delivered" (positive DSN). */
+  action: "failed" | "delayed" | "delivered";
+  /** The address that bounced. */
+  recipient: string;
+  /** RFC 3463 status code, e.g. "5.1.1". */
+  status?: string;
+  /** Message-ID of the original outbound mail, when the DSN echoes it. */
+  originalMessageId?: string;
+  diagnostic?: string;
+}
+
+export interface InboundMail {
+  /** Peer-asserted SMTP envelope (MAIL FROM / RCPT TO), distinct from headers. */
+  envelopeFrom: string;
+  envelopeTo: string[];
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  subject?: string;
+  text?: string;
+  html?: string;
+  headers: {
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string[];
+    /** Everything else, lower-cased keys, for the mapper to mine. */
+    raw: Record<string, string | string[]>;
+  };
+  attachments?: MailAttachment[];
+  /** Auth verdict — present iff capabilities.verifiesInboundAuth. */
+  authResults?: InboundAuthResults;
+  /** Peer IP / hostname, for allow-listing and abuse control. */
+  remote?: { ip?: string; reverseDns?: string };
+  /** Set when this inbound mail is a bounce/DSN (see InboundBounce). */
+  bounce?: InboundBounce;
+  sizeBytes: number;
+  receivedAt: string; // ISO
+}
+
+// ---------------------------------------------------------------------------
+// The transport contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Ingress handler. The transport awaits this; resolution means "durably
+ * accepted" and only then is the peer MTA / webhook ACKed. A thrown handler
+ * means NACK so the sender retries — never a silent drop.
+ */
+export type InboundHandler = (mail: InboundMail) => Promise<void>;
+
+export interface MailTransport {
+  readonly capabilities: MailCapabilities;
+  readonly state: MailTransportState;
+
+  /**
+   * Idempotent. Resolves only when inbound is actually accepting (port bound /
+   * webhook registered) so callers don't ACK before we can receive.
+   */
+  start(): Promise<void>;
+
+  /** Graceful: stop accepting new inbound, finish in-flight, then release. */
+  stop(): Promise<void>;
+
+  /**
+   * Send one already-rendered outbound message.
+   * MUST be idempotent on `envelope.idempotencyKey`.
+   * MUST NOT throw for delivery failures — return a classified result instead.
+   * MAY throw only for programmer error (e.g. called while stopped).
+   */
+  send(envelope: OutboundMail): Promise<MailSendResult>;
+
+  /** Register the single ingress handler. See InboundHandler. */
+  onReceive(handler: InboundHandler): void;
+
+  /** Liveness for health endpoints and the degraded → ready transition. */
+  health(): Promise<MailHealth>;
+}
+
+// ---------------------------------------------------------------------------
+// Attachment storage (opaque contentRef backing store)
+// ---------------------------------------------------------------------------
+
+/**
+ * Swappable attachment byte store. `contentRef` values on MailAttachment are
+ * opaque handles produced by `put`. Mirrors the Storage two-impl pattern:
+ * SqliteAttachmentStore (default) and FsAttachmentStore (opt-in) land later.
+ */
+export interface AttachmentStore {
+  /** Returns a content-addressed ref (sha256-based). Dedups identical bytes. */
+  put(
+    bytes: Buffer,
+    meta: { contentType: string; filename?: string }
+  ): Promise<string>;
+  get(ref: string): Promise<Buffer>;
+  delete(ref: string): Promise<void>;
+}

package/src/push/notifier.ts

@@ -21,8 +21,19 @@ export interface NotifierConfig {
   inboxDir: string;
   /** Optional webhook URLs to POST new messages to */
   webhooks?: string[];
+  /** Soft cap on entries per per-agent inbox file. The file is allowed to
+   *  grow ~10% over this before being trimmed back, to amortize trim cost
+   *  across many appends. Defaults to 1000. Set to 0 to disable. */
+  maxEntriesPerInbox?: number;
+  /** Soft cap (in bytes) on per-agent inbox file size, with the same ~10%
+   *  amortization headroom as `maxEntriesPerInbox`. Defaults to 5 MiB. Set
+   *  to 0 to disable. */
+  maxBytesPerInbox?: number;
 }
 
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+
 export interface InboxFileEntry {
   messageId: string;
   from: string;
@@ -43,6 +54,11 @@ export interface InboxMessageEvent {
 
 export class PushNotifier {
   private webhooks: string[];
+  private maxEntries: number;
+  private maxBytes: number;
+  /** In-memory tracking so we can decide when to trim without stat/read. */
+  private entryCounts = new Map<string, number>();
+  private fileSizes = new Map<string, number>();
 
   constructor(
     private config: NotifierConfig,
@@ -50,6 +66,9 @@ export class PushNotifier {
     private events: EventEmitter
   ) {
     this.webhooks = config.webhooks ?? [];
+    this.maxEntries =
+      config.maxEntriesPerInbox ?? DEFAULT_MAX_ENTRIES;
+    this.maxBytes = config.maxBytesPerInbox ?? DEFAULT_MAX_BYTES;
 
     // Subscribe to message.created events
     events.on("message.created", (msg: Message) => this.onMessage(msg));
@@ -91,11 +110,86 @@ export class PushNotifier {
       importance: message.importance,
       timestamp: message.created_at,
     };
+    const line = JSON.stringify(entry) + "\n";
     try {
-      fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+      fs.appendFileSync(filePath, line);
     } catch {
-      // Best-effort write
+      return; // Best-effort write
+    }
+
+    if (this.maxEntries <= 0 && this.maxBytes <= 0) return;
+    this.bumpCounters(filePath, line.length);
+    this.maybeEnforceCap(filePath);
+  }
+
+  /** Update in-memory entry/size counters after an append. Lazy-inits from
+   *  the file when first seen so caps still apply across process restarts. */
+  private bumpCounters(filePath: string, addedBytes: number): void {
+    let count = this.entryCounts.get(filePath);
+    let size = this.fileSizes.get(filePath);
+    if (count === undefined || size === undefined) {
+      try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        count = raw.split("\n").filter((l) => l.length > 0).length;
+        size = raw.length;
+      } catch {
+        count = 1;
+        size = addedBytes;
+      }
+    } else {
+      count++;
+      size += addedBytes;
+    }
+    this.entryCounts.set(filePath, count);
+    this.fileSizes.set(filePath, size);
+  }
+
+  /** Trim the file when soft caps (~1.1× the configured limits) are exceeded.
+   *  This amortizes the cost of read+rewrite across many appends. */
+  private maybeEnforceCap(filePath: string): void {
+    const count = this.entryCounts.get(filePath) ?? 0;
+    const size = this.fileSizes.get(filePath) ?? 0;
+
+    const overEntries =
+      this.maxEntries > 0 && count > this.maxEntries * 1.1;
+    const overBytes =
+      this.maxBytes > 0 && size > this.maxBytes * 1.1;
+
+    if (!overEntries && !overBytes) return;
+
+    const result = this.trimFile(filePath);
+    this.entryCounts.set(filePath, result.lines);
+    this.fileSizes.set(filePath, result.bytes);
+  }
+
+  /** Trim the file to maxEntries / maxBytes. Returns counts of what's left. */
+  private trimFile(filePath: string): { lines: number; bytes: number } {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return { lines: 0, bytes: 0 };
+    }
+    let kept = raw.split("\n").filter((l) => l.length > 0);
+
+    if (this.maxEntries > 0 && kept.length > this.maxEntries) {
+      kept = kept.slice(kept.length - this.maxEntries);
+    }
+    let bytes = kept.reduce((acc, l) => acc + l.length + 1, 0);
+    if (this.maxBytes > 0) {
+      while (kept.length > 1 && bytes > this.maxBytes) {
+        bytes -= kept[0].length + 1;
+        kept.shift();
+      }
+    }
+
+    const out = kept.length ? kept.join("\n") + "\n" : "";
+    try {
+      fs.writeFileSync(filePath, out);
+    } catch {
+      // Best-effort
     }
+    return { lines: kept.length, bytes: out.length };
   }
 
   /** Read and format an agent's pending inbox as markdown (for hook injection) */
@@ -126,6 +220,8 @@ export class PushNotifier {
     // Clear the file
     try {
       fs.writeFileSync(filePath, "");
+      this.entryCounts.set(filePath, 0);
+      this.fileSizes.set(filePath, 0);
     } catch {
       // Best-effort clear
     }

package/src/router/destination.ts

@@ -0,0 +1,140 @@
+/**
+ * Destination classification.
+ *
+ * Email addresses are syntactically identical to federation addresses
+ * (`bob@example.com` vs `bob@system-2`), so before routing we must classify a
+ * recipient as one of: local agent, federation peer, or external mail.
+ *
+ * Classification is explicit-list driven — nothing is guessed from "looks like
+ * a domain". An unknown `@x` is a hard error rather than a silent misroute.
+ * Federation peers may declare their own domains, in which case they win over
+ * mail config for that domain. See docs/MAIL-INTEROP-PLAN.md §1.
+ *
+ * This layer sits *above* `parseAddress`, which is left untouched.
+ */
+
+import { parseAddress } from "../federation/address.js";
+import type { FederatedAddress } from "../types.js";
+
+export type Destination =
+  | { class: "local"; agentId: string }
+  | { class: "federation"; agentId: string; address: FederatedAddress }
+  | { class: "mail"; email: string };
+
+export interface DestinationPeer {
+  systemId: string;
+  /** Dotted addresses routed to this peer instead of being treated as mail. */
+  domains?: string[];
+}
+
+export interface DestinationContext {
+  /** Returns true if `id` is a known local agent. */
+  isLocalAgent: (id: string) => boolean;
+  /** Configured federation peers (system ids + optionally declared domains). */
+  federationPeers: DestinationPeer[];
+  /** Mail domains we recognize (identity.localDomains ∪ routableDomains). */
+  mailDomains: string[];
+}
+
+/** Thrown when a recipient matches neither a federation peer nor a mail domain. */
+export class UnknownDestinationError extends Error {
+  constructor(public readonly agentId: string) {
+    super(
+      `Cannot classify destination "${agentId}": its domain is not a configured ` +
+        `federation peer or mail domain. Declare it explicitly to route it.`
+    );
+    this.name = "UnknownDestinationError";
+  }
+}
+
+/**
+ * Classify a recipient address into local / federation / mail.
+ *
+ * Priority order (deterministic):
+ *   1. No `@`                                  → local
+ *   2. `@x` matches a peer systemId or domain  → federation
+ *   3. `@x` (or parent domain) in mailDomains  → mail
+ *   4. otherwise                               → throw UnknownDestinationError
+ *
+ * @throws UnknownDestinationError for rule-4 misses.
+ */
+export function classifyDestination(
+  agentId: string,
+  ctx: DestinationContext
+): Destination {
+  const atIdx = agentId.indexOf("@");
+
+  // Rule 1: no @ — local agent (no domain to disambiguate).
+  if (atIdx === -1) {
+    return { class: "local", agentId };
+  }
+
+  const addr = parseAddress(agentId);
+  const system = addr.system; // the part after @ (before any /scope)
+
+  // Defensive: parseAddress yielded no system (e.g. trailing-only @) — treat
+  // the whole string as a local agent id rather than guessing a domain.
+  if (!system) {
+    return { class: "local", agentId };
+  }
+
+  // Rule 2: federation peer by systemId or declared domain (wins over mail).
+  for (const peer of ctx.federationPeers) {
+    if (peer.systemId === system || domainMatches(system, peer.domains)) {
+      return { class: "federation", agentId, address: addr };
+    }
+  }
+
+  // Rule 3: configured mail domain (exact or parent-domain suffix match).
+  if (domainMatches(system, ctx.mailDomains)) {
+    return { class: "mail", email: stripScope(agentId) };
+  }
+
+  // Rule 4: explicit-list miss — never guess.
+  throw new UnknownDestinationError(agentId);
+}
+
+/**
+ * True if `domain` equals, or is a subdomain of, any entry in `candidates`.
+ * Matching is case-insensitive. `mail.example.com` matches a candidate of
+ * `example.com`; `notexample.com` does not match `example.com`.
+ */
+export function domainMatches(
+  domain: string,
+  candidates: string[] | undefined
+): boolean {
+  if (!candidates || candidates.length === 0) return false;
+  const d = domain.toLowerCase();
+  for (const c of candidates) {
+    const cand = c.toLowerCase();
+    if (d === cand || d.endsWith(`.${cand}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Drop a trailing `/scope` qualifier from an address, leaving a bare email.
+ * `bob@example.com/work` → `bob@example.com`.
+ */
+function stripScope(agentId: string): string {
+  const atIdx = agentId.indexOf("@");
+  if (atIdx === -1) return agentId;
+  const slashIdx = agentId.indexOf("/", atIdx);
+  return slashIdx === -1 ? agentId : agentId.slice(0, slashIdx);
+}
+
+/**
+ * Detect domains claimed by both a federation peer and mail config. Federation
+ * wins (see classifyDestination), but callers should surface this at startup
+ * via a `mail.config.conflict` warning. Returns the conflicting domains.
+ */
+export function findDomainConflicts(ctx: DestinationContext): string[] {
+  const mail = new Set(ctx.mailDomains.map((d) => d.toLowerCase()));
+  const conflicts: string[] = [];
+  for (const peer of ctx.federationPeers) {
+    for (const dom of peer.domains ?? []) {
+      if (mail.has(dom.toLowerCase())) conflicts.push(dom);
+    }
+  }
+  return conflicts;
+}

package/src/router/message-router.ts

@@ -11,6 +11,17 @@ import type { Storage } from "../storage/interface.js";
 import type { ConnectionManager } from "../federation/connection-manager.js";
 import { parseAddress, isRemoteAddress } from "../federation/address.js";
 
+/**
+ * Outbound mail sink. Implemented by MailGateway; kept as a local interface so
+ * the router does not depend on the mail module (avoids a cycle).
+ */
+export interface MailEgress {
+  /** True if this recipient's domain is one the mail gateway routes for. */
+  ownsRecipient(agentId: string): boolean;
+  /** Render and deliver the mail-class recipients of a message. */
+  send(message: Message): Promise<void>;
+}
+
 export interface SendOptions {
   from: string;
   to: string | string[] | { agent_id: string; kind?: RecipientKind }[];
@@ -26,6 +37,7 @@ export interface SendOptions {
 
 export class MessageRouter {
   private federation: ConnectionManager | null = null;
+  private mail: MailEgress | null = null;
 
   constructor(
     private storage: Storage,
@@ -40,6 +52,13 @@ export class MessageRouter {
     this.federation = federation;
   }
 
+  /**
+   * Attach a mail gateway for routing to external email recipients.
+   */
+  setMail(mail: MailEgress): void {
+    this.mail = mail;
+  }
+
   async routeMessage(opts: SendOptions): Promise<Message> {
     const recipients = this.resolveRecipients(opts.to);
     const content = normalizeContent(opts.payload);
@@ -72,8 +91,11 @@ export class MessageRouter {
       created_at: now,
     };
 
-    // Mark local recipients as delivered; route remote ones via federation
+    // Classify recipients: mail (external email) takes precedence over the
+    // federation interpretation of "agent@domain"; remaining remote recipients
+    // go to federation; everything else local.
     for (const r of message.recipients) {
+      if (this.mail?.ownsRecipient(r.agent_id)) continue; // mail — see below
       const addr = parseAddress(r.agent_id);
       if (!isRemoteAddress(addr) && this.isLocal(r.agent_id)) {
         r.delivered_at = now;
@@ -91,10 +113,25 @@ export class MessageRouter {
 
     this.events.emit("message.created", message);
 
-    // Route remote recipients via federation
+    // Route external mail recipients via the mail gateway.
+    if (this.mail) {
+      const hasMail = message.recipients.some((r) =>
+        this.mail!.ownsRecipient(r.agent_id)
+      );
+      if (hasMail) {
+        // Fire-and-forget; transient failures are queued inside the gateway.
+        this.mail.send(message).catch(() => {
+          // Mail delivery failures are handled by the gateway's retry queue
+        });
+      }
+    }
+
+    // Route remaining remote recipients via federation (excluding mail).
     if (this.federation) {
-      const hasRemote = message.recipients.some((r) =>
-        isRemoteAddress(parseAddress(r.agent_id))
+      const hasRemote = message.recipients.some(
+        (r) =>
+          isRemoteAddress(parseAddress(r.agent_id)) &&
+          !this.mail?.ownsRecipient(r.agent_id)
       );
       if (hasRemote) {
         // Fire-and-forget federation routing (results tracked via events)

package/src/storage/interface.ts

@@ -27,14 +27,36 @@ export interface Storage {
   // Messages
   getMessage(id: string): Message | undefined;
   putMessage(message: Message): Message;
+  /** Set the conversation_id on an existing message without rewriting the row. */
+  setMessageConversationId(messageId: string, conversationId: string): void;
   getInbox(agentId: string, opts?: InboxQuery): Message[];
   getThread(query: ThreadQuery): Message[];
   getSentMessages(agentId: string, limit?: number): Message[];
   searchMessages(query: string, scope?: string): Message[];
+  /** Delete messages older than `cutoff` (ISO timestamp). Returns the count removed. */
+  pruneMessagesOlderThan(cutoff: string): number;
+
+  // External-id mapping (mail dedup + bounce correlation)
+  /**
+   * Record that an external message id (e.g. an RFC 5322 Message-ID) maps to a
+   * stored inbox message. Idempotent: re-recording the same external id is a no-op.
+   */
+  recordExternalId(externalId: string, messageId: string): void;
+  /** Look up the inbox message id previously recorded for an external id. */
+  getMessageIdByExternalId(externalId: string): string | undefined;
+  /** Convenience: whether an external id has already been recorded. */
+  hasSeenExternalId(externalId: string): boolean;
 
   // Conversations
   getConversation(id: string): Conversation | undefined;
   putConversation(conversation: Conversation): Conversation;
+  /** Bump conversation updated_at without rewriting participants. */
+  touchConversation(conversationId: string, updatedAt: string): void;
+  /** Add a participant if not already present. No-op if already a participant. */
+  addParticipant(
+    conversationId: string,
+    participant: { agent_id: string; role?: string; joined_at: string }
+  ): void;
   listConversations(scope?: string): Conversation[];
 
   // Turns

package/src/storage/memory.ts

@@ -13,6 +13,7 @@ export class InMemoryStorage implements Storage {
   private conversations = new Map<string, Conversation>();
   private turns: Turn[] = [];
   private threads = new Map<string, Thread>();
+  private externalIds = new Map<string, string>();
 
   // --- Agents ---
 
@@ -45,6 +46,43 @@ export class InMemoryStorage implements Storage {
     return message;
   }
 
+  setMessageConversationId(messageId: string, conversationId: string): void {
+    const msg = this.messages.get(messageId);
+    if (msg) msg.conversation_id = conversationId;
+  }
+
+  recordExternalId(externalId: string, messageId: string): void {
+    if (!this.externalIds.has(externalId)) {
+      this.externalIds.set(externalId, messageId);
+    }
+  }
+
+  getMessageIdByExternalId(externalId: string): string | undefined {
+    return this.externalIds.get(externalId);
+  }
+
+  hasSeenExternalId(externalId: string): boolean {
+    return this.externalIds.has(externalId);
+  }
+
+  pruneMessagesOlderThan(cutoff: string): number {
+    let removed = 0;
+    const removedIds = new Set<string>();
+    for (const [id, msg] of this.messages) {
+      if (msg.created_at < cutoff) {
+        this.messages.delete(id);
+        removedIds.add(id);
+        removed++;
+      }
+    }
+    if (removedIds.size > 0) {
+      this.turns = this.turns.filter(
+        (t) => !t.source_message_id || !removedIds.has(t.source_message_id)
+      );
+    }
+    return removed;
+  }
+
   getInbox(agentId: string, opts?: InboxQuery): Message[] {
     const results: Message[] = [];
     for (const msg of this.messages.values()) {
@@ -108,6 +146,27 @@ export class InMemoryStorage implements Storage {
     return conversation;
   }
 
+  touchConversation(conversationId: string, updatedAt: string): void {
+    const conv = this.conversations.get(conversationId);
+    if (conv) conv.updated_at = updatedAt;
+  }
+
+  addParticipant(
+    conversationId: string,
+    participant: { agent_id: string; role?: string; joined_at: string }
+  ): void {
+    const conv = this.conversations.get(conversationId);
+    if (!conv) return;
+    if (conv.participants.some((p) => p.agent_id === participant.agent_id)) {
+      return;
+    }
+    conv.participants.push({
+      agent_id: participant.agent_id,
+      role: participant.role,
+      joined_at: participant.joined_at,
+    });
+  }
+
   listConversations(scope?: string): Conversation[] {
     const all = Array.from(this.conversations.values());
     if (!scope) return all;