small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo docs extension-api.md
12 kB · 119 lines
Markdown
at main

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.