bridge

A thin client for the openclaw helper daemon at ~/.openclaw/helper/server.js, listening on 127.0.0.1:18790 with Bearer-token auth. The daemon is the long-running process that holds the macOS TCC grants (Screen Recording, Accessibility) the agent's own child-process tree does not.

Backed by state/lib/bridge.ts. Local-loopback only. NOT MCP -- this is the same shape every other snappy-os HTTP integration takes (the head-screen server on :3147, the eval endpoint, etc).

When to use

• Any shell call that touches a TCC-restricted primitive: screencapture -x,

peekaboo image|paste|press|click, osascript keystroke, cliclick. Spawned from Claude Code, those return permission errors or zero-byte artifacts. Routed through the bridge, they actually run.

• File operations on paths the agent's process can't read or write directly

(e.g. things under ~/Library, /var/log, or another user's home).

• Long-running shell commands that benefit from the daemon's stable PID

rather than a per-turn child spawn.

When NOT to use

• File reads inside the agent's working tree -- use the local Read tool.
• Internal commands the agent can already run fine (git, npm, npx tsx,

most CLI tools that don't touch the GUI). Adding a hop just adds latency.

• Anything where the local context already works -- if the in-process call

succeeds, don't relay it through the bridge.

Steps

• bridgeAvailable() -- see state/lib/bridge.ts
• bridgeExec(command, opts?) -- see state/lib/bridge.ts
• bridgeReadFile(filePath) -- see state/lib/bridge.ts
• bridgeWriteFile(filePath, content) -- see state/lib/bridge.ts

Library API

bridgeAvailable(): Promise<boolean>

Pings GET /health. Returns true when the daemon answers within 2s with ok: true. Cached for 60s in module-local state -- a tight loop of captureWindow() calls only pays the probe once. Never throws (network failure collapses to false).

import { bridgeAvailable, bridgeExec } from "../lib/bridge.ts";
if (await bridgeAvailable()) {
  await bridgeExec("screencapture -x /tmp/x.png");
}

bridgeExec(command, opts?): Promise<BridgeExecResult>

POSTs { command, timeout } to /exec. Returns { ok, output } on success or { ok: false, error, stderr? } on failure. Default timeout 30s; pass { timeout: 60_000 } for slow captures. The command runs in the daemon's environment, NOT the caller's cwd -- pass absolute paths.

const { ok, output, error } = await bridgeExec("/opt/homebrew/bin/peekaboo image --mode window --app SnappyChat --path /tmp/sc.png");
if (!ok) throw new Error(`capture failed: ${error}`);

bridgeReadFile(filePath): Promise<string>

POST /read-file. Returns the file contents. Throws on ok: false.

bridgeWriteFile(filePath, content): Promise<void>

POST /write-file. Throws on failure.

Configuration

Read from .env.cache at the repo root (or process env, which wins):

• OPENCLAW_BRIDGE_URL (default http://127.0.0.1:18790)
• OPENCLAW_BRIDGE_TOKEN (no default -- throws on first auth attempt if

missing)

The token is the Bearer credential hardcoded in ~/.openclaw/helper/server.js:7. It is NOT secret in the cryptographic sense (anything with read access to either file gets it), but it gates the daemon from accepting requests from random local processes that haven't been told the value. Treat it like a session cookie -- don't log it, don't ship it off-machine.

Failure modes

• Daemon down: bridgeAvailable() returns false. Callers should fall back

to direct exec when graceful degradation is appropriate (the desktop skill does this) or fail fast when the bridge is the only path that works.

• Token missing: every call throws on the first auth attempt. The fix is

to add OPENCLAW_BRIDGE_TOKEN=... to .env.cache.

• Command fails inside the daemon: bridgeExec returns `{ ok: false,

error, stderr } with the same shape regardless of whether the failure was a non-zero exit, a timeout, or a transport error. Inspect error` to discriminate.

Eval

Actor: the exported functions in state/lib/bridge.ts. Auditor: state/lint/library-shape.ts (mechanical -- the lib must exist with named exports). Behavioral correctness is verified by the consuming skill (e.g. desktop), not here -- a relay can't grade its own payload.

Rubric

criteria:
  - name: lib_exists_and_exports
    kind: deterministic
    check: "'state/lib/bridge.ts' exists and exports bridgeAvailable, bridgeExec, bridgeReadFile, bridgeWriteFile."
  - name: token_not_logged
    kind: judge
    check: "No code path writes OPENCLAW_BRIDGE_TOKEN to stdout, stderr, eval rows, or any log file outside .env.cache."
  - name: loopback_only
    kind: judge
    check: "Default bridge URL is 127.0.0.1; no production code path constructs a non-loopback URL."

bridge - loader

Per-turn rules for bridge. TCC-grants relay for screen capture, keystroke, click, file ops. Full reference: state/skills/bridge/SKILL.md. Do not skip Critical Rules.

Critical Rules

1. NEVER log OPENCLAW_BRIDGE_TOKEN. Not to stdout, stderr, eval rows, or any file outside .env.cache. The token gates arbitrary shell exec on the daemon.
2. LOOPBACK ONLY. Default OPENCLAW_BRIDGE_URL is http://127.0.0.1:18790. Never construct a non-loopback URL or expose the daemon over the network - anyone with the token can run anything as the user.
3. The bridge is the actor; the bridge response is NOT the auditor. After a bridgeExec that mutates GUI state, verify with a follow-up that doesn't trust the bridge return alone (e.g. captureWindow to confirm visual change). CONSTITUTION invariant #3.
4. Don't relay commands the local context can already run. Adding a hop costs latency. The bridge is for TCC-restricted ops (screen capture, keystroke, click), not for git status.
5. If bridgeAvailable() returns false, the daemon is down. Restart with launchctl kickstart -k gui/$(id -u)/ai.openclaw.helper. Do NOT try to start ~/.openclaw/helper/server.js directly (it's a launchd-managed process and direct node invocation won't bind the port cleanly). Do NOT curl in a loop.
6. HTTP 500 from bridge = daemon error state, not a transient failure. Restart the daemon (same launchctl command as above). Retrying the same request will keep returning 500.
7. BridgeEvalWatcher hash-nav. To drive snappy-chat to a specific route from shell: echo "__snappyNav('#/chat/customize/themes', 'chat')" > /tmp/snappy-eval.js (or via bridgeExec). The BridgeEvalWatcher in SnappyChat polls /tmp/snappy-eval.js and executes the nav. Verify nav landed with a follow-up screenshot. Registered bridge events: bundle.state, bundle.mounted, config.elevenlabs, agent.select.

Commands

| ui dashboard | state/skills/bridge/resources/ui.openui |

Daemon endpoints (127.0.0.1:18790, Bearer auth)

• GET /health → { ok, service, uptime }
• POST /exec body { command, timeout? } → { ok, output } or { ok: false, error, stderr? }
• POST /read-file body { file_path } → { ok, content }
• POST /write-file body { file_path, content } → { ok, written }

The body field is command, NOT cmd. {"cmd":"..."} returns {"ok":false,"error":"command required"}. Canonical raw-curl shape:

TOKEN=$(grep '^OPENCLAW_BRIDGE_TOKEN=' .env.cache | cut -d= -f2-)
curl -s -X POST http://127.0.0.1:18790/exec \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"command":"echo hello"}'

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/bridge/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Commands run in the daemon's environment, NOT the caller's cwd. Pass absolute paths (/opt/homebrew/bin/peekaboo, not peekaboo).
• bridgeAvailable() is cached for 60s. Call bridgeResetCache() in tests if the daemon was just started.
• Token source of truth: ~/.openclaw/helper/server.js:7 (line const TOKEN = '...'). .env.cache (OPENCLAW_BRIDGE_TOKEN) must match. Read either with: grep '^OPENCLAW_BRIDGE_TOKEN=' ~/projects/snappy-os/.env.cache | cut -d= -f2- OR node -e "const s=require('fs').readFileSync(process.env.HOME+'/.openclaw/helper/server.js','utf8'); console.log(s.match(/TOKEN = '([^']+)'/)[1])". If they disagree, update .env.cache to match server.js (the daemon wins). Current token rotated 2026-05-01 - old literal snappy-openclaw is invalid.
• Default bridgeExec timeout is 30s. Slow GUI ops (e.g. peekaboo image on a buried window) may need { timeout: 60_000 }.
• Async render race on inject-control / theme changes. When you inject a UI state change via the /dispatch/chat inject-control endpoint (e.g. theme:light), the HTTP 204 response confirms the queue consumed the command - but WKWebView renders asynchronously. A screenshot taken immediately after will race and likely capture the pre-change state. Insert a 500ms+ delay before screenshotting, or poll until the visual state settles. (2026-04-29: light-mode verification captured dark state because the peekaboo call followed the inject curl with no delay.)
• peekaboo window-IDs rotate per call. peekaboo list windows returns a fresh ID: each invocation; using --window-id <n> from a previous list call fails with Window not found: window_id <n>. For capture, prefer --app "Snappy Chat" (note the space). For positioning math, use peekaboo list windows --app "Snappy Chat" immediately before the click/move and compute screen coords from the window's Position: (x, y) + Size: WxH fields. Window-rel top: 50% lands at y = window.y + height/2 in screen coords.
• Hover-only chrome won't show in unattended captures. Elements with opacity: 0 until .app:hover (e.g. .panel-toggle) require the cursor to be inside the app window before the screenshot. Use peekaboo move <x>,<y> to position the cursor over the app first (positional, not --coords), then capture. Without this, hover-styled elements render as transparent and look "missing."

Self-Test

An agent reading this should correctly:

1. [ ] Never log OPENCLAW_BRIDGE_TOKEN anywhere?
2. [ ] Construct only loopback URLs (127.0.0.1 or localhost)?
3. [ ] Verify bridgeExec results via independent observation, not response payload?
4. [ ] Skip bridge for commands local context can already run fine?
5. [ ] Restart daemon (not work around) when bridgeAvailable() is false?
6. [ ] Use JSON body field command (not cmd) in raw curl?
7. [ ] Add 500ms+ delay before screenshot after inject-control theme changes?
8. [ ] Know peekaboo window IDs rotate per call - always list first?
9. [ ] Know hover-only chrome needs cursor-in-app before screenshot?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] bridge: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.