feat(provider): add native Google Gemini API adapter (Phase 4)

Adds internal/provider/google, the second native cloud adapter (following
internal/provider/anthropic's pattern) on top of Phase 1's provider-neutral
tool-use loop, wired to a Docker-sandboxed NativeRunner under agent.type:
"google" -- a separate execution path and budget bucket from the existing
CLI-subprocess "gemini" ContainerRunner, which is untouched.

Wire-format research (the highest-risk part of this adapter): Gemini's
multi-turn function-calling shape was resolved by cross-referencing the
REST API reference's own generateContent example against the go-genai SDK's
struct tags on GitHub -- both agree on functionCall/functionResponse parts
keyed by "name" (with an optional "id" for round-tripping ToolCall.ID),
with the response fed back inside a "user"-role Content (Gemini has no
tool/function role, mirroring Anthropic's lack of one). A separate fetched
source (the function-calling guide page) was deliberately discarded as a
reference for this shape -- it documents a different, newer "Interactions
API" whose call_id/type:"function_result" structure doesn't fit the
contents/parts/candidates shape used everywhere else.

- internal/provider/google: request/response translation, systemInstruction
  handling, role mapping (assistant->model, tool-results->user role),
  per-model-prefix pricing table (2.5 Pro/Flash/Flash-Lite, 2.0, 1.5 tiers)
- internal/retry: IsRateLimitError additively extended for RESOURCE_EXHAUSTED
- internal/config: RunnersConfig.Google/GoogleEnabled()
- internal/cli/serve.go, run.go: runners["google"] construction mirroring
  the Anthropic wiring exactly (Docker sandbox default)
- docs/api-keys-setup.md: Google marked wired-up, budget-bucket/disable/
  verify guidance added matching the Anthropic section

go build/vet/test -race all pass. No live Gemini API key available in this
environment; verified via fake-httptest-server adapter tests (plain text,
tool-use round-trip, multi-turn tool-result, rate-limit error matching) plus
a Pool/NativeRunner routing test. Live E2E is a follow-up once a key is
configured, same as Phase 2's Anthropic adapter.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 7 insertions, 4 deletions

diff --git a/docs/api-keys-setup.md b/docs/api-keys-setup.md
index 731a711..1a9daf9 100644
--- a/docs/api-keys-setup.md
+++ b/docs/api-keys-setup.md
@@ -9,7 +9,7 @@ Providers, in escalation-ladder order (cheapest/free first):
 | Groq | to add (works once configured — Phase 1's `openaicompat` adapter, no dedicated phase needed) | free tier (real, no card required historically) | OpenAI-compatible |
 | OpenRouter | to add (same as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible |
 | OpenAI | to add (same as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) |
-| Google (Gemini) | to add — native adapter lands Phase 4 | paid (already have account) | native (Gemini API) |
+| Google (Gemini) | **wired up (Phase 4)** — `agent.type: "google"` works as soon as a key is in `config.toml` | paid (already have account) | native (Gemini API) |
 | Anthropic (Claude) | **wired up (Phase 2)** — `agent.type: "anthropic"` works as soon as a key is in `config.toml` | paid (already have account) | native (Messages API) |
 
 > Note on freshness: signup flows and free-tier limits change without much notice. Treat the specific numbers below (rate limits, credit thresholds) as "true as of when this was written" and double-check the provider's own pricing/limits page before relying on them for capacity planning.
@@ -87,14 +87,17 @@ No meaningful ongoing free tier at this point — expect to prepay. Included in
 
 ---
 
-## Google (Gemini) — you already have a paid account
+## Google (Gemini) — you already have a paid account, and this one's live too
 
-The existing `credentials/gemini/` directory holds an OAuth session for the `gemini` CLI (used by `ContainerRunner`). The native-API path this harness adds is separate: a plain API key from Google AI Studio, used directly against the Gemini API rather than through the CLI.
+Same situation as Anthropic below: the existing `credentials/gemini/` directory holds an OAuth session for the `gemini` CLI (used by `ContainerRunner`). The native-API path this harness adds is separate: a plain API key from Google AI Studio, used directly against the Gemini `generateContent` API rather than through the CLI.
 
 1. Go to `aistudio.google.com/apikey` (Google AI Studio), signed in with the same Google account as your paid plan.
 2. **Create API key** — choose the Google Cloud project tied to your paid billing if prompted, so usage bills correctly rather than falling back to any free-tier project quota.
 3. Copy the key (`AIza...`).
-4. `[providers.google]` needs no `endpoint` override (the adapter defaults to the native Gemini API base) — just `api_key` and `default_model`.
+4. `[providers.google]` needs no `endpoint` override (the adapter defaults to the native Gemini API base) — just `api_key` and `default_model` (e.g. `gemini-2.5-flash` for a cheap/fast rung, `gemini-2.5-pro` for a more capable one).
+5. Since this is a separate credential from the CLI's OAuth session, keep an eye on AI Studio/Cloud Console usage separately from whatever the `gemini` CLI itself reports — they draw from the same account but are tracked as distinct API consumers. This is intentional: `executions.agent = "google"` (native path) and `"gemini"` (CLI-subprocess `ContainerRunner` path) are tracked as **separate budget buckets** even though both bill the same account — set `[budget].provider_5h_usd.google` independently of `.gemini` if you want different caps on each.
+6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "google"` as a usable runner — no restart-time flag needed beyond having the key present. To turn it off without removing the key, set `[runners] google = false`.
+7. Verify it's live: submit any task with `agent.type: "google"`, then check `GET /api/budget` for a distinct `"google"` row once the execution completes.
 
 If you'd rather use Vertex AI (GCP's enterprise entry point to Gemini, with IAM-based auth instead of a bare API key) that's a heavier setup (service account, GCP project, `gcloud` auth) — not necessary for this harness unless you specifically want Vertex's quota/governance features. AI Studio's simple API key is sufficient for what's being built here.