small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo

26 kB · 114 lines

Markdown

ptr.pet · tui: /login makes any number of named profiles per provider, edits a profile's account with ctrl+e and renames it with ctrl+r · 1w ago

57acd2e5

model authentication #

model authentication is supplied by model-provider extensions rather than the daemon configuration loader.

credentials #

Every secret albedo keeps lives in $ALBEDO_HOME/creds.json, mode 0600, and only the daemon reads or writes it. It has three sections: accounts holds OAuth accounts (and an optional alibaba key) by store key, one object or an array; providers holds each profile's apiKey by profile name; mcp holds each MCP server's bearerToken, headers and env by server name. All credential and settings mutations share one per-home daemon lock. OAuth refreshes retain their re-read under that lock and preserve other sections. config.json keeps no keys: an apiKey still written there by hand is used and wins over the saved one until the next daemon start moves it.

Account limit marks under accounts are recorded per model-family meter for Google Antigravity (limitedMeters: {"claude": <epoch ms>, ...} with meter keys gemini, claude, gpt-oss, falling back conservatively to legacy limitedUntil when limitedMeters is absent), whereas Codex, Alibaba, and OpenCode Go record account-wide marks in limitedUntil.

At start the daemon moves secrets still kept elsewhere into creds.json: auth.json's accounts, mcp-credentials.json's servers, and each config.json profile's apiKey. It writes creds.json first, then moves the old files into backups/ as <name>-before-creds-<ms> with every mode bit cleared, so an interrupted start loses nothing and the next one finishes. Not even their owner can read the backups without chmod 600 first, so tools and agents running as the user never read them by accident; rm -f deletes them.

Clients save provider profiles and MCP configuration with credentials through the settings API. Reads disclose saved credential presence, never secret values. Provider keys belong to PATCH /settings?group=providers; MCP secrets belong to PATCH /settings?group=mcp. Both use the observed group validator and commit public and private changes together.

GET /server includes credential migration notices for files moved during this daemon's start. Reading a notice does not consume it. Clients dismiss notices through ui.dismissed_notices. Original files remain sealed in backups/.

openai-compatible api keys #

The enabled-by-default openai extension requires models. It handles existing named OpenAI-compatible profiles and both Responses and Chat Completions. The Responses stream decoder accepts servers that leave output_index off their events (llama.cpp's llama-server) by placing each event with its item_id, and treats a missing content_index as 0. Model discovery comes from the models.dev cache, not the configured API endpoint. Older config.json profiles without an extension field remain OpenAI profiles; newly saved profiles include "extension": "openai".

chatgpt codex oauth #

The enabled-by-default codex extension requires openai, so it reuses the OpenAI Responses encoder, SSE transport, replay format, and model metadata. Its picker shows the models the ChatGPT backend offers the signed-in account (see codex models); API-key OpenAI profiles still show the full OpenAI catalog. /login can add ChatGPT Plus/Pro accounts. A fresh install can enter codex as the provider name; an existing install picks the ChatGPT row under new profile.

The daemon runs the login (see sign-in api) with the Codex CLI browser flow: PKCE S256, the allowlisted http://localhost:1455/auth/callback, state validation, and a manual callback-url/code input that races the local callback. The token exchange uses OpenAI's public Codex client id and stores access, rotating refresh, expiry, ChatGPT workspace id, seat id when present, and email when present.

Credentials live in creds.json's accounts under the openai-codex key. One account uses the legacy object shape; two or more use an array. A login replaces the same seat/account identity and appends a different account. /login lists saved providers and each stored account; ctrl+d on either row asks to remove it. Removing the active provider makes the first remaining provider by name active. A Codex provider with no accounts left reads signed out and starts a sign-in when chosen. Access tokens refresh under the credential lock 60 seconds before expiry, with a re-read under the lock so concurrent sessions do not overwrite a newer refresh.

Each session hashes its id into the account pool and stays on that account. If that account is invalid or cannot refresh, selection continues through its siblings. When the Codex backend answers a request with 401 (for example token_revoked), that account is removed from creds.json and the turn fails with an error ending in run /login; the TUI opens /login when that error follows a turn sent from the open chat. Requests use https://chatgpt.com/backend-api/codex/responses with Bearer auth, chatgpt-account-id, Codex experimental Responses headers, and the session request id. Codex request bodies force store: false, automatic parallel tools, low text verbosity, encrypted reasoning replay, and nullable tool strictness.

The oauth callback binds only to 127.0.0.1. Port 1455 is fixed because OpenAI allowlists the exact redirect URI; a busy port fails instead of silently changing redirects.

/login lists your provider profiles, the accounts the daemon holds, and a new profile section. Every row there makes a new named profile, whether it signs in (Claude, ChatGPT Codex, Antigravity, OpenCode Go) or takes an api key (Anthropic, Alibaba, OpenCode Go and Zen, Bedrock, Vertex, OpenAI-compatible): OAuth and api-key profiles are the same kind of thing, and a provider can have any number of them. A sign-in profile asks for its name first (the provider's, or the next free <provider>-2), then which signed-in account it uses: one account (account_id pinned), rotate between accounts (account_id: null, every account of that provider), or another account, which signs one in now. Enter on an account picks the profile it signs in for, or makes a new one for it. On a profile row ctrl+e changes its credential (the account, or an api-key profile's endpoint and key) without touching its model or the default, ctrl+r renames it (the key, the default and its sessions follow; see settings), and ctrl+d removes it. Service sign-ins for tools (Colab) stay under sign in.

Browser sign-ins run in the daemon, so every client shares one OAuth implementation. An extension contributes extension.LoginPlugin(oauth.Login(...)): the profile extension it serves, a chooser label and detail, the protocol its profiles use, its creds.json accounts key, its loopback callback (host, port, path, and whether the port is fixed), and three functions. authorize builds the provider url from a Grant (redirect, state, PKCE verifier and challenge). exchange trades the code for the credential object to store and may report progress. account names a stored credential; equal ids are the same account. albedo_oauth owns the rest: the callback listener, the race with a pasted code, a 5-minute timeout, and locked writes. A sign-in replaces the stored account with the same id and appends a new one. One account is stored as an object, two or more as an array.

Clients use these resources with the daemon bearer token:

GET /auth returns advertised providers and forms, saved account descriptors, and incomplete login resources.
PUT /auth/logins/<id> creates a login at a client-generated UUIDv7 with {provider, flow, values}. Browser and manual flows use an empty values object. A known identical intent recovers the same resource; another intent conflicts. Creation returns 201; recovery returns 200.
GET /auth/logins/<id> returns retained state, browser URL, progress, completion account, and validator. States are waiting, exchanging, complete, failed, or cancelled.
PATCH /auth/logins/<id> with {response} and If-Match delivers a pasted callback URL, code#state, query string, or code. Callback and manual response compete for one exchange.
DELETE /auth/logins/<id> cancels the login and closes its listener.
DELETE /auth/accounts/<account-id> removes a saved account. A profile binding prevents removal until that binding changes.

Login identity and intent survive restart. Callback and PKCE material remain private. The daemon admits at most eight unfinished logins and retains terminal decisions for fifteen minutes. Browser launch remains client policy and respects ALBEDO_NO_BROWSER.

Clients list models through GET /models?provider_profile=<profile>. Profile defaults and account selection belong to conditional providers settings patches. account_id: null uses existing account rotation; an explicit ID binds runtime authentication to that account.

claude code oauth #

The enabled-by-default claude extension adds Claude Pro/Max accounts through /login using Anthropic’s Claude Code OAuth client. It stores rotating access and refresh tokens in creds.json's accounts under anthropic, refreshed under the credential lock. An account stored without a refresh token (a legacy or hand-edited one) is never refreshed: the request path skips it, and the quota poll keeps it so its auth failure is recorded. The fixed http://localhost:53692/callback loopback redirect must be available; a pasted callback URL also works. Choose a Claude model after signing in; profiles use extension: "claude" and protocol: "chat_completions". The picker shows Opus 5.5, Fable 5.1, Sonnet 5, Opus 5, Opus 4.8, and Haiku 4.5 only when the cached models.dev Anthropic catalog contains them. /reload models refreshes this availability and the models’ limits. New model families still require a picker-policy update.

Requests go to Anthropic’s Messages endpoint with Claude Code’s OAuth beta, client headers, billing attribution block, identity system block, and tool names. The billing marker is text in system[0], not an HTTP header; its CCH attestation hashes the exact outgoing JSON body. Top-level tool-schema combiners are flattened into an object with their property alternatives and common required fields; nested schemas remain intact because Anthropic rejects top-level oneOf/allOf/anyOf. This transformation lives beside the request encoder in harness/extensions/claude/schema.gleam and preserves unrelated schema fields, including definitions and custom metadata. Replay is saved as provider-neutral chat messages so changing models retains conversation and tool history. This is subscription access, not an Anthropic API-key profile. Anthropic can change or restrict this unofficial client behavior at any time.

google antigravity oauth #

The enabled-by-default antigravity extension signs in with the Antigravity IDE's Google OAuth client and sends requests to Cloud Code Assist (https://daily-cloudcode-pa.googleapis.com) for Gemini 3, Claude, and GPT-OSS models. /login lists it under new profile; a fresh install can also enter antigravity as the provider name. The daemon runs the sign-in through the sign-in api. Its callback is 127.0.0.1:51121/oauth-callback, which moves to an ephemeral port when 51121 is busy. After the token exchange it finds or provisions the account's Cloud Code Assist project: loadCodeAssist, a free-tier eligibility check, and onboardUser when the account has no tier yet, with progress shown in the client. An account that Google wants verified fails with the verification url.

antigravity/errors.gleam decodes error.details from the raw response before display truncation. Both streaming and sign-in use that decoder; never extract JSON fields from a formatted error with a regex. Sign-in uses the Google Accounts fallback only when VALIDATION_REQUIRED has no usable URL.

Credentials live in creds.json's accounts under google-antigravity, in the one-object-or-array shape: {type: "oauth", access, refresh, expires, projectId, email?, selected?}. The daemon tries the selected account first, then the others in order. A profile's own accountId instead confines that profile to one account: the pool it rotates through is that account alone, so a 429 on it names the pin rather than promising a sibling the request can never reach. Access tokens refresh under the credential lock 60 seconds before they expire. A 401 ends the turn with an error ending in run /login and marks that access token expired, so the next turn refreshes it; if the refresh token was revoked too, the account is skipped and reads as signed out.

Antigravity profiles use extension: "antigravity" and must use protocol: "chat_completions". The extension's upstream translates albedo requests into the Cloud Code Assist envelope, sends it through openai_api.exchange (the shared HTTP and SSE runner), and reduces Gemini's stream back into albedo events. Each assistant turn is stored as a Chat Completions message, so history, projection, and other providers read it unchanged. The exact Gemini parts, including thought signatures, travel in reasoning_details as an antigravity.parts entry and are replayed only to the model that produced them, at any of its effort tiers (gemini-4-argon-medium output replays exactly to gemini-4-argon-high, as oh-my-pi's collapsed ids do): re-encoding history on an effort switch would make the whole context an uncached prefill. Should Google refuse a request with a 400 that names a signature while it carries another tier's parts, the request goes once more with those turns portable (wire.ExactVariant). Unsigned Gemini thought summaries are left out of the parts (Gemini signs the parts after them, not the summaries; gemini-cli drops them as well); they still show as the reply's reasoning text. Turns stored before that keep theirs, so no existing session's prefix changes. Without a requested effort, the thinking level or budget follows the tier the resolved variant id names. Output from other models replays as plain text and tool calls; Gemini function calls without a signature get Google's documented skip_thought_signature_validator placeholder.

A Gemini variant id (gemini-3.8-flash-low, -medium, -high) is a preset of one model: the thinking comes from the request's thinkingLevel whichever variant carries it. Cloud Code still caches each variant apart, so an effort never moves a Gemini id (catalog.resolve_variant): a session stays on the variant its newest replayed turn ran on (wire.last_variant), a base id with no such turn resolves to its default variant, a variant id stays itself, and the effort travels as the thinking level, so /effort keeps the cached prefix. Claude variants still follow the effort. Gemini 3 Pro, 3.1 Flash Lite, 3.6 Flash and later Flash, and every model from 4 on take levels; 3.8 Flash accepts a budget but treats it only as a rough level (4000 and 10000 think alike).

Requests use the antigravity/hub/<version> user agent. The version comes from the Antigravity update manifest, or from ALBEDO_ANTIGRAVITY_VERSION when it is set. Tool schemas are flattened to the subset Cloud Code Assist accepts: references are resolved, unions keep their first non-null member, const and enums become string enums, and dropped validation keywords move into the description.

amazon bedrock #

The enabled-by-default bedrock extension serves Claude models through Bedrock's Anthropic-shaped Messages route ({baseUrl}/anthropic/v1/messages), identical on the bedrock-runtime and bedrock-mantle endpoints — baseUrl picks which host. There is no sign-in flow. /login offers add or update an Amazon Bedrock provider, which asks for an optional base url and optional api key and then lists the models.dev amazon-bedrock catalog; a profile can also be written with extension: "bedrock" and a Claude model id. baseUrl is optional: left unset, it defaults to bedrock-runtime in whatever region AWS_REGION, else AWS_DEFAULT_REGION, else the active AWS_PROFILE's own region key names (extension.effective_base_url); set it explicitly for bedrock-mantle or a non-default partition.

Authentication tries, in order: the profile's own apiKey (sent as x-api-key, no signing); AWS_BEARER_TOKEN_BEDROCK; AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN, signed with AWS SigV4 (harness/extensions/bedrock/sigv4.gleam); and finally AWS_PROFILE's own resolution from ~/.aws/config/~/.aws/credentials (AWS_CONFIG_FILE/AWS_SHARED_CREDENTIALS_FILE override the paths) — static keys from the shared credentials file, else static keys from the config file, else the config's credential_process. A credentials-file-only profile needs no config section. Credential sources are not mixed. Nothing is cached: each outbound model step re-reads the files and, when selected, re-runs the helper, so an external credential refresher takes effect within a tool-running turn. SigV4's service name follows each endpoint's own IAM action namespace (bedrock:* on bedrock-runtime, bedrock-mantle:* on bedrock-mantle); only bedrock-runtime has been exercised against a live account.

Only HTTPS AWS bedrock-runtime/bedrock-mantle hosts are accepted; embedded credentials, ports, non-root paths, query strings, and fragments are rejected before authentication. A credential_process is a trusted local executable: quoted arguments are parsed without a shell, and it inherits the daemon's environment. Its output and runtime remain bounded, and failure messages never include its stdout. The usage-feed command runner retains its separate environment allowlist. This is a limited credential chain, not the AWS SDK: native SSO, assume-role chains, and instance/container metadata are not resolved.

Replay keeps assistant text and tool calls only; signed extended-thinking blocks are not carried across turns, so multi-turn thinking context starts fresh each turn. The SSE reducer is claude's own (harness/extensions/claude/stream.gleam): Bedrock's Messages route emits the identical event shape.

google vertex #

The enabled-by-default vertex extension serves Gemini models through Vertex AI's own generateContent/streamGenerateContent route — the same request and response body Google documents for the public Gemini API, not Cloud Code Assist's envelope. There is no sign-in flow: /login offers add or update a Google Vertex AI provider, which asks for the project and location and lists the models.dev google-vertex catalog. The extension reads Application Default Credentials from GOOGLE_APPLICATION_CREDENTIALS (default ~/.config/gcloud/application_default_credentials.json) fresh on every call, and the profile's project and location name the project and region, falling back to GOOGLE_VERTEX_PROJECT/GOOGLE_VERTEX_LOCATION when blank. A profile needs extension: "vertex" and a Gemini model id.

The credentials file is either a service-account key (private_key/client_email; the daemon signs its own RS256 JWT and exchanges it at token_uri) or a refresh-token credential (client_id/client_secret/refresh_token) — gcloud auth application-default login's own shape or Workforce Identity Federation's external_account_authorized_user. The latter's STS token endpoint (its token_url field) takes client credentials as HTTP Basic, not body fields; the plain authorized_user shape takes them in the body. There is no token cache: each call re-reads the credentials file and exchanges a fresh access token, so an external refresher that rewrites the file in place just works.

Vertex passes tool schemas as parametersJsonSchema and structured response schemas as responseJsonSchema, without Cloud Code Assist's schema flattening. Supported explicit reasoning efforts map to Gemini 2.5 token budgets or Gemini 3 thinking levels; unknown family/effort combinations fail locally instead of being ignored. Unspecified effort keeps the provider default. The global location uses the bare aiplatform.googleapis.com host for both transport and upstream identity.

Malformed present stream fields fail decoding, and EOF without a terminal finishReason is an incomplete response, not success. Only a normal STOP completion publishes executable tool calls; limited or filtered responses cannot execute partial calls. Output token totals include thinking tokens, with reasoning also reported separately.

Replay keeps text, thinking text, and tool calls only, each replayed call marked with Google's documented placeholder signature (skip_thought_signature_validator) rather than the native one antigravity preserves for its own Gemini calls.

opencode go #

The enabled-by-default opencode-go extension serves OpenCode Go subscription models across OpenCode Go's four inference routes (https://opencode.ai/inference/go/v1, or https://opencode.ai/zen/go/v1): Chat Completions (/chat/completions), OpenAI Responses (/responses for GPT, Grok, and Muse Spark), Anthropic Messages (/messages for Claude and MiniMax M2.7), and Google Gemini (/models/{id}:streamGenerateContent?alt=sse), keeping durable replay in portable Chat Completions shape so switching models within a session never crosses protocols. /login offers both add opencode go account (the OpenCode Console RFC 8628 device-code browser sign-in against https://opencode.ai/console, overrideable via OPENCODE_CONSOLE_SERVER) and add or update an OpenCode Go provider (for a service-account API key and optional base url), and lists the models OpenCode Go serves (opencode-go-models.json cached for 24h from {baseUrl}/models, falling back to the models.dev opencode-go catalog).

Device-code sign-in requests an org-scoped grant (client_id: "opencode-cli", supports_org_scope: true), opens the verification URL in the browser with the confirmation code, polls /auth/device/token, and saves {type: "oauth", access, refresh, expires, accountId, email?, orgId?, orgName?, server} in creds.json under accounts.opencode-go, refreshing under the credential lock 60 seconds before expiry. Every OpenCode Go credential albedo can see joins one rotation pool: the profile's own apiKey or selected OAuth account first, then sibling opencode-go profiles, creds.json's accounts.opencode-go (OAuth accounts and keys), and OPENCODE_GO_API_KEY/OPENCODE_API_KEY. Outbound requests carry x-opencode-session set to the session id (and x-opencode-org-id when the credential is org-scoped) so OpenCode Go routes the conversation to one upstream cache.

opencode zen #

The enabled-by-default opencode-zen extension serves the same gateway's Zen catalog (https://opencode.ai/zen/v1, its /zen/v1 now, /inference/openai/v1 on the console's own config, both rewritten to one root) over Chat Completions, with the Responses route for the muse-spark-* contributor models that answer 400 to a chat request. /login offers add or update an OpenCode Zen provider: the base url defaults, and the API key may be left blank, because the free models need no credential. It lists the models Zen serves (live {baseUrl}/models, cached for 24h in opencode-zen-models.json, falling back to that file, with models.dev's opencode namespace supplying the limits, modalities, and reasoning tiers), so a -free id the gateway adds or retires reaches the picker without an albedo release. A key, the profile's own or OPENCODE_ZEN_API_KEY/OPENCODE_API_KEY in the environment, is what a paid model spends.

A request wears the free lane when its model is one the lane serves — an id ending in -free, or an alias like big-pickle that the gateway serves free without saying so — or when the profile carries no credential at all, since the free lane is the only one reachable without one. A paid model on a keyed profile goes out with that key and albedo's own shape.

Zen answers a -free model only for a request shaped like the one OpenCode's own client sends, and refuses anything else with 403 FreeTierError. Three things are checked, all live-probed against the gateway: the client's identity headers (user-agent: opencode/<channel>/<version>/<artifact>, x-opencode-client: cli, x-opencode-session/x-opencode-session-id/x-session-affinity/x-session-id carrying the same id, x-opencode-project), a session id in the shape OpenCode mints (ses_, twelve lowercase hex, fourteen base62, its hex an inverted millisecond clock whose low twelve bits are a per-millisecond counter the gateway reads back and refuses past sixty-four, so every albedo session id ends in ffe), and one of two body shapes. An agent request — any system prompt but OpenCode's own utility prompt — must carry a tool named bash, glob, grep, or read in its list; albedo's tools are named differently, so shape_for_free_lane appends the reserved quartet, described as never to be called, and the model's own tools sit in front of them untouched. A request whose system prompt is OpenCode's own utility prompt needs no tools at all, and the two shapes are exclusive, so the quartet is what albedo sends. Authorization is the literal public, which is the whole credential the free tier takes.

A paid model wears the same identity — it is harmless and the gateway likes it — but keeps the profile's key and albedo's shape, tools included. The Responses route reads a tool marked strict by strict's own rules, where every property is required, which an optional parameter is not, so that route marks tools not strict before sending; Chat Completions reads the flag and leaves the schema alone.

Account ordering #

harness/accounts.gleam owns pure pool ordering and the 32-bit FNV-1a session spread. The native account owner captures wall time and process-local affinity before calling it. Selected usable accounts come first, followed by the sticky or hashed order; limited accounts come last in reset order. Equal reset times retain their input order. albedo_accounts.erl keeps credential publication, session affinity, transient limits, and local-time display.