@securecoms/agent-bridge 0.3.2 → 0.5.0

package/dist/bridge-agent.js

@@ -1,831 +0,0 @@
-import { RestTransport, RestMlsBackend, SoftwareKeyCustody, MlsGroupKeyProvider, buildOutboundEnvelope, sendWithSelfHeal, KeyedInboxCipher, deriveMlsStoreKey, } from "@agentvault/connect-sdk-ts";
-import { SqliteMlsStateStore } from "@agentvault/connect-mls-store";
-import { decryptFile, encryptFile, computeFileDigest, base64ToBytes, bytesToBase64 } from "@agentvault/crypto";
-import { promises as fsp } from "node:fs";
-import { join, dirname } from "node:path";
-import { LatencyRecorder } from "./latency.js";
-import { shouldProcessRoomMessage } from "./coordination.js";
-import { TokenBucketFloor } from "./rate-limit.js";
-import { materializeAttachment, prepareAttachment } from "./attachments.js";
-/** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
-export const DEFAULT_MAX_BUFFER = 1000;
-/**
- * TTL for the Phase 2 channelMeta cache. `is_dm` is immutable for a channel_id,
- * so this exists only so a cached `name` (the room display name used by the
- * @mention filter) re-resolves after a channel rename. Lazy expiry on read.
- */
-export const CHANNEL_META_TTL_MS = 5 * 60_000;
-/**
- * TTL for the Phase 2 channel ROSTER cache (channel_id → identity_id → name /
- * is_agent), used to attribute decrypted messages by sender. Parallels
- * CHANNEL_META_TTL_MS: a member's display_name can change (rename) and the
- * member set can change, so a stale roster re-resolves on a later cycle. Lazy
- * expiry on read. Resolution is best-effort and fail-soft — a miss leaves
- * sender_name undefined and NEVER blocks or drops a message.
- */
-export const CHANNEL_ROSTER_TTL_MS = 5 * 60_000;
-const ZERO_TRACEPARENT = "00-" + "0".repeat(32) + "-" + "0".repeat(16) + "-01";
-export class ChannelPendingError extends Error {
-    channelId;
-    constructor(channelId) {
-        super(`channel ${channelId} is not yet admitted (awaiting Welcome)`);
-        this.channelId = channelId;
-        this.name = "ChannelPendingError";
-    }
-}
-export class RateLimitedError extends Error {
-    channelId;
-    retryAfterMs;
-    constructor(channelId, retryAfterMs) {
-        super(`channel ${channelId} send rate limit exceeded (retry in ${retryAfterMs}ms)`);
-        this.channelId = channelId;
-        this.retryAfterMs = retryAfterMs;
-        this.name = "RateLimitedError";
-    }
-}
-export class InvalidPathError extends Error {
-    filePath;
-    constructor(filePath, cause) {
-        super(`cannot read attachment file: ${filePath}`);
-        this.filePath = filePath;
-        this.name = "InvalidPathError";
-        if (cause !== undefined)
-            this.cause = cause;
-    }
-}
-export const BRIDGE_VERSION = "0.0.0"; // surfaced by /healthz; bump with package.json
-function hexToBytes(h) {
-    return new Uint8Array(Buffer.from(h, "hex"));
-}
-export class BridgeAgent {
-    cfg;
-    transport;
-    provider;
-    backend; // stored for peek-then-join in ingestOnce
-    custody;
-    fetchImpl;
-    joinState = new Map();
-    /**
-     * Phase 2: lazy channel-metadata cache (channel_id → { is_dm, name, at }) used
-     * by the multi-agent room @mention filter at ingest. Populated/refreshed from a
-     * SINGLE listChannels() per ingest cycle on a cache miss. A channel that cannot
-     * be resolved (network error, or not present in the listing) stays UNKNOWN → the
-     * filter fails OPEN.
-     *
-     * `is_dm` is immutable for a given channel_id (no misclassification risk), so the
-     * TTL exists only to keep `name` fresh after a channel rename — an entry older
-     * than CHANNEL_META_TTL_MS is treated as a miss and re-resolved on the next cycle.
-     */
-    channelMeta = new Map();
-    /**
-     * Phase 2 (sender attribution): per-channel roster cache
-     * (channel_id → identity_id → { name, is_agent }) resolved from the GET
-     * members endpoint. Same lazy/TTL/fail-soft discipline as channelMeta: an
-     * unresolved channel (network error, or no entry) leaves sender_name
-     * undefined and never blocks ingest. Resolved AT MOST ONCE per ingest cycle
-     * per channel on a miss.
-     */
-    channelRoster = new Map();
-    buffer = [];
-    maxBuffer;
-    /** Cumulative count of messages shed by the buffer cap (surfaced on health()/metrics()). */
-    droppedMessages = 0;
-    /**
-     * Cumulative count of ROOM messages dropped by the @mention filter (item 3 /
-     * ADR-0002 ethos). Surfaced on health()/metrics() so an agent correctly filtering
-     * most room traffic is distinguishable from an idle/wedged one.
-     */
-    filteredRoomMessages = 0;
-    /** Cumulative count of sends shed by the per-channel rate-limit floor (surfaced on health()/metrics()). */
-    rateLimitedSends = 0;
-    /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
-    welcomeRequestsSent = 0;
-    /**
-     * Track 5: cumulative count of artifact_share messages where download/decrypt/digest
-     * failed. Fail-soft — failures are acked (no redelivery), logged to stderr, and this
-     * counter is incremented. Surfaced on health()/metrics().
-     */
-    failedAttachments = 0;
-    /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
-    lastWelcomeRequest = new Map();
-    /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
-    static REQUEST_WELCOME_COOLDOWN_MS = 120_000;
-    rateFloor;
-    waiters = [];
-    pingHandle;
-    safetyTimer;
-    listeners = new Set();
-    startedAt = 0;
-    store;
-    latency;
-    /** Track 5: injectable blob download fn (default: fetch-based). */
-    downloadBlobImpl;
-    /** Track 5: injectable blob upload fn (default: fetch-based). */
-    uploadBlobImpl;
-    /** Track 5: directory where received attachments are saved. */
-    attachmentsDirImpl;
-    constructor(cfg, deps = {}) {
-        this.cfg = cfg;
-        const seed = hexToBytes(cfg.signingPrivateKey);
-        this.custody = SoftwareKeyCustody.fromPrivateKey("ed25519", seed);
-        this.transport =
-            deps.transport ??
-                new RestTransport({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey, connectIdentityId: cfg.identityId });
-        this.backend =
-            deps.backend ??
-                new RestMlsBackend({ baseUrl: cfg.apiBase, bearerToken: cfg.apiKey });
-        this.store = new SqliteMlsStateStore({
-            dbPath: cfg.storePath,
-            identityId: cfg.identityId,
-            cipherFor: () => new KeyedInboxCipher(deriveMlsStoreKey(seed)),
-        });
-        this.provider = new MlsGroupKeyProvider({
-            store: this.store,
-            backend: this.backend,
-            deviceId: cfg.deviceId,
-            identity: new TextEncoder().encode(cfg.identityId),
-            // ADR-0002: count + log agent-side decrypt failures. Without this hook the
-            // daemon was 100% blind to a wedged channel (it "looked idle"); the
-            // provider's errorStats() snapshot is surfaced on GET /v1/metrics below.
-            onDecryptError: (row, err) => {
-                const cid = row.connect_channel_id ?? "(unmapped)";
-                console.warn(`[bridge] decrypt error on channel ${cid} (queue ${row.queue_id}, epoch ${row.epoch}): ${err instanceof Error ? err.message : String(err)}`);
-            },
-        });
-        this.fetchImpl = deps.fetchImpl ?? fetch;
-        this.latency = deps.latency ?? new LatencyRecorder();
-        this.maxBuffer = deps.maxBuffer ?? DEFAULT_MAX_BUFFER;
-        this.rateFloor = new TokenBucketFloor({
-            capacity: cfg.rateLimitCapacity ?? 20,
-            refillPerMinute: cfg.rateLimitRefillPerMinute ?? 20,
-        });
-        // Track 5: attachment receive deps
-        const self = this;
-        this.downloadBlobImpl = deps.downloadBlob ?? async function (blobId) {
-            const url = `${cfg.apiBase}/api/v1/attachments/${encodeURIComponent(blobId)}?caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
-            const res = await self.fetchImpl(url, { headers: { authorization: `Bearer ${cfg.apiKey}` } });
-            if (!res.ok)
-                throw new Error(`download blob failed: ${res.status}`);
-            return new Uint8Array(await res.arrayBuffer());
-        };
-        this.uploadBlobImpl = deps.uploadBlob ?? async function (ciphertext, channelId) {
-            const url = `${cfg.apiBase}/api/v1/attachments?channel_id=${encodeURIComponent(channelId)}&caller_identity_id=${encodeURIComponent(cfg.identityId)}`;
-            const res = await self.fetchImpl(url, {
-                method: "POST",
-                headers: { "content-type": "application/octet-stream", authorization: `Bearer ${cfg.apiKey}` },
-                body: ciphertext,
-            });
-            if (!res.ok)
-                throw new Error(`upload blob failed: ${res.status}`);
-            const j = (await res.json());
-            return String(j.attachment_id);
-        };
-        this.attachmentsDirImpl = deps.attachmentsDir ?? join(dirname(cfg.storePath), "attachments");
-    }
-    /**
-     * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
-     *
-     * The buffer is uniformly ordered oldest→newest: ingestOnce() appends freshly
-     * decrypted inbound at the BACK (newest), and requeueFront() unshifts un-acked
-     * messages at the FRONT — those re-buffered messages were consumed earlier, so
-     * they are by definition OLDER than whatever already sits in the buffer. In
-     * every push path the newest messages therefore live at the back. To honour
-     * "the most-recent survive" we always shed from the FRONT, then record the
-     * shed so a silently-dropping daemon stays observable (item 3 / ADR-0002).
-     */
-    capBuffer() {
-        if (this.maxBuffer <= 0)
-            return;
-        const overflow = this.buffer.length - this.maxBuffer;
-        if (overflow > 0) {
-            this.buffer.splice(0, overflow); // drop the oldest, keep the newest maxBuffer
-            this.droppedMessages += overflow;
-        }
-    }
-    async start() {
-        this.startedAt = Date.now();
-        // B1 carry-forward: a restart loses the in-memory pending bundle, so always
-        // re-publish so the owner's cycle-A admission watcher (re)adds this leaf.
-        await this.provider.publishKeyPackage();
-        this.startReceivePump();
-    }
-    async reconcileJoin(channelId) {
-        if (this.joinState.get(channelId) === "JOINED")
-            return true;
-        try {
-            // Reconcile, not a plain join. joinAndReconcile = ensureSession(join)
-            // (consume the Welcome, or early-return if we already hold state) THEN
-            // drain pending commits so we converge on the group's CURRENT epoch.
-            // A plain ensureSession(join) lands at the Welcome's epoch and never
-            // advances: if the owner adds another member after we joined (a commit
-            // bumps the epoch), every later message arrives at an epoch we don't
-            // hold, fails to decrypt, and piles up unconsumed — the channel goes
-            // silent for the agent even though it is a member. Reconciling on
-            // (re)join applies that commit and unsticks it.
-            await this.provider.joinAndReconcile(channelId, this.cfg.enclaveId);
-            this.joinState.set(channelId, "JOINED");
-            return true;
-        }
-        catch {
-            // "no Welcome available yet" — the owner watcher hasn't added us. Stay
-            // PENDING; the pump MUST NOT die. Retried on the next cycle/use.
-            this.joinState.set(channelId, "PENDING");
-            return false;
-        }
-    }
-    /**
-     * Per-channel send-floor check. No-op on allow; throws RateLimitedError on a
-     * trip (incrementing the observable counter). `kind` namespaces the bucket so
-     * room and a2a traffic on the same channel are tracked separately.
-     */
-    enforceRateFloor(kind, channelId) {
-        const key = `${kind}:${channelId}`;
-        if (!this.rateFloor.tryConsume(key)) {
-            this.rateLimitedSends++;
-            throw new RateLimitedError(channelId, this.rateFloor.msUntilNextToken(key));
-        }
-    }
-    async send(channelId, text, messageId) {
-        const meta = this.freshMeta(channelId);
-        if (meta && !meta.is_dm)
-            this.enforceRateFloor("room", channelId);
-        const joined = await this.reconcileJoin(channelId);
-        if (!joined)
-            throw new ChannelPendingError(channelId);
-        const id = messageId ?? crypto.randomUUID();
-        const sendStart = performance.now();
-        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam. reconcileJoin only
-        // converges on the FIRST join (it early-returns once JOINED), so a bridge
-        // that fell behind because a peer committed would seal at a stale epoch and
-        // be rejected with an epoch-stale 400. sendWithSelfHeal reconciles per send
-        // (drain pending commits) and retries once on a stale 400.
-        // send.encrypt = MLS application-message seal (XChaCha20-Poly1305 over the
-        // group's current epoch secret). send.publish = relay to the backend over
-        // the persistent transport. send.total = the full agent-visible send cost.
-        await sendWithSelfHeal(this.provider, channelId, (epoch) => this.latency.time("send.encrypt", () => buildOutboundEnvelope({
-            custody: this.custody,
-            groupKey: this.provider,
-            messageId: id,
-            channelId,
-            enclaveId: this.cfg.enclaveId,
-            senderId: this.cfg.identityId,
-            senderType: "agent",
-            type: "text",
-            bodyPlaintext: JSON.stringify({ text }),
-            bindingId: "",
-            bindingVersion: "0.0.0",
-            agentSkillId: null,
-            epoch,
-            traceparent: ZERO_TRACEPARENT,
-            references: [],
-            stage5Outcome: "allow",
-            stage5Evaluators: [],
-        })), (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope)));
-        this.latency.record("send.total", performance.now() - sendStart);
-        return { message_id: id, status: "sent" };
-    }
-    async sendA2A(channelId, a2a, messageId) {
-        this.enforceRateFloor("a2a", channelId);
-        const joined = await this.reconcileJoin(channelId);
-        if (!joined)
-            throw new ChannelPendingError(channelId);
-        const id = messageId ?? crypto.randomUUID();
-        const sendStart = performance.now();
-        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam (mirrors send()).
-        await sendWithSelfHeal(this.provider, channelId, (epoch) => this.latency.time("send.encrypt", () => buildOutboundEnvelope({
-            custody: this.custody,
-            groupKey: this.provider,
-            messageId: id,
-            channelId,
-            enclaveId: this.cfg.enclaveId,
-            senderId: this.cfg.identityId,
-            senderType: "agent",
-            type: "a2a",
-            bodyPlaintext: JSON.stringify({ type: "a2a", a2a_version: a2a.a2a_version, kind: a2a.kind, object: a2a.object }),
-            bindingId: "",
-            bindingVersion: "0.0.0",
-            agentSkillId: null,
-            epoch,
-            traceparent: ZERO_TRACEPARENT,
-            references: [],
-            stage5Outcome: "allow",
-            stage5Evaluators: [],
-        })), (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope)));
-        this.latency.record("send.total", performance.now() - sendStart);
-        return { message_id: id, status: "sent" };
-    }
-    sendDeps() {
-        return {
-            uploadBlob: (ciphertext, channelId) => this.uploadBlobImpl(ciphertext, channelId),
-            encryptFile,
-            bytesToBase64,
-            readFile: (p) => fsp.readFile(p).then((b) => new Uint8Array(b)),
-        };
-    }
-    async sendAttachment(channelId, filePath, caption) {
-        this.enforceRateFloor("attachment", channelId);
-        const joined = await this.reconcileJoin(channelId);
-        if (!joined)
-            throw new ChannelPendingError(channelId);
-        // prepareAttachment reads, encrypts, and uploads the file — wrap readFile failures
-        // as InvalidPathError so the HTTP layer can return a clear 400 instead of 500.
-        let body;
-        try {
-            body = await prepareAttachment(filePath, caption, channelId, this.sendDeps());
-        }
-        catch (e) {
-            if (e.code === "ENOENT" || e.code === "EACCES" || e.code === "ENOTDIR" || e.code === "EISDIR") {
-                throw new InvalidPathError(filePath, e);
-            }
-            throw e;
-        }
-        const id = crypto.randomUUID();
-        const sendStart = performance.now();
-        await sendWithSelfHeal(this.provider, channelId, (epoch) => this.latency.time("send.encrypt", () => buildOutboundEnvelope({
-            custody: this.custody,
-            groupKey: this.provider,
-            messageId: id,
-            channelId,
-            enclaveId: this.cfg.enclaveId,
-            senderId: this.cfg.identityId,
-            senderType: "agent",
-            type: "artifact_share",
-            bodyPlaintext: JSON.stringify(body),
-            bindingId: "",
-            bindingVersion: "0.0.0",
-            agentSkillId: null,
-            epoch,
-            traceparent: ZERO_TRACEPARENT,
-            references: [],
-            stage5Outcome: "allow",
-            stage5Evaluators: [],
-        })), (envelope) => this.latency.time("send.publish", () => this.transport.publish(envelope)));
-        this.latency.record("send.total", performance.now() - sendStart);
-        return { message_id: id, status: "sent" };
-    }
-    async listChannels() {
-        const url = `${this.cfg.apiBase}/api/v1/enclaves/${this.cfg.enclaveId}/channels?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
-        const res = await this.fetchImpl(url, {
-            headers: { authorization: `Bearer ${this.cfg.apiKey}` },
-        });
-        if (!res.ok)
-            throw new Error(`list_channels failed: ${res.status}`);
-        const rows = (await res.json());
-        return rows.map((r) => ({
-            channel_id: r.channel_id,
-            name: r.name ?? null,
-            is_dm: r.is_dm,
-            joined: true,
-        }));
-    }
-    /** A live channelMeta entry, or undefined if missing OR expired past the TTL. */
-    freshMeta(channelId) {
-        const hit = this.channelMeta.get(channelId);
-        if (!hit)
-            return undefined;
-        // Lazy TTL expiry: a stale entry is treated as a miss so `name` re-resolves
-        // on the next cycle's single refresh. (is_dm is immutable; this is for name.)
-        if (Date.now() - hit.at >= CHANNEL_META_TTL_MS)
-            return undefined;
-        return { is_dm: hit.is_dm, name: hit.name };
-    }
-    /**
-     * One-shot, whole-listing refresh of channelMeta. Called AT MOST ONCE per
-     * ingest cycle (the caller guards with a cycle-local "refreshed" flag), so a
-     * burst of K unknown channels fires a single listChannels() instead of K. Any
-     * listChannels failure is swallowed (UNKNOWN → fail open) so ingest never
-     * blocks on the network.
-     */
-    async refreshChannelMeta() {
-        try {
-            const now = Date.now();
-            const channels = await this.listChannels();
-            for (const c of channels) {
-                this.channelMeta.set(c.channel_id, { is_dm: c.is_dm, name: c.name, at: now });
-            }
-        }
-        catch {
-            /* network error → leave cache as-is → unresolved channels fail open */
-        }
-    }
-    /** A live roster for a channel, or undefined if missing OR expired past the TTL. */
-    freshRoster(channelId) {
-        const hit = this.channelRoster.get(channelId);
-        if (!hit)
-            return undefined;
-        if (Date.now() - hit.at >= CHANNEL_ROSTER_TTL_MS)
-            return undefined;
-        return hit.members;
-    }
-    /**
-     * Resolve one channel's roster (members + display names + is-agent) from the
-     * GET members endpoint into the roster cache. Called AT MOST ONCE per ingest
-     * cycle per channel on a cache miss. Fail-soft: any error leaves the cache
-     * as-is so the affected senders stay unresolved (sender_name undefined) —
-     * attribution must NEVER block or drop a message.
-     */
-    async refreshChannelRoster(channelId) {
-        try {
-            const url = `${this.cfg.apiBase}/api/v1/channels/${encodeURIComponent(channelId)}/members?caller_identity_id=${encodeURIComponent(this.cfg.identityId)}`;
-            const res = await this.fetchImpl(url, {
-                headers: { authorization: `Bearer ${this.cfg.apiKey}` },
-            });
-            if (!res.ok)
-                return; // fail-soft: leave unresolved
-            const rows = (await res.json());
-            const members = new Map();
-            for (const r of rows) {
-                members.set(r.identity_id, { name: r.display_name, is_agent: r.is_agent });
-            }
-            this.channelRoster.set(channelId, { members, at: Date.now() });
-        }
-        catch {
-            /* network/parse error → leave cache as-is → senders fail soft (unresolved) */
-        }
-    }
-    async reportStatus(channelId, state, detail) {
-        const joined = await this.reconcileJoin(channelId);
-        if (!joined)
-            throw new ChannelPendingError(channelId);
-        // Self-heal-on-send (Phase 1.1) via the SHARED SDK seam (mirrors send()).
-        await sendWithSelfHeal(this.provider, channelId, (epoch) => buildOutboundEnvelope({
-            custody: this.custody,
-            groupKey: this.provider,
-            messageId: crypto.randomUUID(),
-            channelId,
-            enclaveId: this.cfg.enclaveId,
-            senderId: this.cfg.identityId,
-            senderType: "agent",
-            type: "system_event",
-            bodyPlaintext: JSON.stringify({
-                v: 1,
-                type: "agent_status",
-                state,
-                at: new Date().toISOString(),
-                ...(detail ? { detail } : {}),
-            }),
-            bindingId: "",
-            bindingVersion: "0.0.0",
-            agentSkillId: null,
-            epoch,
-            traceparent: ZERO_TRACEPARENT,
-            references: [],
-            stage5Outcome: "allow",
-            stage5Evaluators: [],
-        }), (envelope) => this.transport.publish(envelope));
-    }
-    startReceivePump() {
-        // Device-scoped WS ping stream (channel arg ignored by RestTransport).
-        const sub = this.transport.subscribeDeliveryPings("");
-        this.pingHandle = { close: sub.close };
-        void (async () => {
-            try {
-                for await (const _ping of sub.pings) {
-                    await this.ingestOnce();
-                }
-            }
-            catch {
-                /* stream closed — pump exits cleanly */
-            }
-        })();
-        // Safety floor: drain every 25s even if a ping is missed.
-        this.safetyTimer = setInterval(() => {
-            void this.ingestOnce();
-        }, 25_000);
-    }
-    async ingestOnce() {
-        // Phase 0: peek at pending delivery rows to find channel IDs. Reconcile
-        // join for each unjoined channel so that receiveOnce can load the MLS state
-        // and decrypt application messages. Without this, application decryption
-        // silently fails because the MLS group manager hasn't been initialised for
-        // the channel yet (the Welcome must be consumed via ensureSession first).
-        const cycleStart = performance.now();
-        try {
-            const rows = await this.latency.time("recv.pull", () => this.backend.pullDelivery(this.cfg.deviceId));
-            const channelIds = new Set();
-            for (const row of rows) {
-                if (row.connect_channel_id)
-                    channelIds.add(row.connect_channel_id);
-            }
-            for (const cid of channelIds) {
-                if (this.joinState.get(cid) !== "JOINED") {
-                    await this.reconcileJoin(cid);
-                }
-            }
-            // Self-heal: a channel we received delivery for but still have NO local MLS
-            // state for (after attempting a join) is diverged — ask the committer to
-            // re-Welcome us. Rate-limited per channel. (No string-matching; the
-            // persisted-state check is the signal.) Use hasPersistedChannelState (store
-            // + in-memory), NOT the in-memory-only hasChannelState: a healthy agent
-            // whose manager is merely cold this cycle (e.g. a stray-welcome-only cycle)
-            // has persisted state and must NOT trigger a spurious heal/epoch-churn.
-            for (const row of rows) {
-                const cid = row.connect_channel_id;
-                const gid = row.group_id;
-                if (!cid || !gid)
-                    continue;
-                if (await this.provider.hasPersistedChannelState(cid))
-                    continue;
-                const now = performance.now();
-                const last = this.lastWelcomeRequest.get(cid) ?? -Infinity;
-                if (now - last < BridgeAgent.REQUEST_WELCOME_COOLDOWN_MS)
-                    continue;
-                this.lastWelcomeRequest.set(cid, now);
-                try {
-                    await this.backend.requestWelcome(gid, this.cfg.deviceId);
-                    this.welcomeRequestsSent++;
-                }
-                catch { /* best-effort; retried next eligible cycle */ }
-            }
-        }
-        catch {
-            /* best-effort; receiveOnce proceeds regardless */
-        }
-        let entries;
-        try {
-            // recv.decrypt = pull + MLS open of any queued application messages
-            // (symmetric AEAD over the sender's epoch secret) for this device.
-            entries = await this.latency.time("recv.decrypt", () => this.provider.receiveOnce(this.cfg.deviceId));
-        }
-        catch {
-            return; // never let a receive error kill the pump
-        }
-        // Only record a cycle when there was actually something to process — empty
-        // poll ticks (the 25s safety drain) would otherwise dominate the metric.
-        if (!entries.length)
-            return;
-        // S-1: resolve channel metadata AT MOST ONCE per cycle. If any entry's
-        // channel is missing/expired in the cache, do a SINGLE listChannels() for the
-        // whole cycle and set metaRefreshed so no second call fires this tick. Any
-        // channel still unknown after that one refresh fails OPEN (buffers) with no
-        // further calls. ≤1 listChannels() per ingest cycle.
-        let metaRefreshed = false;
-        if (entries.some((m) => this.freshMeta(m.channelId) === undefined)) {
-            await this.refreshChannelMeta();
-            metaRefreshed = true;
-        }
-        // S-1 (roster): resolve each distinct channel's roster AT MOST ONCE per
-        // cycle on a miss, so a burst across K channels fires at most K member
-        // fetches (one per channel) and a single channel with N messages fires
-        // exactly one. Fail-soft inside refreshChannelRoster (a miss leaves
-        // sender_name undefined; never blocks ingest).
-        const rosterRefreshed = new Set();
-        for (const m of entries) {
-            if (rosterRefreshed.has(m.channelId))
-                continue;
-            rosterRefreshed.add(m.channelId);
-            if (this.freshRoster(m.channelId) === undefined) {
-                await this.refreshChannelRoster(m.channelId);
-            }
-        }
-        const acked = [];
-        for (const m of entries) {
-            try {
-                const parsed = JSON.parse(new TextDecoder().decode(m.plaintext));
-                // Handle non-text messages: artifact_share → materialize; others → skip+ack
-                if (parsed.type && parsed.type !== "text") {
-                    if (parsed.type === "artifact_share") {
-                        // Track 5: fail-soft — a download/decrypt/digest failure acks the message
-                        // (no redelivery), increments the counter, and logs but never throws.
-                        try {
-                            const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
-                            const senderType = m.envelope.sender_type;
-                            const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : undefined;
-                            const meta = await materializeAttachment(parsed, { attachmentsDir: this.attachmentsDirImpl, channelId: m.channelId, messageId: m.messageId }, {
-                                downloadBlob: this.downloadBlobImpl,
-                                decryptFile,
-                                computeFileDigest,
-                                base64ToBytes,
-                                mkdirp: (d) => fsp.mkdir(d, { recursive: true }).then(() => undefined),
-                                writeFile: (p, data) => fsp.writeFile(p, data),
-                            });
-                            this.buffer.push({
-                                channel_id: m.channelId,
-                                message_id: m.messageId,
-                                sender_id: m.envelope.sender_id,
-                                text: typeof parsed.text === "string"
-                                    ? parsed.text
-                                    : "",
-                                ts: m.receivedAt,
-                                sender_name: senderName,
-                                sender_is_agent: senderIsAgent,
-                                attachments: [meta],
-                            });
-                            this.capBuffer();
-                        }
-                        catch (e) {
-                            this.failedAttachments++;
-                            process.stderr.write(`[bridge] attachment failed on ${m.messageId}: ${e.message}\n`);
-                        }
-                    }
-                    // other non-text control/status messages: skip (still ack below)
-                    acked.push(m.queueId);
-                    continue;
-                }
-                if (typeof parsed.text === "string") {
-                    // Phase 2 — multi-agent room @mention filter. Classify the channel:
-                    //   DM     → always buffer (1:1, no filtering)
-                    //   Room   → buffer only if the @mention filter says this agent should
-                    //            see it; a message @mentioning a *different* agent is
-                    //            skipped (but still acked so it isn't redelivered forever)
-                    //   UNKNOWN→ fail OPEN: buffer (never silently drop the unclassifiable)
-                    // Metadata was resolved once at the top of the cycle (metaRefreshed).
-                    // freshMeta is a pure cache read here — no per-message network call.
-                    void metaRefreshed;
-                    const meta = this.freshMeta(m.channelId);
-                    // sender_type is the on-wire envelope field (see envelope-builder /
-                    // fake-backend). The @mention filter passes it through; Phase 2 also
-                    // surfaces it on BridgeMessage as sender_is_agent (same derivation,
-                    // not recomputed differently).
-                    const senderType = m.envelope.sender_type;
-                    const senderIsAgent = senderType === "agent" ? true : senderType === "human" ? false : undefined;
-                    let shouldBuffer = true;
-                    if (meta && meta.is_dm === false) {
-                        shouldBuffer = shouldProcessRoomMessage(parsed.text, this.cfg.agentName ?? this.cfg.identityId, this.cfg.identityId, { senderIsAgent, roomDisplayName: meta.name ?? undefined });
-                        if (!shouldBuffer)
-                            this.filteredRoomMessages++; // item 3: observable filtering
-                    }
-                    if (shouldBuffer) {
-                        // Phase 2: attribute the sender. Roster lookup is a pure cache
-                        // read here (resolved once per cycle above) — never a per-message
-                        // network call. Unresolved → sender_name undefined (fail-soft;
-                        // consumer falls back to sender_id). NEVER drop/delay on a miss.
-                        const senderName = this.freshRoster(m.channelId)?.get(m.envelope.sender_id)?.name;
-                        this.buffer.push({
-                            channel_id: m.channelId,
-                            message_id: m.messageId,
-                            sender_id: m.envelope.sender_id,
-                            text: parsed.text,
-                            ts: m.receivedAt,
-                            sender_name: senderName,
-                            sender_is_agent: senderIsAgent,
-                        });
-                        // Bound the buffer: a never-draining consumer must not OOM the daemon.
-                        // Newest was just appended at the back → shed the oldest from the front.
-                        this.capBuffer();
-                    }
-                    // Filtered-out room messages are still acked below (no redelivery loop).
-                }
-                acked.push(m.queueId);
-            }
-            catch {
-                // non-JSON / unparseable: ack to avoid redelivery loop
-                acked.push(m.queueId);
-            }
-        }
-        if (acked.length) {
-            try {
-                await this.latency.time("recv.ack", () => this.provider.ackDelivery(this.cfg.deviceId, acked));
-            }
-            catch {
-                /* retried next cycle */
-            }
-        }
-        // recv.cycle = the full receive-and-decrypt cost for a non-empty tick
-        // (pull + decrypt + parse + ack), i.e. the recipient half of the envelope.
-        this.latency.record("recv.cycle", performance.now() - cycleStart);
-        if (this.buffer.length) {
-            for (const l of this.listeners)
-                l();
-            const w = this.waiters.splice(0);
-            for (const r of w)
-                r();
-        }
-    }
-    async drain(channelId, waitSeconds) {
-        let got = this.takeBuffered(channelId);
-        if (got.length || waitSeconds <= 0)
-            return got;
-        const cap = Math.min(waitSeconds, 50) * 1000;
-        await new Promise((resolve) => {
-            // review FATAL-3: one-shot guard — timer and ingestOnce both call wake();
-            // the first wins, the second is a no-op, preventing a late timer from
-            // splicing an unrelated waiter under a concurrent drain.
-            let fired = false;
-            let timer;
-            const wake = () => {
-                if (fired)
-                    return;
-                fired = true;
-                clearTimeout(timer);
-                const i = this.waiters.indexOf(wake);
-                if (i >= 0)
-                    this.waiters.splice(i, 1);
-                resolve();
-            };
-            timer = setTimeout(wake, cap);
-            this.waiters.push(wake);
-        });
-        return this.takeBuffered(channelId);
-    }
-    /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
-    subscribe(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
-    }
-    /** Synchronous splice of buffered messages (all, or one channel). Shared by drain + SSE. */
-    takeBuffered(channelId) {
-        if (channelId === undefined)
-            return this.buffer.splice(0);
-        const keep = [];
-        const out = [];
-        for (const m of this.buffer)
-            (m.channel_id === channelId ? out : keep).push(m);
-        this.buffer.length = 0;
-        this.buffer.push(...keep);
-        return out;
-    }
-    /**
-     * Put messages back at the front (SSE/disconnect write-failure recovery).
-     *
-     * The re-buffered messages are older un-acked deliveries, so they go at the
-     * FRONT (oldest). A large un-acked backlog re-buffered on reconnect is exactly
-     * the OOM case Phase 1 item 4 targets, so this path is capped too. capBuffer()
-     * sheds from the front, preserving the newest maxBuffer messages across the
-     * combined [requeued-older..., existing-newer...] buffer.
-     */
-    requeueFront(msgs) {
-        if (msgs.length) {
-            this.buffer.unshift(...msgs);
-            this.capBuffer();
-        }
-    }
-    /**
-     * Poke subscribers + waiters to drain the buffer now. Used after a
-     * disconnect re-buffers un-acked messages so a still-connected consumer
-     * (e.g. a replacement WS) redelivers them without waiting for new inbound.
-     * Mirrors the notify tail of ingestOnce.
-     */
-    wakeListeners() {
-        for (const l of this.listeners)
-            l();
-        const w = this.waiters.splice(0);
-        for (const r of w)
-            r();
-    }
-    health() {
-        let joined = 0;
-        for (const s of this.joinState.values())
-            if (s === "JOINED")
-                joined++;
-        return {
-            status: "ok",
-            identity_id: this.cfg.identityId,
-            joined_channels: joined,
-            buffered: this.buffer.length,
-            dropped: this.droppedMessages,
-            filtered_room: this.filteredRoomMessages,
-            rate_limited: this.rateLimitedSends,
-            permanently_skipped: this.provider.permanentlySkippedCount(),
-            failed_attachments: this.failedAttachments,
-            uptime_s: this.startedAt ? Math.floor((Date.now() - this.startedAt) / 1000) : 0,
-            version: BRIDGE_VERSION,
-        };
-    }
-    /**
-     * Loopback observability snapshot served at GET /v1/metrics.
-     *
-     * `stages`: per-stage SecureComs-envelope latency percentiles (ms), measured
-     * locally and monotonically — send.encrypt / send.publish / send.total (the
-     * sender half) and recv.pull / recv.decrypt / recv.ack / recv.cycle (the
-     * recipient half). Excludes the agent's LLM time entirely.
-     *
-     * `errors` (ADR-0002): per-channel decrypt-error / stuck snapshot from the MLS
-     * provider, so a wedged channel is OBSERVABLE here instead of looking idle. A
-     * channel appears only once it has had a decrypt error; `stuck:true` means
-     * repeated failures with no intervening successful decrypt.
-     *
-     * `dropped` (Phase 1 item 4): cumulative count of inbound messages shed by the
-     * bounded-buffer cap. A daemon silently dropping messages under backpressure is
-     * exactly the blindness ADR-0002 eliminates, so the shed is surfaced here (and
-     * on health()) rather than swallowed.
-     *
-     * `filteredRoomMessages` (item 3 / ADR-0002 ethos): cumulative ROOM messages
-     * dropped by the @mention filter. A silently-filtered room message produces no
-     * other signal, so an agent correctly filtering 95% of room traffic would look
-     * identical to an idle/wedged one without this counter.
-     *
-     * `permanentlySkipped` (ADR-0002 ethos): cumulative count of inbound rows
-     * acked-and-dropped because they were provably past-epoch undecryptable
-     * (forward-secrecy secret gone), so a self-healed poison row is observable
-     * here instead of silently dropped.
-     */
-    metrics() {
-        return {
-            stages: this.latency.snapshot(),
-            errors: this.provider.errorStats(),
-            dropped: this.droppedMessages,
-            filteredRoomMessages: this.filteredRoomMessages,
-            rateLimitedSends: this.rateLimitedSends,
-            permanentlySkipped: this.provider.permanentlySkippedCount(),
-            welcomeRequestsSent: this.welcomeRequestsSent,
-            failedAttachments: this.failedAttachments,
-        };
-    }
-    async close() {
-        this.pingHandle?.close();
-        if (this.safetyTimer)
-            clearInterval(this.safetyTimer);
-        this.store.close(); // review SERIOUS-2: release the DatabaseSync handle/WAL
-    }
-}