grok-bot-cli 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# grok-bot-cli
+
+## 0.4.0
+
+### Minor Changes
+
+- 1dc6d34: Ship `gbot` as one generated Agent Bundle CLI at the package root and add `gbot-install install|uninstall <cursor|codex|claude>` / `gbot-install doctor` for the bundled `grok-bot` MCP tools and `talk-to-grok-bot` skill; delete the nested `plugin/` project and the hand-written dispatcher. Breaking (pre-1.0): Node.js 22.19.0 or newer is required; options are command-local (`gbot send --history-dir DIR …`, no leading globals); `--json` is reserved anywhere before `--`, so put `--` before flag-like message text; `send` and every `codex` command write one JSON document to stdout with `exitCode` (failures keep `error`, `delivery`, `reason`, `mode` and exit 1), other commands print failures on stderr and exit 1; argument and schema errors exit 2; `--instructions` is gone (use `--description`) and `--notify`/`--hidden` take `on|off` only; `chat` records history rows as `event: "thread"`; the installed bundle is named `gbot` (uninstall an earlier source-built `grok-bot` plugin first). (#50)
+
+### Patch Changes
+
+- 4b3cd78: Make `gbot codex` dependable for automation and safe for agent relays: `codex status --json` reports `socketState`, a stable failure `mode` (`socket-absent`, `permission-denied`, `not-a-socket`, `connect-failed`, `handshake-failed`, `bad-response`, `windows-unsupported`), `schema.compatibility` separate from reachability, a bounded `codex --version` probe (`cliVersionProbe`), and `desktopAttached: "unknown"`; `codex list-threads` adds `--cursor`, bounds `--limit` to 1–200, rejects unknown arguments, validates the response shape, and strips terminal controls from every text field in JSON too. `codex send` and `send` accept `--correlation-id`, `--reply-to`, `--hop`, and `--envelope`, return receipts with `messageId` (sent as Codex's `clientUserMessageId`), `correlationId`, `replyTo`, `hop`, and `maxHops`, refuse relays at `GROK_BOT_MAX_HOPS` (default 4) with `reason: "hop-limit"`, honor the operator allowlist `GROK_BOT_CODEX_THREADS`, refuse `active` threads with `reason: "busy"` instead of steering a running turn (or, with `--when-busy queue` and `GROK_BOT_CODEX_EXPERIMENTAL=1`, hand them to Codex's experimental `thread/queue/add` and report `delivery: "queued"`; `codex queue <threadId>` lists that queue), and emit `reason`/`mode` in every `--json` send failure. Fixes #37, #38, #39.
+- bf64783: Add `gbot thread --after ID` for exclusive client-side filtering of the bounded gateway tail, including no-op cursors and explicit gap-reset snapshots.
+
+## 0.3.1
+
+### Patch Changes
+
+- HOLD-fix follow-up for the P1 bridge work: gateway reads count true bytes through a streaming reader that cancels on overflow; Codex transport uses an absolute handshake deadline, caps terminated headers and complete frames before decoding, guarantees socket destruction on close, and routes malformed RPC through failure handling; CLI `--json` failures emit structured errors with delivery and IDs; sends stay `unknown` without a confirmed receipt; MCP full reads add aggregate budgets with truncation metadata and a CLI continuation path.
+
+## 0.3.0
+
+### Minor Changes
+
+- 82badce: Add `gbot codex status`, `gbot codex list-threads [--limit N]`, and `gbot codex send <threadId> <message...>`: attach to the local Codex app-server daemon socket (`$CODEX_HOME/app-server-control/app-server-control.sock`) with a built-in WebSocket client, list threads, and start a turn with documented JSON-RPC (`thread/resume` + `turn/start`). Reports an absent socket (no daemon or ChatGPT Desktop private mode), unknown threads, threads owned by another client, and refuses server approval requests instead of approving them. Method names are pinned to Codex 0.154.0.
+
+### Patch Changes
+
+- 93cb28e: Parse global `gbot` flags only before the command so `gbot codex send` keeps `--json` / `--dir` inside the message; refuse native Windows for `gbot codex` with a clear error; strip terminal controls from thread listings; run unit tests through `scripts/run-unit-tests.mjs` so Windows and Node 18 work without shell globs.
+- ef6ce79: Send the gateway bearer only to `https` hosts on `*.cursor.sh`, `*.cursor.com`, or `*.cursorvm.com`, and the EnsureSandBox / Cursor access token only to `*.cursor.sh` / `*.cursor.com`; refuse cross-origin fetch redirects; redact Authorization (any scheme), Cookie, and named token fields from error output. `GROK_BOT_ALLOW_LOCAL_GATEWAY=1` admits loopback gateways and `GROK_BOT_ALLOW_ANY_GATEWAY=1` disables the host check; both warn once on stderr.
+- d59fa95: Add opt-in local JSONL thread history (`GROK_BOT_HISTORY=on`) with offline `gbot history` search.
+- a7415d7: P1 bridge follow-ups: preserve send receipts with rejected/accepted/unknown delivery states (Codex `CodexSendError` keeps thread/turn IDs, gateway `sendPrompt` returns `delivery` + `messageId` and marks post-write loss unknown); bound the Codex WebSocket transport (idempotent close settling pending requests, socket destroy on every failure, exact handshake validation, fragmentation/UTF-8/opcode handling, header/frame/message/buffer budgets); make `gbot_thread` bounded without losing replies (truncation metadata, `full` bounded full-read in tool and `--full` in CLI, safe string normalization, 1–200 limit consistency, gateway deadline and response-byte cap).
+- 9b034ce: Validate group membership in gateway mode before sending mutations: deduplicate member references, enforce one to six bot members, reject nested groups, and reject bots as group targets.
+- ab70a00: Strip C0/C1 controls (including CR, backspace, and BEL) from `gbot codex list-threads` text output, not only ESC sequences.
+- 93cb28e: Fix `gbot thread` so bot replies (`send-message` entries) show their text instead of empty lines, by sharing transcript parsing with the grok-bot plugin.
+- 3fe1287: Use the signed-in Grok Bot app session on Windows (`%APPDATA%\\Grok Bot`, DPAPI Safe Storage).
+
+## 0.2.3
+
+### Patch Changes
+
+- 5519136: Use the signed-in Grok Bot app session on Linux: read `~/.config/Grok Bot/gateway-descriptor.json` (honouring `XDG_CONFIG_HOME`), decrypt Chromium `v11` payloads with the Secret Service password via `secret-tool` and `v10` payloads with the basic-text key, and apply Linux's single PBKDF2 round instead of the macOS 1003.
+
+## 0.2.2
+
+### Patch Changes
+
+- ce452cd: Support version 2 Grok Bot gateway descriptors and report unusable app sessions clearly in `gbot doctor`.
+
+## 0.2.1
+
+### Patch Changes
+
+- 13f6858: Remove redundant group-member normalization branches.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9691ea3: Add complete bot and group profile creation and update fields, including instructions, titles, avatar shape and color, notifications, and sidebar visibility.

package/README.md

@@ -14,7 +14,7 @@ Manage [Grok Bot](https://cursor.com/help/grok-bot/plans) agents, groups, and me
 npm install --global grok-bot-cli
 ```
 
-Requires Node.js 18+ and the Grok Bot desktop app on macOS, Linux, or Windows. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`). On Windows the session lives under `%APPDATA%\\Grok Bot` and decrypts with the app's DPAPI-wrapped Safe Storage key.
+Requires Node.js 22.19.0+ and the Grok Bot desktop app on macOS, Linux, or Windows. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`). On Windows the session lives under `%APPDATA%\\Grok Bot` and decrypts with the app's DPAPI-wrapped Safe Storage key.
 
 ## Use
 
@@ -28,14 +28,25 @@ gbot groups update Launch --title "Launch room" --hidden off
 gbot send Researcher "Summarize the launch status."
 gbot send Launch "Share your updates."
 gbot thread Researcher
+gbot thread Researcher --after <last-entry-id> --json
 gbot groups delete Launch
 gbot bots delete Researcher
 gbot bots delete Writer
 ```
 
-`update` fields: `--name` `--description`/`--instructions` `--title` `--avatar-shape` `--avatar-color` `--notify` `--hidden`. `--description` is the UI Instructions field.
+`update` fields: `--name` `--description` `--title` `--avatar-shape` `--avatar-color` `--notify on|off` `--hidden on|off`. `--description` is the UI Instructions field.
+
+`gbot thread --after ID` filters the bounded tail locally and returns entries strictly
+after that opaque entry ID. Its JSON includes `cursor`, `entryCount`, and `gapReset`.
+An unchanged poll has `entryCount: 0`; an unknown or expired ID returns one bounded
+snapshot with `gapReset: true`. The gateway request remains limit-only.
 
 Run `gbot --help` for every command.
+Options are command-local (for example, `gbot send --history-dir DIR ...`);
+the former leading-global form is no longer accepted. `--json` prints the
+canonical JSON result; `send` and the `codex` commands also report failures as
+a JSON document on stdout with `exitCode` (see below), every other command
+prints the failure message on stderr and exits 1.
 
 ## Gateway URL policy
 
@@ -62,42 +73,63 @@ gbot codex send <threadId> "Grok here: the build is green, please continue."
 
 `send` resumes the thread, starts a turn with your text, prints the turn id, and returns; Codex keeps working after `gbot` disconnects. Every command accepts `--json`.
 
-**Which Codex you reach.** `gbot` connects to `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`) with a built-in WebSocket client. The daemon must be started by `codex app-server daemon start`. `list-threads` shows the threads recorded under `CODEX_HOME` (CLI, TUI, VS Code); `send` works on any of them that no other client currently holds open. Method and parameter names are pinned to the Codex release recorded in `src/codex-bridge.js` (`codex app-server generate-json-schema`); `status` prints the daemon and CLI versions so a stale daemon is visible, and `codex app-server daemon restart` picks up the installed CLI. Native Windows is not supported yet (AF_UNIX control socket); use WSL, Linux, or macOS.
+**Which Codex you reach.** `gbot` connects to `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`) with a built-in WebSocket client. The daemon must be started by `codex app-server daemon start`. `list-threads` shows the threads recorded under `CODEX_HOME` (CLI, TUI, VS Code); `send` works on any of them that no other client currently holds open. Method and parameter names are pinned to the Codex release recorded in `src/core/codex-bridge.js` (`codex app-server generate-json-schema`); `status` prints the daemon and CLI versions so a stale daemon is visible, and `codex app-server daemon restart` picks up the installed CLI. Native Windows is not supported yet (AF_UNIX control socket); use WSL, Linux, or macOS.
 
 **ChatGPT Desktop limitation.** Desktop runs its own private stdio app-server and does not publish the shared control socket, so external clients cannot reach live Desktop tasks. When the socket is absent, `gbot codex status` exits 1 and says so, naming the upstream issues: [openai/codex#41014](https://github.com/openai/codex/issues/41014) and [openai/codex#41112](https://github.com/openai/codex/issues/41112). `gbot` never reads Desktop's temporary `CODEX_APP_TOOLS_PIPE_PATH` sockets under `/tmp/codex-browser-use/`; that channel is private to Desktop.
 
-**Failure modes.**
+**Status contract (`gbot codex status --json`).** `reachable` is endpoint reachability only. `socketState` is `socket`, `absent`, `permission-denied`, or `not-a-socket`; `mode` is `daemon` for a usable daemon, otherwise the failure: `socket-absent`, `permission-denied` (the file or the connect refused this user), `not-a-socket`, `connect-failed` (socket present, nothing completed the WebSocket upgrade), `handshake-failed` (upgrade or `initialize` failed), `windows-unsupported`, or `bad-response` (reachable, but `initialize` returned something off-schema — `reachable` stays `true`). `schema.compatibility` is `exact` when the daemon reports the pinned version, `unverified` when it differs (methods usually survive upgrades, but the shapes are not re-checked), or `unknown`. `cliVersionProbe` reports whether `codex --version` answered (`ok`, `missing`, `timeout` after 3 s, `error`). Whether ChatGPT Desktop owns a thread is not observable from the socket, so `desktopAttached` is always `"unknown"`. The document is always written to stdout and includes `exitCode`; it is `0` only for a usable daemon.
+
+**Thread discovery.** `list-threads --limit N` (1–200) pages with the opaque `--cursor` from the previous `nextCursor`; JSON keeps the cursor verbatim, text output prints a sanitized `more: --cursor …` hint. Text fields are stripped of terminal control sequences in both outputs (single-line fields also lose line breaks; `preview` keeps its newlines; a structured `source` such as `{ "custom": … }` passes through unchanged), `status` is one of `notLoaded | idle | active | systemError | unknown`, and non-numeric `updatedAt` becomes `null`. Unknown arguments are rejected before the socket is touched; a response that does not match the pinned schema (including an entry without a string `id`) fails with `reason: "bad-response"`.
+
+**Routes, attribution, and loops.** `gbot codex send` runs on the machine that owns `CODEX_HOME`, as the user who owns the socket, with that user's Codex credentials; the socket path comes only from `CODEX_HOME`, never from the message or an agent-supplied argument. A cloud-hosted Grok Bot cannot reach a desktop socket directly — run `gbot` locally (for example from a Codex skill or an agent on that machine). `GROK_BOT_CODEX_THREADS=id,id` lets the operator pin `send` to approved threads (`reason: "route-not-allowed"` otherwise). Every send gets a delivery envelope: `messageId` (also sent as Codex's native `clientUserMessageId`), `correlationId` (defaults to the message id), optional `replyTo`, and `hop`. A reply passes the original correlation id and `hop` + 1:
+
+```sh
+gbot codex send <threadId> "Grok here: build is green"                  # receipt: messageId M, correlationId M, hop 0
+gbot codex send --correlation-id M --reply-to M --hop 1 <threadId> "ack" # the answer, one hop later
+```
+
+Sends at `hop >= GROK_BOT_MAX_HOPS` (default 4) are refused with `reason: "hop-limit"` before anything reaches the daemon, so two agents cannot acknowledge each other forever; `gbot` never auto-acknowledges. `--envelope` (implied by any envelope flag) prepends a one-line `[gbot msg=… corr=… reply-to=… hop=… from=user@host]` header so the receiving agent can quote the ids back. That header is caller-authored provenance for the reader, not authentication: the daemon authenticates the local user through the socket, nothing else. Private ChatGPT Desktop pipes and arbitrary ChatGPT chats stay out of scope; only Codex threads on a reachable app-server daemon are routes.
+
+**Busy threads.** `send` reads the thread status on resume. Only `idle` and `notLoaded` threads start a turn. An `active` thread (a turn in progress, or waiting on approval / user input) is refused with `reason: "busy"`: in app-server 0.154.0 a `turn/start` on an active thread steers that turn rather than queueing behind it, and `gbot` never steers or interrupts work a human may be doing. Either wait for `list-threads` to show `idle` and resend, or pass `--when-busy queue` to hand the message to the daemon's own queue through Codex's experimental `thread/queue/add` — that needs `GROK_BOT_CODEX_EXPERIMENTAL=1`, returns `delivery: "queued"` with `queuedSubmissionId`, and `gbot codex queue <threadId>` shows what is still waiting. `systemError` threads are refused with `reason: "thread-error"`, statuses this version does not know with `reason: "unknown-status"`. Receipts distinguish `delivery: "accepted"` (turn started; `turnId`, `turnStatus`), `"queued"`, `"rejected"` (nothing was sent; see `reason`), and `"unknown"` (the request left but no acknowledgment came back — look for `messageId` in the thread or queue before resending). The decision record, with the schema evidence and a live probe of the queue API, is in [`docs/codex-busy-threads.md`](docs/codex-busy-threads.md).
 
-- Socket absent: no daemon, or Desktop-private mode. Start the daemon or wait for the upstream fixes.
-- Unknown thread: `send` fails with "Unknown Codex thread"; use `list-threads`.
-- Thread open elsewhere: a thread with an active writer (VS Code, TUI) fails with "open in another client"; close it there first.
-- Approvals: `gbot` never approves commands or file changes on your behalf. If Codex asks while `gbot` is still connected, `send` refuses the request, exits 1, and tells you the turn id. `send` disconnects as soon as the turn starts, so later approval requests stay with the daemon for a Codex client to answer; for unattended sends set `approval_policy = "never"` in the daemon's `config.toml`.
+**Failure modes.** Every `send` and `codex` outcome under `--json` is one document on stdout with `exitCode`; failures include `{ error, delivery, reason, messageId, correlationId, hop, exitCode: 1, … }` and the process exits 1. Framework argument/schema errors remain on stderr and exit 2. `--json` is reserved anywhere before `--`; put `--` before flag-like message text. `reason` values are stable:
+
+- `socket-absent` / `permission-denied` / `not-a-socket` / `connect-failed` / `handshake-failed` / `windows-unsupported`: the route is unavailable. Start the daemon, fix the socket, or wait for the upstream Desktop fixes.
+- `unknown-thread`: use `list-threads`.
+- `external-owner`: a thread with an active writer (VS Code, TUI) is open in another client; close it there first.
+- `busy` / `thread-error` / `unknown-status`: see above.
+- `route-not-allowed` / `hop-limit` / `experimental-disabled`: refused by operator policy, the relay bound, or the experimental-API gate.
+- `unsupported`: the daemon does not offer the (experimental) method `--when-busy queue` needs.
+- `approval-refused` (`delivery: "accepted"`): `gbot` never approves commands or file changes on your behalf. If Codex asks while `gbot` is still connected, `send` refuses the request, exits 1, and tells you the turn id. `send` disconnects as soon as the turn starts, so later approval requests stay with the daemon for a Codex client to answer; for unattended sends set `approval_policy = "never"` in the daemon's `config.toml`.
+- `transport` / `bad-response` (`delivery: "unknown"`): the connection dropped or the daemon answered off-schema after the request left.
 
 ## Talking to Grok Bot from Codex
 
-`plugin/` is an [Agent Bundle](https://scriptedalchemy.github.io/agent-bundle/) plugin
+The npm package is also an [Agent Bundle](https://scriptedalchemy.github.io/agent-bundle/) plugin
 that gives Codex, Claude Code, and Cursor two MCP tools on a `grok-bot` server,
 `gbot_send` and `gbot_thread`, plus a `talk-to-grok-bot` skill that tells the agent
 when to ping a bot and how to word the message. The tools bundle this repository's
 gateway client, so the installed plugin does not need `gbot` on `PATH`.
 
-The plugin is not part of the npm package. From a clone of this repository, build
-the artifact once, then install it into each host you use:
+Install the bundled host projections from the same npm package:
 
 ```sh
-git clone https://github.com/ScriptedAlchemy/grok-bot-cli.git
-cd grok-bot-cli/plugin
-npm install
-npm run build
-npx agent-bundle install codex --from artifact
-npx agent-bundle install claude --from artifact
-npx agent-bundle install cursor --from artifact
-npx agent-bundle doctor --from artifact
+gbot-install install codex
+gbot-install install claude
+gbot-install install cursor
+gbot-install doctor
 ```
 
-Add `--replace` to an install command to overwrite an earlier copy. `npm run check`
-runs the plugin gates: source validation, build, artifact validation, typecheck, and
-the route-unit tests, which drive both tools against a loopback fake gateway.
+Add `--replace` to an install command to overwrite an earlier copy. The bundle is
+registered as `gbot`; if you installed the pre-0.4 `grok-bot` plugin from a source
+checkout, uninstall it first so the two do not both register the `grok-bot` server.
+
+`gbot_thread` returns a small receipt by default: deterministic `summary`, opaque
+`cursor`, `entryCount`, and `gapReset`.
+Pass the cursor back as `after` for an exclusive client-side delta. Pass `full:true`
+only when bounded entry bodies are needed in structured content; `Agent.Text` remains
+the short summary. Unknown cursors set `gapReset: true`; repeat that call with
+`full:true` to inspect the bounded reset snapshot.
 
 Auth resolves exactly as for `gbot`: `GROK_BOT_GATEWAY_URL` + `GROK_BOT_GATEWAY_TOKEN`,
 then the Grok Bot app session, then `CURSOR_ACCESS_TOKEN`. The MCP server therefore

package/dist/.agents/plugins/marketplace.json

@@ -0,0 +1 @@
+{"interface":{"displayName":"gbot"},"name":"gbot-marketplace","plugins":[{"category":"Productivity","name":"gbot","policy":{"authentication":"ON_INSTALL","installation":"AVAILABLE"},"source":{"path":"./","source":"local"}}]}

package/dist/.claude-plugin/marketplace.json

@@ -0,0 +1 @@
+{"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"author":{"name":"Zack Jackson","url":"https://github.com/ScriptedAlchemy"},"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","homepage":"https://github.com/ScriptedAlchemy/grok-bot-cli#readme","keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","source":"./","version":"0.4.0"}]}

package/dist/.claude-plugin/plugin.json

@@ -0,0 +1 @@
+{"author":{"name":"gbot"},"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","name":"gbot","version":"0.4.0"}

package/dist/.codex-plugin/mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"grok-bot":{"args":["./mcp/mcp-grok-bot-b8c2461e.mjs"],"command":"node","cwd":"./","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"./"},"type":"stdio"}}}

package/dist/.codex-plugin/plugin.json

@@ -0,0 +1 @@
+{"author":{"name":"Zack Jackson","url":"https://github.com/ScriptedAlchemy"},"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","homepage":"https://github.com/ScriptedAlchemy/grok-bot-cli#readme","interface":{"capabilities":["mcp","skills"],"category":"Productivity","defaultPrompt":["Help me use gbot."],"developerName":"gbot","displayName":"gbot","longDescription":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","shortDescription":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor."},"keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","mcpServers":"./.codex-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","skills":"./skills/","version":"0.4.0"}

package/dist/.cursor-plugin/marketplace.json

@@ -0,0 +1 @@
+{"name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","name":"gbot","source":"./"}]}

package/dist/.cursor-plugin/mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"grok-bot":{"args":["${CURSOR_PLUGIN_ROOT}/mcp/mcp-grok-bot-b8c2461e.mjs"],"command":"node","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CURSOR_PLUGIN_ROOT}"}}}}

package/dist/.cursor-plugin/plugin.json

@@ -0,0 +1 @@
+{"author":{"name":"Zack Jackson"},"description":"Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.","displayName":"gbot","homepage":"https://github.com/ScriptedAlchemy/grok-bot-cli#readme","keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","mcpServers":"./.cursor-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","skills":"./skills/","version":"0.4.0"}

package/dist/.mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"grok-bot":{"args":["${CLAUDE_PLUGIN_ROOT}/mcp/mcp-grok-bot-b8c2461e.mjs"],"command":"node","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CLAUDE_PLUGIN_ROOT}"},"type":"stdio"}}}

package/dist/INSTALL.md

@@ -0,0 +1,269 @@
+# Install gbot
+
+Message Grok Bot bots and groups and read their threads from Codex, Claude Code, and Cursor.
+
+Version: `0.4.0`
+
+Run these commands from this bundle directory. The bundle is self-contained: every command below is
+a host command or the bundled installer, and nothing requires the `agent-bundle` CLI. Where that CLI is
+mentioned it is optional and automates the same steps.
+
+## Claude Code
+
+Claude Code installs this bundle through its local marketplace contract:
+
+```sh
+claude plugin marketplace add ./
+claude plugin install gbot@gbot-marketplace --scope user
+```
+
+Replace `user` with `project` or `local` when that Claude scope is intended.
+
+### Reinstall after a same-version rebuild
+
+`claude plugin update` is version-gated: when the bundle content changed but `version` did not,
+it reports the plugin is already at the latest version and leaves the cached copy stale.
+Uninstall and install again instead (`--keep-data` preserves the plugin's persistent data):
+
+```sh
+claude plugin uninstall gbot@gbot-marketplace --scope user --keep-data
+claude plugin marketplace add ./
+claude plugin install gbot@gbot-marketplace --scope user
+```
+
+With the optional `agent-bundle` CLI, `agent-bundle install claude --from ./` runs this sequence
+automatically when the installed copy has the same version but a different content hash; `--replace`
+(alias `--force`) forces it.
+
+### Uninstall
+
+```sh
+claude plugin uninstall gbot@gbot-marketplace --scope user --keep-data
+```
+
+Match the scope the plugin was installed with (`user`, `project`, or `local`). `--keep-data` keeps durable
+runtime state (Claude orphans the cached copy, `state/` included, for its ~14-day grace period); omit it to
+remove `~/.claude/plugins/data/<id>/` immediately.
+
+The marketplace `gbot-marketplace` stays registered. Remove it only when nothing else installs from it:
+`plugin marketplace remove` applies to every scope and every project, and `claude plugin list` shows only
+the current project, so also check `~/.claude/plugins/installed_plugins.json` (under `$CLAUDE_CONFIG_DIR`
+when set), where Claude records every scope of every install. The optional `agent-bundle uninstall claude`
+below performs that inventory before it removes anything.
+
+```sh
+claude plugin marketplace remove gbot-marketplace
+```
+
+With the optional `agent-bundle` CLI, `agent-bundle uninstall claude --from ./ --plan` prints exactly what
+would be removed and `agent-bundle uninstall claude --from ./` reverses the recorded registrations.
+`agent-bundle install claude` records a receipt at `~/.claude/agent-bundle/receipts/gbot.gbot-marketplace.user.json`
+(or under `$CLAUDE_CONFIG_DIR`; `user` is the install scope, pass `--scope project` or `--scope local` to match
+a scoped install), and `uninstall` consumes it, running the two commands above in order and retaining the
+marketplace while any other plugin, scope, or project still installs from it. Durable runtime state
+is kept by default; `--purge-data --confirm-purge` removes `state/` and `~/.claude/plugins/data/<id>/`
+immediately. A missing receipt or a cached copy that no longer matches it is refused unless `--force`; a
+second run is a `not-installed` no-op.
+
+## Codex
+
+Codex installs this bundle from its local marketplace snapshot:
+
+```sh
+codex plugin marketplace add ./
+codex plugin add gbot@gbot-marketplace
+```
+
+### Reinstall after a same-version rebuild
+
+`codex plugin add` re-copies the marketplace snapshot but never deletes files a rebuild removed.
+Remove and add again for a clean same-version copy:
+
+```sh
+codex plugin remove gbot@gbot-marketplace
+codex plugin marketplace add ./
+codex plugin add gbot@gbot-marketplace
+```
+
+With the optional `agent-bundle` CLI, `agent-bundle install codex --from ./` runs this sequence
+automatically when the installed copy has the same version but a different content hash; `--replace`
+(alias `--force`) forces it.
+
+### Uninstall
+
+```sh
+codex plugin remove gbot@gbot-marketplace
+```
+
+Codex 0.147.0 deletes the cached plugin tree, `state/` included, on `plugin remove` and has no keep-data
+option.
+
+The marketplace `gbot-marketplace` stays registered. Remove it only when nothing else installs from it:
+`codex plugin list` shows every other plugin from it.
+
+```sh
+codex plugin marketplace remove gbot-marketplace
+```
+
+With the optional `agent-bundle` CLI, `agent-bundle uninstall codex --from ./ --plan` prints exactly what
+would be removed and `agent-bundle uninstall codex --from ./` reverses the recorded registrations.
+`agent-bundle install codex` records a receipt at `~/.codex/agent-bundle/receipts/gbot.gbot-marketplace.user.json` (or
+under `$CODEX_HOME`), and `uninstall` consumes it, running the two commands above in order. `--keep-data`
+cannot preserve durable state on Codex; the result says so (`unavailable`). A missing receipt or a cached
+copy that no longer matches it is refused unless `--force`; a second run is a `not-installed` no-op.
+
+## Cursor
+
+Cursor has no non-interactive plugin install command. The bundled installer supports two delivery modes.
+
+### Local plugin (default)
+
+```sh
+node ./install.mjs
+```
+
+It safe-copies the bundle to `~/.cursor/plugins/local/gbot`. Restart Cursor or run
+`Developer: Reload Window` after installation. Cursor loads rules, skills, MCP servers, and the
+manifest-declared `hooks/hooks.json` from that directory; plugin hooks run from the plugin root with
+`${CURSOR_PLUGIN_ROOT}` substituted and need no `~/.cursor/hooks.json` entry.
+
+### Reinstall after a same-version rebuild
+
+The installer writes an install receipt (`.agent-bundle-install.json`: plugin, version, content hash,
+owned files) beside the plugin manifest. Re-running `node ./install.mjs` on an identical artifact
+is a no-op that says so. When the installed copy has the same version but different content, the
+installer replaces its owned files in place and leaves runtime state (`state/`) untouched:
+
+```sh
+node ./install.mjs            # same-version content drift of a receipt-managed copy is replaced
+node ./install.mjs --replace  # also replace a different installed version, or adopt a pre-receipt copy
+```
+
+`--force` is an alias for `--replace`. A directory that is not an agent-bundle install of this
+plugin is always refused with an installed-versus-artifact content-hash comparison; remove it
+manually. The optional `agent-bundle` CLI applies the same policy through
+`agent-bundle install cursor --from ./ [--replace]`.
+
+### Uninstall
+
+```sh
+node ./install.mjs --uninstall --plan                        # print exactly what would be removed
+node ./install.mjs --uninstall                               # remove the receipt-owned files; keep state/
+node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove durable runtime state
+node ./install.mjs --uninstall --mode marketplace            # remove a staged marketplace repository
+```
+
+Uninstall removes exactly what the receipt owns: the listed files, the directories the installer
+created (including `~/.cursor/plugins/local` when the installer made it), and nothing else. Durable
+runtime state under `state/` (state kernel, notices journal) — and, for an Agent Plugins pack with a stdio
+server, the `~/.cursor/agent-bundle/plugin-data/<name>` directory the receipt records as `PLUGIN_DATA` — is kept
+unless `--purge-data --confirm-purge` is passed (a kept data directory leaves a remnant receipt behind so a later
+purge still finds it; an empty one is pruned); unowned files are left in place and listed. A supported older
+receipt with no recorded state location retains the current environment's default as unproven; a keep-data run
+cannot turn that observation into later purge authority. A directory without a receipt is refused unless
+`--force` (which removes a pre-receipt legacy copy by its inventory); owned content that no longer matches
+the receipt is refused unless `--force`; a directory that is not this plugin's install is always refused.
+A second run is a `Not installed` no-op. With the optional `agent-bundle` CLI,
+`agent-bundle uninstall cursor --from ./ [--mode marketplace]` applies the same policy, and
+`agent-bundle doctor --from ./` shows the lifecycle stage (placed, registered, enabled, active) with
+unobservable stages typed `unavailable`.
+
+### Marketplace plugin
+
+```sh
+node ./install.mjs --mode marketplace
+```
+
+It stages a committed Git repository at `~/.cursor/agent-bundle/marketplaces/gbot` whose
+`.cursor-plugin/marketplace.json` lists this plugin, then prints the exact Cursor step: Customize -> Plugins ->
+"Add Plugins from Local Repository" -> select that directory -> Install. Cursor then shows the plugin as a
+marketplace install (not "local") and manages it from Customize. `git` must be on PATH. Verify in Cursor:
+Customize -> Plugins lists the plugin, and its files appear under `~/.cursor/plugins/cache`. The optional
+`agent-bundle` CLI performs the same check with `agent-bundle doctor --host cursor`.
+
+## Portable Agent Plugin
+
+Portable is a distribution profile, not a host runtime with one universal install location.
+This bundle follows the Agent Plugins open standard (Agent Plugins 1.0.0, https://agent-plugins.org).
+Cursor loads this format natively from `~/.cursor/plugins/local/<name>`; restart Cursor or run
+`Developer: Reload Window` after copying it. The bundled installer provides the Cursor local copy:
+
+```sh
+node ./install.mjs
+```
+
+### Other recorded clients
+
+Each line below is pinned to that client's own documentation on the date shown, and names only the
+paths this build actually wrote. Recognizing a document and running what it configures are separate:
+`mcp` records that the client reads the emitted `mcp.json` as MCP configuration, while `placeholders`
+records that it expands the reserved `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` and provides them to the
+process it spawns. A client can do the first without the second, and then a plugin-relative server
+is configured but not runnable there.
+
+- **Antigravity** (docs retrieved 2026-09-06; no product or CLI version is published on any page) loads nothing from this bundle as published. Not loaded: manifest, skills, mcp, placeholders, hooks.
+- **Cascade (Devin Desktop)** (docs.devin.ai/desktop retrieved 2026-09-06; Windsurf renamed to Devin Desktop, Cascade documented as the legacy agent beside the Devin Local agent) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `cp -R skills/<skill> .agents/skills/<skill>`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: the emitted package root is not a Cascade discovery root; each skill directory is copied into .windsurf/skills/, ~/.codeium/windsurf/skills/, or .agents/skills/ before Cascade sees it, and the copy is what loads.
+- **Cline** (@cline/cli 0.0.13 exercised 2026-09-06; docs.cline.bot retrieved 2026-09-06 (@cline/sdk 0.0.82)) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `cp -R skills/<skill> ~/.cline/skills/<skill>`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: the skill tree must be copied into one of Cline's own roots; the emitted package is not a Cline install unit, and no CLI verb in @cline/cli 0.0.13 performs the copy.
+- **CodeWhale** (Hmbown/CodeWhale main 19d34a5fb6c07b34e0b7234beb74a1cf1969efb4, docs retrieved 2026-09-06 (native Agent Plugins v1.0.0 support since v0.9.4)) loads this bundle as one plugin. Reads: `mcp.json`, `plugin.json`, `skills`. Install: `/plugin install ./<plugin directory>`. Not loaded: placeholders, hooks.
+  - Partial `mcp`: 2026-09-06: CodeWhale narrows the standard at the plugin boundary. Its env rule — "Local stdio environment entries must use exact ${SOURCE_ENV} references" — rejects an emitted env value that is anything other than one whole variable reference. A remote server emitted into mcp.json is narrower still: the URL must be HTTPS (or explicit loopback HTTP) with no user information, query, or fragment, a literal header is rejected in favor of CodeWhale's own env_headers or bearer_token_env_var keys, redirects must stay on the reviewed origin, and the bundle must declare exactly the normalized endpoint host set in capabilities.network_hosts. That declaration rides in extensions["net.codewhale"], which this projection writes only when the author authors portable.extensions; a remote server emitted without it is a validation error, and "an active bundle must be … free of validation errors", so the whole bundle stays inactive there until the author declares the matching host set.
+- **GitHub Copilot CLI** (@github/copilot 1.0.83, installed and exercised 2026-09-06) loads this bundle as one plugin. Reads: `plugin.json`, `skills`. Install: `copilot plugin install <plugin directory>`. Not loaded: hooks. This build also writes `.mcp.json`, which it uses for mcp instead. A root that also carries `.plugin/plugin.json` uses it for manifest and still reads the rest.
+- **Devin CLI** (Agent Plugins 1.0.0; docs retrieved 2026-09-06, plugins documented as closed beta) loads this bundle as one plugin, but this build also writes `.claude-plugin/plugin.json`, which it reads as the plugin instead.
+- **Gemini CLI** (@google/gemini-cli 0.58.0, installed and exercised 2026-09-06) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `gemini skills install <plugin directory>/skills/<skill>`. Not loaded: manifest, mcp, placeholders, hooks.
+- **Grok Build** (xai-org/grok-build main 72a61251fcffb464bcc687aeb5a998e5a98ec0c9, docs retrieved 2026-09-06) loads the components it recognizes without reading the manifest. Reads: `skills`. Install from a marketplace (no local-directory install is verified for this artifact): `grok plugin install <marketplace plugin name> --trust`. Not loaded: manifest, mcp, placeholders, hooks.
+- **Hermes Agent** (hermes-agent.nousresearch.com developer guide retrieved 2026-09-06; no version is printed on the page) loads this bundle as one plugin. Reads: `mcp.json`, `plugin.json`, `skills`. Install from a Git repository (no local-directory install is verified for this artifact): `hermes plugins install <owner>/<repository> --no-enable`. Not loaded: hooks.
+  - Partial `manifest`: 2026-09-06: the validation rule set is not published: the page never states that the manifest root is treated as closed or what happens to an unknown root key.
+  - Partial `placeholders`: 2026-09-06: the expansion sites are unpublished — the page does not say whether ${PLUGIN_ROOT} and ${PLUGIN_DATA} are expanded in args, env values, and cwd as §9.1 requires, only that the variables are provided.
+- **JetBrains Junie** (junie.jetbrains.com/docs retrieved 2026-09-06, agent-skills page dated 01 September 2026; no CLI version is published on the page) loads the components it recognizes without reading the manifest. Reads: `skills`. Register: `junie --skill-location <plugin directory>/skills`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: the emitted skills/ root is not a default location, so it loads only once registered with --skill-location or the skill-locations config field, and "if a project-level and a user-level skills have the same name, the user-level skill will be skipped".
+- **Kiro (Powers)** (kiro.dev/docs/powers pages updated September 2, 2026 and August 4, 2026, retrieved 2026-09-06) loads this bundle as one plugin. Reads: `mcp.json`, `plugin.json`, `skills`. Install: `Powers panel -> Add Custom Power -> Import power from a folder -> select <plugin directory> -> Install`. Not loaded: placeholders, hooks.
+  - Partial `manifest`: 2026-09-06: Kiro's "Required fields" table additionally requires version, description, author, and keywords, where the canonical schema requires only $schema and name — so a bundle that declares no portable author or keywords metadata does not meet Kiro's tightened manifest, and Kiro publishes no validation-error behavior to say what happens then.
+  - Partial `mcp`: 2026-09-06: only stdio is documented for a power's mcp.json; no Kiro page states that a streamable-http server in that file is read, so an emitted remote server is unproven there.
+- **OpenClaw** (Agent Plugins 1.0.0; docs retrieved 2026-09-06) loads this bundle as one plugin, but this build also writes `.claude-plugin/plugin.json`, which it reads as the plugin instead.
+- **OpenCode** (opencode-ai 1.18.29 exercised 2026-09-06; opencode.ai/docs retrieved 2026-09-06) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `cp -R skills/<skill> .agents/skills/<skill>`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: the skill tree must be copied into one of OpenCode's own roots; the emitted package as a whole is not an OpenCode install unit, and skill names must be unique across all roots ("Ensure skill names are unique across all locations").
+- **Pi** (@mariozechner/pi-coding-agent 0.73.1 installed from npm 2026-09-07; packaged docs/skills.md and docs/packages.md read from that release) loads the components it recognizes without reading the manifest. Reads: `skills`. Register: `pi --skill <plugin directory>/skills`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-07: the emitted skills/ root is not one of the scanned default roots, so it loads only when it is named with --skill or added to the `skills` settings array; discovery inside it is recursive once named.
+- **Qoder CLI** (docs retrieved 2026-09-06; no CLI version is published on any page) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `qoder plugins install <plugin directory> --scope user`. Not loaded: manifest, placeholders, hooks. This build also writes `.mcp.json`, which it uses for mcp instead.
+- **Swival** (docs retrieved 2026-09-06; no product version is published on the documentation pages) loads the components it recognizes without reading the manifest. Reads: `skills`. Register: `swival --skills-dir <plugin directory>/skills "<task>"`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: the emitted skills/ root is not a default location, so it loads only once registered with --skills-dir or the swival.toml skills_dir field, and it loses by name to the default roots: "If the same skill name exists in multiple locations, the first one in the precedence order wins", with .swival/skills/ and .agents/skills/ ahead of --skills-dir paths. A registered tree outside the project resolves as external, which Swival adds "as read-only roots".
+- **VS Code (Copilot agent plugins)** (code.visualstudio.com/docs/agent-customization/agent-plugins, page footer 9/2/2026, retrieved 2026-09-06) loads this bundle as one plugin. Reads: `mcp.json`, `plugin.json`, `skills`. Register: `"chat.pluginLocations": { "<plugin directory>": true }`. Not loaded: placeholders, hooks.
+- **Zed Agent** (zed.dev/docs retrieved 2026-09-06; no page publishes a version or last-updated date) loads the components it recognizes without reading the manifest. Reads: `skills`. Install: `cp -R skills/<skill> ~/.agents/skills/<skill>`. Not loaded: manifest, mcp, placeholders, hooks.
+  - Partial `skills`: 2026-09-06: only the skill folders load, one copy at a time, and the catalog is capped — "50KB catalog budget… Skills that don't fit are dropped from the catalog with a warning in the UI" — so a large emitted skill set is not guaranteed to be wholly visible.
+
+### Cursor placeholder expansion
+
+Cursor 3.18.25 spawns the stdio servers of an Agent Plugins package without expanding
+`${PLUGIN_ROOT}` / `${PLUGIN_DATA}` in `args`, `env` values, or `cwd`, without providing the
+reserved `PLUGIN_ROOT` / `PLUGIN_DATA` variables (spec §9.1), with an omitted `cwd` defaulting to
+the home directory, and with plugin-relative `./` commands resolved against the workspace folder
+(spec §7.2.1). The installer therefore rewrites `mcp.json` in the Cursor copy only: the plugin root
+becomes `~/.cursor/plugins/local/<name>`, the data directory `~/.cursor/agent-bundle/plugin-data/<name>`
+(created by the installer), an omitted `cwd` becomes the plugin root, `./` commands resolve against
+it, and every stdio server gains `PLUGIN_ROOT` / `PLUGIN_DATA` in its environment. The bundle itself
+stays spec-conformant; the pre-expansion document is kept in `.agent-bundle-install.json` (`cursorExpansion`),
+and the optional `agent-bundle doctor --host cursor` verifies the expanded paths (`AB7326`). Nothing is changed for
+other clients; the recorded clients above name which of them expand the placeholders themselves.
+
+### Reinstall after a same-version rebuild
+
+The installer records an install receipt (`.agent-bundle-install.json`) and replaces its owned files in
+place when the same version was rebuilt with different content; runtime state (`state/`) is never
+touched. Pass `--replace` (alias `--force`) to replace a different installed version or to adopt a
+copy installed before receipts existed. Foreign directories are refused with a content-hash
+comparison. For a client that manages its own copy, remove and re-add the plugin through that client
+when only content changed at the same version.
+
+### Uninstall
+
+```sh
+node ./install.mjs --uninstall --plan                        # print exactly what would be removed
+node ./install.mjs --uninstall                               # remove the receipt-owned files; keep state/
+node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove durable runtime state
+```
+
+Uninstall removes exactly what the receipt owns (files, installer-created directories) and keeps
+durable runtime state under `state/` (and the recorded `PLUGIN_DATA` directory of an Agent Plugins pack)
+unless `--purge-data --confirm-purge` is passed. A missing
+receipt or modified owned content is refused unless `--force`; foreign directories are always refused.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScriptedAlchemy
+
+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.