@securecoms/agent-bridge 0.11.2 → 0.15.0

package/dist/latency.js

@@ -1,87 +0,0 @@
-// 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

@@ -1,56 +0,0 @@
-// 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

@@ -1,26 +0,0 @@
-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

@@ -1,60 +0,0 @@
-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

@@ -1,30 +0,0 @@
-/** 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

@@ -1,25 +0,0 @@
-/** 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/ws-server.js

@@ -1,254 +0,0 @@
-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"));
-}