@saleso.innovations/bridge 0.1.0

package/INTEGRATION.md

@@ -0,0 +1,79 @@
+# Hermes ↔ Cleos integration
+
+End users should **never** clone the Cleos repo or run npm scripts. Pairing is:
+
+1. User opens the **Cleos iOS app** and gets an 8-character code.
+2. User opens **their own Hermes** (already running on their machine/VPS).
+3. User enters the code in Hermes (settings UI, web panel, or built-in command).
+4. Done — their Hermes agent is linked to their Cleos account only.
+
+Cleos provides this package as an SDK for **Hermes maintainers**, not for end users.
+
+## Hermes maintainer checklist
+
+- [ ] Add a **Connect to Cleos** screen in Hermes (web UI or CLI subcommand).
+- [ ] User enters the 8-character code from the Cleos app.
+- [ ] Call `pairWithCleos(code)` from this package (see below).
+- [ ] Wire `onUserMessage` to your existing Hermes agent loop.
+- [ ] On Hermes daemon start, call `reconnectHermesAgent()` if credentials exist.
+- [ ] Ship `DEFAULT_CLEOS_CONVEX_SITE_URL` (or your self-hosted URL) in Hermes builds.
+
+## Minimal integration
+
+```typescript
+import { pairWithCleos, reconnectHermesAgent } from "@saleso.innovations/bridge";
+
+// When user submits pairing code in Hermes UI:
+export async function onCleosPairingCodeSubmitted(code: string) {
+  const session = await pairWithCleos(code, {
+    agentName: "My Hermes",
+    onUserMessage: async (content, meta, reply) => {
+      // Forward to YOUR Hermes agent — each user talks to their own agent only.
+      const stream = await myHermesAgent.chat(content, { conversationId: meta.conversationId });
+      let sequence = 0;
+      for await (const chunk of stream) {
+        reply.delta(chunk, sequence++);
+      }
+      reply.complete(stream.finalText, sequence);
+    },
+  });
+  return session.agentId;
+}
+
+// On Hermes daemon startup:
+export async function resumeCleosConnection() {
+  await reconnectHermesAgent({ onUserMessage: handleCleosMessage });
+}
+```
+
+## What Cleos handles
+
+- User authentication (Google / Apple / dev skip)
+- Pairing code generation and expiry
+- Relay routing (Railway) between iOS app and Hermes WebSocket
+- Message history in Convex
+
+## What Hermes handles
+
+- Pairing UI (code entry)
+- Running the user's agent
+- Translating Cleos chat messages into agent requests and streaming replies back
+
+## Public pairing API
+
+Hermes can resolve a code without extra config:
+
+```
+GET https://<convex-site>/pairing/<CODE>
+→ { code, expiresAt, relayHttpUrl, relayWsUrl, connectCommand }
+```
+
+Codes expire after 10 minutes. Each code links **one** Hermes instance to **one** Cleos user account.
+
+## Credentials
+
+After first pairing, credentials are saved to `~/.cleos/agent.json`. Use `reconnectHermesAgent()` on restart — no new code required.
+
+## Self-hosting Cleos
+
+Set `CLEOS_CONVEX_SITE_URL` in the Hermes build to your Convex `.site` URL instead of the default.

package/README.md

@@ -0,0 +1,33 @@
+# @saleso.innovations/bridge
+
+Connect your **Hermes** agent to the **Cleos** iOS app with a pairing code.
+
+## VPS quick install
+
+Get a pairing code from the Cleos app, then on the machine where Hermes runs:
+
+```bash
+curl -fsSL https://amicable-elephant-407.convex.site/install-bridge.sh | bash -s -- ABCD1234
+```
+
+Requirements:
+
+- Node.js 20+
+- Hermes gateway running with API server enabled (`API_SERVER_ENABLED=true` in `~/.hermes/.env`, then `hermes gateway`)
+
+## Manual usage
+
+```bash
+npm install -g @saleso.innovations/bridge
+cleos-bridge connect ABCD1234   # first-time pairing
+cleos-bridge start              # reconnecting daemon (systemd)
+```
+
+Credentials are saved to `~/.cleos/agent.json`.
+
+## Hermes API
+
+By default the bridge forwards chat to Hermes at `http://127.0.0.1:8642/v1/chat/completions`.
+Override with `HERMES_API_URL` or `HERMES_API_KEY` if needed.
+
+See [INTEGRATION.md](./INTEGRATION.md) for native Hermes gateway integration.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { credentialsPathForDisplay, loadCredentials } from "./credentials.js";
+import { connectHermesAgent, pairCleosAgent, reconnectHermesAgent } from "./client.js";
+import { runBridgeDaemon } from "./daemon.js";
+import { createHermesMessageHandler } from "./hermesForwarder.js";
+import { convexSiteUrlFromEnv } from "./resolve.js";
+async function main() {
+    const [, , command, codeArg] = process.argv;
+    const onUserMessage = createHermesMessageHandler();
+    if (command === "pair") {
+        if (!codeArg) {
+            printUsage();
+            process.exit(1);
+        }
+        const payload = await pairCleosAgent({
+            code: codeArg.trim(),
+            convexSiteUrl: convexSiteUrlFromEnv(),
+        });
+        console.log(`Paired agent ${payload.agentId}.`);
+        console.log(`Credentials saved to ${credentialsPathForDisplay()}`);
+        return;
+    }
+    if (command === "connect") {
+        if (!codeArg) {
+            printUsage();
+            process.exit(1);
+        }
+        const session = await connectHermesAgent({
+            code: codeArg.trim(),
+            convexSiteUrl: convexSiteUrlFromEnv(),
+            onUserMessage,
+        });
+        console.log(`Connected agent ${session.agentId}.`);
+        console.log(`Credentials saved to ${credentialsPathForDisplay()}`);
+        console.log("Press Ctrl+C to exit.");
+        await waitForExit(session);
+        return;
+    }
+    if (command === "start") {
+        if (loadCredentials()) {
+            await runBridgeDaemon();
+            return;
+        }
+        if (!codeArg) {
+            console.error("No saved credentials. Run: cleos-bridge connect <CODE>");
+            process.exit(1);
+        }
+        await runBridgeDaemon({ code: codeArg.trim(), convexSiteUrl: convexSiteUrlFromEnv() });
+        return;
+    }
+    if (command === "reconnect") {
+        const saved = loadCredentials();
+        const session = await reconnectHermesAgent({
+            credentials: saved ?? undefined,
+            onUserMessage,
+        });
+        console.log(`Reconnected agent ${session.agentId}.`);
+        console.log("Press Ctrl+C to exit.");
+        await waitForExit(session);
+        return;
+    }
+    printUsage();
+    process.exit(1);
+}
+function printUsage() {
+    console.error("Usage:");
+    console.error("  cleos-bridge pair <CODE>      Save pairing credentials without staying connected");
+    console.error("  cleos-bridge connect <CODE>   Pair and stay connected in the foreground");
+    console.error("  cleos-bridge start [CODE]     Run as a reconnecting daemon (systemd)");
+    console.error("  cleos-bridge reconnect        Reconnect once using saved credentials");
+}
+async function waitForExit(session) {
+    await new Promise((resolve) => {
+        const onSignal = () => {
+            session.close();
+            resolve();
+            process.exit(0);
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+    });
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import { type SavedAgentCredentials } from "./credentials.js";
+export type ConnectOptions = {
+    code: string;
+    convexSiteUrl?: string;
+    relayHttpBaseUrl?: string;
+    relayWsUrl?: string;
+    agentName?: string;
+    capabilities?: string[];
+    onUserMessage?: (content: string, meta: UserMessageMeta, reply: AgentReply) => Promise<void> | void;
+};
+export type UserMessageMeta = {
+    agentId: string;
+    conversationId: string;
+    messageId: string;
+};
+export type AgentReply = {
+    delta: (text: string, sequence: number) => void;
+    complete: (text: string, sequence: number) => void;
+};
+export type ConnectResult = {
+    agentId: string;
+    agentToken: string;
+    close: () => void;
+    closed: Promise<void>;
+};
+export declare function pairCleosAgent(options: Omit<ConnectOptions, "onUserMessage">): Promise<{
+    agentId: string;
+    agentToken: string;
+}>;
+export declare function connectHermesAgent(options: ConnectOptions): Promise<ConnectResult>;
+export declare function reconnectHermesAgent(options?: {
+    credentials?: SavedAgentCredentials;
+    capabilities?: string[];
+    onUserMessage?: ConnectOptions["onUserMessage"];
+}): Promise<ConnectResult>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +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"}

package/dist/client.js

@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { saveCredentials, loadCredentials } from "./credentials.js";
+import { convexSiteUrlFromEnv, resolvePairingCode } from "./resolve.js";
+function createReplySender(ws, agentId, conversationId, messageId) {
+    return {
+        delta(text, sequence) {
+            ws.send(JSON.stringify({
+                type: "agent.delta",
+                agentId,
+                conversationId,
+                messageId,
+                delta: text,
+                sequence,
+            }));
+        },
+        complete(text, sequence) {
+            ws.send(JSON.stringify({
+                type: "agent.message",
+                agentId,
+                conversationId,
+                messageId,
+                content: text,
+                sequence,
+                final: true,
+            }));
+        },
+    };
+}
+async function openAgentConnection(options) {
+    const ws = new WebSocket(options.relayWsUrl);
+    let closedResolve = null;
+    const closed = new Promise((resolve) => {
+        closedResolve = resolve;
+    });
+    await new Promise((resolve, reject) => {
+        ws.once("open", () => resolve());
+        ws.once("error", reject);
+    });
+    ws.send(JSON.stringify({
+        type: "agent.hello",
+        token: options.agentToken,
+        agentId: options.agentId,
+        capabilities: options.capabilities,
+    }));
+    ws.on("message", (raw) => {
+        void (async () => {
+            const envelope = JSON.parse(raw.toString());
+            if (envelope.type !== "user.message")
+                return;
+            const content = typeof envelope.content === "string" ? envelope.content : "";
+            const agentId = typeof envelope.agentId === "string" ? envelope.agentId : options.agentId;
+            const conversationId = typeof envelope.conversationId === "string" ? envelope.conversationId : "unknown";
+            const messageId = typeof envelope.clientMessageId === "string" ? envelope.clientMessageId : randomUUID();
+            const reply = createReplySender(ws, agentId, conversationId, messageId);
+            if (options.onUserMessage) {
+                await options.onUserMessage(content, { agentId, conversationId, messageId }, reply);
+                return;
+            }
+            const echo = `Echo: ${content}`;
+            reply.delta(echo, 0);
+            reply.complete(echo, 1);
+        })();
+    });
+    const heartbeat = setInterval(() => {
+        if (ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify({ type: "heartbeat", sentAt: Date.now() }));
+        }
+    }, 30_000);
+    ws.on("close", () => {
+        clearInterval(heartbeat);
+        closedResolve?.();
+    });
+    return {
+        agentId: options.agentId,
+        agentToken: options.agentToken,
+        close: () => {
+            clearInterval(heartbeat);
+            ws.close();
+        },
+        closed,
+    };
+}
+async function resolveRelayTargets(options) {
+    if (options.relayHttpBaseUrl && options.relayWsUrl) {
+        return {
+            code: options.code.trim().toUpperCase(),
+            expiresAt: Date.now() + 60_000,
+            relayHttpUrl: options.relayHttpBaseUrl,
+            relayWsUrl: options.relayWsUrl,
+            connectCommand: `cleos-bridge connect ${options.code.trim().toUpperCase()}`,
+        };
+    }
+    const convexSiteUrl = options.convexSiteUrl ?? convexSiteUrlFromEnv();
+    return await resolvePairingCode(convexSiteUrl, options.code);
+}
+export async function pairCleosAgent(options) {
+    const pairing = await resolveRelayTargets(options);
+    const response = await fetch(`${pairing.relayHttpUrl.replace(/\/$/, "")}/connect`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            code: pairing.code,
+            agentName: options.agentName ?? "Hermes",
+            capabilities: options.capabilities ?? ["chat"],
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Connect failed (${response.status}): ${await response.text()}`);
+    }
+    const payload = (await response.json());
+    saveCredentials({
+        agentId: payload.agentId,
+        agentToken: payload.agentToken,
+        relayHttpUrl: pairing.relayHttpUrl,
+        relayWsUrl: pairing.relayWsUrl,
+        agentName: options.agentName ?? "Hermes",
+        savedAt: Date.now(),
+    });
+    return payload;
+}
+export async function connectHermesAgent(options) {
+    await pairCleosAgent(options);
+    const credentials = loadCredentials();
+    if (!credentials) {
+        throw new Error("Pairing credentials were not saved");
+    }
+    return await openAgentConnection({
+        relayWsUrl: credentials.relayWsUrl,
+        agentId: credentials.agentId,
+        agentToken: credentials.agentToken,
+        capabilities: options.capabilities ?? ["chat"],
+        onUserMessage: options.onUserMessage,
+    });
+}
+export async function reconnectHermesAgent(options = {}) {
+    const { loadCredentials } = await import("./credentials.js");
+    const credentials = options.credentials ?? loadCredentials();
+    if (!credentials) {
+        throw new Error("No saved Cleos agent credentials. Run `cleos-bridge connect <CODE>` first.");
+    }
+    return await openAgentConnection({
+        relayWsUrl: credentials.relayWsUrl,
+        agentId: credentials.agentId,
+        agentToken: credentials.agentToken,
+        capabilities: options.capabilities ?? ["chat"],
+        onUserMessage: options.onUserMessage,
+    });
+}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/** Default Cleos Convex site — pairing codes resolve relay URLs from here. */
+export declare const DEFAULT_CLEOS_CONVEX_SITE_URL = "https://amicable-elephant-407.convex.site";
+/** Default Hermes OpenAI-compatible API (requires `hermes gateway` + API_SERVER_ENABLED). */
+export declare const DEFAULT_HERMES_API_URL = "http://127.0.0.1:8642/v1/chat/completions";
+/** VPS one-line installer (served from public Convex HTTP). */
+export declare const DEFAULT_BRIDGE_INSTALL_URL = "https://amicable-elephant-407.convex.site/install-bridge.sh";
+export declare function bridgeInstallCommand(code: string): string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,8CAA8C,CAAC;AAEzF,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,8CAA8C,CAAC;AAElF,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,gEACwB,CAAC;AAEhE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/constants.js

@@ -0,0 +1,9 @@
+/** Default Cleos Convex site — pairing codes resolve relay URLs from here. */
+export const DEFAULT_CLEOS_CONVEX_SITE_URL = "https://amicable-elephant-407.convex.site";
+/** Default Hermes OpenAI-compatible API (requires `hermes gateway` + API_SERVER_ENABLED). */
+export const DEFAULT_HERMES_API_URL = "http://127.0.0.1:8642/v1/chat/completions";
+/** VPS one-line installer (served from public Convex HTTP). */
+export const DEFAULT_BRIDGE_INSTALL_URL = "https://amicable-elephant-407.convex.site/install-bridge.sh";
+export function bridgeInstallCommand(code) {
+    return `curl -fsSL ${DEFAULT_BRIDGE_INSTALL_URL} | bash -s -- ${code}`;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,12 @@
+export type SavedAgentCredentials = {
+    agentId: string;
+    agentToken: string;
+    relayHttpUrl: string;
+    relayWsUrl: string;
+    agentName?: string;
+    savedAt: number;
+};
+export declare function loadCredentials(): SavedAgentCredentials | null;
+export declare function saveCredentials(credentials: SavedAgentCredentials): void;
+export declare function credentialsPathForDisplay(): string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF,wBAAgB,eAAe,IAAI,qBAAqB,GAAG,IAAI,CAS9D;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,qBAAqB,GAAG,IAAI,CAGxE;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}

package/dist/credentials.js

@@ -0,0 +1,23 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const credentialsPath = join(homedir(), ".cleos", "agent.json");
+export function loadCredentials() {
+    try {
+        const raw = readFileSync(credentialsPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.agentId || !parsed.agentToken || !parsed.relayWsUrl)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCredentials(credentials) {
+    mkdirSync(dirname(credentialsPath), { recursive: true });
+    writeFileSync(credentialsPath, JSON.stringify(credentials, null, 2));
+}
+export function credentialsPathForDisplay() {
+    return credentialsPath;
+}

package/dist/daemon.d.ts

@@ -0,0 +1,6 @@
+export type RunBridgeOptions = {
+    code?: string;
+    convexSiteUrl?: string;
+};
+export declare function runBridgeDaemon(options?: RunBridgeOptions): Promise<never>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAsB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,CAAC,CA8BpF"}

package/dist/daemon.js

@@ -0,0 +1,36 @@
+import { connectHermesAgent, reconnectHermesAgent } from "./client.js";
+import { createHermesMessageHandler } from "./hermesForwarder.js";
+const RECONNECT_DELAY_MS = 5_000;
+export async function runBridgeDaemon(options = {}) {
+    const onUserMessage = createHermesMessageHandler();
+    let pendingCode = options.code;
+    while (true) {
+        try {
+            let session;
+            if (pendingCode) {
+                session = await connectHermesAgent({
+                    code: pendingCode,
+                    convexSiteUrl: options.convexSiteUrl,
+                    onUserMessage,
+                });
+                pendingCode = undefined;
+                console.log(JSON.stringify({ event: "cleos-bridge.connected", agentId: session.agentId, mode: "pair" }));
+            }
+            else {
+                session = await reconnectHermesAgent({ onUserMessage });
+                console.log(JSON.stringify({ event: "cleos-bridge.connected", agentId: session.agentId, mode: "reconnect" }));
+            }
+            await session.closed;
+            session.close();
+            console.log(JSON.stringify({ event: "cleos-bridge.disconnected", retryInMs: RECONNECT_DELAY_MS }));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(JSON.stringify({ event: "cleos-bridge.error", message, retryInMs: RECONNECT_DELAY_MS }));
+        }
+        await sleep(RECONNECT_DELAY_MS);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/hermesForwarder.d.ts

@@ -0,0 +1,15 @@
+import type { AgentReply, UserMessageMeta } from "./client.js";
+export type HermesForwarderOptions = {
+    apiUrl?: string;
+    apiKey?: string;
+    model?: string;
+    conversationId?: string;
+};
+export declare function resolveHermesApiConfig(options?: HermesForwarderOptions): {
+    apiUrl: string;
+    apiKey: string | undefined;
+    model: string;
+};
+export declare function forwardToHermes(content: string, meta: UserMessageMeta, reply: AgentReply, options?: HermesForwarderOptions): Promise<void>;
+export declare function createHermesMessageHandler(options?: HermesForwarderOptions): (content: string, meta: UserMessageMeta, reply: AgentReply) => Promise<void>;
+//# sourceMappingURL=hermesForwarder.d.ts.map

package/dist/hermesForwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermesForwarder.d.ts","sourceRoot":"","sources":["../src/hermesForwarder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG/D,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAkBF,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf,CAUA;AAqCD,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAwEf;AAED,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,sBAA2B,IAC/D,SAAS,MAAM,EAAE,MAAM,eAAe,EAAE,OAAO,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC,CAMxF"}

package/dist/hermesForwarder.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_HERMES_API_URL } from "./constants.js";
+function readHermesApiKeyFromEnvFile() {
+    const envPath = join(homedir(), ".hermes", ".env");
+    try {
+        const contents = readFileSync(envPath, "utf8");
+        for (const line of contents.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const match = trimmed.match(/^API_SERVER_KEY=(.+)$/);
+            if (match?.[1])
+                return match[1].trim().replace(/^["']|["']$/g, "");
+        }
+    }
+    catch {
+        // Hermes env file is optional.
+    }
+    return undefined;
+}
+export function resolveHermesApiConfig(options = {}) {
+    return {
+        apiUrl: options.apiUrl?.trim() || process.env.HERMES_API_URL?.trim() || DEFAULT_HERMES_API_URL,
+        apiKey: options.apiKey?.trim() ||
+            process.env.HERMES_API_KEY?.trim() ||
+            process.env.API_SERVER_KEY?.trim() ||
+            readHermesApiKeyFromEnvFile(),
+        model: options.model?.trim() || process.env.HERMES_MODEL?.trim() || "hermes-agent",
+    };
+}
+async function ensureHermesReachable(apiUrl, apiKey) {
+    const healthUrl = apiUrl.replace(/\/v1\/chat\/completions\/?$/, "/health");
+    const headers = {};
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    try {
+        const response = await fetch(healthUrl, { headers });
+        if (!response.ok) {
+            throw new Error(`Hermes health check failed (${response.status})`);
+        }
+    }
+    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}`);
+    }
+}
+function parseSseDataLines(buffer) {
+    const parts = buffer.split("\n\n");
+    const rest = parts.pop() ?? "";
+    return { events: parts, rest };
+}
+function extractDeltaFromChunk(payload) {
+    const choices = payload.choices;
+    if (!Array.isArray(choices) || choices.length === 0)
+        return null;
+    const choice = choices[0];
+    if (!choice || typeof choice !== "object")
+        return null;
+    const delta = choice.delta;
+    if (!delta || typeof delta !== "object")
+        return null;
+    const content = delta.content;
+    return typeof content === "string" ? content : null;
+}
+export async function forwardToHermes(content, meta, reply, options = {}) {
+    const { apiUrl, apiKey, model } = resolveHermesApiConfig(options);
+    await ensureHermesReachable(apiUrl, apiKey);
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    const conversationKey = options.conversationId ?? meta.conversationId;
+    const body = {
+        model,
+        stream: true,
+        messages: [{ role: "user", content }],
+        user: conversationKey,
+    };
+    const response = await fetch(apiUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Hermes request failed (${response.status}): ${text}`);
+    }
+    if (!response.body) {
+        throw new Error("Hermes returned an empty streaming body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let sequence = 0;
+    let fullText = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const { events, rest } = parseSseDataLines(buffer);
+        buffer = rest;
+        for (const event of events) {
+            for (const line of event.split("\n")) {
+                if (!line.startsWith("data: "))
+                    continue;
+                const data = line.slice(6).trim();
+                if (!data || data === "[DONE]")
+                    continue;
+                try {
+                    const payload = JSON.parse(data);
+                    const delta = extractDeltaFromChunk(payload);
+                    if (delta) {
+                        fullText += delta;
+                        reply.delta(delta, sequence);
+                        sequence += 1;
+                    }
+                }
+                catch {
+                    // Ignore malformed SSE chunks.
+                }
+            }
+        }
+    }
+    if (!fullText.trim()) {
+        fullText = "(Hermes returned an empty response)";
+        reply.delta(fullText, sequence);
+        sequence += 1;
+    }
+    reply.complete(fullText, sequence);
+}
+export function createHermesMessageHandler(options = {}) {
+    return async (content, meta, reply) => {
+        await forwardToHermes(content, meta, reply, {
+            ...options,
+            conversationId: meta.conversationId,
+        });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { connectHermesAgent, pairCleosAgent, reconnectHermesAgent } from "./client.js";
+export type { AgentReply, ConnectOptions, ConnectResult, UserMessageMeta } from "./client.js";
+export { loadCredentials, saveCredentials, credentialsPathForDisplay } from "./credentials.js";
+export type { SavedAgentCredentials } from "./credentials.js";
+export { resolvePairingCode, convexSiteUrlFromEnv } from "./resolve.js";
+export type { PairingInfo } from "./resolve.js";
+export { pairWithCleos } from "./pairWithCleos.js";
+export { createHermesMessageHandler, forwardToHermes, resolveHermesApiConfig } from "./hermesForwarder.js";
+export type { HermesForwarderOptions } from "./hermesForwarder.js";
+export { runBridgeDaemon } from "./daemon.js";
+export type { RunBridgeOptions } from "./daemon.js";
+export { DEFAULT_BRIDGE_INSTALL_URL, DEFAULT_CLEOS_CONVEX_SITE_URL, DEFAULT_HERMES_API_URL, bridgeInstallCommand, } from "./constants.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACvF,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC3G,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { connectHermesAgent, pairCleosAgent, reconnectHermesAgent } from "./client.js";
+export { loadCredentials, saveCredentials, credentialsPathForDisplay } from "./credentials.js";
+export { resolvePairingCode, convexSiteUrlFromEnv } from "./resolve.js";
+export { pairWithCleos } from "./pairWithCleos.js";
+export { createHermesMessageHandler, forwardToHermes, resolveHermesApiConfig } from "./hermesForwarder.js";
+export { runBridgeDaemon } from "./daemon.js";
+export { DEFAULT_BRIDGE_INSTALL_URL, DEFAULT_CLEOS_CONVEX_SITE_URL, DEFAULT_HERMES_API_URL, bridgeInstallCommand, } from "./constants.js";

package/dist/pairWithCleos.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectOptions, ConnectResult } from "./client.js";
+/**
+ * Pair the local Hermes agent with a user's Cleos account using a code from the iOS app.
+ */
+export declare function pairWithCleos(code: string, options?: {
+    convexSiteUrl?: string;
+    agentName?: string;
+    onUserMessage?: ConnectOptions["onUserMessage"];
+}): Promise<ConnectResult>;
+//# sourceMappingURL=pairWithCleos.d.ts.map

package/dist/pairWithCleos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairWithCleos.d.ts","sourceRoot":"","sources":["../src/pairWithCleos.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjE;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;CAC5C,GACL,OAAO,CAAC,aAAa,CAAC,CAUxB"}

package/dist/pairWithCleos.js

@@ -0,0 +1,15 @@
+import { connectHermesAgent } from "./client.js";
+import { DEFAULT_CLEOS_CONVEX_SITE_URL } from "./constants.js";
+/**
+ * Pair the local Hermes agent with a user's Cleos account using a code from the iOS app.
+ */
+export async function pairWithCleos(code, options = {}) {
+    return connectHermesAgent({
+        code,
+        convexSiteUrl: options.convexSiteUrl ??
+            process.env.CLEOS_CONVEX_SITE_URL?.trim() ??
+            DEFAULT_CLEOS_CONVEX_SITE_URL,
+        agentName: options.agentName,
+        onUserMessage: options.onUserMessage,
+    });
+}

package/dist/resolve.d.ts

@@ -0,0 +1,11 @@
+export type PairingInfo = {
+    code: string;
+    expiresAt: number;
+    relayHttpUrl: string;
+    relayWsUrl: string;
+    connectCommand: string;
+    installCommand?: string;
+};
+export declare function convexSiteUrlFromEnv(): string;
+export declare function resolvePairingCode(convexSiteUrl: string, code: string): Promise<PairingInfo>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +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"}

package/dist/resolve.js

@@ -0,0 +1,16 @@
+import { DEFAULT_CLEOS_CONVEX_SITE_URL } from "./constants.js";
+export function convexSiteUrlFromEnv() {
+    const configured = process.env.CLEOS_CONVEX_SITE_URL?.trim() ||
+        process.env.CONVEX_SITE_URL?.trim() ||
+        DEFAULT_CLEOS_CONVEX_SITE_URL;
+    return configured.replace(/\/$/, "");
+}
+export async function resolvePairingCode(convexSiteUrl, code) {
+    const normalized = code.trim().toUpperCase();
+    const response = await fetch(`${convexSiteUrl.replace(/\/$/, "")}/pairing/${normalized}`);
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Pairing lookup failed (${response.status}): ${body}`);
+    }
+    return (await response.json());
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@saleso.innovations/bridge",
+  "version": "0.1.0",
+  "description": "Connect your Hermes agent to the Cleos iOS app via pairing code.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RemiRonning/cleos.git",
+    "directory": "packages/cleos-hermes-connect"
+  },
+  "keywords": ["cleos", "hermes", "agent", "relay"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "INTEGRATION.md"],
+  "bin": {
+    "cleos-bridge": "./dist/cli.js",
+    "hermes-relay": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "echo 'No @saleso.innovations/bridge tests configured'"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^25.4.0",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9.39.1",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}