@claw-link/gateway-host 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ClawLink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @claw-link/gateway-host — ClawLink Host Gateway
+
+Run **any local agent CLI** — OpenClaw, [Hermes](https://hermes-agent.nousresearch.com),
+Claude, Codex, or Cursor — as a ClawLink agent. The host worker is a small,
+**outbound-only** process: it dials out to ClawLink, claims customer/admin messages
+for your agent, runs the chosen runtime locally, and streams the reply back. No
+inbound ports, no Tailscale Funnel — just a per-agent **Host Token**.
+
+```
+ClawLink (cloud)  ──enqueues message──▶  host-bridge
+        ▲                                    │  (your machine dials OUT)
+        └──── streams reply back ──── @claw-link/gateway-host ──▶ hermes | claude | codex | cursor | local OpenClaw
+```
+
+## Install
+
+```bash
+npx @claw-link/gateway-host install      # one-time: install the background service
+npx @claw-link/gateway-host add-agent    # paste an agent's Host Token — that's it
+```
+
+(`setup` does both in one flow.) **You only paste the Host Token.** The host verifies
+it, **pulls the agent's runtime from ClawLink** (the dashboard is the source of truth),
+auto-detects the runtime binary, and **binds this machine** so the token can't be used
+from anywhere else. For coding runtimes (claude/codex/cursor) it also asks for the
+project **workspace directory** (that part is host-specific). Config lands in
+`~/.clawlink-host/config.json` (chmod 600).
+
+Get a token from **ClawLink → Agents → your agent → Host Gateway → Generate token**, and
+verify the live connection badge there.
+
+## Runtimes
+
+| Runtime  | How it runs                                  | Install |
+|----------|----------------------------------------------|---------|
+| OpenClaw | POSTs to your **local** OpenClaw gateway     | (already running) |
+| Hermes   | `hermes chat -q "<prompt>" --resume <id>`    | `curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| bash` |
+| Claude   | `claude -p --output-format stream-json`      | Claude Code CLI |
+| Codex    | `codex exec "<prompt>"`                       | Codex CLI |
+| Cursor   | `cursor-agent -p "<prompt>"`                  | Cursor CLI |
+
+Each runtime's flags can be overridden per-agent via `args_template` in the config
+(placeholders `{prompt}`, `{sessionId}`, `{systemPrompt}` are substituted **per argv
+element** — never through a shell).
+
+**Workspace directory** — Claude, Codex, and Cursor are coding agents that run inside
+a project directory. The setup wizard asks for that **workspace directory** per agent
+and the CLI is run there (`cwd`). OpenClaw (HTTP) and Hermes (its own `~/.hermes`
+context) don't use one.
+
+## Commands
+
+```bash
+npx @claw-link/gateway-host install     # install the background service (one-time)
+npx @claw-link/gateway-host add-agent   # add an agent by pasting its Host Token
+npx @claw-link/gateway-host setup       # install + add-agent in one flow
+npx @claw-link/gateway-host start       # run in the foreground
+npx @claw-link/gateway-host status      # show configured agents (secrets redacted)
+npx @claw-link/gateway-host rotate      # rotate a Host Token / move to a new machine
+npx @claw-link/gateway-host uninstall   # stop + remove the service
+```
+
+## Config
+
+`~/.clawlink-host/config.json` (chmod 600):
+
+A minimal binding is just a token (everything else is resolved from ClawLink and
+cached back in). `~/.clawlink-host/config.json` (chmod 600):
+
+```json
+{
+  "bridge_url": "https://<project-ref>.supabase.co/functions/v1/host-bridge",
+  "instance_id": "…",
+  "poll_interval_ms": 1500,
+  "agents": [
+    { "host_token": "clk_host_…" },
+    { "host_token": "clk_host_…", "runtime": "claude", "binary": "/usr/local/bin/claude", "work_dir": "/Users/me/projects/acme" }
+  ]
+}
+```
+
+## Security
+
+Outbound-only, per-agent token (stored server-side as a hash only), **machine-bound**
+on first connect (a stolen token fails from any other host), no shell injection, runs
+only the configured binary. See [SECURITY.md](./SECURITY.md).
+
+MIT

package/SECURITY.md

@@ -0,0 +1,50 @@
+# ClawLink Host Gateway — Security Model
+
+The host worker is designed to expose **zero inbound attack surface** and to run
+**only** the agent runtime you configure. The design goals, in order: never leak
+a secret, never run an attacker-controlled command, never open a port.
+
+## Guarantees
+
+1. **Per-agent Host Token** — a ≥256-bit random secret generated in ClawLink. The
+   ClawLink server stores **only its SHA-256 hash**; the raw token is shown once.
+   The worker presents it on every `host-bridge` call. A token scopes the worker to
+   exactly one `agent_id`. Rotate any time from the dashboard (the old token dies
+   immediately).
+2. **Machine binding** — on first connect the worker sends a **hash** of the host's
+   machine fingerprint (MAC address(es) + hostname); ClawLink binds the agent to that
+   machine. Every later call must present the same fingerprint, so a stolen token is
+   rejected from any other host. Only the hash is sent — raw MACs never leave the
+   machine. Rotating the token clears the binding (also how you move to a new host).
+   (A MAC can be spoofed by an attacker who *also* learns it, so treat this as a strong
+   second factor on top of the token, not a replacement.)
+3. **Outbound-only** — the worker **dials out** to the `host-bridge` HTTPS endpoint
+   and short-polls for work. It opens **no inbound port**, needs **no Tailscale
+   Funnel**, and works behind NAT. There is nothing to attack from the network.
+4. **No shell injection** — every CLI is launched with `child_process.spawn(binary,
+   argvArray, { shell: false })`. Untrusted prompt text is passed as a single argv
+   token or via stdin — it is **never** concatenated into a command string.
+5. **No arbitrary command execution** — the worker runs **only** the runtime binary
+   you configured. The job payload it receives carries `{ content, system_prompt,
+   attachments, session }` — it is structurally incapable of carrying a command, and
+   the worker never `eval`s or spawns anything else. Known "auto-approve / no-safety"
+   flags (`--yolo`, `--dangerously-skip-permissions`, …) are stripped even if present
+   in a custom `args_template`.
+5. **Secrets never logged** — a redaction logger replaces every configured token/key
+   with `***` in all output, including the runtime's stderr.
+6. **File permissions** — `~/.clawlink-host/` is `0700`; `config.json` and
+   `sessions.json` are `0600`.
+7. **Concurrency + rate limits** — per-agent caps bound how many jobs run at once and
+   per minute, so a flood can't exhaust the host.
+8. **Heartbeat** — the worker reports liveness; the dashboard shows a live connection
+   badge and a stale host appears clearly offline.
+
+## Your responsibilities
+
+- Keep `~/.clawlink-host/config.json` private (it holds your Host Tokens).
+- Run the worker as a **low-privilege user**, ideally one dedicated to it.
+- Prefer a restricted `work_dir` (or a container) per agent.
+- Apply the ClawLink **Security skills** to any public-facing agent so the runtime
+  itself refuses to leak secrets, read config files, or run out-of-scope commands.
+
+Report vulnerabilities to the ClawLink maintainers privately.

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+// ClawLink Host Gateway CLI. Commands: setup | start | status | rotate | uninstall
+
+const cmd = (process.argv[2] || '').toLowerCase();
+
+async function main() {
+  switch (cmd) {
+    case 'start':
+      return require('../src/worker').startWorker();
+
+    case 'setup':
+    case '':
+      return require('../scripts/install').run();
+
+    case 'install':
+      return require('../scripts/install').installOnly();
+
+    case 'add-agent':
+    case 'add':
+      return require('../scripts/install').addAgentCmd();
+
+    case 'uninstall':
+      return require('../scripts/uninstall').run();
+
+    case 'status':
+      return require('../scripts/install').status();
+
+    case 'rotate':
+      console.log([
+        'To rotate a Host Token (also how you move an agent to a new machine):',
+        '  1. Open ClawLink → Agents → your agent → Host Gateway → "Rotate token".',
+        '     This also clears the machine binding, so a new host can claim it.',
+        '  2. Copy the new token, then run: npx @claw-link/gateway-host add-agent',
+        '     (paste the new token). The old token + old machine stop working immediately.',
+      ].join('\n'));
+      return;
+
+    case '--help':
+    case '-h':
+    case 'help':
+      console.log([
+        'ClawLink Host Gateway',
+        '',
+        'Usage: claw-host <command>',
+        '  install     Install the background service (one-time)',
+        '  add-agent   Add an agent by pasting its Host Token (pulls runtime from ClawLink)',
+        '  setup       install + add-agent in one flow (default)',
+        '  start       Run the worker in the foreground (used by the service)',
+        '  status      Show configured agents + last connection',
+        '  rotate      How to rotate a Host Token / move to a new machine',
+        '  uninstall   Stop + remove the background service',
+      ].join('\n'));
+      return;
+
+    default:
+      console.error(`Unknown command '${cmd}'. Try: claw-host help`);
+      process.exit(1);
+  }
+}
+
+main().catch((e) => { console.error(e && e.message ? e.message : e); process.exit(1); });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@claw-link/gateway-host",
+  "version": "0.1.0",
+  "description": "ClawLink Host Gateway — a secure, outbound-only worker that bridges a local agent CLI (OpenClaw, Hermes, Claude, Codex, Cursor) to your ClawLink agents. No inbound ports; authenticated per-agent by a Host Token.",
+  "bin": {
+    "claw-host": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js start"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "clawlink",
+    "openclaw",
+    "hermes",
+    "claude",
+    "codex",
+    "cursor",
+    "ai-agent",
+    "gateway"
+  ],
+  "license": "MIT"
+}

package/scripts/install.js

@@ -0,0 +1,191 @@
+'use strict';
+// Setup wizard + background-service installer for the ClawLink Host Gateway.
+// Mirrors the launchd/systemd/sc service pattern used by @claw-link/clom.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const config = require('../src/config');
+const { detectRuntimes } = require('../src/detect');
+const { Bridge } = require('../src/bridge');
+
+const VERSION = (() => { try { return require('../package.json').version; } catch { return '0.0.0'; } })();
+const PROJECT_REF_DEFAULT = 'rgzinqbdnesinmbshgtc';
+const RUNTIMES = ['openclaw', 'hermes', 'claude', 'codex', 'cursor'];
+const SERVICE_LABEL = 'co.clawlink.host';
+
+function ask(rl, q, def) {
+  return new Promise((res) => rl.question(def ? `${q} [${def}]: ` : `${q}: `, (a) => res((a || '').trim() || def || '')));
+}
+function execSafe(cmd) { try { return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString(); } catch { return null; } }
+
+async function ensureBridgeUrl(cfg, rl) {
+  if (cfg.bridge_url) return;
+  const ref = await ask(rl, '  Supabase project ref', PROJECT_REF_DEFAULT);
+  cfg.bridge_url = `https://${ref}.supabase.co/functions/v1/host-bridge`;
+}
+
+// Add one agent with ONLY its Host Token. The token resolves the agent + runtime
+// from Supabase (the dashboard is the source of truth); the host fills in the rest.
+async function addAgentInteractive(cfg, rl) {
+  const token = await ask(rl, '  Host Token (clk_host_… — from ClawLink → Agents → Host Gateway)');
+  if (!token) { console.log('  (skipped)'); return null; }
+
+  console.log('  Verifying token + binding this machine…');
+  let resp;
+  try {
+    resp = await new Bridge(cfg.bridge_url, { host_token: token }, cfg.instance_id).register(null, VERSION);
+  } catch (e) {
+    console.log(`  ✗ Could not verify: ${e.message}`);
+    return null;
+  }
+  const runtime = resp.runtime;
+  const agent = { agent_id: resp.agent_id, host_token: token, runtime };
+  console.log(`  ✓ Agent ${resp.agent_id} — runtime: ${runtime}`);
+
+  const detected = detectRuntimes();
+  if (runtime === 'openclaw') {
+    agent.local_gateway_url = await ask(rl, '  Local OpenClaw gateway URL', 'http://localhost:3000');
+    agent.local_gateway_token = await ask(rl, '  Local OpenClaw gateway token (optional)', '');
+  } else if (!detected[runtime]) {
+    agent.binary = await ask(rl, `  '${runtime}' not found on PATH — full path to the binary`, runtime);
+  } else {
+    console.log(`    using ${runtime}: ${detected[runtime]}`);
+  }
+
+  // Coding runtimes run inside a project workspace (host-specific, can't be pulled).
+  if (config.WORKSPACE_RUNTIMES.includes(runtime)) {
+    let ws = '';
+    while (!ws) {
+      ws = await ask(rl, `  Workspace directory for ${runtime} (the project it runs in)`, process.cwd());
+      if (ws && !fs.existsSync(config.expandHome(ws))) { console.log(`  ⚠ ${ws} does not exist.`); ws = ''; }
+    }
+    agent.work_dir = ws;
+  }
+  return agent;
+}
+
+function saveAgent(cfg, agent) {
+  const byId = new Map((cfg.agents || []).map((a) => [a.agent_id || a.host_token, a]));
+  byId.set(agent.agent_id || agent.host_token, agent);
+  cfg.agents = [...byId.values()];
+  config.save(cfg);
+}
+
+// `setup` — install the service (if needed) + add one or more agents.
+async function run() {
+  console.log('\n  ClawLink Host Gateway — setup\n  ─────────────────────────────\n');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const cfg = config.load() || config.defaultConfig();
+  await ensureBridgeUrl(cfg, rl);
+  config.save(cfg);
+
+  let added = 0, more = true;
+  while (more) {
+    console.log('\n  Add an agent:');
+    const agent = await addAgentInteractive(cfg, rl);
+    if (agent) { saveAgent(cfg, agent); added++; }
+    more = (await ask(rl, '\n  Add another agent? (y/N)', 'N')).toLowerCase().startsWith('y');
+  }
+  rl.close();
+
+  if (added === 0) { console.log('\n  No agents added.\n'); return; }
+  console.log(`\n  ✓ Saved config (${config.CONFIG_PATH}, chmod 600)`);
+
+  const installed = installService();
+  console.log(installed
+    ? '  ✓ Installed + started the background service.'
+    : '  ⚠ Could not install a background service automatically.\n    Run it yourself with:  npx @claw-link/gateway-host start');
+  console.log('\n  Check status in ClawLink → Agents → Host Gateway (connection badge).\n');
+}
+
+// `install` — install the service only (configure agents later with `add-agent`).
+async function installOnly() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const cfg = config.load() || config.defaultConfig();
+  await ensureBridgeUrl(cfg, rl);
+  config.save(cfg);
+  rl.close();
+  const installed = installService();
+  console.log(installed ? '  ✓ Service installed.' : '  ⚠ Could not install the service automatically.');
+  console.log('  Next: npx @claw-link/gateway-host add-agent\n');
+}
+
+// `add-agent` — add one agent by token (no service reinstall).
+async function addAgentCmd() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const cfg = config.load() || config.defaultConfig();
+  await ensureBridgeUrl(cfg, rl);
+  const agent = await addAgentInteractive(cfg, rl);
+  rl.close();
+  if (agent) { saveAgent(cfg, agent); console.log(`\n  ✓ Added agent ${agent.agent_id}. Restart the service or it will pick it up shortly.\n`); }
+}
+
+function nodeBin() { return process.execPath; }
+function cliEntry() { return path.join(__dirname, '..', 'bin', 'cli.js'); }
+
+function installService() {
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') {
+      const plistDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+      fs.mkdirSync(plistDir, { recursive: true });
+      const plistPath = path.join(plistDir, `${SERVICE_LABEL}.plist`);
+      const logPath = path.join(config.HOME_DIR, 'host.log');
+      const plist = `<?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>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array><string>${nodeBin()}</string><string>${cliEntry()}</string><string>start</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logPath}</string>
+  <key>StandardErrorPath</key><string>${logPath}</string>
+</dict></plist>`;
+      fs.writeFileSync(plistPath, plist, { mode: 0o644 });
+      const uid = (execSafe('id -u') || '').trim();
+      execSafe(`launchctl bootout gui/${uid}/${SERVICE_LABEL}`);
+      if (execSafe(`launchctl bootstrap gui/${uid} "${plistPath}"`) === null) execSafe(`launchctl load "${plistPath}"`);
+      execSafe(`launchctl enable gui/${uid}/${SERVICE_LABEL}`);
+      execSafe(`launchctl kickstart -k "gui/${uid}/${SERVICE_LABEL}"`);
+      return true;
+    }
+    if (platform === 'linux') {
+      const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+      fs.mkdirSync(unitDir, { recursive: true });
+      const unit = `[Unit]
+Description=ClawLink Host Gateway
+After=network-online.target
+
+[Service]
+ExecStart=${nodeBin()} ${cliEntry()} start
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+      fs.writeFileSync(path.join(unitDir, 'clawlink-host.service'), unit, { mode: 0o644 });
+      execSafe('systemctl --user daemon-reload');
+      return execSafe('systemctl --user enable --now clawlink-host') !== null;
+    }
+    if (platform === 'win32') {
+      // Best effort: a scheduled task that runs at logon.
+      const taskCmd = `"${nodeBin()}" "${cliEntry()}" start`;
+      return execSafe(`schtasks /Create /F /SC ONLOGON /TN ClawLinkHost /TR ${JSON.stringify(taskCmd)}`) !== null;
+    }
+  } catch { /* fall through */ }
+  return false;
+}
+
+function status() {
+  const cfg = config.load();
+  if (!cfg) { console.log('Not configured. Run: npx @claw-link/gateway-host setup'); return; }
+  console.log(JSON.stringify(config.redacted(cfg), null, 2));
+}
+
+module.exports = { run, installOnly, addAgentCmd, status, installService, SERVICE_LABEL };

package/scripts/uninstall.js

@@ -0,0 +1,30 @@
+'use strict';
+// Stop + remove the ClawLink Host Gateway background service.
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { SERVICE_LABEL } = require('./install');
+
+function execSafe(cmd) { try { return execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString(); } catch { return null; } }
+
+function run() {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    const uid = (execSafe('id -u') || '').trim();
+    execSafe(`launchctl bootout gui/${uid}/${SERVICE_LABEL}`);
+    const plist = path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+    try { fs.unlinkSync(plist); } catch { /* ignore */ }
+  } else if (platform === 'linux') {
+    execSafe('systemctl --user disable --now clawlink-host');
+    try { fs.unlinkSync(path.join(os.homedir(), '.config', 'systemd', 'user', 'clawlink-host.service')); } catch { /* ignore */ }
+    execSafe('systemctl --user daemon-reload');
+  } else if (platform === 'win32') {
+    execSafe('schtasks /Delete /F /TN ClawLinkHost');
+  }
+  console.log('ClawLink Host Gateway service removed. Your config (~/.clawlink-host) was left intact —');
+  console.log('delete it manually to remove stored Host Tokens.');
+}
+
+module.exports = { run };

package/src/adapters/base.js

@@ -0,0 +1,115 @@
+'use strict';
+// Shared spawn helper for CLI-wrapping adapters.
+//
+// SECURITY: commands are ALWAYS invoked with an argv ARRAY and shell:false, so
+// untrusted prompt text can never be interpreted by a shell. Placeholders in the
+// configured args_template ({prompt}, {sessionId}, {systemPrompt}) are substituted
+// PER ARRAY ELEMENT — each becomes exactly one argv token, never concatenated into
+// a command string. The host only ever runs the configured runtime binary.
+
+const { spawn } = require('child_process');
+const logger = require('../logger');
+
+// A small set of flags we refuse to pass through (auto-approve / no-safety modes).
+const FORBIDDEN_FLAGS = [
+  '--yolo', '--dangerously-skip-permissions', '--no-sandbox', '--allow-all',
+  '--auto-approve', '--dangerously-allow', '--full-auto', '--yes-to-all',
+];
+
+function buildArgv(template, vars) {
+  const out = [];
+  for (const part of template) {
+    let v = String(part);
+    for (const [k, val] of Object.entries(vars)) {
+      v = v.split(`{${k}}`).join(val == null ? '' : String(val));
+    }
+    out.push(v);
+  }
+  // Defense in depth: strip any forbidden auto-approve flags an operator may have
+  // pasted into args_template.
+  return out.filter((a) => !FORBIDDEN_FLAGS.includes(a.toLowerCase()));
+}
+
+/**
+ * Run `binary` with an argv array; stream stdout lines as they arrive.
+ * Yields { type, content } events. Caller decides how to map/forward them.
+ *   onStdoutLine(line) -> array of events (so adapters can parse runtime markers)
+ * Resolves the final accumulated answer text from the events the parser tags
+ * as { type: 'chunk' }.
+ *
+ * This returns an async iterator of events. The prompt is passed via stdin when
+ * `stdin` is true (preferred — keeps it out of argv/process listings entirely).
+ */
+async function* spawnStreaming({ binary, argv, cwd, env, timeoutMs = 600000, stdinInput = null, parseLine }) {
+  if (!binary) throw new Error('no runtime binary configured');
+
+  const child = spawn(binary, argv, {
+    cwd: cwd || undefined,
+    env: { ...process.env, ...(env || {}) },
+    shell: false, // CRITICAL: never use a shell
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  let killed = false;
+  const timer = setTimeout(() => {
+    killed = true;
+    try { child.kill('SIGKILL'); } catch { /* already gone */ }
+  }, timeoutMs);
+
+  if (stdinInput != null) {
+    try { child.stdin.write(stdinInput); } catch { /* ignore */ }
+  }
+  try { child.stdin.end(); } catch { /* ignore */ }
+
+  const queue = [];
+  let resolveNext = null;
+  let done = false;
+  let exitErr = null;
+
+  const push = (evt) => {
+    if (!evt) return;
+    queue.push(evt);
+    if (resolveNext) { resolveNext(); resolveNext = null; }
+  };
+
+  let stdoutBuf = '';
+  const handleChunk = (buf) => {
+    stdoutBuf += buf.toString();
+    let idx;
+    while ((idx = stdoutBuf.indexOf('\n')) >= 0) {
+      const line = stdoutBuf.slice(0, idx);
+      stdoutBuf = stdoutBuf.slice(idx + 1);
+      for (const evt of (parseLine(line) || [])) push(evt);
+    }
+  };
+
+  child.stdout.on('data', handleChunk);
+  child.stderr.on('data', (b) => {
+    const text = logger.redact(b.toString()).trim();
+    if (text) push({ type: 'log', content: text.slice(0, 500) });
+  });
+
+  child.on('close', (code) => {
+    clearTimeout(timer);
+    if (stdoutBuf.trim()) for (const evt of (parseLine(stdoutBuf) || [])) push(evt);
+    if (killed) exitErr = new Error(`runtime timed out after ${timeoutMs}ms`);
+    else if (code !== 0) exitErr = new Error(`runtime exited with code ${code}`);
+    done = true;
+    if (resolveNext) { resolveNext(); resolveNext = null; }
+  });
+  child.on('error', (e) => {
+    clearTimeout(timer);
+    exitErr = e;
+    done = true;
+    if (resolveNext) { resolveNext(); resolveNext = null; }
+  });
+
+  while (true) {
+    if (queue.length > 0) { yield queue.shift(); continue; }
+    if (done) break;
+    await new Promise((r) => { resolveNext = r; });
+  }
+  if (exitErr) throw exitErr;
+}
+
+module.exports = { spawnStreaming, buildArgv, FORBIDDEN_FLAGS };

package/src/adapters/claude.js

@@ -0,0 +1,19 @@
+'use strict';
+// Anthropic Claude Code CLI in print/stream mode. Emits stream-json events we map
+// to tool/chunk; captures Claude's session_id for --resume on the next turn.
+// VERIFY exact flags against the installed CLI version.
+const { makeCliAdapter } = require('./cli');
+
+module.exports = makeCliAdapter({
+  name: 'claude',
+  binaries: ['claude'],
+  streamJson: true,
+  // Prompt via stdin keeps it out of argv/process listings.
+  promptViaStdin: true,
+  defaultArgs: (_fullPrompt, resumeId) => [
+    '-p',
+    '--output-format', 'stream-json',
+    '--verbose',
+    ...(resumeId ? ['--resume', resumeId] : []),
+  ],
+});

package/src/adapters/cli.js

@@ -0,0 +1,110 @@
+'use strict';
+// Factory for CLI-wrapping adapters (hermes / claude / codex / cursor). Each
+// runtime supplies a default binary, a default argv template, and a line parser.
+// The operator can override binary + args_template in config.
+
+const fs = require('fs');
+const { spawnStreaming, buildArgv } = require('./base');
+const sessionStore = require('../session-store');
+
+// Generic parser: each non-empty stdout line is answer text.
+function genericLineParser(line) {
+  const t = line.replace(/\r$/, '');
+  if (t.trim() === '') return [];
+  return [{ type: 'chunk', content: t + '\n' }];
+}
+
+// Claude Code `--output-format stream-json`: one JSON object per line.
+// Maps tool_use → tool events, assistant text → chunks, captures session_id.
+function makeStreamJsonParser(capture) {
+  return function parse(line) {
+    const s = line.trim();
+    if (!s || s[0] !== '{') return [];
+    let ev;
+    try { ev = JSON.parse(s); } catch { return [{ type: 'chunk', content: line + '\n' }]; }
+    const out = [];
+    if (ev.session_id && capture) capture.sessionId = ev.session_id;
+    const type = ev.type || ev.event;
+    if (type === 'assistant' || type === 'message') {
+      const content = ev.message?.content ?? ev.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text' && block.text) { out.push({ type: 'chunk', content: block.text }); capture.sawText = true; }
+          else if (block.type === 'tool_use') out.push({ type: 'tool', content: block.name || 'tool' });
+        }
+      } else if (typeof content === 'string') {
+        out.push({ type: 'chunk', content }); capture.sawText = true;
+      }
+    } else if (type === 'tool_use' && ev.name) {
+      out.push({ type: 'tool', content: ev.name });
+    } else if (type === 'result' && typeof ev.result === 'string') {
+      // `result` repeats the full answer — only use it if we never saw streamed
+      // assistant text (otherwise it duplicates, e.g. "PONGPONG").
+      if (!capture.sawText) { out.push({ type: 'chunk', content: ev.result }); capture.sawText = true; }
+    }
+    return out;
+  };
+}
+
+/**
+ * @param cfg { name, binaries:[], defaultArgs(fullPrompt, resumeId):[], streamJson?:bool,
+ *              promptViaStdin?:bool, timeoutMs?:number }
+ */
+function makeCliAdapter(cfg) {
+  return {
+    name: cfg.name,
+    binaries: cfg.binaries,
+
+    async *run({ agent, job, logger }) {
+      const binary = agent.binary || cfg.binaries[0];
+      const userPrompt = job.content || '';
+      const systemPrompt = job.system_prompt || '';
+      const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\nUser request:\n${userPrompt}` : userPrompt;
+      const clSession = job.session_key || job.session_id || null;
+      const resumeId = clSession ? sessionStore.get(cfg.name, clSession) : null;
+      const timeoutMs = cfg.timeoutMs || Number(process.env.CLAWHOST_TIMEOUT_MS) || 600000;
+
+      // Run inside the agent's workspace/scratch dir. Create it if missing so the
+      // spawn never fails with ENOENT (coding workspaces are validated at setup).
+      try { fs.mkdirSync(agent.work_dir, { recursive: true }); } catch { /* ignore */ }
+
+      const argvFor = (rid) => Array.isArray(agent.args_template)
+        ? buildArgv(agent.args_template, { prompt: fullPrompt, sessionId: rid || '', systemPrompt })
+        : cfg.defaultArgs(fullPrompt, rid, cfg.promptViaStdin);
+
+      let emittedAny = false;
+      const runOnce = async function* (rid) {
+        const capture = {};
+        const parseLine = cfg.streamJson ? makeStreamJsonParser(capture) : genericLineParser;
+        for await (const evt of spawnStreaming({
+          binary, argv: argvFor(rid), cwd: agent.work_dir, timeoutMs,
+          stdinInput: cfg.promptViaStdin ? fullPrompt : null, parseLine,
+        })) {
+          if (evt.type === 'chunk') emittedAny = true;
+          yield evt;
+        }
+        // Persist the captured session id only on a successful turn.
+        if (capture.sessionId && clSession) {
+          try { sessionStore.set(cfg.name, clSession, capture.sessionId); }
+          catch (e) { logger.warn('session-store write failed:', e.message); }
+        }
+      };
+
+      try {
+        yield* runOnce(resumeId);
+      } catch (e) {
+        // A stale/invalid --resume id shouldn't break the conversation: if it failed
+        // before producing any output, drop the session and retry fresh.
+        if (resumeId && !emittedAny) {
+          logger.warn(`${cfg.name}: resume failed (${e.message}); retrying with a fresh session`);
+          try { sessionStore.set(cfg.name, clSession, null); } catch { /* ignore */ }
+          yield* runOnce(null);
+        } else {
+          throw e;
+        }
+      }
+    },
+  };
+}
+
+module.exports = { makeCliAdapter, genericLineParser, makeStreamJsonParser };

package/src/adapters/codex.js

@@ -0,0 +1,13 @@
+'use strict';
+// OpenAI Codex CLI, non-interactive. VERIFY exact subcommand/flags + resume
+// mechanism against the installed CLI; operators can override args_template.
+const { makeCliAdapter } = require('./cli');
+
+module.exports = makeCliAdapter({
+  name: 'codex',
+  binaries: ['codex'],
+  promptViaStdin: false,
+  // `--` ends option parsing so an untrusted prompt starting with '-' is treated
+  // as a positional argument, never as a flag (argument-injection hardening).
+  defaultArgs: (fullPrompt) => ['exec', '--', fullPrompt],
+});

package/src/adapters/cursor.js

@@ -0,0 +1,11 @@
+'use strict';
+// Cursor agent CLI (headless). VERIFY exact binary name (`cursor-agent`?) and
+// headless/print + resume flags; operators can override binary + args_template.
+const { makeCliAdapter } = require('./cli');
+
+module.exports = makeCliAdapter({
+  name: 'cursor',
+  binaries: ['cursor-agent', 'cursor'],
+  promptViaStdin: false,
+  defaultArgs: (fullPrompt) => ['-p', fullPrompt],
+});

package/src/adapters/hermes.js

@@ -0,0 +1,14 @@
+'use strict';
+// Nous Research Hermes — driven by `hermes chat -q "<prompt>"` (full agent: SOUL,
+// memory, skills). Sessions are local SQLite, resumable by id via --resume.
+// VERIFY: exact streaming behaviour of `hermes chat`; `hermes -z` is final-only.
+const { makeCliAdapter } = require('./cli');
+
+module.exports = makeCliAdapter({
+  name: 'hermes',
+  binaries: ['hermes'],
+  defaultArgs: (fullPrompt, resumeId) => [
+    'chat', '-q', fullPrompt,
+    ...(resumeId ? ['--resume', resumeId] : []),
+  ],
+});

package/src/adapters/index.js

@@ -0,0 +1,19 @@
+'use strict';
+// Runtime → adapter registry. Each adapter exposes `run(ctx)` yielding
+// { type:'chunk'|'log'|'status'|'tool', content } events.
+
+const adapters = {
+  openclaw: require('./openclaw'),
+  hermes: require('./hermes'),
+  claude: require('./claude'),
+  codex: require('./codex'),
+  cursor: require('./cursor'),
+};
+
+function getAdapter(runtime) {
+  const a = adapters[runtime];
+  if (!a) throw new Error(`unknown runtime '${runtime}'`);
+  return a;
+}
+
+module.exports = { adapters, getAdapter };

package/src/adapters/openclaw.js

@@ -0,0 +1,59 @@
+'use strict';
+// OpenClaw adapter — talks to the LOCAL OpenClaw gateway over localhost so an
+// OpenClaw agent can run through the host worker (no public Funnel needed). It's
+// the only HTTP adapter; the others wrap CLIs. Reads url/token from config or
+// ~/.openclaw/openclaw.json.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function resolveLocalGateway(agent) {
+  let url = agent.local_gateway_url;
+  let token = agent.local_gateway_token;
+  if (!url || !token) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.openclaw', 'openclaw.json'), 'utf8'));
+      token = token || cfg?.gateway?.auth?.token || null;
+    } catch { /* ignore */ }
+  }
+  url = (url || 'http://localhost:3000').replace(/\/+$/, '');
+  return { url, token };
+}
+
+module.exports = {
+  name: 'openclaw',
+  binaries: [],
+
+  async *run({ agent, job }) {
+    const { url, token } = resolveLocalGateway(agent);
+    const messages = [];
+    if (job.system_prompt) messages.push({ role: 'system', content: job.system_prompt });
+    messages.push({ role: 'user', content: job.content || '' });
+
+    const timeoutMs = Number(process.env.CLAWHOST_TIMEOUT_MS) || 600000; // 10-min cap
+    const res = await fetch(`${url}/v1/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify({
+        model: agent.openclaw_agent_id ? `openclaw/${agent.openclaw_agent_id}` : 'openclaw',
+        messages,
+        stream: false,
+        user: job.session_key || job.session_id || undefined,
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) throw new Error(`local OpenClaw gateway HTTP ${res.status}`);
+    const data = await res.json();
+    const content = data?.choices?.[0]?.message?.content ?? '';
+    const toolCalls = data?.choices?.[0]?.message?.tool_calls ?? [];
+    for (const tc of toolCalls) {
+      const name = tc.function?.name || tc.name;
+      if (name) yield { type: 'tool', content: name };
+    }
+    if (content) yield { type: 'chunk', content };
+  },
+};

package/src/bridge.js

@@ -0,0 +1,61 @@
+'use strict';
+// Outbound client for the host-bridge edge function. Every call carries the
+// agent's Host Token as a Bearer credential. Uses global fetch (Node 18+).
+
+const logger = require('./logger');
+const { machineId } = require('./machine');
+
+class Bridge {
+  constructor(bridgeUrl, agent, instanceId) {
+    this.url = bridgeUrl;
+    this.agentId = agent.agent_id || null; // may be unknown until register resolves it
+    this.token = agent.host_token;
+    this.instanceId = instanceId;
+    this.machineId = machineId();
+  }
+
+  async _post(action, extra) {
+    const res = await fetch(this.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.token}`,
+      },
+      // agent_id is only a hint (the token resolves the agent); machine_id binds the host.
+      body: JSON.stringify({ action, agent_id: this.agentId || undefined, machine_id: this.machineId, ...extra }),
+    });
+    let data = null;
+    try { data = await res.json(); } catch { /* non-json */ }
+    if (!res.ok) {
+      const msg = (data && data.error) || `host-bridge ${action} → HTTP ${res.status}`;
+      const err = new Error(msg);
+      err.status = res.status;
+      throw err;
+    }
+    return data;
+  }
+
+  register(runtime, version) { return this._post('register', { runtime, version }); }
+  heartbeat() { return this._post('heartbeat', {}); }
+  claim() { return this._post('claim', { instance_id: this.instanceId }); }
+  stream(jobId, seq, type, content) { return this._post('stream', { job_id: jobId, seq, type, content }); }
+  complete(jobId, finalContent, metadata) { return this._post('complete', { job_id: jobId, final_content: finalContent, metadata: metadata || {} }); }
+  fail(jobId, error) { return this._post('fail', { job_id: jobId, error: String(error).slice(0, 1000) }); }
+}
+
+// Retry wrapper for transient network errors (not auth errors).
+async function withRetry(fn, attempts = 3) {
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try { return await fn(); }
+    catch (e) {
+      lastErr = e;
+      if (e.status === 401 || e.status === 403 || e.status === 404) throw e; // don't retry auth/not-found
+      await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+    }
+  }
+  logger.warn('bridge call failed after retries:', lastErr && lastErr.message);
+  throw lastErr;
+}
+
+module.exports = { Bridge, withRetry };

package/src/config.js

@@ -0,0 +1,84 @@
+'use strict';
+// Config load/save for the ClawLink Host Gateway.
+// Stored at ~/.clawlink-host/config.json with 0600 perms (secrets live here).
+// The host only ever talks OUTBOUND to the host-bridge edge function using each
+// agent's Host Token — there is no Supabase key and no inbound listener.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOME_DIR = path.join(os.homedir(), '.clawlink-host');
+const CONFIG_PATH = path.join(HOME_DIR, 'config.json');
+
+// Runtimes whose CLI runs inside a project WORKSPACE directory (coding agents).
+// OpenClaw (HTTP) and Hermes (~/.hermes context) don't need one.
+const WORKSPACE_RUNTIMES = ['claude', 'codex', 'cursor'];
+
+function expandHome(p) {
+  if (typeof p !== 'string' || !p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function ensureHomeDir() {
+  fs.mkdirSync(HOME_DIR, { recursive: true });
+  try { fs.chmodSync(HOME_DIR, 0o700); } catch { /* best effort (e.g. Windows) */ }
+}
+
+function defaultConfig() {
+  return {
+    bridge_url: '',
+    instance_id: require('crypto').randomUUID(),
+    poll_interval_ms: 1500,
+    heartbeat_ms: 10000,
+    agents: [],
+  };
+}
+
+function load() {
+  if (!fs.existsSync(CONFIG_PATH)) return null;
+  const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+  return JSON.parse(raw);
+}
+
+function save(cfg) {
+  ensureHomeDir();
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort */ }
+}
+
+// Validate and normalize one agent binding. Only the token is required — the
+// agent_id and runtime are resolved from Supabase at register (the dashboard is
+// the source of truth) and cached here by `add-agent`.
+function normalizeAgent(a) {
+  if (!a.host_token) throw new Error('host_token required for each agent');
+  return {
+    agent_id: a.agent_id || null,
+    host_token: a.host_token,
+    runtime: a.runtime || null,
+    binary: a.binary || null,
+    args_template: Array.isArray(a.args_template) ? a.args_template : null,
+    local_gateway_url: a.local_gateway_url || null,
+    local_gateway_token: a.local_gateway_token || null,
+    openclaw_agent_id: a.openclaw_agent_id || null,
+    // Coding runtimes (claude/codex/cursor) run inside this WORKSPACE directory;
+    // other runtimes get a private scratch dir (resolved once agent_id is known).
+    work_dir: expandHome(a.work_dir) || null,
+    concurrency: Number(a.concurrency) > 0 ? Number(a.concurrency) : 1,
+    rate_limit_per_min: Number(a.rate_limit_per_min) > 0 ? Number(a.rate_limit_per_min) : 60,
+  };
+}
+
+// Returns a copy with all secrets redacted — safe to print/log.
+function redacted(cfg) {
+  const clone = JSON.parse(JSON.stringify(cfg));
+  for (const a of clone.agents || []) {
+    if (a.host_token) a.host_token = `…${String(a.host_token).slice(-4)}`;
+    if (a.local_gateway_token) a.local_gateway_token = '***';
+  }
+  return clone;
+}
+
+module.exports = { HOME_DIR, CONFIG_PATH, WORKSPACE_RUNTIMES, expandHome, ensureHomeDir, defaultConfig, load, save, normalizeAgent, redacted };

package/src/detect.js

@@ -0,0 +1,35 @@
+'use strict';
+// Detect which runtime CLIs are installed, to pre-fill the setup wizard.
+
+const { execSync } = require('child_process');
+
+function which(cmd) {
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try {
+    const out = execSync(probe, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    return out.split(/\r?\n/)[0] || null;
+  } catch { return null; }
+}
+
+const RUNTIME_BINARIES = {
+  openclaw: ['openclaw'],
+  hermes: ['hermes'],
+  claude: ['claude'],
+  codex: ['codex'],
+  cursor: ['cursor-agent', 'cursor'],
+};
+
+// Returns { runtime: resolvedPath|null }
+function detectRuntimes() {
+  const found = {};
+  for (const [runtime, bins] of Object.entries(RUNTIME_BINARIES)) {
+    found[runtime] = null;
+    for (const b of bins) {
+      const p = which(b);
+      if (p) { found[runtime] = p; break; }
+    }
+  }
+  return found;
+}
+
+module.exports = { detectRuntimes, which, RUNTIME_BINARIES };

package/src/logger.js

@@ -0,0 +1,28 @@
+'use strict';
+// Redaction-aware logger. Every secret registered here is replaced with *** in
+// ALL output (including adapter stderr passthrough) so tokens never hit the logs.
+
+const secrets = new Set();
+
+function addSecret(s) {
+  if (s && typeof s === 'string' && s.length >= 6) secrets.add(s);
+}
+
+function redact(line) {
+  let out = String(line);
+  for (const s of secrets) {
+    if (!s) continue;
+    out = out.split(s).join('***');
+  }
+  return out;
+}
+
+function ts() {
+  return new Date().toISOString();
+}
+
+function info(...args) { console.log(`[claw-host ${ts()}]`, redact(args.join(' '))); }
+function warn(...args) { console.warn(`[claw-host ${ts()}] WARN`, redact(args.join(' '))); }
+function error(...args) { console.error(`[claw-host ${ts()}] ERROR`, redact(args.join(' '))); }
+
+module.exports = { addSecret, redact, info, warn, error };

package/src/machine.js

@@ -0,0 +1,30 @@
+'use strict';
+// Stable machine fingerprint for host binding. Derived from the host's physical
+// MAC address(es) + hostname, then hashed — we send only the HASH to ClawLink, so
+// raw MACs never leave the machine. Supabase binds this on first connect; after
+// that, only this machine may act for the agent (a stolen token from elsewhere
+// fails the binding check).
+
+const os = require('os');
+const crypto = require('crypto');
+
+function macAddresses() {
+  const macs = [];
+  const ifaces = os.networkInterfaces();
+  for (const name of Object.keys(ifaces)) {
+    for (const ni of ifaces[name] || []) {
+      if (ni.internal) continue;
+      if (!ni.mac || ni.mac === '00:00:00:00:00:00') continue;
+      macs.push(ni.mac.toLowerCase());
+    }
+  }
+  return [...new Set(macs)].sort();
+}
+
+function machineId() {
+  const macs = macAddresses();
+  const basis = (macs.length ? macs.join(',') : 'no-mac') + '|' + os.hostname();
+  return crypto.createHash('sha256').update(basis).digest('hex');
+}
+
+module.exports = { machineId };

package/src/session-store.js

@@ -0,0 +1,35 @@
+'use strict';
+// Maps a ClawLink session id → the runtime CLI's own resumable session id, so
+// multi-turn conversations keep context (e.g. `hermes chat --resume <id>`,
+// `claude --resume <id>`). Persisted to ~/.clawlink-host/sessions.json (0600).
+
+const fs = require('fs');
+const path = require('path');
+const { HOME_DIR, ensureHomeDir } = require('./config');
+
+const STORE_PATH = path.join(HOME_DIR, 'sessions.json');
+
+function read() {
+  try { return JSON.parse(fs.readFileSync(STORE_PATH, 'utf8')); } catch { return {}; }
+}
+function write(obj) {
+  ensureHomeDir();
+  fs.writeFileSync(STORE_PATH, JSON.stringify(obj, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(STORE_PATH, 0o600); } catch { /* best effort */ }
+}
+
+// Composite key so the same ClawLink session under different runtimes never clashes.
+function keyFor(runtime, clawlinkSessionId) {
+  return `${runtime}:${clawlinkSessionId || 'default'}`;
+}
+
+function get(runtime, clawlinkSessionId) {
+  return read()[keyFor(runtime, clawlinkSessionId)] || null;
+}
+function set(runtime, clawlinkSessionId, runtimeSessionId) {
+  const all = read();
+  all[keyFor(runtime, clawlinkSessionId)] = runtimeSessionId;
+  write(all);
+}
+
+module.exports = { get, set };

package/src/worker.js

@@ -0,0 +1,116 @@
+'use strict';
+// The long-lived worker. For each configured agent it registers with host-bridge,
+// heartbeats, and polls `claim` for jobs (RLS blocks anon Realtime on the queue,
+// so short-polling — token-only, outbound — is both simplest and most secure).
+// Each job runs the agent's runtime adapter; output is streamed back chunk-by-chunk.
+
+const path = require('path');
+const logger = require('./logger');
+const config = require('./config');
+const { Bridge, withRetry } = require('./bridge');
+const { getAdapter } = require('./adapters');
+const { detectRuntimes } = require('./detect');
+
+const VERSION = (() => { try { return require('../package.json').version; } catch { return '0.0.0'; } })();
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let stopping = false;
+
+async function processJob(bridge, agentCfg, job) {
+  logger.info(`job ${job.id} claimed (${agentCfg.runtime})`);
+  const adapter = getAdapter(agentCfg.runtime);
+  let seq = 0;
+  let finalText = '';
+  try {
+    for await (const evt of adapter.run({ agent: agentCfg, job, logger })) {
+      if (!evt || !evt.type) continue;
+      if (evt.type === 'chunk') finalText += evt.content || '';
+      try { await bridge.stream(job.id, seq++, evt.type, String(evt.content ?? '')); }
+      catch (e) { logger.warn(`stream seq ${seq} failed: ${e.message}`); }
+    }
+    await withRetry(() => bridge.complete(job.id, finalText));
+    logger.info(`job ${job.id} done (${finalText.length} chars)`);
+  } catch (e) {
+    logger.error(`job ${job.id} failed: ${e.message}`);
+    try { await bridge.fail(job.id, e.message); } catch { /* ignore */ }
+  }
+}
+
+async function runAgentLoop(agentCfg, cfg) {
+  const bridge = new Bridge(cfg.bridge_url, agentCfg, cfg.instance_id);
+  logger.addSecret(agentCfg.host_token);
+  if (agentCfg.local_gateway_token) logger.addSecret(agentCfg.local_gateway_token);
+
+  try {
+    // Token-only register: the server resolves agent_id + runtime (dashboard is
+    // the source of truth) and binds this machine on first connect.
+    const resp = await withRetry(() => bridge.register(agentCfg.runtime, VERSION));
+    agentCfg.agent_id = resp.agent_id || agentCfg.agent_id;
+    if (resp.runtime) agentCfg.runtime = resp.runtime;
+    bridge.agentId = agentCfg.agent_id;
+
+    // Resolve binary + work_dir now that the runtime is known.
+    if (!agentCfg.binary && agentCfg.runtime !== 'openclaw') {
+      const found = detectRuntimes()[agentCfg.runtime];
+      if (found) agentCfg.binary = found;
+      else logger.warn(`no '${agentCfg.runtime}' binary found on PATH — set "binary" in config for ${agentCfg.agent_id}`);
+    }
+    if (!agentCfg.work_dir) agentCfg.work_dir = path.join(config.HOME_DIR, 'work', agentCfg.agent_id || 'default');
+
+    logger.info(`registered ${agentCfg.agent_id} as '${agentCfg.runtime}'`);
+  } catch (e) {
+    logger.error(`register failed — check the Host Token & machine binding (rotate the token in the dashboard to re-bind a new machine). ${e.message}`);
+    return; // bad token / machine mismatch: stop this agent's loop (don't spin)
+  }
+
+  const hb = setInterval(() => { bridge.heartbeat().catch(() => {}); }, cfg.heartbeat_ms || 10000);
+
+  let inFlight = 0;
+  const starts = []; // job start timestamps for the rolling rate-limit window
+
+  while (!stopping) {
+    const now = Date.now();
+    while (starts.length && now - starts[0] > 60000) starts.shift();
+
+    const canRun = inFlight < agentCfg.concurrency && starts.length < agentCfg.rate_limit_per_min;
+    if (canRun) {
+      let job = null;
+      try { const r = await bridge.claim(); job = r && r.job; }
+      catch (e) { logger.warn(`claim failed (${agentCfg.agent_id}): ${e.message}`); }
+      if (job) {
+        inFlight++; starts.push(Date.now());
+        processJob(bridge, agentCfg, job).finally(() => { inFlight--; });
+        continue; // try to fill remaining concurrency immediately
+      }
+    }
+    await sleep(cfg.poll_interval_ms || 1500);
+  }
+
+  clearInterval(hb);
+}
+
+async function startWorker() {
+  const raw = config.load();
+  if (!raw) {
+    logger.error('No config found. Run: npx @claw-link/gateway-host setup');
+    process.exit(1);
+  }
+  if (!raw.bridge_url) { logger.error('config.bridge_url is missing.'); process.exit(1); }
+  const agents = (raw.agents || []).map(config.normalizeAgent);
+  if (agents.length === 0) { logger.error('No agents configured. Run setup again.'); process.exit(1); }
+
+  logger.info(`ClawLink Host Gateway v${VERSION} — ${agents.length} agent(s): ${agents.map((a) => `${(a.agent_id || 'pending').slice(0, 8)}…(${a.runtime || 'resolving'})`).join(', ')}`);
+
+  const onStop = (sig) => {
+    if (stopping) return;
+    stopping = true;
+    logger.info(`${sig} received — draining in-flight jobs…`);
+    setTimeout(() => process.exit(0), 8000).unref();
+  };
+  process.on('SIGINT', () => onStop('SIGINT'));
+  process.on('SIGTERM', () => onStop('SIGTERM'));
+
+  await Promise.all(agents.map((a) => runAgentLoop(a, raw)));
+}
+
+module.exports = { startWorker };