handoffkit 1.3.0__tar.gz → 1.4.0__tar.gz

{handoffkit-1.3.0/handoffkit.egg-info → handoffkit-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoffkit
-Version: 1.3.0
+Version: 1.4.0
 Summary: A lightweight Python framework for building multi-agent workflows with structured state transfer protocols.
 Author: DaosPath
 License-Expression: MIT
@@ -231,6 +231,51 @@ clinical_trials_search.run(condition="systemic sclerosis", max_results=3)
 dailymed_drug_search.run(drug_name="ibuprofen", max_results=3)
 ```
 
+## What 1.4.0 Adds
+
+HandoffKit 1.4.0 adds experimental provider routing:
+
+- provider registry entries for OpenCode Go, OpenCode Zen, OpenAI-compatible
+  endpoints, and Ollama,
+- `ProviderSelector` for offline model lists and real opt-in probes,
+- `ProviderRouter` for ordered fallback between model candidates,
+- retry/backoff for transient OpenCode `429`, `5xx`, and transport failures,
+- `handoffkit providers ...` CLI commands that never call real APIs unless
+  `--real` is passed.
+
+```bash
+handoffkit providers list
+handoffkit providers models --provider opencode-go
+handoffkit providers select --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --json
+```
+
+Real probes require an explicit flag and a scoped provider key:
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+handoffkit providers probe --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --real
+```
+
+## Provider Registry and Model Routing
+
+The provider registry is experimental in 1.4.0. It is intended for diagnostics,
+model selection, and fallback without adding heavy provider SDKs.
+
+```python
+from handoffkit.providers import ModelCandidate, ProviderRouter
+
+router = ProviderRouter(
+    [
+        ModelCandidate("opencode-go", "mimo-v2.5"),
+        ModelCandidate("opencode-go", "deepseek-v4-flash"),
+    ]
+)
+
+print(router.generate("Create a concise release checklist."))
+```
+
+Docs: [`docs/PROVIDERS.md`](docs/PROVIDERS.md).
+
 ## What 1.1.0 Adds
 
 HandoffKit 1.1.0 focuses on adoption:
@@ -256,6 +301,8 @@ Use it as the contract and reporting layer beside orchestration frameworks:
 - [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state,
 - [`OpenCode Go / Zen`](docs/integrations/OPENCODE.md): provider adapters route
   OpenCode model families to their matching API endpoint styles.
+- [`Provider Registry`](docs/PROVIDERS.md): experimental provider listing,
+  probing, model selection, and fallback routing.
 
 Runnable offline examples:
 [`examples/langgraph_integration.py`](examples/langgraph_integration.py),
@@ -1085,6 +1132,9 @@ handoffkit demo-trace
 handoffkit demo-replay
 handoffkit validate-report reports/trace_demo.json
 handoffkit evaluate reports/trace_demo.json
+handoffkit providers list
+handoffkit providers models --provider opencode-go
+handoffkit providers select --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --json
 handoffkit init my-agent --template basic-agent --output .
 ```
 

{handoffkit-1.3.0 → handoffkit-1.4.0}/README.md

@@ -199,6 +199,51 @@ clinical_trials_search.run(condition="systemic sclerosis", max_results=3)
 dailymed_drug_search.run(drug_name="ibuprofen", max_results=3)
 ```
 
+## What 1.4.0 Adds
+
+HandoffKit 1.4.0 adds experimental provider routing:
+
+- provider registry entries for OpenCode Go, OpenCode Zen, OpenAI-compatible
+  endpoints, and Ollama,
+- `ProviderSelector` for offline model lists and real opt-in probes,
+- `ProviderRouter` for ordered fallback between model candidates,
+- retry/backoff for transient OpenCode `429`, `5xx`, and transport failures,
+- `handoffkit providers ...` CLI commands that never call real APIs unless
+  `--real` is passed.
+
+```bash
+handoffkit providers list
+handoffkit providers models --provider opencode-go
+handoffkit providers select --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --json
+```
+
+Real probes require an explicit flag and a scoped provider key:
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+handoffkit providers probe --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --real
+```
+
+## Provider Registry and Model Routing
+
+The provider registry is experimental in 1.4.0. It is intended for diagnostics,
+model selection, and fallback without adding heavy provider SDKs.
+
+```python
+from handoffkit.providers import ModelCandidate, ProviderRouter
+
+router = ProviderRouter(
+    [
+        ModelCandidate("opencode-go", "mimo-v2.5"),
+        ModelCandidate("opencode-go", "deepseek-v4-flash"),
+    ]
+)
+
+print(router.generate("Create a concise release checklist."))
+```
+
+Docs: [`docs/PROVIDERS.md`](docs/PROVIDERS.md).
+
 ## What 1.1.0 Adds
 
 HandoffKit 1.1.0 focuses on adoption:
@@ -224,6 +269,8 @@ Use it as the contract and reporting layer beside orchestration frameworks:
 - [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state,
 - [`OpenCode Go / Zen`](docs/integrations/OPENCODE.md): provider adapters route
   OpenCode model families to their matching API endpoint styles.
+- [`Provider Registry`](docs/PROVIDERS.md): experimental provider listing,
+  probing, model selection, and fallback routing.
 
 Runnable offline examples:
 [`examples/langgraph_integration.py`](examples/langgraph_integration.py),
@@ -1053,6 +1100,9 @@ handoffkit demo-trace
 handoffkit demo-replay
 handoffkit validate-report reports/trace_demo.json
 handoffkit evaluate reports/trace_demo.json
+handoffkit providers list
+handoffkit providers models --provider opencode-go
+handoffkit providers select --provider opencode-go --models mimo-v2.5,deepseek-v4-flash --json
 handoffkit init my-agent --template basic-agent --output .
 ```
 

{handoffkit-1.3.0 → handoffkit-1.4.0}/examples/mai_clinical_mimo_benchmark.py

@@ -11,6 +11,7 @@ import hashlib
 import json
 import os
 import re
+import sys
 import time
 import uuid
 from pathlib import Path
@@ -69,6 +70,12 @@ CLINICAL_EQUIVALENCE_ALIASES = {
 }
 
 
+def _configure_output_encoding() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
 def _compact(value: str) -> str:
     return re.sub(r"[^a-z0-9]+", "", value.lower())
 
@@ -824,6 +831,7 @@ Judge:
 
 
 def main() -> int:
+    _configure_output_encoding()
     parser = argparse.ArgumentParser()
     parser.add_argument("--cases", type=int, default=3)
     parser.add_argument("--model", default=os.getenv("OPENCODE_GO_MODEL", DEFAULT_MODEL))

{handoffkit-1.3.0 → handoffkit-1.4.0}/examples/opencode_go_agent.py

@@ -5,6 +5,7 @@ Requires OPENCODE_API_KEY. No secrets are printed.
 
 from __future__ import annotations
 
+import argparse
 import os
 import sys
 
@@ -18,10 +19,25 @@ def _configure_stdout() -> None:
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
 
-def main() -> None:
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run HandoffKit against OpenCode Go.")
+    parser.add_argument(
+        "--model",
+        default=os.getenv("OPENCODE_GO_MODEL", DEFAULT_OPENCODE_GO_MODEL),
+        help="OpenCode Go model id.",
+    )
+    parser.add_argument(
+        "--task",
+        default="Create a concise architecture plan for a Python CLI calculator.",
+        help="Task prompt.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
     _configure_stdout()
+    args = _parser().parse_args(argv)
     api_key = os.getenv("OPENCODE_API_KEY")
-    model = os.getenv("OPENCODE_GO_MODEL", DEFAULT_OPENCODE_GO_MODEL)
     if not api_key:
         print("OPENCODE_API_KEY is not set.")
         print('Set it with: $env:OPENCODE_API_KEY="..."')
@@ -29,19 +45,19 @@ def main() -> None:
         return
 
     try:
-        provider = OpenCodeGoProvider(model=model, api_key=api_key)
+        provider = OpenCodeGoProvider(model=args.model, api_key=api_key)
         agent = Agent(
             name="OpenCodeGoArchitect",
             role="Create concise coding architecture plans.",
             provider=provider,
         )
-        response = agent.run("Create a concise architecture plan for a Python CLI calculator.")
+        response = agent.run(args.task)
     except (ProviderConfigurationError, ProviderExecutionError) as exc:
         print(f"OpenCode Go unavailable: {exc}")
         return
 
     print("Provider: OpenCode Go")
-    print(f"Model: {model}")
+    print(f"Model: {args.model}")
     print(response)
 
 

{handoffkit-1.3.0 → handoffkit-1.4.0}/examples/opencode_zen_agent.py

@@ -5,6 +5,7 @@ Requires OPENCODE_API_KEY. No secrets are printed.
 
 from __future__ import annotations
 
+import argparse
 import os
 import sys
 
@@ -18,10 +19,25 @@ def _configure_stdout() -> None:
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
 
-def main() -> None:
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run HandoffKit against OpenCode Zen.")
+    parser.add_argument(
+        "--model",
+        default=os.getenv("OPENCODE_ZEN_MODEL", DEFAULT_OPENCODE_ZEN_MODEL),
+        help="OpenCode Zen model id.",
+    )
+    parser.add_argument(
+        "--task",
+        default="Create a concise architecture plan for a Python CLI calculator.",
+        help="Task prompt.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
     _configure_stdout()
+    args = _parser().parse_args(argv)
     api_key = os.getenv("OPENCODE_API_KEY")
-    model = os.getenv("OPENCODE_ZEN_MODEL", DEFAULT_OPENCODE_ZEN_MODEL)
     if not api_key:
         print("OPENCODE_API_KEY is not set.")
         print('Set it with: $env:OPENCODE_API_KEY="..."')
@@ -30,19 +46,19 @@ def main() -> None:
         return
 
     try:
-        provider = OpenCodeZenProvider(model=model, api_key=api_key)
+        provider = OpenCodeZenProvider(model=args.model, api_key=api_key)
         agent = Agent(
             name="OpenCodeZenArchitect",
             role="Create concise coding architecture plans.",
             provider=provider,
         )
-        response = agent.run("Create a concise architecture plan for a Python CLI calculator.")
+        response = agent.run(args.task)
     except (ProviderConfigurationError, ProviderExecutionError) as exc:
         print(f"OpenCode Zen unavailable: {exc}")
         return
 
     print("Provider: OpenCode Zen")
-    print(f"Model: {model}")
+    print(f"Model: {args.model}")
     print(response)
 
 

{handoffkit-1.3.0 → handoffkit-1.4.0}/handoffkit/__init__.py

@@ -66,7 +66,7 @@ from handoffkit.validation import (
     ValidationReport,
 )
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 
 __all__ = [
     "Agent",

{handoffkit-1.3.0 → handoffkit-1.4.0}/handoffkit/cli.py

@@ -20,7 +20,7 @@ from handoffkit.handoff import HandoffState
 from handoffkit.mai_benchmark import run_mai_style_benchmark
 from handoffkit.protocol import HandoffProtocol
 from handoffkit.provider_adapters import ProviderToolAdapter
-from handoffkit.providers import BaseProvider
+from handoffkit.providers import BaseProvider, ProviderSelector
 from handoffkit.quality import HandoffQualityEvaluator
 from handoffkit.recipes import RecipeRunner
 from handoffkit.replay import ReplayRunner
@@ -382,6 +382,90 @@ def list_showcases() -> str:
     return "\n".join(lines)
 
 
+def _split_models(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def list_providers(*, json_output: bool = False) -> str:
+    """List experimental provider registry entries."""
+    selector = ProviderSelector()
+    specs = [spec.to_dict() for spec in selector.list_providers()]
+    if json_output:
+        return json.dumps({"providers": specs}, indent=2, sort_keys=True)
+    lines = ["HandoffKit providers", ""]
+    for spec in selector.list_providers():
+        lines.append(f"- {spec.name}: {spec.description}")
+        lines.append(f"  default: {spec.default_model}")
+        lines.append(f"  models: {', '.join(spec.suggested_models)}")
+        lines.append(f"  env: {', '.join(spec.env_vars)}")
+    return "\n".join(lines)
+
+
+def list_provider_models(provider: str, *, real: bool = False, json_output: bool = False) -> str:
+    """List known provider models without network unless real=True."""
+    selector = ProviderSelector()
+    models = selector.list_models(provider, real=real)
+    payload = {"provider": provider, "real": real, "models": models}
+    if json_output:
+        return json.dumps(payload, indent=2, sort_keys=True)
+    mode = "real" if real else "offline"
+    return (
+        f"HandoffKit provider models ({mode})\n"
+        f"Provider: {provider}\n"
+        + "\n".join(f"- {model}" for model in models)
+    )
+
+
+def probe_provider_models(
+    provider: str,
+    *,
+    models: str | None = None,
+    real: bool = False,
+    json_output: bool = False,
+) -> str:
+    """Probe provider model candidates."""
+    selector = ProviderSelector()
+    results = [
+        selector.probe(candidate, real=real)
+        for candidate in selector.candidates(provider, _split_models(models))
+    ]
+    payload = {"provider": provider, "real": real, "results": [item.to_dict() for item in results]}
+    if json_output:
+        return json.dumps(payload, indent=2, sort_keys=True)
+    mode = "real" if real else "offline"
+    lines = [f"HandoffKit provider probe ({mode})", f"Provider: {provider}"]
+    for result in results:
+        status = "ok" if result.success else "failed"
+        suffix = f" error={result.error}" if result.error else ""
+        lines.append(f"- {result.model}: {status} {result.latency_seconds:.3f}s{suffix}")
+    return "\n".join(lines)
+
+
+def select_provider_model(
+    provider: str,
+    *,
+    models: str | None = None,
+    real: bool = False,
+    json_output: bool = False,
+) -> str:
+    """Select the first working provider model."""
+    selector = ProviderSelector()
+    result = selector.select(provider, _split_models(models), real=real)
+    payload = result.to_dict()
+    if json_output:
+        return json.dumps(payload, indent=2, sort_keys=True)
+    mode = "real" if real else "offline"
+    return (
+        f"HandoffKit provider select ({mode})\n"
+        f"Provider: {result.provider}\n"
+        f"Model: {result.model}\n"
+        f"Success: {result.success}\n"
+        f"Latency: {result.latency_seconds:.3f}s"
+    )
+
+
 def run_named_showcase(slug: str) -> str:
     """Run one named showcase and write runs/latest artifacts."""
     return run_showcase(slug).to_markdown()
@@ -471,6 +555,42 @@ def main(argv: list[str] | None = None) -> int:
     subparsers.add_parser("demo-support", help="Run the support escalation showcase.")
     subparsers.add_parser("demo-research", help="Run the research workflow showcase.")
     subparsers.add_parser("demo-doctor", help="Run the educational doctor-orchestrator showcase.")
+    providers_parser = subparsers.add_parser("providers", help="Inspect provider registry.")
+    providers_subparsers = providers_parser.add_subparsers(dest="providers_command")
+    providers_list_parser = providers_subparsers.add_parser("list", help="List providers.")
+    providers_list_parser.add_argument("--json", action="store_true", help="Print JSON.")
+    providers_models_parser = providers_subparsers.add_parser(
+        "models",
+        help="List provider models.",
+    )
+    providers_models_parser.add_argument("--provider", required=True, help="Provider name.")
+    providers_models_parser.add_argument(
+        "--real",
+        action="store_true",
+        help="Call provider endpoint.",
+    )
+    providers_models_parser.add_argument("--json", action="store_true", help="Print JSON.")
+    providers_probe_parser = providers_subparsers.add_parser("probe", help="Probe provider models.")
+    providers_probe_parser.add_argument("--provider", required=True, help="Provider name.")
+    providers_probe_parser.add_argument("--models", default=None, help="Comma-separated models.")
+    providers_probe_parser.add_argument(
+        "--real",
+        action="store_true",
+        help="Call provider endpoint.",
+    )
+    providers_probe_parser.add_argument("--json", action="store_true", help="Print JSON.")
+    providers_select_parser = providers_subparsers.add_parser(
+        "select",
+        help="Select a provider model.",
+    )
+    providers_select_parser.add_argument("--provider", required=True, help="Provider name.")
+    providers_select_parser.add_argument("--models", default=None, help="Comma-separated models.")
+    providers_select_parser.add_argument(
+        "--real",
+        action="store_true",
+        help="Call provider endpoint.",
+    )
+    providers_select_parser.add_argument("--json", action="store_true", help="Print JSON.")
     benchmark_doctor_parser = subparsers.add_parser(
         "benchmark-doctor",
         help="Run the real-case doctor benchmark harness.",
@@ -556,6 +676,34 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "demo-doctor":
         print(run_doctor_orchestrator_demo())
         return 0
+    if args.command == "providers":
+        if args.providers_command == "list":
+            print(list_providers(json_output=args.json))
+            return 0
+        if args.providers_command == "models":
+            print(list_provider_models(args.provider, real=args.real, json_output=args.json))
+            return 0
+        if args.providers_command == "probe":
+            print(
+                probe_provider_models(
+                    args.provider,
+                    models=args.models,
+                    real=args.real,
+                    json_output=args.json,
+                )
+            )
+            return 0
+        if args.providers_command == "select":
+            print(
+                select_provider_model(
+                    args.provider,
+                    models=args.models,
+                    real=args.real,
+                    json_output=args.json,
+                )
+            )
+            return 0
+        parser.error("providers requires a subcommand")
     if args.command == "benchmark-doctor":
         print(run_doctor_benchmark_demo(args.cases))
         return 0

{handoffkit-1.3.0 → handoffkit-1.4.0}/handoffkit/providers/__init__.py

@@ -14,12 +14,23 @@ from handoffkit.providers.opencode_provider import (
     DEFAULT_OPENCODE_GO_MODEL,
     DEFAULT_OPENCODE_ZEN_BASE_URL,
     DEFAULT_OPENCODE_ZEN_MODEL,
+    OPENCODE_GO_MODELS,
+    OPENCODE_ZEN_MODELS,
     OpenCodeGoProvider,
     OpenCodeProvider,
     OpenCodeZenProvider,
+    RetryPolicy,
     infer_opencode_api_style,
     list_opencode_models,
 )
+from handoffkit.providers.registry import (
+    ModelCandidate,
+    ProviderProbeResult,
+    ProviderRouter,
+    ProviderSelector,
+    ProviderSpec,
+    default_provider_specs,
+)
 
 __all__ = [
     "BaseProvider",
@@ -29,12 +40,21 @@ __all__ = [
     "DEFAULT_OPENCODE_ZEN_BASE_URL",
     "DEFAULT_OPENCODE_ZEN_MODEL",
     "ModelSelectionResult",
+    "ModelCandidate",
+    "OPENCODE_GO_MODELS",
+    "OPENCODE_ZEN_MODELS",
     "OllamaProvider",
     "OpenCodeGoProvider",
     "OpenCodeProvider",
     "OpenCodeZenProvider",
     "OpenAIProvider",
+    "ProviderProbeResult",
+    "ProviderRouter",
+    "ProviderSelector",
+    "ProviderSpec",
+    "RetryPolicy",
     "choose_openai_compatible_model",
+    "default_provider_specs",
     "infer_opencode_api_style",
     "list_opencode_models",
     "list_openai_compatible_models",

{handoffkit-1.3.0 → handoffkit-1.4.0}/handoffkit/providers/opencode_provider.py

@@ -4,8 +4,10 @@ from __future__ import annotations
 
 import json
 import os
+import time
 import urllib.error
 import urllib.request
+from dataclasses import dataclass
 from typing import Any, Literal
 
 from handoffkit.errors import ProviderConfigurationError, ProviderExecutionError
@@ -18,6 +20,53 @@ DEFAULT_OPENCODE_ZEN_BASE_URL = "https://opencode.ai/zen/v1"
 DEFAULT_OPENCODE_GO_BASE_URL = "https://opencode.ai/zen/go/v1"
 DEFAULT_OPENCODE_ZEN_MODEL = "gpt-5.4"
 DEFAULT_OPENCODE_GO_MODEL = "deepseek-v4-flash"
+OPENCODE_USER_AGENT = "handoffkit/1.4 OpenCodeProvider"
+
+OPENCODE_GO_MODELS = (
+    "mimo-v2.5",
+    "deepseek-v4-flash",
+    "deepseek-v4-pro",
+    "glm-5.2",
+    "qwen3.7-max",
+    "qwen3.7-plus",
+    "kimi-k2.7-code",
+    "minimax-m3",
+)
+
+OPENCODE_ZEN_MODELS = (
+    "gpt-5.4",
+    "claude-sonnet-5",
+    "qwen3.7-max",
+    "qwen3.7-plus",
+    "deepseek-v4-flash",
+    "deepseek-v4-pro",
+    "glm-5.2",
+    "kimi-k2.7-code",
+    "minimax-m3",
+)
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Retry policy for transient provider failures."""
+
+    max_attempts: int = 3
+    backoff_seconds: float = 0.5
+    retry_status_codes: tuple[int, ...] = (429, 500, 502, 503, 504)
+
+    def should_retry_status(self, status_code: int, attempt: int) -> bool:
+        """Return whether this HTTP status should be retried."""
+        return attempt < self.max_attempts and status_code in self.retry_status_codes
+
+    def should_retry_url_error(self, attempt: int) -> bool:
+        """Return whether this URL-level error should be retried."""
+        return attempt < self.max_attempts
+
+    def sleep(self, attempt: int) -> None:
+        """Sleep before the next retry attempt."""
+        delay = self.backoff_seconds * max(0, attempt - 1)
+        if delay > 0:
+            time.sleep(delay)
 
 _GO_ANTHROPIC_MODELS = {
     "minimax-m3",
@@ -92,7 +141,7 @@ def list_opencode_models(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "Content-Type": "application/json",
-            "User-Agent": "handoffkit/1.2 OpenCodeProvider",
+            "User-Agent": OPENCODE_USER_AGENT,
         },
         method="GET",
     )
@@ -110,7 +159,13 @@ def list_opencode_models(
             f"OpenCode {resolved_catalog} models request failed for "
             f"{resolved_base_url}: {exc.reason}"
         ) from exc
-    data = body.get("data", body if isinstance(body, list) else [])
+    data = (
+        body.get("data", [])
+        if isinstance(body, dict)
+        else body
+        if isinstance(body, list)
+        else []
+    )
     models: list[str] = []
     if isinstance(data, list):
         for item in data:
@@ -133,6 +188,7 @@ class OpenCodeProvider(BaseProvider):
         base_url: str | None = None,
         api_style: OpenCodeAPIStyle = "auto",
         timeout: float = 60.0,
+        retry_policy: RetryPolicy | None = None,
     ) -> None:
         self.catalog = _normalize_catalog(catalog)
         self.model = _strip_opencode_prefix(
@@ -143,6 +199,7 @@ class OpenCodeProvider(BaseProvider):
         self.base_url = _resolve_base_url(self.catalog, base_url)
         self.api_style = infer_opencode_api_style(self.model, self.catalog, api_style)
         self.timeout = timeout
+        self.retry_policy = retry_policy or RetryPolicy()
         if not self.api_key:
             raise ProviderConfigurationError(
                 "OPENCODE_API_KEY is required for OpenCodeProvider. "
@@ -227,7 +284,7 @@ class OpenCodeProvider(BaseProvider):
             "Authorization": f"Bearer {self.api_key}",
             "Accept": "application/json",
             "Content-Type": "application/json",
-            "User-Agent": "handoffkit/1.2 OpenCodeProvider",
+            "User-Agent": OPENCODE_USER_AGENT,
         }
         if extra_headers:
             headers.update(extra_headers)
@@ -237,19 +294,29 @@ class OpenCodeProvider(BaseProvider):
             headers=headers,
             method="POST",
         )
-        try:
-            with urllib.request.urlopen(request, timeout=self.timeout) as response:
-                body = json.loads(response.read().decode("utf-8"))
-        except urllib.error.HTTPError as exc:
-            detail = exc.read().decode("utf-8", errors="replace")
-            raise ProviderExecutionError(
-                f"OpenCode {self.catalog} request failed with HTTP {exc.code}: "
-                f"{_sanitize_error_detail(detail, self.api_key)}"
-            ) from exc
-        except urllib.error.URLError as exc:
-            raise ProviderExecutionError(
-                f"OpenCode {self.catalog} request failed for {self.base_url}: {exc.reason}"
-            ) from exc
+        for attempt in range(1, self.retry_policy.max_attempts + 1):
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    body = json.loads(response.read().decode("utf-8"))
+                break
+            except urllib.error.HTTPError as exc:
+                detail = exc.read().decode("utf-8", errors="replace")
+                if self.retry_policy.should_retry_status(exc.code, attempt):
+                    self.retry_policy.sleep(attempt)
+                    continue
+                raise ProviderExecutionError(
+                    f"OpenCode {self.catalog} request failed with HTTP {exc.code}: "
+                    f"{_sanitize_error_detail(detail, self.api_key)}"
+                ) from exc
+            except urllib.error.URLError as exc:
+                if self.retry_policy.should_retry_url_error(attempt):
+                    self.retry_policy.sleep(attempt)
+                    continue
+                raise ProviderExecutionError(
+                    f"OpenCode {self.catalog} request failed for {self.base_url}: {exc.reason}"
+                ) from exc
+        else:  # pragma: no cover - defensive fallback.
+            raise ProviderExecutionError(f"OpenCode {self.catalog} request failed.")
         if not isinstance(body, dict):
             raise ProviderExecutionError(
                 f"OpenCode {self.catalog} response was not a JSON object."