diff --git a/.github/workflows/guardian-reusable.yml b/.github/workflows/guardian-reusable.yml index e0069648..069d1152 100644 --- a/.github/workflows/guardian-reusable.yml +++ b/.github/workflows/guardian-reusable.yml @@ -13,13 +13,25 @@ name: Guardian Review (reusable) # secrets: # ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # GUARDIAN_APP_PRIVATE_KEY: ${{ secrets.GUARDIAN_APP_PRIVATE_KEY }} -# permissions: {contents: read, pull-requests: write, issues: write} +# permissions: {contents: read, pull-requests: write, issues: write, id-token: write} # # `secrets: inherit` reaches a called workflow only within one organisation or # enterprise; any other caller passes the secrets declared below by name. # Variables are always the caller's: GUARDIAN_PROVIDER, GUARDIAN_MODEL, -# GUARDIAN_ANTHROPIC_EFFORT, GUARDIAN_FEATURES, GUARDIAN_SKEPTIC, -# GUARDIAN_SKEPTIC_MODEL, GUARDIAN_APP_CLIENT_ID. +# GUARDIAN_OPENCODE_EFFORT, GUARDIAN_FEATURES, GUARDIAN_SKEPTIC, +# GUARDIAN_SKEPTIC_MODEL, OPENCODE_CLIENT_ID, GUARDIAN_APP_CLIENT_ID. +# +# The opencode-go finder needs no static key: the job exchanges a GitHub OIDC +# token for a short-lived inference token immediately before the review (#775). +# The caller grants `id-token: write` and sets its own OPENCODE_CLIENT_ID +# variable, and OIDC access must be enabled for GitHub Actions in the Opencode +# console. Sign-in happens only when the normalised GUARDIAN_PROVIDER is +# `opencode-go`, `opencode` or empty; an empty value still signs in because the +# minted OPENCODE_API_KEY then makes `_autodetect_provider` pick opencode. An +# explicit other provider logs that OpenCode is not selected and skips cleanly. +# The workflow declares no OPENCODE_API_KEY secret, and the review step must +# not set that variable: a step-level value overrides GITHUB_ENV and would +# discard the minted token. # # The caller's Actions policy must allow this workflow and the actions it uses # (actions/*, astral-sh/setup-uv, peter-evans/create-or-update-comment). @@ -59,6 +71,9 @@ on: type: boolean default: false secrets: + # `ANTHROPIC_API_KEY` stays declared and passed so existing callers keep + # working; opencode-go does not require it. There is deliberately no + # OPENCODE_API_KEY secret: the token is minted from GitHub OIDC below. ANTHROPIC_API_KEY: required: false GEMINI_API_KEY: @@ -80,6 +95,9 @@ jobs: contents: read pull-requests: write issues: write + # Required to request the OIDC token the OpenCode sign-in exchanges + # (#775). A reusable workflow cannot ask for more than the caller grants. + id-token: write steps: # Here rather than in each caller, so no caller can forget it. @@ -245,17 +263,92 @@ jobs: repositories: ${{ github.event.repository.name }} permission-pull-requests: write + # Minted immediately before the review and only after every step that + # touches the PR checkout, exactly like the App token above (#730, #775): + # the token is short-lived and the code it reviews never sees it. The + # value goes to GITHUB_ENV, which the review step inherits. + - name: Sign in to OpenCode (OIDC) + if: vars.OPENCODE_CLIENT_ID != '' + env: + AUDIENCE: https://opencode.ai/console + CLIENT_ID: ${{ vars.OPENCODE_CLIENT_ID }} + GUARDIAN_PROVIDER: ${{ vars.GUARDIAN_PROVIDER }} + run: | + set -euo pipefail + provider=$(printf '%s' "${GUARDIAN_PROVIDER:-}" | tr '[:upper:]' '[:lower:]') + case "$provider" in + ""|opencode-go|opencode) ;; + *) + echo "OpenCode is not the selected provider ($provider); skipping sign-in." + exit 0 + ;; + esac + # No jq: a self-hosted runner may not have it, the same reason #742 + # removed the GitHub CLI dependency. `uv` is installed and the + # environment synced above, so use it rather than assuming `python3` + # is on PATH on a self-hosted runner. + missing="" + [ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || missing="$missing ACTIONS_ID_TOKEN_REQUEST_URL" + [ -n "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ] || missing="$missing ACTIONS_ID_TOKEN_REQUEST_TOKEN" + if [ -n "$missing" ]; then + echo "::error::GitHub OIDC is unavailable:$missing. Grant id-token: write to this job and to the caller's job." + exit 1 + fi + + oidc_response=$(curl -sS -w '\n%{http_code}' \ + --oauth2-bearer "$ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ + "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE") + oidc_status=$(printf '%s' "$oidc_response" | tail -n1) + oidc_body=$(printf '%s' "$oidc_response" | sed '$d') + if [ "$oidc_status" -lt 200 ] || [ "$oidc_status" -ge 300 ]; then + # The OIDC response is not printed: it carries a JWT. + echo "::error::GitHub OIDC token request failed with HTTP $oidc_status." + exit 1 + fi + oidc=$(printf '%s' "$oidc_body" | uv run --frozen python -c 'import json, sys; print(json.load(sys.stdin)["value"])') || { + echo "::error::GitHub OIDC response carried no value field." + exit 1 + } + + token_response=$(curl -sS -w '\n%{http_code}' \ + https://opencode.ai/console/auth/oauth/token \ + -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \ + -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \ + -d client_id="$CLIENT_ID" \ + -d subject_token="$oidc") + token_status=$(printf '%s' "$token_response" | tail -n1) + token_body=$(printf '%s' "$token_response" | sed '$d') + if [ "$token_status" -lt 200 ] || [ "$token_status" -ge 300 ]; then + echo "::error::OpenCode token exchange failed with HTTP $token_status: ${token_body:0:400}" + exit 1 + fi + token=$(printf '%s' "$token_body" | uv run --frozen python -c 'import json, sys; print(json.load(sys.stdin)["access_token"])') || { + echo "::error::OpenCode token exchange returned no access_token." + exit 1 + } + if [ -z "$token" ]; then + echo "::error::OpenCode token exchange returned an empty access_token." + exit 1 + fi + echo "::add-mask::$token" + echo "OPENCODE_API_KEY=$token" >> "$GITHUB_ENV" + - name: Run Guardian Review id: guardian env: + # OPENCODE_API_KEY is deliberately absent: the OIDC step above + # writes it to GITHUB_ENV, and a step-level value would override it. ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }} GUARDIAN_PROVIDER: ${{ vars.GUARDIAN_PROVIDER }} GUARDIAN_MODEL: ${{ vars.GUARDIAN_MODEL }} - # Thinking depth for an anthropic finder or skeptic; unset = the - # provider's default ("low"). #246 J measured the finder at "medium". - GUARDIAN_ANTHROPIC_EFFORT: ${{ vars.GUARDIAN_ANTHROPIC_EFFORT }} + # Reasoning depth for an opencode-go finder; unset = the provider's + # default ("low"). A bad value fails at the gateway, loudly. + GUARDIAN_OPENCODE_EFFORT: ${{ vars.GUARDIAN_OPENCODE_EFFORT }} + # Anthropic stays selectable but is no longer the default finder, so + # GUARDIAN_ANTHROPIC_EFFORT is deliberately not passed here; an + # explicit anthropic pick runs at the provider's own default (#775). GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }} GITHUB_REPOSITORY: ${{ github.repository }} GUARDIAN_FEATURES: ${{ vars.GUARDIAN_FEATURES }} diff --git a/.github/workflows/guardian.yml b/.github/workflows/guardian.yml index e221d225..70c8f3ce 100644 --- a/.github/workflows/guardian.yml +++ b/.github/workflows/guardian.yml @@ -25,6 +25,9 @@ jobs: contents: read pull-requests: write issues: write + # The reusable workflow signs in to OpenCode with GitHub OIDC (#775); a + # called workflow cannot ask for more than its caller grants. + id-token: write save-metrics: needs: review diff --git a/PRIVACY.md b/PRIVACY.md index 1972d6b6..0352af07 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -24,7 +24,7 @@ We do not collect, transmit, store or have access to: your source code, the grap The `codegraph-brain` package also contains **Guardian**, a code reviewer that sends diffs and graph context to a large language model. **Guardian is not part of the Claude Code plugin**: the plugin neither ships nor invokes it, and it does nothing unless you configure it and run it deliberately, normally in CI. -If you choose to use Guardian, you select the model provider yourself — Google Gemini, Mistral, Anthropic (Claude), OpenRouter, or a local Ollama instance — and supply your own credentials. In that case the code being reviewed is sent to whichever provider you chose, under **that provider's** privacy policy and terms, not this one. Choosing Ollama keeps it local. We never see that traffic and never receive a copy. +If you choose to use Guardian, you select the model provider yourself — Google Gemini, Mistral, Anthropic (Claude), OpenRouter, OpenCode Go (DeepSeek), or a local Ollama instance — and supply your own credentials. In that case the code being reviewed is sent to whichever provider you chose, under **that provider's** privacy policy and terms, not this one. Choosing Ollama keeps it local. We never see that traffic and never receive a copy. Credentials for those providers are read from your environment and used only to call the provider they belong to. They are not logged, stored or transmitted anywhere else. diff --git a/README.md b/README.md index eaac3e85..b46aaa50 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ The details — and a pipeline graph CGIS regenerates from its own source on eve **Guardian** is CGIS's built-in LLM reviewer — it reviews pull requests using the *graph* as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line. * **Two-stage, recall-first:** a **finder** surfaces every plausible defect (optimised for recall), then a separate **skeptic** pass filters false positives — closer to how human reviewers work, and far more reliable than a single precision-gated prompt. -* **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini / Claude** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic. +* **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini / Claude / OpenCode Go (DeepSeek)** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic. * **Graph-aware context:** the reviewer sees impact graphs, architectural drift, and project ontology — so it catches structural and convention defects a flat-diff reviewer can't. * **Deterministic anchoring:** every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess. * **Dogfooded & measured:** Guardian reviews CGIS's *own* pull requests, and a benchmark harness scores it against curated ground truth — so prompt changes are validated, not guessed. @@ -149,6 +149,13 @@ cgis ingest ./src --output graph.db GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \ uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline +# Or OpenCode Go / DeepSeek: deepseek-v4.1-flash unless GUARDIAN_MODEL names another. +# GUARDIAN_OPENCODE_EFFORT is low unless set (the catalog lists low|high|max; other values +# pass through to the gateway). GUARDIAN_OPENCODE_BASE_URL pins a different gateway. +# No ANTHROPIC_API_KEY is needed for this provider. +GUARDIAN_PROVIDER=opencode-go GUARDIAN_MODEL=deepseek-v4.1-flash OPENCODE_API_KEY=... \ + uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline + # Or a Claude skeptic over a Mistral finder: Claude Haiku 5.5 unless GUARDIAN_SKEPTIC_MODEL names # another, at GUARDIAN_ANTHROPIC_EFFORT=low unless set (low|medium|high|xhigh|max). Claude models # reject a sampling temperature, so GUARDIAN_TEMPERATURE must be unset. @@ -156,6 +163,8 @@ GUARDIAN_SKEPTIC=anthropic ANTHROPIC_API_KEY=... MISTRAL_API_KEY=... \ uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline ``` +In GitHub Actions, opencode-go needs no static key: the reusable workflow exchanges a short-lived GitHub OIDC token for inference access immediately before the review. Enable OIDC for GitHub Actions in the Opencode console, set the calling repository's `OPENCODE_CLIENT_ID` variable, and grant the review job `id-token: write`. `OPENCODE_API_KEY` is then minted at run time and never stored as a secret. Sign-in happens when `GUARDIAN_PROVIDER` is `opencode-go`, `opencode`, or unset (unset means the minted key makes opencode the auto-detected provider); an explicit other provider skips it. + No GPU on hand? **[Benchmark it on a notebook GPU →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt. --- diff --git a/src/cgis/guardian/providers/base.py b/src/cgis/guardian/providers/base.py index ee24ab40..b9156cc0 100644 --- a/src/cgis/guardian/providers/base.py +++ b/src/cgis/guardian/providers/base.py @@ -87,7 +87,7 @@ def __init_subclass__(cls, **kwargs: object) -> None: _msg = ( f"{cls.__name__} must declare `name: ClassVar[str]` — one of the " 'GUARDIAN_PROVIDER values: "gemini", "mistral", "ollama", "openrouter", ' - '"anthropic". Add ' + '"opencode", "anthropic". Add ' f'`name: ClassVar[str] = "..."` as the first line of ' f"{cls.__name__}'s class body." ) diff --git a/src/cgis/guardian/providers/openai_compatible.py b/src/cgis/guardian/providers/openai_compatible.py new file mode 100644 index 00000000..70dfe796 --- /dev/null +++ b/src/cgis/guardian/providers/openai_compatible.py @@ -0,0 +1,88 @@ +"""Shared request plumbing for OpenAI-compatible providers (#246, #775). + +OpenRouter and OpenCode Go speak the same chat-completions shape, so the +prompt, budget, temperature and schema handling live here once. A change to +that contract moves both providers; only the endpoint, headers, error handling +and the reasoning knob remain provider-specific. +""" + +from abc import ABC, abstractmethod +from typing import Any, ClassVar + +from pydantic import BaseModel + +from cgis.guardian.providers.base import BaseProvider + + +class OpenAICompatibleProvider(BaseProvider, ABC): + """A model reached through an OpenAI-shaped chat-completions API.""" + + #: Concrete subclasses declare their own `name`; this intermediate stays + #: abstract (`_post` and `_reasoning_payload` are still unimplemented), so + #: `BaseProvider.__init_subclass__` does not demand one here. + name: ClassVar[str] + + def __init__( + self, + api_key: str, + model_name: str, + timeout: float, + max_tokens: int, + temperature: float | None, + ) -> None: + """Store the settings every OpenAI-compatible provider sends. + + `temperature` is None by default and then not sent at all, leaving the + model's own value in place — the rule every sampled provider here + follows, so an unset knob never becomes a value this project invented + and could not describe afterwards. + """ + super().__init__() + self._api_key = api_key + self._model_name = model_name + self._timeout = timeout + self._max_tokens = max_tokens + self._temperature = temperature + + @abstractmethod + async def _post(self, payload: dict[str, Any]) -> str: + """Send one completion; return the message content or raise.""" + + @abstractmethod + def _payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]: + """The full request body; each provider adds its own reasoning knob.""" + + def _shared_payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]: + """The fields both providers send: model, prompt, budget, temperature.""" + payload: dict[str, Any] = { + "model": self._model_name, + "messages": [ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": user_prompt}, + ], + "max_tokens": self._max_tokens, + } + # `is not None`, not truthiness: 0.0 is the one temperature that states + # something, and a falsy test would drop exactly that value. + if self._temperature is not None: + payload["temperature"] = self._temperature + return payload + + async def generate_content(self, system_prompt: str, user_prompt: str) -> str: + """Free-text generation.""" + return await self._retry(lambda: self._post(self._payload(system_prompt, user_prompt))) + + async def generate_structured( + self, system_prompt: str, user_prompt: str, schema: type[BaseModel] + ) -> str: + """Generation asked to conform to `schema`; returns raw JSON text.""" + payload = self._payload(system_prompt, user_prompt) + payload["response_format"] = { + "type": "json_schema", + "json_schema": { + "name": schema.__name__, + "strict": True, + "schema": schema.model_json_schema(), + }, + } + return await self._retry(lambda: self._post(payload)) diff --git a/src/cgis/guardian/providers/opencode.py b/src/cgis/guardian/providers/opencode.py new file mode 100644 index 00000000..30eb09cd --- /dev/null +++ b/src/cgis/guardian/providers/opencode.py @@ -0,0 +1,210 @@ +"""OpenCode Go provider — DeepSeek through an OpenAI-compatible gateway (#775). + +Guardian used to spend a second credential and a second bill on Anthropic for +the finder, while the rest of the stack already reached opencode-go. The +gateway is OpenAI-shaped, so `providers/openrouter.py` is the template: httpx, +an explicit token budget and temperature, and transport failures that raise +rather than degrade to "no judgement". + +**Reasoning is a request field, not an inherited default.** The gateway states +`reasoning_effort` per model — `low|high|max` for `deepseek-v4.1-flash` in the +live catalog on 2026-11-05 — and the model writes its chain of thought to a +separate `reasoning_content` field. Only `content` is the answer: an empty +`content` beside a non-empty `reasoning_content` means the model was still +thinking, and returning that as text would be recorded as an unparseable +verdict. That is the same failure OpenRouter's budget guard exists for, which +is why the budget is generous and exceeding it is raised, not returned. + +**A 429 is its own error and is never swallowed.** Quota arrives mid-run, after +some findings are judged and some are not; a run that continued would record +unanswered findings, which is indistinguishable from a skeptic that refutes +nothing — the exact result #246 is testing for. + +`GUARDIAN_OPENCODE_BASE_URL` overrides the endpoint so a gateway pin needs no +code change. The trailing slash is removed here rather than at every caller, +because `…/v1/` + `/chat/completions` would otherwise double the separator. +""" + +import uuid +from typing import Any, ClassVar, Final, override + +import httpx + +from cgis import __version__ +from cgis.guardian.providers.base import ProviderUsage +from cgis.guardian.providers.openai_compatible import OpenAICompatibleProvider + +#: The model this provider exists for: the finder's default, priced at +#: 0.15/0.6 per 1M tokens in/out when the switch was measured (#775). +DEFAULT_OPENCODE_MODEL: Final = "deepseek-v4.1-flash" + +#: OpenAI-compatible completions base. The catalog's `api.chat-completions` +#: entry points at this exact URL; POSTs go to `{base}/chat/completions`. +DEFAULT_OPENCODE_BASE_URL: Final = "https://opencode.ai/inference/go/openai/v1" + +#: Wall-clock budget for one call. Reasoning models are slow and the finder's +#: prompt is large; a timeout tuned to a fast model fails the capable ones by +#: construction, which is what OpenRouter's 300 s exists to avoid. +DEFAULT_REQUEST_TIMEOUT: Final = 300.0 + +#: Completion budget, reasoning included. The report is JSON, but the model +#: spends completion tokens thinking first; a reply cut short is raised rather +#: than returned, so too low a budget is a failed call, not a short answer. +DEFAULT_MAX_TOKENS: Final = 8000 + +#: How hard the model is asked to think. `low` matches the finder's one-pass +#: answer (the same choice `DEFAULT_ANTHROPIC_EFFORT` makes) and bills the least +#: thinking. An explicit value is passed through without a local allowlist: the +#: catalog can grow past today's three levels, and a hard-coded set would reject +#: a value the gateway accepts. A genuinely bad value fails loudly at the +#: gateway, where `raise_for_status` keeps the 4xx message. +DEFAULT_OPENCODE_EFFORT: Final = "low" + +_TOO_MANY_REQUESTS = 429 + + +class OpenCodeQuotaError(RuntimeError): + """Raised on HTTP 429 — the gateway's quota for this key is spent. + + Its own type, and never swallowed: every other transport failure can be + retried into a judgement, but this one cannot, and a run that treated it as + "the finder had nothing to say" would report exhausted quota as a clean + review. The same reasoning as `OpenRouterQuotaError` (#246). + """ + + +class OpenCodeReplyError(RuntimeError): + """The reply is not an answer: it contains reasoning but no `content`. + + Raised rather than returned as empty text, because the caller would count + that as an unparseable answer — attributing to the model a loss this file + can name, and inflating exactly the "unruled" rate a review reads. + """ + + +class OpenCodeProvider(OpenAICompatibleProvider): + """A DeepSeek model reached through opencode-go's OpenAI-compatible API.""" + + name: ClassVar[str] = "opencode" + + def __init__( + self, + api_key: str, + model_name: str = DEFAULT_OPENCODE_MODEL, + timeout: float = DEFAULT_REQUEST_TIMEOUT, + max_tokens: int = DEFAULT_MAX_TOKENS, + temperature: float | None = None, + effort: str = DEFAULT_OPENCODE_EFFORT, + base_url: str = DEFAULT_OPENCODE_BASE_URL, + session_id: str | None = None, + ) -> None: + """Store the key, model, endpoint and generation settings. + + `temperature` is None by default and then not sent at all, leaving the + model's own value in place — the rule every sampled provider here + follows, so an unset knob never becomes a value this project invented. + + `session_id` is stable for one provider instance, i.e. one review run. + The gateway asks for it to route and cache a conversation; a fresh id + per call would split a run into unrelated sessions. It is injectable so + a test can assert the header without pinning a random value. + """ + super().__init__(api_key, model_name, timeout, max_tokens, temperature) + self._effort = (effort or "").strip() or DEFAULT_OPENCODE_EFFORT + # One expression, so the default cannot be skipped by a whitespace-only + # value or a bare "/" and the empty-string fallback is not duplicated. + self._base_url = (base_url or "").strip().rstrip("/") or DEFAULT_OPENCODE_BASE_URL + self._session_id = session_id or uuid.uuid4().hex + + @property + @override + def effort(self) -> str: + """The reasoning depth sent on every call, for the run record (#713).""" + return self._effort + + async def _post(self, payload: dict[str, Any]) -> str: + """One completion call; return the message content. + + `response_format` is passed through when the caller asks for a schema. + The model's compat record advertises structured output, and sending the + schema costs nothing where it is ignored; the caller still parses + defensively either way. + """ + headers = { + "Authorization": f"Bearer {self._api_key}", + "Content-Type": "application/json", + # Identifies this client to the gateway. The catalog's docs ask for + # both headers: the user agent for attribution, the session id for + # routing and cache locality. + "User-Agent": f"codegraph-brain-guardian/{__version__}", + "x-opencode-session": self._session_id, + } + async with httpx.AsyncClient(timeout=self._timeout) as client: + response = await client.post( + f"{self._base_url}/chat/completions", headers=headers, json=payload + ) + if response.status_code == _TOO_MANY_REQUESTS: + # The body is carried, not summarised: it says whether the limit is + # per-minute or the account's allowance, and those have different + # remedies — wait, or stop. Dropping it would leave the operator + # guessing, the same defect as an exception that swallows stderr. + _msg = ( + f"OpenCode returned 429 for {self._model_name}: " + f"{response.text.strip()[:400]}. A run that continued would " + f"record unanswered findings, which is indistinguishable from a " + f"skeptic that refutes nothing." + ) + raise OpenCodeQuotaError(_msg) + response.raise_for_status() + body = response.json() + # An error object with HTTP 200 is how some gateways report an upstream + # refusal; `body["choices"]` would raise KeyError with nothing in the + # message about what declined or why. + if not body.get("choices"): + _msg = f"OpenCode returned no choices for {self._model_name}: {body}" + raise RuntimeError(_msg) + choice = body["choices"][0] + usage = body.get("usage") or {} + self._record_usage( + ProviderUsage( + prompt_tokens=int(usage.get("prompt_tokens") or 0), + completion_tokens=int(usage.get("completion_tokens") or 0), + ) + ) + message = choice.get("message") or {} + if choice.get("finish_reason") == "length": + # Reported, not returned. A model cut off mid-reasoning yields prose + # where JSON was asked for, and the caller would record that as an + # unparseable answer — attributing to the model a limit this file + # chose. + _msg = ( + f"{self._model_name} hit the {self._max_tokens}-token budget before finishing. " + f"Raise max_tokens; the reply so far is reasoning, not an answer." + ) + raise RuntimeError(_msg) + content = str(message.get("content") or "") + reasoning = str(message.get("reasoning_content") or "") + if not content.strip() and reasoning.strip(): + # DeepSeek puts the chain of thought in its own field and fills + # `content` only at the end. An empty answer beside a non-empty + # thought is truncated reasoning, not a verdict. + _msg = ( + f"{self._model_name} returned reasoning but no content. " + f"The answer was cut off before it reached `content`; the " + f"reasoning alone is not a verdict." + ) + raise OpenCodeReplyError(_msg) + return content + + @override + def _payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]: + """The request body; this gateway takes reasoning as an effort level. + + `reasoning_effort` is always sent, so a run can state the depth it ran + at and the same value is exposed through `effort` for the record. The + budget field is `max_tokens`, not the `max_completion_tokens` spelling + some OpenAI deployments use. + """ + payload = self._shared_payload(system_prompt, user_prompt) + payload["reasoning_effort"] = self._effort + return payload diff --git a/src/cgis/guardian/providers/openrouter.py b/src/cgis/guardian/providers/openrouter.py index 122c0e46..862ebcdf 100644 --- a/src/cgis/guardian/providers/openrouter.py +++ b/src/cgis/guardian/providers/openrouter.py @@ -23,12 +23,13 @@ import json import re -from typing import Any, ClassVar +from typing import Any, ClassVar, override import httpx from pydantic import BaseModel -from cgis.guardian.providers.base import BaseProvider, ProviderUsage +from cgis.guardian.providers.base import ProviderUsage +from cgis.guardian.providers.openai_compatible import OpenAICompatibleProvider #: OpenAI-compatible completions endpoint. OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions" @@ -74,7 +75,7 @@ class OpenRouterQuotaError(RuntimeError): """ -class OpenRouterProvider(BaseProvider): +class OpenRouterProvider(OpenAICompatibleProvider): """A chat model reached through OpenRouter's OpenAI-compatible API.""" name: ClassVar[str] = "openrouter" @@ -88,21 +89,23 @@ def __init__( temperature: float | None = None, reasoning: bool = DEFAULT_REASONING, ) -> None: - """Store the key, model, timeout and generation budget. + """Store the key, model, timeout, budget and reasoning switch. `temperature` is None by default and then not sent at all, leaving the model's own value in place — the rule the Mistral and Ollama providers already follow, so an unset knob never becomes a value this project invented and could not describe afterwards. """ - super().__init__() - self._api_key = api_key - self._model_name = model_name - self._timeout = timeout - self._max_tokens = max_tokens - self._temperature = temperature + super().__init__(api_key, model_name, timeout, max_tokens, temperature) self._reasoning = reasoning + @override + def _payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]: + """The request body; OpenRouter states reasoning as a boolean switch.""" + payload = self._shared_payload(system_prompt, user_prompt) + payload["reasoning"] = {"enabled": self._reasoning} + return payload + async def _post(self, payload: dict[str, Any]) -> str: """One completion call; return the message content. @@ -160,43 +163,6 @@ async def _post(self, payload: dict[str, Any]) -> str: raise RuntimeError(_msg) return str(choice["message"].get("content") or "") - def _payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]: - """The request body common to both generation modes.""" - payload: dict[str, Any] = { - "model": self._model_name, - "messages": [ - {"role": "system", "content": system_prompt}, - {"role": "user", "content": user_prompt}, - ], - "max_tokens": self._max_tokens, - # Always sent, in both directions, so a run can state what it did. - "reasoning": {"enabled": self._reasoning}, - } - # `is not None`, not truthiness: 0.0 is the one temperature that states - # something, and a falsy test would drop exactly that value. - if self._temperature is not None: - payload["temperature"] = self._temperature - return payload - - async def generate_content(self, system_prompt: str, user_prompt: str) -> str: - """Free-text generation.""" - return await self._retry(lambda: self._post(self._payload(system_prompt, user_prompt))) - - async def generate_structured( - self, system_prompt: str, user_prompt: str, schema: type[BaseModel] - ) -> str: - """Generation asked to conform to `schema`; returns raw JSON text.""" - payload = self._payload(system_prompt, user_prompt) - payload["response_format"] = { - "type": "json_schema", - "json_schema": { - "name": schema.__name__, - "strict": True, - "schema": schema.model_json_schema(), - }, - } - return await self._retry(lambda: self._post(payload)) - #: An opening code fence with an optional language tag, and a closing one. #: diff --git a/src/cgis/guardian/review_fingerprint.py b/src/cgis/guardian/review_fingerprint.py index 2d1b47b7..b9775a18 100644 --- a/src/cgis/guardian/review_fingerprint.py +++ b/src/cgis/guardian/review_fingerprint.py @@ -155,7 +155,7 @@ def walk_closure(read: ReadFile, active_providers: frozenset[str]) -> list[str]: """ known = frozenset( name - for name in ("gemini", "mistral", "ollama", "openrouter", "anthropic") + for name in ("gemini", "mistral", "ollama", "openrouter", "anthropic", "opencode") if _module_path(f"{_PROVIDER_PACKAGE}.{name}", read) is not None ) unknown = active_providers - known diff --git a/src/cgis/guardian/runner.py b/src/cgis/guardian/runner.py index 8d340524..eeb4788a 100644 --- a/src/cgis/guardian/runner.py +++ b/src/cgis/guardian/runner.py @@ -28,6 +28,12 @@ DEFAULT_OLLAMA_NUM_PREDICT, OllamaProvider, ) +from cgis.guardian.providers.opencode import ( + DEFAULT_OPENCODE_BASE_URL, + DEFAULT_OPENCODE_EFFORT, + DEFAULT_OPENCODE_MODEL, + OpenCodeProvider, +) from cgis.guardian.providers.openrouter import OpenRouterProvider from cgis.guardian.recording import save_finder_recording from cgis.guardian.render import render_report @@ -232,6 +238,39 @@ def _build_openrouter( ) +def _opencode_base_url(env: Mapping[str, str]) -> str: + """GUARDIAN_OPENCODE_BASE_URL, or the gateway's default when unset or blank. + + Collapses an empty/whitespace-only value to the default at the boundary, so + a blank GitHub variable pins nothing rather than producing a URL with no + host. A trailing slash is the provider's to remove. + """ + return (env.get("GUARDIAN_OPENCODE_BASE_URL") or "").strip() or DEFAULT_OPENCODE_BASE_URL + + +def _build_opencode(env: Mapping[str, str], model_override: str | None) -> tuple[BaseProvider, str]: + """Construct an OpenCodeProvider; OPENCODE_API_KEY is required. + + Unlike OpenRouter there is one default model: the gateway is not a catalog + of hundreds, and `deepseek-v4.1-flash` is the measured cheap model this + provider exists for. GUARDIAN_MODEL still overrides it. + """ + key = env.get("OPENCODE_API_KEY") + if not key: + _msg = "OPENCODE_API_KEY must be set when GUARDIAN_PROVIDER=opencode-go" + raise RuntimeError(_msg) + model = model_override or DEFAULT_OPENCODE_MODEL + effort = (env.get("GUARDIAN_OPENCODE_EFFORT") or "").strip() or DEFAULT_OPENCODE_EFFORT + provider = OpenCodeProvider( + api_key=key, + model_name=model, + base_url=_opencode_base_url(env), + effort=effort, + temperature=temperature(env), + ) + return provider, model + + def _anthropic(env: Mapping[str, str], model: str) -> AnthropicProvider: """An AnthropicProvider on ANTHROPIC_API_KEY, refusing a set GUARDIAN_TEMPERATURE. @@ -312,8 +351,9 @@ def _model_from_env(env: Mapping[str, str], key: str) -> str | None: def build_provider(env: Mapping[str, str]) -> tuple[BaseProvider, str]: """Return (provider, model_name) from GUARDIAN_PROVIDER / available API keys. - With no explicit GUARDIAN_PROVIDER, auto-select: mistral if its key is set, - else gemini if its key is set, else an error. + With no explicit GUARDIAN_PROVIDER, auto-select: opencode-go if its key is + set, else mistral if its key is set, else gemini if its key is set, else an + error. """ model_override = _model_from_env(env, "GUARDIAN_MODEL") provider_name = env.get("GUARDIAN_PROVIDER", "").lower() or _autodetect_provider(env) @@ -324,6 +364,12 @@ def build_provider(env: Mapping[str, str]) -> tuple[BaseProvider, str]: "ollama": _build_ollama, "openrouter": _build_openrouter, "anthropic": _build_anthropic, + # The issue's canonical selector is `opencode-go`, but the provider's + # own `name` must stay `opencode` — the fingerprint derives its module + # path from the name, and a hyphen would name `providers/opencode-go.py` + # (#775). Both spellings therefore select it. + "opencode-go": _build_opencode, + "opencode": _build_opencode, } builder = builders.get(provider_name) if builder is None: @@ -337,11 +383,13 @@ def build_provider(env: Mapping[str, str]) -> tuple[BaseProvider, str]: def _autodetect_provider(env: Mapping[str, str]) -> str: """Pick a provider from available API keys when GUARDIAN_PROVIDER is unset.""" + if env.get("OPENCODE_API_KEY"): + return "opencode-go" if env.get("MISTRAL_API_KEY"): return "mistral" if env.get("GEMINI_API_KEY"): return "gemini" - _msg = "Set MISTRAL_API_KEY or GEMINI_API_KEY to run Guardian." + _msg = "Set OPENCODE_API_KEY, MISTRAL_API_KEY or GEMINI_API_KEY to run Guardian." raise RuntimeError(_msg) diff --git a/tests/unit/test_guardian_opencode.py b/tests/unit/test_guardian_opencode.py new file mode 100644 index 00000000..977f4fda --- /dev/null +++ b/tests/unit/test_guardian_opencode.py @@ -0,0 +1,262 @@ +"""The OpenCode Go provider (#775), with the network stubbed. + +Every branch here exists because failing it quietly would corrupt a review. +A spent quota, a truncated answer and an upstream 4xx all produce "no +judgement", and a finder that produces no judgement is indistinguishable from +one that found nothing. + +The gateway speaks the OpenAI shape, so the request tests pin the parts this +provider chooses: the endpoint, the budget field, the reasoning depth and the +session header. The failure tests pin what it refuses to return. +""" + +from typing import Any + +import httpx +import pytest +from pydantic import BaseModel + +from cgis.guardian.providers import opencode as mod +from cgis.guardian.providers.opencode import ( + DEFAULT_MAX_TOKENS, + DEFAULT_OPENCODE_BASE_URL, + DEFAULT_OPENCODE_EFFORT, + DEFAULT_OPENCODE_MODEL, + DEFAULT_REQUEST_TIMEOUT, + OpenCodeProvider, + OpenCodeQuotaError, + OpenCodeReplyError, +) + +_ENDPOINT = f"{DEFAULT_OPENCODE_BASE_URL}/chat/completions" + + +class _Judgement(BaseModel): + verdict: str + rationale: str + + +def _reply( + content: str | None = '{"verdict": "refuted", "rationale": "r"}', + *, + status: int = 200, + finish: str = "stop", + usage: dict[str, int] | None = None, + reasoning: str | None = None, + body: dict[str, Any] | None = None, +) -> httpx.Response: + message: dict[str, Any] = {"content": content} + if reasoning is not None: + message["reasoning_content"] = reasoning + payload = body or { + "choices": [{"message": message, "finish_reason": finish}], + "usage": usage or {"prompt_tokens": 11, "completion_tokens": 7}, + } + return httpx.Response(status, json=payload, request=httpx.Request("POST", _ENDPOINT)) + + +def _serve(monkeypatch: pytest.MonkeyPatch, response: httpx.Response) -> dict[str, list[Any]]: + """Route every POST to `response`; return the URLs, headers, bodies and timeouts sent.""" + captured: dict[str, list[Any]] = { + "urls": [], + "headers": [], + "bodies": [], + "timeouts": [], + } + + class _Client: + def __init__(self, **kw: object) -> None: + captured["timeouts"].append(kw["timeout"]) + + async def __aenter__(self) -> "_Client": + return self + + async def __aexit__(self, *_exc: object) -> None: + return None + + async def post(self, url: str, **kwargs: object) -> httpx.Response: + captured["urls"].append(url) + captured["headers"].append(kwargs["headers"]) + captured["bodies"].append(kwargs["json"]) + return response + + monkeypatch.setattr(mod.httpx, "AsyncClient", _Client) + return captured + + +def _provider(**overrides: object) -> OpenCodeProvider: + settings: dict[str, Any] = {"api_key": "k", "model_name": DEFAULT_OPENCODE_MODEL} + settings.update(overrides) + return OpenCodeProvider(**settings) + + +class TestTheFailuresThatWouldLookLikeSilence: + """Each of these would produce "no verdict", and each must say why instead.""" + + @pytest.mark.asyncio + async def test_a_spent_quota_raises_rather_than_returning_nothing( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """429 is not an answer, and the body names which limit was hit.""" + _serve(monkeypatch, _reply(status=429)) + provider = _provider() + with pytest.raises(OpenCodeQuotaError, match="refutes nothing"): + await provider.generate_content("s", "u") + + @pytest.mark.asyncio + async def test_any_other_http_error_is_raised_not_degraded( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """An auth, model or effort mistake fails loudly, with the gateway's message.""" + _serve(monkeypatch, _reply(status=400, body={"error": {"message": "bad effort"}})) + provider = _provider() + with pytest.raises(httpx.HTTPStatusError): + await provider.generate_content("s", "u") + + @pytest.mark.asyncio + async def test_hitting_the_token_budget_raises_rather_than_returning_reasoning( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + _serve(monkeypatch, _reply(content="We need to assess the claim", finish="length")) + provider = _provider(max_tokens=600) + with pytest.raises(RuntimeError, match="reasoning, not an answer"): + await provider.generate_content("s", "u") + + @pytest.mark.asyncio + async def test_empty_content_beside_reasoning_raises( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """DeepSeek writes the chain of thought to `reasoning_content`. + + An empty `content` beside a non-empty thought means the answer never + arrived; returning "" would be counted as an unparseable verdict. + """ + _serve(monkeypatch, _reply(content=None, reasoning="The claim seems...")) + provider = _provider() + with pytest.raises(OpenCodeReplyError, match="reasoning but no content"): + await provider.generate_content("s", "u") + + @pytest.mark.asyncio + async def test_an_empty_choices_list_is_reported_not_an_indexerror( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """An upstream content filter returns a 200 with an empty list.""" + _serve(monkeypatch, _reply(body={"choices": [], "usage": {}})) + provider = _provider() + with pytest.raises(RuntimeError, match="no choices"): + await provider.generate_content("s", "u") + + +class TestTheRequest: + """What goes on the wire, and what deliberately does not.""" + + @pytest.mark.asyncio + async def test_the_endpoint_and_the_identifying_headers( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """The gateway asks for a client user agent and a stable per-run session id.""" + captured = _serve(monkeypatch, _reply()) + provider = _provider() + await provider.generate_content("s", "u") + await provider.generate_content("s", "u") + assert captured["urls"][0] == _ENDPOINT + headers = captured["headers"][0] + assert headers["Authorization"] == "Bearer k" + assert str(headers["User-Agent"]).startswith("codegraph-brain-guardian/") + sessions = [headers["x-opencode-session"] for headers in captured["headers"]] + assert sessions[0] + assert sessions[0] == sessions[1] + + @pytest.mark.asyncio + async def test_the_base_url_can_be_pinned_and_its_trailing_slash_removed( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """A gateway pin with a trailing slash must not produce `//chat/completions`.""" + captured = _serve(monkeypatch, _reply()) + await _provider(base_url="https://gateway.example/v1/").generate_content("s", "u") + assert captured["urls"][0] == "https://gateway.example/v1/chat/completions" + + @pytest.mark.asyncio + async def test_the_timeout_is_the_providers_own(self, monkeypatch: pytest.MonkeyPatch) -> None: + captured = _serve(monkeypatch, _reply()) + await _provider().generate_content("s", "u") + await _provider(timeout=45.0).generate_content("s", "u") + assert captured["timeouts"] == [DEFAULT_REQUEST_TIMEOUT, 45.0] + + @pytest.mark.asyncio + async def test_the_budget_field_and_the_effort(self, monkeypatch: pytest.MonkeyPatch) -> None: + """`max_tokens`, not `max_completion_tokens`; the effort is stated, not inherited.""" + captured = _serve(monkeypatch, _reply()) + await _provider().generate_content("s", "u") + await _provider(effort="high").generate_content("s", "u") + bodies = captured["bodies"] + assert bodies[0]["max_tokens"] == DEFAULT_MAX_TOKENS + assert bodies[0]["reasoning_effort"] == DEFAULT_OPENCODE_EFFORT + assert bodies[1]["reasoning_effort"] == "high" + + @pytest.mark.asyncio + async def test_effort_is_exposed_for_the_run_record( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + _serve(monkeypatch, _reply()) + provider = _provider(effort="max") + await provider.generate_content("s", "u") + assert provider.effort == "max" + + @pytest.mark.asyncio + async def test_an_unset_temperature_is_not_sent(self, monkeypatch: pytest.MonkeyPatch) -> None: + """An unset knob must not become a value this project invented.""" + captured = _serve(monkeypatch, _reply()) + await _provider().generate_content("s", "u") + assert "temperature" not in captured["bodies"][0] + + @pytest.mark.asyncio + async def test_a_zero_temperature_is_sent(self, monkeypatch: pytest.MonkeyPatch) -> None: + """0.0 is the one temperature that states something, and it is falsy.""" + captured = _serve(monkeypatch, _reply()) + await _provider(temperature=0.0).generate_content("s", "u") + assert captured["bodies"][0]["temperature"] == 0.0 + + @pytest.mark.asyncio + async def test_structured_generation_carries_the_schema( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + captured = _serve(monkeypatch, _reply()) + await _provider().generate_structured("s", "u", _Judgement) + fmt = captured["bodies"][0]["response_format"] + assert fmt["type"] == "json_schema" + assert fmt["json_schema"]["name"] == "_Judgement" + assert "verdict" in fmt["json_schema"]["schema"]["properties"] + + @pytest.mark.asyncio + async def test_usage_is_recorded(self, monkeypatch: pytest.MonkeyPatch) -> None: + _serve(monkeypatch, _reply(usage={"prompt_tokens": 100, "completion_tokens": 20})) + provider = _provider() + await provider.generate_content("s", "u") + assert provider.last_usage.total_tokens == 120 + assert provider.cumulative_usage.total_tokens == 120 + + @pytest.mark.asyncio + async def test_a_reply_with_no_usage_is_not_a_crash( + self, monkeypatch: pytest.MonkeyPatch + ) -> None: + """Some upstreams omit it; losing the token count must not lose the answer.""" + _serve(monkeypatch, _reply(body={"choices": [{"message": {"content": "ok"}}]})) + assert await _provider().generate_content("s", "u") == "ok" + + +def test_the_default_model_is_the_cheap_deepseek() -> None: + """The model the switch is measured on, and the one the catalog prices at 0.15/0.6.""" + assert DEFAULT_OPENCODE_MODEL == "deepseek-v4.1-flash" + + +def test_blank_settings_fall_back_to_their_defaults() -> None: + """An empty endpoint, a bare slash or a missing effort must not build a broken URL. + + External callers can pass whitespace or a null where the environment path + always supplies a string; the default is safer than an empty host or an + AttributeError before the first request. + """ + provider = _provider(base_url=" / ", effort=None) + assert provider.effort == DEFAULT_OPENCODE_EFFORT + assert provider._base_url == DEFAULT_OPENCODE_BASE_URL # noqa: SLF001 # white-box: default diff --git a/tests/unit/test_guardian_providers_name.py b/tests/unit/test_guardian_providers_name.py index 7de15221..18e6bb0a 100644 --- a/tests/unit/test_guardian_providers_name.py +++ b/tests/unit/test_guardian_providers_name.py @@ -10,25 +10,34 @@ from cgis.guardian.providers.gemini import GeminiProvider from cgis.guardian.providers.mistral import MistralProvider from cgis.guardian.providers.ollama import OllamaProvider +from cgis.guardian.providers.opencode import OpenCodeProvider def test_every_provider_names_itself() -> None: assert GeminiProvider.name == "gemini" assert MistralProvider.name == "mistral" assert OllamaProvider.name == "ollama" + assert OpenCodeProvider.name == "opencode" def test_names_match_the_runner_vocabulary() -> None: """The names are the GUARDIAN_PROVIDER values, not free-form labels. - `build_provider` dispatches on exactly these three strings, so a provider - whose name does not appear there cannot be selected and its module would be - pruned out of every fingerprint. + `build_provider` dispatches on exactly these strings, so a provider whose + name does not appear there cannot be selected and its module would be + pruned out of every fingerprint. `opencode` is deliberately hyphen-free: + the fingerprint derives `providers/.py` from it (#775). """ - assert {GeminiProvider.name, MistralProvider.name, OllamaProvider.name} == { + assert { + GeminiProvider.name, + MistralProvider.name, + OllamaProvider.name, + OpenCodeProvider.name, + } == { "gemini", "mistral", "ollama", + "opencode", } diff --git a/tests/unit/test_guardian_review_script.py b/tests/unit/test_guardian_review_script.py index 10e59d8d..bd7b6983 100644 --- a/tests/unit/test_guardian_review_script.py +++ b/tests/unit/test_guardian_review_script.py @@ -32,7 +32,7 @@ async def test_refuses_a_bad_metrics_path_before_building_a_provider( """Ordering is the point, and the exception type is what proves it. With no API keys in the environment, `build_provider` raises - `RuntimeError("Set MISTRAL_API_KEY or GEMINI_API_KEY…")`. So getting a + `RuntimeError("Set OPENCODE_API_KEY, MISTRAL_API_KEY or GEMINI_API_KEY…")`. So getting a `ValueError` about the metrics path means the check ran *first* — which is the whole reason it is duplicated here rather than left to `record_review`, which runs after the review is complete and paid for. diff --git a/tests/unit/test_guardian_runner.py b/tests/unit/test_guardian_runner.py index 28a57775..6f4b83e3 100644 --- a/tests/unit/test_guardian_runner.py +++ b/tests/unit/test_guardian_runner.py @@ -16,6 +16,7 @@ from cgis.guardian.providers.base import BaseProvider, ProviderUsage from cgis.guardian.providers.mistral import MistralProvider from cgis.guardian.providers.ollama import OllamaProvider +from cgis.guardian.providers.opencode import DEFAULT_OPENCODE_MODEL, OpenCodeProvider from cgis.guardian.recording import load_finder_recording from cgis.guardian.runner import ( DEFAULT_GEMINI_MODEL, @@ -62,7 +63,7 @@ async def generate_structured( def test_build_provider_requires_a_key() -> None: """No API keys in env → RuntimeError with guidance.""" - with pytest.raises(RuntimeError, match="MISTRAL_API_KEY or GEMINI_API_KEY"): + with pytest.raises(RuntimeError, match="OPENCODE_API_KEY"): build_provider({}) @@ -195,6 +196,52 @@ def test_build_provider_ollama_num_ctx_from_env() -> None: assert provider._num_ctx == 8192 # noqa: SLF001 # white-box: ctx wiring +def test_build_provider_opencode_go_needs_only_its_own_key() -> None: + """`opencode-go` must not require ANTHROPIC_API_KEY — that is the point of #775.""" + provider, model = build_provider({"GUARDIAN_PROVIDER": "opencode-go", "OPENCODE_API_KEY": "k"}) + assert isinstance(provider, OpenCodeProvider) + assert model == DEFAULT_OPENCODE_MODEL + assert provider.effort == "low" + + +def test_build_provider_opencode_go_requires_its_key() -> None: + with pytest.raises(RuntimeError, match="OPENCODE_API_KEY"): + build_provider({"GUARDIAN_PROVIDER": "opencode-go"}) + + +def test_build_provider_accepts_the_bare_opencode_alias() -> None: + """The provider's own `name` is `opencode`; selecting by it must work too (#775).""" + provider, _ = build_provider({"GUARDIAN_PROVIDER": "opencode", "OPENCODE_API_KEY": "k"}) + assert isinstance(provider, OpenCodeProvider) + + +def test_build_provider_opencode_reads_the_run_settings() -> None: + """Model, effort, endpoint and temperature all come from the environment.""" + provider, model = build_provider( + { + "GUARDIAN_PROVIDER": "opencode-go", + "OPENCODE_API_KEY": "k", + "GUARDIAN_MODEL": "deepseek-v4-pro", + "GUARDIAN_OPENCODE_EFFORT": "high", + "GUARDIAN_OPENCODE_BASE_URL": "https://gateway.example/v1/", + "GUARDIAN_TEMPERATURE": "0.2", + } + ) + assert isinstance(provider, OpenCodeProvider) + assert model == "deepseek-v4-pro" + assert provider.effort == "high" + assert provider._effort == "high" # noqa: SLF001 # white-box: env wiring + assert provider._base_url == "https://gateway.example/v1" # noqa: SLF001 + assert provider._temperature == 0.2 # noqa: SLF001 # white-box: temperature wiring + + +def test_build_provider_autodetects_opencode_go_before_the_other_keys() -> None: + """With no GUARDIAN_PROVIDER, the new provider is preferred when its key is present.""" + provider, model = build_provider({"OPENCODE_API_KEY": "k", "MISTRAL_API_KEY": "m"}) + assert isinstance(provider, OpenCodeProvider) + assert model == DEFAULT_OPENCODE_MODEL + + def test_build_provider_unknown_lists_every_provider_there_is() -> None: """A typo in GUARDIAN_PROVIDER names the valid ones — all of them. @@ -206,7 +253,15 @@ def test_build_provider_unknown_lists_every_provider_there_is() -> None: with pytest.raises(RuntimeError) as raised: build_provider({"GUARDIAN_PROVIDER": "cohere", "GEMINI_API_KEY": "g"}) message = str(raised.value) - for name in ("mistral", "gemini", "ollama", "openrouter", "anthropic"): + for name in ( + "mistral", + "gemini", + "ollama", + "openrouter", + "anthropic", + "opencode-go", + "opencode", + ): assert name in message @@ -867,7 +922,7 @@ def test_build_provider_anthropic_refuses_a_temperature() -> None: def test_anthropic_is_never_autodetected_from_its_key() -> None: """ANTHROPIC_API_KEY is set in many shells for other tools; it must not start spending.""" - with pytest.raises(RuntimeError, match="Set MISTRAL_API_KEY or GEMINI_API_KEY"): + with pytest.raises(RuntimeError, match="Set OPENCODE_API_KEY, MISTRAL_API_KEY"): build_provider({"ANTHROPIC_API_KEY": "k"}) diff --git a/tests/unit/test_guardian_workflow.py b/tests/unit/test_guardian_workflow.py index 33d56469..a1cb9928 100644 --- a/tests/unit/test_guardian_workflow.py +++ b/tests/unit/test_guardian_workflow.py @@ -53,6 +53,27 @@ def _in_pr(directory: object) -> bool: return parts[:1] == (PR_DIR,) +def _last_pr_step(steps: list[dict[str, Any]]) -> int: + """Index of the last step that checks out, parses or runs inside the PR checkout.""" + return max( + i + for i, s in enumerate(steps) + if _in_pr(s.get("working-directory")) + or "refs/pull/" in str(_with(s).get("ref", "")) + or f"{PR_DIR}/" in str(s.get("run", "")) + ) + + +#: A `jq` command word in a shell script: start, or after whitespace or a shell +#: separator, and followed by whitespace or end of line. The sign-in step must +#: not need it: a self-hosted runner may not have it (#742, #775). +_JQ_COMMAND = re.compile(r"(?:^|[\s;|&(`])jq(?=\s|$)", re.M) + +#: A `python3` command word. The sign-in step must not assume it is on PATH on +#: a self-hosted runner; uv is installed and the environment synced (#775). +_PYTHON3_COMMAND = re.compile(r"(?:^|[\s;|&(`])python3(?=\s|$)", re.M) + + @pytest.fixture(scope="module") def workflow() -> dict[Any, Any]: """The parsed workflow file.""" @@ -235,14 +256,126 @@ def test_only_the_posting_steps_reference_the_app_token(steps: list[dict[str, An def test_the_app_token_is_minted_after_every_pr_step(steps: list[dict[str, Any]]) -> None: """Nothing that checks out or runs in the PR checkout comes after the token exists.""" minted = steps.index(_app_token_step(steps)) - last_pr = max( - i - for i, s in enumerate(steps) - if _in_pr(s.get("working-directory")) - or "refs/pull/" in str(_with(s).get("ref", "")) - or f"{PR_DIR}/" in str(s.get("run", "")) - ) - assert minted > last_pr + assert minted > _last_pr_step(steps) + + +# OIDC sign-in (#775): opencode-go needs no static key. The job exchanges a +# short-lived GitHub OIDC token for inference access immediately before the +# review, and the review step inherits it from GITHUB_ENV. + + +def _oidc_step(steps: list[dict[str, Any]]) -> dict[str, Any]: + matches = [s for s in steps if s.get("name") == "Sign in to OpenCode (OIDC)"] + assert len(matches) == 1 + return matches[0] + + +def test_the_review_job_can_request_an_oidc_token(workflow: dict[Any, Any]) -> None: + """`id-token: write` is what makes ACTIONS_ID_TOKEN_REQUEST_* exist at all.""" + assert workflow["jobs"]["review"]["permissions"] == { + "contents": "read", + "pull-requests": "write", + "issues": "write", + "id-token": "write", + } + + +def test_the_oidc_sign_in_runs_after_every_pr_step_and_before_the_review( + steps: list[dict[str, Any]], +) -> None: + """The token is short-lived, so it is minted last — after no PR code can see it.""" + signed_in = steps.index(_oidc_step(steps)) + review = steps.index(next(s for s in steps if s.get("name") == "Run Guardian Review")) + assert signed_in > _last_pr_step(steps) + assert signed_in < review + + +def test_the_oidc_sign_in_exchanges_a_github_token_for_inference( + steps: list[dict[str, Any]], +) -> None: + step = _oidc_step(steps) + assert step.get("if") == "vars.OPENCODE_CLIENT_ID != ''" + assert step["env"] == { + "AUDIENCE": "https://opencode.ai/console", + "CLIENT_ID": "${{ vars.OPENCODE_CLIENT_ID }}", + "GUARDIAN_PROVIDER": "${{ vars.GUARDIAN_PROVIDER }}", + } + run = step["run"] + for needle in ( + "ACTIONS_ID_TOKEN_REQUEST_URL", + "ACTIONS_ID_TOKEN_REQUEST_TOKEN", + "--oauth2-bearer", + "audience=$AUDIENCE", + "grant_type=urn:ietf:params:oauth:grant-type:token-exchange", + "subject_token_type=urn:ietf:params:oauth:token-type:jwt", + 'client_id="$CLIENT_ID"', + 'subject_token="$oidc"', + "https://opencode.ai/console/auth/oauth/token", + "::add-mask::", + 'echo "OPENCODE_API_KEY=$token" >> "$GITHUB_ENV"', + ): + assert needle in run + # The token is masked before it is exported, and neither jq nor a PATH + # python3 is assumed: uv was installed and its environment synced above. + assert run.index("::add-mask::") < run.index('>> "$GITHUB_ENV"') + assert not _JQ_COMMAND.search(run) + assert not _PYTHON3_COMMAND.search(run) + assert run.count("uv run --frozen python -c") == 2 + + +@pytest.mark.parametrize( + ("provider", "signs_in"), + [ + ("", True), + ("opencode-go", True), + ("OPEncode-Go", True), + ("opencode", True), + ("mistral", False), + ("MISTRAL", False), + ("anthropic", False), + ], +) +def test_the_oidc_sign_in_only_runs_when_opencode_is_selected( + steps: list[dict[str, Any]], tmp_path: Path, provider: str, signs_in: bool +) -> None: + """Another explicit provider must not depend on OpenCode's availability. + + Empty still signs in on purpose: the minted key then makes autodetection + choose opencode. The missing-token branch is reached only for a provider + this step owns, so no network is involved here. + """ + run = _oidc_step(steps)["run"] + env = { + **os.environ, + "GUARDIAN_PROVIDER": provider, + "GITHUB_ENV": str(tmp_path / "github_env"), + } + env.pop("ACTIONS_ID_TOKEN_REQUEST_URL", None) + env.pop("ACTIONS_ID_TOKEN_REQUEST_TOKEN", None) + done = subprocess.run(["bash", "-c", run], env=env, capture_output=True, text=True, check=False) + output = done.stdout + done.stderr + if signs_in: + assert done.returncode != 0 + assert "GitHub OIDC is unavailable" in output + else: + assert done.returncode == 0 + assert f"not the selected provider ({provider.lower()})" in output + assert not (tmp_path / "github_env").exists() + + +def test_the_oidc_sign_in_fails_loudly_instead_of_minting_an_empty_key( + steps: list[dict[str, Any]], +) -> None: + """Every failure path runs before the model call; none can leave an empty key.""" + run = _oidc_step(steps)["run"] + for needle in ( + "GitHub OIDC is unavailable", + "failed with HTTP", + "carried no value field", + "returned no access_token", + "empty access_token", + ): + assert needle in run def test_the_review_job_ends_before_the_app_token_expires(workflow: dict[Any, Any]) -> None: @@ -276,6 +409,8 @@ def test_the_caller_hands_the_review_to_the_reusable_workflow(caller: dict[Any, "contents": "read", "pull-requests": "write", "issues": "write", + # A called workflow cannot request more than its caller grants (#775). + "id-token": "write", } @@ -305,6 +440,24 @@ def test_cross_org_callers_can_pass_the_secrets(workflow: dict[Any, Any]) -> Non assert all(v == {"required": False} for v in declared.values()) +def test_the_review_step_does_not_receive_a_static_opencode_key( + steps: list[dict[str, Any]], +) -> None: + """The OIDC step writes GITHUB_ENV; a step-level value would override it (#775). + + `ANTHROPIC_API_KEY` stays in the environment because existing callers pass + it by name; it is simply not required. `GUARDIAN_ANTHROPIC_EFFORT` is gone: + an explicit anthropic pick runs at its provider default. + """ + review = next(s for s in steps if s.get("name") == "Run Guardian Review") + env = review["env"] + assert "OPENCODE_API_KEY" not in env + assert not any("OPENCODE" in str(v) and "secrets." in str(v) for v in env.values()) + assert env["GUARDIAN_OPENCODE_EFFORT"] == "${{ vars.GUARDIAN_OPENCODE_EFFORT }}" + assert env["ANTHROPIC_API_KEY"] == "${{ secrets.ANTHROPIC_API_KEY }}" + assert "GUARDIAN_ANTHROPIC_EFFORT" not in env + + @pytest.mark.parametrize( ("event", "source_root", "ok"), [ diff --git a/tests/unit/test_review_fingerprint_closure.py b/tests/unit/test_review_fingerprint_closure.py index 2680c133..f3d33d6a 100644 --- a/tests/unit/test_review_fingerprint_closure.py +++ b/tests/unit/test_review_fingerprint_closure.py @@ -83,6 +83,28 @@ def test_the_anthropic_provider_joins_the_closure_only_when_active() -> None: assert "src/cgis/guardian/providers/mistral.py" in closure +def test_the_opencode_provider_is_known_and_joins_the_closure() -> None: + """A provider missing from the hardcoded known set fails every review with it (#775). + + `walk_closure` derives `providers/.py` from the active name, so the + hyphenated selector would raise `UnknownProviderError`; the provider's name + is `opencode` and that is what gets hashed. + """ + opencode = "src/cgis/guardian/providers/opencode.py" + assert opencode not in walk_closure(disk_reader, frozenset({"gemini"})) + closure = walk_closure(disk_reader, frozenset({"opencode"})) + assert opencode in closure + assert "src/cgis/guardian/providers/base.py" in closure + + +def test_the_shared_openai_compatible_helper_joins_the_closure() -> None: + """The helper has no provider name, so it is never pruned — both providers read it (#775).""" + helper = "src/cgis/guardian/providers/openai_compatible.py" + assert helper in walk_closure(disk_reader, frozenset({"openrouter"})) + assert helper in walk_closure(disk_reader, frozenset({"opencode"})) + assert helper not in walk_closure(disk_reader, frozenset({"gemini"})) + + def test_resolve_active_providers_is_the_union() -> None: """The shared helper both scripts call, so they cannot drift apart (#375).