Imported from ChingFuHan/My_relay_test_host (AGENTS.md). Install upstream with npx skills add ChingFuHan/My_relay_test_host. Copyright stays with the author.

AGENTS.md — orientation for AI agents & new contributors

Read this first if you are an AI agent (or a new human) picking up this repo cold. It tells you what the project is, how the pieces fit, and the conventions to respect.

What this repo is

A host-side bridge for GPT Relay. A small Node service (server.mjs) connects to a locally running Chrome over the Chrome DevTools Protocol (CDP) and exposes a token-protected HTTP API on port 8765. A Linux VM running GPT Relay / Codex calls that API to drive the host's Chrome. Around the service is a set of Windows one-click launchers so a non-technical user can start/stop/check the whole stack by double-clicking .bat files.

Full details: see README.md. Chinese end-user guide: 使用說明.txt.

Mental model (data flow)

VM (GPT Relay plugin) → HTTP :8765 (Bearer token) → server.mjs → Playwright connectOverCDP → Chrome :9222 → real browser tabs.

Startup ordering matters and is enforced by the launcher: Chrome first → wait for :9222 → start server.mjs → verify /health. /health deliberately opens the CDP connection, so it only passes once Chrome is up.

File map (what to touch for what)

• server.mjs — the HTTP API + Playwright proxy. Change here to add/modify endpoints or RPC namespaces (playwright, cua, dom_cua, clipboard, capabilities). Config is read from env vars only (no .env).
• gpt-relay.ps1 — the single source of truth for the Windows launcher logic and its config. The CONFIG block at the very top holds Chrome path, token, ports, CDP URL, profile dir. Four .bat files are thin wrappers that call this with -Action run|stop|status|setup.
• *.bat — do not put logic here; they only invoke gpt-relay.ps1.
• 使用說明.txt / README.md / this file — docs. Keep them in sync when behavior changes.

Conventions

• Launcher output is ASCII-only (status tags [ OK ] / [FAIL] / [WARN]) to avoid Windows console code-page issues. Keep it that way.
• Windows paths with spaces must be passed via PowerShell -FilePath + -ArgumentList arrays, never string-concatenated, so Chrome flags don't break.
• Kill only the gpt-relay debug Chrome on stop (matched by command line: gpt-relay-chrome / remote-debugging-port=9222), never the user's personal Chrome. The run action is the only place that intentionally closes all Chrome.
• The bridge launches in its own cmd window (cmd /k node server.mjs) so its logs stay visible; stop finds it by the server.mjs command line.
• Env vars the service honors: HOST_BRIDGE_PORT, HOST_BRIDGE_HOST, HOST_BRIDGE_TOKEN, CHROME_CDP_URL.

How to verify a change

• Static: powershell -NoProfile -Command "[System.Management.Automation.Language.Parser]::ParseFile('gpt-relay.ps1',[ref]$null,[ref]([ref]$e).Value)" or just run status-gpt-relay-host.bat (read-only — checks ports + HTTP).
• End to end: double-click run-gpt-relay-host.bat, expect all [ OK ] + SUCCESS; then stop-gpt-relay-host.bat; re-run status and expect the ports to read [FAIL] (down).

Gotchas

• This folder may live inside another git repo (the upstream GPT-Relay-Codex-Plugin-). It is published standalone as My_relay_test_host.
• node_modules/ is git-ignored — run npm install (or setup-host-bridge-deps.bat) after cloning.
• The shipped token change-me is a placeholder. Treat it as non-secret; set a real token for any real deployment.