@triclaps/cli 0.0.2 → 0.0.4

package/adapters/hermes_claps_adapter.py

@@ -0,0 +1,697 @@
+#!/usr/bin/env python3
+"""
+CLAPS ↔ Hermes structured adapter.
+
+Wraps Hermes as a Python library (no source modifications) and outputs
+Codex-compatible NDJSON events to stdout for CLAPS stream consumption.
+
+Events emitted (one JSON object per line):
+  {"type":"session_meta","payload":{"id":"..."}}
+  {"type":"item.completed","item":{"type":"reasoning","text":"..."}}
+  {"type":"item.started","item":{"type":"<tool>","id":"<id>","command":"..."}}
+  {"type":"item.completed","item":{"type":"<tool>","id":"<id>","status":"completed","aggregated_output":"..."}}
+  {"type":"item.completed","item":{"type":"agent_message"}}
+
+Usage:
+  python3 hermes_claps_adapter.py --prompt "..." [-o /tmp/output.txt] [--resume ID]
+
+The final agent response is written to the file specified by -o (if provided).
+All structured NDJSON events are emitted to stdout.
+Hermes internal output is redirected to stderr.
+"""
+
+import argparse
+import inspect
+import json
+import os
+from pathlib import Path
+from typing import Any
+import sys
+import threading
+
+# ---------------------------------------------------------------------------
+# Redirect stdout BEFORE importing any Hermes modules.
+# Hermes prints banners, tool progress, and status messages to stdout/stderr
+# during import and initialization.  Capturing the real stdout early ensures
+# the NDJSON event stream stays clean.
+# ---------------------------------------------------------------------------
+_ndjson_fd = os.dup(sys.stdout.fileno())   # duplicate the real stdout fd
+_ndjson_out = os.fdopen(_ndjson_fd, "w", encoding="utf-8", closefd=True)
+_emit_lock = threading.Lock()
+
+# Point Python-level stdout to stderr so all Hermes prints go there.
+sys.stdout = sys.stderr
+
+
+def env_flag_enabled(name: str) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return False
+    return value.strip().lower() not in {"", "0", "false", "no", "off"}
+
+
+DEBUG_ENABLED = env_flag_enabled("CLAPS_HERMES_DEBUG")
+DEFAULT_DEBUG_BODY_BYTES = 64 * 1024
+
+
+def resolve_debug_body_limit() -> int:
+    raw_value = os.environ.get("CLAPS_HERMES_DEBUG_MAX_BODY_BYTES", "").strip()
+    if not raw_value:
+        return DEFAULT_DEBUG_BODY_BYTES
+
+    try:
+        parsed = int(raw_value)
+    except ValueError:
+        return DEFAULT_DEBUG_BODY_BYTES
+
+    if parsed <= 0:
+        return DEFAULT_DEBUG_BODY_BYTES
+
+    return min(parsed, 5 * 1024 * 1024)
+
+
+DEBUG_BODY_LIMIT = resolve_debug_body_limit()
+
+
+def emit(event: dict) -> None:
+    """Write one NDJSON event to the real stdout (fd-level) and flush."""
+    line = json.dumps(event, ensure_ascii=False) + "\n"
+    with _emit_lock:
+        _ndjson_out.write(line)
+        _ndjson_out.flush()
+
+
+def clip_debug_text(text: str) -> str:
+    if len(text) <= DEBUG_BODY_LIMIT:
+        return text
+    remaining = len(text) - DEBUG_BODY_LIMIT
+    return f"{text[:DEBUG_BODY_LIMIT]}... [truncated {remaining} chars]"
+
+
+def normalize_debug_value(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (bytes, bytearray)):
+        return clip_debug_text(value.decode("utf-8", errors="replace"))
+    if isinstance(value, str):
+        return clip_debug_text(value)
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(key): normalize_debug_value(inner) for key, inner in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [normalize_debug_value(item) for item in value]
+    if isinstance(value, (bool, int, float)):
+        return value
+    return clip_debug_text(repr(value))
+
+
+def debug_log(label: str, payload: dict[str, Any]) -> None:
+    if not DEBUG_ENABLED:
+        return
+    print(
+        f"[hermes-debug] {label}: {json.dumps(normalize_debug_value(payload), ensure_ascii=False)}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def read_request_body_for_debug(request: Any) -> str | None:
+    try:
+        content = request.content
+    except Exception as exc:
+        return f"<unavailable: {exc}>"
+    return normalize_debug_value(content)
+
+
+def extract_response_body_for_debug(response: Any) -> str:
+    try:
+        content = response.read()
+    except Exception as exc:
+        return f"<unavailable: {exc}>"
+    return normalize_debug_value(content)
+
+
+async def extract_async_response_body_for_debug(response: Any) -> str:
+    try:
+        content = await response.aread()
+    except Exception as exc:
+        return f"<unavailable: {exc}>"
+    return normalize_debug_value(content)
+
+
+def build_http_debug_payload(prefix: str, request: Any, *, stream: bool) -> dict[str, Any]:
+    return {
+        "kind": prefix,
+        "method": getattr(request, "method", None),
+        "url": str(getattr(request, "url", "")),
+        "headers": dict(getattr(request, "headers", {}) or {}),
+        "body": read_request_body_for_debug(request),
+        "stream": stream,
+    }
+
+
+def is_likely_llm_url(url: str) -> bool:
+    normalized = url.strip()
+    if not normalized:
+        return False
+
+    configured_prefixes = [
+        os.environ.get("HERMES_BASE_URL", "").strip(),
+        os.environ.get("OPENAI_BASE_URL", "").strip(),
+        os.environ.get("ANTHROPIC_BASE_URL", "").strip(),
+    ]
+    for prefix in configured_prefixes:
+        if prefix and normalized.startswith(prefix.rstrip("/")):
+            return True
+
+    return any(
+        marker in normalized
+        for marker in (
+            "/chat/completions",
+            "/responses",
+            "/messages",
+            "/v1/completions",
+        )
+    )
+
+
+def install_http_debug_logging() -> None:
+    if not DEBUG_ENABLED:
+        return
+
+    try:
+        import httpx  # type: ignore
+    except Exception as exc:
+        debug_log("httpx_debug_unavailable", {"error": str(exc)})
+    else:
+        original_send = httpx.Client.send
+        if not getattr(original_send, "_claps_debug_wrapped", False):
+            def wrapped_send(self, request, *args, **kwargs):
+                stream = bool(kwargs.get("stream", False))
+                request_url = str(getattr(request, "url", ""))
+                if is_likely_llm_url(request_url):
+                    debug_log("llm_request", build_http_debug_payload("httpx", request, stream=stream))
+
+                response = original_send(self, request, *args, **kwargs)
+
+                if is_likely_llm_url(request_url):
+                    payload = {
+                        "kind": "httpx",
+                        "status_code": getattr(response, "status_code", None),
+                        "url": str(getattr(response, "url", request_url)),
+                        "headers": dict(getattr(response, "headers", {}) or {}),
+                        "stream": stream,
+                    }
+                    if stream:
+                        payload["body"] = "<streaming response body not eagerly captured>"
+                    else:
+                        payload["body"] = extract_response_body_for_debug(response)
+                    debug_log("llm_response", payload)
+
+                return response
+
+            wrapped_send._claps_debug_wrapped = True  # type: ignore[attr-defined]
+            httpx.Client.send = wrapped_send
+
+        original_async_send = httpx.AsyncClient.send
+        if not getattr(original_async_send, "_claps_debug_wrapped", False):
+            async def wrapped_async_send(self, request, *args, **kwargs):
+                stream = bool(kwargs.get("stream", False))
+                request_url = str(getattr(request, "url", ""))
+                if is_likely_llm_url(request_url):
+                    debug_log("llm_request", build_http_debug_payload("httpx_async", request, stream=stream))
+
+                response = await original_async_send(self, request, *args, **kwargs)
+
+                if is_likely_llm_url(request_url):
+                    payload = {
+                        "kind": "httpx_async",
+                        "status_code": getattr(response, "status_code", None),
+                        "url": str(getattr(response, "url", request_url)),
+                        "headers": dict(getattr(response, "headers", {}) or {}),
+                        "stream": stream,
+                    }
+                    if stream:
+                        payload["body"] = "<streaming response body not eagerly captured>"
+                    else:
+                        payload["body"] = await extract_async_response_body_for_debug(response)
+                    debug_log("llm_response", payload)
+
+                return response
+
+            wrapped_async_send._claps_debug_wrapped = True  # type: ignore[attr-defined]
+            httpx.AsyncClient.send = wrapped_async_send
+
+    try:
+        import requests  # type: ignore
+    except Exception as exc:
+        debug_log("requests_debug_unavailable", {"error": str(exc)})
+    else:
+        original_request = requests.Session.request
+        if not getattr(original_request, "_claps_debug_wrapped", False):
+            def wrapped_request(self, method, url, **kwargs):
+                normalized_url = str(url)
+                if is_likely_llm_url(normalized_url):
+                    debug_log(
+                        "llm_request",
+                        {
+                            "kind": "requests",
+                            "method": method,
+                            "url": normalized_url,
+                            "headers": dict(kwargs.get("headers") or {}),
+                            "body": normalize_debug_value(kwargs.get("data") or kwargs.get("json")),
+                            "stream": bool(kwargs.get("stream", False)),
+                        },
+                    )
+
+                response = original_request(self, method, url, **kwargs)
+
+                if is_likely_llm_url(normalized_url):
+                    debug_log(
+                        "llm_response",
+                        {
+                            "kind": "requests",
+                            "status_code": getattr(response, "status_code", None),
+                            "url": getattr(response, "url", normalized_url),
+                            "headers": dict(getattr(response, "headers", {}) or {}),
+                            "body": normalize_debug_value(getattr(response, "text", "")),
+                            "stream": bool(kwargs.get("stream", False)),
+                        },
+                    )
+
+                return response
+
+            wrapped_request._claps_debug_wrapped = True  # type: ignore[attr-defined]
+            requests.Session.request = wrapped_request
+
+
+def _looks_like_hermes_root(candidate: Path) -> bool:
+    return (candidate / "cli.py").is_file() and (candidate / "hermes_cli").is_dir()
+
+
+def ensure_hermes_import_path() -> Path | None:
+    candidates: list[Path] = []
+
+    configured_root = os.environ.get("HERMES_PROJECT_ROOT")
+    if configured_root:
+        candidates.append(Path(configured_root).expanduser())
+
+    web_dist = os.environ.get("HERMES_WEB_DIST")
+    if web_dist:
+        current = Path(web_dist).expanduser().resolve()
+        candidates.extend(current.parents)
+
+    adapter_path = Path(__file__).resolve()
+    candidates.extend(adapter_path.parents)
+    candidates.extend(
+        [
+            Path.cwd(),
+            Path("/opt/hermes"),
+        ]
+    )
+
+    seen: set[str] = set()
+    for candidate in candidates:
+        try:
+            resolved = candidate.resolve()
+        except OSError:
+            continue
+
+        key = str(resolved)
+        if key in seen:
+            continue
+        seen.add(key)
+
+        if not _looks_like_hermes_root(resolved):
+            continue
+
+        if key not in sys.path:
+            sys.path.insert(0, key)
+        return resolved
+
+    return None
+
+
+def resolve_runtime_overrides_from_env() -> dict:
+    openai_api_key = os.environ.get("OPENAI_API_KEY")
+    openrouter_api_key = os.environ.get("OPENROUTER_API_KEY")
+    model = (
+        os.environ.get("HERMES_MODEL")
+        or os.environ.get("CLAPS_HERMES_MODEL")
+        or os.environ.get("OPENAI_MODEL")
+        or os.environ.get("ANTHROPIC_MODEL")
+        or None
+    )
+    base_url = (
+        os.environ.get("HERMES_BASE_URL")
+        or os.environ.get("OPENAI_BASE_URL")
+        or None
+    )
+    provider = (
+        os.environ.get("HERMES_INFERENCE_PROVIDER")
+        or None
+    )
+    if (
+        not base_url
+        and isinstance(openai_api_key, str)
+        and openai_api_key.strip()
+        and not (isinstance(openrouter_api_key, str) and openrouter_api_key.strip())
+    ):
+        base_url = "https://api.openai.com/v1"
+
+    if (
+        not provider
+        and isinstance(openai_api_key, str)
+        and openai_api_key.strip()
+        and not (isinstance(openrouter_api_key, str) and openrouter_api_key.strip())
+    ):
+        provider = "custom"
+
+    return {
+        "model": model.strip() if isinstance(model, str) and model.strip() else None,
+        "base_url": base_url.strip() if isinstance(base_url, str) and base_url.strip() else None,
+        "provider": provider.strip() if isinstance(provider, str) and provider.strip() else None,
+    }
+
+
+def resolve_toolsets_from_env() -> list[str] | None:
+    raw_value = (
+        os.environ.get("CLAPS_HERMES_TOOLSETS")
+        or os.environ.get("HERMES_TOOLSETS")
+        or None
+    )
+    if raw_value is None:
+        return None
+
+    toolsets = [part.strip() for part in raw_value.split(",") if part.strip()]
+    return toolsets or None
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="CLAPS Hermes structured adapter")
+    parser.add_argument("--prompt", required=True, help="User prompt")
+    parser.add_argument("-o", "--output", default=None, help="Output file for the final response")
+    parser.add_argument("--resume", default=None, help="Hermes session ID to resume")
+    parser.add_argument(
+        "--session-id",
+        default=None,
+        help="Deterministic session ID to use for a fresh session (ignored when --resume is set)",
+    )
+    parser.add_argument("--max-turns", type=int, default=None, help="Max tool iterations")
+    parser.add_argument("--skills", default=None, help="Comma-separated skill names to preload")
+    args = parser.parse_args()
+
+    debug_log(
+        "incoming_request",
+        {
+            "cwd": str(Path.cwd()),
+            "resume": args.resume,
+            "session_id": args.session_id,
+            "max_turns": args.max_turns,
+            "skills": args.skills,
+            "prompt": args.prompt,
+            "env": {
+                "HERMES_HOME": os.environ.get("HERMES_HOME"),
+                "HERMES_PROJECT_ROOT": os.environ.get("HERMES_PROJECT_ROOT"),
+                "HERMES_INFERENCE_PROVIDER": os.environ.get("HERMES_INFERENCE_PROVIDER"),
+                "HERMES_BASE_URL": os.environ.get("HERMES_BASE_URL"),
+                "OPENAI_BASE_URL": os.environ.get("OPENAI_BASE_URL"),
+                "OPENAI_MODEL": os.environ.get("OPENAI_MODEL"),
+                "ANTHROPIC_BASE_URL": os.environ.get("ANTHROPIC_BASE_URL"),
+                "ANTHROPIC_MODEL": os.environ.get("ANTHROPIC_MODEL"),
+                "CLAPS_HERMES_TOOLSETS": os.environ.get("CLAPS_HERMES_TOOLSETS"),
+            },
+        },
+    )
+
+    # ── Import Hermes modules ────────────────────────────────────────────
+    hermes_root = ensure_hermes_import_path()
+    try:
+        from cli import HermesCLI
+    except ImportError as exc:
+        root_hint = (
+            "Resolved roots searched, but no Hermes checkout was found. "
+            "Set HERMES_PROJECT_ROOT or PYTHONPATH to the Hermes source root."
+            if hermes_root is None
+            else f"Resolved Hermes root: {hermes_root}"
+        )
+        emit({"type": "error", "error": f"Cannot import Hermes modules: {exc}. {root_hint}"})
+        sys.exit(1)
+
+    # ── Create CLI instance (handles config loading, credential setup) ──
+    runtime_overrides = resolve_runtime_overrides_from_env()
+    configured_toolsets = resolve_toolsets_from_env()
+    install_http_debug_logging()
+    cli_init_kwargs = {
+        "resume": args.resume,
+        "pass_session_id": True,
+    }
+    if configured_toolsets is not None:
+        cli_init_kwargs["toolsets"] = configured_toolsets
+    if runtime_overrides["model"] is not None:
+        cli_init_kwargs["model"] = runtime_overrides["model"]
+    if runtime_overrides["base_url"] is not None:
+        cli_init_kwargs["base_url"] = runtime_overrides["base_url"]
+    if runtime_overrides["provider"] is not None:
+        cli_init_kwargs["provider"] = runtime_overrides["provider"]
+
+    debug_log(
+        "runtime_overrides",
+        {
+            "toolsets": configured_toolsets,
+            "runtime_overrides": runtime_overrides,
+        },
+    )
+
+    cli = HermesCLI(**cli_init_kwargs)
+    cli.tool_progress_mode = "off"
+
+    # ── Override session id for fresh sessions ───────────────────────────
+    # When CLAPS provides a deterministic --session-id, use it so that the
+    # same CLAPS conversation maps 1:1 onto a Hermes session.  We only
+    # override on cold starts; resume paths already locate the session via
+    # --resume so the id must come from the persisted record.
+    #
+    # HermesCLI.__init__ auto-generates a timestamp-based session_id and may
+    # have already registered it with SessionDB before we get here, which
+    # leaves orphan session_<timestamp>_<hash>.json files behind on every
+    # cold start. Clean up the orphan id after overriding so each CLAPS
+    # conversation maps to exactly one hermes session file.
+    if args.session_id and not args.resume:
+        auto_session_id = cli.session_id
+        cli.session_id = args.session_id
+        if auto_session_id and auto_session_id != args.session_id:
+            session_db = getattr(cli, "_session_db", None)
+            if session_db is not None:
+                try:
+                    session_db.delete_session(auto_session_id)
+                except Exception as exc:
+                    print(
+                        f"[adapter] failed to drop auto-generated session row {auto_session_id}: {exc}",
+                        file=sys.stderr,
+                    )
+            try:
+                hermes_home = os.environ.get("HERMES_HOME") or str(Path.home() / ".hermes")
+                auto_file = Path(hermes_home) / "sessions" / f"session_{auto_session_id}.json"
+                if auto_file.exists():
+                    auto_file.unlink()
+            except OSError as exc:
+                print(
+                    f"[adapter] failed to remove auto-generated session file {auto_session_id}: {exc}",
+                    file=sys.stderr,
+                )
+
+    # ── Preload skills if requested ──────────────────────────────────────
+    if args.skills:
+        try:
+            from hermes_cli.skills_loader import build_preloaded_skills_prompt
+            skill_names = [s.strip() for s in args.skills.split(",") if s.strip()]
+            skills_prompt, _loaded, _missing = build_preloaded_skills_prompt(
+                skill_names, task_id=cli.session_id,
+            )
+            if skills_prompt:
+                cli.system_prompt = "\n\n".join(
+                    part for part in (cli.system_prompt, skills_prompt) if part
+                ).strip()
+        except Exception as exc:
+            print(f"[adapter] skill preload failed: {exc}", file=sys.stderr)
+
+    # ── Ensure credentials & initialize agent ────────────────────────────
+    if not cli._ensure_runtime_credentials():
+        emit({"type": "error", "error": "Hermes credential initialization failed"})
+        sys.exit(1)
+
+    turn_route = cli._resolve_turn_agent_config(args.prompt)
+    route_signature = turn_route.get("signature")
+    if route_signature != cli._active_agent_route_signature:
+        cli.agent = None
+
+    init_agent_kwargs = {
+        "model_override": turn_route.get("model"),
+        "runtime_override": turn_route.get("runtime"),
+        "request_overrides": turn_route.get("request_overrides"),
+    }
+    try:
+        init_agent_signature = inspect.signature(cli._init_agent)
+    except (TypeError, ValueError):
+        init_agent_signature = None
+
+    if init_agent_signature and "route_label" in init_agent_signature.parameters:
+        route_label = turn_route.get("label")
+        if route_label is not None:
+            init_agent_kwargs["route_label"] = route_label
+
+    if not cli._init_agent(**init_agent_kwargs):
+        emit({"type": "error", "error": "Hermes agent initialization failed"})
+        sys.exit(1)
+
+    debug_log(
+        "agent_initialized",
+        {
+            "session_id": cli.session_id,
+            "turn_route": turn_route,
+            "model": getattr(cli, "model", None),
+            "provider": getattr(cli, "provider", None),
+            "base_url": getattr(cli, "base_url", None),
+        },
+    )
+
+    agent = cli.agent
+    agent.quiet_mode = True
+    agent.suppress_status_output = True
+
+    if args.max_turns:
+        agent.max_iterations = args.max_turns
+
+    # ── Ensure thinking/reasoning tokens are requested ───────────────────
+    # Some providers (e.g. Gemini via LiteLLM) need an explicit thinking
+    # config in extra_body.  Hermes only sends this for known providers
+    # (OpenRouter, Nous, GitHub), so custom/LiteLLM endpoints miss out.
+    # Inject it via request_overrides so reasoning_callback actually fires.
+    if not getattr(agent, "_supports_reasoning_extra_body", lambda: False)():
+        overrides = dict(getattr(agent, "request_overrides", None) or {})
+        existing_extra = overrides.get("extra_body", {})
+        if "reasoning" not in existing_extra and "thinking" not in existing_extra:
+            existing_extra["thinking"] = {"type": "enabled", "budget_tokens": 8192}
+            overrides["extra_body"] = existing_extra
+            agent.request_overrides = overrides
+
+    # ── Override callbacks with NDJSON emitters ──────────────────────────
+    # Disable streaming so reasoning_callback fires once with the complete
+    # reasoning text (instead of many deltas).  Tool callbacks fire
+    # independently of the streaming path.
+    agent.stream_delta_callback = None
+    agent.tool_progress_callback = None
+    agent.tool_gen_callback = None
+
+    _last_reasoning_text = None
+
+    def on_reasoning(text: str) -> None:
+        nonlocal _last_reasoning_text
+        stripped = (text or "").strip()
+        if stripped and stripped != _last_reasoning_text:
+            _last_reasoning_text = stripped
+            emit({
+                "type": "item.completed",
+                "item": {"type": "reasoning", "text": stripped},
+            })
+
+    def on_tool_start(call_id: str, name: str, arguments) -> None:
+        cmd = ""
+        if isinstance(arguments, dict):
+            cmd = (
+                arguments.get("command", "")
+                or arguments.get("code", "")
+                or arguments.get("query", "")
+                or ""
+            )
+        emit({
+            "type": "item.started",
+            "item": {
+                "type": name,
+                "id": call_id or f"{name}-started",
+                "command": str(cmd)[:2000] if cmd else None,
+            },
+        })
+
+    def on_tool_complete(call_id: str, name: str, arguments, result: str) -> None:
+        emit({
+            "type": "item.completed",
+            "item": {
+                "type": name,
+                "id": call_id or f"{name}-completed",
+                "status": "completed",
+                "aggregated_output": (result or "")[:6000],
+            },
+        })
+
+    agent.reasoning_callback = on_reasoning
+    agent.tool_start_callback = on_tool_start
+    agent.tool_complete_callback = on_tool_complete
+
+    # ── Emit initial session meta ────────────────────────────────────────
+    emit({"type": "session_meta", "payload": {"id": cli.session_id}})
+
+    # ── Run conversation ─────────────────────────────────────────────────
+    failed = False
+    response = ""
+    result_error = ""
+    result_partial = False
+    result_completed = True
+    try:
+        result = agent.run_conversation(
+            user_message=args.prompt,
+            conversation_history=cli.conversation_history,
+        )
+        debug_log("run_conversation_result", {"result": result})
+        if isinstance(result, dict):
+            response = result.get("final_response", "") or ""
+            failed = result.get("failed", False)
+            result_partial = bool(result.get("partial", False))
+            if "completed" in result:
+                result_completed = bool(result.get("completed"))
+            raw_error = result.get("error")
+            if isinstance(raw_error, str):
+                result_error = raw_error.strip()
+            elif raw_error is not None:
+                result_error = str(raw_error).strip()
+        else:
+            response = str(result) if result else ""
+    except Exception as exc:
+        emit({"type": "error", "error": f"Hermes execution failed: {exc}"})
+        sys.exit(1)
+
+    # ── Emit final agent message event (consumed but filtered by CLAPS) ─
+    if response:
+        emit({
+            "type": "item.completed",
+            "item": {"type": "agent_message", "content": response},
+        })
+
+    should_fail = failed or (
+        not response.strip() and (result_partial or not result_completed or bool(result_error))
+    )
+
+    if should_fail:
+        emit({
+            "type": "error",
+            "error": result_error or "Hermes returned an incomplete result without a final response.",
+        })
+
+    # ── Emit closing session meta (session_id may update on resume) ──────
+    emit({"type": "session_meta", "payload": {"id": cli.session_id}})
+
+    # ── Write clean response to output file ──────────────────────────────
+    if args.output:
+        try:
+            with open(args.output, "w", encoding="utf-8") as f:
+                f.write(response)
+        except OSError as exc:
+            print(f"[adapter] failed to write output file: {exc}", file=sys.stderr)
+
+    sys.exit(1 if should_fail else 0)
+
+
+if __name__ == "__main__":
+    main()