Extension API reference #
The public functions in albedo/harness/sdk are
the shared Gleam API for extensions. Each function's /// comment describes its
behavior beside its signature. Gleam generates the function reference, type
definitions, and module search from those sources. The source comments are
canonical; this page does not maintain a second copy of the signatures.
Write an extension walks through a complete extension. Extension composition describes installation and selection, and plugins describes contribution lifetimes and host callbacks.
Build the function reference #
From the repository root:
nix develop -c gleam docs build
Open build/dev/docs/albedo/index.html in a browser. Search for
albedo/harness/sdk/ or a function name. Each module page lists its public
functions with argument labels, argument and result types, and documentation.
Public types include the record fields and callbacks needed to use those
functions. For example, the settings reference is at
build/dev/docs/albedo/albedo/harness/sdk/settings.html, and #update selects
its atomic settings update function.
Rebuild after changing source documentation or public declarations. Generated
HTML stays under the ignored build/ directory. It is not a separately
maintained or published API snapshot.
The compiler also renders other public Albedo modules. Their presence in the HTML does not make them supported extension imports. The SDK import contract defines which daemon, domain, and cross-extension modules may be used. The SDK ships with Albedo and follows the checkout's version.
Extensions also import the general helpers in
workspace packages, such as
albedo_clock, albedo_bytes/digest, and albedo_process/memo. They are not
part of the SDK, and the root reference does not render them. Build a package's
reference in its own directory, for example
cd packages/albedo_clock && nix develop ../.. -c gleam docs build, and open
its build/dev/docs/albedo_clock/index.html. The
workspace package list links
each one by purpose.
Find an operation #
The SDK module overview and session data and effects link the available modules by purpose. These are useful starting points for common tasks:
| Task | Starting API | Contract |
|---|---|---|
| Declare contributions | extension.Extension, Plugin |
Declarations describe capabilities. Preparation and invocation callbacks perform effects. |
| Add a command | command.Command |
Invocation.state reaches session operations through the actor's bridge, and Invocation.storage is the extension's handle. |
| Add a kernel host route | host.Route, Context, rpc.args |
Decode foreign arguments once. Return JSON or a code/message pair. |
| Serve a client resource | service.json, http_api, client_api |
The service owns HTTP behavior; client declarations describe how to invoke it. |
| Read or change settings | settings.Section, load_section, update |
Use the same typed settings for schema and decoding. Update callbacks run under the settings lock. |
| Resolve provider credentials | credentials, key_accounts |
Keep the selected snapshot through the request, attribution, and cooldown update. |
| Observe session history | history.snapshot, fold_sources |
Capture an append boundary once and retain it through related reads. |
| Give a session an input | input.Inbox: post, post_in, withdraw, from the context's inbox |
Post on the caller's transaction when effects must commit together. The session hears of it after the commit; never tell it yourself. |
| Start or stop other sessions | session_control: spawn, start, stop, close, with the context's control |
The daemon's coordinator owns admission and limits. A call runs in the caller's process and answers an error when the coordinator is unavailable. |
| Send mail between agents | host.Context.send_mail |
Resolves the address and forwards to another daemon when needed. A receipt does not mean the recipient answered. |
| Reach session state | host.Context.session_state, extension.Daemon.session_state |
The host supplies the command.Context. A route uses its own session's. A service looks up the session its request names. |
| Own a session worker | worker.start, observer |
Monitor preparation and runtime owners; attach adoption and close callbacks. |
| Call external services | http, albedo_ports/subprocess, concurrent |
Choose explicit deadlines and preserve caller lifetime for concurrent work. |
| Read bounded file content | file.read_prefix, read_range |
Bounds count bytes. EOF succeeds with empty bytes; ReadError distinguishes invalid ranges from unavailable files. Callers own path and identity validation. |
| Update a shared cache file | file.with_lock, with_lock_timeout, home_write |
Lock the complete read/merge/write operation. Use with_lock_timeout for finite admission. Locks are daemon-local and non-reentrant. |
| Poll a custom sign-in flow | oauth.Device, wait_for_input |
Wait in the OAuth completion worker. Input wakes it. The sign-in service handles cancellation. |
| Wait for a keyed change | subscriptions |
Subscribe before reading state, then wait or close in the same process. Owner death cleans up. Publish after commit and re-read state after waking. |
Read function and callback contracts #
A Result(a, String) carries the module's diagnostic, not a universal HTTP
status. Host routes use Result(Json, #(String, String)) for code and message.
HTTP handlers use
http_api.Failure. Identified OAuth
operations return #(status, code, message) errors. Keep those boundaries
explicit when adapting an operation.
Time parameters are documented where they are used. HTTP and worker timeouts are durations in milliseconds. Credential expiry and cooldown marks are Unix millisecond timestamps. History sequence numbers are positions, not times.
An opaque handle does not imply a live lease or exclusive ownership.
credentials.Stored is an
immutable credential snapshot.
extension.Owned attaches resource
callbacks; copies borrow the same resources. Only the composition owner adopts
or closes them. Follow the
shared lifecycle rules.
Some SDK functions support the host itself. For example, extension.install,
declared, and contribution_routes collect and validate declarations.
Extension authors normally construct Extension and Plugin values instead of
installing or composing them manually. The reference includes these public
functions and identifies their role.
Maintain the reference #
When adding a public SDK function, document its purpose, argument meanings that
are not evident from their types, result and error behavior, and effects.
Include units, ordering, limits, snapshot validity, or cleanup duties where they
matter. Put this information in /// comments on the declaration, before any
@external attribute. Document callback restrictions with the type or function
that accepts the callback.
Keep examples in Write an extension aligned with those contracts. Verify examples against the current compiler and run any daemon scenario through the shared harness. Documentation changes follow the repository checks and documentation rules.