superqode 0.2.7__tar.gz → 0.2.9__tar.gz

{superqode-0.2.7 → superqode-0.2.9}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.9] - 2026-07-09
+
+### Added
+
+- **Grok subscription profile (`:connect grok`)** - New connection profile that runs xAI's official Grok Build coding agent through its native ACP server (`grok agent stdio`) on an eligible SuperGrok/X Premium+ account. Includes agent-registry and discovery entries, a `:grok` command surface (`connect`, `status`, `login`, `help`), completion/suggestion wiring, and docs across the provider, CLI-reference, connection-profiles, and TUI pages.
+- **Opt-in direct API on the Grok subscription (`:grok api`)** - Explicitly imports the local `grok login` session token into SuperQode's 0600 auth store and connects the new `grok-cli` provider against the CLI chat proxy xAI documents (`https://cli-chat-proxy.grok.com/v1`), sending the required `X-XAI-Token-Auth` and `x-grok-model-override` headers. `:grok api off` removes the token; `:grok status` reports token state. The default ACP path still never reads the CLI's credentials.
+- **Grok 4.5 in the xAI BYOK catalog** - Added `grok-4.5` (500K context, reasoning efforts, vision), `grok-4.3` (1M context), and `grok-build-0.1` with current pricing; refreshed registry example models, base URL, and docs links.
+- **`ProviderDef.extra_headers`** - Curated providers can now declare required HTTP headers (with a `{model}` placeholder) applied per-request by the LiteLLM gateway, and can opt into per-request `api_base`/`api_key` routing without env mutation.
+
+### Fixed
+
+- **Stale models.dev cache hiding new models** - A months-old on-disk models.dev cache no longer replaces newer curated builtin model lists (it previously hid day-one models like `grok-4.5` and mispriced lookups via fuzzy matching). Live provider lists now only override builtins when they are at least as new by release date.
+- **Retired xAI models removed** - Dropped `grok-3`, `grok-3-mini`, `grok-2`, and `grok-beta` from the BYOK pickers to match xAI's current catalog; video-generation models are now excluded from chat model lists.
+
+### Changed
+
+- **Release metadata** - Bumped the package version, runtime `__version__`, lockfile package entry, and ACP registry metadata to `0.2.9`.
+
+## [0.2.8] - 2026-07-07
+
+### Added
+
+- **Self-improving harness loop** - Added `harness mine-failures`, `harness logbook`, and `harness improve` workflows for mining failures, maintaining repo-local harness memory, exporting bounded improvement projects, and feeding evidence into candidate generation.
+- **Candidate audit and ledger** - Added `harness audit-candidate` plus `harness candidates list/show/export` to record accepted and rejected harness candidates, detect protected-surface edits, permission widening, weakened checks, duplicate rejected edits, and missing held-out gates.
+- **Held-in / held-out eval splits** - Added split-aware eval tasks and `harness eval --split {all,held-in,held-out}` so candidate improvements can be gated separately from training/proposal tasks.
+- **Harness usage metrics** - Harness runs and eval scorecards now aggregate token, latency, and cost metrics where providers expose them.
+- **Self-improvement docs** - Documented the end-to-end loop, optimization policy fields, candidate audit gates, candidate ledger, and logbook pruning.
+
+### Changed
+
+- **Release metadata** - Bumped the package version, runtime `__version__`, lockfile package entry, and ACP registry metadata to `0.2.8`.
+
 ## [0.2.7] - 2026-07-05
 
 ### Fixed

{superqode-0.2.7/src/superqode.egg-info → superqode-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.7
+Version: 0.2.9
 Summary: SuperQode: harness engineering framework for coding agents, optimized for local and open models
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -356,6 +356,7 @@ Inside the TUI, start with `:help` and these commands:
 :connect codex        # Codex SDK with local Codex login
 :connect claude       # Claude Code through ACP
 :connect antigravity  # local Antigravity CLI handoff
+:connect grok         # Grok Build via the official Grok CLI (subscription)
 :connect byok         # hosted provider/API-key path
 :connect local        # local model provider
 :tree                 # saved session branches

{superqode-0.2.7 → superqode-0.2.9}/README.md

@@ -228,6 +228,7 @@ Inside the TUI, start with `:help` and these commands:
 :connect codex        # Codex SDK with local Codex login
 :connect claude       # Claude Code through ACP
 :connect antigravity  # local Antigravity CLI handoff
+:connect grok         # Grok Build via the official Grok CLI (subscription)
 :connect byok         # hosted provider/API-key path
 :connect local        # local model provider
 :tree                 # saved session branches

{superqode-0.2.7 → superqode-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "0.2.7"
+version = "0.2.9"
 description = "SuperQode: harness engineering framework for coding agents, optimized for local and open models"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/acp/server.py

@@ -46,6 +46,7 @@ from acp.schema import (
     PermissionOption,
     PromptCapabilities,
     TerminalAuthMethod,
+    ToolCallLocation,
     ToolCallUpdate,
 )
 
@@ -98,6 +99,74 @@ def _tool_kind(name: str) -> str:
     return "other"
 
 
+# Argument keys that carry the tool's target, by role. Cover both snake_case and
+# camelCase spellings since specs and external runtimes disagree on convention.
+_PATH_ARG_KEYS = ("file_path", "filePath", "path", "file", "abs_path", "filename", "target_file")
+_COMMAND_ARG_KEYS = ("command", "cmd", "script")
+_PATTERN_ARG_KEYS = ("pattern", "query", "regex", "search")
+_URL_ARG_KEYS = ("url", "uri")
+
+_TITLE_LIMIT = 120
+
+
+def _first_str(args: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = args.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def _clip_title(text: str) -> str:
+    text = " ".join(text.split())
+    if len(text) <= _TITLE_LIMIT:
+        return text
+    return text[: _TITLE_LIMIT - 1] + "…"
+
+
+def _tool_title(name: str, arguments: Any) -> str:
+    """Human-readable tool_call title: verb + target, not just the tool name.
+
+    Editors surface ``title`` directly (Zed, JetBrains) while ``raw_input`` is
+    hidden behind an expander, so the file path / command must be in the title.
+    """
+    args = arguments if isinstance(arguments, dict) else {}
+    kind = _tool_kind(name)
+    path = _first_str(args, _PATH_ARG_KEYS)
+    if kind == "execute":
+        command = _first_str(args, _COMMAND_ARG_KEYS)
+        return _clip_title(command) if command else name
+    if kind == "read" and path:
+        return _clip_title(f"Read {path}")
+    if kind == "edit" and path:
+        verb = "Write" if "write" in name.lower() or "create" in name.lower() else "Edit"
+        return _clip_title(f"{verb} {path}")
+    if kind == "search":
+        pattern = _first_str(args, _PATTERN_ARG_KEYS)
+        if pattern:
+            return _clip_title(f"Search {pattern}" + (f" in {path}" if path else ""))
+    if kind == "fetch":
+        url = _first_str(args, _URL_ARG_KEYS)
+        if url:
+            return _clip_title(f"Fetch {url}")
+    if path:
+        return _clip_title(f"{name} {path}")
+    return name
+
+
+def _tool_locations(arguments: Any) -> list[ToolCallLocation] | None:
+    """File locations for follow-the-agent UIs, when the arguments name a path."""
+    args = arguments if isinstance(arguments, dict) else {}
+    path = _first_str(args, _PATH_ARG_KEYS)
+    if not path:
+        return None
+    location = ToolCallLocation(path=path)
+    line = args.get("line") or args.get("start_line") or args.get("offset")
+    if isinstance(line, int) and line > 0:
+        location.line = line
+    return [location]
+
+
 def _prompt_to_text(blocks: list[Any] | None) -> str:
     """Flatten ACP prompt content blocks into one harness prompt string."""
     parts: list[str] = []
@@ -430,32 +499,55 @@ class SuperQodeAcpAgent:
                 await self._send_update(session_id, update_agent_thought_text(text))
         elif event_type == "tool_call":
             name = str(data.get("tool_name") or "tool")
+            arguments = data.get("arguments")
             call_id = tracker.start(name)
             await self._send_update(
                 session_id,
                 start_tool_call(
                     call_id,
-                    name,
+                    _tool_title(name, arguments),
                     kind=_tool_kind(name),
                     status="in_progress",
-                    raw_input=data.get("arguments"),
+                    locations=_tool_locations(arguments),
+                    raw_input=arguments,
                 ),
             )
         elif event_type == "tool_result":
             name = str(data.get("tool_name") or "tool")
             call_id = tracker.finish(name)
-            if call_id is None:
-                return
             success = data.get("success", True)
             output = data.get("output") if success else (data.get("error") or data.get("output"))
             content = []
             if output:
                 content.append(tool_content(text_block(_clip(output))))
+            status = "completed" if success else "failed"
+            if call_id is None:
+                # Runtimes like codex-sdk report tools only on completion; synthesize
+                # the tool_call rather than dropping the result on the floor.
+                arguments = data.get("arguments") or {
+                    key: data[key] for key in ("command", "path") if data.get(key)
+                }
+                call_id = tracker.start(name)
+                tracker.finish(name)
+                await self._send_update(
+                    session_id,
+                    start_tool_call(
+                        call_id,
+                        _tool_title(name, arguments),
+                        kind=_tool_kind(name),
+                        status=status,
+                        locations=_tool_locations(arguments),
+                        raw_input=arguments or None,
+                        content=content or None,
+                        raw_output=output,
+                    ),
+                )
+                return
             await self._send_update(
                 session_id,
                 update_tool_call(
                     call_id,
-                    status="completed" if success else "failed",
+                    status=status,
                     content=content or None,
                     raw_output=output,
                 ),
@@ -472,6 +564,7 @@ class SuperQodeAcpAgent:
                 return True
             item = dict(pending[0])
             tool_name = str(item.get("tool_name") or "tool")
+            arguments = item.get("arguments")
             call_id = str(item.get("tool_call_id") or tracker.start(tool_name))
             response = await self._conn.request_permission(
                 options=[
@@ -484,10 +577,11 @@ class SuperQodeAcpAgent:
                 session_id=session.session_id,
                 tool_call=ToolCallUpdate(
                     tool_call_id=call_id,
-                    title=tool_name,
+                    title=_tool_title(tool_name, arguments),
                     kind=_tool_kind(tool_name),
                     status="pending",
-                    raw_input=item.get("arguments"),
+                    locations=_tool_locations(arguments),
+                    raw_input=arguments,
                 ),
             )
             outcome = getattr(response, "outcome", None)

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/acp_discovery.py

@@ -212,6 +212,21 @@ KNOWN_AGENTS: List[Dict[str, Any]] = [
         "check_command": ["codex", "--version"],
     },
     # =========================================================================
+    # Grok Build - xAI's official CLI with native ACP support
+    # =========================================================================
+    {
+        "name": "Grok Build",
+        "short_name": "grok",
+        "command": ["grok", "agent", "stdio"],
+        "icon": "G",
+        "color": "#e5e7eb",
+        "description": "xAI's official Grok Build coding agent with native ACP support",
+        "website": "https://x.ai/cli",
+        "requires_api_key": False,
+        "api_key_env_vars": ["XAI_API_KEY", "GROK_CODE_XAI_API_KEY"],
+        "check_command": ["grok", "--version"],
+    },
+    # =========================================================================
     # 4. JetBrains Junie - JetBrains AI Agent
     # =========================================================================
     {
@@ -659,6 +674,39 @@ class ACPDiscovery:
                     id="gpt-4o", name="GPT-4o", provider="openai", description="Multimodal GPT"
                 ),
             ],
+            # Grok Build follows the signed-in account's current default. The
+            # bare "grok-build" id is the CLI's own default-model alias; the
+            # rest are real xAI model ids a user can pin explicitly.
+            "grok": [
+                AgentModel(
+                    id="grok-build",
+                    name="Grok Build (account default)",
+                    provider="xai",
+                    description="Official Grok Build default alias, currently Grok 4.5",
+                    context_window=500000,
+                ),
+                AgentModel(
+                    id="grok-4.5",
+                    name="Grok 4.5",
+                    provider="xai",
+                    description="xAI's flagship model for agentic coding and reasoning",
+                    context_window=500000,
+                ),
+                AgentModel(
+                    id="grok-build-0.1",
+                    name="Grok Build 0.1",
+                    provider="xai",
+                    description="Fast coding model tuned for agentic engineering loops",
+                    context_window=256000,
+                ),
+                AgentModel(
+                    id="grok-4.3",
+                    name="Grok 4.3",
+                    provider="xai",
+                    description="1M-context Grok for document-heavy work",
+                    context_window=1000000,
+                ),
+            ],
             # JetBrains Junie
             "junie": [
                 AgentModel(id="auto", name="Auto", description="Automatic model selection"),

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/agent/loop.py

@@ -605,6 +605,11 @@ class AgentResponse:
     # and any schema-validation errors (empty list means valid).
     structured_output: Optional[Any] = None
     schema_errors: Optional[List[str]] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    cost_usd: Optional[float] = None
+    cost_currency: Optional[str] = None
 
 
 class ToolApprovalRequired(RuntimeError):
@@ -1991,8 +1996,60 @@ class AgentLoop:
         from .hooks import SESSION_START, STOP, USER_PROMPT_SUBMIT
 
         lifecycle_ctx = self._lifecycle_context()
+        usage_input_tokens = 0
+        usage_output_tokens = 0
+        usage_total_tokens = 0
+        usage_cost = 0.0
+        usage_seen = False
+        cost_seen = False
+        cost_currency = "USD"
+
+        def _record_gateway_usage(gateway_response) -> None:
+            nonlocal usage_input_tokens
+            nonlocal usage_output_tokens
+            nonlocal usage_total_tokens
+            nonlocal usage_cost
+            nonlocal usage_seen
+            nonlocal cost_seen
+            nonlocal cost_currency
+            usage = getattr(gateway_response, "usage", None)
+            if usage is not None:
+                prompt_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+                completion_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+                total_tokens = int(getattr(usage, "total_tokens", 0) or 0)
+                if total_tokens <= 0:
+                    total_tokens = prompt_tokens + completion_tokens
+                usage_input_tokens += prompt_tokens
+                usage_output_tokens += completion_tokens
+                usage_total_tokens += total_tokens
+                usage_seen = True
+            cost = getattr(gateway_response, "cost", None)
+            if cost is not None:
+                input_cost = float(getattr(cost, "input_cost", 0.0) or 0.0)
+                output_cost = float(getattr(cost, "output_cost", 0.0) or 0.0)
+                total_cost = float(getattr(cost, "total_cost", 0.0) or 0.0)
+                if total_cost == 0.0 and (input_cost or output_cost):
+                    total_cost = input_cost + output_cost
+                usage_cost += total_cost
+                cost_currency = str(getattr(cost, "currency", None) or cost_currency or "USD")
+                cost_seen = True
 
         async def _finish(response: AgentResponse) -> AgentResponse:
+            if usage_seen:
+                response.input_tokens = (
+                    usage_input_tokens if response.input_tokens is None else response.input_tokens
+                )
+                response.output_tokens = (
+                    usage_output_tokens if response.output_tokens is None else response.output_tokens
+                )
+                response.total_tokens = (
+                    usage_total_tokens if response.total_tokens is None else response.total_tokens
+                )
+            if cost_seen:
+                response.cost_usd = usage_cost if response.cost_usd is None else response.cost_usd
+                response.cost_currency = (
+                    cost_currency if response.cost_currency is None else response.cost_currency
+                )
             self.run_active = False
             await self.hooks.fire(STOP, self._lifecycle_context(), response)
             # Opt-in automatic memory extraction, off the hot path.
@@ -2156,6 +2213,7 @@ class AgentLoop:
                         error=str(e),
                     )
                 )
+            _record_gateway_usage(response)
             await self.hooks.fire(AFTER_LLM_CALL, lifecycle_ctx, response)
 
             # Extract thinking content if available

superqode-0.2.9/src/superqode/agents/data/x.ai.toml

@@ -0,0 +1,81 @@
+# Official Grok CLI agent entry.
+# https://x.ai/cli
+
+identity = "x.ai"
+name = "Grok Build"
+short_name = "grok"
+url = "https://x.ai/cli"
+protocol = "acp"
+author_name = "xAI"
+author_url = "https://x.ai"
+publisher_name = "SuperQode"
+publisher_url = "https://github.com/SuperagenticAI/superqode"
+type = "coding"
+description = "xAI's official Grok Build coding agent, connected through its native ACP server."
+tags = ["xai", "grok", "subscription", "byok", "acp"]
+run_command."*" = "grok agent stdio"
+api_key_env_vars = ["XAI_API_KEY", "GROK_CODE_XAI_API_KEY"]
+
+help = '''
+# Grok Build
+
+Grok Build is xAI's official coding agent. SuperQode starts its native ACP server with:
+
+```bash
+grok agent stdio
+```
+
+## Install
+
+```bash
+# macOS / Linux / WSL
+curl -fsSL https://x.ai/cli/install.sh | bash
+
+# Windows PowerShell
+irm https://x.ai/cli/install.ps1 | iex
+```
+
+## Subscription login
+
+Grok Build is available to eligible SuperGrok and X Premium+ accounts.
+Authenticate the official CLI before connecting:
+
+```bash
+grok login
+```
+
+For an SSH or headless machine, use device authentication:
+
+```bash
+grok login --device-auth
+```
+
+Then connect in SuperQode with `:connect grok` or `superqode --connect grok`.
+The official CLI keeps subscription credentials locally (`~/.grok/auth.json`);
+SuperQode does not copy the token. Eligibility and available models are
+determined by xAI for the signed-in account.
+
+## Models
+
+Grok Build defaults to its `grok-build` alias (currently Grok 4.5). Pin a
+specific model from SuperQode with `:grok connect grok-4.5` or
+`:grok connect grok-build-0.1`; the hint is forwarded through ACP.
+
+## Direct API on your subscription (opt-in)
+
+`:grok api [model]` imports the local `grok login` session token into
+SuperQode's own auth store and connects the `grok-cli` provider against the
+CLI chat proxy documented by xAI. Remove it anytime with `:grok api off`.
+CLI sessions last about 7 days; re-run `grok login` when they expire.
+
+## BYOK
+
+For direct xAI API usage, set `XAI_API_KEY` and connect `xai/grok-4.5` through
+the BYOK provider picker. API usage is billed separately from a consumer
+subscription. The CLI itself also accepts `GROK_CODE_XAI_API_KEY` for
+headless, key-based runs.
+'''
+
+[actions."*".install]
+command = "curl -fsSL https://x.ai/cli/install.sh | bash"
+description = "Install the official Grok CLI"

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/app/constants.py

@@ -141,6 +141,7 @@ AGENT_COLORS = {
     "claude": "#d97706",  # Anthropic Orange
     "claude-code": "#d97706",  # Anthropic Orange
     "codex": "#10b981",  # Green
+    "grok": "#e5e7eb",  # xAI neutral, readable on the dark TUI
     "junie": "#fe315d",  # JetBrains Pink
     "goose": "#8b5cf6",  # Block Purple
     "kimi": "#5b21b6",  # Moonshot Deep Purple
@@ -162,6 +163,7 @@ AGENT_ICONS = {
     "claude": "🧡",  # Orange heart - Anthropic's warm AI
     "claude-code": "🧡",  # Orange heart - Anthropic's warm AI
     "codex": "📜",  # Scroll
+    "grok": "G",  # Grok Build
     "junie": "🧠",  # Brain - JetBrains intelligence
     "goose": "🦆",  # Duck - Block's Goose
     "kimi": "🌙",  # Moon - Moonshot AI's Kimi
@@ -251,6 +253,7 @@ COMMANDS = [
     ":connect codex",
     ":connect claude",
     ":connect antigravity",
+    ":connect grok",
     ":connect byok",
     ":connect local",
     ":connect acp",
@@ -266,6 +269,10 @@ COMMANDS = [
     ":antigravity migrate",
     ":antigravity launch",
     ":agy",
+    ":grok",
+    ":grok status",
+    ":grok login",
+    ":grok api",
     ":exit",
     ":quit",
     ":help",
@@ -371,6 +378,7 @@ COMMANDS = [
     ":serve web",
     ":serve harness",
     ":serve api",
+    ":serve acp",
     ":profiles",
     ":profiles list",
     ":doctor",
@@ -587,6 +595,18 @@ COMMANDS = [
     ":harness observability",
     ":harness observability status",
     ":harness observability export",
+    ":harness mine-failures",
+    ":harness logbook",
+    ":harness logbook update",
+    ":harness logbook show",
+    ":harness logbook export",
+    ":harness logbook prune",
+    ":harness audit-candidate",
+    ":harness candidates",
+    ":harness candidates list",
+    ":harness candidates show",
+    ":harness candidates export",
+    ":harness improve",
     ":harness optimize",
     ":harness optimize-inspect",
     ":harness optimize-ledger",

{superqode-0.2.7 → superqode-0.2.9}/src/superqode/app/suggester.py

@@ -71,25 +71,28 @@ class CommandSuggester(Suggester):
                 ":connect": 0,
                 ":connect acp": 1,
                 ":connect antigravity": 2,
-                ":connect byok": 3,
-                ":connect local": 4,
-                ":exit": 5,
-                ":quit": 6,
+                ":connect grok": 3,
+                ":connect byok": 4,
+                ":connect local": 5,
+                ":exit": 6,
+                ":quit": 7,
             },
             ":c": {
                 ":connect": 0,
                 ":connect acp": 1,
                 ":connect antigravity": 2,
-                ":connect byok": 3,
-                ":connect local": 4,
+                ":connect grok": 3,
+                ":connect byok": 4,
+                ":connect local": 5,
                 ":clear": 20,
             },
             ":co": {
                 ":connect": 0,
                 ":connect acp": 1,
                 ":connect antigravity": 2,
-                ":connect byok": 3,
-                ":connect local": 4,
+                ":connect grok": 3,
+                ":connect byok": 4,
+                ":connect local": 5,
             },
             ":q": {
                 ":quit": 0,