@securecoms/agent-bridge 0.1.0

package/dist/bridge-agent.d.ts

@@ -0,0 +1,259 @@
+import { MlsGroupKeyProvider } from "@agentvault/connect-sdk-ts";
+import type { BridgeConfig } from "./config.js";
+import { LatencyRecorder } from "./latency.js";
+export interface BridgeMessage {
+    channel_id: string;
+    message_id: string;
+    sender_id: string;
+    text: string;
+    ts: number;
+    /**
+     * Phase 2 (sender attribution): the sender's display name, resolved from the
+     * channel roster cache. Undefined when the roster hasn't resolved the
+     * sender_id (fetch failure, or a member not in the listing) — the consumer
+     * then falls back to sender_id. Never blocks delivery on resolution.
+     */
+    sender_name?: string;
+    /**
+     * Phase 2: true if the envelope's sender_type is "agent", false if "human",
+     * undefined if the envelope carried neither. Derived from the SAME field the
+     * @mention filter reads (not recomputed differently).
+     */
+    sender_is_agent?: boolean;
+}
+export interface BridgeAgentDeps {
+    transport?: any;
+    backend?: any;
+    fetchImpl?: typeof fetch;
+    /** Injectable so tests can assert recorded stages; defaults to a fresh one. */
+    latency?: LatencyRecorder;
+    /**
+     * Phase 1 item 4 (ADR-0002): hard cap on the in-memory inbound buffer. A
+     * consumer that never drains (agent offline, no /v1/events poller) must not
+     * let a sustained inbound backlog grow unbounded and OOM the daemon. When the
+     * buffer would exceed this many messages we shed the OLDEST and keep the most
+     * recent (a real-time messaging consumer cares about the newest). Default 1000.
+     */
+    maxBuffer?: number;
+}
+/** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
+export declare 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 declare const CHANNEL_META_TTL_MS: number;
+/**
+ * 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 declare const CHANNEL_ROSTER_TTL_MS: number;
+export declare class ChannelPendingError extends Error {
+    readonly channelId: string;
+    constructor(channelId: string);
+}
+export declare class RateLimitedError extends Error {
+    readonly channelId: string;
+    readonly retryAfterMs: number;
+    constructor(channelId: string, retryAfterMs: number);
+}
+export declare const BRIDGE_VERSION = "0.0.0";
+export declare class BridgeAgent {
+    private readonly cfg;
+    private readonly transport;
+    private readonly provider;
+    private readonly backend;
+    private readonly custody;
+    private readonly fetchImpl;
+    private readonly joinState;
+    /**
+     * 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.
+     */
+    private readonly channelMeta;
+    /**
+     * 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.
+     */
+    private readonly channelRoster;
+    private readonly buffer;
+    private readonly maxBuffer;
+    /** Cumulative count of messages shed by the buffer cap (surfaced on health()/metrics()). */
+    private droppedMessages;
+    /**
+     * 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.
+     */
+    private filteredRoomMessages;
+    /** Cumulative count of sends shed by the per-channel rate-limit floor (surfaced on health()/metrics()). */
+    private rateLimitedSends;
+    /** Cumulative count of requestWelcome calls fired for no-local-state deliveries (self-heal signal). */
+    private welcomeRequestsSent;
+    /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
+    private readonly lastWelcomeRequest;
+    /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
+    private static readonly REQUEST_WELCOME_COOLDOWN_MS;
+    private readonly rateFloor;
+    private readonly waiters;
+    private pingHandle?;
+    private safetyTimer?;
+    private readonly listeners;
+    private startedAt;
+    private readonly store;
+    private readonly latency;
+    constructor(cfg: BridgeConfig, deps?: BridgeAgentDeps);
+    /**
+     * 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).
+     */
+    private capBuffer;
+    start(): Promise<void>;
+    private reconcileJoin;
+    /**
+     * 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.
+     */
+    private enforceRateFloor;
+    send(channelId: string, text: string, messageId?: string): Promise<{
+        message_id: string;
+        status: "sent";
+    }>;
+    sendA2A(channelId: string, a2a: {
+        a2a_version: string;
+        kind: "message" | "task" | "artifact";
+        object: Record<string, unknown>;
+    }, messageId?: string): Promise<{
+        message_id: string;
+        status: "sent";
+    }>;
+    listChannels(): Promise<Array<{
+        channel_id: string;
+        name: string | null;
+        is_dm: boolean;
+        joined: boolean;
+    }>>;
+    /** A live channelMeta entry, or undefined if missing OR expired past the TTL. */
+    private freshMeta;
+    /**
+     * 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.
+     */
+    private refreshChannelMeta;
+    /** A live roster for a channel, or undefined if missing OR expired past the TTL. */
+    private freshRoster;
+    /**
+     * 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.
+     */
+    private refreshChannelRoster;
+    reportStatus(channelId: string, state: "idle" | "working" | "stalled" | "error", detail?: string): Promise<void>;
+    protected startReceivePump(): void;
+    private ingestOnce;
+    drain(channelId: string | undefined, waitSeconds: number): Promise<BridgeMessage[]>;
+    /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
+    subscribe(listener: () => void): () => void;
+    /** Synchronous splice of buffered messages (all, or one channel). Shared by drain + SSE. */
+    takeBuffered(channelId?: string): BridgeMessage[];
+    /**
+     * 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: BridgeMessage[]): void;
+    /**
+     * 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(): void;
+    health(): {
+        status: "ok";
+        identity_id: string;
+        joined_channels: number;
+        buffered: number;
+        /** Cumulative inbound messages shed by the buffer cap (0 unless a flood hit the bound). */
+        dropped: number;
+        /** Cumulative ROOM messages dropped by the @mention filter (correct filtering ≠ idle). */
+        filtered_room: number;
+        /** Cumulative sends shed by the per-channel rate-limit floor (correct backpressure ≠ idle). */
+        rate_limited: number;
+        /** Cumulative inbound rows acked-and-dropped because they were provably past-epoch undecryptable (forward-secrecy secret gone). */
+        permanently_skipped: number;
+        uptime_s: number;
+        version: string;
+    };
+    /**
+     * 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(): {
+        stages: ReturnType<LatencyRecorder["snapshot"]>;
+        errors: ReturnType<MlsGroupKeyProvider["errorStats"]>;
+        dropped: number;
+        filteredRoomMessages: number;
+        rateLimitedSends: number;
+        permanentlySkipped: number;
+        welcomeRequestsSent: number;
+    };
+    close(): Promise<void>;
+}