feat: thunderbolt — stdio-bridge CLI (thunderbolt bridge), curl|bash installer, and in-app connect flows

[ital0]

Brings up the full stdio-bridge feature in one PR: the thunderbolt CLI package, its curl | bash delivery, and the in-app "Connect via bridge" flows (agent catalog + MCP servers). Built clean-room from the approved THU-601 design. Supersedes #989 (first implementation, discarded as incorrect).

CLI — cli/ (thunderbolt bridge subcommand)

Renamed thunderbolt-stdio-bridge → thunderbolt (package dir cli/); the bridge is the thunderbolt bridge subcommand (positions for the future general-purpose Thunderbolt CLI). Plain Node, no bundled runtime. Modules + tests: argv parser + subcommand dispatch, exit-code table, PII-safe logger, loopback/util, child supervisor, ACP↔WS relay, ACP WebSocket face, MCP Streamable-HTTP face, MCP session multiplexer, cloudflared tunnel, composition root.

Contracts: thunderbolt bridge --mode <acp|mcp> … -- <launch>; banners/logs stderr-only; sysexits exit codes (0/64/69/70/130); Origin allowlist default-on (ACP rejects at upgrade, MCP rejects present-but-disallowed Origins server-side); tunnel ⇒ mandatory constant-time bearer (never in URL); never-orphan child (SIGKILL on every fatal path); newest-wins ACP client + backpressure; MCP body cap + deterministic teardown. The MCP face multiplexes sessions so the probe + the live connection + reconnects share one stdio child (initialized once) — a single-session child would otherwise reject the second client with "already initialized". bun test: 199 green incl. a real multi-client server-everything integration test.

Delivery

• cli/install.sh — POSIX curl | bash: resolves version from main's package.json, downloads thunderbolt.cjs + verifies its SHA-256 from the GitHub Release, installs the bare thunderbolt on the npm global bin (sudo fallback). Requires node.
• .github/workflows/thunderbolt-release.yml — PR/main pushes build + smoke; thunderbolt-v* tag builds, smoke-tests, and attaches thunderbolt.cjs + thunderbolt.cjs.sha256 to the Release.

App connect flows

Extends the #987 catalog; no schema/DAL/migration changes. Loopback carve-out (resolveWebSocketFactory ACP + resolveMcpFetch MCP) routes loopback URLs to native WS/fetch ahead of standalone/proxy (classifies all of 127.0.0.0/8, matching the bridge).

• ACP agent catalog: a 3-step BridgeConnectDialog ("Connect via bridge" card action) — composeBridgeCommand emits thunderbolt bridge --mode acp -- <launch> (installed binary directly, --allow-origin '<app-origin>' for non-loopback web).
• MCP servers screen: a "Connect a local server via bridge" button + McpBridgeConnectDialog — free-text stdio command → composeMcpBridgeCommand emits thunderbolt bridge --mode mcp -- <command>; user adds the printed http://127.0.0.1:PORT/mcp.
• Desktop auto-install: BridgeInstallStep (shared by both dialogs) — on macOS/Linux desktop an "Install automatically" button invokes a new Tauri install_bridge command (runs install.sh via the login $SHELL wrapping bash -c 'set -o pipefail; …' — login PATH + pipefail, fish-safe); web/Windows show the manual curl | bash (also pipefail-wrapped so a failed curl isn't silent).

Validation

bun run check green (type/lint/prettier/license); thunderbolt (cli/) bun test 199 green (5×); app glue + full src suite green; Rust cargo check/cargo test. Reviewed blind by GLM-5.2 + Codex (gpt-5.5) each round; consensus findings fixed. Verified end-to-end against the real app via Playwright: the binary wraps server-everything, the MCP server connects (13 tools), and a chat message drives the model to call an MCP tool through the bridge. Bot-review findings triaged + resolved (incl. two validated false positives: HTTPS→loopback "mixed content" — loopback is potentially-trustworthy per W3C; and a paths+tags workflow trigger — paths aren't evaluated for tag pushes).

---

Note

High Risk
New security-sensitive local networking (Origin gate, bearer, optional public tunnel) and child-process lifecycle; mistakes could expose LAN services or leak access, though defaults target loopback and the surface is heavily tested.

Overview
Introduces the thunderbolt CLI under cli/, a local toolkit whose bridge subcommand spawns a stdio ACP or MCP child and exposes it on loopback as WebSocket (--mode acp) or Streamable HTTP (--mode mcp). Diagnostics and readiness URLs go to stderr only; sysexits-style exit codes, signal/fatal teardown, and never-orphan child reaping are wired in bin/cli.ts.

The MCP path adds a session multiplexer so multiple HTTP clients share one stdio child (single initialize, id remapping, cached init). Security defaults include an Origin allowlist, optional bearer auth (constant-time), body caps, and loud warnings for non-loopback binds; optional --tunnel fronts MCP with cloudflared and a minted bearer.

Delivery: install.sh downloads a release thunderbolt.cjs, verifies SHA-256, and installs to the npm global bin; scripts/build-cli.mjs esbuild-bundles the entry; .github/workflows/thunderbolt-release.yml builds, smoke-tests ACP/MCP banners, and publishes artifacts on thunderbolt-v* tags. Root .gitignore gains .playwright-mcp/.

^{Reviewed by Cursor Bugbot for commit 950a0e1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Semgrep Security Scan

Found 1 issue(s).

#	Severity	Rule	File	Line
1	WARNING	cors-misconfiguration	cli/src/mcp-server.ts	L262

Finding details

cors-misconfiguration — cli/src/mcp-server.ts:262

Severity: WARNING
Message: By letting user input control CORS parameters, there is a risk that software does not properly verify that the source of data or communication is valid. Use literal values for CORS settings.

requires login

[github-actions]

Preview environment destroyed 🧹

Stack preview-pr-1021 and its Cloudflare subdomain have been cleaned up.

[github-actions]

PR Metrics

Metric	Value
Lines changed (prod code)	+3644 / -209
JS bundle size (gzipped)	🟢 769.4 KB → 769.6 KB (+196 B, +0.0%)
Test coverage	🟢 78.47% → 78.92% (+0.5%)
Performance (preview)	Preview not ready — Render deploy may have timed out
Accessibility	—
Best Practices	—
SEO	—

Updated Mon, 29 Jun 2026 21:35:49 GMT · run #2114

[github-actions]

🔭 thunder-deep-review (advisory)

Reviewed the diff — no issues to report. ✅ Never approves, never requests changes, never gates merge.
_{head: 3b2b80d1e9d4 · mode: deep · deferred 5 item(s) already reported by other bots (best-effort dedup)}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 46b7fcd. Configure here.}

[ital0]

closed that in favor or #1032