small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs provider-requests.md
16 kB · 281 lines
Markdown
at main

Provider requests #

The daemon records provider attempts separately from the conversation transcript. requests.gleam owns the row schema, prefix hashing, recording, and queries. sdk/request_history owns the Prefix value type and the selection of a session's latest completed turn. These records support usage and cache analysis. They do not store request bodies.

What a row holds #

A row identifies the session, request kind, profile, provider, account when known, model, timing, outcome, and optional status and error. It can also contain reported usage, cost, stream observations, and response identifiers. Kinds include turn, summarizer, background, title, and side calls. outcome bounds HTTP and provider error details to 2,000 text scalars before adding a truncation marker. See Call, outcome, and record.

record returns a result, so a storage failure can prevent a row from being recorded. A row starts with a null transcript sequence. attach_in can attach it after the transcript row commits. Reported cost contributes to session spend in the same store operation as the insert. Missing cost adds nothing.

Prefix identity #

prefix hashes the instructions and tool definitions as the request head. It records the projected input count and, when projection replaces history, the count replaced and a hash of the replacement. direct_prefix describes calls outside session projection without a replacement identity. These hashes help compare requests without storing their bodies. They do not prove a provider cache hit.

Reading requests and usage #

page reads session rows with an ID cursor and time filter. requests.last_turn reads the latest completed turn row whose transcript sequence is attached, with the background calls that repeated its prefix. It selects that turn through request_history.last_turn_in, which also serves the narrower request_history.last_turn that extensions use. The session HTTP handler exposes the request listing. The usage-hours migration defines an insert trigger that aggregates calls, errors, and token counts by hour, profile, provider, account, model, and kind. See quota for separately polled provider readings.

Usage totals #

usage_hours.summary reads hourly aggregates into day totals and per-profile, provider, account, and model summaries. It reports when its model or account lists are truncated. Day totals include all matching aggregate rows, including rows omitted from those lists. These are totals of recorded usage, not an independent measurement of provider billing.

Token counts #

Upstream.count is a provider's own count of the input tokens a request would take, asked of its count endpoint, or None for a route that has none. Nothing estimates a count in its place. sdk/token_count posts the body the provider extension encoded and reads the number at the path its Endpoint names; a refusal comes back as the provider's own error. An endpoint says what a refusal means: NotFound marks the route absent for a day on a 404 or 405, and AnyRefusal does on any refusal, for a credential the endpoint is not documented to take. The two are remembered apart.

OpenAI profiles that speak Responses ask /responses/input_tokens, and Mistral asks the same path with its history bridged to Responses items. Anthropic API keys ask /messages/count_tokens. A Claude subscription asks the same on api.anthropic.com in Claude's identity encoding, with its billing block's placeholder digits and AnyRefusal. Vertex asks the model's :countTokens with the Gemini contents, system instruction and tools. Bedrock asks CountTokens on bedrock-runtime with a Converse input or Claude's InvokeModel body, signed over the exact body with the aws_sigv4 package.

Antigravity, Codex, GitHub Copilot, OpenCode Go and Zen, and Perplexity count nothing, and each says why where its upstream is built.

Image generation #

The Codex image driver does not record its calls through requests.record. Image generation is therefore absent from these request listings, recorded spend, and usage totals. Missing image usage does not establish that a call consumed no quota or incurred no charge. See image generation for request identifiers and recovery rules.

Transport #

openai_api validates client header values before transport. stream_http handles streaming exchanges, and transport exposes both ordinary receive and deadline-based receive functions. Do not assume every stream wait has a timeout.

The connection coordinator tries IPv4 and IPv6 concurrently for hostnames. HTTPS selects the first connection that completes certificate verification, so a failed or stalled TLS handshake on one family does not discard a usable connection on the other. IP literals use only their own address family.

The streaming transport owns the request flow, pooled reuse, the replay rules, and each connection's state. framing reads response bodies, and the connection pool keeps finished connections for the next request to the same host. request_body owns a body's plan, its length, whether it may be compressed, and its streaming write with stored images and the attestation marker. Its writer reports a refused send as SendError, so the error keeps the socket reason. The native transport adapter keeps only the receive that waits on one socket and the walk over untyped body iodata. The transport's destination function returns the request URL unchanged. The offline Antigravity fixture in antigravity_support replaces it in the generated Erlang of a private build to route requests to a local server.

The streaming transport builds TLS options and loads trusted certificates only for HTTPS connections. Plain HTTP connections do not need that initialization.

One monotonic deadline covers fresh connection establishment, including DNS, TCP, TLS, and socket handoff. Cleanup confirms that losing attempts have stopped before returning. Cleanup can finish after that deadline while workers are being stopped. This budget does not replace the separate send, first-event, or response-body budgets.

Every provider connection is marked DSCP CS1 (bulk) after it connects, tos on IPv4 and tclass on IPv6, so routers that queue by DSCP and Wi-Fi's background access category send games and calls ahead of large request uploads. A platform that refuses the option leaves the connection unmarked. See mark_bulk in connect.gleam.

A wire asks for a compressed request body with transport.zstd or transport.gzip; the transport compresses it once before taking a connection and adds the matching content-encoding, so a pooled retry resends the same bytes. Only endpoints known to accept it ask: the Codex backend with zstd, which its own CLI sends by default; Responses on https://api.openai.com/v1 with zstd, which OpenAI documents; and Claude's Messages with gzip, which Claude Code sends. A body carrying stored images goes out uncompressed, because compressing it would hold every image in memory at once and base64 images barely shrink. See encode_body in the streaming transport.

The coordinator owns the attempt processes, their cleanup, socket handoff, and connection selection policy. Each attempt dials, upgrades to TLS and checks an IP literal's certificate through direct gen_tcp, ssl and public_key bindings in connect.gleam. Attempts must not send HTTP requests. Only the selected connection reaches the existing request guard and HTTP writer. Preserve certificate and hostname verification, pool ownership, and the rule that guarded requests never replay implicitly when changing this path.

A provider's outbound route is its extension id's. Tunnel negotiation precedes destination TLS verification, and pool keys distinguish routes.

Antigravity metadata #

The Antigravity wire encoder derives each session's cascade UUID from the Albedo session ID. Each session is its own root cascade, including forks and child sessions. The cascade UUID also starts the agent envelope's requestId. The provider adapter keeps that envelope ID across a signature-only resend.

The counter owner stores a random trajectory UUID and the next request index in antigravity_request_state, which Antigravity declares as its table. ModelContext.storage and web_search.Query.storage supply Antigravity's storage handle without allocating state during model resolution. Each attempted agent envelope reserves an index on the database writer before encoding and sending. Its request_id label is <trajectory>-<index>, starting at zero. Signature resends, quota retries, and Antigravity searches each reserve another index. Titles do not. A crash or encoding failure may leave a gap. SQL errors and exhaustion prevent that send rather than resetting the counter. Losing the store stops the caller through the existing store failure boundary.

The row survives restarts and history projection. Session deletion removes it. Transfers exclude it because the source can still send after export. A target with no local row starts a new trajectory at zero; an existing local row resumes its own trajectory and index. Cascade and session IDs stay unchanged across the move. There is one row per provider conversation identity, not per attempt. Synthetic proxy identities have no session-deletion lifecycle, so their counter rows remain in that daemon's database.

The outer agent step still starts at one and counts model turns in supplied input. It is not the request counter and can shrink after projection. sessionId is now signed FNV-1a64 over the UTF-8 Albedo session ID. This changes the previous SHA-derived wire value for existing sessions. The native client's hash seed is unknown; Albedo uses its own session identity rather than a shared constant from a capture. Counter semantics are Albedo's explicit reservation policy, not a recovered native retry protocol.

Session naming sets Options.purpose to SessionTitle. Antigravity encodes it as requestType: checkpoint with a fresh checkpoint/<uuid> request ID and omits agent lifecycle labels. Other requests default to agent. Purpose does not select a model or change instructions, tools, or input. It is not a generic JSON request field for other providers.

The identity module uses the hub user-agent family and the reference darwin/arm64 platform. The fallback release is 2.32.1, paired with build 1021296516. Only that release gets a cl field. Other cached or overridden versions omit it rather than claiming an unrelated build. Model discovery still refreshes the version from the public updater manifest. ALBEDO_ANTIGRAVITY_VERSION overrides the inference and sign-in version, not discovery's manifest version.

These choices do not establish provider acceptance or prevent account restrictions. Preserve the provider and retry boundaries when changing this metadata.

Mistral wire projection #

The Mistral wire module normalizes streamed thinking parts, projects replay for the current reasoning effort, and maps tool IDs before using the shared Chat Completions codec. It leaves stored replay unchanged. The sign-in module builds the browser sign-in's requests and PKCE pair, checks that returned URLs stay under the console, builds the stored key account, and runs the status poll. See sign-in ownership for deadlines, input wakes, and cancellation.

Claude image uploads #

claude/files owns Files API multipart requests, response IDs and expiration, and inline fallback. It uses SDK HTTP requests and four linked concurrent workers. A reader or upload failure leaves that image inline while successful uploads remain reusable. Stopping the caller stops its workers. A stopped batch does not publish partial cache state. The provider extension still supplies the account identity, credential header, and approved endpoint. Uploads do not choose another credential destination.

The persistent claude-files.json format remains an account object containing content keys and entries with id, bytes, and optional millisecond expires_at. Content keys hash the base64 payload. Fresh callers reuse saved handles. Expired handles and unreadable caches fall back inline. An unreadable cache is left unchanged. Newly uploaded handles become visible only after a successful cache write. A failed write leaves those images inline.

The shared file.with_lock protects short cache reads and merges. Image readers and HTTP uploads run outside that lock. A separate home-wide upload slot admits one batch with four workers; file.with_lock_timeout waits at most 50 milliseconds for this optional work. A busy slot leaves missing images inline. Empty and fully cached requests skip upload admission. Locks are daemon-local and independent of credential transactions; they do not coordinate separate OS processes.

A file-related 4xx rejection quarantines the caller and advances the account's in-memory generation under the cache lock before attempting a purge. Uploads capture that generation and discard results if it has changed before the merge. Fresh reference tokens also reject old results after generation storage is lost. A failed purge still fences earlier uploads, although existing saved handles may remain available to other callers. Other accounts survive the purge. Later callers may upload fresh handles; caller-local quarantine ends with its process.

Wire encoding loads one fresh account snapshot per request and projects all images from it without further disk reads. A later request observes sibling purges. This snapshot cannot revoke a request that has already been assembled. Keep this persistent cache with its feature owner; transient memo entries do not replace it.