@saleso.innovations/bridge 0.1.0 → 0.1.4

package/README.md

@@ -13,10 +13,19 @@ curl -fsSL https://amicable-elephant-407.convex.site/install-bridge.sh | bash -s
 Requirements:
 
 - Node.js 20+
-- Hermes gateway running with API server enabled (`API_SERVER_ENABLED=true` in `~/.hermes/.env`, then `hermes gateway`)
+- Hermes installed on the same machine (`hermes gateway` — the install script configures the API automatically)
 
 ## Manual usage
 
+The install script puts the bridge in `~/.cleos/bridge` (no PATH setup needed). To run manually:
+
+```bash
+node ~/.cleos/bridge/node_modules/@saleso.innovations/bridge/dist/cli.js pair ABCD1234
+node ~/.cleos/bridge/node_modules/@saleso.innovations/bridge/dist/cli.js start
+```
+
+Or install globally if you prefer:
+
 ```bash
 npm install -g @saleso.innovations/bridge
 cleos-bridge connect ABCD1234   # first-time pairing

package/dist/cli.js

@@ -2,18 +2,23 @@
 import { credentialsPathForDisplay, loadCredentials } from "./credentials.js";
 import { connectHermesAgent, pairCleosAgent, reconnectHermesAgent } from "./client.js";
 import { runBridgeDaemon } from "./daemon.js";
+import { prepareHermesForBridge } from "./ensureHermesApi.js";
 import { createHermesMessageHandler } from "./hermesForwarder.js";
 import { convexSiteUrlFromEnv } from "./resolve.js";
+import { normalizePairingCode } from "./normalizePairingCode.js";
 async function main() {
     const [, , command, codeArg] = process.argv;
     const onUserMessage = createHermesMessageHandler();
+    if (command === "pair" || command === "connect" || command === "start" || command === "reconnect") {
+        await prepareHermesForBridge();
+    }
     if (command === "pair") {
         if (!codeArg) {
             printUsage();
             process.exit(1);
         }
         const payload = await pairCleosAgent({
-            code: codeArg.trim(),
+            code: normalizePairingCode(codeArg),
             convexSiteUrl: convexSiteUrlFromEnv(),
         });
         console.log(`Paired agent ${payload.agentId}.`);
@@ -26,7 +31,7 @@ async function main() {
             process.exit(1);
         }
         const session = await connectHermesAgent({
-            code: codeArg.trim(),
+            code: normalizePairingCode(codeArg),
             convexSiteUrl: convexSiteUrlFromEnv(),
             onUserMessage,
         });
@@ -45,7 +50,7 @@ async function main() {
             console.error("No saved credentials. Run: cleos-bridge connect <CODE>");
             process.exit(1);
         }
-        await runBridgeDaemon({ code: codeArg.trim(), convexSiteUrl: convexSiteUrlFromEnv() });
+        await runBridgeDaemon({ code: normalizePairingCode(codeArg), convexSiteUrl: convexSiteUrlFromEnv() });
         return;
     }
     if (command === "reconnect") {

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGhG,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrG,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB,CAAC;AA6HF,wBAAsB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA0BD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAcxF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE;IAClD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;CAC5C,GAAG,OAAO,CAAC,aAAa,CAAC,CAc9B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAIhG,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrG,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB,CAAC;AA8HF,wBAAsB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA0BD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAcxF;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE;IAClD,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;CAC5C,GAAG,OAAO,CAAC,aAAa,CAAC,CAc9B"}

package/dist/client.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import WebSocket from "ws";
 import { saveCredentials, loadCredentials } from "./credentials.js";
 import { convexSiteUrlFromEnv, resolvePairingCode } from "./resolve.js";
+import { normalizePairingCode } from "./normalizePairingCode.js";
 function createReplySender(ws, agentId, conversationId, messageId) {
     return {
         delta(text, sequence) {
@@ -82,17 +83,18 @@ async function openAgentConnection(options) {
     };
 }
 async function resolveRelayTargets(options) {
+    const normalizedCode = normalizePairingCode(options.code);
     if (options.relayHttpBaseUrl && options.relayWsUrl) {
         return {
-            code: options.code.trim().toUpperCase(),
+            code: normalizedCode,
             expiresAt: Date.now() + 60_000,
             relayHttpUrl: options.relayHttpBaseUrl,
             relayWsUrl: options.relayWsUrl,
-            connectCommand: `cleos-bridge connect ${options.code.trim().toUpperCase()}`,
+            connectCommand: `cleos-bridge connect ${normalizedCode}`,
         };
     }
     const convexSiteUrl = options.convexSiteUrl ?? convexSiteUrlFromEnv();
-    return await resolvePairingCode(convexSiteUrl, options.code);
+    return await resolvePairingCode(convexSiteUrl, normalizedCode);
 }
 export async function pairCleosAgent(options) {
     const pairing = await resolveRelayTargets(options);

package/dist/ensureHermesApi.d.ts

@@ -0,0 +1,7 @@
+export declare function ensureHermesApiConfigured(): Promise<{
+    envPath: string;
+    changed: boolean;
+    apiKey: string;
+}>;
+export declare function prepareHermesForBridge(): Promise<void>;
+//# sourceMappingURL=ensureHermesApi.d.ts.map

package/dist/ensureHermesApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureHermesApi.d.ts","sourceRoot":"","sources":["../src/ensureHermesApi.ts"],"names":[],"mappings":"AA8EA,wBAAsB,yBAAyB,IAAI,OAAO,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CA0BD;AAkDD,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB5D"}

package/dist/ensureHermesApi.js

@@ -0,0 +1,158 @@
+import { randomBytes } from "node:crypto";
+import { execFile, spawn } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { DEFAULT_HERMES_API_URL } from "./constants.js";
+const execFileAsync = promisify(execFile);
+const HERMES_ENV_PATH = join(homedir(), ".hermes", ".env");
+const HEALTH_URL = DEFAULT_HERMES_API_URL.replace(/\/v1\/chat\/completions\/?$/, "/health");
+const HEALTH_POLL_MS = 1_000;
+const HEALTH_TIMEOUT_MS = 30_000;
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { kind: "blank" };
+    if (trimmed.startsWith("#"))
+        return { kind: "comment", text: line };
+    const eq = line.indexOf("=");
+    if (eq <= 0)
+        return { kind: "comment", text: line };
+    const key = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    return { kind: "assignment", key, value, raw: line };
+}
+function serializeEnvLine(line) {
+    if (line.kind === "blank")
+        return "";
+    if (line.kind === "comment")
+        return line.text;
+    return `${line.key}=${line.value}`;
+}
+function generateApiKey() {
+    return randomBytes(24).toString("base64url");
+}
+async function readHermesEnvLines() {
+    try {
+        await access(HERMES_ENV_PATH);
+        const contents = await readFile(HERMES_ENV_PATH, "utf8");
+        return contents.split("\n").map(parseEnvLine);
+    }
+    catch {
+        return [];
+    }
+}
+function getAssignment(lines, key) {
+    for (const line of lines) {
+        if (line.kind === "assignment" && line.key === key) {
+            return line.value.replace(/^["']|["']$/g, "");
+        }
+    }
+    return undefined;
+}
+function upsertAssignment(lines, key, value) {
+    let found = false;
+    const next = lines.map((line) => {
+        if (line.kind !== "assignment" || line.key !== key)
+            return line;
+        found = true;
+        return { kind: "assignment", key, value, raw: `${key}=${value}` };
+    });
+    if (!found) {
+        if (next.length > 0 && next[next.length - 1]?.kind !== "blank") {
+            next.push({ kind: "blank" });
+        }
+        next.push({ kind: "assignment", key, value, raw: `${key}=${value}` });
+    }
+    return next;
+}
+export async function ensureHermesApiConfigured() {
+    await mkdir(join(homedir(), ".hermes"), { recursive: true });
+    const before = await readHermesEnvLines();
+    const enabled = getAssignment(before, "API_SERVER_ENABLED");
+    const existingKey = getAssignment(before, "API_SERVER_KEY");
+    const apiKey = existingKey && existingKey.length >= 8 ? existingKey : generateApiKey();
+    let lines = before;
+    let changed = false;
+    if (enabled !== "true") {
+        lines = upsertAssignment(lines, "API_SERVER_ENABLED", "true");
+        changed = true;
+    }
+    if (!existingKey || existingKey.length < 8) {
+        lines = upsertAssignment(lines, "API_SERVER_KEY", apiKey);
+        changed = true;
+    }
+    if (changed || before.length === 0) {
+        const body = lines.map(serializeEnvLine).join("\n");
+        await writeFile(HERMES_ENV_PATH, body.endsWith("\n") ? body : `${body}\n`, "utf8");
+    }
+    return { envPath: HERMES_ENV_PATH, changed, apiKey };
+}
+async function fetchHermesHealth(apiKey) {
+    const headers = {};
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    try {
+        const response = await fetch(HEALTH_URL, { headers, signal: AbortSignal.timeout(2_000) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryRestartHermesGateway() {
+    const units = ["hermes-gateway.service", "hermes.service", "hermes-gateway", "hermes"];
+    for (const unit of units) {
+        try {
+            await execFileAsync("systemctl", ["try-restart", unit], { timeout: 10_000 });
+        }
+        catch {
+            // Unit may not exist — keep trying other names.
+        }
+    }
+}
+async function tryStartHermesGateway() {
+    await new Promise((resolve) => {
+        try {
+            const child = spawn("hermes", ["gateway"], {
+                detached: true,
+                stdio: "ignore",
+            });
+            child.on("error", () => resolve());
+            child.unref();
+            resolve();
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+async function waitForHermesHealth(apiKey) {
+    const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await fetchHermesHealth(apiKey))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, HEALTH_POLL_MS));
+    }
+    return false;
+}
+export async function prepareHermesForBridge() {
+    const { envPath, changed, apiKey } = await ensureHermesApiConfigured();
+    if (changed) {
+        console.log(`Configured Hermes API in ${envPath}`);
+    }
+    if (await fetchHermesHealth(apiKey))
+        return;
+    if (changed) {
+        console.log("Restarting Hermes gateway to apply API settings...");
+        await tryRestartHermesGateway();
+        if (await waitForHermesHealth(apiKey))
+            return;
+    }
+    console.log("Hermes gateway not detected — starting `hermes gateway`...");
+    await tryStartHermesGateway();
+    if (await waitForHermesHealth(apiKey))
+        return;
+    throw new Error("Hermes is not running. Install Hermes, then run `hermes gateway` once on this machine and retry.");
+}

package/dist/hermesForwarder.js

@@ -43,7 +43,7 @@ async function ensureHermesReachable(apiUrl, apiKey) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error";
-        throw new Error(`Hermes is not reachable at ${healthUrl}. Start Hermes with \`hermes gateway\` and enable API_SERVER_ENABLED in ~/.hermes/.env. ${message}`);
+        throw new Error(`Hermes is not reachable at ${healthUrl}. Ensure Hermes is installed and run \`hermes gateway\` on this machine. ${message}`);
     }
 }
 function parseSseDataLines(buffer) {

package/dist/normalizePairingCode.d.ts

@@ -0,0 +1,3 @@
+/** Strip spaces/dashes and uppercase — matches Cleos app pairing codes. */
+export declare function normalizePairingCode(code: string): string;
+//# sourceMappingURL=normalizePairingCode.d.ts.map

package/dist/normalizePairingCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizePairingCode.d.ts","sourceRoot":"","sources":["../src/normalizePairingCode.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/normalizePairingCode.js

@@ -0,0 +1,4 @@
+/** Strip spaces/dashes and uppercase — matches Cleos app pairing codes. */
+export function normalizePairingCode(code) {
+    return code.replace(/[^A-Za-z0-9]/g, "").toUpperCase();
+}

package/dist/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQlG"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAQlG"}

package/dist/resolve.js

@@ -1,4 +1,5 @@
 import { DEFAULT_CLEOS_CONVEX_SITE_URL } from "./constants.js";
+import { normalizePairingCode } from "./normalizePairingCode.js";
 export function convexSiteUrlFromEnv() {
     const configured = process.env.CLEOS_CONVEX_SITE_URL?.trim() ||
         process.env.CONVEX_SITE_URL?.trim() ||
@@ -6,7 +7,7 @@ export function convexSiteUrlFromEnv() {
     return configured.replace(/\/$/, "");
 }
 export async function resolvePairingCode(convexSiteUrl, code) {
-    const normalized = code.trim().toUpperCase();
+    const normalized = normalizePairingCode(code);
     const response = await fetch(`${convexSiteUrl.replace(/\/$/, "")}/pairing/${normalized}`);
     if (!response.ok) {
         const body = await response.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saleso.innovations/bridge",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Connect your Hermes agent to the Cleos iOS app via pairing code.",
   "type": "module",
   "license": "MIT",