@claw-link/gateway-host 0.1.2 → 0.2.0

package/README.md

@@ -43,23 +43,44 @@ Each runtime's flags can be overridden per-agent via `args_template` in the conf
 (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.
+**Workspace & baseline files** — each agent gets a managed workspace at
+`~/.clawlink-host/workspace/<runtime>/agents/<agent_id>` by default (Claude/Codex/Cursor
+can be pointed at your own project folder instead). When you add an agent, if the
+runtime's **baseline files are missing**, `add-agent` asks before adding them and
+**never overwrites** existing files — so pointing an agent at a real project is safe.
+Baselines per runtime:
+
+| Runtime | Baseline files |
+|---------|----------------|
+| Claude  | `CLAUDE.md`, **`.claude/settings.json`** (pins a default `model` — `sonnet` — so the agent never silently falls back to a weaker model) |
+| Codex   | `AGENTS.md` |
+| Cursor  | `AGENTS.md`, **`.cursor/rules/clawlink.mdc`** (always-applied agent rules) |
+| OpenClaw / Hermes | `README.md` (their real config lives in `~/.openclaw` / `~/.hermes`) |
+
+Change the Claude model by editing `.claude/settings.json` (e.g. `"model": "opus"`).
+For Codex/Cursor, set the model via their CLI (`args_template` in the config, or the
+tool's own settings).
 
 ## Commands
 
+After install the `clhost` command is available (aliases: `gateway-host`, `claw-host`):
+
 ```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
+clhost install      # install the background service (one-time)
+clhost add-agent    # add an agent by pasting its Host Token
+clhost rm-agent <id># remove a mapped agent
+clhost agents       # list mapped agents
+clhost status       # bridge + service state + mapped agents
+clhost start        # start the background service
+clhost stop         # stop the background service
+clhost restart      # restart the service (apply config changes)
+clhost rotate       # rotate a Host Token / move to a new machine
+clhost uninstall    # stop + remove the service
+clhost run          # (internal) run the worker in the foreground — the service uses this
 ```
 
+(Use `npx @claw-link/gateway-host <command>` before a global install.)
+
 ## Config
 
 `~/.clawlink-host/config.json` (chmod 600):

package/bin/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 'use strict';
-// ClawLink Host Gateway CLI. Commands: setup | start | status | rotate | uninstall
+// ClawLink Host Gateway CLI (alias: clhost).
+// Service control: start | stop | restart   ·   internal worker entrypoint: run
 
 const cmd = (process.argv[2] || '').toLowerCase();
 
 async function main() {
   switch (cmd) {
-    case 'start':
+    // Internal entrypoint the background service runs — the foreground worker loop.
+    case 'run':
       return require('../src/worker').startWorker();
 
     case 'setup':
@@ -20,6 +22,21 @@ async function main() {
     case 'add':
       return require('../scripts/install').addAgentCmd();
 
+    case 'rm-agent':
+    case 'remove-agent':
+    case 'rm':
+      return require('../scripts/install').removeAgentCmd();
+
+    case 'agents':
+    case 'list':
+      return require('../scripts/install').listAgents();
+
+    // Control the installed background service.
+    case 'start':
+    case 'stop':
+    case 'restart':
+      return require('../scripts/install').serviceControlCmd(cmd);
+
     case 'uninstall':
       return require('../scripts/uninstall').run();
 
@@ -29,10 +46,10 @@ async function main() {
     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.',
+        '  1. ClawLink → Agents → your agent → Host Gateway → "Rotate token"',
+        '     (this clears the machine binding so a new host can claim it).',
+        '  2. Copy the new token, then run: clhost add-agent',
+        '     The old token + old machine stop working immediately.',
       ].join('\n'));
       return;
 
@@ -40,21 +57,26 @@ async function main() {
     case '-h':
     case 'help':
       console.log([
-        'ClawLink Host Gateway',
+        'ClawLink Host Gateway (clhost)',
         '',
-        'Usage: gateway-host <command>',
+        'Usage: clhost <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',
+        '  rm-agent    Remove a mapped agent (clhost rm-agent <id>)',
+        '  agents      List mapped agents',
+        '  status      Show bridge, service state, and mapped agents',
+        '  start       Start the background service',
+        '  stop        Stop the background service',
+        '  restart     Restart the background service (apply config changes)',
+        '  setup       install + add-agent in one flow',
         '  rotate      How to rotate a Host Token / move to a new machine',
         '  uninstall   Stop + remove the background service',
+        '  run         (internal) run the worker in the foreground — used by the service',
       ].join('\n'));
       return;
 
     default:
-      console.error(`Unknown command '${cmd}'. Try: gateway-host help`);
+      console.error(`Unknown command '${cmd}'. Try: clhost help`);
       process.exit(1);
   }
 }

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@claw-link/gateway-host",
-  "version": "0.1.2",
+  "version": "0.2.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.",
   "homepage": "https://claw-link.co",
   "bin": {
+    "clhost": "bin/cli.js",
     "gateway-host": "bin/cli.js",
     "claw-host": "bin/cli.js"
   },
   "scripts": {
-    "start": "node bin/cli.js start"
+    "start": "node bin/cli.js run"
   },
   "engines": {
     "node": ">=18"
@@ -17,6 +18,7 @@
     "bin/",
     "scripts/",
     "src/",
+    "templates/",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -31,5 +33,8 @@
     "ai-agent",
     "gateway"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@claw-link/gateway-host": "^0.1.3"
+  }
 }

package/scripts/install.js

@@ -11,9 +11,9 @@ const { execSync } = require('child_process');
 const config = require('../src/config');
 const { detectRuntimes } = require('../src/detect');
 const { Bridge } = require('../src/bridge');
+const scaffold = require('../src/scaffold');
 
 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';
 
@@ -22,10 +22,10 @@ function ask(rl, q, 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`;
+// The bridge URL is baked in (config.DEFAULT_BRIDGE_URL / CLAWLINK_BRIDGE_URL env)
+// — operators never type it. We just ensure it's populated.
+function ensureBridgeUrl(cfg) {
+  if (!cfg.bridge_url) cfg.bridge_url = config.DEFAULT_BRIDGE_URL;
 }
 
 // Add one agent with ONLY its Host Token. The token resolves the agent + runtime
@@ -47,23 +47,40 @@ async function addAgentInteractive(cfg, rl) {
   console.log(`  ✓ Agent ${resp.agent_id} — runtime: ${runtime}`);
 
   const detected = detectRuntimes();
+  const defaultWs = config.defaultWorkDir(runtime, resp.agent_id);
+
   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);
+    agent.work_dir = defaultWs;
   } else {
-    console.log(`    using ${runtime}: ${detected[runtime]}`);
+    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. Default to the managed
+    // workspace/<runtime>/agents/<id> folder; an explicit project path is also fine.
+    if (config.WORKSPACE_RUNTIMES.includes(runtime)) {
+      let ws = '';
+      while (!ws) {
+        ws = await ask(rl, `  Workspace directory for ${runtime}`, defaultWs);
+        const resolved = config.expandHome(ws);
+        if (resolved !== defaultWs && !fs.existsSync(resolved)) { console.log(`  ⚠ ${ws} does not exist.`); ws = ''; }
+      }
+      agent.work_dir = ws;
+    } else {
+      agent.work_dir = defaultWs; // hermes — runs in its own ~/.hermes context
+    }
   }
 
-  // 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 = ''; }
+  // Baseline scaffolding — opt-in, only when the files are missing, never overwrites.
+  const wd = config.expandHome(agent.work_dir);
+  const missing = scaffold.missingBaselineFiles(runtime, wd);
+  if (missing.length) {
+    const ans = await ask(rl, `  Baseline ${runtime} agent files are missing in ${agent.work_dir} (${missing.join(', ')}). Add them? (Y/n)`, 'Y');
+    if (ans.toLowerCase().startsWith('y')) {
+      const copied = scaffold.copyBaseline(runtime, wd);
+      console.log(`  ✓ Added baseline file(s): ${copied.join(', ')}`);
     }
-    agent.work_dir = ws;
   }
   return agent;
 }
@@ -80,7 +97,7 @@ 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);
+  ensureBridgeUrl(cfg);
   config.save(cfg);
 
   let added = 0, more = true;
@@ -98,30 +115,99 @@ async function run() {
   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');
+    : '  ⚠ Could not install a background service automatically.\n    Run it yourself with:  clhost run');
   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);
+  ensureBridgeUrl(cfg);
   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).
+// `add-agent` — add one agent by token, then restart the service to pick it up.
 async function addAgentCmd() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const cfg = config.load() || config.defaultConfig();
-  await ensureBridgeUrl(cfg, rl);
+  ensureBridgeUrl(cfg);
   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`); }
+  if (agent) {
+    saveAgent(cfg, agent);
+    const restarted = serviceControl('restart');
+    console.log(`\n  ✓ Added agent ${agent.agent_id} (${agent.runtime}).` +
+      (restarted ? ' Service restarted.' : ' Run `clhost restart` (or start) to apply.') + '\n');
+  }
+}
+
+// `rm-agent [id-or-prefix]` — remove a mapped agent from the config.
+async function removeAgentCmd() {
+  const cfg = config.load();
+  if (!cfg || !(cfg.agents || []).length) { console.log('No agents configured.'); return; }
+  let target = (process.argv[3] || '').trim();
+  if (!target) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    printAgents(cfg);
+    target = await ask(rl, '\n  Agent ID (or prefix) to remove');
+    rl.close();
+  }
+  if (!target) { console.log('  (nothing removed)'); return; }
+  const before = cfg.agents.length;
+  cfg.agents = cfg.agents.filter((a) => !(a.agent_id && (a.agent_id === target || a.agent_id.startsWith(target))));
+  if (cfg.agents.length === before) { console.log(`  No agent matched '${target}'.`); return; }
+  config.save(cfg);
+  const restarted = serviceControl('restart');
+  console.log(`  ✓ Removed agent '${target}'.` + (restarted ? ' Service restarted.' : ' Run `clhost restart` to apply.'));
+}
+
+function printAgents(cfg) {
+  const agents = (cfg && cfg.agents) || [];
+  if (!agents.length) { console.log('  No agents mapped. Run: clhost add-agent'); return; }
+  console.log(`  ${agents.length} agent(s) mapped:`);
+  for (const a of agents) {
+    const id = (a.agent_id || '(unresolved)').slice(0, 8);
+    const tok = a.host_token ? `…${String(a.host_token).slice(-4)}` : '—';
+    console.log(`    • ${id}…  runtime=${a.runtime || 'pull'}  token=${tok}` + (a.work_dir ? `  work=${a.work_dir}` : ''));
+  }
+}
+
+// `agents` — list mapped agents.
+function listAgents() { printAgents(config.load() || {}); }
+
+// `start | stop | restart` — control the installed background service.
+function serviceControl(action) {
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') {
+      const uid = (execSafe('id -u') || '').trim();
+      const label = SERVICE_LABEL;
+      if (action === 'restart') return execSafe(`launchctl kickstart -k "gui/${uid}/${label}"`) !== null;
+      if (action === 'stop')    return execSafe(`launchctl bootout "gui/${uid}/${label}"`) !== null || execSafe(`launchctl kill SIGTERM "gui/${uid}/${label}"`) !== null;
+      if (action === 'start') {
+        const plist = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+        execSafe(`launchctl bootstrap "gui/${uid}" "${plist}"`);
+        return execSafe(`launchctl kickstart "gui/${uid}/${label}"`) !== null;
+      }
+    }
+    if (platform === 'linux') {
+      return execSafe(`systemctl --user ${action} clawlink-host`) !== null;
+    }
+    if (platform === 'win32') {
+      if (action === 'stop')    return execSafe('schtasks /End /TN ClawLinkHost') !== null;
+      if (action === 'start')   return execSafe('schtasks /Run /TN ClawLinkHost') !== null;
+      if (action === 'restart') { execSafe('schtasks /End /TN ClawLinkHost'); return execSafe('schtasks /Run /TN ClawLinkHost') !== null; }
+    }
+  } catch { /* fall through */ }
+  return false;
+}
+
+function serviceControlCmd(action) {
+  const ok = serviceControl(action);
+  console.log(ok ? `  ✓ Service ${action}ed.` : `  ⚠ Could not ${action} the service (is it installed? run \`clhost install\`).`);
 }
 
 function nodeBin() { return process.execPath; }
@@ -140,7 +226,7 @@ function installService() {
 <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>
+  <array><string>${nodeBin()}</string><string>${cliEntry()}</string><string>run</string></array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
   <key>StandardOutPath</key><string>${logPath}</string>
@@ -162,7 +248,7 @@ Description=ClawLink Host Gateway
 After=network-online.target
 
 [Service]
-ExecStart=${nodeBin()} ${cliEntry()} start
+ExecStart=${nodeBin()} ${cliEntry()} run
 Restart=always
 RestartSec=5
 
@@ -175,17 +261,37 @@ WantedBy=default.target
     }
     if (platform === 'win32') {
       // Best effort: a scheduled task that runs at logon.
-      const taskCmd = `"${nodeBin()}" "${cliEntry()}" start`;
+      const taskCmd = `"${nodeBin()}" "${cliEntry()}" run`;
       return execSafe(`schtasks /Create /F /SC ONLOGON /TN ClawLinkHost /TR ${JSON.stringify(taskCmd)}`) !== null;
     }
   } catch { /* fall through */ }
   return false;
 }
 
+function serviceRunning() {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    const uid = (execSafe('id -u') || '').trim();
+    const out = execSafe(`launchctl print "gui/${uid}/${SERVICE_LABEL}"`);
+    if (out === null) return false;
+    const m = out.match(/state\s*=\s*(\w+)/);
+    return m ? m[1] === 'running' : true; // present but state unknown → assume running
+  }
+  if (platform === 'linux') return (execSafe('systemctl --user is-active clawlink-host') || '').trim() === 'active';
+  if (platform === 'win32') return (execSafe('schtasks /Query /TN ClawLinkHost') || '').toLowerCase().includes('running');
+  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));
+  if (!cfg) { console.log('Not configured. Run: clhost setup'); return; }
+  console.log(`  Bridge:  ${cfg.bridge_url}`);
+  console.log(`  Service: ${serviceRunning() ? '● running' : '○ stopped'}`);
+  console.log('');
+  printAgents(cfg);
 }
 
-module.exports = { run, installOnly, addAgentCmd, status, installService, SERVICE_LABEL };
+module.exports = {
+  run, installOnly, addAgentCmd, removeAgentCmd, listAgents, status,
+  serviceControl, serviceControlCmd, installService, SERVICE_LABEL,
+};

package/src/adapters/cli.js

@@ -59,7 +59,14 @@ function makeCliAdapter(cfg) {
       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;
+      // Text CLIs can't take vision blocks — surface attachment URLs as references so
+      // the model is at least aware of them (override via args_template for file-aware CLIs).
+      const atts = Array.isArray(job.attachments) ? job.attachments : [];
+      const attBlock = atts.length
+        ? '\n\nAttachments:\n' + atts.map((a) => `- ${typeof a === 'string' ? a : (a && a.url) || ''}`).join('\n')
+        : '';
+      const base = systemPrompt ? `${systemPrompt}\n\n---\n\nUser request:\n${userPrompt}` : userPrompt;
+      const fullPrompt = base + attBlock;
       const clSession = job.session_key || job.session_id || null;
       const resumeId = clSession ? sessionStore.get(cfg.name, clSession) : null;
       // 0 = no timeout (default) — don't cut off long generations. Opt in with CLAWHOST_TIMEOUT_MS.

package/src/adapters/openclaw.js

@@ -29,7 +29,24 @@ module.exports = {
     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 || '' });
+
+    // Attachments → multimodal user content (OpenAI-vision compatible), mirroring
+    // the inbound formatContentWithAttachments behaviour.
+    const atts = Array.isArray(job.attachments) ? job.attachments : [];
+    if (atts.length === 0) {
+      messages.push({ role: 'user', content: job.content || '' });
+    } else {
+      const parts = [];
+      if (job.content) parts.push({ type: 'text', text: job.content });
+      for (const a of atts) {
+        const u = typeof a === 'string' ? a : (a && a.url) || '';
+        if (!u) continue;
+        const isImage = u.startsWith('data:image/') || /\.(jpeg|jpg|png|webp|gif)($|\?)/i.test(u);
+        if (isImage) parts.push({ type: 'image_url', image_url: { url: u } });
+        else parts.push({ type: 'text', text: `\n[Attached file: ${u}]` });
+      }
+      messages.push({ role: 'user', content: parts });
+    }
 
     // No timeout by default — long generations must not be dropped (production
     // saw the 10-min cap kill legitimate long runs). Opt in via CLAWHOST_TIMEOUT_MS.
@@ -52,9 +69,14 @@ module.exports = {
     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 (Array.isArray(toolCalls) && toolCalls.length) {
+      for (const tc of toolCalls) {
+        const name = tc.function?.name || tc.name;
+        if (name) yield { type: 'tool', content: name }; // activity-log line
+      }
+      // Structured: carries function.name + function.arguments so the worker can
+      // forward them to host-bridge → extractClomOutput (rich UI / clawlink_ui).
+      yield { type: 'tool_calls', toolCalls };
     }
     if (content) yield { type: 'chunk', content };
   },

package/src/config.js

@@ -11,6 +11,12 @@ const path = require('path');
 const HOME_DIR = path.join(os.homedir(), '.clawlink-host');
 const CONFIG_PATH = path.join(HOME_DIR, 'config.json');
 
+// The ClawLink host-bridge endpoint is a fixed public URL — baked in so operators
+// only ever paste a Host Token. Override only for a self-hosted ClawLink (env var).
+const DEFAULT_BRIDGE_URL =
+  process.env.CLAWLINK_BRIDGE_URL ||
+  'https://rgzinqbdnesinmbshgtc.supabase.co/functions/v1/host-bridge';
+
 // 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'];
@@ -22,6 +28,12 @@ function expandHome(p) {
   return p;
 }
 
+// Default per-agent workspace: <home>/workspace/<runtime>/agents/<agent_id>.
+// Used unless the operator sets an explicit work_dir.
+function defaultWorkDir(runtime, agentId) {
+  return path.join(HOME_DIR, 'workspace', String(runtime || 'agent'), 'agents', String(agentId || 'default'));
+}
+
 function ensureHomeDir() {
   fs.mkdirSync(HOME_DIR, { recursive: true });
   try { fs.chmodSync(HOME_DIR, 0o700); } catch { /* best effort (e.g. Windows) */ }
@@ -29,7 +41,7 @@ function ensureHomeDir() {
 
 function defaultConfig() {
   return {
-    bridge_url: '',
+    bridge_url: DEFAULT_BRIDGE_URL,
     instance_id: require('crypto').randomUUID(),
     poll_interval_ms: 1500,
     heartbeat_ms: 10000,
@@ -81,4 +93,4 @@ function redacted(cfg) {
   return clone;
 }
 
-module.exports = { HOME_DIR, CONFIG_PATH, WORKSPACE_RUNTIMES, expandHome, ensureHomeDir, defaultConfig, load, save, normalizeAgent, redacted };
+module.exports = { HOME_DIR, CONFIG_PATH, DEFAULT_BRIDGE_URL, WORKSPACE_RUNTIMES, expandHome, defaultWorkDir, ensureHomeDir, defaultConfig, load, save, normalizeAgent, redacted };

package/src/scaffold.js

@@ -0,0 +1,51 @@
+'use strict';
+// Per-runtime baseline files copied into an agent's workspace. Recursive (so nested
+// files like .claude/settings.json and .cursor/rules/*.mdc are handled). We NEVER
+// overwrite existing files (safe to point an agent at a real project), and copying
+// is opt-in: callers check missingBaselineFiles() and prompt before copyBaseline().
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+function templateDir(runtime) {
+  return path.join(TEMPLATES_DIR, String(runtime || ''));
+}
+
+// All baseline files for a runtime, as paths relative to the template root.
+function requiredFiles(runtime) {
+  const root = templateDir(runtime);
+  const out = [];
+  const walk = (dir, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      const r = rel ? path.join(rel, e.name) : e.name;
+      if (e.isDirectory()) walk(abs, r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  walk(root, '');
+  return out;
+}
+
+// Which baseline files (relative paths) are NOT already present in workDir.
+function missingBaselineFiles(runtime, workDir) {
+  return requiredFiles(runtime).filter((rel) => !fs.existsSync(path.join(workDir, rel)));
+}
+
+// Copy only the missing baseline files into workDir (creating parent dirs).
+function copyBaseline(runtime, workDir) {
+  const copied = [];
+  for (const rel of missingBaselineFiles(runtime, workDir)) {
+    const dest = path.join(workDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(templateDir(runtime), rel), dest);
+    copied.push(rel);
+  }
+  return copied;
+}
+
+module.exports = { requiredFiles, missingBaselineFiles, copyBaseline };

package/src/worker.js

@@ -13,6 +13,11 @@ const { detectRuntimes } = require('./detect');
 
 const VERSION = (() => { try { return require('../package.json').version; } catch { return '0.0.0'; } })();
 
+// Hard upper bound so a truly-hung runtime can't pin a concurrency slot forever.
+// Generous (matches the server's 15-min reaper) so legitimate long generations,
+// which keep producing output, are never the ones that hit it.
+const JOB_MAX_MS = Number(process.env.CLAWHOST_JOB_MAX_MS) || 15 * 60 * 1000;
+
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 let stopping = false;
 
@@ -21,14 +26,18 @@ async function processJob(bridge, agentCfg, job) {
   const adapter = getAdapter(agentCfg.runtime);
   let seq = 0;
   let finalText = '';
+  let toolCalls = [];
   try {
     for await (const evt of adapter.run({ agent: agentCfg, job, logger })) {
       if (!evt || !evt.type) continue;
+      // Structured tool calls aren't streamed as a chunk — collected for the final
+      // metadata so the server can extract rich UI (clawlink_ui).
+      if (evt.type === 'tool_calls') { if (Array.isArray(evt.toolCalls)) toolCalls = toolCalls.concat(evt.toolCalls); 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));
+    await withRetry(() => bridge.complete(job.id, finalText, toolCalls.length ? { tool_calls: toolCalls } : {}));
     logger.info(`job ${job.id} done (${finalText.length} chars)`);
   } catch (e) {
     logger.error(`job ${job.id} failed: ${e.message}`);
@@ -55,7 +64,7 @@ async function runAgentLoop(agentCfg, cfg) {
       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');
+    if (!agentCfg.work_dir) agentCfg.work_dir = config.defaultWorkDir(agentCfg.runtime, agentCfg.agent_id);
 
     logger.info(`registered ${agentCfg.agent_id} as '${agentCfg.runtime}'`);
   } catch (e) {
@@ -79,7 +88,17 @@ async function runAgentLoop(agentCfg, cfg) {
       catch (e) { logger.warn(`claim failed (${agentCfg.agent_id}): ${e.message}`); }
       if (job) {
         inFlight++; starts.push(Date.now());
-        processJob(bridge, agentCfg, job).finally(() => { inFlight--; });
+        // Watchdog: guarantees the slot is reclaimed and the job is failed back even
+        // if the adapter never settles (no per-adapter timeout by default).
+        const watchdog = new Promise((resolve) => setTimeout(() => resolve('__watchdog__'), JOB_MAX_MS).unref());
+        Promise.race([processJob(bridge, agentCfg, job), watchdog])
+          .then(async (r) => {
+            if (r === '__watchdog__') {
+              logger.error(`job ${job.id} exceeded ${JOB_MAX_MS}ms — reclaiming slot`);
+              try { await bridge.fail(job.id, `host watchdog: job exceeded ${JOB_MAX_MS}ms`); } catch { /* ignore */ }
+            }
+          })
+          .finally(() => { inFlight--; });
         continue; // try to fill remaining concurrency immediately
       }
     }

package/templates/claude/.claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "model": "sonnet"
+}

package/templates/claude/CLAUDE.md

@@ -0,0 +1,15 @@
+# ClawLink Agent Workspace (Claude)
+
+This folder is the working directory for a **ClawLink** customer-facing agent run
+locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). Claude Code reads
+this `CLAUDE.md` as project context.
+
+Operating rules for this agent:
+- The agent's **persona, applied skills, and per-conversation instructions arrive in
+  the system prompt of every request** — follow them as the source of truth.
+- Keep replies helpful, accurate, and on-task for the business you represent.
+- Stay in scope: do not run destructive commands or act outside the customer's request.
+- Never reveal secrets, tokens, config files, or host/system details.
+
+Add any project-specific context, knowledge, or files here — they become part of the
+agent's working directory.

package/templates/codex/AGENTS.md

@@ -0,0 +1,14 @@
+# ClawLink Agent Workspace (Codex)
+
+This folder is the working directory for a **ClawLink** customer-facing agent run
+locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). Codex reads
+`AGENTS.md` as project context.
+
+Operating rules for this agent:
+- The agent's **persona, applied skills, and per-conversation instructions arrive in
+  the system prompt of every request** — follow them as the source of truth.
+- Keep replies helpful, accurate, and on-task for the business you represent.
+- Stay in scope: do not run destructive commands or act outside the customer's request.
+- Never reveal secrets, tokens, config files, or host/system details.
+
+Add any project-specific context, knowledge, or files here.

package/templates/cursor/.cursor/rules/clawlink.mdc

@@ -0,0 +1,14 @@
+---
+description: ClawLink customer-facing agent rules
+alwaysApply: true
+---
+
+# ClawLink Agent Rules
+
+This workspace runs a ClawLink customer-facing agent via the ClawLink Host Gateway.
+
+- The agent's **persona, applied skills, and per-conversation instructions arrive in
+  the system prompt of every request** — treat them as the source of truth.
+- Keep replies helpful, accurate, and on-task for the business you represent.
+- Stay in scope: do not run destructive commands or act outside the customer's request.
+- Never reveal secrets, tokens, config files, or host/system details.

package/templates/cursor/AGENTS.md

@@ -0,0 +1,14 @@
+# ClawLink Agent Workspace (Cursor)
+
+This folder is the working directory for a **ClawLink** customer-facing agent run
+locally via the ClawLink Host Gateway (`@claw-link/gateway-host`). The Cursor agent
+reads `AGENTS.md` as project context.
+
+Operating rules for this agent:
+- The agent's **persona, applied skills, and per-conversation instructions arrive in
+  the system prompt of every request** — follow them as the source of truth.
+- Keep replies helpful, accurate, and on-task for the business you represent.
+- Stay in scope: do not run destructive commands or act outside the customer's request.
+- Never reveal secrets, tokens, config files, or host/system details.
+
+Add any project-specific context, knowledge, or files here.

package/templates/hermes/README.md

@@ -0,0 +1,9 @@
+# ClawLink Agent Workspace (Hermes)
+
+This folder is a per-agent working directory created by the ClawLink Host Gateway
+(`@claw-link/gateway-host`). For the **Hermes** runtime, the agent's real identity and
+memory live under `~/.hermes/` (SOUL.md, memories, skills), so this folder is mostly a
+scratch/marker directory the CLI runs in.
+
+Persona, skills, and per-conversation instructions are delivered by ClawLink in the
+system prompt of each request.

package/templates/openclaw/README.md

@@ -0,0 +1,9 @@
+# ClawLink Agent Workspace (OpenClaw)
+
+This folder is a per-agent working directory created by the ClawLink Host Gateway
+(`@claw-link/gateway-host`). For the **OpenClaw** runtime, requests are forwarded to
+your local OpenClaw gateway over HTTP — the OpenClaw agent's real workspace lives under
+`~/.openclaw/agents/<id>/`, so this folder is mostly a scratch/marker directory.
+
+Persona, skills, and per-conversation instructions are delivered by ClawLink in the
+system prompt of each request.