Deliberationv4.6.1

Provider bridges

Provider bridges

Gemini bridge

Gemini has two paths. Which one an advisory call takes is set by providers.gemini.transport (auto default, api, agy):

Path When How
API key (default) advisory call with GEMINI_API_KEY set (auto), or any call with transport: "api" POST {GEMINI_API_BASE}/chat/completions on Google's OpenAI-compatible endpoint, Authorization: Bearer <key>, model providers.gemini.apiModel (default gemini-flash-latest). Same HTTP client as OpenRouter (server/openrouter callOpenRouter), with reasoning_effort as a top-level field and errors labelled Gemini. Multi-turn sessions are in memory. File-blind, so fan-outs attach the orientation bundle.
agy (opt-in) workspace-write calls under auto and agy; advisory calls with no GEMINI_API_KEY (auto) or with transport: "agy". Never under transport: "api" the Antigravity CLI, described below

GEMINI_API_KEY wins over GOOGLE_API_KEY, and GOOGLE_API_KEY alone does not switch auto (it is often a key for another Google API). The key is never passed to agy: the API path does not spawn it, and the agy child env scrubs every *_KEY variable anyway. In the standalone bridge, a gemini-reply to a thread that started on the API path continues on the API path; asking for workspace-write on such a thread is an invalid-params error. Under transport: "api" one gate in front of agy refuses everything that would run it (workspace-write, or a reply to a thread the API path does not know) with invalid params. With the API path selected, the standalone bridge starts even when agy is missing (a stderr warning; workspace-write calls then fail). The per-call model argument of the standalone gemini tool is an agy id, so the API path ignores it and uses providers.gemini.apiModel.

Antigravity terms. The Antigravity terms (external), section 6, list "Using third party software, tools, or services to access the Service (e.g. using OpenClaw with Antigravity OAuth)" as a breach that "may be grounds for suspension or termination of your Antigravity and/or Gemini CLI accounts". Deliberation drives agy as third-party software, which is why the key path is the default and agy is opt-in.

The agy path wraps the Antigravity CLI (agy) in print mode (agy -p) and adds two reliability behaviors:

  • Soft-timeout drain - on timeout it keeps agy alive, keeps buffering its streamed stdout, and returns the answer if agy completes cleanly within the grace budget. The unified MCP orchestration uses hard absolute deadlines for single calls and shared fan-outs, so it disables this drain; it remains available on standalone bridge calls without a hard deadline or host cap. See Gemini timeout recovery.
  • Plain-stdout answer with an Error: sentinel - agy -p prints the answer as plain UTF-8 text on stdout and exits 0; there is no -o json mode. The bridge treats stdout as the answer unless it matches /^\s*Error:/ (agy reports failures as Error: <message> on stdout, still at exit 0), in which case it classifies the failure into an error envelope.

Flag mapping the bridge applies to agy:

Bridge input agy flag
sandbox: read-only (advisory) --sandbox (terminal-only; see below)
sandbox: workspace-write --dangerously-skip-permissions
include-directories: [...] repeated --add-dir <dir>
gemini-reply (multi-turn) --conversation <id>
always --print-timeout <duration> and -p <prompt>

There is no -o json. agy (>= 1.0.9) does take --model, and the bridge always pins it, so a run never inherits the operator's ~/.gemini/settings.json (model.name). Model ids fuse family and reasoning effort - gemini-3.6-flash-high; the bare family (gemini-3.6-flash) is rejected with requires --effort. agy models prints display names (Gemini 3.6 Flash (High)) which --model also accepts, but the slug is canonical. Resolution order is per-call model > providers.gemini.model in config.json > GEMINI_DEFAULT_MODEL > the built-in auto-gemini-3. Point at a different agy binary with AGY_BIN. agy print mode does not enforce folder trust.

The bridge probes agy --help once per process to learn whether the flag exists (agy < 1.0.9 rejects unknown flags outright). agy 1.1.x prints its usage to stderr only, so the probe reads both streams - reading stdout alone never saw --model, warned "does not support --model" on every boot, and silently dropped the pin (issue #180 (external)). That also means the pin had never reached a real agy before: the built-in auto-gemini-3 alias is not in agy models on 1.1.x, and agy rejects an unknown id with invalid model selection (exit 1, about 3.5s, because it fetches its catalog first). Two outcomes, by whose pin it was:

  • The shipped alias (auto-gemini-3, seeded into every install's config): the call does not fail. runGemini retries once without --model within the remaining time budget (agy then uses its ~/.gemini/settings.json), warns once per process on stderr, and omits the alias for the rest of the process. The response carries pinDropped: true and the unified envelope reports model: "agy-settings-default" rather than an id that never ran. Set providers.gemini.model to an id agy models lists to stop the warning.
  • Any other id (config, GEMINI_DEFAULT_MODEL, or the call): a typo or a stale pin is the operator's config error, and running some other model behind their back would be worse than failing. The call fails as errorKind: "model-not-allowed" (not retried) with agy's own message, which lists the catalog, forwarded as message.

The pin is located by position (--model <id> sits immediately before the -p <prompt> tail that buildAgyArgs always emits), never by scanning argv values, so an --add-dir path or a prompt can never be mistaken for the flag. The --help probe itself is bounded (15s); a probe that times out is treated like a failed spawn (assume supported).

The built-in stays the portable auto-gemini-3 router alias because the concrete catalog differs per install - shipping a pinned id would hard-fail every call on a machine that lacks it. Pin a concrete id in config.json where you can: the alias routes server-side, and agy's catalog also carries Claude and GPT-OSS entries, so a routed call can seat a non-Gemini model in the Gemini slot and silently collapse cross-vendor independence in ask-all / consensus, with nothing in the result envelope showing it. Run agy models to see what this machine actually offers.

Read-only is enforced by the bridge, not by agy. agy's --sandbox restricts only terminal commands - the agent's file-edit tool is unrestricted, and the model can bypass the terminal restriction per tool call. So a read-only dispatch does NOT rely on --sandbox alone. The bridge layers its own enforcement on every read-only run:

  1. macOS OS sandbox - the agy process is wrapped in sandbox-exec with a Seatbelt profile that denies all file writes except ~/.gemini (OAuth + the conversation cache that backs threadId continuity) and temp dirs. Workspace writes are blocked at the kernel. Disable with DELIBERATION_DISABLE_OS_SANDBOX=1.
  2. Prompt guard - a hard advisory instruction block is prepended to the prompt.
  3. Git mutation detection (all platforms) - the bridge snapshots git rev-parse HEAD + git status --porcelain of the consulted cwd (and any --add-dir roots) before and after the run; on a diff it prepends a WORKSPACE MUTATION DETECTED warning and sets workspaceMutated: true on the result. No auto-revert - the result is surfaced as tainted for the caller to act on.
  4. Env scrub - the child env drops the kill-switch and push/exfil credentials (GITHUB_TOKEN, GH_TOKEN, GIT_ASKPASS, SSH_AUTH_SOCK).

The network is intentionally NOT isolated (agy needs its API + OAuth token refresh), so a determined delegate could still push pre-existing commits or exfil over the network - read-only contains local writes. On Linux there is no OS sandbox in v1; read-only there relies on the prompt guard + mutation detection (bwrap is a documented future seam). workspace-write (the direct gemini tool only) is an explicit opt-in that intentionally skips all of the above.

Grok bridge

A bundled zero-dependency Node bridge over the xAI Responses API (/v1/responses). It is advisory-only (it cannot edit files) but it can read attached files: pass files: [{ path | file_id | file_url | dir }] and the bridge delivers them per the mode setting - uploaded to the xAI Files API (default), inlined as input_text (for line-by-line reading of source files), or expanded via the bundled glob walker for directories. Resolution is against the top-level roots: string[] (first-root-wins) or cwd when roots is omitted. Uploaded files are SHA-256 dedup-cached locally and carry an expires_after (default 7 days); manage with /grok-files (list / prune / gc). See Grok files and cleanup.

The bridge default model is grok-4.6. It needs XAI_API_KEY in its environment; a missing key surfaces errorKind: "missing-auth". Replies are read as a stream, which is what makes a configured timeout above 300s reachable at all - see Grok streaming.

Rendered from TECHNICAL.md in the repository.

Type to search the site.