@securecoms/agent-bridge 0.10.0 → 0.11.1

package/dist/latency.js

@@ -0,0 +1,87 @@
+// latency.ts — lightweight per-stage latency recorder for the agent-bridge.
+//
+// Captures the SecureComs MESSAGE-ENVELOPE cost (MLS encrypt, relay publish,
+// decrypt, receive cycle) so we can report real p50/p95/p99 SEPARATE from the
+// agent's LLM time. Deliberately dependency-free and bounded: each stage keeps
+// a fixed-size ring buffer of recent samples and percentiles are computed on
+// demand from a sorted copy. Off the hot path beyond a single array write.
+//
+// This is NOT a metrics-pipeline replacement; it is a self-contained, loopback
+// -exposed snapshot (`/v1/metrics`) for profiling + load tests. Per-stage
+// timings are monotonic (performance.now) and local — true cross-process
+// end-to-end (sender-publish → recipient-decrypt) needs clock-synced
+// correlation by message id and is a follow-up.
+const DEFAULT_CAPACITY = 1024;
+function round(n) {
+    // Two-decimal ms is plenty; avoids float noise in the JSON snapshot.
+    return Math.round(n * 100) / 100;
+}
+/** Nearest-rank percentile (1-indexed ceil) over an ascending-sorted array. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const rank = Math.ceil((p / 100) * sorted.length);
+    const idx = Math.min(Math.max(rank, 1), sorted.length) - 1;
+    return sorted[idx];
+}
+export class LatencyRecorder {
+    capacity;
+    // Per-stage ring buffer of recent samples (ms).
+    buffers = new Map();
+    // Write cursor per stage (for the ring buffer wrap).
+    cursors = new Map();
+    constructor(opts = {}) {
+        this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+    }
+    /** Record a single sample (ms) for a stage. O(1). */
+    record(stage, ms) {
+        let buf = this.buffers.get(stage);
+        if (!buf) {
+            buf = [];
+            this.buffers.set(stage, buf);
+            this.cursors.set(stage, 0);
+        }
+        if (buf.length < this.capacity) {
+            buf.push(ms);
+        }
+        else {
+            // Ring-buffer overwrite of the oldest slot.
+            const cur = this.cursors.get(stage) ?? 0;
+            buf[cur] = ms;
+            this.cursors.set(stage, (cur + 1) % this.capacity);
+        }
+    }
+    /**
+     * Time an async fn, record its elapsed wall time under `stage`, return its
+     * value. Records even when the fn throws (the failure still consumed time),
+     * then re-throws — so a thrown error never loses the timing sample.
+     */
+    async time(stage, fn) {
+        const start = performance.now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.record(stage, performance.now() - start);
+        }
+    }
+    /** Percentile snapshot per stage. Rounded to 2 decimals (ms). */
+    snapshot() {
+        const out = {};
+        for (const [stage, buf] of this.buffers) {
+            if (buf.length === 0)
+                continue;
+            const sorted = [...buf].sort((a, b) => a - b);
+            const sum = sorted.reduce((acc, n) => acc + n, 0);
+            out[stage] = {
+                count: sorted.length,
+                p50: round(percentile(sorted, 50)),
+                p95: round(percentile(sorted, 95)),
+                p99: round(percentile(sorted, 99)),
+                max: round(sorted[sorted.length - 1]),
+                mean: round(sum / sorted.length),
+            };
+        }
+        return out;
+    }
+}

package/dist/rate-limit.js

@@ -0,0 +1,56 @@
+// Per-channel token-bucket safety floor for the SecureComs agent bridge.
+//
+// A lazy-refill token bucket: tokens regenerate based on elapsed wall-clock time
+// at each read, so there is no timer/interval. The clock is injectable for
+// deterministic tests. State is per-key; an unseen key starts full.
+//
+// `capacity <= 0` disables the floor entirely (tryConsume always allows),
+// mirroring how `maxBuffer <= 0` disables the bridge's buffer cap.
+export class TokenBucketFloor {
+    capacity;
+    refillPerMs;
+    now;
+    buckets = new Map();
+    constructor(opts) {
+        this.capacity = opts.capacity;
+        this.refillPerMs = opts.refillPerMinute / 60_000;
+        this.now = opts.now ?? Date.now;
+    }
+    refill(key) {
+        const t = this.now();
+        let b = this.buckets.get(key);
+        if (!b) {
+            b = { tokens: this.capacity, lastRefill: t };
+            this.buckets.set(key, b);
+            return b;
+        }
+        const elapsed = t - b.lastRefill;
+        if (elapsed > 0) {
+            b.tokens = Math.min(this.capacity, b.tokens + elapsed * this.refillPerMs);
+            b.lastRefill = t;
+        }
+        return b;
+    }
+    /** Consume one token. Returns true if allowed, false if the bucket is empty. */
+    tryConsume(key) {
+        if (this.capacity <= 0)
+            return true; // disabled
+        const b = this.refill(key);
+        if (b.tokens >= 1) {
+            b.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /** Milliseconds until one token is available (0 if already available). */
+    msUntilNextToken(key) {
+        if (this.capacity <= 0)
+            return 0;
+        const b = this.refill(key);
+        if (b.tokens >= 1)
+            return 0;
+        if (this.refillPerMs <= 0)
+            return Infinity;
+        return Math.ceil((1 - b.tokens) / this.refillPerMs);
+    }
+}

package/dist/service/config.js

@@ -0,0 +1,26 @@
+import { basename, extname, isAbsolute, resolve } from "node:path";
+function slugify(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
+export function deriveServiceConfig(input) {
+    const stem = input.label ?? basename(input.credentialPath, extname(input.credentialPath));
+    const slug = slugify(stem);
+    const cred = isAbsolute(input.credentialPath) ? input.credentialPath : resolve(input.credentialPath);
+    const args = ["--credential", cred];
+    if (input.storePath)
+        args.push("--store", isAbsolute(input.storePath) ? input.storePath : resolve(input.storePath));
+    if (input.port != null)
+        args.push("--port", String(input.port));
+    return {
+        slug,
+        label: `com.securecoms.bridge.${slug}`,
+        unitName: `securecoms-bridge-${slug}`,
+        args,
+        execPath: input.execPath,
+        binScript: input.binScript,
+        uid: input.uid,
+        plistPath: `${input.home}/Library/LaunchAgents/com.securecoms.bridge.${slug}.plist`,
+        unitPath: `${input.home}/.config/systemd/user/securecoms-bridge-${slug}.service`,
+        logPath: `${input.home}/Library/Logs/securecoms-bridge-${slug}.log`,
+    };
+}

package/dist/service/install.js

@@ -0,0 +1,60 @@
+import { dirname } from "node:path";
+import { deriveServiceConfig } from "./config.js";
+import { renderLaunchdPlist } from "./launchd.js";
+import { renderSystemdUnit } from "./systemd.js";
+export class ServiceUnsupportedError extends Error {
+}
+function tokenHint(input) {
+    return `${dirname(input.credentialPath)}/bridge-token`;
+}
+function requireOk(r, what) {
+    if (r.status !== 0)
+        throw new Error(`${what} failed (exit ${r.status})${r.stderr ? `: ${r.stderr.trim()}` : ""}`);
+}
+export function installService(input, deps) {
+    const cfg = deriveServiceConfig(input);
+    if (deps.platform === "darwin") {
+        deps.mkdirp(dirname(cfg.plistPath));
+        deps.mkdirp(dirname(cfg.logPath));
+        deps.writeFile(cfg.plistPath, renderLaunchdPlist(cfg));
+        // Reload-safe: boot out any prior instance (ignore failure), then bootstrap + enable.
+        deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
+        // bootstrap actually loads the service — its failure is the real install failure,
+        // so surface it (don't let a broken install look silently successful).
+        requireOk(deps.run("launchctl", ["bootstrap", `gui/${cfg.uid}`, cfg.plistPath]), "launchctl bootstrap");
+        deps.run("launchctl", ["enable", `gui/${cfg.uid}/${cfg.label}`]);
+        // Start (or restart) the service now so install doesn't wait for the next login.
+        // Mirrors the linux `enable --now`; kickstart -k re-launches if an old instance lingers.
+        requireOk(deps.run("launchctl", ["kickstart", "-k", `gui/${cfg.uid}/${cfg.label}`]), "launchctl kickstart");
+        return { label: cfg.label, filePath: cfg.plistPath, logHint: cfg.logPath, tokenHint: tokenHint(input) };
+    }
+    if (deps.platform === "linux") {
+        deps.mkdirp(dirname(cfg.unitPath));
+        deps.writeFile(cfg.unitPath, renderSystemdUnit(cfg));
+        deps.run("systemctl", ["--user", "daemon-reload"]);
+        deps.run("loginctl", ["enable-linger", deps.user]);
+        // enable --now is the load-bearing command (enable at login + start now); surface failure.
+        requireOk(deps.run("systemctl", ["--user", "enable", "--now", cfg.unitName]), "systemctl --user enable --now");
+        return { label: cfg.unitName, filePath: cfg.unitPath, logHint: `journalctl --user -u ${cfg.unitName} -f`, tokenHint: tokenHint(input) };
+    }
+    throw new ServiceUnsupportedError(`Service install isn't supported on ${deps.platform} yet. Run the agent in a terminal, or use a process manager.`);
+}
+export function uninstallService(input, deps) {
+    const cfg = deriveServiceConfig(input);
+    if (deps.platform === "darwin") {
+        const existed = deps.fileExists(cfg.plistPath);
+        deps.run("launchctl", ["bootout", `gui/${cfg.uid}/${cfg.label}`]);
+        if (existed)
+            deps.removeFile(cfg.plistPath);
+        return { removed: existed, filePath: cfg.plistPath };
+    }
+    if (deps.platform === "linux") {
+        const existed = deps.fileExists(cfg.unitPath);
+        deps.run("systemctl", ["--user", "disable", "--now", cfg.unitName]);
+        if (existed)
+            deps.removeFile(cfg.unitPath);
+        deps.run("systemctl", ["--user", "daemon-reload"]);
+        return { removed: existed, filePath: cfg.unitPath };
+    }
+    throw new ServiceUnsupportedError(`Service uninstall isn't supported on ${deps.platform} yet.`);
+}

package/dist/service/launchd.js

@@ -0,0 +1,30 @@
+/** A deterministic launchd LaunchAgent plist. ProgramArguments re-invoke the
+ *  running bin in run mode; KeepAlive restarts on crash, RunAtLoad starts at login. */
+export function renderLaunchdPlist(cfg) {
+    const argv = [cfg.execPath, cfg.binScript, ...cfg.args];
+    const programArgs = argv.map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${cfg.label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${programArgs}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(cfg.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(cfg.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/service/systemd.js

@@ -0,0 +1,25 @@
+/** Quotes a single systemd ExecStart token if it contains whitespace or a
+ *  double-quote character.  Tokens that are already safe pass through unchanged
+ *  so the common no-space case stays readable in the unit file. */
+function sdQuote(s) {
+    return s.includes(" ") || s.includes('"') ? `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : s;
+}
+/** A systemd --user unit. ExecStart re-invokes the running bin in run mode;
+ *  Restart=always supervises crashes. WantedBy=default.target enables at login. */
+export function renderSystemdUnit(cfg) {
+    const execStart = [cfg.execPath, cfg.binScript, ...cfg.args].map(sdQuote).join(" ");
+    return `[Unit]
+Description=SecureComs agent bridge (${cfg.slug})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}

package/dist/sodium-ready.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Warm libsodium once per process, before any file-crypto call.
+ *
+ * ⛔ THE DISCARDED KEYPAIR IS THE READINESS GATE, NOT DEAD CODE. Do not
+ * delete it. `@agentvault/crypto` has no readiness contract on its entire
+ * synchronous surface: sixteen exported synchronous functions throw when
+ * libsodium's WASM heap is not yet initialised, with either
+ * `<member> is not a function` or
+ * `Cannot read properties of undefined (reading '_malloc')`.
+ * `generateEphemeralKeypair` is an ASYNC export that awaits `sodium.ready`
+ * internally, on the SAME module instance the synchronous exports use, so
+ * awaiting it is what makes those exports safe to call afterwards. The X25519
+ * keypair it returns is minted and thrown away: it is never stored, never
+ * published, and never used for anything.
+ *
+ * ⛔ DO NOT IMPORT `libsodium-wrappers-sumo` DIRECTLY HERE. That specifier is
+ * absent from esbuild.config.mjs's EXTERNAL list, so esbuild would bundle a
+ * SECOND libsodium instance. The await would then warm a heap that nothing
+ * reads, and this fix would look correct and do nothing.
+ *
+ * ⛔ MEMOIZE THE PROMISE, NOT A BOOLEAN. Measured: under
+ * `if (warmed) return; await ...; warmed = true;` two CONCURRENT callers both
+ * run the body. The bridge has two independent entry points (send and
+ * receive), so that concurrency is real. The promise form runs the body once.
+ *
+ * ⛔⛔ THE `catch` THAT CLEARS THE MEMO IS NOT REDUNDANT. DO NOT DELETE IT.
+ * Caching the promise fixes the double-warm race, but a bare
+ * `warming ??= ...` introduces a failure mode the boolean form did NOT have:
+ * if the FIRST warm-up REJECTS (WASM instantiation failure, OOM, a corrupt
+ * binary), `warming` holds a REJECTED promise for the life of the process, and
+ * every later prepareAttachment AND materializeAttachment then rejects at its
+ * first statement, forever. ⛔ ON THE RECEIVE SIDE THAT IS SILENT: the ingest
+ * pump's fail-soft catch acks the message, increments the failed-attachment
+ * counter and logs, so one transient failure becomes a PERMANENT,
+ * PROCESS-WIDE attachment outage that never surfaces as a crash. The boolean
+ * form would have retried. Clearing the memo on rejection restores that retry
+ * while keeping the single-warm guarantee on the success path.
+ * ⛔ It RETHROWS: the first caller must still see the real failure. This is
+ * not a swallow-and-proceed, which is the exact shape that caused the
+ * production incident this whole finding catalogues.
+ * Pinned by src/sodium-ready.retry.test.ts, both halves.
+ */
+export declare function ensureSodiumReady(): Promise<void>;

package/dist/vault.d.ts

@@ -0,0 +1,96 @@
+/** Vault-crypto integrity failures: digest mismatch, DEK-wrap AEAD failure
+ *  (bad/dropped nonce, wrong KEK, spliced ciphertext), or "no wrap for any
+ *  generation we hold". Distinguished from generic REST/plumbing errors so
+ *  the HTTP boundary can map it to a dedicated error code (errors.ts
+ *  `vault_integrity_failed`) instead of a bare 500. */
+export declare class VaultIntegrityError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+export interface VaultWriteDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    currentGeneration: number;
+    createNode: (body: any) => Promise<{
+        node_id: string;
+        presign_post: {
+            url: string;
+            fields: Record<string, string>;
+        } | null;
+    }>;
+    putBlob: (presign: {
+        url: string;
+        fields: Record<string, string>;
+    }, ciphertext: Uint8Array) => Promise<void>;
+    commitNode: (nodeId: string) => Promise<{
+        status: string;
+    }>;
+}
+export declare function vaultWriteImpl(args: {
+    enclaveId: string;
+    nodeId: string;
+    name: string;
+    bytes: Uint8Array;
+    deps: VaultWriteDeps;
+}): Promise<{
+    node_id: string;
+}>;
+export interface VaultReadDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    getNodeForDownload: (nodeId: string) => Promise<{
+        download_url: string;
+        wraps: {
+            kek_generation: number;
+            wrapped_dek_b64: string;
+        }[];
+        content_hash: string | null;
+    }>;
+    getBlob: (url: string) => Promise<Uint8Array>;
+}
+export declare function vaultReadImpl(args: {
+    enclaveId: string;
+    nodeId: string;
+    deps: VaultReadDeps;
+}): Promise<Uint8Array>;
+export interface VaultListRawNode {
+    node_id: string;
+    kind: "folder" | "file";
+    parent_id: string | null;
+    enc_name_b64: string;
+    name_kek_generation: number;
+    ciphertext_len: number | null;
+    content_hash: string | null;
+}
+export interface VaultListNode {
+    node_id: string;
+    kind: "folder" | "file";
+    parent_id: string | null;
+    name: string;
+    size_bytes: number | null;
+    content_hash: string | null;
+}
+export interface VaultListDeps {
+    exporterKekForGeneration: (gen: number) => Uint8Array;
+    listNodes: (parentId: string | null) => Promise<{
+        nodes: VaultListRawNode[];
+    }>;
+}
+export declare function vaultListImpl(args: {
+    enclaveId: string;
+    parentId: string | null;
+    deps: VaultListDeps;
+}): Promise<VaultListNode[]>;
+export interface VaultDeleteDeps {
+    deleteNode: (nodeId: string) => Promise<{
+        deleted: string;
+        bytes_freed: number;
+    }>;
+}
+/** No crypto on delete (the server drops an opaque row) — kept as a thin
+ *  pass-through so BridgeAgent.vaultDelete has the same deps-injection shape
+ *  as write/read/list for testability and symmetry. */
+export declare function vaultDeleteImpl(args: {
+    nodeId: string;
+    deps: VaultDeleteDeps;
+}): Promise<{
+    deleted: string;
+    bytes_freed: number;
+}>;

package/dist/ws-server.js

@@ -0,0 +1,254 @@
+import { WebSocketServer, WebSocket } from "ws";
+import { ChannelPendingError, RateLimitedError } from "./bridge-agent.js";
+import { tokenMatches, bearerFrom, originHostAllowed } from "./auth.js";
+import { wsErrorFrame } from "./errors.js";
+const PING_INTERVAL_MS = 30_000;
+/** Pull the local token from `?token=` first, then `Authorization: Bearer`. */
+function tokenFromUpgrade(req) {
+    try {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const q = url.searchParams.get("token");
+        if (q)
+            return q;
+    }
+    catch {
+        /* malformed URL — fall through to header */
+    }
+    return bearerFrom(req.headers.authorization);
+}
+function authedUpgrade(req, opts) {
+    if (!tokenMatches(tokenFromUpgrade(req), opts.token))
+        return false;
+    if (!originHostAllowed({ origin: req.headers.origin, host: req.headers.host }, opts.allowOrigins)) {
+        return false;
+    }
+    return true;
+}
+export function attachAgentWebSocket(server, agent, opts) {
+    const wss = new WebSocketServer({ server, path: "/v1/ws" });
+    // Server-side keepalive: ping every interval, drop sockets that miss a pong.
+    const keepalive = setInterval(() => {
+        for (const client of wss.clients) {
+            const sock = client;
+            if (sock.isAlive === false) {
+                sock.terminate();
+                continue;
+            }
+            sock.isAlive = false;
+            try {
+                sock.ping();
+            }
+            catch {
+                /* socket on its way out */
+            }
+        }
+    }, PING_INTERVAL_MS);
+    // Don't let the interval pin the process open.
+    if (typeof keepalive.unref === "function")
+        keepalive.unref();
+    // One agent per process: the live connection currently owning the inbound
+    // stream, carrying its cleanup so a replacement can drain it synchronously.
+    let current = null;
+    wss.on("connection", (sock, req) => {
+        // Auth is enforced here (not verifyClient) so we can close with a clean
+        // 1008 policy-violation code that the client observes, rather than a bare
+        // HTTP handshake rejection.
+        if (!authedUpgrade(req, opts)) {
+            sock.close(1008, "unauthorized");
+            return;
+        }
+        // Single consumer, newest wins (mirrors the SSE path). Close the prior
+        // socket AND run its cleanup synchronously, so its un-acked in-flight is
+        // re-buffered (in FIFO order) BEFORE this socket's initial flush — otherwise
+        // the replaced socket's async close could re-buffer those messages after
+        // this socket has already consumed newer ones, reordering delivery.
+        if (current && current.sock !== sock) {
+            const prior = current;
+            if (prior.sock.readyState === WebSocket.OPEN) {
+                prior.sock.close(1000, "replaced by newer connection");
+            }
+            prior.cleanup();
+        }
+        sock.isAlive = true;
+        sock.on("pong", () => {
+            sock.isAlive = true;
+        });
+        // Delivered-but-unacked messages, keyed by message_id in delivery order.
+        // Held until the agent acks; re-buffered on disconnect (at-least-once).
+        const inflight = new Map();
+        const flush = () => {
+            if (sock.readyState !== WebSocket.OPEN)
+                return;
+            const batch = agent.takeBuffered();
+            for (let i = 0; i < batch.length; i++) {
+                if (sock.readyState !== WebSocket.OPEN) {
+                    // Socket closing mid-flush — give the rest back to the buffer.
+                    agent.requeueFront(batch.slice(i));
+                    return;
+                }
+                const frame = { type: "message", ...batch[i] };
+                try {
+                    sock.send(JSON.stringify(frame));
+                    inflight.set(batch[i].message_id, batch[i]);
+                }
+                catch {
+                    agent.requeueFront(batch.slice(i));
+                    return;
+                }
+            }
+        };
+        const unsubscribe = agent.subscribe(flush);
+        let cleaned = false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            unsubscribe();
+            // Re-buffer anything delivered but never acked, in original order, so the
+            // next consumer redelivers it rather than the daemon dropping it. Poke
+            // listeners so a still-connected replacement consumer drains it now.
+            if (inflight.size) {
+                agent.requeueFront([...inflight.values()]);
+                inflight.clear();
+                agent.wakeListeners();
+            }
+            if (current?.sock === sock)
+                current = null;
+        };
+        current = { sock, cleanup };
+        sock.on("close", cleanup);
+        sock.on("error", cleanup);
+        sock.on("message", (data) => {
+            void handleInbound(sock, agent, data, inflight);
+        });
+        // Flush anything already buffered for an agent that connects after delivery.
+        flush();
+    });
+    return {
+        close() {
+            clearInterval(keepalive);
+            for (const client of wss.clients) {
+                try {
+                    client.terminate();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            wss.close();
+        },
+    };
+}
+function sendJson(sock, body) {
+    if (sock.readyState !== WebSocket.OPEN)
+        return;
+    try {
+        sock.send(JSON.stringify(body));
+    }
+    catch {
+        /* socket closing */
+    }
+}
+async function handleInbound(sock, agent, data, inflight) {
+    let msg;
+    try {
+        msg = JSON.parse(data.toString("utf8"));
+    }
+    catch {
+        sendJson(sock, wsErrorFrame("invalid_request"));
+        return;
+    }
+    if (typeof msg !== "object" || msg === null) {
+        sendJson(sock, wsErrorFrame("invalid_request"));
+        return;
+    }
+    const m = msg;
+    if (m.type === "ack") {
+        // Consume confirmation: drop the message from in-flight so it is not
+        // re-buffered on disconnect. Fire-and-forget (no reply frame).
+        if (typeof m.message_id !== "string" || !m.message_id) {
+            sendJson(sock, wsErrorFrame("invalid_request"));
+            return;
+        }
+        inflight.delete(m.message_id);
+        return;
+    }
+    if (m.type === "send") {
+        if (typeof m.channel_id !== "string" || !m.channel_id) {
+            sendJson(sock, wsErrorFrame("invalid_request"));
+            return;
+        }
+        if (m.a2a && typeof m.a2a === "object") {
+            const a = m.a2a;
+            if (typeof a.a2a_version !== "string" || !a.a2a_version || (a.kind !== "message" && a.kind !== "task" && a.kind !== "artifact") || typeof a.object !== "object" || a.object === null) {
+                sendJson(sock, wsErrorFrame("invalid_request"));
+                return;
+            }
+            try {
+                const r = await agent.sendA2A(m.channel_id, { a2a_version: a.a2a_version, kind: a.kind, object: a.object });
+                sendJson(sock, { type: "sent", message_id: r.message_id });
+            }
+            catch (e) {
+                if (e instanceof ChannelPendingError) {
+                    sendJson(sock, wsErrorFrame("channel_pending"));
+                }
+                else if (e instanceof RateLimitedError) {
+                    sendJson(sock, wsErrorFrame("rate_limited"));
+                }
+                else {
+                    sendJson(sock, wsErrorFrame("invalid_request"));
+                }
+            }
+            return;
+        }
+        if (typeof m.text !== "string" || !m.text) {
+            sendJson(sock, wsErrorFrame("invalid_request"));
+            return;
+        }
+        const idempotencyKey = typeof m.idempotency_key === "string" ? m.idempotency_key : undefined;
+        try {
+            const r = await agent.send(m.channel_id, m.text, idempotencyKey);
+            sendJson(sock, { type: "sent", message_id: r.message_id });
+        }
+        catch (e) {
+            if (e instanceof ChannelPendingError) {
+                sendJson(sock, wsErrorFrame("channel_pending"));
+            }
+            else if (e instanceof RateLimitedError) {
+                sendJson(sock, wsErrorFrame("rate_limited"));
+            }
+            else {
+                sendJson(sock, wsErrorFrame("invalid_request"));
+            }
+        }
+        return;
+    }
+    if (m.type === "status") {
+        const states = ["idle", "working", "stalled", "error"];
+        if (typeof m.channel_id !== "string" ||
+            !m.channel_id ||
+            typeof m.state !== "string" ||
+            !states.includes(m.state)) {
+            sendJson(sock, wsErrorFrame("invalid_request"));
+            return;
+        }
+        const detail = typeof m.detail === "string" ? m.detail : undefined;
+        try {
+            await agent.reportStatus(m.channel_id, m.state, detail);
+            sendJson(sock, { type: "ok" });
+        }
+        catch (e) {
+            if (e instanceof ChannelPendingError) {
+                sendJson(sock, wsErrorFrame("channel_pending"));
+            }
+            else if (e instanceof RateLimitedError) {
+                sendJson(sock, wsErrorFrame("rate_limited"));
+            }
+            else {
+                sendJson(sock, wsErrorFrame("invalid_request"));
+            }
+        }
+        return;
+    }
+    sendJson(sock, wsErrorFrame("invalid_request"));
+}