grok-bot-cli 0.9.0 → 0.10.1

package/dist/skills/talk-to-grok-bot/SKILL.md

@@ -1,17 +1,34 @@
 ---
 name: talk-to-grok-bot
-description: Send or read Grok Bot threads via gbot_send/gbot_thread and Codex daemon threads via codex_send/codex_threads. Use when handing off to a named bot/group or posting a status note agents watch — not for work you can finish yourself.
+description: Message Grok Bot, Codex threads, or opted-in local Claude Code channels. Use when handing off to a named bot/group or posting a status note agents watch — not for work you can finish yourself.
 ---
 # Talk to Grok Bot
 
-MCP tools on the `grok-bot` server use the same gateway as the `gbot` CLI.
+The `grok-bot` MCP server and `gbot` CLI share Grok gateway access. Codex and
+Claude tools use **local sockets only** on the user's registered machines.
+
+## MCP instructions (Codex / Claude)
+
+gbot connects only to a local Unix socket
+(`$CODEX_HOME/app-server-control/app-server-control.sock`, or
+`CODEX_APP_SERVER_SOCK`). There is **no remote transport**.
+
+- Codex app-server threads and opted-in Claude Code channels live on the user's
+  registered computers (Linux desktop, Mac, …) — **never** on the Grok Bot agent
+  box (`HOME=/home/box`, no Codex install).
+- When this MCP server is running on the box, **do not** call `codex_*` or
+  `claude_send`. Run the `gbot` CLI on the user's machine through **Grok Bot Shell
+  with a machineId** (the host's machine-targeted shell).
+- On that machine, provide the socket with `codex app-server daemon start` (or
+  bootstrap). Auth stays with each machine's native Codex or Claude login.
 
 ## When to load this
 
 - The repo or task names a bot as owner, or you need a decision only that thread holds.
 - You want a short status note in a shared group other agents watch.
 
-Do not ping a bot for work you can finish yourself. Replies are asynchronous — never block a turn waiting.
+Do not ping a bot for work you can finish yourself. Grok replies are asynchronous;
+continue useful work instead of waiting or polling.
 
 ## How
 
@@ -27,42 +44,17 @@ Do not ping a bot for work you can finish yourself. Replies are asynchronous —
    Read `gbot_thread` later, using `after` for a known cursor and `full: true` only
    when entry bodies are needed. `replyMode: manual` explicitly requests this flow.
 
-Automatic routes start a durable background worker that survives the calling tool.
-Use `gbot_bridge_status` to distinguish delivery from execution and return delivery,
-and to inspect gaps, paused routes and pending interactions. Do not resend unknown
-submissions under a new identity. A provided `requestId` safely replays identical
-tracked input; `controlRequestId` is returned independently of the gateway request ID.
-`gbot_bridge_stop` stops a `bindingId`; `worker: true` explicitly stops the process.
-Neither deletes receipts nor interrupts a Codex turn. No login service is installed;
-if the process dies, the next tracked send/start resumes saved routes.
-
-`gbot_codex_respond` is only for an explicit operator response to a current scoped
-interaction. Copy the advertised interactionId, generation, threadId, turnId and
-bindingId/exchangeId. Use one-time `decision: accept|decline|cancel`, or `answersJson`
-with exact question IDs mapped to `{"answers":["answer"]}`. Never auto-approve,
-change session permissions, or respond to an unsupported interaction; use its owning UI.
-
-Bot replies are `send-message` entries; yours are `message` with `role: user`.
-
-Grok-origin approvals are separate from Codex interactions. `gbot_grok_approvals`
-(CLI: `gbot approvals list TARGET`) lists pending auto-review and local-tool cards in
-the latest 200 entries. Linked/tracked routes forward new pending cards as notices;
-their chat answers never authorize an action. After an explicit user decision, use
-`gbot_grok_respond` (CLI: `gbot approvals respond --target TARGET --entry-id ID
---request-id ID --decision accept|decline`). Copy the exact IDs from the current
-card. Accept grants once; persistent grants are unavailable. Responses recheck the
-card before sending; delivery success does not prove execution. Older cards,
-cookie/payment approvals and other unsupported requests require the owning Grok UI.
+Never resend an unknown submission under a new identity. Inspect delivery with
+`gbot_bridge_status`. Never infer permission from chat replies or auto-approve a
+Codex/Grok interaction; keep approvals in the owning UI unless the user explicitly
+authorizes a scoped response.
 
-List targets with `gbot bots list` / `gbot groups list` when the name is ambiguous.
-
-## CLI automation
+Read [bridge administration](references/bridge-administration.md) before starting,
+stopping, diagnosing or answering approvals on a managed bridge, or using direct
+Codex conversation tools. It covers exact approval IDs, idempotent requests, guarded
+steering, CLI output, and host limitations. Ordinary Grok sends need no reference.
 
-The bundled `gbot` and `gbot-install` executables require Node.js 22.19.0 or newer.
-For `gbot send`, `gbot codex status`, and `gbot codex send` with `--json`, read the result
-document from stdout and branch on its `exitCode`, `mode`, `reason`, and `delivery`.
-Framework argument/schema errors use stderr and exit 2. `--json` is reserved before
-`--`; put `--` before flag-like message text.
+List targets with `gbot bots list` / `gbot groups list` when the name is ambiguous.
 
 ## Auth
 
@@ -70,50 +62,14 @@ Same order as `gbot`: `GROK_BOT_GATEWAY_URL` plus `GROK_BOT_GATEWAY_TOKEN`,
 else the Grok Bot app session, else `CURSOR_ACCESS_TOKEN`. `gbot doctor` shows
 which source is present.
 
-## Codex conversation tools
-
-The generated Codex, Cursor, and Claude plugins and portable MCP artifact expose these
-additional tools on the same `grok-bot` MCP server. Codex tools use the local Codex
-app-server control socket; Grok tools use the Grok gateway. Portable MCP artifacts
-must be configured in an MCP-capable host; they are not automatically loaded by the Grok app.
-
-- `codex_threads`: bounded discovery of daemon-managed Codex threads.
-- `codex_send`: submit a message with a correlation envelope. Default delivery is
-  immediate acceptance, which does not mean execution finished. `wait: true` adds
-  bounded execution and final reply fields. An accepted message remains accepted
-  when observation times out or execution fails.
-- `codex_wait`: explicitly observe a known thread/turn and recover its final output.
-- `codex_watch`: diagnostic observation of bounded thread events. It never answers approvals.
-
-Use `expectedCwd` to verify the destination workspace. Busy sends reject by default;
-`whenBusy: queue` needs `GROK_BOT_CODEX_EXPERIMENTAL=1`. Explicit `whenBusy: steer`
-requires `expectedTurnId` and visibly rejects a stale guard without retrying another turn.
-Final replies omit commentary/reasoning; older phase-null agent messages are a fallback
-only after terminal execution. Inspect `reply.truncated` and execution errors for coverage limits.
-
-CLI equivalents are `gbot codex send --wait --timeout-ms 1000 THREAD_ID hello --json`,
-`gbot codex wait --timeout-ms 1000 THREAD_ID TURN_ID --json`, and
-`gbot codex watch --timeout-ms 1000 --max-events 20 THREAD_ID --json`.
-Use framework `--ndjson` for progress. Wait/watch are explicit diagnostics; automatic
-background reply routing uses the managed tools above. `codex_send` with `replyToGrok` or `bindingId` returns its terminal answer automatically; without either it retains the explicit observation flow. Managed routes default to guarded steering; ordinary sends still reject busy work by default.
-
-`gbot codex bridge start/status/stop/respond` provide the same administration controls.
-CLI auto-routing requires explicit `gbot send --reply-mode auto --codex-thread-id ID`.
-`bridge run` is foreground and bounded (`--lifetime-ms`, default/maximum 23 hours).
-The packaged `scripts/gbot-relay.mjs` is the unlimited foreground service entry.
-Grok participation is through its gateway conversation, not an assumed native Grok
-plugin loader or remote MCP tunnel. Never claim a host loaded a plugin from generated
-configuration alone.
-
-Managed Codex return routes reject `expectedTurnId` and legacy `replyTo`/`envelope`
-options before submission; use plain `codex_send` for a caller-selected turn guard.
-An explicit Grok target supplied with `bindingId` must resolve to the binding's
-recipient. A mismatch fails instead of selecting one destination silently.
-
-## Host tool inventory
-
-Codex MCP clients receive Grok messaging and approval tools; truthfully identified
-Grok Bot clients receive Codex messaging and approval tools. Bridge start/status/stop
-remain shared. Cursor and unknown clients retain both sets. Filtering uses negotiated
-client-name prefixes and does not provide authorization. A Grok runtime identifying
-itself as Cursor needs its native MCP identity corrected before this filter applies.
+## Claude Code channel
+
+`claude_send` sends to a named live Claude Code session on the user's registered
+machine (local socket under `~/.grok-bot-cli/claude/`) and waits for its explicit
+`claude_reply`. From the Grok Bot box, do not call this tool — use Grok Bot Shell
+with a machineId to run `gbot claude send` on that machine instead. The destination
+must enable the native `claude-channel` with `GROK_BOT_CLAUDE_CHANNEL=NAME` and
+Claude's development-channel opt-in. Supply `name`, `message`, and optional
+`timeoutMs` (1..120000). `replied` means the reply tool ran; `unknown` is not
+rejection and must not be automatically retried. Normal Claude tool approvals remain
+in its session. CLI: `gbot claude send NAME "message" --json`.

package/dist/skills/talk-to-grok-bot/references/bridge-administration.md

@@ -0,0 +1,89 @@
+# Bridge administration and diagnostics
+
+Automatic routes start a durable background worker that survives the calling tool.
+Use `gbot_bridge_status` to distinguish delivery from execution and return delivery,
+and to inspect gaps, paused routes and pending interactions. Do not resend unknown
+submissions under a new identity. A provided `requestId` safely replays identical
+tracked input; `controlRequestId` is returned independently of the gateway request ID.
+`gbot_bridge_stop` stops a `bindingId`; `worker: true` explicitly stops the process.
+Neither deletes receipts nor interrupts a Codex turn. No login service is installed;
+if the process dies, the next tracked send/start resumes saved routes.
+
+`gbot_codex_respond` is only for an explicit operator response to a current scoped
+interaction. Copy the advertised interactionId, generation, threadId, turnId and
+bindingId/exchangeId. Use one-time `decision: accept|decline|cancel`, or `answersJson`
+with exact question IDs mapped to `{"answers":["answer"]}`. Never auto-approve,
+change session permissions, or respond to an unsupported interaction; use its owning UI.
+
+Bot replies are `send-message` entries; yours are `message` with `role: user`.
+
+Grok-origin approvals are separate from Codex interactions. `gbot_grok_approvals`
+(CLI: `gbot approvals list TARGET`) lists pending auto-review and local-tool cards in
+the latest 200 entries. Linked/tracked routes forward new pending cards as notices;
+their chat answers never authorize an action. After an explicit user decision, use
+`gbot_grok_respond` (CLI: `gbot approvals respond --target TARGET --entry-id ID
+--request-id ID --decision accept|decline`). Copy the exact IDs from the current
+card. Accept grants once; persistent grants are unavailable. Responses recheck the
+card before sending; delivery success does not prove execution. Older cards,
+cookie/payment approvals and other unsupported requests require the owning Grok UI.
+
+## Codex conversation tools
+
+The generated Codex, Cursor, and Claude plugins and portable MCP artifact expose these
+additional tools on the same `grok-bot` MCP server. Codex tools connect only to a
+**local** Codex app-server control socket on the process's machine
+(`$CODEX_HOME/...` or `CODEX_APP_SERVER_SOCK`). gbot has **no remote transport**.
+When the MCP server runs on the Grok Bot agent box (`HOME=/home/box`), do not call
+these tools — run the `gbot` CLI on the user's registered machine through Grok Bot
+Shell with a machineId, after `codex app-server daemon start` (or bootstrap) there.
+Grok tools use the Grok gateway. Portable MCP artifacts must be configured in an
+MCP-capable host; they are not automatically loaded by the Grok app.
+
+- `codex_threads`: bounded discovery of daemon-managed Codex threads.
+- `codex_send`: submit a message with a correlation envelope. Default delivery is
+  immediate acceptance, which does not mean execution finished. `wait: true` adds
+  bounded execution and final reply fields. An accepted message remains accepted
+  when observation times out or execution fails.
+- `codex_wait`: explicitly observe a known thread/turn and recover its final output.
+- `codex_watch`: diagnostic observation of bounded thread events. It never answers approvals.
+
+Use `expectedCwd` to verify the destination workspace. Busy sends reject by default;
+`whenBusy: queue` needs `GROK_BOT_CODEX_EXPERIMENTAL=1`. Explicit `whenBusy: steer`
+requires `expectedTurnId` and visibly rejects a stale guard without retrying another turn.
+Final replies omit commentary/reasoning; older phase-null agent messages are a fallback
+only after terminal execution. Inspect `reply.truncated` and execution errors for coverage limits.
+
+CLI equivalents are `gbot codex send --wait --timeout-ms 1000 THREAD_ID hello --json`,
+`gbot codex wait --timeout-ms 1000 THREAD_ID TURN_ID --json`, and
+`gbot codex watch --timeout-ms 1000 --max-events 20 THREAD_ID --json`.
+Use framework `--ndjson` for progress. Wait/watch are explicit diagnostics; automatic
+background reply routing uses the managed tools above. `codex_send` with `replyToGrok` or `bindingId` returns its terminal answer automatically; without either it retains the explicit observation flow. Managed routes default to guarded steering; ordinary sends still reject busy work by default.
+
+`gbot codex bridge start/status/stop/respond` provide the same administration controls.
+CLI auto-routing requires explicit `gbot send --reply-mode auto --codex-thread-id ID`.
+`bridge run` is foreground and bounded (`--lifetime-ms`, default/maximum 23 hours).
+The packaged `scripts/gbot-relay.mjs` is the unlimited foreground service entry.
+Grok participation is through its gateway conversation, not an assumed native Grok
+plugin loader or remote MCP tunnel. Never claim a host loaded a plugin from generated
+configuration alone.
+
+Managed Codex return routes reject `expectedTurnId` and legacy `replyTo`/`envelope`
+options before submission; use plain `codex_send` for a caller-selected turn guard.
+An explicit Grok target supplied with `bindingId` must resolve to the binding's
+recipient. A mismatch fails instead of selecting one destination silently.
+
+## CLI automation
+
+The bundled `gbot` and `gbot-install` executables require Node.js 22.19.0 or newer.
+For `gbot send`, `gbot codex status`, and `gbot codex send` with `--json`, read the result
+document from stdout and branch on its `exitCode`, `mode`, `reason`, and `delivery`.
+Framework argument/schema errors use stderr and exit 2. `--json` is reserved before
+`--`; put `--` before flag-like message text.
+
+## Host tool inventory
+
+Codex MCP clients receive Grok messaging and approval tools; truthfully identified
+Grok Bot clients receive Codex messaging and approval tools. Bridge start/status/stop
+remain shared. Cursor and unknown clients retain both sets. Filtering uses negotiated
+client-name prefixes and does not provide authorization. A Grok runtime identifying
+itself as Cursor needs its native MCP identity corrected before this filter applies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-bot-cli",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "CLI and Agent Bundle plugin for Grok Bot agents and groups: create, update, message, inspect threads, and automate cleanup",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "gbot": "node dist/bin/gbot.mjs",
     "prepack": "agent-bundle prepack",
     "release": "changeset publish",
+    "release:version": "changeset version && npm run build && npm run validate:artifact",
     "test": "npm run test:unit && npm run test:routes",
     "test:routes": "rstest --config rstest.route-unit.config.ts",
     "test:unit": "node scripts/run-unit-tests.mjs",
@@ -54,12 +55,13 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@agent-bundle/runtime": "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@ab5ae66e1d9c2829a092640c586e2b3eacc4be88",
+    "@agent-bundle/runtime": "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@899755dc6d",
     "@changesets/cli": "3.0.3",
+    "@modelcontextprotocol/server": "2.1.0",
     "@rstest/core": "0.11.12",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.18",
-    "agent-bundle": "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@ab5ae66e1d9c2829a092640c586e2b3eacc4be88",
+    "agent-bundle": "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@899755dc6d",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2",