ags-cli 0.1.0__py3-none-any.whl

harness/adapters/local_openai.py

@@ -0,0 +1,534 @@
+"""OpenAI-compatible adapter — local **or** remote.
+
+Targets any ``/v1/chat/completions`` endpoint, whether self-hosted (Ollama, LM Studio,
+vLLM, LocalAI) or a remote SaaS (OpenAI, Groq, OpenRouter, Together, Azure OpenAI). Every
+endpoint quirk is driven from ``config.params`` so a new provider needs only a
+``config.yaml`` entry — no code:
+
+- ``headers``      static extra headers (e.g. ``OpenAI-Organization``, OpenRouter ``X-Title``)
+- ``auth_header`` / ``auth_prefix``   where/how the resolved secret is sent
+  (default ``Authorization`` + ``"Bearer "``; Azure → ``api-key`` + ``""``)
+- ``query``        extra query params on the request URL (e.g. Azure ``api-version``)
+- ``extra_body``   arbitrary request-body params (``top_p``, ``stop``, ``seed``, …)
+- ``timeout_s``    read timeout override
+- ``temperature``/``max_tokens``/``max_context``/``reasoning``   common knobs
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import time
+from collections.abc import AsyncIterator
+
+import httpx
+from harness_sdk.base import (
+    AdapterConfig,
+    BaseAdapter,
+    Capabilities,
+    Cost,
+    HealthStatus,
+    ProviderSession,
+    SessionContext,
+    Usage,
+)
+from harness_sdk.events import (
+    AdapterMetaEvent,
+    CostEvent,
+    ErrorEvent,
+    MessageEvent,
+    NormalizedEvent,
+    StatusEvent,
+    TokenEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+)
+
+from harness.models.enums import AdapterKind
+
+# read = max idle between bytes (so a non-responding endpoint fails in ~2 min, not 5+);
+# a streaming model emits chunks well within this. Override per-provider via params.timeout_s.
+DEFAULT_TIMEOUT = httpx.Timeout(connect=10.0, read=120.0, write=30.0, pool=10.0)
+_MAX_TOOL_ROUNDS = 40  # cap the agentic loop so a misbehaving model can't spin forever
+
+
+class OpenAICompatibleLocalAdapter(BaseAdapter):
+    kind = AdapterKind.openai_local
+
+    def __init__(self, config: AdapterConfig) -> None:
+        super().__init__(config)
+        self._base_url = (config.base_url or "http://localhost:11434/v1").rstrip("/")
+        self._cancelled: set[str] = set()
+
+    def _headers(self) -> dict[str, str]:
+        params = self.config.params
+        headers = {"Content-Type": "application/json"}
+        # Static custom headers (e.g. OpenAI-Organization, OpenRouter HTTP-Referer/X-Title).
+        headers.update(params.get("headers") or {})
+        # Resolve the secret into a configurable auth header. Defaults to OpenAI's
+        # ``Authorization: Bearer <key>``; Azure uses ``auth_header: api-key`` + empty prefix.
+        if self.config.api_key:
+            name = params.get("auth_header", "Authorization")
+            prefix = params.get("auth_prefix", "Bearer ")
+            headers[name] = f"{prefix}{self.config.api_key}"
+        return headers
+
+    def _timeout(self) -> httpx.Timeout:
+        """Per-request timeout: ``params.timeout_s`` overrides only the read timeout."""
+        ts = self.config.params.get("timeout_s")
+        if ts is None:
+            return DEFAULT_TIMEOUT
+        return httpx.Timeout(connect=10.0, read=float(ts), write=30.0, pool=10.0)
+
+    def _build_messages(self, ctx_system: str | None, memory: str, message: str) -> list[dict]:
+        msgs: list[dict] = []
+        system_parts = [p for p in (ctx_system, memory) if p]
+        if system_parts:
+            msgs.append({"role": "system", "content": "\n\n".join(system_parts)})
+        msgs.append({"role": "user", "content": message})
+        return msgs
+
+    async def start_session(self, ctx: SessionContext) -> ProviderSession:
+        # OpenAI-compatible endpoints are stateless; we carry context per-message.
+        return ProviderSession(
+            provider_session_id=f"local-{ctx.run_id}",
+            adapter_kind=self.kind,
+            meta={
+                "system_prompt": ctx.system_prompt,
+                "memory_context": ctx.memory_context,
+                # Project context for the agentic file-tool loop (used only when the
+                # provider advertises tool_calling and a project dir is set).
+                "workspace_dir": ctx.workspace_dir,
+                "read_only": ctx.read_only,
+                "trust_policy": ctx.trust_policy,
+                # MCP servers offered to this run (resolved by the engine). The harness
+                # is the MCP client here (this endpoint has no native MCP support).
+                "mcp_servers": ctx.extra.get("mcp_servers", []),
+            },
+        )
+
+    async def stream_events(
+        self,
+        session: ProviderSession,
+        message: str,
+        *,
+        tools: list[dict] | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[NormalizedEvent]:
+        run_id = session.provider_session_id.removeprefix("local-")
+        seq = itertools.count()
+        messages = self._build_messages(
+            session.meta.get("system_prompt"),
+            session.meta.get("memory_context", ""),
+            message,
+        )
+        # Agentic tool loop: when the provider advertises tool_calling AND there is
+        # something to call — a project dir (file tools) and/or MCP servers. Otherwise
+        # behave as a plain chat endpoint.
+        use_tools = bool(
+            self.list_capabilities().tool_calling
+            and (session.meta.get("workspace_dir") or session.meta.get("mcp_servers"))
+        )
+
+        yield StatusEvent(seq=next(seq), status="running")
+        # A terminal status (needs_approval / cancelled) yielded mid-stream means the
+        # loop already ended for a specific reason — the unconditional "succeeded"
+        # below must not overwrite it.
+        already_terminal = False
+        try:
+            if use_tools:
+                async for ev in self._agentic_loop(messages, session, seq):
+                    if ev.type == "status" and ev.status in ("needs_approval", "cancelled"):
+                        already_terminal = True
+                    yield ev
+            elif stream:
+                async for ev in self._stream(self._payload(messages, stream=True), run_id, seq):
+                    if ev.type == "status" and ev.status == "cancelled":
+                        already_terminal = True
+                    yield ev
+            else:
+                async for ev in self._complete(self._payload(messages, stream=False), seq):
+                    yield ev
+        except httpx.HTTPError as exc:
+            yield ErrorEvent(seq=next(seq), message=f"local llm error: {exc}", retriable=True)
+            return
+        if not already_terminal:
+            yield StatusEvent(seq=next(seq), status="succeeded")
+
+    def _payload(
+        self, messages: list[dict], *, stream: bool, tools: list[dict] | None = None
+    ) -> dict:
+        """Build a /chat/completions body, applying the configured knobs."""
+        p = self.config.params
+        payload: dict = {
+            "model": self.config.model or "llama3.1",
+            "messages": messages,
+            "stream": stream,
+            "temperature": p.get("temperature", 0.2),
+        }
+        if (mt := p.get("max_tokens")) is not None:
+            payload["max_tokens"] = mt
+        if (reasoning := p.get("reasoning")) is not None:
+            payload["reasoning"] = reasoning
+        if (extra := p.get("extra_body")):
+            payload.update(extra)  # top_p, stop, seed, … (can override defaults above)
+        if stream and p.get("stream_usage", True):
+            payload["stream_options"] = {"include_usage": True}
+        if tools:
+            payload["tools"] = tools
+        return payload
+
+    async def _post_json(self, payload: dict) -> dict:
+        async with httpx.AsyncClient(timeout=self._timeout()) as client:
+            resp = await client.post(
+                f"{self._base_url}/chat/completions",
+                headers=self._headers(),
+                params=self.config.params.get("query"),
+                json=payload,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    async def _agentic_loop(
+        self, messages: list[dict], session: ProviderSession, seq
+    ) -> AsyncIterator[NormalizedEvent]:
+        """Drive a tool-calling model over the project files and/or MCP servers,
+        executing each tool call in the harness and feeding results back, until the
+        model returns a final answer (or the round cap is hit). Streams text while
+        accumulating tool calls, then executes tools synchronously between rounds."""
+        from harness.mcp.registry import McpManager
+        from harness.models.enums import TrustPolicy
+        from harness.tools.fs_tools import FileTools, tool_specs
+
+        run_id = session.provider_session_id
+        workspace_dir = session.meta.get("workspace_dir")
+        fs = (
+            FileTools(
+                workspace_dir, session.meta.get("read_only", True),
+                trust_policy=TrustPolicy(session.meta.get("trust_policy", "restricted")),
+            )
+            if workspace_dir else None
+        )
+        specs = tool_specs(fs.read_only) if fs else []
+
+        # Connect the run's MCP servers (the harness is the MCP client here). Failures
+        # are soft: an unreachable server / missing SDK just contributes no tools.
+        mcp = McpManager(session.meta.get("mcp_servers") or [])
+        try:
+            await mcp.connect()
+            specs = specs + await mcp.specs()
+        except Exception as exc:  # never sink the run on MCP setup
+            yield ErrorEvent(seq=next(seq), message=f"mcp setup: {exc}", retriable=False)
+
+        try:
+            async for ev in self._tool_rounds(messages, specs, fs, mcp, run_id, seq):
+                yield ev
+        finally:
+            await mcp.aclose()
+
+    async def _tool_rounds(
+        self, messages, specs, fs, mcp, run_id, seq
+    ) -> AsyncIterator[NormalizedEvent]:
+        from harness.mcp.tools import is_mcp_tool
+        from harness.security.approval_policy import ApprovalRequired
+
+        executed_tools: list[tuple[str, bool]] = []  # (name, is_error), in call order
+
+        for _ in range(_MAX_TOOL_ROUNDS):
+            payload = self._payload(messages, stream=True, tools=specs)
+            collected_text: list[str] = []
+            tool_calls: dict[int, dict] = {}
+            usage: dict | None = None
+
+            async with httpx.AsyncClient(timeout=self._timeout()) as client, client.stream(
+                "POST",
+                f"{self._base_url}/chat/completions",
+                headers=self._headers(),
+                params=self.config.params.get("query"),
+                json=payload,
+            ) as resp:
+                resp.raise_for_status()
+                async for line in resp.aiter_lines():
+                    if run_id in self._cancelled:
+                        yield StatusEvent(seq=next(seq), status="cancelled")
+                        return
+                    if not line or not line.startswith("data:"):
+                        continue
+                    data = line[len("data:"):].strip()
+                    if data == "[DONE]":
+                        break
+                    try:
+                        chunk = json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+
+                    if (u := chunk.get("usage")):
+                        usage = u
+
+                    delta = (chunk.get("choices") or [{}])[0].get("delta", {})
+
+                    # Reasoning models stream their chain-of-thought separately
+                    # (delta.reasoning / reasoning_content). Surface it live so the
+                    # GUI shows activity, but keep it out of the stored answer.
+                    if (rsn := delta.get("reasoning") or delta.get("reasoning_content")):
+                        yield TokenEvent(seq=next(seq), text=rsn, reasoning=True)
+
+                    if (content := delta.get("content")):
+                        collected_text.append(content)
+                        yield TokenEvent(seq=next(seq), text=content)
+
+                    # Accumulate streamed tool calls
+                    if (tcs := delta.get("tool_calls")):
+                        for tc in tcs:
+                            idx = tc.get("index", 0)
+                            if idx not in tool_calls:
+                                tool_calls[idx] = {"id": tc.get("id"), "type": "function", "function": {"name": "", "arguments": ""}}
+                            fn = tc.get("function", {})
+                            if (name := fn.get("name")):
+                                tool_calls[idx]["function"]["name"] += name
+                            if (args := fn.get("arguments")):
+                                tool_calls[idx]["function"]["arguments"] += args
+
+            final_text = "".join(collected_text)
+            final_calls = list(tool_calls.values())
+
+            # Emit final message if there was text
+            if final_text:
+                yield MessageEvent(seq=next(seq), role="assistant", text=final_text)
+            if usage:
+                yield CostEvent(
+                    seq=next(seq),
+                    prompt_tokens=usage.get("prompt_tokens", 0),
+                    completion_tokens=usage.get("completion_tokens", 0),
+                    total_tokens=usage.get("total_tokens", 0),
+                )
+
+            if not final_calls:
+                # No tool calls requested; we are done. Small local models often
+                # execute a tool successfully and then simply stop instead of
+                # narrating the result — without this, the run ends "succeeded"
+                # with an empty transcript, which looks indistinguishable from a
+                # hang. Leave a trace of what actually happened instead.
+                if not final_text and executed_tools:
+                    yield MessageEvent(
+                        seq=next(seq), role="assistant",
+                        text=_default_completion_message(executed_tools),
+                    )
+                return
+
+            # Echo the assistant's turn back to messages
+            assistant_msg: dict = {"role": "assistant"}
+            if final_text:
+                assistant_msg["content"] = final_text
+            if final_calls:
+                assistant_msg["tool_calls"] = final_calls
+            messages.append(assistant_msg)
+
+            # Execute each tool and append results
+            for tc in final_calls:
+                fn = tc.get("function", {})
+                name = fn.get("name", "")
+                args_raw = fn.get("arguments", "{}")
+                args = _safe_json(args_raw)
+
+                yield ToolCallEvent(seq=next(seq), name=name, arguments=args, call_id=tc.get("id"))
+                if is_mcp_tool(name):
+                    output, is_error = await mcp.dispatch(name, args)
+                elif fs is not None:
+                    try:
+                        output, is_error = fs.execute(name, args)
+                    except ApprovalRequired as exc:
+                        reason = exc.decision.reason
+                        yield ToolResultEvent(
+                            seq=next(seq), call_id=tc.get("id"),
+                            output=f"paused: {reason}", is_error=False,
+                        )
+                        yield AdapterMetaEvent(seq=next(seq), data={"approval_request": {
+                            "tool_name": exc.tool_name,
+                            "arguments": exc.tool_args,
+                            "action_class": (
+                                exc.decision.action_class.value
+                                if exc.decision.action_class else None
+                            ),
+                            "reason": reason,
+                            "workspace_dir": str(fs.root),
+                            "provider": self.config.name,
+                        }})
+                        yield StatusEvent(seq=next(seq), status="needs_approval", detail=reason)
+                        return
+                else:
+                    output, is_error = f"error: unknown tool {name!r}", True
+                yield ToolResultEvent(
+                    seq=next(seq), call_id=tc.get("id"), output=output, is_error=is_error
+                )
+                executed_tools.append((name, is_error))
+
+                messages.append(
+                    {"role": "tool", "tool_call_id": tc.get("id"), "content": output}
+                )
+
+        yield MessageEvent(
+            seq=next(seq), role="assistant",
+            text=f"(stopped after {_MAX_TOOL_ROUNDS} tool rounds without a final answer)",
+        )
+
+    async def _stream(self, payload, run_id, seq) -> AsyncIterator[NormalizedEvent]:
+        collected: list[str] = []
+        usage: dict | None = None
+        async with httpx.AsyncClient(timeout=self._timeout()) as client, client.stream(
+            "POST",
+            f"{self._base_url}/chat/completions",
+            headers=self._headers(),
+            params=self.config.params.get("query"),
+            json=payload,
+        ) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if run_id in self._cancelled:
+                    yield StatusEvent(seq=next(seq), status="cancelled")
+                    return
+                if not line or not line.startswith("data:"):
+                    continue
+                data = line[len("data:"):].strip()
+                if data == "[DONE]":
+                    break
+                chunk = json.loads(data)
+                if (u := chunk.get("usage")):
+                    usage = u  # final usage chunk (typically carries empty choices)
+                delta = (chunk.get("choices") or [{}])[0].get("delta", {})
+                # Reasoning ("thinking") deltas: stream live but exclude from the answer.
+                if (rsn := delta.get("reasoning") or delta.get("reasoning_content")):
+                    yield TokenEvent(seq=next(seq), text=rsn, reasoning=True)
+                if (content := delta.get("content")):
+                    collected.append(content)
+                    yield TokenEvent(seq=next(seq), text=content)
+                for tc in delta.get("tool_calls", []) or []:
+                    fn = tc.get("function", {})
+                    yield ToolCallEvent(
+                        seq=next(seq),
+                        name=fn.get("name", ""),
+                        arguments=_safe_json(fn.get("arguments", "{}")),
+                        call_id=tc.get("id"),
+                    )
+        if collected:
+            yield MessageEvent(seq=next(seq), role="assistant", text="".join(collected))
+        if usage:
+            yield CostEvent(
+                seq=next(seq),
+                prompt_tokens=usage.get("prompt_tokens", 0),
+                completion_tokens=usage.get("completion_tokens", 0),
+                total_tokens=usage.get("total_tokens", 0),
+            )
+
+    async def _complete(self, payload, seq) -> AsyncIterator[NormalizedEvent]:
+        async with httpx.AsyncClient(timeout=self._timeout()) as client:
+            resp = await client.post(
+                f"{self._base_url}/chat/completions",
+                headers=self._headers(),
+                params=self.config.params.get("query"),
+                json=payload,
+            )
+            resp.raise_for_status()
+            body = resp.json()
+        choice = (body.get("choices") or [{}])[0]
+        text = choice.get("message", {}).get("content", "") or ""
+        yield MessageEvent(seq=next(seq), role="assistant", text=text)
+        if (usage := body.get("usage")):
+            yield CostEvent(
+                seq=next(seq),
+                prompt_tokens=usage.get("prompt_tokens", 0),
+                completion_tokens=usage.get("completion_tokens", 0),
+                total_tokens=usage.get("total_tokens", 0),
+            )
+
+    async def cancel_run(self, run_id: str) -> None:
+        self._cancelled.add(run_id)
+
+    def list_capabilities(self) -> Capabilities:
+        caps = self.config.capabilities
+        return Capabilities(
+            streaming=caps.get("streaming", True),
+            tool_calling=caps.get("tool_calling", False),
+            max_context=int(self.config.params.get("max_context", 8192)),
+            reasoning=caps.get("reasoning", False),
+            cost_known=False,
+            notes="OpenAI-compatible endpoint (local or remote).",
+        )
+
+    async def _probe_url(self, url: str) -> tuple[bool, float, dict]:
+        start = time.perf_counter()
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(2.0)) as client:
+                resp = await client.get(f"{url}/models", headers=self._headers())
+                if resp.status_code < 500:
+                    elapsed_ms = (time.perf_counter() - start) * 1000
+                    return True, elapsed_ms, {"status_code": resp.status_code}
+        except httpx.HTTPError:
+            pass
+        return False, 0.0, {}
+
+    async def health_check(self) -> HealthStatus:
+        ok, latency, detail = await self._probe_url(self._base_url)
+        if ok:
+            return HealthStatus(ok=True, latency_ms=latency, detail=detail)
+
+        # Fallback detection
+        import urllib.parse
+        try:
+            parsed = urllib.parse.urlparse(self._base_url)
+            if parsed.hostname in ("localhost", "127.0.0.1"):
+                common_ports = [11434, 1234, 8000, 8080]
+                for port in common_ports:
+                    fallback_url = f"{parsed.scheme}://{parsed.hostname}:{port}/v1"
+                    if fallback_url == self._base_url:
+                        continue
+                    ok, latency, detail = await self._probe_url(fallback_url)
+                    if ok:
+                        self._base_url = fallback_url
+                        detail["auto_detected_url"] = fallback_url
+                        return HealthStatus(ok=True, latency_ms=latency, detail=detail)
+        except Exception as exc:
+            return HealthStatus(ok=False, detail={"error": str(exc)})
+
+        return HealthStatus(ok=False, detail={"error": "endpoint unreachable"})
+
+    async def list_models(self) -> list[str]:
+        """Enumerate models via the OpenAI-compatible ``GET /v1/models`` endpoint
+        (supported by Ollama, LM Studio, vLLM, LocalAI, …)."""
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
+                resp = await client.get(f"{self._base_url}/models", headers=self._headers())
+                resp.raise_for_status()
+                data = resp.json().get("data", [])
+        except (httpx.HTTPError, ValueError):
+            return [self.config.model] if self.config.model else []
+        models = [m.get("id") for m in data if isinstance(m, dict) and m.get("id")]
+        return models or ([self.config.model] if self.config.model else [])
+
+    def estimate_cost(self, usage: Usage) -> Cost | None:
+        # Local inference is free at the API boundary; report tokens, usd=0.
+        return Cost(
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            total_tokens=usage.prompt_tokens + usage.completion_tokens,
+            usd=0.0,
+        )
+
+
+def _safe_json(raw: str) -> dict:
+    try:
+        return json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        return {"_raw": raw}
+
+
+def _default_completion_message(executed: list[tuple[str, bool]]) -> str:
+    """Synthesized narration for a tool round that ends with no assistant text."""
+    ok = list(dict.fromkeys(n for n, is_error in executed if not is_error))
+    failed = list(dict.fromkeys(n for n, is_error in executed if is_error))
+    parts = []
+    if ok:
+        parts.append("ran " + ", ".join(f"`{n}`" for n in ok))
+    if failed:
+        parts.append(", ".join(f"`{n}`" for n in failed) + " failed")
+    return ("Done — " + "; ".join(parts) + ".") if parts else "Done."

harness/adapters/mock.py

@@ -0,0 +1,112 @@
+"""Deterministic mock adapter — the reference implementation and CI workhorse.
+
+Produces a predictable token stream, a cost event, and a final message without
+any network access, so the orchestrator, ledger, memory, and contract tests can
+run fully offline. Behaviour is tunable via ``params`` (``latency_ms``, ``tokens``,
+``fail``)."""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+from collections.abc import AsyncIterator
+
+from harness_sdk.base import (
+    AdapterConfig,
+    BaseAdapter,
+    Capabilities,
+    Cost,
+    HealthStatus,
+    ProviderSession,
+    SessionContext,
+    Usage,
+)
+from harness_sdk.events import (
+    CostEvent,
+    ErrorEvent,
+    MessageEvent,
+    NormalizedEvent,
+    StatusEvent,
+    TokenEvent,
+)
+
+from harness.models.enums import AdapterKind
+
+
+class MockAdapter(BaseAdapter):
+    kind = AdapterKind.mock
+
+    def __init__(self, config: AdapterConfig) -> None:
+        super().__init__(config)
+        self._cancelled: set[str] = set()
+
+    async def start_session(self, ctx: SessionContext) -> ProviderSession:
+        return ProviderSession(
+            provider_session_id=f"mock-{ctx.run_id}",
+            adapter_kind=self.kind,
+            meta={"objective": ctx.objective},
+        )
+
+    async def stream_events(
+        self,
+        session: ProviderSession,
+        message: str,
+        *,
+        tools: list[dict] | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[NormalizedEvent]:
+        params = self.config.params
+        run_id = session.provider_session_id.removeprefix("mock-")
+        seq = itertools.count()
+
+        if params.get("fail"):
+            yield ErrorEvent(seq=next(seq), message="mock forced failure", retriable=False)
+            return
+
+        yield StatusEvent(seq=next(seq), status="running")
+
+        n_tokens = int(params.get("tokens", 40))
+        latency = float(params.get("latency_ms", 50)) / 1000.0
+        words = (
+            f"[mock:{self.config.model or 'mock-1'}] response to: "
+            f"{message[:80]}"
+        ).split()
+        emitted: list[str] = []
+        for i in range(min(n_tokens, max(len(words), 8))):
+            if run_id in self._cancelled:
+                yield StatusEvent(seq=next(seq), status="cancelled")
+                return
+            tok = (words[i] if i < len(words) else f"tok{i}") + " "
+            emitted.append(tok)
+            yield TokenEvent(seq=next(seq), text=tok)
+            await asyncio.sleep(latency / max(n_tokens, 1))
+
+        final = "".join(emitted).strip()
+        yield MessageEvent(seq=next(seq), role="assistant", text=final)
+        yield CostEvent(
+            seq=next(seq),
+            prompt_tokens=len(message.split()),
+            completion_tokens=len(emitted),
+            total_tokens=len(message.split()) + len(emitted),
+        )
+        yield StatusEvent(seq=next(seq), status="succeeded")
+
+    async def cancel_run(self, run_id: str) -> None:
+        self._cancelled.add(run_id)
+
+    def list_capabilities(self) -> Capabilities:
+        return Capabilities(
+            streaming=True, tool_calling=False, max_context=8192, cost_known=False,
+            notes="Deterministic offline mock.",
+        )
+
+    async def health_check(self) -> HealthStatus:
+        return HealthStatus(ok=True, latency_ms=1.0, detail={"adapter": "mock"})
+
+    def estimate_cost(self, usage: Usage) -> Cost | None:
+        return Cost(
+            prompt_tokens=usage.prompt_tokens,
+            completion_tokens=usage.completion_tokens,
+            total_tokens=usage.prompt_tokens + usage.completion_tokens,
+            usd=0.0,
+        )