feat(grok-cli): grok CLI agent image + headless entrypoint

The roboco-agent-grok image now installs xAI's official grok CLI (Grok Build,
pinned 0.2.56) instead of opencode, authenticated by the SuperGrok subscription
via a mounted ~/.grok/auth.json (parity with the Claude ~/.claude mount, no
metered API key). The entrypoint renders ~/.grok/config.toml + per-role flags
from /app (the ModuleNotFound-shadowing lesson), runs grok -p headless with
--output-format json, keeps the prompt-injection guard, and exits 75 on a
rate-limit so the orchestrator parks the provider. No in-container SDK server or
budget-feed — native --max-turns + server-side terminal-substitute replace them.

docker/agent-grok.Dockerfile

@@ -1,55 +1,41 @@
 # Grok (xAI) Agent Image
 # =============================================================================
-# Runs grok-build-0.1 through the opencode CLI (OpenAI protocol) instead of
+# Runs Grok Build through xAI's official `grok` CLI, authenticated by the
-# Claude Code, while reusing the base image's roboco venv + uv + the RoboCo MCP
+# SuperGrok subscription via a mounted ~/.grok/auth.json — the parity analogue of
-# gateway servers. The entrypoint renders opencode.json from the spawn env +
+# the Claude Code path's mounted ~/.claude (no metered API key). Reuses the base
-# mounted mcp-config.json (see roboco.llm.providers.opencode_config) and runs
+# image's roboco venv + uv + the RoboCo MCP gateway servers. The entrypoint
-# opencode. One runtime image serves every role — role behaviour comes from the
+# renders ~/.grok/config.toml (the gateway) + the per-role grok flags from the
-# mounted system prompt / manifest / mcp-config, exactly as on the Claude path.
+# mounted mcp-config.json (see roboco.llm.providers.grok_cli_config) and runs the
+# CLI headless. One runtime image serves every role — role behaviour comes from
+# the mounted system prompt / manifest / mcp-config, exactly as on the Claude path.
 # =============================================================================
 
 FROM roboco-agent-base
 
 USER root
 
-# opencode — the OpenAI-protocol agent runtime. grok-build-0.1 runs on opencode's
+# Install the official grok CLI (Grok Build) for the agent user: the binary lands
-# BUILT-IN xai provider (no custom provider block / npm needed), so only
+# at ~/.local/bin/grok and its runtime (bin / bundled / skills) at ~/.grok, both
-# opencode-ai is installed; it resolves the provider SDK at runtime.
+# agent-owned. Pinned — untrusted model output runs under it, so bump the version
-# Pinned: this version is the live-verified runtime (grok-build-0.1 on the NAS).
+# deliberately, never float. (curl + bash are provided by roboco-agent-base.)
-# Untrusted model output runs under it, so bump the pin deliberately, never float.
+ARG GROK_CLI_VERSION=0.2.56
-ARG OPENCODE_VERSION=1.17.8
+RUN su agent -s /bin/bash -c "export HOME=/home/agent; \
-RUN npm install -g "opencode-ai@${OPENCODE_VERSION}" \
+      curl -fsSL https://x.ai/cli/install.sh | bash -s ${GROK_CLI_VERSION}" \
-    && npm cache clean --force \
+    && rm -rf /tmp/*
-    && rm -rf /root/.npm /tmp/*
 
-# opencode plugins, baked into the AUTO-DISCOVERY dir (~/.config/opencode/plugin/)
+# Entrypoint: render ~/.grok/config.toml + the per-role flags, then run grok
-# rather than referenced by a config `plugin:` path — the dir is the simplest
+# headless (overrides the base image's `claude` entrypoint).
-# registration route. Each plugin uses a NAMED export (opencode's convention).
+COPY docker/scripts/grok-cli-agent-entrypoint.sh /app/scripts/grok-cli-agent-entrypoint.sh
-#   secret-scrub — bash-guard parity (PAT/credential deny on tool.execute.before)
+RUN chmod 0755 /app/scripts/grok-cli-agent-entrypoint.sh \
-#   budget-feed  — POSTs budget/loop/terminal counters to the in-container SDK
+    && chown -R agent:agent /home/agent/.grok /home/agent/.local
-#                  server (tool.execute.{before,after}); the entrypoint starts
-#                  that server (roboco.agent_sdk.server) for Claude-parity.
-COPY docker/grok/secret-scrub.js /home/agent/.config/opencode/plugin/secret-scrub.js
-COPY docker/grok/budget-feed.js /home/agent/.config/opencode/plugin/budget-feed.js
-
-# Entrypoint: render opencode.json, then run opencode (overrides base's `claude`).
-COPY docker/scripts/grok-agent-entrypoint.sh /app/scripts/grok-agent-entrypoint.sh
-RUN chmod 0755 /app/scripts/grok-agent-entrypoint.sh
-
-# opencode persists data under ~/.local/share and state under ~/.local/state, and
-# reads config + plugins from ~/.config/opencode. When the orchestrator
-# bind-mounts the opencode store at ~/.local/share/opencode, docker creates the
-# intermediate ~/.local AS ROOT, so the non-root agent can no longer create its
-# siblings and opencode EACCESes at boot. Pre-create the trees agent-owned so the
-# mount leaves the parents writable (complements the orchestrator's 0777
-# host-source pre-create), and so the baked plugin dir is agent-owned.
-RUN mkdir -p /home/agent/.local/share/opencode /home/agent/.local/state \
-        /home/agent/.config/opencode/plugin \
-    && chown -R agent:agent /home/agent/.local /home/agent/.config
 
 USER agent
 
-LABEL role="grok-runtime"
+# grok installs to ~/.local/bin; put it ahead of the venv on PATH so the
-LABEL description="Grok (xAI) agent runtime — grok-build-0.1 via opencode (OpenAI protocol)"
+# entrypoint finds `grok` (and still resolves `python` to /app/.venv/bin).
+ENV PATH="/home/agent/.local/bin:/app/.venv/bin:$PATH"
 
-ENTRYPOINT ["/app/scripts/grok-agent-entrypoint.sh"]
+LABEL role="grok-cli-runtime"
+LABEL description="Grok (xAI) agent runtime — Grok Build via the official grok CLI"
+
+ENTRYPOINT ["/app/scripts/grok-cli-agent-entrypoint.sh"]

docker/scripts/grok-cli-agent-entrypoint.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Entrypoint for the roboco-agent-grok-cli image (one-shot delivery roles).
+#
+# Runs an agent on xAI's official `grok` CLI (Grok Build), authenticated by the
+# SuperGrok subscription via a mounted ~/.grok/auth.json — the parity analogue of
+# the Claude Code path's mounted ~/.claude. The gateway, identity, and workspace
+# are mounted by the orchestrator's shared container assembly (the same that
+# wires Claude); this entrypoint renders the grok runtime config from that mount
+# and runs the CLI headless.
+set -euo pipefail
+
+# Render ~/.grok/config.toml (the MCP gateway) + the per-role grok flags. Run
+# from /app so `python -m` resolves the INSTALLED roboco package: dev/doc/qa
+# agents run at their workspace-clone cwd, whose own roboco/ dir would shadow it
+# on the sys.path front (the ModuleNotFound lesson). The render reads
+# ROBOCO_MCP_CONFIG + ROBOCO_AGENT_ID and writes the config + an args file.
+( cd /app && python -m roboco.llm.providers.grok_cli_config )
+
+GROK_ARGS_FILE="${ROBOCO_GROK_ARGS_FILE:-/tmp/roboco-grok-args}"
+mapfile -t GROK_ARGS < "$GROK_ARGS_FILE"
+
+# Prompt-injection guard (parity with the Claude UserPromptSubmit hook): the task
+# prompt is DATA, not instructions — refuse a poisoned one before the model sees
+# it. Same patterns as docker/scripts/user-prompt-hook.sh; run from /app too.
+if ! ( cd /app && python -m roboco.agent_sdk.prompt_guard "${ROBOCO_INITIAL_PROMPT:-}" ); then
+  echo "Refusing to run: task prompt matched a prompt-injection pattern." >&2
+  exit 1
+fi
+
+# Run the agent. The prompt comes from an env var (never an untrusted argv
+# positional). `< /dev/null` keeps the headless run from blocking on stdin. We
+# do NOT `exec`: the script regains control to inspect the result + exit code.
+# `--cwd` is the agent's workspace (the orchestrator sets the container workdir
+# to it, mirroring the Claude path). Per-role flags (tool removal / deny rules /
+# effort / turn cap) come from the rendered args file.
+RUN_LOG="/tmp/grok-run.json"
+ERR_LOG="/tmp/grok-run.err"
+WORKSPACE="${ROBOCO_WORKSPACE:-$PWD}"
+set +e
+grok -p "${ROBOCO_INITIAL_PROMPT:-}" \
+  -m "${ROBOCO_AGENT_MODEL:-grok-build}" \
+  --cwd "$WORKSPACE" \
+  --output-format json \
+  "${GROK_ARGS[@]}" \
+  < /dev/null > "$RUN_LOG" 2> "$ERR_LOG"
+run_rc=$?
+set -e
+# Surface the run output + any stderr into the agent log.
+cat "$RUN_LOG"
+[ -s "$ERR_LOG" ] && cat "$ERR_LOG" >&2
+
+# Rate-limit detection (parity with the opencode B4 path): an xAI 429 / quota
+# error ends the run without a terminal verb. Detect it from the run output and
+# exit 75 (EX_TEMPFAIL) so the orchestrator PARKS the grok provider instead of
+# the dispatcher respawning the same task every tick (429 -> exit -> respawn, a
+# token loop). A rate-limited task is retried once the limit lifts, not dropped.
+if grep -qiE '(\b429\b|rate.?limit|too many requests|quota|insufficient_quota)' \
+    "$RUN_LOG" "$ERR_LOG" 2>/dev/null; then
+  echo "[grok] rate-limited — exiting 75 so the orchestrator parks the provider;" \
+    "the task is retried when the limit lifts." >&2
+  exit 75
+fi
+
+# A graceful exit without a terminal verb is handled server-side by the
+# orchestrator (_handle_stopped_container substitutes the still-owned task) —
+# the grok-cli runtime needs no in-container SDK server for that.
+exit "$run_rc"