@anusornneal/chat-relay 0.9.0 → 0.9.2

package/README.md

@@ -1,31 +1,33 @@
-# chat-relay
+# Chat Relay
 
-Cloudflare Worker + Durable Objects relay that exposes one or more local Windows or macOS agents to ChatGPT through remote MCP.
+Remote MCP relay that lets ChatGPT work with a local Windows or macOS machine through a Cloudflare-hosted relay.
 
-```
-ChatGPT / MCP client
-        |
-        | Streamable HTTP MCP
-        v
-Cloudflare Worker
-        |
-        +-- Registry Durable Object (users, agents, grants)
-        |
-        +-- Relay Durable Object per agent
-                    |
-                    | WebSocket
-                    v
-             Local Agent
-             - terminal
-             - files
-             - processes
+**Dashboard:** https://chat-relay.anusorn-hank.workers.dev/
+
+## Quick start
+
+There are two parts:
+
+1. Connect ChatGPT to the relay.
+2. Run the local agent on the computer you want ChatGPT to access.
+
+### 1. Connect to ChatGPT
+
+Add the production MCP server to ChatGPT:
+
+```text
+https://chat-relay.anusorn-hank.workers.dev/mcp
 ```
 
-The relay is generic and has no Devflow-specific logic.
+Complete the OAuth sign-in when ChatGPT opens the authorization flow.
 
-## Quick start
+ChatGPT MCP should connect to the plain `/mcp` endpoint. The legacy `/mcp?key=<USER_TOKEN>` flow remains available only during migration and should not be used for new connections.
+
+ChatGPT connects to the cloud relay. To actually access files, terminal, processes, or desktop controls on a computer, that computer must also be running the local agent below.
+
+### 2. Run the local agent with `npx`
 
-The CLI is published on npm. You do **not** need to clone this repository or run `npm install`.
+Requirements: Node.js 20 or newer.
 
 From any directory:
 
@@ -33,321 +35,152 @@ From any directory:
 npx @anusornneal/chat-relay@latest remote
 ```
 
-On the first run, Chat Relay opens a browser-based device login. Sign in, approve the computer, then return to the terminal. The CLI saves its credentials in your user profile and connects the local agent automatically.
+On the first run, Chat Relay opens browser-based device authorization. Choose **Continue with Google and authorize computer**, sign in with the same Google account used for the ChatGPT connector, then return to the terminal. Device sign-in requires configured Google OAuth and does not accept a local username/password.
 
-Later, use the same command from anywhere:
+The CLI saves the device credentials in your user profile, so later you can reconnect with the same command:
 
 ```bash
 npx @anusornneal/chat-relay@latest remote
 ```
 
-A successful connection looks like:
-
-```text
-Chat Relay Remote
------------------
-Agent:      Primary PC (default)
-Terminal:   enabled
-Desktop:    disabled
-Agent connected
-```
-
-## Zero-checkout CLI
-
-Other commands:
+Enable desktop screenshot, mouse, and keyboard access:
 
 ```bash
-npx @anusornneal/chat-relay@latest login
-npx @anusornneal/chat-relay@latest status
-npx @anusornneal/chat-relay@latest logout
+npx @anusornneal/chat-relay@latest remote --desktop
 ```
 
-On Windows the config defaults to `%LOCALAPPDATA%\chat-relay\config.json`. On macOS/Linux it uses `$XDG_CONFIG_HOME/chat-relay/config.json` or `~/.config/chat-relay/config.json`. Set `CHAT_RELAY_HOME` to override the location.
-
-Useful options:
+Limit filesystem access to a specific root:
 
 ```bash
-chat-relay remote --root "C:\Users\you\Projects"
-chat-relay login --name "Work PC"
-chat-relay login --no-open
-chat-relay remote --desktop
-chat-relay remote --no-desktop
+npx @anusornneal/chat-relay@latest remote --root "C:\Users\you\Projects"
 ```
 
-The published package locates its bundled local agent relative to the package itself, so commands work from any working directory. Existing repository users can still run `npm start`; legacy `.dev.vars` credentials are migrated once into the user-level config.
-## Device lifecycle and recovery
-
-- `chat-relay status` shows the signed-in account, readable device name/id, relay URL, access state, online/offline state, last-seen time, and granted scopes without printing secrets.
-- One account can own multiple PCs. Each PC keeps its own agent id and credential, so devices remain independently visible and revocable.
-- Admins can rename a device from the dashboard without changing its agent id or grants.
-- Retiring a device invalidates its current machine credential and disconnects the live agent. That credential cannot reconnect until the device is authorized again.
-- Recovery after retirement does not require copying tokens: run `chat-relay login --force`, complete browser authorization, then run `chat-relay remote`.
-- A different account cannot reclaim another owner's active or retired agent id; a colliding login receives a separate device identity instead.
-
-
-## Agent protocol and capabilities
-
-Local agents send a lightweight hello handshake when their WebSocket connects. The handshake reports the protocol version, package version, platform/architecture, and the capabilities that are actually enabled on that machine. Feature routing should use the advertised capability list rather than inferring support from the package version alone.
-
-Protocol v1 keeps legacy agents backward compatible: a connected agent that does not send hello metadata can still use the pre-handshake behavior. An agent that explicitly advertises an unsupported protocol is disconnected with a clear incompatibility reason instead of failing later on an unrelated tool call or entering a restart loop.
-
-## Dashboard administrator sessions
-
-Browser dashboard access uses the same Chat Relay username/password accounts but requires an explicit global administrator entitlement. Successful dashboard login creates a short-lived opaque server-side session; the browser receives an HttpOnly, Secure, SameSite=Strict cookie plus a CSRF token for state-changing requests. `ADMIN_TOKEN` remains an operator/CLI recovery credential and must never be embedded in dashboard JavaScript, browser storage, or URLs.
-## Authentication and multi-user model
-
-- Browser/device login uses a short-lived device code. Raw user or admin tokens are not typed into the CLI.
-- New accounts use a unique login plus password. Passwords are stored only as salted PBKDF2-SHA256 hashes.
-- Device start/approval requests and failed password attempts are rate-limited.
-- CLI user sessions are opaque random tokens stored server-side only as hashes and expire after 90 days.
-- Re-authentication revokes the previous CLI session when possible.
-- Each local machine has an independent `agentId` and agent token; agent tokens are stored server-side only as hashes.
-- Agent ownership is enforced before an existing machine identity can be reused, preventing shared users from rotating another owner's agent credential.
-- Grants map users to agents with scopes: `read`, `write`, `terminal`, `process`, `desktop_read`, `desktop_control`, or `*`. Explicit legacy grants do not gain desktop access automatically.
-- Logging out revokes the local user session and the owning machine credential.
-- `ADMIN_TOKEN` remains separate and protects administration routes.
-- The existing legacy owner token remains supported only as transitional compatibility while OAuth becomes the normal ChatGPT MCP path.
-
-ChatGPT MCP should connect to the plain `/mcp` endpoint. Compatible clients discover OAuth 2.1 automatically, then use authorization-code login with PKCE S256. OAuth access tokens are audience-bound to `/mcp`; `offline_access` issues rotating refresh tokens. Dynamic client registration and protected-resource/authorization-server discovery are exposed for compatible MCP clients. The legacy `/mcp?key=<USER_TOKEN>` flow remains available only during migration. Browser/device login is for the zero-checkout local CLI and creates the same registry user/agent model used by OAuth.
-
-## MCP tools
-
-Identity and agent routing:
-- `whoami`
-- `list_agents`
-- `ping_agent`
-- `get_config`
-- `get_recent_tool_calls`
-
-Filesystem:
-- `stat_path`
-- `list_directory`
-- `read_file` - bounded by bytes; returns `truncated` and `nextOffset` when more lines remain
-- `read_multiple_files` - bounded aggregate response; supports string paths or per-file `{ path, offset, length, maxBytes }` entries plus `maxTotalBytes`
-- `start_search`
-- `get_more_search_results`
-- `write_file`
-- `edit_block`
-- `create_directory`
-- `move_path`
-- `delete_path`
-
-Processes:
-- `list_processes`
-- `kill_process`
-
-Terminal:
-- `terminal_exec`
-- `terminal_batch_start`
-- `terminal_batch_status`
-- `terminal_batch_read`
-- `terminal_batch_cancel`
-- `terminal_start`
-- `terminal_start_shell`
-- `terminal_read`
-- `terminal_write`
-- `terminal_list`
-- `terminal_kill`
-
-Desktop (Windows/macOS, opt-in):
-- `screenshot` - returns a bounded MCP image content block plus coordinate metadata
-- `mouse_click` - left/right/middle single or double click in desktop coordinates
-- `keyboard_input` - Unicode text or named key/modifier chord
-
-Desktop-Commander-compatible aliases:
-- `start_process`
-- `read_process_output`
-- `interact_with_process`
-- `list_sessions`
-- `force_terminate`
+## `npx` commands
 
-## Administration
+| Command | What it does |
+| --- | --- |
+| `npx @anusornneal/chat-relay@latest remote` | Connects this computer to Chat Relay and keeps the local agent running. Enables the capabilities allowed for this device, such as files, terminal, and processes. |
+| `npx @anusornneal/chat-relay@latest remote --desktop` | Starts the agent with desktop screenshot/input support enabled. Desktop permissions must also be granted by the relay. |
+| `npx @anusornneal/chat-relay@latest login` | Signs in and registers this computer without starting the long-running agent. |
+| `npx @anusornneal/chat-relay@latest login --force` | Forces a fresh sign-in and device authorization. Useful when credentials were revoked or need to be replaced. |
+| `npx @anusornneal/chat-relay@latest status` | Shows the signed-in account, device, relay URL, online state, scopes, agent version, protocol compatibility, lifecycle state, allowed roots, and desktop state. |
+| `npx @anusornneal/chat-relay@latest drain` | Stops accepting new long-running work so active work can finish before a restart. |
+| `npx @anusornneal/chat-relay@latest resume` | Cancels drain mode and resumes normal work admission. |
+| `npx @anusornneal/chat-relay@latest restart` | Restarts the local agent after drain has completed and the agent is ready to restart. |
+| `npx @anusornneal/chat-relay@latest logout` | Revokes this computer login and removes its local credentials. |
+| `npx @anusornneal/chat-relay@latest help` | Shows CLI usage and available options. |
 
-Administration is intentionally separate from MCP. Set the Cloudflare `ADMIN_TOKEN` secret, keep the same value in the local ignored `.dev.vars` on the administrator machine, and use:
+Useful options:
 
-```
-npm run admin -- state
-npm run admin -- bootstrap default "Primary PC"
-npm run admin -- create-user "Alice"
-npm run admin -- create-agent "Work Laptop" work-laptop
-npm run admin -- grant <userId> <agentId> read,write,terminal,process
-npm run admin -- grant <userId> <agentId> desktop_read
-npm run admin -- grant <userId> <agentId> desktop_read,desktop_control
-npm run admin -- revoke <userId> <agentId>
-npm run admin -- enable-user <userId> false
-$env:CHAT_RELAY_PASSWORD="choose-a-password"; npm run admin -- set-login <userId> <login>
-npm run admin -- enable-agent <agentId> false
-npm run admin -- rotate-user <userId>
-npm run admin -- rotate-agent <agentId>
+```text
+--root <path>       Allowed filesystem root. Use semicolons for multiple roots.
+--name <name>       Computer display name.
+--agent-id <id>     Stable agent identifier.
+--desktop           Enable desktop access.
+--no-desktop        Disable desktop access.
+--no-open           Do not open the login browser automatically.
+--force             Force a new login.
+--relay <url>       Use another Chat Relay deployment.
 ```
 
-Create and rotate commands return the new raw token once. Store it on the corresponding client/agent; the registry retains only its hash.
-
-The initial `bootstrap` migrates the legacy `CALLER_TOKEN` and `AGENT_TOKEN` secrets into an owner user and the default agent. To move that existing owner to OAuth without creating a duplicate account, set `CHAT_RELAY_PASSWORD` in the administrator shell and run `npm run admin -- set-login owner <login>`. This attaches login credentials to the same owner user, preserving its grants and agent ownership.
-
-## Worker routes
-
-| Route | Authentication | Purpose |
-| --- | --- | --- |
-| `GET /health` | none | Worker health |
-| `GET /.well-known/oauth-protected-resource[/mcp]` | none | MCP protected-resource metadata |
-| `GET /.well-known/oauth-authorization-server` | none | OAuth authorization-server metadata |
-| `POST /register` | none | Dynamic registration for public PKCE clients |
-| `GET/POST /authorize` | login/password | OAuth authorization-code sign-in |
-| `POST /token` | public client + PKCE/refresh token | Access/refresh token exchange |
-| `POST /auth/device/start` | none | Start CLI device authorization |
-| `GET /device?user_code=<code>` | none | Browser sign-in/approval page |
-| `POST /auth/device/approve` | login/password + device code | Approve or create a user account |
-| `POST /auth/device/token` | device code | Exchange approved device code for session/agent credentials |
-| `GET /auth/me` | user Bearer token | Current user and permitted agents |
-| `POST /auth/session/revoke` | user Bearer token | Revoke only the current user session |
-| `POST /auth/logout` | user Bearer token | Revoke local session and owning agent credential |
-| `POST /mcp` | OAuth Bearer token | Streamable HTTP MCP (normal path) |
-| `POST /mcp?key=<user token>` | legacy user token | Transitional Streamable HTTP MCP compatibility |
-| `GET /agent?agentId=<id>` | agent Bearer token | Local agent WebSocket |
-| `GET /status?agentId=<id>` | user token | Agent online status |
-| `POST /relay?agentId=<id>` | user token | Direct JSON relay with scope checks |
-| `/admin/*` | admin Bearer token | User/agent/grant administration |
-
-## Desktop access (Windows/macOS, opt-in)
-
-Desktop interaction is disabled by default and requires two independent gates:
-
-1. Enable the local agent with `chat-relay remote --desktop` or `DESKTOP_ENABLED=1`. The CLI persists this setting locally. Use `--no-desktop` to disable it again.
-2. Grant `desktop_read` for screenshots and/or `desktop_control` for mouse/keyboard input. Generic read/write/terminal/process scopes do not imply desktop access.
-
-- `screenshot` captures the selected interactive display on Windows or macOS, scales/compresses it to a bounded JPEG, and returns it as an MCP image block. The accompanying metadata contains image size, desktop origin/size, and scale factors for converting screenshot pixels to desktop coordinates.
-- `mouse_click` accepts integer desktop x/y coordinates, button `left|right|middle`, and click count 1 or 2. Invalid/out-of-bounds input is rejected rather than coerced.
-- `keyboard_input` accepts either Unicode `text` or one named `key` with optional Ctrl/Alt/Shift/Win modifiers. Text and key cannot be supplied together.
-- `desktop_step` batches 1-20 actions in one local round trip, compacts adjacent text/waits, and uses adaptive settle delays. It does not capture by default; set `captureAfter: true` when a post-action screenshot is required. Timing metadata separates local queue, input, wait/settle, capture, and encode costs.
-- Windows uses the persistent PowerShell desktop worker. macOS uses built-in `screencapture`, `sips`, `osascript`/JXA, CoreGraphics, and System Events; no extra npm/native dependency is required.
-- macOS desktop capture requires Screen Recording permission for the terminal/Node process, while mouse, keyboard, and window control require Accessibility permission. Missing permissions return controlled errors instead of crashing the reconnect loop.
-- Linux desktop control is not implemented yet and returns `unsupported_platform`.
-- Screenshot bytes, typed text, key chords, and click coordinates are not stored in recentCalls. Only action/timing/success metadata is retained there.
-- This card does not add streaming video, OCR, remote-desktop viewer UI, clipboard sync, drag-and-drop, app-specific automation, or Session 0/service automation.
-
-## Public plugin review
-
-Public ChatGPT onboarding uses the plain production `/mcp` URL and OAuth; the legacy `?key=` route is migration compatibility only. Submission/reviewer requirements, permission boundaries, privacy/retention behavior, domain-verification setup, positive/negative test cases, and clean-room demo steps are maintained in `docs/plugin-review.md`.
-
-The OpenAI domain verification token is served at `/.well-known/openai-apps-challenge` when `OPENAI_APPS_CHALLENGE` is configured. Keep reviewer credentials and challenge values separate from production administrator secrets.
-## Runtime limits and controls
-
-- Per-user durable rate/quota controls are available before local-agent dispatch, but both are disabled by default (`rateLimit=0`, `dailyCallQuota=0`). Set `USER_RATE_LIMIT_PER_WINDOW` and/or `USER_DAILY_CALL_QUOTA` to a positive value to enable them; `USER_RATE_WINDOW_SECONDS` controls the rate window (1-3600 seconds).
-- Admins can inspect or override the effective policy with `GET/POST /admin/api/limits`; POST `{ "resetToDefaults": true }` returns to environment defaults. Rejections return HTTP 429 with `rate_limited` or `quota_exceeded`, `Retry-After`, and reset metadata, and are recorded as bounded usage events without dispatching agent work.
-- Relay request/response message: 64 KiB. The local agent caps serialized responses below that transport ceiling and returns `response_too_large` instead of allowing a silent timeout.
-- `read_file` defaults to a 32 KiB content budget (max 48 KiB) and exposes deterministic `nextOffset` continuation.
-- `read_multiple_files` defaults to a 48 KiB aggregate budget (max 48 KiB). If not all requested files fit, use `nextIndex`; if an individual file is truncated, continue it with that entry's `nextOffset`.
-- One-shot terminal command: max 20 seconds.
-- `terminal_batch_start` accepts 2-20 jobs in one MCP call to avoid N-call E2E dispatch overhead. Each agent owns an independent FIFO queue and bounded execution pool.
-- Batch concurrency defaults to 4 and is capped at 8 per agent. Override with `TERMINAL_BATCH_CONCURRENCY`; queued jobs default to 64 and are capped at 256 via `TERMINAL_BATCH_MAX_QUEUED`.
-- Queue overflow fails fast with `queue_full` instead of spawning unbounded processes. Use `terminal_batch_status`, `terminal_batch_read`, and `terminal_batch_cancel` for lifecycle control.
-- Batch output retained in memory is capped at 8 KiB per job; completed batches are capped at 64 per agent and also expire after 30 minutes.
-- Scaling is horizontal by agent: each connected machine has its own queue/concurrency budget, so additional agents add execution capacity without sharing one local hot queue.
-- Persistent terminal sessions: up to 8 running sessions per local agent.
-- Terminal output buffer: bounded in memory; completed sessions retained for 30 minutes.
-- Filesystem reads/writes are bounded and restricted to configured `ALLOWED_ROOTS`.
-- Search skips common heavy directories such as `.git`, `node_modules`, `.gradle`, `.idea`, and `.wrangler`.
-- The agent blocks a small set of high-risk system-management commands. This is defense in depth, not a security sandbox.
-
-## Audit, retention, and recovery
-
-- Security/admin mutations are recorded in a dedicated `Audit` Durable Object with actor, action, target, result, and sanitized scalar metadata only. Passwords, tokens, cookies, CSRF values, commands, file content, and raw tool payloads are excluded.
-- Raw usage events default to 30-day retention while daily usage aggregates are preserved independently. Set `USAGE_RAW_RETENTION_DAYS` to change raw-event retention.
-- Audit events default to 180-day retention. Set `AUDIT_RETENTION_DAYS` to change that window.
-- `GET /admin/api/audit` returns bounded audit history. `GET /admin/api/operations` exposes component health and last cleanup state. `POST /admin/api/operations/cleanup` performs bounded idempotent cleanup across registry auth transients, raw usage events, and audit history.
-- Cleanup does not intentionally remove active users, grants, agents, live sessions, pending non-expired device authorization, or long-lived usage aggregates.
-- Durable Object state is the production source of truth. Git/npm artifacts do not back it up. Before destructive migration or account transfer, export any operator-required identity/config state separately and treat Cloudflare account/Durable Object recovery controls as the infrastructure recovery boundary.
-- Cleanup failures are surfaced through the operations endpoint and audit result instead of being silently treated as success.
-## Tests
-
-The legacy relay integration test remains available:
+## What ChatGPT can access
 
-```
-npm run dev:test
-python test/integration.py
-```
-
-The full MCP/multi-user smoke test expects a local Worker on port 8795 plus an attached local agent:
+Depending on the device grants and local configuration, Chat Relay can expose:
 
-```
-node test/multiuser-smoke.mjs
-```
+- Filesystem operations inside configured allowed roots.
+- Terminal commands and persistent terminal sessions. Short stateless commands automatically reuse a cross-platform shell pool; stateful commands fall back to isolated execution.
+- Process inspection and termination.
+- Windows/macOS screenshots, mouse input, and keyboard input when desktop access is explicitly enabled.
+- Multiple computers under one account, with per-device routing and permissions.
+- Batched filesystem, terminal, and desktop operations to reduce remote round trips.
 
-It verifies the MCP tool surface, agent routing, filesystem operations, search sessions, process listing, persistent terminals, scope enforcement, multi-agent selection, and token rotation.
+Desktop access is opt-in. Linux desktop control is not currently implemented.
 
-Device/browser login is covered by:
+## How it works
 
-```bash
-TEST_RELAY_URL=http://127.0.0.1:8796 npm run test:device-auth
+```text
+ChatGPT
+   |
+   | Streamable HTTP MCP + OAuth
+   v
+Cloudflare Worker
+   |
+   +-- Registry Durable Object
+   |
+   +-- Relay Durable Object
+           |
+           | WebSocket
+           v
+      Local Agent
+      - files
+      - terminal
+      - processes
+      - desktop
 ```
 
-OAuth discovery, DCR, PKCE, token exchange, refresh rotation, audience binding, MCP Bearer auth, and legacy-key compatibility are covered by:
+ChatGPT talks only to the cloud MCP endpoint. The local computer opens the outbound WebSocket connection to the relay.
 
-```bash
-TEST_RELAY_URL=http://127.0.0.1:8796 npm run test:oauth
-```
+## Security model
 
-Per-user rate/quota enforcement, isolation, reset-window behavior, disabled policy, rejection observability, and pre-dispatch blocking are covered by:
+- ChatGPT MCP authentication uses OAuth 2.1 authorization code flow with PKCE.
+- Local computers use browser/device authorization; raw agent tokens do not need to be copied manually.
+- Filesystem access is constrained to configured allowed roots.
+- Access is scope-based: read, write, terminal, process, desktop read, and desktop control can be granted separately.
+- Desktop access is disabled by default.
+- Stored credentials are hashed server-side where applicable.
+- Persisted usage/audit telemetry is metadata-only and excludes commands, file contents, screenshots, clipboard contents, and credentials.
 
-```bash
-TEST_RELAY_URL=http://127.0.0.1:8804 npm run test:quota
-```
+Chat Relay is currently intended for small trusted teams rather than an enterprise zero-trust control plane.
 
-Desktop tool contracts, scope separation, disabled/unsupported gates, controlled image mapping, and input validation are covered by:
+## Local configuration
 
-```bash
-TEST_RELAY_URL=http://127.0.0.1:8807 npm run test:desktop
-```
+Default CLI config locations:
 
-After `npm pack`, the zero-checkout package smoke test installs and runs the tarball from a temporary directory:
+- Windows: `%LOCALAPPDATA%\chat-relay\config.json`
+- macOS/Linux: `$XDG_CONFIG_HOME/chat-relay/config.json` or `~/.config/chat-relay/config.json`
 
-```bash
-CHAT_RELAY_TARBALL=<path-to-tgz> TEST_RELAY_URL=http://127.0.0.1:8796 npm run test:zero-checkout
-```
+Set `CHAT_RELAY_HOME` to override the config directory.
 
-The npm package is configured as `@anusornneal/chat-relay`. Publishing requires an authenticated npm account with access to that scope.
+A single account can own multiple computers. Each computer keeps its own agent identity and credential.
 
-## CI and npm publishing
+## Development
 
-GitHub Actions runs package verification on Node 20 and Node 24. A separate integration job starts a local Worker and verifies device auth, OAuth, and the zero-checkout tarball flow.
+Clone the repository only when developing Chat Relay itself. Normal users should use the zero-checkout `npx` flow above.
 
-Before publishing locally:
+Common development commands:
 
 ```bash
+npm install
+npm start
+npm run dev
 npm run verify:publish
 ```
 
-This checks the npm file set, CLI entrypoint, Worker dry-run build, and production dependency audit. The package whitelist excludes .dev.vars, Worker source, tests, and repository-only files.
+`npm run verify:publish` checks the publish file set, CLI entrypoint, Worker dry-run build, review artifacts, and production dependency audit.
 
-The repository also includes a Publish npm workflow for version tags or manual dispatch. It supports npm trusted publishing through GitHub OIDC and can also use an NPM_TOKEN repository secret when configured.
+## Administration
+
+Administration is separate from the public MCP interface. The admin tooling manages users, agents, grants, lifecycle, quotas, audit data, and operational cleanup.
 
-The first registry publish still requires npm authorization for the @anusornneal scope. After publishing, verify the exact public UX from a clean directory:
+Operator commands are available through:
 
 ```bash
-npx @anusornneal/chat-relay@latest status
-npx @anusornneal/chat-relay@latest remote
+npm run admin -- <command>
 ```
 
+Keep `ADMIN_TOKEN` and other deployment secrets out of client configuration and source control.
 
-### Safe local-agent restart
-
-Agent updates remain explicit and user-controlled. Check the current agent version, protocol compatibility, and lifecycle with `chat-relay status`.
-
-Before restarting an active remote, run `chat-relay drain`. Drain mode rejects new long-running work while existing terminal/session control remains available so bounded work can finish or be stopped safely. When `status` reports the lifecycle is ready to restart, run `chat-relay restart`. Use `chat-relay resume` to cancel a drain before restart.
-
-To install a newer package, stop/restart the wrapper with the desired npm version (for example `npx @anusornneal/chat-relay@latest remote --desktop`). The agent does not self-modify or automatically cross an incompatible protocol version.
-
-
-### Trusted-team security baseline
-
-Chat Relay is currently designed for a small trusted internal team, not as an enterprise zero-trust control plane. The intentionally small baseline is:
+## Platform notes
 
-- Filesystem access is constrained to configured `allowedRoots`; canonical real paths are checked so `..` traversal and symlink/junction escapes are rejected.
-- Agent grants continue to enforce the existing read/write/process/terminal/desktop scopes. User and agent credentials can be revoked or rotated without retaining raw tokens server-side.
-- Persisted usage/audit/dashboard telemetry is metadata-only. Commands, tool arguments, payloads, stdout/stderr, file contents, clipboard contents, screenshots, credentials, and arbitrary remote messages are excluded.
-- Accidental runaway use is bounded by request/response size limits, rate/quota controls, per-capability queues, queue timeouts, terminal batch limits, and bounded history/query windows.
+- Local agent: Windows and macOS.
+- Desktop control: Windows and macOS.
+- Linux desktop control: not implemented.
+- MCP transport: Streamable HTTP over HTTPS.
+- Local agent transport: outbound WebSocket.
+- Node.js: 20+.
 
-Regression coverage is provided by the filesystem boundary checks in `test/multiuser-smoke.mjs`, credential/scope tests in the device/admin/multi-user smoke suites, telemetry privacy checks in `test/ops-smoke.mjs`, and queue/size tests in the terminal and filesystem smoke suites.
+## More information
 
-Deferred by design: enterprise role hierarchies, approval workflows, device-attestation/trust frameworks, and a general policy engine. Add those only if the deployment threat model changes.
+- Public plugin/reviewer flow: `docs/plugin-review.md`
+- Google sign-in setup: `docs/google-login.md`
+- Source: https://github.com/anusornNeal/chat-relay

package/agent/local-agent.mjs

@@ -25,6 +25,9 @@ const MAX_RESPONSE_BYTES = 60 * 1024;
 const terminals = new TerminalManager({
   batchConcurrency: process.env.TERMINAL_BATCH_CONCURRENCY,
   maxQueuedJobs: process.env.TERMINAL_BATCH_MAX_QUEUED,
+  fastExec: process.env.TERMINAL_FAST_EXEC !== "0",
+  fastExecPoolSize: process.env.TERMINAL_FAST_EXEC_POOL_SIZE,
+  fastExecIdleMs: process.env.TERMINAL_FAST_EXEC_IDLE_MS,
 });
 const scheduler = new CapabilityScheduler({
   maxQueued: process.env.AGENT_MAX_QUEUED,
@@ -116,6 +119,7 @@ async function handlePayload(payload) {
         agentName,
         terminalEnabled,
         terminalBatch: terminals.getBatchConfig(),
+        terminalExec: terminals.getExecConfig(),
         concurrency: scheduler.snapshot(),
         desktop: desktop.getConfig(),
         allowedRoots: files.getRoots(),
@@ -313,6 +317,7 @@ function requireProtocolUpdate(details = {}) {
   const socket = activeSocket;
   activeSocket = null;
   try { socket?.terminate(); } catch {}
+  terminals.close();
   desktop.close();
   const expected = details.expectedProtocolVersion ?? "current";
   const received = details.receivedProtocolVersion ?? agentHello.protocolVersion;
@@ -329,6 +334,7 @@ function requireReauthorization(reason = "credential_revoked") {
   const socket = activeSocket;
   activeSocket = null;
   try { socket?.terminate(); } catch {}
+  terminals.close();
   desktop.close();
   console.error("Agent credential was revoked or rejected.");
   console.error('Recovery: run "chat-relay login --force", then "chat-relay remote".');
@@ -402,6 +408,7 @@ function connect() {
         handlerDurationMs,
         lane: scheduleMeta.lane,
         ...(timing ? { timing } : {}),
+        ...(typeof result?.execMode === "string" ? { execMode: result.execMode } : {}),
         ok: !(result && typeof result === "object" && result.ok === false),
       });
       if (recentCalls.length > 100) recentCalls.shift();
@@ -470,6 +477,7 @@ function restartAgentProcess() {
   const socket = activeSocket;
   activeSocket = null;
   try { socket?.close(1012, "restart_requested"); } catch {}
+  terminals.close();
   desktop.close();
   setTimeout(() => process.exit(AGENT_RESTART_EXIT_CODE), 50);
 }
@@ -483,12 +491,13 @@ function shutdown(reason) {
   const socket = activeSocket;
   activeSocket = null;
   try { socket?.close(1000, "client_shutdown"); } catch {}
+  terminals.close();
   desktop.close();
   setTimeout(() => process.exit(0), 50);
 }
 
 process.once("SIGINT", () => shutdown("SIGINT"));
 process.once("SIGTERM", () => shutdown("SIGTERM"));
-process.once("exit", () => desktop.close());
+process.once("exit", () => { terminals.close(); desktop.close(); });
 
 connect();

package/agent/terminal-manager.mjs

@@ -13,6 +13,11 @@ const MAX_BATCH_CONCURRENCY = 8;
 const DEFAULT_BATCH_CONCURRENCY = 4;
 const DEFAULT_MAX_QUEUED_JOBS = 64;
 const MAX_QUEUED_JOBS = 256;
+const DEFAULT_FAST_EXEC_POOL_SIZE = 2;
+const MAX_FAST_EXEC_POOL_SIZE = 4;
+const DEFAULT_FAST_EXEC_IDLE_MS = 60 * 1000;
+const MIN_FAST_EXEC_IDLE_MS = 5 * 1000;
+const MAX_FAST_EXEC_IDLE_MS = 10 * 60 * 1000;
 const MAX_BATCH_READ_CHARS = 24 * 1024;
 const MAX_JOB_READ_CHARS = 8 * 1024;
 const MAX_RETAINED_BATCHES = 64;
@@ -59,6 +64,7 @@ export function shellForPlatform(platform, preferredShell) {
       displayName: "powershell",
       commandArgs: (command) => ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command],
       interactiveArgs: ["-NoLogo", "-NoProfile", "-NoExit", "-Command", "-"],
+      persistentArgs: ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "-"],
     };
   }
   const file = preferredShell || (platform === "darwin" ? "/bin/zsh" : "/bin/sh");
@@ -67,6 +73,7 @@ export function shellForPlatform(platform, preferredShell) {
     displayName: path.basename(file),
     commandArgs: (command) => ["-lc", command],
     interactiveArgs: ["-l"],
+    persistentArgs: platform === "darwin" && path.basename(file) === "zsh" ? ["-f"] : [],
   };
 }
 
@@ -88,6 +95,410 @@ function terminateProcessTree(platform, pid) {
     }, 150);
   });
 }
+
+function quotePowerShell(value) {
+  return "'" + String(value).replace(/'/g, "''") + "'";
+}
+
+function quotePosix(value) {
+  return "'" + String(value).replace(/'/g, "'\"'\"'") + "'";
+}
+
+function canUsePersistentExec(platform, command) {
+  if (typeof command !== "string" || command.includes("\0")) return false;
+  if (platform === "win32") {
+    return !/\b(exit|stop-process|taskkill(?:\.exe)?|start-process\s+-wait|set-location|push-location|pop-location|set-alias|new-alias|remove-alias|set-variable|new-variable|remove-variable|import-module|remove-module|set-psdebug|set-strictmode)\b|\$(?:env|global|script):/i.test(command);
+  }
+  return !/(^|[^&])&([^&]|$)/.test(command);
+}
+
+function persistentExecScript(platform, command, cwd, marker) {
+  const begin = marker + "_BEGIN__";
+  const endPrefix = marker + "_END_";
+  const endSuffix = "__";
+
+  if (platform === "win32") {
+    const psCommand = quotePowerShell(command);
+    const psCwd = quotePowerShell(cwd);
+    const psBegin = quotePowerShell(begin);
+    const psEndPrefix = quotePowerShell(endPrefix);
+    const psEndSuffix = quotePowerShell(endSuffix);
+    return [
+      "& {",
+      "  [Console]::Out.Write(" + psBegin + ")",
+      "  [Console]::Error.Write(" + psBegin + ")",
+      "  $__ChatRelayOldLocation = (Get-Location).Path",
+      "  $global:LASTEXITCODE = $null",
+      "  $__ChatRelayExitCode = 0",
+      "  try {",
+      "    Set-Location -LiteralPath " + psCwd,
+      "    & ([ScriptBlock]::Create(" + psCommand + "))",
+      "    $__ChatRelaySucceeded = $?",
+      "    if ($null -ne $global:LASTEXITCODE) {",
+      "      $__ChatRelayExitCode = [Math]::Max(0, [Math]::Min(2147483647, [int]$global:LASTEXITCODE))",
+      "    } elseif (-not $__ChatRelaySucceeded) {",
+      "      $__ChatRelayExitCode = 1",
+      "    }",
+      "  } catch {",
+      "    [Console]::Error.Write(($_ | Out-String))",
+      "    $__ChatRelayExitCode = 1",
+      "  } finally {",
+      "    Set-Location -LiteralPath $__ChatRelayOldLocation -ErrorAction SilentlyContinue",
+      "  }",
+      "  $__ChatRelayEnd = " + psEndPrefix + " + [string]$__ChatRelayExitCode + " + psEndSuffix,
+      "  [Console]::Out.Write($__ChatRelayEnd)",
+      "  [Console]::Error.Write($__ChatRelayEnd)",
+      "}",
+    ].join("\n");
+  }
+
+  const shCommand = quotePosix(command);
+  const shCwd = quotePosix(cwd);
+  const shBegin = quotePosix(begin);
+  const shEndPrefix = quotePosix(endPrefix);
+  const shEndSuffix = quotePosix(endSuffix);
+  return [
+    "printf %s " + shBegin,
+    "printf %s " + shBegin + " >&2",
+    "(",
+    "  cd -- " + shCwd + " || exit 200",
+    "  eval " + shCommand,
+    ")",
+    "__chat_relay_exit_code=$?",
+    "printf '%s%s%s' " + shEndPrefix + " \"$__chat_relay_exit_code\" " + shEndSuffix,
+    "printf '%s%s%s' " + shEndPrefix + " \"$__chat_relay_exit_code\" " + shEndSuffix + " >&2",
+  ].join("\n");
+}
+
+class PersistentExecWorker {
+  constructor({ platform, shell }) {
+    this.platform = platform;
+    this.shell = shell;
+    this.child = null;
+    this.startPromise = null;
+    this.current = null;
+    this.reserved = false;
+    this.idleTimer = null;
+  }
+
+  get busy() {
+    return this.reserved || this.current !== null;
+  }
+
+  async run(command, cwd, timeoutMs) {
+    if (this.reserved || this.current) {
+      return { ok: false, exitCode: 1, stdout: "", stderr: "", error: "fast_exec_busy", fastExecUnavailable: true };
+    }
+    this.reserved = true;
+    try {
+      await this.#ensureStarted();
+      if (!this.child?.stdin?.writable) {
+        return { ok: false, exitCode: 1, stdout: "", stderr: "", error: "fast_exec_unavailable", fastExecUnavailable: true };
+      }
+
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+      const marker = "__CHAT_RELAY_" + randomUUID().replace(/-/g, "") + "__";
+      const begin = marker + "_BEGIN__";
+      const endPrefix = marker + "_END_";
+      const endSuffix = "__";
+
+      return await new Promise((resolve) => {
+        const current = {
+          resolve,
+          begin,
+          endPrefix,
+          endSuffix,
+          stdout: "",
+          stderr: "",
+          stdoutBuffer: "",
+          stderrBuffer: "",
+          stdoutStarted: false,
+          stderrStarted: false,
+          stdoutEnded: false,
+          stderrEnded: false,
+          exitCode: 0,
+          startedAt: Date.now(),
+          timer: null,
+        };
+        current.timer = setTimeout(() => {
+          if (this.current !== current) return;
+          this.current = null;
+          void this.#terminate();
+          resolve({
+            ok: false,
+            exitCode: 1,
+            stdout: current.stdout,
+            stderr: current.stderr,
+            error: "Command timed out after " + timeoutMs + "ms",
+            execMode: "persistent-shell",
+          });
+        }, timeoutMs);
+        this.current = current;
+
+        const script = persistentExecScript(this.platform, command, cwd, marker);
+        try {
+          this.child.stdin.write(script + os.EOL + os.EOL);
+        } catch (error) {
+          clearTimeout(current.timer);
+          this.current = null;
+          resolve({
+            ok: false,
+            exitCode: 1,
+            stdout: "",
+            stderr: "",
+            error: error instanceof Error ? error.message : "fast_exec_write_failed",
+            fastExecUnavailable: true,
+          });
+        }
+      });
+    } finally {
+      this.reserved = false;
+    }
+  }
+
+  scheduleIdleClose(idleMs) {
+    if (this.busy || !this.child) return;
+    clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      if (!this.busy) void this.#terminate();
+    }, idleMs);
+    this.idleTimer.unref?.();
+  }
+
+  close() {
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+    void this.#terminate();
+  }
+
+  async #ensureStarted() {
+    if (this.child && !this.child.killed) return;
+    if (this.startPromise) return this.startPromise;
+
+    this.startPromise = new Promise((resolve, reject) => {
+      const child = spawn(this.shell.file, this.shell.persistentArgs || [], {
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        detached: this.platform !== "win32",
+      });
+      const onError = (error) => {
+        cleanup();
+        if (this.child === child) this.child = null;
+        reject(error);
+      };
+      const onSpawn = () => {
+        cleanup();
+        this.child = child;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => this.#onData("stdout", chunk));
+        child.stderr.on("data", (chunk) => this.#onData("stderr", chunk));
+        child.stdin.on("error", (error) => this.#onPipeError(child, error));
+        child.on("exit", (code, signal) => this.#onExit(child, code, signal));
+        child.on("error", () => {});
+        resolve();
+      };
+      const cleanup = () => {
+        child.off("error", onError);
+        child.off("spawn", onSpawn);
+      };
+      child.once("error", onError);
+      child.once("spawn", onSpawn);
+    }).finally(() => {
+      this.startPromise = null;
+    });
+
+    return this.startPromise;
+  }
+
+  #onData(stream, chunk) {
+    const current = this.current;
+    if (!current) return;
+    const bufferKey = stream + "Buffer";
+    const startedKey = stream + "Started";
+    const endedKey = stream + "Ended";
+    const outputKey = stream;
+
+    current[bufferKey] += String(chunk);
+    if (!current[startedKey]) {
+      const beginIndex = current[bufferKey].indexOf(current.begin);
+      if (beginIndex < 0) {
+        if (current[bufferKey].length > current.begin.length) {
+          current[bufferKey] = current[bufferKey].slice(-current.begin.length);
+        }
+        return;
+      }
+      current[bufferKey] = current[bufferKey].slice(beginIndex + current.begin.length);
+      current[startedKey] = true;
+    }
+
+    const endIndex = current[bufferKey].indexOf(current.endPrefix);
+    if (endIndex < 0) {
+      if (Buffer.byteLength(current[bufferKey], "utf8") > MAX_EXEC_BUFFER + current.endPrefix.length + 32) {
+        this.#overflow(stream, current);
+      }
+      return;
+    }
+
+    const tail = current[bufferKey].slice(endIndex + current.endPrefix.length);
+    const suffixIndex = tail.indexOf(current.endSuffix);
+    if (suffixIndex < 0) return;
+
+    current[outputKey] += current[bufferKey].slice(0, endIndex);
+    const parsedCode = Number.parseInt(tail.slice(0, suffixIndex), 10);
+    if (Number.isInteger(parsedCode)) current.exitCode = parsedCode;
+    current[bufferKey] = tail.slice(suffixIndex + current.endSuffix.length);
+    current[endedKey] = true;
+
+    if (Buffer.byteLength(current[outputKey], "utf8") > MAX_EXEC_BUFFER) {
+      this.#overflow(stream, current);
+      return;
+    }
+    this.#completeIfDone(current);
+  }
+
+  #overflow(stream, current) {
+    if (this.current !== current) return;
+    clearTimeout(current.timer);
+    const clipped = clipText(current[stream] + current[stream + "Buffer"], MAX_EXEC_BUFFER);
+    current[stream] = clipped.text;
+    this.current = null;
+    void this.#terminate();
+    current.resolve({
+      ok: false,
+      exitCode: 1,
+      stdout: current.stdout,
+      stderr: current.stderr,
+      error: stream + " maxBuffer exceeded",
+      execMode: "persistent-shell",
+    });
+  }
+
+  #completeIfDone(current) {
+    if (this.current !== current || !current.stdoutEnded || !current.stderrEnded) return;
+    clearTimeout(current.timer);
+    this.current = null;
+    current.resolve({
+      ok: current.exitCode === 0,
+      exitCode: current.exitCode,
+      stdout: current.stdout,
+      stderr: current.stderr,
+      error: current.exitCode === 0 ? null : "Command failed with exit code " + current.exitCode,
+      execMode: "persistent-shell",
+      shellMs: Math.max(0, Date.now() - current.startedAt),
+    });
+  }
+
+  #onPipeError(child, error) {
+    if (this.child !== child) return;
+    const current = this.current;
+    if (!current) return;
+    clearTimeout(current.timer);
+    this.current = null;
+    void this.#terminate();
+    current.resolve({
+      ok: false,
+      exitCode: 1,
+      stdout: current.stdout,
+      stderr: current.stderr,
+      error: "Persistent shell pipe failed: " + (error instanceof Error ? error.message : String(error)),
+      execMode: "persistent-shell",
+    });
+  }
+
+  #onExit(child, code, signal) {
+    if (this.child !== child) return;
+    this.child = null;
+    const current = this.current;
+    if (!current) return;
+    clearTimeout(current.timer);
+    this.current = null;
+    current.resolve({
+      ok: false,
+      exitCode: Number.isInteger(code) ? code : 1,
+      stdout: current.stdout,
+      stderr: current.stderr,
+      error: signal ? "Persistent shell exited with signal " + signal : "Persistent shell exited unexpectedly",
+      execMode: "persistent-shell",
+    });
+  }
+
+  async #terminate() {
+    const child = this.child;
+    this.child = null;
+    if (!child) return;
+    try { child.stdin?.end(); } catch {}
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    await terminateProcessTree(this.platform, child.pid);
+  }
+}
+
+class PersistentExecPool {
+  constructor({ platform, shell, size, idleMs }) {
+    this.platform = platform;
+    this.shell = shell;
+    this.size = size;
+    this.idleMs = idleMs;
+    this.workers = [];
+    this.queue = [];
+  }
+
+  exec(command, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+      this.queue.push({ command, cwd, timeoutMs, resolve });
+      this.#pump();
+    });
+  }
+
+  snapshot() {
+    return {
+      enabled: true,
+      size: this.size,
+      workers: this.workers.length,
+      busy: this.workers.filter((worker) => worker.busy).length,
+      queued: this.queue.length,
+      idleMs: this.idleMs,
+    };
+  }
+
+  close() {
+    for (const worker of this.workers) worker.close();
+    this.workers.length = 0;
+    while (this.queue.length > 0) {
+      const job = this.queue.shift();
+      job.resolve({ ok: false, exitCode: 1, stdout: "", stderr: "", error: "terminal_closed" });
+    }
+  }
+
+  #pump() {
+    while (this.queue.length > 0) {
+      let worker = this.workers.find((item) => !item.busy);
+      if (!worker && this.workers.length < this.size) {
+        worker = new PersistentExecWorker({ platform: this.platform, shell: this.shell });
+        this.workers.push(worker);
+      }
+      if (!worker) return;
+
+      const job = this.queue.shift();
+      worker.run(job.command, job.cwd, job.timeoutMs)
+        .then(job.resolve)
+        .catch((error) => job.resolve({
+          ok: false,
+          exitCode: 1,
+          stdout: "",
+          stderr: "",
+          error: error instanceof Error ? error.message : "fast_exec_unavailable",
+          fastExecUnavailable: true,
+        }))
+        .finally(() => {
+          worker.scheduleIdleClose(this.idleMs);
+          this.#pump();
+        });
+    }
+  }
+}
+
 function clipText(value, limit) {
   const text = typeof value === "string" ? value : "";
   if (text.length <= limit) return { text, truncated: false };
@@ -128,6 +539,28 @@ export class TerminalManager {
       1,
       MAX_QUEUED_JOBS,
     );
+    this.fastExecEnabled = options.fastExec !== false;
+    this.fastExecPoolSize = normalizeInteger(
+      options.fastExecPoolSize,
+      DEFAULT_FAST_EXEC_POOL_SIZE,
+      1,
+      MAX_FAST_EXEC_POOL_SIZE,
+    );
+    this.fastExecIdleMs = normalizeInteger(
+      options.fastExecIdleMs,
+      DEFAULT_FAST_EXEC_IDLE_MS,
+      MIN_FAST_EXEC_IDLE_MS,
+      MAX_FAST_EXEC_IDLE_MS,
+    );
+    this.fastExecPool = this.fastExecEnabled
+      ? new PersistentExecPool({
+          platform: this.platform,
+          shell: this.shell,
+          size: this.fastExecPoolSize,
+          idleMs: this.fastExecIdleMs,
+        })
+      : null;
+    this.fastExecStats = { persistent: 0, isolated: 0, unavailable: 0 };
   }
 
   async exec(command, cwd, timeoutMs) {
@@ -135,6 +568,20 @@ export class TerminalManager {
     const resolvedCwd = safeCwd(cwd);
     const timeout = normalizeTimeout(timeoutMs);
 
+    if (this.fastExecPool && canUsePersistentExec(this.platform, command)) {
+      const result = await this.fastExecPool.exec(command, resolvedCwd, timeout);
+      if (!result?.fastExecUnavailable) {
+        this.fastExecStats.persistent += 1;
+        return result;
+      }
+      this.fastExecStats.unavailable += 1;
+    }
+
+    this.fastExecStats.isolated += 1;
+    return this.#execIsolated(command, resolvedCwd, timeout);
+  }
+
+  #execIsolated(command, resolvedCwd, timeout) {
     return new Promise((resolve) => {
       execFile(
         this.shell.file,
@@ -152,12 +599,27 @@ export class TerminalManager {
             stdout: stdout ?? "",
             stderr: stderr ?? "",
             error: error ? error.message : null,
+            execMode: "isolated",
           });
         },
       );
     });
   }
 
+  getExecConfig() {
+    return {
+      enabled: this.fastExecEnabled,
+      poolSize: this.fastExecPoolSize,
+      idleMs: this.fastExecIdleMs,
+      stats: { ...this.fastExecStats },
+      pool: this.fastExecPool?.snapshot() || null,
+    };
+  }
+
+  close() {
+    this.fastExecPool?.close();
+  }
+
   start(command, cwd, observability) {
     validateCommand(command);
     return this.#spawnSession({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@anusornneal/chat-relay",
-    "version": "0.9.0",
+    "version": "0.9.2",
     "description": "Zero-checkout remote MCP agent for ChatGPT with terminal, filesystem, process, multi-user, and multi-agent support.",
     "type": "module",
     "bin": {