@securecoms/agent-bridge 0.1.0

package/dist/latency.d.ts

@@ -0,0 +1,26 @@
+export interface StageStats {
+    count: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+    mean: number;
+}
+export declare class LatencyRecorder {
+    private readonly capacity;
+    private readonly buffers;
+    private readonly cursors;
+    constructor(opts?: {
+        capacity?: number;
+    });
+    /** Record a single sample (ms) for a stage. O(1). */
+    record(stage: string, ms: number): void;
+    /**
+     * 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.
+     */
+    time<T>(stage: string, fn: () => Promise<T>): Promise<T>;
+    /** Percentile snapshot per stage. Rounded to 2 decimals (ms). */
+    snapshot(): Record<string, StageStats>;
+}

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.d.ts

@@ -0,0 +1,17 @@
+export interface TokenBucketFloorOpts {
+    capacity: number;
+    refillPerMinute: number;
+    now?: () => number;
+}
+export declare class TokenBucketFloor {
+    private readonly capacity;
+    private readonly refillPerMs;
+    private readonly now;
+    private readonly buckets;
+    constructor(opts: TokenBucketFloorOpts);
+    private refill;
+    /** Consume one token. Returns true if allowed, false if the bucket is empty. */
+    tryConsume(key: string): boolean;
+    /** Milliseconds until one token is available (0 if already available). */
+    msUntilNextToken(key: string): number;
+}

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.d.ts

@@ -0,0 +1,23 @@
+export interface ServiceInput {
+    credentialPath: string;
+    storePath?: string;
+    port?: number;
+    label?: string;
+    execPath: string;
+    binScript: string;
+    home: string;
+    uid: number;
+}
+export interface ServiceConfig {
+    slug: string;
+    label: string;
+    unitName: string;
+    args: string[];
+    execPath: string;
+    binScript: string;
+    uid: number;
+    plistPath: string;
+    unitPath: string;
+    logPath: string;
+}
+export declare function deriveServiceConfig(input: ServiceInput): ServiceConfig;

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.d.ts

@@ -0,0 +1,28 @@
+import { type ServiceInput } from "./config.js";
+export declare class ServiceUnsupportedError extends Error {
+}
+export interface ServiceDeps {
+    platform: NodeJS.Platform;
+    run: (cmd: string, args: string[]) => {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+    writeFile: (path: string, data: string) => void;
+    removeFile: (path: string) => void;
+    mkdirp: (path: string) => void;
+    fileExists: (path: string) => boolean;
+    user: string;
+}
+export interface InstallResult {
+    label: string;
+    filePath: string;
+    logHint: string;
+    tokenHint: string;
+}
+export interface UninstallResult {
+    removed: boolean;
+    filePath: string;
+}
+export declare function installService(input: ServiceInput, deps: ServiceDeps): InstallResult;
+export declare function uninstallService(input: ServiceInput, deps: ServiceDeps): UninstallResult;

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.d.ts

@@ -0,0 +1,4 @@
+import type { ServiceConfig } from "./config.js";
+/** A deterministic launchd LaunchAgent plist. ProgramArguments re-invoke the
+ *  running bin in run mode; KeepAlive restarts on crash, RunAtLoad starts at login. */
+export declare function renderLaunchdPlist(cfg: ServiceConfig): string;

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/resolve-bin.d.ts

@@ -0,0 +1,35 @@
+export declare class GlobalInstallPermissionError extends Error {
+    constructor(message?: string);
+}
+export interface ResolveBinDeps {
+    run: (cmd: string, args: string[]) => {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+    fileExists: (path: string) => boolean;
+}
+export interface ResolveBinInput {
+    binScript: string;
+    packageName: string;
+}
+/** npx unpacks packages into a `_npx` cache dir that is garbage-collected; a
+ *  service definition must never bake a path under it. */
+export declare function isEphemeralPath(p: string): boolean;
+/**
+ * Returns an absolute, reboot-stable path to `dist/bin.js`. If we're already
+ * running from a durable location (dev `node dist/bin.js`, or a global install),
+ * use it as-is. If we're under an npx cache, install the *currently-running*
+ * package copy globally (content-pinned, offline, works pre-publish) and return
+ * the global path.
+ */
+/** True when two paths refer to the same file, resolving symlinks. Falls back
+ *  to string equality when a path can't be resolved (e.g. doesn't exist). */
+export declare function refersToSameFile(a: string, b: string, realpath: (p: string) => string): boolean;
+export declare function resolveStableBinScript(input: ResolveBinInput, deps: ResolveBinDeps): string;
+/** Reads this package's own name/version from the sibling package.json
+ *  (dist/bin.js -> ../package.json). */
+export declare function loadPackageMeta(importMetaUrl: string): {
+    name: string;
+    version: string;
+};

package/dist/service/systemd.d.ts

@@ -0,0 +1,4 @@
+import type { ServiceConfig } from "./config.js";
+/** A systemd --user unit. ExecStart re-invokes the running bin in run mode;
+ *  Restart=always supervises crashes. WantedBy=default.target enables at login. */
+export declare function renderSystemdUnit(cfg: ServiceConfig): string;

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/ws-server.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent-facing keepalive WebSocket (/v1/ws).
+ *
+ * Adds a single persistent bidirectional socket for the AGENT⇄DAEMON hop,
+ * modeled on AgentVault's keepalive WS (token in `?token=` query OR
+ * `Authorization: Bearer`). This replaces the curl/long-poll loop: the agent
+ * receives live inbound messages as JSON frames and sends/reports status over
+ * the same socket.
+ *
+ * Protocol (all frames are JSON text):
+ *   Daemon → agent:
+ *     { "type":"message", channel_id, message_id, sender_id, text, ts }  // inbound, decrypted
+ *     { "type":"sent", message_id }                                      // ack of a send
+ *     { "type":"ok" }                                                    // ack of a status report
+ *     { "type":"error", error, message, detail? }   // canonical codes (see errors.ts):
+ *                                                    // channel_pending | invalid_request
+ *   Agent → daemon:
+ *     { "type":"send", channel_id, text?, a2a?, idempotency_key? }   // exactly one of text | a2a
+ *     { "type":"status", channel_id, state, detail? }
+ *     { "type":"ack", message_id }   // confirms a delivered `message` was consumed
+ *
+ * Inbound delivery is at-least-once. A delivered `message` is held in-flight
+ * until the agent sends a matching `ack`; if the socket drops first, the frame
+ * is re-buffered and redelivered to the next consumer. The agent dedups by
+ * message_id (sends are already idempotent via idempotency_key).
+ *
+ * Single consumer: the daemon serves one agent per process. A new `/v1/ws`
+ * connection replaces the prior one (newest wins, mirroring the SSE path); the
+ * replaced socket's un-acked in-flight messages are re-buffered.
+ *
+ * Keepalive uses the ws library's server-side ping (the protocol-level ping
+ * frame, not an application message); dead sockets are reaped via pong tracking.
+ */
+import type { Server as HttpServer } from "node:http";
+import type { BridgeAgent } from "./bridge-agent.js";
+export interface AgentWebSocketOptions {
+    token: string;
+    allowOrigins: string[];
+}
+export declare function attachAgentWebSocket(server: HttpServer, agent: BridgeAgent, opts: AgentWebSocketOptions): {
+    close(): void;
+};