spawnllm 0.4.0__tar.gz → 0.5.0__tar.gz

{spawnllm-0.4.0 → spawnllm-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.4.0
+Version: 0.5.0
 Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -64,24 +64,13 @@ domain logic instead of its own copy of the backends.
 
 ## Install
 
-No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+Run the CLI with [uvx](https://docs.astral.sh/uv/):
 
 ```bash
 uvx spawnllm --help
 ```
 
-`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
-to a project instead:
-
-```bash
-uv add spawnllm
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra:
-
-```bash
-uv add "spawnllm[mlx]"
-```
+For the local MLX engine (Apple Silicon only), pull the extra: `uv add "spawnllm[mlx]"`.
 
 ## Quickstart
 
@@ -107,9 +96,9 @@ uvx spawnllm call --backend claude "What is 2+2? Reply with just the number."
 4
 ```
 
-`--model small|medium|large` swaps the tier, which each backend maps to a concrete model.
-The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
-`--agent` to let the call use tools.
+`--model small|medium|large` swaps the tier, which each backend maps to a concrete model — the
+`claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
+`--agent` to let the call use tools. Run `uvx spawnllm --help` for the full flag list.
 
 ### From Python
 
@@ -171,21 +160,14 @@ result = run_sync(
 print(result.stdout)  # 4
 ```
 
-## What problems does this solve?
-
-Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv
-construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful
-errors. spawnllm holds it once.
-
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
-
-Local MLX is fiddly. Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
-batched single-token generation live behind one engine instead of in every consumer.
+## How it works
 
-Behavior drift goes away with the duplication: two tools that call the same models stay
-byte-for-byte consistent because they share the backend layer, not a pair of diverging
-copies.
+Each backend holds plumbing that consumers would otherwise rebuild: the CLI backends own argv
+construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful errors,
+and they turn a Pydantic model into a JSON-schema constraint plus a parsed, validated result. The
+MLX engine wraps adapter fusion, prompt-cache reuse, worker-thread lifecycle, and batched
+single-token generation. Tools that share the layer stay byte-for-byte consistent instead of
+drifting across diverging copies.
 
 ## Docs
 

{spawnllm-0.4.0 → spawnllm-0.5.0}/README.md

@@ -17,24 +17,13 @@ domain logic instead of its own copy of the backends.
 
 ## Install
 
-No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+Run the CLI with [uvx](https://docs.astral.sh/uv/):
 
 ```bash
 uvx spawnllm --help
 ```
 
-`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
-to a project instead:
-
-```bash
-uv add spawnllm
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra:
-
-```bash
-uv add "spawnllm[mlx]"
-```
+For the local MLX engine (Apple Silicon only), pull the extra: `uv add "spawnllm[mlx]"`.
 
 ## Quickstart
 
@@ -60,9 +49,9 @@ uvx spawnllm call --backend claude "What is 2+2? Reply with just the number."
 4
 ```
 
-`--model small|medium|large` swaps the tier, which each backend maps to a concrete model.
-The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
-`--agent` to let the call use tools.
+`--model small|medium|large` swaps the tier, which each backend maps to a concrete model — the
+`claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
+`--agent` to let the call use tools. Run `uvx spawnllm --help` for the full flag list.
 
 ### From Python
 
@@ -124,21 +113,14 @@ result = run_sync(
 print(result.stdout)  # 4
 ```
 
-## What problems does this solve?
-
-Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv
-construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful
-errors. spawnllm holds it once.
-
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
-
-Local MLX is fiddly. Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
-batched single-token generation live behind one engine instead of in every consumer.
+## How it works
 
-Behavior drift goes away with the duplication: two tools that call the same models stay
-byte-for-byte consistent because they share the backend layer, not a pair of diverging
-copies.
+Each backend holds plumbing that consumers would otherwise rebuild: the CLI backends own argv
+construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful errors,
+and they turn a Pydantic model into a JSON-schema constraint plus a parsed, validated result. The
+MLX engine wraps adapter fusion, prompt-cache reuse, worker-thread lifecycle, and batched
+single-token generation. Tools that share the layer stay byte-for-byte consistent instead of
+drifting across diverging copies.
 
 ## Docs
 

{spawnllm-0.4.0 → spawnllm-0.5.0}/pyproject.toml

@@ -1,6 +1,7 @@
 [project]
 name = "spawnllm"
-version = "0.4.0"
+# Inert sentinel: the real version is set from the release tag (uv version --frozen).
+version = "0.5.0"
 description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
 readme = "README.md"
 license = "MIT"

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/__init__.py

@@ -1,14 +1,17 @@
 """Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 
-The top-level namespace exposes the CLI backends, subprocess transport, and
-structured-output helpers. The MLX engine lives under `spawnllm.mlx`, whose
-imports are lazy so that `import spawnllm` never pulls `mlx_lm`/`zstandard`.
+The top-level namespace exposes the three primitives — `run`/`call`/`extract`
+and their `_sync` companions — over a `Backend` family that fully encapsulates
+execution and returns one shared `Response`. The MLX engine lives under
+`spawnllm.mlx`, whose imports are lazy so that `import spawnllm` never pulls
+`mlx_lm`/`zstandard`.
 """
 
 from __future__ import annotations
 
 from spawnllm.backends import (
     AntigravityCliBackend,
+    BackendCallError,
     BackendNotAuthenticated,
     BackendNotInstalled,
     BackendReady,
@@ -18,26 +21,21 @@ from spawnllm.backends import (
     CliBackend,
     CodexCliBackend,
     GeminiCliBackend,
-    Invocation,
     LlmBackend,
     LlmBackends,
     MlxBackend,
     select_backend,
 )
 from spawnllm.call import call, call_sync
-from spawnllm.proc import RunResult, arun_cli, collect_process, map_concurrent, run_cli
+from spawnllm.extract import extract, extract_sync
+from spawnllm.response import Response
 from spawnllm.run import run, run_sync
 from spawnllm.spec import ClaudeConfig, CodexConfig, GeminiConfig, RunSpec
-from spawnllm.structured import (
-    extract_structured,
-    parse_result_envelope,
-    parse_structured_output,
-    resolve_schema_path,
-)
 from spawnllm.types import ProviderName, TModel, TSpecialty
 
 __all__ = [
     "AntigravityCliBackend",
+    "BackendCallError",
     "BackendNotAuthenticated",
     "BackendNotInstalled",
     "BackendReady",
@@ -50,26 +48,19 @@ __all__ = [
     "CodexConfig",
     "GeminiCliBackend",
     "GeminiConfig",
-    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",
     "ProviderName",
-    "RunResult",
+    "Response",
     "RunSpec",
     "TModel",
     "TSpecialty",
-    "arun_cli",
     "call",
     "call_sync",
-    "collect_process",
-    "extract_structured",
-    "map_concurrent",
-    "parse_result_envelope",
-    "parse_structured_output",
-    "resolve_schema_path",
+    "extract",
+    "extract_sync",
     "run",
-    "run_cli",
     "run_sync",
     "select_backend",
 ]

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/backends/__init__.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from spawnllm.backends.base import (
+    BackendCallError,
     BackendNotAuthenticated,
     BackendNotInstalled,
     BackendReady,
     BackendStatus,
     BackendUnavailable,
     CliBackend,
-    Invocation,
     LlmBackend,
 )
 from spawnllm.backends.claude import ClaudeCliBackend
@@ -20,6 +20,7 @@ from spawnllm.backends.registry import LlmBackends, select_backend
 
 __all__ = [
     "AntigravityCliBackend",
+    "BackendCallError",
     "BackendNotAuthenticated",
     "BackendNotInstalled",
     "BackendReady",
@@ -29,7 +30,6 @@ __all__ = [
     "CliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
-    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/backends/base.py

@@ -10,7 +10,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar
 
-from spawnllm.proc import RunResult, acapture_cli, capture_cli
+from spawnllm.proc import acapture_cli, capture_cli
+from spawnllm.response import Response
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -62,6 +63,18 @@ class BackendUnavailable(RuntimeError):
     """Raised when no backend is ready (installed and authenticated)."""
 
 
+class BackendCallError(RuntimeError):
+    """Raised by `call`/`extract` when a backend returns a provider error.
+
+    Carries the backend's error string (a nonzero exit with stderr, or an error
+    envelope), attached both as the message and as a note for tracebacks.
+    """
+
+    def __init__(self, error: str) -> None:
+        super().__init__(error)
+        self.add_note(error)
+
+
 @dataclass(frozen=True)
 class Invocation:
     """A built CLI invocation: argv, optional stdin, and where to read the result.
@@ -95,37 +108,28 @@ class LlmBackend(ABC):
     provider: ClassVar[ProviderName]
 
     @abstractmethod
-    async def aexecute(self, spec: RunSpec) -> RunResult:
-        """Execute a single run asynchronously and capture its raw outcome.
-
-        Args:
-            spec: The configured run to execute.
-
-        Returns:
-            The captured stdout, stderr, and exit code.
-        """
+    async def aexecute(self, spec: RunSpec) -> Response:
+        """Execute a single run asynchronously and resolve it to a `Response`.
 
-    @abstractmethod
-    def execute(self, spec: RunSpec) -> RunResult:
-        """Execute a single run synchronously and capture its raw outcome.
+        The backend runs the process, reads its output wherever the provider
+        writes it, detects failure, and validates against `spec.response_model`.
 
         Args:
             spec: The configured run to execute.
 
         Returns:
-            The captured stdout, stderr, and exit code.
+            The resolved `Response`.
         """
 
     @abstractmethod
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse raw stdout into text or a validated model.
+    def execute(self, spec: RunSpec) -> Response:
+        """Execute a single run synchronously and resolve it to a `Response`.
 
         Args:
-            raw: Raw stdout from the backend.
-            response_model: Model to validate against, or `None` for raw text.
+            spec: The configured run to execute.
 
         Returns:
-            `raw` when `response_model` is `None`, else a validated instance.
+            The resolved `Response`.
         """
 
     @abstractmethod
@@ -172,6 +176,49 @@ class LlmBackend(ABC):
         """
         return json.dumps(model.model_json_schema())
 
+    def schema_arg(self, spec: RunSpec) -> str | None:
+        """Return the JSON-schema string for `spec`'s `response_model`, or `None` when absent."""
+        return self.schema_for(spec.response_model) if spec.response_model is not None else None
+
+    def to_response(self, raw: str, *, returncode: int, stderr: str, spec: RunSpec) -> Response:
+        """Resolve a raw capture into a `Response`: detect failure, extract text, validate.
+
+        A nonzero exit or an error envelope becomes `Response.error`; otherwise
+        the text comes from `result_text` and, when `spec.response_model` is set,
+        the validated model from `result_value`. A `pydantic.ValidationError`
+        from a non-conforming model propagates.
+
+        Args:
+            raw: The raw output read wherever the provider wrote it.
+            returncode: The process exit code.
+            stderr: The captured stderr.
+            spec: The configured run, carrying the optional `response_model`.
+
+        Returns:
+            The resolved `Response`.
+        """
+        if returncode != 0:
+            return Response(error=f"{self.provider} exited {returncode}: {stderr.strip()[-2000:]}", result=None)
+        if (err := self.envelope_error(raw)) is not None:
+            return Response(error=err, result=None)
+        if spec.response_model is None:
+            return Response(error=None, result=self.result_text(raw))
+        return Response(
+            error=None, result=self.result_text(raw), parsed=spec.response_model.model_validate(self.result_value(raw))
+        )
+
+    def result_text(self, raw: str) -> str:
+        """Return the final text output from a raw capture; the default is `raw` unchanged."""
+        return raw
+
+    def result_value(self, raw: str) -> object:
+        """Return the JSON value to validate from a raw capture; the default parses `raw` as JSON."""
+        return json.loads(raw)
+
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the provider's error message from an error envelope, or `None` on success."""
+        return None
+
 
 class CliBackend(LlmBackend):
     """Execution contract for the subprocess-backed LLM family.
@@ -214,7 +261,7 @@ class CliBackend(LlmBackend):
         """
         return Invocation(self.build_command(spec), spec.prompt)
 
-    async def aexecute(self, spec: RunSpec) -> RunResult:
+    async def aexecute(self, spec: RunSpec) -> Response:
         inv = self.invocation(spec)
         try:
             rr = await acapture_cli(
@@ -224,13 +271,13 @@ class CliBackend(LlmBackend):
                 cwd=spec.cwd,
                 timeout=spec.timeout,
             )
-            stdout = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+            raw = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
         finally:
             for path in inv.cleanup_paths:
                 Path(path).unlink(missing_ok=True)
-        return RunResult(stdout, rr.stderr, rr.returncode)
+        return self.to_response(raw, returncode=rr.returncode, stderr=rr.stderr, spec=spec)
 
-    def execute(self, spec: RunSpec) -> RunResult:
+    def execute(self, spec: RunSpec) -> Response:
         inv = self.invocation(spec)
         try:
             rr = capture_cli(
@@ -240,11 +287,11 @@ class CliBackend(LlmBackend):
                 cwd=spec.cwd,
                 timeout=spec.timeout,
             )
-            stdout = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+            raw = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
         finally:
             for path in inv.cleanup_paths:
                 Path(path).unlink(missing_ok=True)
-        return RunResult(stdout, rr.stderr, rr.returncode)
+        return self.to_response(raw, returncode=rr.returncode, stderr=rr.stderr, spec=spec)
 
     def check_status(self, *, timeout: int = 10) -> BackendStatus:
         """Check whether this backend's CLI is installed and authenticated.

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/backends/claude.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, ClassVar
 
 from spawnllm.backends.base import CliBackend
 from spawnllm.spec import ClaudeConfig
-from spawnllm.structured import parse_structured_output
+from spawnllm.structured import structured_value
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -19,6 +19,21 @@ if TYPE_CHECKING:
 CLAUDE_MODELS: dict[TModel, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
 
 
+def result_event(raw: str) -> dict[str, object] | None:
+    """Return the `claude` result envelope: the dict itself, or the `type=="result"` stream-json event, else `None`."""
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    match data:
+        case {"is_error": _} | {"result": _}:
+            return data
+        case list():
+            return next((e for e in data if isinstance(e, dict) and e.get("type") == "result"), None)
+        case _:
+            return None
+
+
 class ClaudeCliBackend(CliBackend):
     """`CliBackend` for the Anthropic `claude` CLI.
 
@@ -53,6 +68,7 @@ class ClaudeCliBackend(CliBackend):
             The argv list to execute; the prompt is delivered over stdin.
         """
         cfg = spec.config_for(ClaudeConfig) or ClaudeConfig()
+        schema = self.schema_arg(spec)
         explicit = (
             cfg.permission_mode is not None
             or cfg.mcp_config is not None
@@ -92,8 +108,8 @@ class ClaudeCliBackend(CliBackend):
             *(["--tools", cfg.tools] if cfg.tools is not None else []),
             *(["--disable-slash-commands"] if cfg.disable_slash_commands else []),
             *(
-                ["--json-schema", spec.schema, "--output-format", "json"]
-                if spec.schema
+                ["--json-schema", schema, "--output-format", "json"]
+                if schema
                 else ["--output-format", cfg.output_format]
                 if cfg.output_format
                 else []
@@ -118,17 +134,21 @@ class ClaudeCliBackend(CliBackend):
 
         return json.dumps(transform_schema(model))
 
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse `claude` stdout into text or a validated model.
-
-        Args:
-            raw: Raw stdout from the `claude` CLI.
-            response_model: Model to validate against, or `None` for raw text.
-
-        Returns:
-            `raw` for text calls; otherwise the validated `structured_output` from the result event, else `raw` as JSON.
-        """
-        return parse_structured_output(raw, response_model)
+    def result_text(self, raw: str) -> str:
+        """Return the `result` text from the `claude` envelope, falling back to `raw` for plain text."""
+        if (event := result_event(raw)) is not None and isinstance(text := event.get("result"), str):
+            return text
+        return raw
+
+    def result_value(self, raw: str) -> object:
+        """Return the `structured_output` from the `claude` stream-json result event, else `raw` parsed as JSON."""
+        return structured_value(raw)
+
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the error message when the `claude` result event marks the run as an error, else `None`."""
+        if (event := result_event(raw)) is not None and event.get("is_error"):
+            return event["result"] if isinstance(event.get("result"), str) else "claude reported an error"
+        return None
 
     def env(self) -> dict[str, str]:
         """Return no extra environment variables; the `claude` CLI runs with the inherited environment."""

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/backends/codex.py

@@ -47,9 +47,9 @@ class CodexCliBackend(CliBackend):
     def build_command(self, spec: RunSpec) -> list[str]:
         """Build the `codex exec` argv for one stdin-prompted invocation.
 
-        Resolves `spec.schema` to a temp file via `resolve_schema_path` and adds
-        `--output-schema` when present; `invocation` reuses that path and cleans
-        it up after the run.
+        Derives the schema from `spec.response_model`, writes it to a temp file
+        via `resolve_schema_path`, and adds `--output-schema` when present;
+        `invocation` reuses that path and cleans it up after the run.
 
         Args:
             spec: The configured run to translate into argv.
@@ -59,7 +59,7 @@ class CodexCliBackend(CliBackend):
         """
         from spawnllm.structured import resolve_schema_path
 
-        return self.command_for(spec, resolve_schema_path(self, spec.schema))
+        return self.command_for(spec, resolve_schema_path(self, self.schema_arg(spec)))
 
     def command_for(self, spec: RunSpec, schema_path: str | None) -> list[str]:
         cfg = spec.config_for(CodexConfig) or CodexConfig()
@@ -97,7 +97,7 @@ class CodexCliBackend(CliBackend):
         """
         from spawnllm.structured import resolve_schema_path
 
-        schema_path = resolve_schema_path(self, spec.schema)
+        schema_path = resolve_schema_path(self, self.schema_arg(spec))
         fd, result_path = tempfile.mkstemp(suffix=".json")
         os.close(fd)
         return Invocation(
@@ -125,18 +125,6 @@ class CodexCliBackend(CliBackend):
 
         return json.dumps(to_strict_json_schema(model))
 
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse the final message `codex` wrote to its `-o` file into text or a validated model.
-
-        Args:
-            raw: The final message read from the `-o` file.
-            response_model: Model to validate against, or `None` for raw text.
-
-        Returns:
-            `raw` when `response_model` is `None`; otherwise `raw` validated as JSON against `response_model`.
-        """
-        return raw if not response_model else response_model.model_validate_json(raw)
-
     def env(self) -> dict[str, str]:
         """Return no extra environment variables; the `codex` CLI runs with the inherited environment."""
         return {}

{spawnllm-0.4.0 → spawnllm-0.5.0}/spawnllm/backends/gemini.py

@@ -16,8 +16,6 @@ from spawnllm.spec import GeminiConfig
 from spawnllm.structured import extract_json_block
 
 if TYPE_CHECKING:
-    from pydantic import BaseModel
-
     from spawnllm.spec import RunSpec
     from spawnllm.types import ProviderName, TModel
 
@@ -33,7 +31,7 @@ class GeminiFamilyBackend(CliBackend, ABC):
     api_key_envs: ClassVar[tuple[str, ...]]
 
     def env(self) -> dict[str, str]:
-        """Return no extra environment variables; Gemini-family CLIs authenticate via OAuth, never an injected API key."""
+        """Return no extra environment variables; Gemini-family CLIs authenticate via OAuth, not an injected key."""
         return {}
 
     def is_authenticated(self, *, timeout: int) -> bool:
@@ -60,23 +58,17 @@ class GeminiFamilyBackend(CliBackend, ABC):
         Returns:
             An `Invocation` with an empty stdin that forces non-interactive output.
         """
-        text = spec.prompt if spec.schema is None else f"{spec.prompt}\n\n{SCHEMA_PROMPT}\n{spec.schema}"
+        schema = self.schema_arg(spec)
+        text = spec.prompt if schema is None else f"{spec.prompt}\n\n{SCHEMA_PROMPT}\n{schema}"
         return Invocation(self.build_command(spec) + ["-p", text], "")
 
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse Gemini-family stdout into text or a validated model.
-
-        Args:
-            raw: Raw stdout from the CLI.
-            response_model: Model to validate against, or `None` for raw text.
+    def result_text(self, raw: str) -> str:
+        """Return the model's text output, extracted from this CLI's stdout envelope."""
+        return self.extract_text(raw)
 
-        Returns:
-            The extracted text when `response_model` is `None`; otherwise the JSON block validated against it.
-        """
-        text = self.extract_text(raw)
-        if response_model is None:
-            return text
-        return response_model.model_validate_json(extract_json_block(text))
+    def result_value(self, raw: str) -> object:
+        """Return the JSON block parsed from the model's text output."""
+        return json.loads(extract_json_block(self.result_text(raw)))
 
     @abstractmethod
     def extract_text(self, raw: str) -> str: ...
@@ -149,13 +141,19 @@ class GeminiCliBackend(GeminiFamilyBackend):
                 return [arg for e in extensions for arg in ("-e", e)]
 
     def extract_text(self, raw: str) -> str:
+        return json.loads(raw)["response"]
+
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the raw failure payload when `gemini` reports `totalErrors` or an empty response, else `None`.
+
+        The whole payload tail is folded into the message so any transient marker the CLI emits
+        (529/overloaded/rate-limit) lands in `Response.error` and `is_transient` can fire a retry.
+        """
         data = json.loads(raw)
-        if (
-            sum(m["api"]["totalErrors"] for m in data.get("stats", {}).get("models", {}).values()) > 0
-            or not data.get("response")
-        ):
-            raise RuntimeError(f"gemini call failed: {data.get('stats', {}).get('models')}")
-        return data["response"]
+        models = data.get("stats", {}).get("models", {})
+        if sum(m["api"]["totalErrors"] for m in models.values()) > 0 or not data.get("response"):
+            return f"gemini call failed: {raw.strip()[-2000:]}"
+        return None
 
     def has_cached_credentials(self) -> bool:
         return (Path.home() / ".gemini" / "oauth_creds.json").exists()