@securecoms/agent-bridge 0.5.0 → 0.6.0

package/dist/preflight-upgrade.d.cts

@@ -24,6 +24,8 @@ export interface UpgradeDeps {
     cleanup: (p: string) => void;
     resolveNewNode: () => string | null;
     reexec: (nodePath: string) => boolean;
+    activeVersion: string;
+    existingCompatibleNode: () => string | null;
 }
 export declare function guidedUpgrade(deps: UpgradeDeps): Promise<boolean>;
 export declare function resolveNewNodeFrom(probe: (p: string) => string | null, candidates?: string[]): string | null;

package/dist/preflight.cjs

@@ -21,6 +21,15 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/service/resolve-node.ts
+var REQUIRED_NODE_MAJOR;
+var init_resolve_node = __esm({
+  "src/service/resolve-node.ts"() {
+    "use strict";
+    REQUIRED_NODE_MAJOR = 24;
+  }
+});
+
 // src/preflight-upgrade.cts
 var preflight_upgrade_exports = {};
 __export(preflight_upgrade_exports, {
@@ -54,6 +63,13 @@ async function promptYesNo(question, deps) {
 async function guidedUpgrade(deps) {
   if (deps.platform !== "darwin") return false;
   try {
+    const existing = deps.existingCompatibleNode();
+    if (existing) {
+      deps.stderr(
+        "[bridge] Node " + deps.activeVersion + " is running, but a compatible Node (>= " + REQUIRED_NODE_MAJOR + ") is already installed at " + existing + " \u2014 it is shadowed earlier on your PATH. Continuing under it (no install needed).\n"
+      );
+      return deps.reexec(existing);
+    }
     const viaBrew = deps.hasBrew();
     const source = viaBrew ? "Homebrew (brew install node \u2014 user-space, no sudo)" : "the official installer from " + DIST_BASE + " (needs your admin password)";
     const ok = await promptYesNo(
@@ -94,7 +110,7 @@ function resolveNewNodeFrom(probe, candidates) {
   const list = candidates || NODE_CANDIDATES;
   for (let i = 0; i < list.length; i++) {
     const v = probe(list[i]);
-    if (v && Number(String(v).replace(/^v/, "").split(".")[0]) >= 24) return list[i];
+    if (v && Number(String(v).replace(/^v/, "").split(".")[0]) >= REQUIRED_NODE_MAJOR) return list[i];
   }
   return null;
 }
@@ -104,6 +120,13 @@ function realUpgradeDeps(originalArgv) {
   const os = require("os");
   const https = require("https");
   const readline = require("readline");
+  const probeNodeVersion = (p) => {
+    try {
+      return String(execFileSync(p, ["--version"], { encoding: "utf8" })).trim();
+    } catch {
+      return null;
+    }
+  };
   function fetch(url, redirects) {
     return new Promise((resolve, reject) => {
       https.get(url, (res) => {
@@ -162,13 +185,12 @@ function realUpgradeDeps(originalArgv) {
       } catch {
       }
     },
-    resolveNewNode: () => resolveNewNodeFrom((p) => {
-      try {
-        return String(execFileSync(p, ["--version"], { encoding: "utf8" })).trim();
-      } catch {
-        return null;
-      }
-    }),
+    resolveNewNode: () => resolveNewNodeFrom(probeNodeVersion),
+    activeVersion: process.versions.node,
+    // Same candidate probe as resolveNewNode: is a Node >= REQUIRED_NODE_MAJOR
+    // already installed at a stable location (shadowed on PATH)? If so, the
+    // pre-check re-execs under it and never prompts to install.
+    existingCompatibleNode: () => resolveNewNodeFrom(probeNodeVersion),
     reexec: (nodePath) => {
       const child = spawnSync(nodePath, originalArgv.slice(1), { stdio: "inherit" });
       process.exit(child.status !== null && child.status !== void 0 ? child.status : child.signal ? 130 : 1);
@@ -179,6 +201,7 @@ var DIST_BASE, NODE_CANDIDATES;
 var init_preflight_upgrade = __esm({
   "src/preflight-upgrade.cts"() {
     "use strict";
+    init_resolve_node();
     DIST_BASE = "https://nodejs.org/dist/latest-v24.x";
     NODE_CANDIDATES = [
       "/usr/local/bin/node",

package/dist/service/connection-file.d.ts

@@ -0,0 +1,33 @@
+export type ConnectionFileV1 = {
+    schema: "securecoms.connection/1";
+    identity_id: string;
+    bridge_url: string;
+    token_file: string;
+    instance_id: string;
+    slug: string;
+    label: string;
+    written_at: string;
+};
+export interface FsDeps {
+    mkdir: (p: string, mode: number) => void;
+    chmod: (p: string, mode: number) => void;
+    writeFile: (p: string, data: string, mode: number) => void;
+    rename: (a: string, b: string) => void;
+    readFile: (p: string) => string;
+    unlink: (p: string) => void;
+}
+export declare function securecomsDir(home: string): string;
+export declare function connectionsDir(home: string): string;
+export declare function connectionFilePath(home: string, identityId: string): string;
+export declare function newInstanceId(): string;
+export declare function buildConnectionFile(args: {
+    identityId: string;
+    port: number;
+    tokenFile: string;
+    slug?: string;
+    label?: string;
+    instanceId: string;
+    now: string;
+}): ConnectionFileV1;
+export declare function writeConnectionFile(home: string, doc: ConnectionFileV1, deps?: FsDeps): void;
+export declare function removeConnectionFileIfOwned(home: string, identityId: string, instanceId: string, deps?: FsDeps): void;

package/dist/service/fleet.d.ts

@@ -0,0 +1,27 @@
+export declare function parseArgFromDef(def: string, flag: string): string | null;
+export declare function parseExecPathFromDef(def: string): string | null;
+export interface FleetDeps {
+    home: string;
+    listDir: (p: string) => string[];
+    readFile: (p: string) => string;
+}
+export interface AgentFleetEntry {
+    identityId: string;
+    deviceId: string;
+    slug: string;
+    label: string;
+    environment: "prod" | "preprod" | "unknown";
+    interpreterStable: boolean;
+    port: number | null;
+    interpreterPath: string | null;
+    credentialDir: string | null;
+}
+export declare function surfaceableProjection(e: AgentFleetEntry): {
+    identityId: string;
+    deviceId: string;
+    slug: string;
+    label: string;
+    environment: "unknown" | "prod" | "preprod";
+    interpreterStable: boolean;
+};
+export declare function readFleet(deps: FleetDeps): AgentFleetEntry[];

package/dist/service/install-prep.d.ts

@@ -42,6 +42,7 @@ export declare function harnessSnippet(args: {
     port: number;
     tokenFilePath: string;
     harness: string;
+    identityId: string;
 }): string;
 export interface OrchestrateInstallCtx {
     credentialAbsPath: string;

package/dist/service/resolve-node.d.ts

@@ -0,0 +1,13 @@
+export declare const REQUIRED_NODE_MAJOR = 24;
+export declare function isVersionEmbeddedNodePath(p: string): boolean;
+export interface ResolveNodeDeps {
+    realpath: (p: string) => string;
+    fileExists: (p: string) => boolean;
+    nodeMajorOf: (p: string) => number | null;
+    arch: () => string;
+    archOf: (p: string) => string | null;
+}
+export declare function resolveStableNodePath(runningExecPath: string, deps: ResolveNodeDeps): {
+    path: string;
+    stable: boolean;
+};

package/dist/service/status.d.ts

@@ -0,0 +1,25 @@
+import type { AgentFleetEntry } from "./fleet.js";
+export interface StatusDeps {
+    readFleet: () => AgentFleetEntry[];
+    probeConnect: (port: number) => boolean;
+    getHealth: (port: number) => {
+        agent_sessions?: number;
+        evictions?: number;
+    } | null;
+}
+export interface AgentStatusRow {
+    slug: string;
+    environment: string;
+    port: number | null;
+    bridge: "up" | "down";
+    harness: "attached" | "no brain" | "-";
+    interpreter: "stable" | "REBOOT-RISK";
+    /** Task 3 (audit M3): cumulative newest-wins WS evictions for this identity,
+     *  read straight off the daemon's health(). Nonzero/climbing while harness
+     *  stays "attached" means two connectors are flapping the same identity
+     *  (split-brain), not one stable harness — 0 when the bridge is down or
+     *  the daemon predates this counter. */
+    evictions: number;
+}
+export declare function readFleetStatus(deps: StatusDeps): AgentStatusRow[];
+export declare function renderStatusTable(rows: AgentStatusRow[]): string;

package/dist/service/wire.d.ts

@@ -0,0 +1,76 @@
+import type { AgentFleetEntry } from "./fleet.js";
+export type Harness = "openclaw" | "hermes";
+export interface WireDeps {
+    home: string;
+    argv: string[];
+    readFleet: () => AgentFleetEntry[];
+    copyConnector: (srcDir: string, dstDir: string) => void;
+    writeBinding: (dstDir: string, identityId: string) => void;
+    removeBinding: (dstDir: string) => void;
+    getHealth: (port: number) => {
+        agent_sessions?: number;
+    } | null;
+    log: (s: string) => void;
+    /**
+     * Precomputed absolute path to the reference connector's source dir
+     * (`<pkgRoot>/connectors/openclaw`). REQUIRED: the only real caller
+     * (bin.ts's realWireDeps) always computes this via
+     * `connectorsSrcDir(import.meta.url)` using bin.ts's OWN import.meta.url —
+     * see that function's doc comment for why it has to be bin.ts's URL, not
+     * wire.ts's. A fallback that read wire.ts's own import.meta.url used to
+     * live here, but wire.ts sits one directory deeper than bin.ts
+     * (`src/service/wire.ts` vs `src/bin.ts`), so that fallback resolved to
+     * the wrong path — removed rather than fixed, since every real caller
+     * already supplies this field. Unit tests must pass a value too (any
+     * string is fine — `copyConnector` is mocked in tests and never inspects
+     * it for the non-hermes paths that reach it).
+     */
+    connectorsSrcDir: string;
+}
+/**
+ * Detects an installed harness by probing well-known home-relative dirs.
+ * Checked in order: openclaw, then hermes. Returns null when neither is
+ * present — the caller (bin.ts's realWireDeps) must then require an explicit
+ * --harness rather than guess.
+ */
+export declare function detectHarness(home: string, statDir: (p: string) => boolean): Harness | null;
+/**
+ * Where the connector gets installed for a given harness. Openclaw is the
+ * REFERENCE CONNECTOR (Task 6, connectors/openclaw/) and is fully wired.
+ * Hermes gets a defined target path so `detectHarness`/`wire --harness hermes`
+ * don't crash, but the Hermes CONNECTOR ITSELF is a fast-follow — only
+ * detection + this target dir ship in this task. Do not claim a working
+ * Hermes connector exists.
+ */
+export declare function connectorTargetDir(home: string, harness: Harness): string;
+/**
+ * Resolves the reference connector's SOURCE dir at runtime. `connectors/` is
+ * shipped SOURCE (not compiled — H2), so this must resolve from the running
+ * file's location back to the package root, never into dist/. Callers pass
+ * their OWN import.meta.url (bin.ts's), not wire.ts's: esbuild bundles
+ * wire.ts's code into dist/bin.js, so only the entry point's import.meta.url
+ * is guaranteed to sit exactly one directory below the package root in BOTH
+ * dev (src/bin.ts) and the built artifact (dist/bin.js) — mirrors
+ * resolve-bin.ts's loadPackageMeta (`dist/bin.js -> ../package.json`).
+ */
+export declare function connectorsSrcDir(importMetaUrl: string): string;
+/**
+ * Installs the reference connector into the harness's plugin dir and drops
+ * an explicit securecoms.binding.json naming the resolved agent's identity.
+ * There is NO auto-discovery (audit C1): the binding is written for EVERY
+ * agent, singleton included, every time `wire` runs.
+ *
+ * Hermes has no real connector yet (this round only ships detection +
+ * `connectorTargetDir`, see that function's doc comment) — refuse rather
+ * than install the openclaw connector's files into a Hermes plugin dir,
+ * which would be a false "installed" success.
+ */
+export declare function runWire(deps: WireDeps): number;
+/** Removes the explicit binding for the resolved agent. Leaves the copied
+ *  connector files in place — unwire un-names the agent, it doesn't uninstall
+ *  the plugin (that stays a harness-native operation).
+ *
+ *  Hermes never has anything installed by `runWire` (see its hermes guard),
+ *  so there's nothing to remove — no-op cleanly rather than call
+ *  `removeBinding` against a dir that was never created. */
+export declare function runUnwire(deps: WireDeps): number;

package/dist/ws-server.d.ts

@@ -27,7 +27,7 @@
  * 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).
+ * message_id (a fresh UUID minted per send; server-side dedup is on replay_nonce).
  *
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "connectors",
     "README.md"
   ],
   "publishConfig": {
@@ -28,20 +29,20 @@
   },
   "dependencies": {
     "@agentvault/crypto": "^0.4.1",
+    "@noble/ciphers": "^1.3.0",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.4.0",
-    "@noble/ciphers": "^1.3.0",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "ws": "^8.21.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@agentvault/connect-core": "*",
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
     "esbuild": "0.24.0",
     "typescript": "^5.4.0",
-    "vitest": "^2.0.0",
-    "@agentvault/connect-core": "*"
+    "vitest": "^2.0.0"
   }
 }