# Extension API reference The public functions in [`albedo/harness/sdk`](../src/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](extensions.md) walks through a complete extension. [Extension composition](../robot-docs/extensions.md) describes installation and selection, and [plugins](../robot-docs/plugins.md) describes contribution lifetimes and host callbacks. ## Build the function reference From the repository root: ```sh 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](../robot-docs/extensions.md#sdk-imports-and-native-bindings) 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](../robot-docs/workspace-packages.md), 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](../robot-docs/extensions.md#workspace-packages) links each one by purpose. ## Find an operation The [SDK module overview](../robot-docs/extensions.md#sdk-imports-and-native-bindings) and [session data and effects](../robot-docs/extensions.md#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`](../src/albedo/harness/sdk/extension.gleam) | Declarations describe capabilities. Preparation and invocation callbacks perform effects. | | Add a command | [`command.Command`](../src/albedo/harness/sdk/command.gleam) | `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`](../src/albedo/harness/sdk/host.gleam), [`rpc.args`](../src/albedo/harness/sdk/rpc.gleam) | Decode foreign arguments once. Return JSON or a code/message pair. | | Serve a client resource | [`service.json`](../src/albedo/harness/sdk/service.gleam), [`http_api`](../src/albedo/harness/sdk/http_api.gleam), [`client_api`](../src/albedo/harness/sdk/client_api.gleam) | The service owns HTTP behavior; client declarations describe how to invoke it. | | Read or change settings | [`settings.Section`, `load_section`, `update`](../src/albedo/harness/sdk/settings.gleam) | Use the same typed settings for schema and decoding. Update callbacks run under the settings lock. | | Resolve provider credentials | [`credentials`](../src/albedo/harness/sdk/credentials.gleam), [`key_accounts`](../src/albedo/harness/sdk/key_accounts.gleam) | Keep the selected snapshot through the request, attribution, and cooldown update. | | Observe session history | [`history.snapshot`, `fold_sources`](../src/albedo/harness/sdk/history.gleam) | Capture an append boundary once and retain it through related reads. | | Give a session an input | [`input.Inbox`: `post`, `post_in`, `withdraw`](../src/albedo/harness/sdk/input.gleam), 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`](../src/albedo/harness/sdk/session_control.gleam), 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`](../src/albedo/harness/sdk/host.gleam) | 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`](../src/albedo/harness/sdk/host.gleam), [`extension.Daemon.session_state`](../src/albedo/harness/sdk/extension.gleam) | 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`](../src/albedo/harness/sdk/worker.gleam) | Monitor preparation and runtime owners; attach adoption and close callbacks. | | Call external services | [`http`](../src/albedo/harness/sdk/http.gleam), [`albedo_ports/subprocess`](../packages/albedo_ports/src/albedo_ports/subprocess.gleam), [`concurrent`](../src/albedo/harness/sdk/concurrent.gleam) | Choose explicit deadlines and preserve caller lifetime for concurrent work. | | Read bounded file content | [`file.read_prefix`, `read_range`](../src/albedo/harness/sdk/file.gleam) | 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`](../src/albedo/harness/sdk/file.gleam) | 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`](../src/albedo/harness/sdk/oauth.gleam) | Wait in the OAuth completion worker. Input wakes it. The sign-in service handles cancellation. | | Wait for a keyed change | [`subscriptions`](../src/albedo/harness/sdk/subscriptions.gleam) | 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`](../src/albedo/harness/sdk/http_api.gleam). 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`](../src/albedo/harness/sdk/credentials.gleam) is an immutable credential snapshot. [`extension.Owned`](../src/albedo/harness/sdk/extension.gleam) attaches resource callbacks; copies borrow the same resources. Only the composition owner adopts or closes them. Follow the [shared lifecycle rules](../robot-docs/contributing.md#preserve-extension-lifecycle-boundaries). 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](extensions.md) aligned with those contracts. Verify examples against the current compiler and run any daemon scenario through the [shared harness](../robot-docs/testing.md). Documentation changes follow the [repository checks](../AGENTS.md#use-the-project-tools) and [documentation rules](../robot-docs/AGENTS.md).