codex-grok-mcp 0.2.0-beta.1

package/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thanks for helping keep this bridge small, safe, and dependable.
+
+## Before opening a change
+
+- Use an issue or discussion before adding tools, adapters, dependencies, authentication paths, or new supported platforms.
+- Preserve the isolated `grok_ask` boundary. Experimental persistent Bot support must stay opt-in, separately paired, and unavailable without a validated private pairing file.
+- Never include credentials, `~/.grok/auth.json`, private prompts, responses, transcripts, or unredacted logs.
+- Never scrape Grok Bot app state, decrypt descriptors, read Keychain, or infer gateway credentials.
+
+## Local setup
+
+```bash
+npm ci
+npm run typecheck
+npm run test:all
+npm run build
+npm run doctor
+```
+
+Use a real live call only with your own Grok account and data you are authorized to send. Unit tests must not require network access or real authentication.
+
+## Pull requests
+
+Keep pull requests focused. Include:
+
+- the user-visible problem and why the existing behavior is insufficient;
+- the smallest implementation that fixes it;
+- one focused regression test for non-trivial behavior;
+- compatibility and security-boundary impact;
+- documentation changes when commands or behavior change;
+- upstream source and license attribution for adapted code.
+
+Before requesting review, run:
+
+```bash
+npm run typecheck
+npm run test:all
+python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins/codex-grok-mcp
+```
+
+Do not update generated package versions in feature pull requests unless the maintainer asks. Do not add postinstall scripts or telemetry.
+
+## Compatibility claims
+
+Mocks and unit tests are not platform proof. To add a supported compatibility row, provide a redacted live smoke-test result showing the OS/architecture, Node version, Codex version, Grok CLI version, selected model, and successful response. Do not include response content.
+
+## New adapters and tools
+
+The core `grok_ask` tool stays isolated from optional adapters. A new adapter needs:
+
+- a documented upstream contract and operator-authorized credentials or pairing;
+- an identified maintenance owner;
+- a separate explicit configuration path;
+- tests and threat-boundary documentation;
+- no scraping, Keychain extraction, internal gateway credentials, or silent fallback.
+
+Persistent Grok Bot integration is accepted only through an official inbound API or a clearly separated experimental adapter.
+
+The paired bridge is the narrow exception: its bounded local client discovers the loopback gateway only inside the Grok VM; the gateway token never leaves that VM; the self-hosted relay authenticates native clients before allocation and forwards only authenticated ciphertext; the companion exposes only metadata-only status, roster listing, exact-ID bounded text/status reads, and exact-ID sends. Preserve the strict status allowlist; exact-ID and non-group checks; text-only sanitization and byte ceilings; Bot-bound opaque pagination; the untrusted-content, no-correlation, and no-completion-claim boundaries; and protocol-v3 status plus protocol-v2 reads with explicit `UPGRADE_REQUIRED` for an older companion while v1 list/send remains compatible. For writes, preserve fingerprint-bound plus native-user-confirmed `PING`-to-all, sequential one-shot delivery, cached replay receipts, per-Bot receipts, no automatic retries, `outcome_unknown` for ambiguous sends, and `not_attempted` after cancellation. Keep the legacy URL/token transport out of the default plugin environment. Tests must use mock gateways/relays; distinguish metadata-only live probes from live read or message compatibility.
+
+## Governance and license
+
+Fato07 is the initial maintainer. Maintainer approval and passing checks are required to merge. There is no CLA or DCO at this stage.
+
+By contributing, you agree that your contribution is licensed under the repository's MIT License and that you have the right to submit it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fato07
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# Codex Grok MCP
+
+<p align="center">
+  <img src="plugins/codex-grok-mcp/assets/icon.png" alt="Codex Grok MCP icon" width="180" />
+</p>
+
+An unofficial, local-first MCP bridge that lets Codex ask the authenticated Grok CLI for a bounded second opinion. Its experimental paired bridge can also read bounded status and sanitized recent text from, or message, an exact persistent Grok Bot without exporting Grok Bot's gateway credential.
+
+> [!IMPORTANT]
+> Each `grok_ask` call sends the supplied prompt to xAI/Grok and consumes allowance from the signed-in Grok account. Experimental Bot sends are separate external writes. Bot reads expose sensitive transcript text to Codex as untrusted external content. This project is not affiliated with or endorsed by OpenAI or xAI.
+
+The public beta is distributed as the exact npm package `codex-grok-mcp@0.2.0-beta.1` and an immutable GitHub prerelease.
+
+## What it is
+
+```text
+Codex -> local MCP server -> isolated Grok CLI -> xAI
+                           -> authenticated encrypted relay <- companion in Grok Bot VM
+                                                    -> local gateway -> named Bots
+```
+
+The default connector exposes `grok_ask` plus the read-only `grok_bridge_status`. The ask tool pins a Grok model, runs one turn without subagents, and always disables Grok web search. Status returns only local mode/version metadata until the bridge is paired.
+
+`grok_ask` talks to **Grok CLI**, not a persistent named **Grok Bot**. It cannot enter a Bot conversation, use Bot memory, read Bot transcripts, or control the Grok Bot desktop app.
+
+After pairing, the server additionally exposes `grok_list_bots`, `grok_read_bot`, `grok_wait_for_bot`, `grok_send_bot_message`, and `grok_ping_all_bots`. `grok_bridge_status` then performs an authenticated metadata-only handshake that returns connector and companion versions, supported bridge capabilities, gateway health/busy state, and the non-group Bot count—never Bot identities, relay details, credentials, or content. Codex and the VM companion initiate outbound WebSocket connections to an opaque relay. A bearer derived for one random channel blocks anonymous or cross-channel relay allocation, while AES-256-GCM encrypts application frames end to end. The relay sees connection metadata, a random channel, and roles, but not Bot IDs, names, or messages. The Grok gateway token remains inside the managed VM.
+
+The VM companion implements only local discovery, health, roster listing, exact-ID bounded text/status reads, and exact-ID send. Each bridge operation pins one verified local gateway descriptor and token, so an exact-ID roster check and its subsequent read or send cannot cross a gateway restart. Its unofficial gateway contract was cross-checked against the MIT-licensed [`grokbot-sdk`](https://github.com/Adam91holt/grokbot-sdk), but the Node-22-only SDK is not a runtime dependency because the live Grok Bot VM currently provides Node.js 20. Group rooms are excluded from the Bot roster and fail closed on reads. A live metadata-only probe has verified local gateway discovery and full-roster access inside a Grok Bot VM; paired reads and sends remain experimental and may break when Grok Bot changes.
+
+## Five-minute local install
+
+Prerequisites:
+
+- macOS; this is the only platform verified for the isolated CLI path in this beta.
+- Node.js 20.19.2 or newer.
+- Codex CLI/desktop.
+- Grok CLI installed and signed in. Confirm with `grok --version` and `grok models`.
+
+Install the repository marketplace at the immutable beta tag, then install the plugin:
+
+```bash
+codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.1
+codex plugin add codex-grok-mcp@codex-grok
+```
+
+Start a new Codex task so it discovers the plugin, then try:
+
+```text
+Ask Grok to challenge this architecture and return the three strongest objections.
+```
+
+The plugin uses `npx` to run only `codex-grok-mcp@0.2.0-beta.1`. It does not modify Grok authentication.
+
+## Direct Codex MCP setup
+
+If you do not want the plugin wrapper:
+
+```bash
+codex mcp add grok -- npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-mcp
+```
+
+Start a new Codex task after adding the server, then ask Codex to use `grok_ask`.
+
+## Doctor
+
+Run after the local package installation:
+
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-mcp --doctor
+```
+
+Doctor checks local prerequisites and configuration without sending a prompt to Grok. It must not print authentication material.
+
+## Pair persistent Grok Bots
+
+The repository contains a small Cloudflare Durable Object relay in [`relay/`](relay/). It forwards opaque frames, stores no messages or credentials, hibernates while idle, and is not deployed automatically.
+
+Deploy your own relay, then pair Codex on the Mac. The same random master token must be set in Cloudflare and supplied once to the local pairing command. Pairing derives a channel-only bearer for both clients; the deployment master is not copied into the pair code or Grok VM, and neither credential appears in a relay URL.
+
+```bash
+cd relay
+npm ci
+RELAY_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+printf 'RELAY_ACCESS_TOKEN=%s\n' "$RELAY_TOKEN" | npx wrangler deploy --secrets-file /dev/stdin
+
+cd ..
+CODEX_GROK_RELAY_TOKEN="$RELAY_TOKEN" npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-mcp pair --relay-url wss://YOUR-WORKER.workers.dev/v1/connect
+unset RELAY_TOKEN
+```
+
+The pairing command requires an interactive terminal and prints the credential only there. Keep it private. In **Grok Bot's Computer** terminal—not in a Bot chat—run the exact companion release and paste the code into the no-echo prompt:
+
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-bridge probe
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-bridge connect
+```
+
+To update an already paired companion, stop the foreground process with `Ctrl-C`, then run the exact package version with `run`; pairing again is unnecessary:
+
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-bridge probe
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-bridge run
+```
+
+Do not run a mutable GitHub default branch inside the credential-bearing VM. Always pin an exact audited package version.
+
+`probe` returns only gateway health, process metadata, Bot count, and a roster fingerprint. It never prints the gateway token, URL, Bot names, IDs, transcripts, or prompts.
+
+The source beta companion currently runs in the foreground. Keep that terminal running while using the Bot tools. Background survival across Grok VM idle periods and computer updates is not yet claimed. The replay ledger survives restarts under `${XDG_STATE_HOME}/codex-grok-mcp/replay` when `XDG_STATE_HOME` is absolute, or `~/.local/state/codex-grok-mcp/replay` otherwise. One exclusive lease prevents two companion processes from running against the same pairing; stop the current companion before updating, forcing a new pairing, or unpairing. A clean stop removes its lease. After an unclean crash, startup fails closed with `companion_lease_stale`; verify that the recorded PID is no longer running before manually removing the exact `bridge.json.lock` beside the pairing file. Automatic stale-lock reclamation is intentionally disabled to avoid two starters racing into the same pairing. Unpairing removes the saved copy but deliberately leaves fresh replay markers in place. Close old Codex tasks too: an already-running process retains configuration loaded into memory. `pair --force` prepares a new channel for future processes but does not revoke an old relay channel; suspected credential exposure requires stopping both sides, rotating the relay master, and pairing again.
+
+## Configuration
+
+Configuration is operator-owned and optional:
+
+| Variable | Default | Constraint |
+|---|---|---|
+| `GROK_MCP_BIN` | `grok` | Absolute Grok CLI path when overridden |
+| `GROK_MCP_MODEL` | `grok-4.6` | `grok-4.6` or `grok-4.5` |
+| `GROK_MCP_TIMEOUT_MS` | `180000` | Integer from `5000` to `600000` |
+| `GROK_MCP_AUTH_PATH` | `~/.grok/auth.json` | Absolute or working-directory-relative auth file path |
+| `CODEX_GROK_RELAY_TOKEN` | none | Exact 32-byte base64url relay master; required only by the manual `pair` command and not copied into its output |
+
+The plugin passes only these connector-specific overrides through its MCP configuration. The connector itself supplies a narrow child environment for Grok CLI. Paired bridge configuration is stored locally in a mode-`0600` file under the user's configuration directory; it is never accepted as tool input.
+
+The old `GROKBOT_GATEWAY_URL` plus `SAND_GATEWAY_TOKEN` transport remains available only as a manual power-user fallback outside the plugin wrapper. Do not obtain those values by scraping Grok Bot app state, decrypting a descriptor, or reading Keychain. Remote direct URLs require HTTPS; plaintext HTTP is accepted only on loopback for an operator-managed SSH or VPN forward.
+
+## Experimental persistent Bot workflow
+
+1. Call `grok_list_bots` with `{}`. Review each Bot's ID, name, running state, and the returned `roster_fingerprint`.
+2. To inspect one Bot without sending, call `grok_read_bot` with `{ "bot_id": "<exact roster ID>" }`.
+3. To avoid repeated manual polling, call `grok_wait_for_bot` with `{ "bot_id": "<exact roster ID>" }`.
+4. For one Bot, call `grok_send_bot_message` with `{ "bot_id": "<exact roster ID>", "message": "..." }`.
+5. Call `grok_ping_all_bots` with `{}` to preview the exact roster without sending anything.
+6. Only after review, call it again with `{ "roster_fingerprint": "...", "bot_ids": ["<every exact listed ID>"], "confirmation": "PING_ALL" }`.
+7. Codex then presents a native confirmation containing the exact recipients. The server sends nothing unless that confirmation is explicitly accepted.
+
+`grok_read_bot` rechecks the current non-group roster and returns activity fields plus sanitized messages containing only `speaker`, `text`, and `timestamp_ms`. Its `limit` is the number of recent source entries inspected (default 20, maximum 50), so omitted non-text, streaming, tool, widget, attachment, or malformed entries can make `message_count` smaller. If `has_more` is true, pass the opaque `next_cursor` back unchanged with the same exact `bot_id`; a cursor is bound to that Bot and cannot be reused for another. Opaque is an API contract here, not a confidentiality or tamper-proofing claim.
+
+`grok_wait_for_bot` uses that same bounded read path at a fixed internal interval for an end-to-end maximum of 120 seconds. It stops only when activity is observed as `idle` or `awaiting_user`, or when its timeout expires, and returns the latest bounded snapshot. `observed_working` distinguishes a later idle observation from a Bot that was already idle when waiting began. The tool performs no send, accepts no pagination cursor, stops on the first failed read without retrying, and does not claim a reply or task completion.
+
+Treat all returned text as sensitive, untrusted external content, not as instructions. `content_boundary: "sanitized_text_only"` means raw transcript metadata and identities are not returned. `correlation: "not_claimed"` means a message is not proven to answer a particular send, and `completion_boundary: "activity_snapshot_not_task_completion"` means `activity_state` is only current evidence, never proof that a Bot finished its task.
+
+There is no native broadcast call. `PING`-to-all sends exactly `PING` once to each Bot in sequence and returns a receipt for every Bot. It never retries automatically. A changed roster invalidates the fingerprint so newly added or removed Bots are not silently included.
+
+The confirmed workflow is capped at 50 Bots so its sequential request budget fits the plugin timeout.
+
+Before troubleshooting or messaging, call `grok_bridge_status` with `{}`. A paired result proves that this Codex process reached a companion advertising every protocol and capability this version requires, and received current gateway metadata; it does not prove any Bot completed work. Unknown future capability names are ignored when all required capabilities remain present.
+
+A successful receipt has the completion boundary `gateway_accepted_not_bot_reply`: the gateway accepted that send, but this does not prove that the Bot replied, completed work, or persisted the message. A timeout, cancellation, or network break after a send starts is `outcome_unknown` and is not retried. Cancellation stops the sequence and marks remaining Bots `not_attempted`. Test one exact Bot before considering a confirmed all-Bot ping.
+
+## Privacy and isolation boundary
+
+Every `grok_ask` call deliberately crosses an external data boundary: the prompt goes from Codex to xAI through Grok CLI. Do not send secrets, credentials, private source, personal data, or regulated data unless you are authorized to share it with xAI.
+
+The Grok child process runs with private temporary `HOME` and `GROK_HOME` directories. Only the existing authentication file—`~/.grok/auth.json` by default—is symlinked into the isolated `GROK_HOME`; the connector checks the file but does not read it. The rest of the user's `~/.grok` state—sessions, memory, plugins, logs, configuration, and Bot data—is not mounted into the child home. The connector removes its prompt file and temporary home after each call.
+
+This boundary limits what the Grok child discovers by default. It is not a general sandbox for the Codex process or this Node.js MCP server. The paired Bot bridge is a separate network and credential boundary; it does not weaken or reuse the isolated `grok_ask` runner.
+
+The connector does not intentionally log prompt, response, or Bot transcript content, child arguments, stdout/stderr, environment values, authentication data, or temporary paths. Safe operational fields may include the connector version, elapsed time, prompt byte count, a request identifier, and a coarse exit category.
+
+## Compatibility
+
+| Environment | Status |
+|---|---|
+| macOS, current local Codex and Grok CLI | Verified target for `0.2.0-beta.1` isolated CLI path |
+| Linux | Planned; unverified |
+| Windows / WSL | Unverified |
+| Codex cloud | Unsupported; the connector needs a local Grok executable and login |
+| Grok Bot VM gateway discovery and roster probe | Verified metadata-only on Node.js 20.19.2 |
+| Paired bounded Bot reads | Experimental; live operator smoke test passed on the current private beta |
+| Paired exact-ID Bot messaging | Experimental; gateway acceptance and later bounded transcript observation passed in a live operator smoke test |
+| Background companion lifecycle | Unsupported; foreground operation only |
+
+Passing unit tests is not compatibility proof. A platform becomes supported only after a live model-identity smoke test.
+
+## Troubleshooting
+
+### `codex-grok-mcp` is not found
+
+Run the pinned package doctor directly:
+
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-mcp --doctor
+```
+
+### Grok CLI is missing or not signed in
+
+Run:
+
+```bash
+grok --version
+grok models
+```
+
+Complete Grok's normal login flow outside Codex, then rerun doctor. This connector never asks Codex for tokens or passwords.
+
+### The requested Grok model is unavailable
+
+Use `grok models` to inspect what the signed-in account can access. The connector fails closed instead of silently using the Grok CLI default, because that default may not be a Grok model.
+
+### The request times out or allowance is exhausted
+
+Retry only after checking the Grok account and direct CLI behavior. A retry consumes another request if the first one reached xAI.
+
+### Codex does not show the tool
+
+Run `codex plugin marketplace list`, confirm the `codex-grok` Git marketplace, reinstall the plugin, and start a new task. For direct setup, inspect `codex mcp list`.
+
+### Direct CLI works but the connector fails
+
+Run the pinned package doctor, record the connector, Node, Codex, Grok CLI, OS, and architecture versions, and report a bug with redacted output. Never attach `~/.grok/auth.json`, prompts, responses, or transcripts.
+
+### Experimental Bot tools do not appear
+
+Confirm `RELAY_ACCESS_TOKEN` is set on the relay, run the pinned `codex-grok-mcp pair` command with the same value in `CODEX_GROK_RELAY_TOKEN`, keep the pinned `codex-grok-bridge connect` command running in Grok Bot's Computer, and start a new Codex task. Never paste the pairing code or gateway token into a Bot/Codex prompt or issue.
+
+If `grok_bridge_status` or `grok_read_bot` returns `UPGRADE_REQUIRED`, update and restart the VM companion. Status uses bridge protocol v3, reads use v2, and roster listing plus sends remain compatible with v1.
+
+## Uninstall
+
+If installed as a plugin, uninstall **Codex Grok MCP** in the Codex desktop app, then remove the local marketplace:
+
+```bash
+codex plugin marketplace remove codex-grok
+```
+
+If configured directly, remove that MCP entry too:
+
+```bash
+codex mcp remove grok
+```
+
+Remove both pairing files before uninstalling:
+
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-mcp unpair
+npx --yes --package=codex-grok-mcp@0.2.0-beta.1 -- codex-grok-bridge unpair
+```
+
+Uninstalling does not change or delete Grok CLI authentication or account data.
+
+## Development
+
+```bash
+npm ci
+npm ci --prefix relay
+npm run typecheck
+npm run test:all
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before opening a change.
+
+## License and attribution
+
+MIT. The process-runner design was informed by the MIT-licensed [`libraz/grok-mcp`](https://github.com/libraz/grok-mcp). The bounded Grok Bot gateway contract was cross-checked against the MIT-licensed [`Adam91holt/grokbot-sdk`](https://github.com/Adam91holt/grokbot-sdk). See repository history and accompanying notices for exact reused or adapted code if applicable.

package/SECURITY.md

@@ -0,0 +1,109 @@
+# Security policy
+
+## Supported versions
+
+`0.2.0-beta.1` is the supported public beta. Security fixes target the current source revision and the next prerelease.
+
+## Trust boundary
+
+```text
+Codex -> local MCP server -> isolated Grok CLI -> xAI
+```
+
+With an experimental paired bridge, there is a second, separate boundary:
+
+```text
+Codex -> local MCP server -> opaque relay <- companion in Grok Bot VM
+                                              -> loopback gateway -> named Bots
+```
+
+Calling `grok_ask` sends the supplied prompt to xAI and consumes Grok account allowance. Treat that transmission as an external write even though the tool returns analysis rather than modifying files or public state.
+
+The connector is designed to:
+
+- invoke Grok without a shell;
+- pass prompts through a private temporary file rather than process arguments;
+- run Grok with a private temporary home;
+- link only the existing Grok authentication file into that home;
+- avoid inheriting arbitrary environment variables;
+- remove temporary material after the child exits;
+- cap input, output, runtime, and concurrency;
+- pin an allowed Grok model instead of trusting the user's CLI default.
+
+The authentication link lets Grok use and refresh the user's existing login. By default, it points from the temporary `GROK_HOME/auth.json` to `~/.grok/auth.json`; `GROK_MCP_AUTH_PATH` can select a different operator-owned file. The connector checks that file but does not read or copy it. The link is still a sensitive capability, and the connector must never print, return, upload, or persist its contents.
+
+The isolation boundary deliberately excludes normal Grok sessions, memory, configuration, plugins, logs, internal Grok Bot state, Keychain material, and undocumented gateway credentials. It narrows Grok CLI discovery; it is not a general sandbox for Codex or the Node.js MCP process.
+
+Only `PATH`, locale, and TLS certificate discovery values are inherited into the Grok child where present. Connector options are restricted to `GROK_MCP_BIN`, `GROK_MCP_MODEL`, `GROK_MCP_TIMEOUT_MS`, and `GROK_MCP_AUTH_PATH`.
+
+## Experimental paired Grok Bot bridge
+
+The persistent Bot adapter is registered only after a pairing file passes strict validation. Pairing generates a random 128-bit channel identifier and 256-bit AES key. It derives a 256-bit channel bearer with HMAC-SHA-256 from the operator's relay master; the master stays on the Mac and in the Cloudflare secret and is not copied into the pair code or VM. Both client copies are stored in a mode-`0600` file under a mode-`0700` directory. Pair codes and files are credentials: never paste them into Codex/Bot prompts, issues, logs, or process arguments. The Mac command emits a code only to an interactive terminal; the VM companion reads it with terminal echo disabled.
+
+Codex and the VM companion make outbound WebSocket connections. Before allocating a Durable Object, the included relay derives and checks the bearer for that exact channel and rejects browser-originated connections. Application frames use AES-256-GCM with random nonces and authenticated data binding the protocol version, channel, and sender role. The relay routes opaque frames between one `codex` and one `bridge` socket per channel, caps frames at 128 KiB, stores no payloads or credentials, and contains no payload logging. Default Cloudflare invocation logs and traces are explicitly disabled because the channel appears in the request path. The relay can still observe live connection timing, IP metadata, the random channel, and roles; it can drop, replay, or delay traffic, but it cannot decrypt or forge valid frames without the pairing key. The included deployment master is intended for one operator's self-hosted relay, not a shared public service.
+
+Each request also carries an authenticated timestamp and UUID. The companion rejects requests older than 60 seconds before invoking the gateway, persists send UUIDs to a private bounded ledger before delivery, and caches authenticated responses in memory. The ledger uses a mode-`0700` persistent XDG state directory and mode-`0600` markers; unpairing does not remove fresh markers. A same-process duplicate receives the original receipt; a replay after restart is blocked and reported as `outcome_unknown`. One process-wide in-flight guard remains active across relay reconnects. An exclusive config-path lease prevents concurrent companions, forced re-pairing, or unpairing from racing a live process. Stale leases fail closed and require operator-verified manual removal; the connector never races to reclaim them automatically. The same UUID is also sent as the gateway `clientNonce`, but callers do not rely on undocumented host deduplication.
+
+The companion uses a Node-20-compatible local client for a bounded loopback-only command set: discovery, health, `listAgents`, transcript-tail and activity-status reads, and exact-ID `sendPrompt`. The contract was cross-checked against the MIT-licensed `grokbot-sdk`; the full SDK is not installed because it declares Node.js 22 while the verified VM provides Node.js 20. Each whole bridge operation pins one verified descriptor/token snapshot, including its roster check and subsequent reads or send. Every subrequest verifies that snapshot before dispatch and again after the complete bounded body passes schema validation; rotation fails closed without retry. For a send, any failure after send dispatch remains delivery-uncertain. Standalone client calls outside a bridge operation resolve a fresh snapshot per request. The client also bounds response bytes and duration, rejects redirects and non-loopback URLs, validates descriptor ownership and permissions, verifies on Linux that the descriptor PID owns the listening socket, validates response shapes, and sanitizes errors. The gateway token stays in VM memory and is never returned to Codex or the relay. The companion does not expose arbitrary gateway commands, raw transcript rows, files, shell, delete/reset, or credential APIs. It refreshes the roster before every read or send.
+
+`grok_bridge_status` is always registered. Without pairing it returns only connector mode and version; with the legacy direct adapter it does not probe the gateway. In paired mode, its authenticated protocol-v3 request returns only the companion version, bounded protocol versions and capability names, gateway health/busy booleans, and non-group Bot count. The MCP side requires every protocol and capability used by its current Bot tools while tolerating additional bounded future capabilities. Bot identities, relay details, credentials, paths, transcripts, and prompts are excluded by a strict response schema.
+
+`grok_read_bot` is read-only and requires an exact ID from the current non-group roster. It accepts at most 50 recent source entries, returns only recognized plain-text message shapes, removes raw identities and metadata, normalizes line endings, strips control and bidirectional-override characters, and bounds each message to 16 KiB, aggregate text to 48 KiB, and the normalized snapshot to 64 KiB. Streaming, tool, widget, attachment, event, unknown, and malformed entries are omitted. Returned text remains sensitive, untrusted external content and must not be treated as instructions.
+
+`grok_wait_for_bot` is an MCP-side bounded loop over the same exact-ID read path, not a new bridge operation or event stream. It retains only the latest bounded snapshot, applies an end-to-end deadline of at most 120 seconds across roster lookup, relay queueing, reads, and waits, stops only on observed `idle` or `awaiting_user` activity or timeout, and propagates cancellation or the first failed read without retry. Its `observed_working` field distinguishes later idle activity from an initially idle Bot, and its result preserves the same untrusted-content, no-correlation, and no-completion-claim boundaries.
+
+Read pagination wraps the upstream sequence boundary in a canonical, Bot-bound API cursor. The cursor is opaque by contract, not secret or tamper-proof; callers must pass it back unchanged. Read output states `content_boundary: "sanitized_text_only"`, `correlation: "not_claimed"`, and `completion_boundary: "activity_snapshot_not_task_completion"`: status is a point-in-time activity signal, not proof of task completion, and transcript order does not prove that a message replies to a particular send. Status uses bridge protocol v3, reads use v2, and v1 roster and send operations remain compatible. An older companion that rejects status or a read is surfaced as `UPGRADE_REQUIRED` and must be updated and restarted.
+
+The legacy direct adapter remains available for manual power users only when both `GROKBOT_GATEWAY_URL` and `SAND_GATEWAY_TOKEN` are explicitly configured outside the plugin wrapper. The connector must not discover them by scraping Grok Bot app state, decrypting local descriptors, reading Keychain, or inspecting another process. Remote direct URLs require HTTPS; plaintext HTTP is accepted only on loopback for operator-managed SSH or VPN forwarding.
+
+Bot sends are external writes. `grok_send_bot_message` requires an exact Bot ID from `grok_list_bots`. An empty `grok_ping_all_bots` call is a no-write preview; the write requires the current `roster_fingerprint`, every exact listed `bot_id`, and `confirmation: "PING_ALL"`, followed by an accepted native MCP user-confirmation request containing the recipients. It rechecks the roster, sends the fixed message `PING` sequentially, records a per-Bot receipt, and never retries automatically. It does not use a native broadcast endpoint. A roster change or declined confirmation fails closed without sending.
+
+A timeout, cancellation, malformed response, ambiguous HTTP status, or network break after a send starts is reported as `outcome_unknown`, not failed, because the write may have reached the gateway. Relay close codes are untrusted and cannot turn a post-send outcome into a definite failure. Cancellation stops the sequence and marks remaining targets `not_attempted`.
+
+The send completion boundary `gateway_accepted_not_bot_reply` is not proof of a Bot reply, task completion, or message persistence. The gateway protocol is unofficial and unsupported by xAI; compatibility and security behavior may change without notice. A live paired operator smoke test verified roster listing, unique exact-ID gateway acceptance receipts, and later bounded transcript observation without connector errors or retries. Transcript position still does not prove reply correlation, and background lifecycle remains unverified.
+
+## Logging and diagnostics
+
+Logs and errors must not contain:
+
+- prompt or response content;
+- child command arguments;
+- stdout or stderr bodies;
+- environment values;
+- credentials or authentication files;
+- gateway URLs or tokens;
+- relay URLs, pairing codes, channels, or encryption keys;
+- temporary file or directory paths;
+- Grok sessions, transcripts, memory, or Bot data.
+
+Allowed operational fields are limited to a request identifier, connector version, elapsed milliseconds, prompt byte count, and a coarse exit category.
+
+Doctor must be read-only and must not submit a model request.
+
+## User responsibilities
+
+- Do not send data to Grok unless you are authorized to share it with xAI.
+- Keep `~/.grok/auth.json` private and never attach it to an issue.
+- Review xAI account, privacy, and allowance terms before use.
+- Verify uncertain failures through the direct Grok CLI before retrying; a request may already have consumed allowance.
+- For Bot sends, inspect per-Bot receipts before any new attempt; an accepted or timed-out request may already have reached a Bot.
+- Enter pairing codes only in Grok Bot's Computer terminal, never in a Bot/Codex prompt. `pair --force` changes the saved channel for future processes but does not revoke the old stateless relay channel. If pairing material may have been exposed, stop both sides, end old Codex tasks, rotate the relay master, and pair again.
+- Keep the VM companion in the foreground until a supported lifecycle mechanism is verified. A stopped companion means Bot tools are unavailable, not safe to retry after an uncertain send.
+- For the legacy fallback, provide only a gateway URL and token you are authorized to use. Never paste the token into prompts or issue reports.
+- Install only audited source or an exact immutable maintainer-controlled release. Never execute a mutable GitHub default branch inside the Grok Bot VM.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability or credential exposure. Use the repository's private GitHub **Report a vulnerability** flow when available; otherwise contact the maintainer privately through the source distribution channel.
+
+Include a minimal reproduction, affected revision/version, OS and architecture, Node/Codex/Grok CLI versions, and impact. Redact prompts, outputs, paths, tokens, environment values, and account information.
+
+The maintainer will acknowledge a valid report as soon as practical, coordinate remediation privately, and publish a security advisory when users need to act. There is no paid bug bounty or response-time SLA.
+
+## Out of scope
+
+- Vulnerabilities in Codex, Grok CLI, xAI, Node.js, or the operating system that do not arise from this connector.
+- Reports requiring access to another person's account or credentials.
+- Social engineering, denial-of-service testing, or testing against xAI infrastructure.
+- The behavior, availability, or security of the unofficial Grok Bot gateway itself.
+- Denial of service by a relay operator; end-to-end encryption provides confidentiality and integrity, not availability.

package/dist/bridge-companion.d.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { type LocalAgentSummary, type LocalGatewayDiscovery, type LocalGatewayHealth, type LocalSendPromptInput } from "./grok-bot-client.js";
+import { type BridgeRequest, type BridgeResponse } from "./bridge-protocol.js";
+import { type PairingConfig } from "./bridge-pairing.js";
+export type BridgeProbeClient = {
+    discovery(): Pick<LocalGatewayDiscovery, "port" | "pid" | "hasToken">;
+    health(): Promise<Pick<LocalGatewayHealth, "ok" | "isBusy">>;
+    listAgents(): Promise<Array<Pick<LocalAgentSummary, "awaitingUserResponse" | "id" | "isComposingMessage" | "isGroup" | "isRunning" | "name">>>;
+};
+export type BridgeClient = BridgeProbeClient & {
+    withGatewaySnapshot?<T>(operation: () => Promise<T>): Promise<T>;
+    getAgentTranscriptTail(input: {
+        id: string;
+        limit: number;
+        beforeSeq?: number;
+    }): Promise<{
+        entries: unknown[];
+        nextBeforeSeq?: number | undefined;
+    }>;
+    getAsyncTasks(input: {
+        id: string;
+    }): Promise<unknown[]>;
+    getSubagents(input: {
+        id: string;
+    }): Promise<Array<{
+        status: string;
+    }>>;
+    sendPrompt(input: LocalSendPromptInput): Promise<{
+        accepted: true;
+    }>;
+};
+export type BridgeProbeResult = {
+    gateway: {
+        port: number;
+        pid: number;
+        hasToken: boolean;
+    };
+    health: {
+        ok: boolean;
+        busy: boolean;
+    };
+    bot_count: number;
+    roster_fingerprint: string;
+};
+type Writer = {
+    write(chunk: string): unknown;
+};
+type CliDependencies = {
+    createClient?: () => BridgeClient;
+    readPairCode?: () => Promise<string>;
+    runBridge?: (config: PairingConfig, client: BridgeClient) => Promise<void>;
+    configPath?: string;
+    stdout?: Writer;
+    stderr?: Writer;
+};
+export declare function createBridgeProbeClient(): BridgeClient;
+export declare function probeBridge(client: BridgeProbeClient): Promise<BridgeProbeResult>;
+export declare function handleBridgeRequest(client: BridgeClient, request: BridgeRequest): Promise<BridgeResponse>;
+export declare function runBridge(config: PairingConfig, client?: BridgeClient, signal?: AbortSignal, replayRoot?: string): Promise<void>;
+export declare function runBridgeCompanion(argv: string[], dependencies?: CliDependencies): Promise<number>;
+export {};