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

Usage feed #

The usage feed drives the usage-core executable to obtain provider account and limit reports. usage_feed.gleam owns the round loop, report types, executable resolution, and request answers. subprocess.gleam owns the command policy, the port I/O and the stdout cap it is given, over the shared port binding in albedo_ports.gleam, which owns the timeout kill. The daemon quota component consumes the report in quota.gleam.

Rounds and errors #

fetch(provider, credential, now_ms) sends a JSON envelope to a fresh usage advance - process on each round. The envelope contains the credential and prior responses on stdin, not in arguments. The driver parses the last nonempty output line as a report, an error, or requests to answer. It stops after six rounds. See fetch, loop, and step in usage_feed.gleam.

A core error step becomes Ok(Report(error: Some(...))). Driver failures, including missing executable, invalid output, timeout, or exceeding the round limit, return Error. A transport error becomes an HTTP answer with status 0 and a reason body.

Request execution #

usage_feed.http_request sends HTTP requests through sdk/http with a 30-second timeout. It moves the content-type header into the request body and defaults it to application/json. A method that sdk/http does not send answers status 0 with the body invalid_method. Command requests receive an environment limited to PATH, HOME, locale, timezone, and proxy variables. Their timeout defaults to 15 seconds and is capped at 60 seconds. Stdout is capped at 64 KiB. An unavailable command or timeout returns status 126. See execute and command_environment in subprocess.gleam. The timeout cleanup in albedo_ports.kill uses a kill executable on PATH. Local commands and change listings use the same command_environment and kill.

The executable resolves through ALBEDO_USAGE_CORE when set, otherwise priv/bin/usage and then PATH. The priv directory comes from priv.directory, which the daemon pins at boot. An invalid override does not fall back to the bundled binary. Envelope and response data can contain credentials and must not be logged. Resolution is resolve in usage_feed.gleam.

Report and packaging #

Report contains optional account ID, email, plan, and error, plus a list of Limit values. Limits include an ID, label, status, and optional usage, window, reset, and scope fields. Their decoding is in usage_feed.gleam. The external core is pinned in flake.nix and built by usage-core.nix. Provider-specific semantics belong to that pinned dependency, not this page.

Keep the package's -Dcpu=baseline build flag. Distributed binaries must not require the build host's CPU extensions.