Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

9.9 KB
Raw Blame

Google protocol consumer extension

Normative since the v11 Model Hub contract. This extends the existing gateway, EngineAdapter and pinned CPA transport; it does not add a provider implementation to agent-core, change backend registration, or upgrade the engine.

Source admission and observation

The complete protocol vocabulary includes google. New Google API-key Sources are admitted with vendor: "custom", explicit protocol: "google", an explicit Base URL and the usual transient key through the existing observe/create APIs. Since v22 the gemini catalog row pins google on Google's native root, so a Gemini API key is a google Source of vendor gemini (../vibey-gemini-native.md §3), and one saved on the OpenAI-compatible endpoint moves to it on load. Existing vendor pins, subscriptions, OAuth and native CLI configuration do not change. The UI protocol picker still contains only its three approved options. Existing Source details can label Google; its tier suggestions are empty. The Google vendor rule (custom, or the gemini catalog pin) is validated before API credential work and at config/runtime Source admission; unverified save cannot bypass it. Source and SourceCreate schemas enforce the same conditional.

The Base URL is the upstream origin or a proxy root, optionally ending in /v1beta; that suffix is removed only for CPA configuration because its Gemini executor appends it. Query-bearing roots are refused before Source registration, because this executor appends paths rather than preserving a Base URL query. Discovery calls <root>/v1beta/models, supplies the held key as x-goog-api-key, and follows nextPageToken on that same endpoint. Redirects, malformed pages and repeated continuation tokens fail the whole observation; partial inventory must never replace a saved list. A custom Source's model names lose only their models/ API resource prefix; a gemini Source keeps Google's models/<id> names, as its OpenAI-compatible listing always named them, and its engine entry routes each by that alias while calling the bare id upstream. Inventory does not invent limits, vision support or reasoning tiers.

Google is not added to custom Auto detection: its inference endpoints require a model in the path. Add-time observation performs no model call. For an explicitly declared protocol, the existing credential witness rule applies: a listing that accepts the supplied key and rejects the same uncredentialed request establishes authentication; public lists do not. Explicit unverified save remains available. A user-requested saved-model probe uses a Gemini contents request.

Consumer and transport

ModelHubLaunch.to_hop_resolution() and the runtime router return protocol: "google" and the gateway frontend Base URL ending in /vibey/v1beta. Required request_headers, gateway token, runtime model, Source identity, provider identity and nullable capabilities have exactly the same owners as in vibey-consumer.md.

The gateway accepts:

  • POST /<backend>/v1beta/models/<runtime_model>:generateContent
  • POST /<backend>/v1beta/models/<runtime_model>:streamGenerateContent?alt=sse

It also accepts omitted alt or $alt=sse on the streaming path, always using SSE. Other alt values are refused before admission. Model and streaming mode come from the path, not JSON model or stream fields; those fields are refused. Callers percent-encode the runtime model as one path parameter. The engine client likewise encodes model identity as data, retaining only its deliberate Source.prefix/model boundary as a structural slash; dot segments and leading slashes in admitted model ids must not change routing. countTokens, embedding/batch APIs and query-string credential authentication are not consumer endpoints. A caller uses the returned gateway token through Bearer authentication or x-goog-api-key; upstream keys never cross this boundary.

The engine request routes Source.prefix/model_id in the URL and uses the Google frontend regardless of the selected Source's protocol. CPA owns native or cross-protocol request/response conversion. Avibe performs no duplicate translator. The engine remains v7.3.16 at upstream c404af96 with the existing Avibe patch.

Pinned-engine limitations and admission skips

For Vibey streaming only, a Google frontend request cannot admit an openai_responses Source hop: the pinned CPA Responses/Codex-to-Gemini translator does not emit finishReason for response.completed. Before transport/recovery admission, skip that hop with stable reason google_stream_responses_unsupported and continue the request's effective chain. The reason is recorded on the Model Hub service diagnostic log record's reason field with the exact Source/model identity. A skip is not an upstream attempt: no health transition, cooldown, metering, failed-attempt entry, or served origin is fabricated. If all selectable hops were skipped without an upstream attempt, return local HTTP 422 with that same machine reason and no served-hop header. If actual upstream attempts failed too, ordinary exhaustion still owns the turn.

For Vibey Google-frontend requests, buffered or streaming, a selected original model id containing : is also unsupported: CPA splits the decoded Google action on every colon, so percent-encoding does not preserve that identity. Skip exactly that hop with reason google_model_path_unsupported before transport, recovery or attempt admission. Continue the chain, including a later supported model on the same Source. Do not rename, truncate or normalize the configured model id. This check precedes the streaming conversion check when both apply. If all hops are skipped, the last skip reason is returned in the same local 422/no-origin envelope. Logs retain each exact skipped identity and its reason. An explicit Agent probe still tests only its selected hop: an unsupported Google model returns the same controlled 422 reason instead of retrying a permanent local limitation as a changed route.

Saved-Source probes are an explicit exception to the Vibey-only consumer scope: they test one exact inventory model with a buffered request in the Source's protocol. A Google Source model containing : returns local HTTP 422 with google_model_path_unsupported, not an upstream/model failure. It does not try another model, admit a transport or attempt, settle recovery, verify the credential, meter usage, or attach a served origin. The internal opencode adapter-dispatch marker does not make this Model Hub operation a native CLI call.

One pure predicate owns the two engine limitations, from frontend protocol, Source protocol, original model id and streaming mode. Vibey routing/Agent probes and saved-Source probes explicitly apply it before engine preparation and to the locked, revalidated snapshot immediately before adapter admission. A request already known to be unsupported at preflight does not start/reconcile the engine or drain credential custody; a supported fallback retains ordinary demand preparation. A later configuration change is checked again before any inference admission. Source observation and inventory discovery remain model-free and do not apply these inference-path checks.

Native CLI behavior is unchanged. Google buffered conversion, Google/Anthropic/ Chat streaming without model colons, and all other frontends served by a Google Source are not skipped. No usage frame or clean EOF is interpreted as a missing model terminal. Fixing the engine and publishing a replacement managed-runtime asset is a separate owner-authorized release operation, not part of this PR.

Response facts and provenance

Google candidate content parts are model output; metadata alone is not. Native finishReason or prompt blocking marks terminal completion; there is no [DONE]. Native error envelopes (unnamed or CPA's event: error) are failures. The existing no-fallback-after-output rule remains in force. A buffered promptFeedback.blockReason completion needs no candidates array and is positive recovery evidence, just like its streaming terminal. Empty, malformed or error-bearing bodies do not gain recovery evidence from that field.

Token reports project usageMetadata.promptTokenCount (including its cached subset), cachedContentTokenCount, and the sum of candidatesTokenCount and thoughtsTokenCount. No report is guessed when the upstream provides none. Both buffered and streaming responses share these facts with metering.

Local JSON failures use Google's numeric error.code, canonical error.status, localized error.message, and details[].reason for the Model Hub machine code. Late local streaming endings use the Google error envelope. All carriers retain the response-origin policy of vibey-consumer.md: x-avibe-served-hop comes only from the immutable admitted invocation that actually supplied the response. Pre-admission/local failures have no origin header.

Vibey fallback compares each admitted hop with the launch's primary origin. For a different or unverifiable origin, Google contents[].parts lose opaque signatures and visible thought text becomes ordinary text; tool arguments and results are user data and remain intact. Same-origin requests retain signatures. Cross-protocol fallback follows this same policy before CPA conversion.

Validation and compatibility

The shared Source enum guard includes create, observation and Source-probe contracts, runtime storage, config, adapter and UI type consumers. The new writer generation is 11; persisted provenance generations 5 through 10 still load, and released configuration fixtures retain their meaning. Only version literals change in existing UI browser fixtures.

Owning tests cover config/runtime/YAML round trips, Google URL/body admission, finite stream facts and metering, paginated credential witness/refusals, same/different-origin gateway fallback and served provenance. Real pinned-engine tests isolate all state and allow only loopback upstreams. UI validation uses the existing hermetic Model Hub browser suite and production build.