small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
albedo robot-docs proxy.md
4.6 kB · 90 lines
Markdown

Proxy #

The proxy extension exposes a Chat Completions interface over saved provider profiles. It projects the conversation in each request to the selected upstream. See authentication for accounts and models for catalog lookup.

Endpoint #

The proxy extension admits GET /extensions/proxy/v1/models, GET /extensions/proxy/v1/models/{id}, and POST /extensions/proxy/v1/chat/completions. The default admission requires the daemon token. If ALBEDO_PROXY_ALLOW_ANONYMOUS is exactly 1, these routes use local access instead, as defined by allow_anonymous.

The models response names entries as <profile>/<model>. A profile with a custom endpoint lists its saved model. Other profiles use the provider catalog when available and otherwise list the saved model. The response can include a nonstandard errors field for unusable profiles. Each entry carries a nonstandard efforts field: the reasoning efforts its model takes, the list a chat request's effort is checked against, empty for a model that takes none.

GET /extensions/proxy/v1/models/{id} returns the same entry for one <profile>/<model> id, such as claude/claude-haiku-5-5; the slash may be sent as is or as %2F. A bare profile name stands for its saved model. The model need not be listed, as for chat requests; an unknown profile returns 404.

Translation #

chat.from_fields splits the requested model at the first slash. With no model suffix, the proxy uses the profile's saved model. The parser accepts the fields listed by request_fields, logs unknown fields at debug level, and validates options, tool count, and token limit. It rejects invalid input with a 400 response.

A request that names reasoning_effort or reasoning.effort must name an albedo level (types.Effort); any other name is refused with a 400. The level is checked against the efforts the profile accepts for its model, the list sessions use: the model's catalogue entry, or the Bedrock Converse table for such profiles. chat.check_effort refuses an effort that list leaves out, and any effort for a model that takes none, with a 400 naming the accepted efforts, before the upstream is called. The proxy does not translate efforts: none works only for a model whose catalogue lists it.

The extension resolves the profile and upstream, projects the supplied history, and calls the upstream stream interface. Non-streaming upstream errors return 502. Streaming replies use server-sent events and finish with [DONE]. An upstream error is emitted as an error event. The client supplies the conversation on each request.

Thinking #

For a model that thinks, its thinking tokens count against max_tokens or max_completion_tokens and are included in completion_tokens. A reply that runs out of room while thinking ends with finish_reason: "length" and can have little or no text. completion_tokens_details.reasoning_tokens appears only when the provider reports a thinking count; Claude does not, so it is absent for Claude models.

Claude models think by default when the request names no effort. Measured through the proxy, trivial prompts added no thinking tokens and hard ones added 3,000 to 10,000, and the thinking text was not returned. Name a lower effort from the model's list, such as low, to think less, and leave enough max_tokens for the thinking. Claude's catalogue lists no none, so the proxy has no way to turn its thinking off.

State #

chat.carry carries provider-specific turn state for replay. The extension replays carried turns verbatim only to the profile that produced them. chat.pack compresses state with sdk/zlib into URL-safe base64. chat.unpack bounds decompression to 4 MiB. Invalid or altered packed state takes the portable replay path.

The synthetic conversation identity can also key provider-owned metadata. Antigravity persists a local trajectory and request counter for it, without storing the supplied history. Those rows have no normal session-deletion lifecycle and remain in the daemon's database.