ouroboros-ai 0.44.1.dev2__tar.gz → 0.44.1.dev4__tar.gz

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.44.1.dev2
+Version: 0.44.1.dev4
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/docs/cli-reference.md

@@ -68,7 +68,7 @@ ouroboros auto "Build a local-first habit tracker CLI"
 | Option | Description |
 |--------|-------------|
 | `--resume TEXT` | Resume an existing auto session id |
-| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
+| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
 | `--max-interview-rounds INTEGER` | Maximum automatic interview rounds; prevents unbounded interview loops |
 | `--max-repair-rounds INTEGER` | Maximum Seed repair rounds; prevents unbounded repair loops |
 | `--skip-run` | Stop after creating an A-grade Seed |
@@ -243,7 +243,7 @@ ouroboros setup [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`. Auto-detected if omitted |
+| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Auto-detected if omitted |
 | `--opencode-mode TEXT` | OpenCode integration mode: `plugin` (default, recommended — bridge plugin for interactive sessions) or `subprocess` (headless/CI). Mutually exclusive — see [OpenCode runtime guide](runtime-guides/opencode.md#configuration) |
 | `--non-interactive` | Skip interactive prompts (for scripted installs) |
 | `--mcp-mode TEXT` | Codex MCP config mode: `auto` (default), `preserve`, or `stdio` |
@@ -343,7 +343,7 @@ ouroboros init [start] [OPTIONS] [CONTEXT]
 | `-r, --resume TEXT` | Resume an existing interview by ID |
 | `--state-dir DIRECTORY` | Custom directory for interview state files |
 | `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
-| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`. Custom adapters registered in `runtime_factory.py` are also accepted. |
+| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Custom adapters registered in `runtime_factory.py` are also accepted. |
 | `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`) |
 | `-d, --debug` | Show verbose logs including debug messages |
 
@@ -416,7 +416,7 @@ ouroboros run [workflow] [OPTIONS] SEED_FILE
 | Option | Description |
 |--------|-------------|
 | `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
-| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`). Uses configured default if omitted |
+| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Uses configured default if omitted |
 | `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
 | `--mcp-config PATH` | Path to MCP client configuration YAML file |
 | `--mcp-tool-prefix TEXT` | Prefix to add to all MCP tool names (e.g., `mcp_`) |
@@ -945,7 +945,7 @@ ouroboros mcp serve [OPTIONS]
 | `-p, --port INTEGER` | Port to bind to (default: 8080) |
 | `-t, --transport TEXT` | Transport type: `stdio`, `sse`, or `streamable-http` (default: stdio). Note: `http` is only a client config alias for outbound MCP connections and is NOT a valid serve transport. |
 | `--db TEXT` | Path to the EventStore database file |
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
 | `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
 
 **Examples:**
@@ -1027,7 +1027,7 @@ ouroboros mcp info [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
 | `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
 
 **Available Tools:**
@@ -1066,7 +1066,7 @@ The table below covers the most commonly used variables. For the full list — i
 | `ANTHROPIC_API_KEY` | — | Anthropic API key for Claude models |
 | `OPENAI_API_KEY` | — | OpenAI API key for LiteLLM / Codex CLI |
 | `OPENROUTER_API_KEY` | — | OpenRouter API key for consensus and LiteLLM |
-| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`) |
+| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`) |
 | `OUROBOROS_RUNTIME` | `orchestrator.runtime_backend` (fallback) | Shortcut env var honored by both `orchestrator.runtime_backend` and `llm.backend` resolution when their dedicated env vars are unset |
 | `OUROBOROS_KIRO_CLI_PATH` | `orchestrator.kiro_cli_path` | Explicit path to `kiro-cli` binary when it is not on `PATH` |
 | `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for Claude Code / Codex runtimes (no-op for OpenCode) |

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/docs/runtime-capability-matrix.md

@@ -13,7 +13,7 @@ The runtime backend is selected via the `orchestrator.runtime_backend` config ke
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | gemini | kiro | copilot | pi | gjc
+  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | gemini | kiro | copilot | pi | gjc | antigravity | grok
                             # The runtime abstraction layer also accepts custom
                             # adapters registered in runtime_factory.py
 ```
@@ -26,10 +26,16 @@ ouroboros run workflow --runtime codex seed.yaml
 
 You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME` environment variable.
 
-> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, Kiro CLI, GitHub Copilot CLI, Pi CLI, and GJC are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter).
+> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, Kiro CLI, GitHub Copilot CLI, Pi CLI, GJC, the Antigravity CLI (`agy`, Google's Gemini-CLI successor — runtime-only), and the Grok Build CLI (`grok`, xAI — runtime-only) are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter). For the full contracts, see [runtime-guides/antigravity.md](runtime-guides/antigravity.md) and [runtime-guides/grok.md](runtime-guides/grok.md).
 
 ## Capability Matrix
 
+> **Note — runtime-only backends not yet threaded as columns:** The tables below
+> predate the runtime-only backends added more recently. Their per-capability
+> contract lives in the per-runtime guide rather than as a column here:
+> Antigravity (`agy`) → [runtime-guides/antigravity.md](runtime-guides/antigravity.md);
+> Grok (`grok`) → [runtime-guides/grok.md](runtime-guides/grok.md).
+
 ### Workflow Layer (identical across runtimes)
 
 These capabilities are part of the Ouroboros core engine and work the same way regardless of runtime backend.

ouroboros_ai-0.44.1.dev4/docs/runtime-guides/antigravity.md

@@ -0,0 +1,154 @@
+# Antigravity CLI Runtime
+
+Run Ouroboros workflows on top of the locally installed **Antigravity CLI**
+(the `agy` binary) — Google's successor to the Gemini CLI.
+
+On **2026-06-18** the Gemini CLI stops serving the Google AI Pro / Ultra / free
+consumer tiers and migrates those users to the Antigravity CLI (enterprise and
+API-key Gemini access is unaffected). If you authenticated the Gemini runtime
+through a Pro/Ultra subscription, switch the affected stages to the
+`antigravity` runtime.
+
+The Antigravity runtime extends the Gemini runtime (Antigravity is Google's
+Gemini-CLI successor): Ouroboros owns the orchestration loop and shells out to
+`agy` per task. `agy -p` prints a **plain-text** response (there is no
+`--output-format` flag), so the runtime surfaces the final answer as assistant
+messages and checkpoints at the Ouroboros layer (event store + lineage) rather
+than inside the subprocess.
+
+## Prerequisites
+
+| Requirement       | Why                                                              |
+|-------------------|------------------------------------------------------------------|
+| `agy` CLI         | Provider — the Antigravity CLI binary, installed in `~/.local/bin`|
+| Google auth       | Run `agy` once (browser OAuth) — Google AI Pro/Ultra/free, or set `ANTIGRAVITY_API_KEY` |
+| Ouroboros (base)  | `pip install ouroboros-ai` — no provider-specific extras         |
+
+> Antigravity runs on the **base** Ouroboros package. It does **not** require
+> the `[claude]` extra.
+
+## Quick start
+
+```bash
+# 1. Authenticate the Antigravity CLI (one-time browser OAuth)
+agy            # first launch opens the sign-in flow
+
+# 2. Point Ouroboros at Antigravity (config.yaml or the settings GUI)
+ouroboros config           # GUI: set Execute/Evaluate/... runtime to "antigravity"
+# or set OUROBOROS_ANTIGRAVITY_CLI_PATH / orchestrator.antigravity_cli_path
+
+# 3. Run a workflow
+ouroboros run workflow seed.yaml --runtime antigravity
+```
+
+## CLI path resolution
+
+The runtime looks for the binary in this order:
+
+1. Constructor argument `cli_path=...`
+2. `OUROBOROS_ANTIGRAVITY_CLI_PATH` environment variable
+3. `orchestrator.antigravity_cli_path` in `~/.ouroboros/config.yaml`
+4. `agy` on `$PATH`
+
+## Configuration
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: antigravity
+  antigravity_cli_path: ~/.local/bin/agy   # optional; auto-detected
+```
+
+Antigravity is **runtime-only** — it drives the agentic orchestrator but is not
+registered as an LLM-completion backend (`agy -p` returns plain text, not a
+structured JSON/schema payload), so it is not a valid `llm.backend` value. Use
+the runtime via `orchestrator.runtime_backend`, per-stage routing, or
+`--runtime antigravity`. For completion-level diversity (consensus / role
+models) route Gemini/other vendors through `litellm`/OpenRouter.
+
+### Per-stage routing
+
+Antigravity shines as a cross-vendor stage in a multi-LLM pipeline — for
+example, generate with one vendor and verify with another:
+
+```yaml
+orchestrator:
+  runtime_backend: claude
+  runtime_profile:
+    stages:
+      execute: claude          # generate
+      evaluate: antigravity    # cross-vendor verification (Gemini 3.x via agy)
+```
+
+## Headless contract
+
+Each task spawns:
+
+```text
+agy -p <PROMPT> \
+    --dangerously-skip-permissions \
+    [--model <MODEL>]
+```
+
+| Flag                             | Why                                                       |
+|----------------------------------|-----------------------------------------------------------|
+| `-p` (`--print` / `--prompt`)    | Runs a single prompt non-interactively, prints the answer |
+| `--dangerously-skip-permissions` | Auto-approves tool requests so the subprocess never blocks|
+| `--model`                        | Forwarded only for an explicit, non-sentinel model id     |
+
+`agy` exposes no granular accept-edits-only mode, so both Ouroboros
+non-blocking permission modes map to the single skip flag:
+
+| Ouroboros permission mode | `agy` behavior                  | Notes                                         |
+|---------------------------|---------------------------------|-----------------------------------------------|
+| `acceptEdits` (default)   | `--dangerously-skip-permissions`| Over-approximated to full skip (no narrower mode) |
+| `bypassPermissions`       | `--dangerously-skip-permissions`| Explicit full bypass                          |
+
+The interactive Ouroboros `default` mode is normalized to `acceptEdits` (with an
+audit log) because a headless `agy -p` invocation cannot service a TTY approval
+prompt.
+
+> ⚠️ **Security note — `acceptEdits` is full auto-approval here.** Unlike the
+> Gemini parent runtime (where `acceptEdits` maps to the narrower edits-only
+> `--approval-mode auto_edit`), `agy` exposes no edits-only mode, so on
+> Antigravity **both** `acceptEdits` (the default) and `bypassPermissions`
+> resolve to `--dangerously-skip-permissions` — every tool request is
+> auto-approved, not just file edits. This is `agy`'s all-or-nothing permission
+> model, and it applies only when you explicitly select the `antigravity`
+> backend. Run Antigravity stages in a sandbox/worktree (Ouroboros uses managed
+> git worktrees by default) and do not select it for untrusted inputs if you
+> need edits-only containment — use the Claude, Codex, or Gemini runtime there
+> instead.
+
+Available models (`agy models`): Gemini 3.5 Flash, Gemini 3.1 Pro, Claude
+Sonnet 4.6, Claude Opus 4.6, GPT-OSS 120B (subject to your plan). Antigravity is
+a **sentinel-model backend** — by default Ouroboros lets `agy` pick its own
+configured model and only forwards `--model` when you set an explicit id.
+
+## Capabilities
+
+| Capability               | Status                                                |
+|--------------------------|-------------------------------------------------------|
+| Headless execution       | ✅ `agy -p`                                           |
+| Tool calls               | ✅ (Antigravity-managed via `--dangerously-skip-permissions`) |
+| Structured event stream  | ❌ plain-text stdout (no `--output-format`)           |
+| Session resumption       | ❌ not surfaced in v1 (recovery at the Ouroboros lineage layer) |
+| LLM-completion backend   | ❌ runtime-only                                       |
+
+If you need a structured event stream or resumable sessions, use the Claude,
+Codex, or Grok runtime.
+
+## Troubleshooting
+
+**`agy` not found.** Install the Antigravity CLI, then set
+`OUROBOROS_ANTIGRAVITY_CLI_PATH=/abs/path/to/agy` or
+`orchestrator.antigravity_cli_path`.
+
+**The CLI hangs waiting for input.** The runtime always passes
+`--dangerously-skip-permissions` and `-p`. If you see a hang, confirm you are
+invoking the runtime through `ouroboros run` (or the MCP server) rather than
+driving `agy` directly.
+
+**Gemini stopped working on 2026-06-18.** That is the consumer-tier Gemini CLI
+cutoff. Switch the affected stages to `antigravity`, or keep Gemini via an
+enterprise/API-key credential (unaffected).

ouroboros_ai-0.44.1.dev4/docs/runtime-guides/grok.md

@@ -0,0 +1,145 @@
+# Grok Build CLI Runtime
+
+Run Ouroboros workflows on top of the locally installed xAI **Grok Build** CLI
+(the `grok` binary).
+
+The Grok runtime is a sibling of the Codex / Gemini / Hermes runtimes:
+Ouroboros owns the orchestration loop and shells out to `grok` per task. Grok
+emits a structured `streaming-json` event stream, so intermediate reasoning and
+output are surfaced live; v1 checkpoints at the Ouroboros layer (event store +
+lineage) rather than using Grok's native session resume.
+
+## Prerequisites
+
+| Requirement       | Why                                                              |
+|-------------------|------------------------------------------------------------------|
+| `grok` CLI        | Provider — install via `curl -fsSL https://x.ai/cli/install.sh \| bash` |
+| xAI auth          | `grok login` (browser OAuth, SuperGrok / X Premium+) or `XAI_API_KEY` |
+| Ouroboros (base)  | `pip install ouroboros-ai` — no provider-specific extras         |
+
+> Grok Build runs on the **base** Ouroboros package. It does **not** require the
+> `[claude]` extra.
+
+## Quick start
+
+```bash
+# 1. Install + authenticate the Grok Build CLI
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login                           # browser OAuth (SuperGrok / X Premium+)
+
+# 2. Point Ouroboros at Grok (config.yaml or the settings GUI)
+ouroboros config                     # GUI: set a stage's runtime to "grok"
+
+# 3. Run a workflow
+ouroboros run workflow seed.yaml --runtime grok
+```
+
+## CLI path resolution
+
+The runtime looks for the binary in this order:
+
+1. Constructor argument `cli_path=...`
+2. `OUROBOROS_GROK_CLI_PATH` environment variable
+3. `orchestrator.grok_cli_path` in `~/.ouroboros/config.yaml`
+4. `grok` on `$PATH`
+
+## Configuration
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: grok
+  grok_cli_path: ~/.local/bin/grok    # optional; auto-detected
+```
+
+Grok is **runtime-only** — it drives the agentic orchestrator but is not
+registered as an LLM-completion backend, so it is not a valid `llm.backend`
+value. For completion-level diversity (consensus / role models), route xAI Grok
+through `litellm`/OpenRouter.
+
+### Per-stage routing
+
+Grok is a strong cross-vendor stage in a multi-LLM pipeline — for example, as a
+divergent reflect/unstuck stage distinct from the execute vendor:
+
+```yaml
+orchestrator:
+  runtime_backend: claude
+  runtime_profile:
+    stages:
+      execute: claude      # generate
+      evaluate: gemini     # cross-vendor verify
+      reflect: grok        # divergent lateral thinking
+```
+
+## Headless contract
+
+Each task spawns:
+
+```text
+grok -p <PROMPT> \
+     --output-format streaming-json \
+     --permission-mode acceptEdits \
+     [-m grok-build]
+```
+
+| Flag                  | Why                                                            |
+|-----------------------|----------------------------------------------------------------|
+| `-p`                  | Single-turn prompt; prints the response to stdout and exits    |
+| `--output-format`     | `streaming-json` NDJSON events parsed by the normalizer         |
+| `--permission-mode`   | Native non-blocking mode (`acceptEdits` / `bypassPermissions`)  |
+| `-m`                  | Optional model override (`grok-build`, `grok-composer-2.5-fast`)|
+
+Ouroboros maps its permission modes onto Grok's native `--permission-mode`:
+
+| Ouroboros permission mode | `grok` value        | When used                                |
+|---------------------------|---------------------|------------------------------------------|
+| `acceptEdits` (default)   | `acceptEdits`       | Applies edits without TTY prompts        |
+| `bypassPermissions`       | `bypassPermissions` | Explicit full bypass                     |
+
+The interactive Ouroboros `default` mode is normalized to `acceptEdits` (with an
+audit log) because a headless `grok -p` run cannot service a TTY approval
+prompt.
+
+Grok owns its own model catalog, so it is a **sentinel-model backend**:
+Ouroboros lets Grok pick its configured model and only forwards `-m` when you
+set an explicit id. The settings GUI **dynamically lists** the callable models
+by running `grok models` (parsing its bulleted output), so the picker reflects
+exactly what your Grok CLI / subscription can call; the static fallback catalog
+is `grok-build` and `grok-composer-2.5-fast`.
+
+## Event mapping
+
+The runtime parses Grok's `streaming-json` events through the shared NDJSON
+normalizer and maps them onto Ouroboros' `AgentMessage`:
+
+| Grok event                       | Ouroboros message                       |
+|----------------------------------|-----------------------------------------|
+| `{"type":"thought","data":...}`  | `assistant` with `data.thinking`        |
+| `{"type":"text","data":...}`     | `assistant` message                     |
+| `{"type":"end","stopReason":...}`| **terminal** `assistant` marker (`data.terminal=True`) |
+| `error`                          | `system` message with `data.is_error=True` |
+
+## Capabilities
+
+| Capability               | Status                                                |
+|--------------------------|-------------------------------------------------------|
+| Headless execution       | ✅ `grok -p`                                          |
+| Structured event stream  | ✅ `--output-format streaming-json`                   |
+| Tool calls               | ✅ (Grok-managed via `--permission-mode`)             |
+| Reasoning effort         | `grok --reasoning-effort` exists; native effort routing is a planned follow-up |
+| Session resumption       | ❌ not wired in v1 (`grok -r` exists; recovery at the Ouroboros lineage layer) |
+| LLM-completion backend   | ❌ runtime-only                                       |
+
+## Troubleshooting
+
+**`grok` not found.** Install the Grok Build CLI, then set
+`OUROBOROS_GROK_CLI_PATH=/abs/path/to/grok` or `orchestrator.grok_cli_path`.
+
+**Authentication errors.** Run `grok login` once (SuperGrok / X Premium+), or
+export `XAI_API_KEY` for headless/API-key use.
+
+**The CLI hangs waiting for input.** The runtime always passes `-p` and a
+non-blocking `--permission-mode`. If you see a hang, confirm you are invoking
+the runtime through `ouroboros run` (or the MCP server) rather than driving
+`grok` directly.

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/docs/runtime-guides/skill-capability-guides.md

@@ -42,6 +42,8 @@ its rendered guide or a documented fallback.
 | Kiro | `~/.kiro/steering/ouroboros-skill-capability-guide.md` | Installed by Kiro setup as a global steering file. |
 | Copilot | `~/.copilot/ouroboros-instructions/AGENTS.md` | Installed by Copilot setup; Ouroboros Copilot runtime also injects that directory through `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`. |
 | GJC | `<agent-dir>/rules/ouroboros-skill-capability-guide.md` | Installed by GJC setup as a setup-owned, renderer-generated capability artifact. |
+| Antigravity | No setup-owned capability artifact yet | Known gap: Antigravity (the `agy` binary, Google's Gemini CLI successor) can be selected as a runtime, but setup does not yet install a durable agy-owned instruction artifact. Use `render_backend_skill_capability_guide("antigravity")` when building Antigravity prompts until a stable artifact surface exists. |
+| Grok | No setup-owned capability artifact yet | Known gap: Grok Build (the `grok` binary) can be selected as a runtime, but setup does not yet install a durable grok-owned instruction artifact. Use `render_backend_skill_capability_guide("grok")` when building Grok prompts until a stable artifact surface exists. |
 | Goose | No setup-owned capability artifact yet | Known gap: setup can select Goose as a runtime, but no durable Goose instruction surface or Goose-specific `SkillExecutionCapability` entries are registered yet. Keep skill requirements runtime-neutral and rely on runtime-local operator guidance until a Goose artifact installer exists. |
 | Pi | No setup-owned capability artifact yet | Known gap: Pi has generic rendered capability guidance in the registry, but setup does not yet install it into a durable Pi-owned instruction artifact. Use `render_backend_skill_capability_guide("pi")` when building Pi prompts until a stable artifact surface exists. |
 

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.44.1.dev2'
-__version_tuple__ = version_tuple = (0, 44, 1, 'dev2')
+__version__ = version = '0.44.1.dev4'
+__version_tuple__ = version_tuple = (0, 44, 1, 'dev4')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/backends/capabilities.py

@@ -491,6 +491,41 @@ _CAPABILITIES: tuple[BackendCapability, ...] = (
         supports_tool_envelope=False,
         skill_execution_capabilities=_GENERIC_SKILL_EXECUTION_CAPABILITIES,
     ),
+    BackendCapability(
+        # Antigravity is Google's successor to the Gemini CLI (the ``agy``
+        # binary). Gemini CLI stops serving the Pro/Ultra/free consumer tiers
+        # on 2026-06-18 and migrates those users to Antigravity. Runtime-only:
+        # ``agy -p`` prints a plain-text response (no ``--output-format``), so
+        # it drives the agentic orchestrator runtime but does not back
+        # structured LLM completions or auto-interview answering.
+        name="antigravity",
+        aliases=("agy",),
+        supports_runtime=True,
+        supports_llm=False,
+        supports_interview_driver=False,
+        switchable_runtime=True,
+        cli_name="agy",
+        cli_config_key="antigravity_cli_path",
+        supports_tool_envelope=False,
+        skill_execution_capabilities=_GENERIC_SKILL_EXECUTION_CAPABILITIES,
+    ),
+    BackendCapability(
+        # Grok Build (xAI) — the ``grok`` binary. Runtime-only: ``grok -p
+        # --output-format streaming-json`` drives the agentic orchestrator
+        # runtime. Auth is subscription OAuth (``grok login`` with SuperGrok /
+        # X Premium+) or ``XAI_API_KEY``. Grok owns its own model catalog
+        # (``grok models``), so it is a sentinel-model backend.
+        name="grok",
+        aliases=("grok_cli", "grok_build"),
+        supports_runtime=True,
+        supports_llm=False,
+        supports_interview_driver=False,
+        switchable_runtime=True,
+        cli_name="grok",
+        cli_config_key="grok_cli_path",
+        supports_tool_envelope=False,
+        skill_execution_capabilities=_GENERIC_SKILL_EXECUTION_CAPABILITIES,
+    ),
     BackendCapability(
         # ourocode is an LLM-completion backend only: it streams a single Claude
         # turn over ACP (`ourocode --acp`, its OAuth `:claude_api`) with no tool

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/backends/model_catalog.py

@@ -21,6 +21,7 @@ because ``opencode models`` has been verified; other backends degrade to
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 import shutil
@@ -36,7 +37,7 @@ from ouroboros.config._model_defaults import DEFAULT_OPUS_MODEL, DEFAULT_SONNET_
 # than a Claude model id. Mirrors the loader's sentinel frozensets
 # (_CODEX_LLM_BACKENDS et al.); the mirror is locked by a unit test.
 _SENTINEL_MODEL_BACKENDS = frozenset(
-    {"codex", "opencode", "kiro", "copilot", "hermes", "pi", "gjc"}
+    {"codex", "opencode", "kiro", "copilot", "hermes", "pi", "gjc", "antigravity", "grok"}
 )
 
 # The sentinel the loader maps Claude-incapable backends to.
@@ -78,11 +79,63 @@ class BackendModelCatalog:
 _EXTRA_KNOWN_MODELS: dict[str, tuple[str, ...]] = {
     "claude": ("claude-haiku-4-5-20251001",),
     "codex": ("gpt-5-codex", "gpt-5", "gpt-5-mini"),
+    # Grok Build model slugs, after the CLI-owned "default" sentinel. Verified
+    # against a live `grok models` listing (grok-build, grok-composer-2.5-fast).
+    "grok": ("grok-build", "grok-composer-2.5-fast"),
 }
 
-# Verified model-listing subcommands (one model id per line on stdout).
+# Verified model-listing subcommands. The resolved backend binary is invoked
+# with these args and the stdout is parsed by the backend's entry in
+# `_LIST_PARSERS` (default: one model id per line).
 _LIST_ARGS: dict[str, tuple[str, ...]] = {
     "opencode": ("models",),
+    "grok": ("models",),
+}
+
+
+def _parse_models_one_per_line(stdout: str) -> tuple[str, ...]:
+    """Default listing parser: one model id per non-blank line."""
+    return tuple(line.strip() for line in stdout.splitlines() if line.strip())
+
+
+def _parse_grok_models(stdout: str) -> tuple[str, ...]:
+    """Parse ``grok models`` output into callable model ids.
+
+    Grok prints auth / default-model headers and a bulleted "Available models"
+    list rather than one id per line, e.g.::
+
+        You are logged in with grok.com.
+
+        Default model: grok-composer-2.5-fast
+
+        Available models:
+          - grok-build
+          * grok-composer-2.5-fast (default)
+
+    Extract the bulleted ids (dropping the ``-``/``*`` bullet and any trailing
+    ``(default)`` marker), preserving order and de-duplicating, so the catalog
+    reflects exactly what the user's Grok CLI can call.
+    """
+    models: list[str] = []
+    in_list = False
+    for line in stdout.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.lower().startswith("available models"):
+            in_list = True
+            continue
+        if in_list and stripped[0] in "-*":
+            parts = stripped[1:].strip().split()
+            if parts:
+                models.append(parts[0])
+    return tuple(dict.fromkeys(models))
+
+
+# Backend-specific stdout parsers for `refresh_models`. Backends absent here use
+# `_parse_models_one_per_line`.
+_LIST_PARSERS: dict[str, Callable[[str], tuple[str, ...]]] = {
+    "grok": _parse_grok_models,
 }
 
 
@@ -166,7 +219,8 @@ def refresh_models(
         )
     except (OSError, subprocess.SubprocessError):
         return None
-    models = tuple(line.strip() for line in result.stdout.splitlines() if line.strip())
+    parser = _LIST_PARSERS.get(catalog.backend, _parse_models_one_per_line)
+    models = parser(result.stdout)
     return models or None
 
 
@@ -183,6 +237,8 @@ _CLI_PATH_GETTERS: dict[str, str] = {
     "goose": "get_goose_cli_path",
     "pi": "get_pi_cli_path",
     "gjc": "get_gjc_cli_path",
+    "antigravity": "get_antigravity_cli_path",
+    "grok": "get_grok_cli_path",
     "ourocode": "get_ourocode_cli_path",
 }
 

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/auto.py

@@ -109,6 +109,8 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     KIRO = "kiro"
     PI = "pi"
     GJC = "gjc"
+    ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 app = typer.Typer(

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/config.py

@@ -462,6 +462,14 @@ def backend(
         from ouroboros.config import get_pi_cli_path
 
         cli_path = get_pi_cli_path()
+    elif new_backend == "antigravity":
+        from ouroboros.config import get_antigravity_cli_path
+
+        cli_path = get_antigravity_cli_path()
+    elif new_backend == "grok":
+        from ouroboros.config import get_grok_cli_path
+
+        cli_path = get_grok_cli_path()
     if not cli_path:
         cli_path = shutil.which(cli_name)
     if not cli_path:
@@ -500,11 +508,13 @@ def backend(
     # print_error to set a flag.
     from ouroboros.cli.commands import setup as setup_mod
     from ouroboros.cli.commands.setup import (
+        _setup_antigravity,
         _setup_claude,
         _setup_codex,
         _setup_gemini,
         _setup_gjc,
         _setup_goose,
+        _setup_grok,
         _setup_hermes,
         _setup_pi,
     )
@@ -536,6 +546,10 @@ def backend(
             _setup_goose(cli_path)
         elif new_backend == "pi":
             _setup_pi(cli_path)
+        elif new_backend == "antigravity":
+            _setup_antigravity(cli_path)
+        elif new_backend == "grok":
+            _setup_grok(cli_path)
     except Exception as exc:
         setup_failed = True
         console.quiet = prev_quiet

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/init.py

@@ -72,6 +72,8 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     COPILOT = "copilot"
     PI = "pi"
     GJC = "gjc"
+    ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/mcp.py

@@ -71,6 +71,8 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     GOOSE = "goose"
     PI = "pi"
     GJC = "gjc"
+    ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042

{ouroboros_ai-0.44.1.dev2 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/run.py

@@ -122,6 +122,8 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     KIRO = "kiro"
     PI = "pi"
     GJC = "gjc"
+    ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 def _derive_quality_bar(seed: "Seed") -> str: