Provider adapters

The selected Local Antigravity sign-in is confirmed. Its 1.2.7 headless initialization still advertises native tools despite the requested empty tool list, so an Antigravity SDK adapter and live application certification remain pending. See the readiness evidence and no-prompt check. This limitation does not require signing in again or switching to API billing.

Documentation reviewed on 2026-09-21. Model IDs are deliberately supplied by the application or host; this SDK does not silently pick a model or change billing modes.

An API key may be a string or an async credential resolver, so a host can integrate a secrets manager. Options also include id, name, models, and an optional server-owned baseUrl. models is an allowlist, not just presentation metadata. CLI options include a trusted binary and absolute accountDirectory; remote requests cannot choose binaries, arguments, environment variables, or directories.

Custom local or enterprise integrations can use the provider extension kit. It supplies a versioned construction contract, trusted host registration and real service integration without changes to the runtime or language clients.

Subscription mode is provider-specific#

Codex supports a ChatGPT sign-in as well as API-key authentication, and OpenAI documents programmatic SDK integrations. The Codex adapter runs the official codex app-server --stdio protocol and leaves authentication to that CLI. Development source requires the qualified CLI 0.157.0 protocol; the published 0.1.0 package still contains the older exec adapter. Codex authentication, Codex app server.

Claude Code can run as an unmodified binary with the end user's own sign-in. Anthropic's documentation distinguishes this from offering Claude.ai sign-in in a third-party application or routing users' consumer credentials through a service. Use the API adapter for a conventional hosted Claude product; assess the official integration requirements for an end-user CLI deployment. Claude Code integration and authentication requirements.

Gemini CLI documents headless mode and reuse of cached authentication. Its available quotas depend on the user's authentication method and account. Headless mode, authentication.

Live checks on 2026-09-21 found that the selected personal Google sign-in was rejected as an unsupported client route on Gemini CLI 0.58.0 and the current stable 0.60.0. The SDK reports CLI_AUTH_UNSUPPORTED; it does not infer quota, subscription tier or successful model access from cached credentials. See the recorded validation limits. Google's Antigravity migration guidance describes a separate route; it is not an automatic fallback in this SDK.

AgenticDriver currently supports Grok through the xAI API. Official Grok Build headless/ACP and native sign-in interfaces now provide an integration route, but its SDK adapter and live certification are pending. See the dated feasibility decision and implementation work. An isolated test of Grok Build 1.0.40 found that setting native inference idle to zero still terminates after ten seconds of silence. It also attempted separate session-title generation. These controls need qualification before the SDK can offer its default disabled-inactivity contract through that native route; the test used only a synthetic local endpoint, with no account or paid inference. The published 0.1.0 xai() adapter retains Chat Completions. Development source also offers an explicit xaiResponses() factory and xai-responses host kind; see the unreleased Responses adapter and migration guide. xAI recommends Responses for new integrations. Both API paths remain separate from the pending Grok Build native-session route.

The normalized mode is called cli-session: an existing CLI login may itself use subscription or API billing. The SDK does not infer the plan, scrape browser cookies, extract OAuth tokens, or treat subscriptions as universal API credits.

CLI execution policy#

The adapters use an empty temporary working directory, stdin for user content, an explicit environment allowlist, bounded stdout/stderr, process-group termination, and runtime feature checks. Ambient application API keys are not forwarded to a CLI. A host-owned account directory selects a separate account without copying its credentials. For Gemini, accountDirectory is the home directory containing .gemini, as used by GEMINI_CLI_HOME; it is not the .gemini directory itself.

• Codex starts an ephemeral app-server thread and turn with environments: [], a read-only sandbox and no application tools or capability roots. It disables agents, goals, hooks, plugins, apps and web search, and explicitly disables every inherited MCP server before creating the thread. Ambiguous MCP names fail before the prompt is sent. The native model still advertises sandboxed JavaScript, a clock and an asynchronous question utility; the SDK rejects client-side authority requests. An explicitly configured application-tool bridge exposes only selected SDK tools through an owned MCP helper; inherited MCP servers stay disabled. Native shell, file, image, agent, MCP and goal operations are unavailable in the default text registry. Global AGENTS.md and skill descriptions still enter the prompt. See the native evidence and limits.
• Claude Code uses restricted mode, safe mode, no tools, strict empty MCP configuration, no session persistence, and noninteractive permissions. Development source explicitly disables fallback chains and switching models after a flagged response; a refusal remains a refusal on the selected model. Its separately qualified metadata probe does not submit a prompt. The dated execution qualification covers native Linux 2.1.282 and two inexpensive live Haiku 4.5 checks, including cancellation, Usagestat capture and provider-specific billing/deployment limits.
• Gemini CLI uses a settings override with an empty effective tool allowlist, disabled hooks/extensions/MCP/skills/agents/auto-memory, an empty context configuration, and a supplemental deny-tools policy. Host administrators' policies still apply.

These are CLI controls, not an operating-system isolation boundary. Run separate hosts or OS users/containers for mutually untrusted accounts. maxOutputTokens is passed to API providers; CLI text adapters currently rely on their native output limits and the SDK's output-byte limit. Inactivity timeouts are optional and disabled by default for both CLI and API providers.

API adapters request SSE and forward text deltas before a turn completes. Claude Code runs with stream-json and partial messages; Gemini CLI uses stream-json. The Codex adapter emits completed message items and uses native deltas for progress, so it conservatively advertises textStreaming: false. Quiet native reasoning is observable only when the CLI emits an event. A provider that returns JSON instead of SSE remains usable, with progress visible only when that response completes.

Gemini startup and streamed failures preserve fixed actionable codes: CLI_AUTH_UNSUPPORTED for the unsupported account route, CLI_AUTH_REQUIRED for recognized missing/expired authentication, RATE_LIMITED for recognized quota/rate failures and UNSUPPORTED_MODEL for an unavailable model. Unknown native failures remain CLI_FAILED. Native stderr is privately inspected only on failed exits, bounded to 64 KiB for classification, and is never copied into public error messages. CLI JSON result failures are classified before a nonzero exit can obscure them. These mappings do not add automatic retries.

Claude Code's structured session-limit rejection maps to RATE_LIMITED, before the native process's nonzero exit can obscure it. The SDK returns fixed text; raw native diagnostics and local reset-time details stay private. Ordinary assistant text and nonterminal quota warnings do not become failures. Catalog availability can remain visible while the selected subscription is exhausted.

Codex's recognized native HTTP 401 and permanent session-refresh failures, rate-limit and missing-model diagnostics map to CLI_AUTH_REQUIRED, RATE_LIMITED and UNSUPPORTED_MODEL. Unknown errors remain CLI_FAILED; native diagnostic bodies and endpoint URLs stay private. The native CLI owns credential refresh. Its auth recovery can make multiple HTTP attempts within one execution. If startup refresh invalidates native network policy before initialization replies, the adapter can reopen the process once under freshly loaded native policy, before sending any thread or prompt. It never replays a submitted prompt through that recovery path. A repeated policy change returns CLI_POLICY_CHANGED; no native permission is bypassed. These mappings and the additional Codex options below are development changes after the published 0.1.0 release.

Set reasoningEffort on a Codex provider instance (or its host configuration) when the application needs an explicit native reasoning setting:

codex({
  id: "selected-codex",
  models: ["gpt-6-luna"],
  reasoningEffort: "medium",
});

The native CLI validates the effort against the selected model. Omitting it uses the native CLI/model configuration. Set it explicitly when the application requires a particular effort. This is a host-owned setting; applications select a configured provider instance rather than passing arbitrary native configuration in remote requests. Availability depends on the account and model; the SDK never substitutes another model.

Provider state and usage#

OpenAI Responses output items, Anthropic content blocks, Gemini thought signatures, and compatible assistant messages stay intact inside a tool loop. They are not exposed as application data. Refusals, invalid JSON, truncated tool calls, nonzero CLI exits, and missing terminal markers fail explicitly.

Token totals include cached input; cached-input tokens are also reported as a subset when available. Gemini API output includes reported thought tokens; Gemini CLI streaming reports its native output count, with reasoning tokens unavailable. Usage measurements remain absent when unavailable. Claude CLI's costUsd, when reported, is its API-equivalent estimate and does not establish the amount charged to a subscription account. Never treat missing cost as zero.

API format references: OpenAI function calling, Anthropic API overview, Gemini generateContent, Gemini function calling.

Streaming format references: OpenAI streaming, Anthropic streaming, xAI streaming.