Extension API reference
The public functions in the workspace package
albedo_sdk are the shared Gleam API for
extensions. Its modules are albedo_sdk/.... 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.
On this page: Build the function reference, Find an operation, Read function and callback contracts, and Maintain the reference.
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:
cd packages/albedo_sdk && nix develop ../.. -c gleam docs build
Open packages/albedo_sdk/build/dev/docs/albedo_sdk/index.html in a browser.
Search for a module, such as albedo_sdk/extension, 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
packages/albedo_sdk/build/dev/docs/albedo_sdk/albedo_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.
Run (cd apps/albedo && gleam docs build) to render Albedo's own public
modules, not the SDK's. Their presence in that 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 neither reference renders 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. |
| Work with worktrees | worktree.Worktrees, from the context's worktrees | Declare Worktrees and Sessions, and pass your own storage handle. The host owns the table, placement, providers, and removal. |
| Reach a workspace's host | hosts.Hosts, from Daemon.hosts or Preparation.hosts | Declare Hosts. A preparation asks exists with a wait of 0, so opening a session never waits on a host. |
| Read a workspace group | links.group, members, with the context's origins | The host's worktree records decide which worktrees join a group; pass the Origins your context carries. |
| Read a session's project files | Preparation.project_files, instructions, and preferences in extension | The host owns discovery, the remote mirror, and selection. Read preferences only when there is something to choose among. |
| Own a session worker | worker.start, observer | Monitor preparation and runtime owners; attach adoption and close callbacks. |
| Call external services | http with buffered.Timeouts, Body, albedo_ports/, albedo_process/ | Choose explicit deadlines and preserve caller lifetime for concurrent work. |
| Read bounded file content | albedo_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 | albedo_file.with_lock, write_private | Lock the complete read/merge/write operation. Wait Within a limit 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 | albedo_process/ | 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.
The SDK functions that read or change core's tables, such as sdk/history,
sdk/sessions, sdk/family, sdk/mail, sdk/images, sdk/request_history,
and transfer.occurred_in, take your storage handle and check its capabilities.
Core runs their statements: the records in
sdk/core_tables are
the contract it implements, and storage.core is for the host and the SDK only.
Call the SDK functions, not those records. See
core table operations.
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.
Previous write an extension Next client api