switchroom 0.19.48 → 0.20.1

package/telegram-plugin/gateway/buzz-mirror.ts

@@ -0,0 +1,494 @@
+/**
+ * Buzz co-channel — Phase 2b hub-side mirror module.
+ *
+ * This is the gateway-side half of "the part that actually sends". It sits
+ * strictly DOWNSTREAM of a successful Telegram delivery: `sendReply` calls
+ * `mirrorReplyDelivered(...)` only AFTER the Telegram copy has landed, and
+ * `executeEditMessage` calls `mirrorCorrection(...)` after a Telegram edit
+ * lands. Every Buzz publish is fire-and-forget — a failure or absence of the
+ * Buzz peer NEVER fails, delays, or retries the Telegram answer (the core
+ * invariant). There is no agent-facing Buzz-only send path: the ONLY way a
+ * Buzz event is ever emitted is as a mirror of an already-delivered Telegram
+ * message.
+ *
+ * Content signing lives in the sidecar (`src/buzz-gateway/publisher.ts`, the
+ * sole content-signer, S3). The hub only decides ROUTE + OWNER SAFETY and hands
+ * already-Telegram-scrubbed text (layer-1 redaction, via `normalizeOutboundBody`
+ * upstream) to the peer as an `outbound_to_buzz` request; the sidecar re-scrubs
+ * through `detectSecrets` (layer-2) before it ever reaches `finalizeEvent`.
+ *
+ * Dark by default: `getBuzzMirror()` returns null until `initBuzzMirror(...)`
+ * is called, which the gateway does ONLY when `channels.buzz.enabled === true`.
+ * With Buzz disabled the hook sites are `getBuzzMirror()?.…` — a byte-identical
+ * no-op on the hot path.
+ */
+
+import { randomUUID } from "crypto";
+import { join } from "path";
+import type { OutboundToBuzzMessage } from "./ipc-protocol.js";
+import {
+  resolveRoute,
+  isBuzzThreadedPublishSafe,
+  parseConfiguredMirrorMode,
+  type BuzzCoords,
+  type Channel,
+} from "./channel-route.js";
+import {
+  createCorrelationStore,
+  type CorrelationStore,
+} from "./buzz-mirror-correlation-store.js";
+
+export type BuzzPeerSender = (msg: OutboundToBuzzMessage) => boolean;
+
+export interface BuzzMirrorConfig {
+  /** Configured mode, ALREADY narrowed to both|off (S2) by the caller. */
+  mode: "both" | "off";
+  /** This gateway's agent name — stamped on every outbound_to_buzz. */
+  agentName: string;
+  /**
+   * The relay-minted group UUID a TELEGRAM-origin answer is mirrored to as a
+   * fresh top-level post (`channels.buzz.default_channel_id`). Empty string ⇒
+   * telegram-origin mirroring is disabled (no channel to post into); buzz-origin
+   * threaded replies still work (they carry their own channelId).
+   */
+  defaultChannelId: string;
+  /**
+   * Absolute path to the durable msg→Buzz correlation journal (#4222). When
+   * set, the `${chatId}:${messageId}` → published-event map is persisted and
+   * reloaded on construction, so an `edit_message` correction survives a gateway
+   * restart. Omit (dev/one-shot/tests) to keep the map in-memory only — same
+   * bound, no durability. See `buzz-mirror-correlation-store.ts`.
+   */
+  correlationJournalPath?: string;
+  /** Optional log sink (defaults to a no-op). */
+  log?: (msg: string) => void;
+}
+
+export interface MirrorReplyInput {
+  /** The answer text AFTER layer-1 Telegram scrub (normalizeOutboundBody). */
+  scrubbedText: string;
+  /** Resolved reply-owner turn's origin channel. */
+  ownerOriginChannel: Channel;
+  /** Owner turn's Buzz coordinates, when it originated on Buzz. */
+  ownerBuzzCoords?: BuzzCoords;
+  /** True IFF the reply positively echoed the owner turn's id (S1). */
+  ownerEchoed: boolean;
+  /** True IFF a live/recent turn of a DIFFERENT origin exists (S1). */
+  hasRecentDifferentOriginTurn: boolean;
+  /**
+   * `${chatId}:${messageId}` keys of the Telegram messages this answer was
+   * delivered as. Recorded so a later `edit_message` on any of them can find
+   * the published Buzz event to correct.
+   */
+  telegramMessageKeys: string[];
+  /**
+   * `${chatId}:${messageId}` of the Telegram message this outbound answer is
+   * itself a reply to (its Telegram `reply_to` antecedent), when it has one.
+   * Used ONLY on the telegram-origin path to thread the mirrored Buzz event
+   * under the antecedent's previously-published Buzz event (NIP-10 outbound
+   * continuity). When the antecedent was never mirrored (e.g. it is a user's
+   * inbound message, or it aged past the correlation bound) the lookup misses
+   * and the mirror stays a flat top-level post — no wrong/guessed tag. Absent
+   * for a non-reply answer. Ignored on the buzz-origin path (that thread is
+   * bound by `ownerBuzzCoords`, not a Telegram antecedent).
+   */
+  antecedentTelegramMessageKey?: string;
+  /**
+   * True IFF `antecedentTelegramMessageKey` is the quote-opt-in DEFAULT — i.e.
+   * the caller had no explicit/model-supplied `reply_to` and defaulted it to the
+   * latest INBOUND user message (#4301). That message is never in the
+   * correlation store, so its lookup ALWAYS misses; distinguishing it lets the
+   * mirror log the expected flat fallback quietly with a distinct reason instead
+   * of as an "outbound thread MISS", so a genuine eviction miss stays visible.
+   */
+  antecedentIsQuoteOptInDefault?: boolean;
+}
+
+export interface MirrorCorrectionInput {
+  /** `${chatId}:${messageId}` of the edited Telegram message. */
+  telegramMessageKey: string;
+  /** The edit text AFTER layer-1 Telegram scrub. */
+  scrubbedText: string;
+}
+
+/** F6 — coalesce a burst of edits into a single correction event. */
+export const CORRECTION_DEBOUNCE_MS = 30_000;
+
+/** Bound the in-memory correlation / message maps (FIFO eviction). */
+const MAX_TRACKED = 4096;
+
+interface PendingPublish {
+  channelId: string;
+  telegramMessageKeys: string[];
+  /**
+   * The NIP-10 thread root this in-flight event belongs to, when it threaded
+   * under a parent. Undefined for a fresh top-level post — in which case the
+   * event's OWN id (learned in `onPublishResult`) becomes the thread root. Stored
+   * so the correlation record carries the root a LATER reply's `root` marker
+   * needs.
+   */
+  threadRootId?: string;
+}
+
+class BuzzMirror {
+  private readonly cfg: BuzzMirrorConfig;
+  private readonly log: (msg: string) => void;
+  private sender: BuzzPeerSender | null = null;
+
+  /** correlationId → in-flight publish awaiting its buzz_publish_result. */
+  private readonly pending = new Map<string, PendingPublish>();
+  private readonly pendingOrder: string[] = [];
+
+  /**
+   * `${chatId}:${messageId}` → the published Buzz event it maps to. Durable
+   * (JSONL journal) when `correlationJournalPath` is configured, so a correction
+   * survives a gateway restart (#4222); the store enforces the same MAX_TRACKED
+   * FIFO bound in memory and on disk.
+   */
+  private readonly msgToBuzz: CorrelationStore;
+
+  /**
+   * Count of `mirrorCorrection` calls whose key was genuinely absent from the
+   * correlation store (never mirrored, or evicted past the bound) — surfaced for
+   * the loud-miss regression assertion, not just the log line.
+   */
+  private correctionMisses = 0;
+
+  /** `${chatId}:${messageId}` → live correction debounce timer. */
+  private readonly correctionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(cfg: BuzzMirrorConfig) {
+    this.cfg = cfg;
+    this.log = cfg.log ?? (() => {});
+    this.msgToBuzz = createCorrelationStore({
+      journalPath: cfg.correlationJournalPath,
+      capacity: MAX_TRACKED,
+      log: this.log,
+    });
+  }
+
+  /** Test/introspection: number of corrections that missed the correlation store. */
+  getCorrectionMisses(): number {
+    return this.correctionMisses;
+  }
+
+  /** Register the transport to the duplex Buzz peer (ipcServer.sendToBuzzPeer). */
+  attachSender(sender: BuzzPeerSender): void {
+    this.sender = sender;
+  }
+
+  /** Release the correlation journal fd and cancel any pending correction timers. */
+  close(): void {
+    for (const timer of this.correctionTimers.values()) clearTimeout(timer);
+    this.correctionTimers.clear();
+    this.msgToBuzz.close();
+  }
+
+  private evict<T>(map: Map<string, T>, order: string[]): void {
+    while (order.length > MAX_TRACKED) {
+      const k = order.shift();
+      if (k !== undefined) map.delete(k);
+    }
+  }
+
+  /**
+   * Mirror a just-delivered Telegram answer to Buzz, if the route calls for it
+   * and the owner binding is safe (S1). No-op when Buzz is not in the route.
+   * Never throws — a mirror failure must never disturb the Telegram answer.
+   */
+  mirrorReplyDelivered(input: MirrorReplyInput): void {
+    try {
+      // buzzEnabled is implied — this instance only exists when enabled.
+      const route = resolveRoute(input.ownerOriginChannel, this.cfg.mode, true);
+      const buzzInRoute =
+        route.primary === "buzz" || route.mirrors.includes("buzz");
+      if (!buzzInRoute) return;
+
+      let channelId: string;
+      let replyToEventId: string | undefined;
+      let threadRootId: string | undefined;
+
+      if (input.ownerOriginChannel === "buzz" && input.ownerBuzzCoords) {
+        // THREADED reply into an existing Buzz conversation — the ONLY path the
+        // S1 owner guard gates. Fail safe to Telegram-only on an ambiguous bind.
+        if (
+          !isBuzzThreadedPublishSafe({
+            ownerEchoed: input.ownerEchoed,
+            hasRecentDifferentOriginTurn: input.hasRecentDifferentOriginTurn,
+          })
+        ) {
+          this.log(
+            "buzz-mirror: S1 guard blocked a threaded publish on an ambiguous " +
+              "owner binding (un-echoed reply + a recent different-origin turn) " +
+              "— delivered Telegram-only",
+          );
+          return;
+        }
+        channelId = input.ownerBuzzCoords.channelId;
+        replyToEventId = input.ownerBuzzCoords.eventId;
+        threadRootId = input.ownerBuzzCoords.threadRoot;
+      } else {
+        // TELEGRAM-origin → post to the configured channel. Not an owner-bound
+        // thread, so the S1 guard does not apply (design §3.3).
+        if (!this.cfg.defaultChannelId) return; // no channel to post into
+        channelId = this.cfg.defaultChannelId;
+
+        // NIP-10 OUTBOUND thread continuity: if this answer is itself a reply to
+        // a Telegram message that was ALREADY mirrored to Buzz, thread the new
+        // event under that antecedent's published event — a `reply` marker for
+        // the immediate parent and a `root` marker for the thread root — so a
+        // Telegram-origin reply chain renders threaded on the Buzz desktop
+        // instead of flat. The antecedent→event resolution reuses the SAME
+        // durable msg→event correlation store (#4280) the correction path uses;
+        // no new lookup surface. A MISS (antecedent never mirrored — e.g. it is
+        // the user's own inbound message — or evicted past MAX_TRACKED) leaves
+        // the post flat rather than emitting a wrong/guessed tag.
+        if (input.antecedentTelegramMessageKey) {
+          const parent = this.msgToBuzz.get(input.antecedentTelegramMessageKey);
+          if (parent && parent.channelId === channelId) {
+            replyToEventId = parent.eventId; // immediate parent → NIP-10 `reply`
+            // Thread root → NIP-10 `root`. Fall back to the parent's own id when
+            // the parent has no recorded root (it was itself top-level, or was
+            // journaled before threadRoot was tracked): then parent IS the root.
+            threadRootId = parent.threadRoot ?? parent.eventId;
+          } else if (parent) {
+            // #4299 CROSS-CHANNEL GUARD: the antecedent WAS mirrored, but into a
+            // DIFFERENT Buzz channel than this event's target (e.g. it was
+            // recorded via a buzz-origin threaded reply whose channelId came from
+            // the inbound event's own `h`-tag). This event publishes into
+            // `defaultChannelId`; threading it under a foreign-channel parent
+            // would carry e-tags that point into another group. Mirror FLAT
+            // instead — same fallback as a MISS, no cross-group e-tag.
+            this.log(
+              `buzz-mirror: outbound thread CROSS-CHANNEL — antecedent ` +
+                `${input.antecedentTelegramMessageKey} was mirrored into channel ` +
+                `${parent.channelId} != target ${channelId}; mirroring flat ` +
+                `(no cross-group e-tag)`,
+            );
+          } else if (input.antecedentIsQuoteOptInDefault) {
+            // #4301: quote-opt-in defaulted `reply_to` to the latest INBOUND user
+            // message, which is never in the correlation store — so this "miss"
+            // is EXPECTED, not an eviction. Log it quietly with a distinct reason
+            // (no "MISS") so genuine eviction misses stay visible in the logs.
+            this.log(
+              `buzz-mirror: outbound thread default-quote — antecedent ` +
+                `${input.antecedentTelegramMessageKey} is the latest inbound user ` +
+                `message (never mirrored); mirroring flat (expected, not an eviction)`,
+            );
+          } else {
+            this.log(
+              `buzz-mirror: outbound thread MISS — no Buzz correlation for ` +
+                `Telegram antecedent ${input.antecedentTelegramMessageKey}; ` +
+                `mirroring flat (never mirrored, or evicted past the bound)`,
+            );
+          }
+        }
+      }
+
+      this.publish(
+        {
+          channelId,
+          replyToEventId,
+          threadRootId,
+          payload: { kind: "message", text: input.scrubbedText },
+        },
+        input.telegramMessageKeys,
+      );
+    } catch (err) {
+      this.log(`buzz-mirror: mirrorReplyDelivered threw (ignored): ${String(err)}`);
+    }
+  }
+
+  /**
+   * Debounced correction: an `edit_message` on a Telegram message that was
+   * mirrored to Buzz publishes a superseding `correction` event 30s after the
+   * last edit (F6 CORRECTION_DEBOUNCE_MS). No-op when the edited message was
+   * never mirrored (no Buzz event to correct). Never throws.
+   */
+  mirrorCorrection(input: MirrorCorrectionInput): void {
+    try {
+      const target = this.msgToBuzz.get(input.telegramMessageKey);
+      if (!target) {
+        // No mapping for this key — either it was genuinely never mirrored, or
+        // it aged out past MAX_TRACKED (memory AND journal). Either way the
+        // correction cannot land, so DON'T fail silently: emit a loud log and
+        // bump the miss counter so the gap is observable (#4222, audit "at
+        // minimum" ask). Pre-#4222 a restart also landed here (empty map) — the
+        // durable journal is what keeps that from being the common case.
+        this.correctionMisses++;
+        this.log(
+          `buzz-mirror: CORRECTION MISS — no Buzz correlation for Telegram ` +
+            `message ${input.telegramMessageKey}; the edit could NOT be mirrored ` +
+            `(never mirrored, or evicted past MAX_TRACKED=${MAX_TRACKED}). ` +
+            `Buzz copy may be stale. total_misses=${this.correctionMisses}`,
+        );
+        return;
+      }
+
+      const existing = this.correctionTimers.get(input.telegramMessageKey);
+      if (existing) clearTimeout(existing);
+
+      const timer = setTimeout(() => {
+        this.correctionTimers.delete(input.telegramMessageKey);
+        // Re-read: the mapping may have advanced (a later publish), but the
+        // targetEventId to supersede is the one current at fire time.
+        const t = this.msgToBuzz.get(input.telegramMessageKey);
+        if (!t) return;
+        this.publish(
+          {
+            channelId: t.channelId,
+            replyToEventId: t.eventId,
+            threadRootId: t.eventId,
+            payload: {
+              kind: "correction",
+              text: input.scrubbedText,
+              targetEventId: t.eventId,
+            },
+          },
+          [], // a correction is not itself re-correctable via a Telegram edit
+        );
+      }, CORRECTION_DEBOUNCE_MS);
+      if (typeof (timer as { unref?: () => void }).unref === "function") {
+        (timer as { unref: () => void }).unref();
+      }
+      this.correctionTimers.set(input.telegramMessageKey, timer);
+    } catch (err) {
+      this.log(`buzz-mirror: mirrorCorrection threw (ignored): ${String(err)}`);
+    }
+  }
+
+  /** Handle the sidecar's advisory publish outcome (buzz_publish_result). */
+  onPublishResult(msg: {
+    correlationId: string;
+    ok: boolean;
+    eventId?: string;
+    error?: string;
+  }): void {
+    const p = this.pending.get(msg.correlationId);
+    this.pending.delete(msg.correlationId);
+    if (!p) return;
+    if (!msg.ok || !msg.eventId) {
+      this.log(
+        `buzz-mirror: publish failed (correlationId=${msg.correlationId.slice(0, 8)}` +
+          `${msg.error ? ` error=${msg.error}` : ""}) — Telegram copy already delivered`,
+      );
+      return;
+    }
+    // Record the published event against each Telegram message it mirrored, so
+    // a later edit_message on any of them can target it for a correction AND a
+    // later reply whose antecedent is one of these messages can thread under it.
+    // The store persists (durable journal) + enforces the MAX_TRACKED FIFO bound.
+    //
+    // threadRoot: the root this event belongs to. If it threaded under a parent
+    // (`p.threadRootId` set) that parent's root IS this event's root; otherwise
+    // this is a fresh top-level post and its OWN id is the thread root.
+    const threadRoot = p.threadRootId ?? msg.eventId;
+    for (const key of p.telegramMessageKeys) {
+      this.msgToBuzz.set(key, { eventId: msg.eventId, channelId: p.channelId, threadRoot });
+    }
+  }
+
+  private publish(
+    fields: Omit<OutboundToBuzzMessage, "type" | "correlationId" | "agentName">,
+    telegramMessageKeys: string[],
+  ): void {
+    if (!this.sender) {
+      this.log("buzz-mirror: no Buzz peer connected — mirror dropped (Telegram copy delivered)");
+      return;
+    }
+    const correlationId = randomUUID();
+    const msg: OutboundToBuzzMessage = {
+      type: "outbound_to_buzz",
+      correlationId,
+      agentName: this.cfg.agentName,
+      ...fields,
+    };
+    const sent = this.sender(msg);
+    if (!sent) {
+      this.log("buzz-mirror: Buzz peer send returned false — mirror dropped (Telegram copy delivered)");
+      return;
+    }
+    this.pending.set(correlationId, {
+      channelId: fields.channelId,
+      telegramMessageKeys,
+      threadRootId: fields.threadRootId,
+    });
+    this.pendingOrder.push(correlationId);
+    this.evict(this.pending, this.pendingOrder);
+  }
+}
+
+let singleton: BuzzMirror | null = null;
+
+/**
+ * Initialize the hub mirror. Called by the gateway ONLY when
+ * `channels.buzz.enabled === true`. Idempotent-ish: a second call replaces the
+ * instance (used by tests). When never called, `getBuzzMirror()` stays null and
+ * every hook site is a no-op.
+ */
+export function initBuzzMirror(cfg: BuzzMirrorConfig): BuzzMirror {
+  singleton?.close(); // release any prior instance's journal fd + timers
+  singleton = new BuzzMirror(cfg);
+  return singleton;
+}
+
+export function getBuzzMirror(): BuzzMirror | null {
+  return singleton;
+}
+
+/**
+ * Resolve the durable msg→Buzz correlation journal path from env (#4222). Lives
+ * under the same `$TELEGRAM_STATE_DIR/buzz/` dir as the sidecar's dedup journal
+ * but at a DISTINCT filename — a collision on `journal.jsonl` would corrupt
+ * both. `BUZZ_MIRROR_CORRELATION_PATH` overrides. When `TELEGRAM_STATE_DIR` is
+ * unset (dev/one-shot), returns undefined so the store degrades to in-memory
+ * only rather than scattering a journal under the home dir.
+ */
+export function resolveCorrelationJournalPath(
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const override = env.BUZZ_MIRROR_CORRELATION_PATH?.trim();
+  if (override) return override;
+  const stateDir = env.TELEGRAM_STATE_DIR?.trim();
+  if (!stateDir) return undefined;
+  return join(stateDir, "buzz", "mirror-correlation.jsonl");
+}
+
+/**
+ * Boot the hub mirror from env at gateway startup — the single wiring seam the
+ * gateway calls. DARK BY DEFAULT and by construction: returns null (leaving
+ * `getBuzzMirror()` null, every hook site a no-op) unless BOTH hold —
+ *   (1) `BUZZ_ENABLED` is truthy, AND
+ *   (2) the S2-narrowed mode (`parseConfiguredMirrorMode`) is `both`;
+ *       a configured `origin`/`off` degrades to dark, never a half-live mirror.
+ * The Buzz env vars are projected at compose time from `channels.buzz`
+ * (src/agents/compose.ts), with BUZZ_ENABLED=1 gated on `enabled === true`;
+ * an enabled:false/absent block leaves them unset, so for those agents this
+ * is inert by construction. `sender` is the transport to the duplex peer
+ * (`ipcServer.sendToBuzzPeer`). Returns the booted instance for tests.
+ */
+export function maybeBootBuzzMirror(
+  sender: BuzzPeerSender,
+  env: Record<string, string | undefined> = process.env,
+): BuzzMirror | null {
+  if (env.BUZZ_ENABLED !== "1" && env.BUZZ_ENABLED !== "true") return null;
+  const mode = parseConfiguredMirrorMode(env.BUZZ_MIRROR);
+  if (mode !== "both") return null;
+  const bm = initBuzzMirror({
+    mode,
+    agentName: env.SWITCHROOM_AGENT_NAME?.trim() ?? "",
+    defaultChannelId: env.BUZZ_CHANNEL_IDS?.trim() ?? "",
+    correlationJournalPath: resolveCorrelationJournalPath(env),
+    log: (m) => process.stderr.write(`telegram gateway: buzz-mirror — ${m}\n`),
+  });
+  bm.attachSender(sender);
+  return bm;
+}
+
+/** Test-only: tear down the singleton so cases don't leak state into each other. */
+export function __resetBuzzMirrorForTests(): void {
+  singleton?.close();
+  singleton = null;
+}
+
+export type { BuzzMirror };

package/telegram-plugin/gateway/buzz-type-guards.ts

@@ -0,0 +1,34 @@
+/**
+ * Buzz co-channel — compile-time type-identity guards (2a MINOR-3).
+ *
+ * `gateway.ts` INLINES the `CurrentTurn.buzzCoords` shape
+ * (`{ channelId; eventId; threadRoot }`) rather than importing the canonical
+ * `BuzzCoords` from `channel-route.ts`, purely to hold gateway.ts at its
+ * zero-headroom line-ratchet (switchroom#2996). That inlining is a drift hazard:
+ * nothing structurally ties the two shapes together, so an edit to one could
+ * silently diverge from the other.
+ *
+ * This file closes that hazard with a strict, invariant type-equality assertion
+ * that makes `tsc --noEmit` (the lint gate) FAIL the moment the shapes differ.
+ * Both imports are `import type` — fully erased at runtime, so this introduces
+ * NO runtime dependency and NO module-load side effect (in particular it does
+ * NOT load gateway.ts, which binds a UDS listener at import under prod). The
+ * file is imported by nothing; it exists only to be type-checked.
+ */
+
+import type { CurrentTurn } from "./gateway.js";
+import type { BuzzCoords } from "./channel-route.js";
+
+/**
+ * Invariant type equality: `true` IFF `A` and `B` are mutually assignable with
+ * identical `readonly`/optional modifiers (the `(<T>() => …)` wrapper defeats
+ * the bivariant/structural leniency a plain `extends` pair would allow).
+ */
+type TypeEq<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+
+// `buzzCoords` is optional on CurrentTurn; compare its PRESENT shape to the
+// canonical BuzzCoords. If these ever drift, `TypeEq<…>` becomes `false` and the
+// `= true` initializer is a hard `tsc` error — the intended build break.
+const _buzzCoordsIdentity: TypeEq<NonNullable<CurrentTurn["buzzCoords"]>, BuzzCoords> = true;
+void _buzzCoordsIdentity;