albedo docs

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:

TaskStarting APIContract
Declare contributionsextension.Extension, PluginDeclarations describe capabilities. Preparation and invocation callbacks perform effects.
Add a commandcommand.CommandInvocation.state reaches session operations through the actor's bridge, and Invocation.storage is the extension's handle.
Add a kernel host routehost.Route, Context, rpc.argsDecode foreign arguments once. Return JSON or a code/message pair.
Serve a client resourceservice.json, http_api, client_apiThe service owns HTTP behavior; client declarations describe how to invoke it.
Read or change settingssettings.Section, load_section, updateUse the same typed settings for schema and decoding. Update callbacks run under the settings lock.
Resolve provider credentialscredentials, key_accountsKeep the selected snapshot through the request, attribution, and cooldown update.
Observe session historyhistory.snapshot, fold_sourcesCapture an append boundary once and retain it through related reads.
Give a session an inputinput.Inbox: post, post_in, withdraw, from the context's inboxPost 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 sessionssession_control: spawn, start, stop, close, with the context's controlThe 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 agentshost.Context.send_mailResolves the address and forwards to another daemon when needed. A receipt does not mean the recipient answered.
Reach session statehost.Context.session_state, extension.Daemon.session_stateThe host supplies the command.Context. A route uses its own session's. A service looks up the session its request names.
Work with worktreesworktree.Worktrees, from the context's worktreesDeclare Worktrees and Sessions, and pass your own storage handle. The host owns the table, placement, providers, and removal.
Reach a workspace's hosthosts.Hosts, from Daemon.hosts or Preparation.hostsDeclare Hosts. A preparation asks exists with a wait of 0, so opening a session never waits on a host.
Read a workspace grouplinks.group, members, with the context's originsThe host's worktree records decide which worktrees join a group; pass the Origins your context carries.
Read a session's project filesPreparation.project_files, instructions, and preferences in extensionThe host owns discovery, the remote mirror, and selection. Read preferences only when there is something to choose among.
Own a session workerworker.start, observerMonitor preparation and runtime owners; attach adoption and close callbacks.
Call external serviceshttp with buffered.Timeouts, Body, albedo_ports/subprocess, albedo_process/parallelChoose explicit deadlines and preserve caller lifetime for concurrent work.
Read bounded file contentalbedo_file.read_prefix, read_rangeBounds count bytes. EOF succeeds with empty bytes; ReadError distinguishes invalid ranges from unavailable files. Callers own path and identity validation.
Update a shared cache filealbedo_file.with_lock, write_privateLock 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 flowoauth.Device, wait_for_inputWait in the OAuth completion worker. Input wakes it. The sign-in service handles cancellation.
Wait for a keyed changealbedo_process/subscriptionsSubscribe 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