Repository navigation
feat(grok): add Grok Build as a fourth provider (grok-code-headless + parser codec + parity) #832
Description
Spec: docs/superpowers/specs/2026-09-07-grok-code-provider-design.md (branch feat/grok-code-provider). Plan: docs/superpowers/plans/2026-09-07-grok-code-provider.md. Stage-decomposed: stage-0 evidence captures, grok-code-headless package repo, agent-transcript-parser grok codec, app provider core, toolchain, provider switching both directions, renderer surface, ghost policy.
Activity
feat: add ConversationItem codec, session discovery, and real-CLI int…
Juliusolsson05 commentedon Sep 9, 2026
Local Grok headless progress: added an explicitly opt-in, shape-only native transcript export and a 22-session normalized corpus. No original prompts, tool text, ciphertext, source paths or source hashes are retained. Independent privacy review and codec/archive checks passed; export tests also cover malformed counters, linked identities, unsafe keys, symlinks and no-overwrite publication.
Added channel-qualified history reset/caught-up notifications, including empty atomic replacements. Resume/replacement observations are replay, not live activity or approval authority. Short reads cannot certify unread bytes as complete. Permission tokens are generation-scoped so reissued cards remain answerable while delayed old actions fail closed.
Verification on Node 24.14.1: grok-code-headless npm run check passed 148 deterministic tests, typecheck, build and packed-entry verification. All 3 native fixture-backed relay and one-shot approval tests passed. Read-only re-reviews reported no remaining blockers in these boundaries.
This work remains local/uncommitted; it is not part of a merged app release. PR #835 remains package/build wiring only. Agent Code runtime/renderer registration, switch persistence, main-turn streaming attribution and app-level end-to-end coverage remain outstanding. The app was not launched, no paid inference was used for these checks, and no merge was performed.
feat(grok): expose owned PTY bytes and process identity
Juliusolsson05 commentedon Sep 9, 2026
Publication update: the implementation is no longer local-only. Headless PR Juliusolsson05/grok-code-headless#1 is pushed at c3ecb63 with green CI and 150 deterministic tests; parser PR Juliusolsson05/agent-transcript-parser#27 is pushed at 5c43207 with green CI and 163 tests. App integration is now tracked in draft #844 at 4adcd8e, including current main, the exact component pins, sidecar-preserving switch/duplicate/rewind publication, strict Grok file-set persistence and tests.
App-local verification passed: 62 switching unit tests, 9 real-filesystem/parser system tests, full app typecheck and an installed-Grok loopback test using the APP publisher. Native Grok loaded imported tool context, supplied its own system instructions, appended a reply and did not re-execute historical tools. Seven read-only orchestration agents audited/reviewed the boundaries; verified findings were addressed.
Grok remains unavailable as a selectable app provider. Runtime/renderer registration, correctness-bearing history resets across desktop/phone, recorded composer readiness, native-TUI built-in MCP injection and verified main-turn streaming attribution remain gates in #844. Component CI is separate from app-wide verification. No PRs have been merged.
Juliusolsson05 commentedon Sep 9, 2026
Verification follow-up: draft app PR #844 now has green quality-gate and minimum-node-fixture-gate checks. The quality pipeline passed core/system/renderer tests, coverage, typechecks and distributable-output verification. Headless native loopback relay and one-shot permission tests were rerun after the raw-PTY delta: all3 passed. The app-published native resume probe also passed against the updated pinned headless revision. These verify the implemented publication stage; full runtime/renderer registration and the documented readiness/MCP/attribution gates remain open. No PR merged.
test(grok): prove native ACP control with the real TUI
Juliusolsson05 commentedon Sep 11, 2026
Approved architecture update is committed to draft #844 as67045890 (docs/decomposition/grok-native-control.md). Grok is now1.0.25. Native terminal paste was observed attaching unrequested clipboard content in a loopback-only test; this is tracked in grok-code-headless#2 and no unexpected payload was published.
The new ACP route has now been VERIFIED against the installed binary: literal multiline/tab text, no images, private native leader +stdio control +actual TUI, replay/live TUI output, per-session MCP calls and isolation, and native permission UI cancelled via ACP. Evidence/probe is pushed in headless#1 at eac5b65. This establishes a viable native route without clipboard-sensitive paste or user-config edits; production control/lifecycle code, app runtime/renderer/reset integration and final end-to-end coverage still remain. Both integration PRs stay draft; no merge approval was inferred.
docs(grok): record verified ACP control and reconnect gate
Juliusolsson05 commentedon Sep 11, 2026
ACP control checkpoint: headless PR Juliusolsson05/grok-code-headless#1 now includes 9108a42 (owned PID-verified direct IPC, typed prompt/MCP, cancellation correlation and shared-permission retirement). 180 deterministic tests, typecheck/build/packed exports, and both installed Grok 1.0.25 loopback proof variants passed. Normal shutdown checks process absence; TUI rejection invalidates stale ACP permission tokens.
New source-backed integration gate: Juliusolsson05/grok-code-headless#3 records native TUI automatic respawn and embedded fallback, for which no supported connect-only option was found. Native crash containment is not yet proven. App #844 remains draft; its design/progress record is updated in d778066. The next design decision is a verified TUI lifetime boundary before enabling app input.
fix(grok): reconcile current main with transcript publications
build(grok): pin verified native control and TUI guard
Juliusolsson05 commentedon Sep 12, 2026
Current implementation checkpoint: headless 4814a17 includes the framed TUI guard, 198 passing deterministic tests, green package CI, and isolated installed-native failed-attachment/idle-crash/mid-turn-crash proofs. Full details and remaining scope are in grok-code-headless#3 and its metadata-only native-tui-guard-proof fixture.
App #844 is now at 51d37e5, includes main 552914f, fixes the newer Codex clone publication contract, and pins the reviewed control/guard implementation. All eight runtime pins, full typecheck and 90 selected provider-switch/capability tests pass locally; newest app CI is running. Older wiring #835 is already included, so implementation remains consolidated in #844 rather than reopening another branch.
Next gates: one owned Grok runtime with native session-identity controls and prompt acceptance semantics, then provider/Conversations registration, desktop/phone structural resets and rendering, model-driven tools, streaming attribution and complete end-to-end verification. Grok remains unselectable and all Grok PRs remain unmerged.
docs(grok): decompose runtime adoption around recorded evidence
docs(grok): mirror sibling provider structure in runtime plan
feat(grok): expose transport and lifecycle observations for evidence …
test(grok): inventory Claude render shapes as Grok collection targets
test(grok): record and strictly verify controlled native runtime evid…
fix(grok): close remaining fail-open paths in runtime evidence verifi…
test(grok): publish shape-only controlled runtime timelines
test(grok): record Grok verdicts for every Claude render shape
docs(grok): record the Stage 1 controlled-runtime exit gate
merge: bring current main into the Grok app integration
test(grok): record prompt identity, queued cancel and terminal new-se…
docs(grok): record the Stage 2 ownership evidence in the runtime plan
test(grok): catalog recorded runtime ownership and settle the Stage 2…
Juliusolsson05 commentedon Sep 20, 2026
Shipped and never closed. PR #844 (
5fda2f06) plus PR #835 (feat(grok): add grok-code-headless submodule and resolver wiring). Grok is a real fourth provider end to end:registry.main.ts:144-181(grokMain, typed as aRecord<AgentProviderKind, …>so omitting a provider is a compile error),registry.renderer.ts:47-56,registry.setup.ts:85-99(binaryName: 'grok', installnpm install -g @xai-official/grok).AGENT_PROVIDER_KINDS = ['claude','codex','opencode','grok'](providerKind.ts:35, pinned byproviderKind.test.ts:20), andproviderChoices.tsderives every picker from that list, so Grok appears in create, spawn and switch without a second registration.grokinswitchTargets, and grok lists all three back.packages/agent-transcript-parser/src/grok/, enginegrokTranscript.tswith system/listPrompts/live tests, conversations sourceconversations/sources/grok.ts.grokSession.ts,promptDelivery.ts,transcript/mapper.tsx,conditions/views.tsx. 25 test files undersrc/exercise Grok.On the packaging question, for anyone who checks:
grok-code-headlessis not an npm dependency — and neither is any other headless package. All five (claude-code-headless,codex-headless,opencode-headless,opencode-terminal-headless,agent-transcript-parser) resolve identically as git submodules throughelectron.vite.config.tsaliases plus the tsconfig and vitest path maps..gitmodulescarriespackages/grok-code-headless, and its pin is an ancestor of that repo'sorigin/main.One declared gap, deliberate and recorded in code rather than forgotten:
grokMain.personalAgentSkills = { supported: false }— native Grok skill locations are unrecorded, so personal agent skills are not claimed for Grok panes. Separately, Grok emits the sameprovider_session_switcheddiagnostic as OpenCode rather than following a TUI-side switch; that is #894's scope, not this one.