mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00

Files

T

Renn F 3441e37120 [sweep] strip Fxxx audit-ID tokens + trim bloated comments/docstrings + add behavior-change docs

Post-audit sweep over the 135 audit-fix commits since 19a474d3:

1. Stripped every # Fxxx: audit-ID token from comments AND every Fxxx token
   from docstring openings across 211 blocks / ~626 lines. The CEO flagged
   these twice: audit-issue IDs in code confuse future devs/agents. The
   descriptive text is preserved; only the Fxxx token is removed (and bloated
   narrative blocks trimmed to 1-3 lines keeping the one non-obvious invariant).
2. Trimmed bloated comments/docstrings to the concise standard (1-3 lines).
3. Added missing behavior-change docs for the audit-fix batch: prompts/roles
   (documenter, pr_reviewer, qa), user-facing docs (api auth, websockets,
   agent-gateway, megatask, merge-model, task-lifecycle, grok, resilience,
   conventions, panel, security, troubleshooting), and the RAG corpus (cell-pm,
   main-pm, pr-reviewer, qa roles; conventions; messaging-tools; escalation;
   megatask; task-claiming workflows).

Comment/docstring/prose ONLY — zero code-line edits (verified: the diff
contains no def/class/return/if/for/await/assignment/call lines). Gates green:
ruff format + ruff check clean, mypy clean on roboco/. The only pytest failures
are the pre-existing sync_branch tracing-decision gap (B1, 250be5c2) — not
sweep-caused and tracked separately.

2026-06-29 01:25:40 +02:00

4.5 KiB

Raw Blame History

Run on xAI Grok

RoboCo can run the entire workforce — or just some agents — on xAI Grok, using xAI's official grok CLI on a SuperGrok subscription rather than a metered API key. That matters operationally: a subscription can't run out of credits mid-task, so a Grok fleet won't stall halfway through a delivery the way a metered key can. Grok reaches full parity with the Claude path by construction: the same MCP gateway, the same per-role tool manifest, the same prompt-injection and bash guards, the same per-agent cost capture.

Set it up once

Authenticate Grok on the host with the official CLI, then point RoboCo at the resulting directory:

grok login                     # once, on the host — creates ~/.grok/auth.json

Then in .env:

ROBOCO_HOST_GROK_DIR=/home/youruser/.grok   # the REAL host ~/.grok to mount in

The orchestrator mounts that directory's auth.json read-only into each Grok agent container. On a NAS or any docker-in-docker deploy the orchestrator's home is not the host's home, so ROBOCO_HOST_GROK_DIR must point at the actual host path where grok login wrote ~/.grok — otherwise agents start with no credential.

Finally, on Settings → AI Providers set the routing mode to Grok (whole fleet) or pin individual agents to a Grok model in Mix mode. See Choosing a provider for the modes and precedence. The installation guide covers the same first-run steps inline.

The token refreshes itself

The Grok access token has a fixed ~6-hour, server-set lifetime, and the CLI can't refresh it headlessly — on an expired token it would hang forever at an interactive login prompt. RoboCo handles this for you:

Once per dispatch tick the orchestrator mints a fresh token from the offline-access refresh token (xAI's OIDC refresh_token grant) before expiry and atomically rewrites the shared auth.json in place. The refresh fires ROBOCO_GROK_AUTH_REFRESH_SKEW seconds (default 1800) ahead of expiry.
As a backstop, each agent's entrypoint runs python -m roboco.llm.providers.grok_auth --check and refuses to start on a missing or expired token instead of hanging.

!!! warning "The orchestrator's ~/.grok mount must be writable" The orchestrator rewrites auth.json when it refreshes the token, so the orchestrator's own mount of ~/.grok must be read-write. (The per-agent mount stays read-only — agents only read the credential.) If the orchestrator can't write it, the token will expire and Grok agents will fail their start-up --check. If the host auth.json is missing entirely at spawn time, the orchestrator logs a loud warning — a missing credential is the most common Grok misconfiguration, so it's surfaced early rather than as a fleet of failed starts.

Per-fleet tuning

Three optional knobs let you trade cost against quality across the whole Grok fleet. All are env-set and apply uniformly (no per-role reduction — that's parity with the Claude path):

Variable	Default	What it does
`ROBOCO_GROK_REASONING_EFFORT`	unset (model default)	The `grok --effort` level. Set `low` / `medium` / `high` / `xhigh` / `max` to dial cost vs quality; empty, `default`, or `full` keeps the model's own default.
`ROBOCO_GROK_MAX_TURNS`	`200`	The per-agent turn cap for a `grok -p` run.
`ROBOCO_GROK_MAX_COST_USD`	`0` (off)	A per-agent cost ceiling in USD. The grok CLI has no live usage hook, so the orchestrator reads each running container's captured cost and kills it once it crosses this ceiling — a backstop against a runaway loop. `0` disables the cap.

Two more variables exist mostly for staged rollouts and tests:

Variable	Default	What it does
`ROBOCO_GROK_AGENT_IMAGE`	`roboco-agent-grok:latest`	Override the Grok agent Docker image.
`ROBOCO_GROK_CLI_MODEL`	`grok-build`	The grok CLI model id passed to agents.

!!! note "Usage and cost still show up" Each Grok agent gets a per-agent usage directory mounted read-write so its token/cost is read back when the session finalizes. Grok traffic therefore lands on the same usage dashboard as Claude, priced from the captured session totals.

Choosing a provider — set the Grok mode or pin agents in Mix.
What keeps a run alive — Grok agents park-and-resume on a rate limit like any other provider.

4.5 KiB Raw Blame History

Run on xAI Grok

Set it up once

The token refreshes itself

Per-fleet tuning

Next

4.5 KiB

Raw Blame History