# Extensions An extension is a named bundle of plugins. The registry in [extensions.gleam](../src/albedo/harness/extensions.gleam) declares installed extensions and defaults. The [extension types](../src/albedo/harness/sdk/extension.gleam) define their contributions. See [plugins](plugins.md) for the host contracts, [Write an extension](../docs/extensions.md) for a working Gleam example, and the [extension API reference](../docs/extension-api.md) for function-level documentation and generated signatures. ## The harness base Python is part of the harness, not an extension. Every session composes the [harness base](../src/albedo/harness/kernel/base.gleam) ahead of its selected extensions: the `python` tool, the kernel's `cells`, `user_shell_output`, and `session` host routes, the `/kernel` command and its client bindings, and the remote-place context. Every session also runs a kernel. No selection adds or removes them, so every extension may rely on the kernel and on the Python bindings that it and other extensions contribute. Do not declare a requirement on `python`. The runtime builds the base once at startup and publishes it with the installed extensions (`Installed.base` in [runtime/state.gleam](../src/albedo/harness/runtime/state.gleam)), and `composition.compose` takes that shared value. Do not call `base.contribution()` per session: a base built on a composing process's heap is copied into every session's composition, about 10 KB each. The base keeps the owner name `python`, which the python extension had in earlier releases. Client command ids such as `python:/kernel:kernelAction` and the kernel's transfer adapter keep that name. Extension install refuses an extension with that name. A saved choice that names `python`, in the global `enabled` section, a session's `session_extensions` rows, or a configuration or defaults patch from an older client, is accepted and changes nothing. See `selection.select` and `selection.change_defaults` in [selection.gleam](../src/albedo/harness/extension/selection.gleam). ## Installed and enabled Installation makes an extension known to the daemon. Session selection combines global defaults with stored session overrides. `selection.select` preserves registry order and handles exclusive compaction strategies. `selection.validate_selection` checks requirements before the selection is used. A quarantined extension appears in summaries with its reason and no capabilities. See [selection.gleam](../src/albedo/harness/extension/selection.gleam). ## Session composition [`composition.compose`](../src/albedo/harness/extension/composition.gleam) loads static contributions and prepares managed contributions for the harness base and then each selected extension. `composition.extensions` lists only the selected extensions. A failed load, failed preparation, module clash, or duplicate tool, command, or route leaves that extension inactive and adds a warning. Dependents whose requirements are inactive are removed as well. A composition is immutable. A refresh prepares a replacement, and the host closes the composition that loses. Managed resources close in reverse preparation order. Adoption failure closes the candidate. Owned callbacks return an optional opaque `Owned` value with explicitly attached adoption and close callbacks. `None` contributes nothing. The ownership contract is defined by `PreparationOwner`, `Preparation`, and `OwnedManagedPlugin` in [extension.gleam](../src/albedo/harness/sdk/extension.gleam). During reload, application workers borrow the adopted candidate and previous session. The runtime settles their results and closes the losing resources. See [reload ownership](runtime.md#extension-reload-ownership) for rejection, worker death, and late-result cleanup. ## Extension settings `SettingsPlugin` registers an extension's settings declaration. [`settings/declared.gleam`](../src/albedo/harness/settings/declared.gleam) collects declarations and validates declared values. [`core_settings.all`](../src/albedo/daemon/core_settings.gleam) lists the daemon's own sections before each extension's `extension.settings_sections`. The daemon exposes them through its settings resources. See [persisted settings](settings.md) for conditional updates and recovery, and [plugins](plugins.md) for contribution types. ## SDK imports and native bindings An extension belongs to one directory under `src/albedo/harness/extensions/`. Use `albedo/harness/sdk/*` for shared extension helpers and contracts, and import modules within your own extension for feature behavior. Standard library and other declared dependency imports, including [workspace packages](workspace-packages.md), remain available. Extensions import nothing from `albedo/daemon/`. Storage is the scoped [`sdk/storage`](../src/albedo/harness/sdk/storage.gleam) handle described in [extension storage](#extension-storage), and the HTTP contract is [`sdk/http_api`](../src/albedo/harness/sdk/http_api.gleam). The allowed harness domain imports are `location`, `ssh`, `worktree`, `compaction`, `cache_ttl`, `capabilities`, `project_files`, `instruction_files`, `context_limits`, `links`, and `extension/selection`, each under `albedo/harness/`. Any extension may also import the core kernel modules [`kernel/jobs`](../src/albedo/harness/kernel/jobs.gleam), which owns live and saved job reads and fallback rules, and [`kernel/resources`](../src/albedo/harness/kernel/resources.gleam), which exposes the supported kernel resource types. Any extension may import the core skills modules under [`albedo/harness/skills/`](../src/albedo/harness/skills). Every other kernel module is private to core, including [`albedo/harness/kernel`](../src/albedo/harness/kernel.gleam), [`kernel/journal`](../src/albedo/harness/kernel/journal.gleam), [`kernel/tool`](../src/albedo/harness/kernel/tool.gleam), and the [harness base](#the-harness-base) modules, along with link, launch, recovery, termination, and cell storage. Reach the kernel through Python bindings and host routes, not by driving cells. Shared helpers outside the SDK are [`albedo/clock`](../src/albedo/clock.gleam), [`albedo/text_scalars`](../src/albedo/text_scalars.gleam), and [`albedo/actor_call`](../src/albedo/actor_call.gleam). Transfer adapters import [`albedo/transfer`](../src/albedo/transfer.gleam) for the `Adapter`, `Table`, `Shift`, and `Activation` types. Use supplied host or session callbacks for daemon effects that the SDK does not expose. Follow the [shared contribution rules](contributing.md). The existing SDK modules are: - [`sdk/extension`](../src/albedo/harness/sdk/extension.gleam): Extension declarations, contributions, preparation and startup contexts, and preparation ownership. - [`sdk/storage`](../src/albedo/harness/sdk/storage.gleam): An extension's storage handle and the store operations it runs its own SQL through. See [extension storage](#extension-storage). - [`sdk/service`](../src/albedo/harness/sdk/service.gleam): Buffered JSON extension HTTP services. - [`sdk/http_api`](../src/albedo/harness/sdk/http_api.gleam): HTTP failures, problem and JSON replies, strict request decoding, negotiation, validators, and paging tokens shared with the daemon. - [`sdk/worker`](../src/albedo/harness/sdk/worker.gleam): Owned worker startup and adoption. - [`sdk/host`](../src/albedo/harness/sdk/host.gleam): Context and routes for kernel host calls. - [`sdk/rpc`](../src/albedo/harness/sdk/rpc.gleam): Host-call dispatch and argument decoding. - [`sdk/command`](../src/albedo/harness/sdk/command.gleam): Session command declarations and state operations. - [`sdk/follow`](../src/albedo/harness/sdk/follow.gleam): Core history and worktree changes that `FollowPlugin` callbacks receive. - [`sdk/hook`](../src/albedo/harness/sdk/hook.gleam): Turn and tool hook events and verdicts. - [`sdk/tool`](../src/albedo/harness/sdk/tool.gleam): Retrieval tool schemas, paging, and rendering. - [`sdk/client_api`](../src/albedo/harness/sdk/client_api.gleam): Declarative client HTTP operations. - [`sdk/imagegen`](../src/albedo/harness/sdk/imagegen.gleam): Provider-neutral image generation contracts. - [`sdk/web_search`](../src/albedo/harness/sdk/web_search.gleam): Web search provider contracts and selection. - [`sdk/search`](../src/albedo/harness/sdk/search.gleam): Transcript search with bounded database reads. - [`sdk/sessions`](../src/albedo/harness/sdk/sessions.gleam): What the `sessions` table says about sessions: their names, workspaces, and whether a transfer is importing them or moved them. See [extension storage](#extension-storage). - [`sdk/page`](../src/albedo/harness/sdk/page.gleam): Sidebar rows and command argument parsing. - [`sdk/http`](../src/albedo/harness/sdk/http.gleam): Buffered HTTP requests and timeout settings. `request` returns status, headers, and bytes, including non-2xx responses. `failure` formats status errors; `locations` follows redirect locations concurrently. The httpc binding [`albedo_http`](../src/albedo/harness/sdk/albedo_http.erl) owns TLS options and the address-family fallback. Its `get/4` and `request/6` remain for core Erlang callers. - [`sdk/settings`](../src/albedo/harness/sdk/settings.gleam): Extension settings declarations and decoding. - [`sdk/credentials`](../src/albedo/harness/sdk/credentials.gleam): Credential recovery, persistence, and notifications. `text` and `lenient_text` treat missing or non-string credential fields as empty strings. - [`sdk/key_accounts`](../src/albedo/harness/sdk/key_accounts.gleam): Typed snapshots of profile-bound key accounts. `fast_mode` selects the current connection before invoking the provider's support callback. A selection failure returns `FastUnknown` with the provider's error prefix. The callback owns model and endpoint eligibility, mode, source, and unavailable reasons. - [`sdk/key_environment`](../src/albedo/harness/sdk/key_environment.gleam): The runtime's composed `KeyEnvironmentPlugin` lookups. Pass the value from the context you receive to key account readers. See [typed key accounts](auth.md#typed-key-accounts). - [`sdk/accounts`](../src/albedo/harness/sdk/accounts.gleam): Pure account pool ordering. - [`sdk/rotation`](../src/albedo/harness/sdk/rotation.gleam): Rate-limit account rotation. - [`sdk/oauth`](../src/albedo/harness/sdk/oauth.gleam): OAuth sign-in and token helpers. Build `DeviceFlow` inside `oauth.device`'s start callback so runtime environment overrides are read after sealed declarations load. - [`sdk/oauth_flows`](../src/albedo/harness/sdk/oauth_flows.gleam): The sign-in service that runs `oauth.Login` declarations. The daemon starts it and passes the opaque `Service` handle to its HTTP handlers. Extensions do not call it. See [sign-in](auth.md#sign-in). - [`sdk/oauth_listener`](../src/albedo/harness/sdk/oauth_listener.gleam): The loopback listener that serves a sign-in flow's browser callback. Only `oauth_flows` uses it. See [sign-in](auth.md#sign-in). - [`sdk/google_oauth`](../src/albedo/harness/sdk/google_oauth.gleam): Shared Google token renewal. - [`sdk/model_lists`](../src/albedo/harness/sdk/model_lists.gleam): Provider model-list helpers. - [`sdk/concurrent`](../src/albedo/harness/sdk/concurrent.gleam): Linked concurrent calls with caller lifetime. - [`sdk/protect`](../src/albedo/harness/sdk/protect.gleam): Callback crash recovery as a result value, a typed `rescue` that can raise the crash again, and `finally` for cleanup that must run however a callback ends. - [`sdk/usage_feed`](../src/albedo/harness/sdk/usage_feed.gleam): Usage driver execution and bounded I/O. The SDK also provides these helpers. - [`sdk/digest`](../src/albedo/harness/sdk/digest.gleam): Hash, hex, base64, HMAC, and constant-time comparison helpers. - [`sdk/ids`](../src/albedo/harness/sdk/ids.gleam): Random and unique identifier helpers, including a version-4-shaped UUID derived from a seed. - [`sdk/env`](../src/albedo/harness/sdk/env.gleam): Environment variable lookup, returning an empty string when unset. Read it during resolution or startup callbacks, never while constructing cached declarations. - [`sdk/file`](../src/albedo/harness/sdk/file.gleam): File reads and private atomic cache writes. `home_read_optional` distinguishes absence from read failure so a save can preserve an unreadable existing file. Bounded prefix and range reads close descriptors on every outcome. `with_lock` serializes a complete cache update within this daemon; it is separate from credential transactions and does not coordinate other OS processes. `with_path_lock` takes the same lock for a whole path. - [`sdk/cached_fetch`](../src/albedo/harness/sdk/cached_fetch.gleam): The bounded fetch of a url-backed cache file. It allows https, and plain http only on loopback. `refresh` starts at most one background fetch per refresh key when the file is stale. `reload` fetches now and reports the failure. A fetch commits through `commit`, a rename that a failed fetch never reaches. `isolated` runs a large decode in a fresh process. - [`sdk/file_revision`](../src/albedo/harness/sdk/file_revision.gleam): A file's size and modification time, for caches derived once per file revision. - [`sdk/pinned`](../src/albedo/harness/sdk/pinned.gleam): Values shared with every process without copying, under a namespace and key. Each `put` and `erase` costs a global garbage collection pass, so pin only values that change rarely. - [`sdk/credential_store`](../src/albedo/harness/sdk/credential_store.gleam): `creds.json` reads, private atomic writes, the saved account sections, and cache file age. Hold the settings lock from [`sdk/settings_store`](../src/albedo/harness/sdk/settings_store.gleam) across a read and the write that depends on it. - [`sdk/file_status`](../src/albedo/harness/sdk/file_status.gleam): The kind, size, and permission bits of a path without following a final symbolic link, for checks that a secret file is private before reading it. - [`sdk/settings_documents`](../src/albedo/harness/sdk/settings_documents.gleam): Whole settings documents such as `creds.json`, read and committed as a group through the settings store. Hold `with_lock` across a read and the commit that depends on it. `mcp_secrets` reads the `mcp` section of `creds.json`. - [`sdk/term_codec`](../src/albedo/harness/sdk/term_codec.gleam): The Erlang external term format for caches and fingerprints that earlier daemons wrote. `decode_safe` refuses bytes that would create unknown atoms or functions. `tuple` and `binary` check decoded shapes exactly. Use JSON for new persisted data. - [`sdk/log`](../src/albedo/harness/sdk/log.gleam): Warning and debug messages for the daemon's log. Never include secrets or tokens. - [`sdk/process_flag`](../src/albedo/harness/sdk/process_flag.gleam): Flags in the calling process's dictionary that last as long as that process. Use a key type your module owns. - [`sdk/zlib`](../src/albedo/harness/sdk/zlib.gleam): zlib compression and inflation bounded by a caller's byte limit. A damaged stream or checksum mismatch is an error. - [`sdk/priv`](../src/albedo/harness/sdk/priv.gleam): Paths and reads of files shipped in albedo's priv directory, as `pin` pinned it at boot. A failed read names the path and the file error. - [`sdk/subprocess`](../src/albedo/harness/sdk/subprocess.gleam): Credential helpers with bounded stdout and timeouts, the command environment allowlist, and PATH lookup. - [`sdk/helper`](../src/albedo/harness/sdk/helper.gleam): Python helper subprocess execution with explicit outcomes, and `open_python` for a long-running helper port an extension reads itself. - [`sdk/port_program`](../src/albedo/harness/sdk/port_program.gleam): Typed `open_port` settings and events, port reads that select only the port's own messages, writes and closes that tolerate a closed port, and the deadline kill. - [`sdk/rsa`](../src/albedo/harness/sdk/rsa.gleam): RS256 signing for provider authentication. - [`sdk/renderer`](../src/albedo/harness/sdk/renderer.gleam): Runs of the optional `albedo-render` binary, its report lines, and a scratch directory deleted after each render. - [`sdk/memo`](../src/albedo/harness/sdk/memo.gleam): Typed cache handles with explicit expiry clocks and decoded reads. The owner sweeps expired entries every second. Each namespace keeps at most 1024 entries and evicts its oldest write when full. - [`sdk/once`](../src/albedo/harness/sdk/once.gleam): Single-flight work shared by concurrent callers. The returned process runs the job; killing it cancels that job. - [`sdk/subscriptions`](../src/albedo/harness/sdk/subscriptions.gleam): One-shot keyed wakeups with owner-death and explicit close cleanup. Subscribe before reading state and publish after commit. Handles belong to their creating process; callers must bound concurrent subscriptions. Six lint rules enforce the layer boundaries in the commit and review profiles: - `albedo_extension_daemon_import` flags any `albedo/daemon/` import from an extension. Use SDK helpers or supplied callbacks instead. - `albedo_extension_harness_import` flags harness imports outside the SDK, extension directories, and the domain allow-list above. Use an SDK contract. - `albedo_extension_external` flags `@external(erlang, M, _)` unless `M` has an `.erl` file within the same extension directory, including its subdirectories. OTP modules also violate this rule. Call an SDK Gleam helper instead of its native implementation, or keep feature-specific natives with their owner. - `albedo_extension_cross_import` rejects another extension's private modules. Deliberate feature dependencies use the public entrypoints below. Provider contributions still resolve from the active composition. - `albedo_core_extension_import` flags an `albedo/harness/extensions/*` import from any Gleam module under `src/albedo/` outside the extension directories, including the SDK. It also flags an `@external(erlang, M, _)` binding in those modules when `M` is an Erlang module owned by an extension. The registry [`extensions.gleam`](../src/albedo/harness/extensions.gleam) is exempt. - `albedo_sdk_daemon_import` flags an `albedo/daemon/` import from an SDK module, and an `@external(erlang, M, _)` binding there when `M` has its `.erl` file under `src/albedo/daemon`. Move what the SDK needs into the SDK, so the daemon imports it, or have the host supply the behavior through a context callback. The first four rules check imports from extensions. The fifth checks the other direction. The sixth keeps the SDK independent of the daemon, so the layers run extensions, then the SDK, then the daemon. Core and SDK modules must not import extension modules. Reach a new core need through a plugin contract in the active composition, or move the shared code into a core module. The extension registry is the only exception. These rules read Gleam source only. Core Erlang modules must not call extension natives, and SDK and extension Erlang natives must not call daemon-owned Erlang modules. No lint rule checks those Erlang calls, so check them in review. Process-wide infrastructure, such as `albedo_registry` and [`process_helpers`](../src/albedo/process_helpers.gleam), lives in `src/albedo/` so every layer can use it. [`albedo_registry`](../src/albedo/albedo_registry.erl) holds keyed ETS registries whose tables outlive their callers. [`sdk/priv`](../src/albedo/harness/sdk/priv.gleam) answers albedo's priv directory, with the link the daemon resolved at boot. The daemon keeps its own handler registries in `albedo_registry` tables through [`keyed`](../src/albedo/daemon/keyed.gleam), such as the coordinator in [`session_control`](../src/albedo/daemon/session_control.gleam) and the state closures in [`command_state`](../src/albedo/daemon/command_state.gleam). Extensions reach them only through capabilities in their context, such as `control` and `session_state`, that they [declare](#extension-capabilities). Do not let the SDK or an extension find a process, handler, or callback that carries daemon or extension behavior through a process-wide registration, such as a registered name, a registry key, a persistent term, or a named table. Pass a capability or opaque handle in a context instead. Caches, single-flight claims, subscriptions, and locks may stay process-wide, because they hand out no behavior. The same rule covers a process an extension starts itself. Create its handle in the `StartupPlugin` callback and return the `extension.Started` contributions that use it, as described in [startup plugins](plugins.md#daemon-contributions). The first four rules do not restrict SDK implementation imports or JavaScript external bindings. The [lint profiles](gleam-lint.md#extension-boundary-review) run the same boundary checks. Two checks enforce the process-wide registration rule above in SDK and extension code. The `albedo_process_registration` lint rule reads Gleam bindings and the gleam_erlang and gleam_otp naming APIs. The Erlang registration check scans `.erl` and `.hrl` files. Both fail on a use that is not in the [reviewed allow-list](../tools/lint/src/albedo_lint/registrations.gleam). Add an entry only for a cache, single-flight claim, subscription, lock, or handle name, with its reason. A handle name is a fresh name from `process.new_name` that an opaque handle holds so its supervised process keeps one address across restarts. The handle is the interface callers use, not enforced isolation: the name is registered, and any Erlang code could find it among the registered names. Do not find a process by enumerating registered names, even by a known prefix. Test probes under `test/` may do so to inspect a running daemon. Fix any other finding by passing a capability or handle in a context. [Gleam lint](gleam-lint.md#process-wide-registration-checks) describes what each check matches. ## Extension storage Each extension declares the tables it creates in the `tables` field of its [`extension.Extension`](../src/albedo/harness/sdk/extension.gleam). Write the list as a `pub const tables: List(String)` of string literals in a Gleam module under the extension's directory, and pass that constant to the constructor. The lint reads the constant, not the constructor call. Extensions in the same directory, such as `lcm` and `lcm-memory`, share the directory's declaration. List only tables a `CREATE TABLE` in that directory makes: a core table in `tables` is a lint finding, not a way to write it. See [Gleam lint](gleam-lint.md#extension-storage-rules) for the two tables allowed explicitly. Core tables belong to the daemon, not to an extension: `sessions`, `session_family`, `mail`, `transcript`, `transfer_occurrences`, `session_extensions`, and the other tables the daemon creates. Extension SQL names only the extension's own tables. Read or change a core table through a typed core or SDK operation that takes the extension's handle, never through extension SQL. Those operations apply the capability and session rules ([extension capabilities](#extension-capabilities)), which no lint can check in SQL. For example, an extension that was renamed moves sessions' choices of its former name with `extension.rename_session_choices`, which owns the write to `session_extensions`. Reach another extension's tables through its [public feature](#public-features-own-their-tables). The typed core reads that extensions use are: - [`sdk/sessions`](../src/albedo/harness/sdk/sessions.gleam): a session's `names`, given name, family name, and title, from which each caller picks its own precedence (`label` gives the one agents and `family.name_of` use); its `standing`, whether a transfer is importing it or it moved; which of some sessions are `importing`; `describe`, its names with its workspace; and the discovery reads `find`, `all`, and `occupied`. - [`sdk/history`](../src/albedo/harness/sdk/history.gleam): besides the history reads, `seqs` for a page of a session's transcript rows, `spans` for when ranges of them were written, and `context_use` for its pin and the prompt tokens of its latest request. - [`sdk/mail`](../src/albedo/harness/sdk/mail.gleam): `statuses_in` for the letters an extension posted, by ID, `queued_in` for the letters still waiting for some sessions, `undelivered_in` and `delivered_in` for a page of the letters a producer filed under one grouping (`input.Filed`), `file_in` to file letters posted before, and `requested` for whom a session asked for work. - [`albedo/transfer`](../src/albedo/transfer.gleam): `occurred_in`, for an occurrence the daemon a session moved from ran after its export. - [`follow.Forked`](../src/albedo/harness/sdk/follow.gleam) carries the branch's copied rows as `branch_seqs`, so a follower maps source rows to their copies without reading the transcript. A read whose name ends in `_in` takes the caller's connection as well as its handle, so it runs inside the caller's transaction or read snapshot with the extension's own reads. Where a feature filtered its own rows by a core fact in one statement, it now reads its rows and asks the typed read about the sessions or letters they name. Keep such a split bounded: ask about the rows of one page, or the letters waiting for some sessions, which `mail.pending_limit` bounds, not about every row an extension ever kept. Do not filter a page by a core fact by walking the extension's history in Gleam. Page from the side whose index the filter selects, as webhooks' receipts page the letters filed under their hook in the state the page asks for. A grouping can live in a column the table already has, as `input.Filed` keeps it in the letter's key. Keep local bookkeeping that should not travel in a table no transfer carries, as webhooks' `webhook_upgrades` does. Adding a column to a carried table is allowed: moves are supported only from an older daemon to a newer one, and a move to an older daemon whose tables lack the column is refused at staging. See [moves between versions](workspaces.md#moves-between-versions). Settle an owner's imported rows in its transfer adapter's `activate`, which runs as the import goes live. `schedule` reads its first 25 due jobs and reads again without any importing session's, so those jobs never crowd out others. The host gives each extension a [`storage.Storage`](../src/albedo/harness/sdk/storage.gleam) handle that carries the shared store, the extension's name, its declared tables, and its declared capabilities. `extension.storage_of` builds it. The contexts an extension receives carry the handle in a `storage` field, and none carries the raw store: `Setup`, `Startup`, `Daemon`, `Preparation`, `ModelContext`, the tool `Context`, `host.Context`, `hook.Context`, `compaction.Context`, `web_search.Query`, `transfer.BindingsContext`, and `transfer.Activation`. Callbacks that touch the store receive the handle too: `ManagedPlugin` and `StartedManaged`, `GlancePlugin`, `SchedulePlugin`, `DataMigration`, `FoldPlugin`, and `extension.storage_initialise`. No plugin variant hands an extension the raw store. Callbacks that receive a connection, such as `CleanPlugin`, `SchemaMigration`, `FollowPlugin`, and `Due.advance`, need no handle. The transfer adapter's `disarm`, `occurrences`, and `refuse` take the handle, and its `activate` reads it from its `transfer.Activation`. When the host builds one context before it knows which extension receives it, it fills `storage` with `extension.unscoped`, which names no extension and no tables. The host replaces it before an extension's callback runs: - `composition.tools`, `composition.tool`, and `composition.routes` wrap each extension's tools and routes, so one `host.Context` per composition reaches each route with its own extension's handle, bound to the calling session. They wrap when read, not in `composition.compose`: the composition is copied between processes, and a stored wrapper copied its handle once per closure, about 18 KB per idle session. `composition.definitions` reads tool definitions without wrapping, and `composition.tool` wraps only the tool a call names. - `composition.commands` and `composition.command_entries` bind each declared `command.Command(command.Invocation)` with `extension.scoped_commands` into the `command.Command(command.Context)` the dispatchers run. Each call turns the handle-free `command.Context` the host built into a `command.Invocation` that carries the command's extension's handle, bound to the context's session, as `storage`. A `command.Context`, such as `host.Context.session_state`, carries no handle, and the types keep a command from running without one. Read the handle from the invocation instead of capturing one in a command: a captured handle is copied with every copy of the composition (skills' load recorder cost about 16 KB per idle session). - `composition.hooks` gives each hook, from a `HookPlugin` or a managed contribution, a `hook.Context` that carries its extension's handle bound to the session it asks for, built by `extension.hook_context` when the hooks are read. Read it there instead of capturing one in the hook (agents' hook cost about 0.3 KB per idle session). See [hook context](hooks.md#hook-context). - `extension.service` scopes the `Daemon` its handler receives. - `extension.upstream`, `fast_mode`, `cyber_catalog`, and `cyber_access` scope the `ModelContext` for the provider they ask. - `extension.compaction` and `extension.notes` scope the `compaction.Context`. - `extension.searches` scopes each provider's `web_search.Query`. - `extension.transfers` scopes each adapter's `BindingsContext`, its `Activation`, and the handle its `disarm`, `occurrences`, and `refuse` receive, and gates the inbox in the `Activation`. The daemon passes them `extension.unscoped`. - `extension.install` builds each extension's `Setup` and `Startup`. Run the extension's own SQL through `sdk/storage`, not `sdk/store`. Its operations match the `sdk/store` functions of the same names. Typed core and SDK operations take the handle itself, such as `sdk/history`, `sdk/family`, `sdk/search`, `worktree`, `links`, `kernel/journal`, an `input.Inbox` callback, or a `mail.Letters` read. Pass them the handle from your context. Those operations own the core tables they touch, and the ones `capability.functions` lists check the handle's declared capabilities ([extension capabilities](#extension-capabilities)). No extension code holds the raw store. Core code that holds the store passes `storage.host(store)`, a handle with no extension, no tables, and every capability. Do not call `storage.new`, `storage.host`, `storage.bind`, or `storage.ledger` from an extension. Name the tables given to `storage.forget_session` and `storage.add_columns` as string literals so the lint can read them. Nothing checks the table scope at run time. The connection a callback receives is the shared writer's or a reader's. Two lint rules enforce the contract in extension code: - `albedo_extension_raw_store` flags an import of `albedo/harness/sdk/store` and any use of `storage.new`, `storage.host`, `storage.grant`, `storage.declare`, `storage.bind`, or `storage.ledger`, and any use of an SDK reader that takes a raw connection and reads a session's stored data. It also flags `storage.owned_by` outside a public feature module. - `albedo_table_ownership` flags SQL that names another extension's created table. It also flags SQL that names a table the extension does not declare, including one it creates. SQLite's `sqlite_` schema tables, `pragma_` functions, `json_each`, and `json_tree` are exempt. Core tables are not exempt: read them through the typed operations above. The rule also flags a `tables` entry the extension does not create. ### Migrations An extension changes its stored data with a `MigrationPlugin`. Both variants of [`extension.Migration`](../src/albedo/harness/sdk/extension.gleam) take a `name` and a [`migration.Compatibility`](../src/albedo/harness/sdk/migration.gleam): - `SchemaMigration(name, compatibility, apply)` runs on a connection right after the extension's initialiser, at every startup. Make `apply` idempotent. - `DataMigration(name, compatibility, run)` runs after core data migrations, with the extension's handle and the pre-upgrade backup path. It returns the rows it rewrote. Mark a migration `Breaking` when a build without it would misread or lose the extension's data, for example after a rename or a format rewrite. The host records a breaking migration's name in the home before it writes, and a build that does not know the name refuses that home. Prefix the name with the extension's name and never change it. When you remove a breaking migration, or the extension that declares it, add its name to `migrations.retired`. See [downgrades](migrations.md#downgrades). ### Public features own their tables A [public feature](#public-feature-dependencies) runs its SQL under its owner's handle, even when another extension calls it. Its module declares a `storage.Owner` with `storage.owned_by`, from the owning extension's name and `tables` constant, and its functions run their SQL under `storage.as_owner(caller, owner, session)`. An extension that calls the feature declares that owner with `extension.FeaturePlugin(feature.owner())`. `extension.storage_of` grants the extension's handle each owner it declares. `as_owner` answers a handle scoped to the owner's name and tables when the caller declares the owner, and the caller's own handle when the caller is the owner. It answers an error otherwise, so a setup that calls an undeclared feature quarantines its extension. The grant does not limit SQL at run time. `session` names the session whose data the call reads or writes. `as_owner` applies the same rule as the SDK history reads to it ([extension capabilities](#extension-capabilities)): a handle bound to that session, or a host handle, passes, and any other handle passes only when its extension declares `History`. The owner's handle would otherwise read another session's rows for any caller. Pass `Some(session)` from every feature function keyed by a session, and from one keyed by a row of a session, such as an LCM node, the session that holds the row. Pass `None` only for work on no session's data, such as `initialise`. - [`rolling/strategy`](../src/albedo/harness/extensions/rolling/strategy.gleam) declares `rolling.owner()`. Its strategy and `initialise` read and write `rolling_compaction_state` under rolling's handle. `snapcompact` and `snapcompact-memory` declare it, because the text fallback and their setup use rolling's strategy and table. - [`lcm/graph`](../src/albedo/harness/extensions/lcm/graph.gleam) declares `graph.owner()`, owned by `lcm-memory`. Every graph function that takes a handle runs under it, including those `lcm/core` calls. `coding-lcm` and `persistent-agent` declare it. - [`models/catalogue`](../src/albedo/harness/extensions/models/catalogue.gleam) and [`memory/linked`](../src/albedo/harness/extensions/memory/linked.gleam) touch no tables, so they declare no owner. Pass a feature function the handle from your context. Do not build a handle for the owner, and do not reach the owner's tables through the raw store. A new public feature that touches its owner's tables declares an owner the same way, and each extension that calls it declares a `FeaturePlugin`. ### No storage baseline Every extension declares its tables and runs its SQL through its handle, so both storage rules apply to all extension code without exceptions. There is no baseline to add a finding to. Fix a new finding by declaring the table, by moving the SQL behind the handle, or by reading or changing the core table through a typed core or SDK operation, adding one where none answers. See [Gleam lint](gleam-lint.md#extension-storage-rules) for what the rules match. ## Extension capabilities Some context fields carry authority beyond an extension's own session data: posting to any session, controlling sessions, reaching other daemons, or calling other extensions' providers. These fields are capabilities. Each extension declares the capabilities its code uses in the `uses` field of its [`extension.Extension`](../src/albedo/harness/sdk/extension.gleam). Write the list as a constant of [`capability.Capability`](../src/albedo/harness/sdk/capability.gleam) constructors in a Gleam module under the extension's directory, and pass that constant to the constructor as `uses:`, `uses: editor_uses`, or `uses: module.uses`. An extension that uses no capability passes `uses: []`. Each constructor has its own declaration, even where several extensions share a directory and its [`tables`](#extension-storage): `editor-mcp` passes `editor_uses`, which holds the `EditorOverlay` it reads, and `mcp` passes `[]`. Set `uses` only in the constructor. A record update such as `extension.Extension(..bundled, plugins: ...)` keeps its record's declaration. | Capability | Context fields | | ---------------- | ---------------------------------------------------------------------------------------------- | | `Inbox` | `inbox` on `Setup`, `Startup`, `Daemon`, `host.Context`, and `transfer.Activation` | | `Mail` | `letters` on `Preparation` and `host.Context`, and `host.Context.send_mail` | | `SessionControl` | `control` on `Daemon` and `host.Context` | | `SessionState` | `session_state` on `Daemon` and `host.Context` | | `Sessions` | `Daemon.sessions` | | `History` | none: the SDK reads of another session's history | | `Correspondence` | none: the SDK reads and changes of another session's letters | | `Remote` | `host.Context.correspondents` and `ask_moved`, and `Daemon.tell_refused` and `hook_gone` | | `Intake` | `intake_port` on `Daemon` and `Preparation`, and `transfer.BindingsContext.intake_url` | | `ShellOutput` | `host.Context.read_shell_output` | | `Upstream` | `Daemon.upstream` | | `Models` | `Daemon.models` and `Daemon.efforts` | | `Providers` | `searches`, `worktrees`, `imagegens`, and `followers` on `host.Context`, and `Daemon.searches` | | `Invalidate` | `invalidate` on `Startup` and `Daemon` | | `EditorOverlay` | `Preparation.editor_overlay` | `capability.fields` in [`sdk/capability`](../src/albedo/harness/sdk/capability.gleam) holds this table. The host gate denies exactly those fields, which [`extension_capability_test`](../test/harness/extension_capability_test.gleam) checks, and the lint rule reads the constant from source, so the three agree. The lint also reads the SDK's constructors from source to learn where the host calls extension code with a context. Every other field is plain data that the host always passes: session IDs, the workspace, the daemon home, the storage handle, the preparation owner, the tool context's kernel and image limits, and `host.Context.progress`, which is bound to the calling session. `ModelContext`, `compaction.Context`, `web_search.Query`, `hook.Context`, and a command's `command.Invocation` carry no capability. The host gates capabilities where it scopes `storage`. `composition.compose` gates each extension's routes, `extension.service` its `Daemon`, `composition.prepare` its `Preparation`, `extension.install` its `Setup` and `Startup`, and `extension.transfers` each adapter's `BindingsContext` and `Activation`. It replaces every capability the extension does not declare with a stand-in of the same type: - An operation that answers a `Result` answers `Error(" does not declare ")`. The inbox's `post` and `post_in` answer `input.Failed` with that text, and `intake_port` answers `Error(Nil)`, as it does while the listener is down. - `Daemon.models`, `Daemon.efforts`, and `Daemon.sessions` answer an empty list. `invalidate` and `tell_refused` do nothing. `hook_gone` answers the refusal text as its description, and `intake_url` answers `None`. - The four provider lists on `host.Context` have no failing path, so a denied `Providers` passes them empty. The first denied call of each extension and capability within an hour logs a warning that names both. A denied provider list logs nothing, because reading a list calls nothing. Extensions that declare what they use see the host's values unchanged. Typed SDK operations take the storage handle, and a few of them act beyond the caller's own data. `capability.functions` lists them with the capability whose authority they grant. The rule for `Sessions` is that a function which answers the ID of a session other than one its caller passed in needs it: - listings: `history.sessions`, `search.candidates`, `family.children`, `resources.recorded_kernels`, `sessions.all`, and `mail.requested`; - a name resolved to an ID: `family.resolve`, `family.locate`, `family.remote`, and `sessions.find`; - a related session's ID: `family.get`, which names the parent, and `family.started_by`; - the session a worktree records or runs: `worktree.get`, `for_session`, `for_workspace`, `list`, `remove`, and `running_occupant`. `sessions.occupied` answers no ID, but it tells whether any session works in a workspace, so it needs `Sessions` too. `family.set_role` and `family.set_verifier` change another session's family row, so they need `SessionControl`. `search.candidates` is listed under both `Sessions` and `History`, because it finds other sessions by what their messages say. `mail.requested` is listed under `Mail` and `Sessions`, because it reads a session's letters and answers their recipients. `mail.statuses_in`, `queued_in`, `undelivered_in`, `delivered_in`, and `file_in` read or file letters in the inbox, so they need `Inbox`, which posts them. A function listed more than once needs every capability listed for it. These mail functions also keep the session rule below. Holding another session's ID, from a letter, a webhook, or a tool argument the model supplied, does not let an extension read that session's history. `capability.session_functions` lists the SDK functions that take a session ID, or a `transcript.Snapshot` or kernel cell that names one, and read that session's stored history: its `sessions` row (`history.get`, `history.acp_marker`, `history.context_use`), its transcript (`history.snapshot`, `source_stats`, `latest_user_seq`, `rows_before`, `fold_sources`, `uploaded_image`, `seqs`, `spans`, `tool.transcript_read`, `tool.source_page`, `search.newest`, `page`, `page_without`, `running_call`, and `transcript_grep`), its request history (`request_history.last_turn`), and its kernel journal (`journal.get`, `find_call`, `draft`, `prepare`, `unfinished`, `recent`, `trace`, and `saved_trace`). Each one calls `storage.permit_session` with the session it reads. The rule is: - a host handle reads any session; - a handle bound to a session reads that session without a capability; - a handle reads any other session only when its extension declares `History`. The same rule covers a session's letters under `Correspondence` instead of `History`. The [`sdk/mail`](../src/albedo/harness/sdk/mail.gleam) reads of letters in the inbox are listed under it: `statuses_in`, `queued_in`, `undelivered_in`, `delivered_in`, `file_in`, which files letters, and `requested`. Each checks the rule for every session whose letters it reaches. `queued_in` checks the recipients it names and `requested` its sender before reading. `statuses_in` and the filed pages check the recipients of the letters they find, and `file_in` those of the letters it would file, before it writes. One letter to a session the handle may not reach refuses the whole call. These functions need the capability `capability.functions` lists for them as well. The list also names, by field, the reads of the `input.Inbox` and `mail.Letters` the host hands extensions that reach one session's letters: the inbox's `withdraw` and `waiting`, and the letters' `owed_requesters`, `owes_reply`, which reads both sessions it names, and `open_json`. [`mail.inbox` and `mail.letters`](../src/albedo/daemon/mail.gleam) check them. The inbox's `post` and `post_in` still reach any session under `Inbox`. So an extension that declares `Inbox` posts to any session, but withdraws from or reads the queue of another session only when it declares `Correspondence` too: withdrawing can take out another producer's letter. `Daemon.session_state` reaches any session's actor under `SessionState`, but a service's handle is bound to no session, so the gate keeps the same rule for the operations that read a session's letters or history. [`command.other_session_needs`](../src/albedo/harness/sdk/command.gleam) decides every `command.StateOp` in an exhaustive `case`, so a new operation does not compile until it is classified: - `QueueRead`, `QueueDrop`, and `QueueArrange` need `Correspondence`. - `ContextSummary`, `ContextPage`, `KernelJobs`, and `KernelRead` need `History`. Their answers carry what the session ran and its output, including the retained output of its background jobs. - The rest need nothing more than `SessionState`. They set or report the session's settings, drive its turn, or start, stop, or replace its kernel or jobs, and answer no output. `capability.session_functions` lists the operations that need a capability by constructor name, which the lint reads, and [`extension_capability_test`](../test/harness/extension_capability_test.gleam) checks that the list and the classification agree. `extension.gate_daemon` checks them with `storage.permit_session` for the session the context serves, and refuses an operation whose two answers disagree. An extension that declares every capability these operations need gets the host's `session_state` unchanged. `host.Context.session_state` serves the calling session, which its handle is bound to, so the host does not wrap it. The `mail` extension's queue service declares `Correspondence` for this, and the `run` extension's service, which lists and reads any session's jobs, declares `History`. `History` and `Correspondence` grant nothing of each other. Letters are where a producer's posts stand, which a service needs without reading any transcript. A transcript holds what the model said and ran, which letters do not show. `sessions.describe` follows the same rule under `Sessions` instead of `History`. It answers a session's workspace, not its history, and every `Sessions` listing shows that workspace already. The host binds a handle to the session of the context or callback that carries one, where it scopes `storage`: the tool `Context` and `host.Context` in `extension.scoped`, `Preparation` and the `ManagedPlugin` handle in `composition.prepare`, `compaction.Context` in `extension.compaction` and `notes`, `ModelContext` for each provider, `web_search.Query` in `extension.searches`, `hook.Context` in `composition.hooks`, `FoldPlugin` folds, and the `GlancePlugin` read. `extension.session_storage_of` builds such a handle. `Setup`, `Startup`, `Daemon`, `transfer.BindingsContext`, `transfer.Activation`, `SchedulePlugin`, and `DataMigration` handles are bound to no session, so a service or a startup worker reads no session's history without `History`, and no session's letters without `Correspondence`. The host cannot bind a handle to a session that only an extension's own tables name, such as the session that owns a webhook or a Discord bot. A service that reaches the letters of such sessions declares `Correspondence`. `storage.as_owner` keeps the caller's bound session and checks the session a feature call names. Only the host calls `storage.bind`. Family facts, such as `family.role`, `family.closed`, `family.owns`, and `family.name_of`, stay plain: they address a session but do not read its history. So do `sessions.names`, `standing`, `standing_in`, and `importing`, which answer only about the sessions their caller names, and `transfer.occurred_in`, which reads no session's data. `images.bytes` and `images.reader` stay plain too, because they read an image by its content hash, which only a transcript row names. Finding another session's ID still takes a `Sessions` function, and reading its history takes `History`. A callback that holds a connection, from `storage.snapshot`, `storage.query`, or a plugin that receives one, has no handle to check. So the SDK readers that take a connection and read a session's stored data are core's alone: `history.read_info` and `snapshot_in`, `request_history.last_turn_in`, `family.member_in`, and `journal.traces_in` and `session_hashes`. The `albedo_extension_raw_store` lint refuses them in extension code. Read through their handle-taking counterparts, such as `history.get`, `history.snapshot`, or `request_history.last_turn`. A transfer export collects the images that the moved sessions' kernel cells name in core (`transfers.cell_images`), not in the kernel's transfer adapter. `History` is separate from `Sessions` so that discovery does not imply reading. `links` and `worktrees` list sessions and their metadata but read no transcript. `schedule` checks that the session a new schedule names exists, which needs `History` but not discovery. `agents` reads and searches other sessions' messages and declares both. It also shows which requests other sessions owe and await, so it declares `Correspondence`. `webhooks` and `discord` read and file the letters they posted to the sessions that own their hooks and bots, from an upgrade, an import, a service, or a gateway manager bound to no session. They declare `Correspondence`, not `History`, because they read no transcript. `extension.storage_of` records the extension's `uses` in its handle, and each listed function calls `storage.permit` before it acts. A handle whose extension does not declare the capability gets `Error(" does not declare ")`, logged as for a denied field. `worktree.for_session`, `for_workspace`, and `running_occupant` answer an `Option`, so they answer `None`, as `journal.trace` and `saved_trace` do. `permit_session` refuses the same way. A host handle (`storage.host` or `extension.unscoped`) may call them all. A handle `storage.as_owner` returns for a public feature keeps its caller's capabilities. `permit` and `permit_session` refuse a function their list does not name, so a check cannot pass by a misspelt name. Extension SQL names no core table, so every core read an extension makes goes through one of these typed operations and its check. Add a typed operation for a new core read, and list it in `capability.functions` or `capability.session_functions` when it answers another session's ID or reads another session's history. The `albedo_extension_capability` lint rule checks the declaration in extension code. It flags a capability field read, or a call of a `capability.functions` entry, that an extension which may run it does not declare. A call of a `capability.session_functions` entry may read the session its handle is bound to, which the lint cannot tell from a variable, so it counts as a use of its capability but is flagged as undeclared only when its handle is the `storage` of a context with no `session` field, such as `daemon.storage`. The host refuses the other cross-session reads at run time. A read belongs to one extension when only that extension's constructor reaches the function that holds it, through calls or function references within the constructor's module. Every other read is shared: code in another module of the directory, a function two constructors reach, or a public function another module of the directory references may run under any of the directory's extensions, so each of them must declare the capability. Keep a read only one extension needs in a function only its constructor reaches. The rule also flags a declared capability the extension never reads, a name that is not a capability, a capability constant no extension passes, a `uses:` argument other than `[]` or a reference to a capability constant in the directory, and a record update that sets `uses`. A directory that moves plugins between `Extension` values shares every read, and a read in code another extension directory reaches is a finding, because it runs under the installing extension's declaration. Give a public feature what it needs as a parameter instead. It reads field access on a variable whose type is a context and record patterns of a context. A variable's type comes from an annotation, an alias of a known variable, or the callback position of an anonymous function the SDK calls with a context, such as a `StartupPlugin` callback or a handler in a route list. Pass a context to a helper with an annotated parameter, and the helper's reads count. Every extension declares its capabilities, so the rule has no baseline. See [Gleam lint](gleam-lint.md#extension-capability-rule) for what it matches. Declare only what the extension reads. Do not declare a capability to reserve it for later. ## Session data and effects [`sdk/history`](../src/albedo/harness/sdk/history.gleam) owns read-only history observations, including generic folds, boundary snapshots, uploaded image pages, and session metadata lists. The daemon reads history through the same functions and keeps every transcript write. Keep the captured snapshot through related reads. [`sdk/transcript`](../src/albedo/harness/sdk/transcript.gleam) and [`sdk/session_info`](../src/albedo/harness/sdk/session_info.gleam) own the shared value types, including a session stage's stored spelling. [`sdk/transcript_codec`](../src/albedo/harness/sdk/transcript_codec.gleam) owns the stored row format, and [`sdk/image_fit`](../src/albedo/harness/sdk/image_fit.gleam) applies image fit rows to earlier images. Producing a fit stays with the daemon's turn loop. Some of these functions are public only because the daemon calls them across modules: `history.info_columns`, `history.info_decoder`, and the `transcript_codec` packing functions. Treat them as internal storage helpers. Read history through the typed `sdk/history` functions. Do not write the core transcript, session, or image tables from an extension. Replay projection, note encoding, and image validation use [`sdk/projection`](../src/albedo/harness/sdk/projection.gleam), [`sdk/message_content`](../src/albedo/harness/sdk/message_content.gleam), [`sdk/note`](../src/albedo/harness/sdk/note.gleam), and [`sdk/image`](../src/albedo/harness/sdk/image.gleam). [`sdk/request_history`](../src/albedo/harness/sdk/request_history.gleam) owns the request `Prefix` type. Its `last_turn` returns the latest successful transcript turn's input identity. Background pings do not replace that observation. It reads only the turn's sequence, head hash, and inputs, so a malformed cost or cache-mark column on that row, or any malformed ping row, does not fail it. `requests.last_turn` in the daemon still reads and validates the whole row and its pings. Give a session something to read through [`sdk/input`](../src/albedo/harness/sdk/input.gleam) with the shared [`sdk/letter`](../src/albedo/harness/sdk/letter.gleam) kinds and deliveries: describe the input and post it through the `input.Inbox` the context carries. `extension.Setup`, `extension.Startup`, `extension.Daemon`, and `host.Context` each have an `inbox` field. Pass it on to the code that posts, as the Discord manager keeps it in its state. Do not store it in process-wide state. The record's `post_in` takes the caller's connection, so feature changes and their input commit together, and the session hears of it after the commit. Do not reach into the inbox's storage or the session's actor. See [inbox](inbox.md). Agents' letters to each other go through `host.Context.send_mail`, which is bound to the calling session. The [`mail.Letters`](../src/albedo/harness/sdk/mail.gleam) on `host.Context` and `extension.Preparation` reads the requests a session owes and has open. [`sdk/images`](../src/albedo/harness/sdk/images.gleam) owns image payload reads and inserts. `images.store_images` likewise retains the caller's transaction. The daemon keeps the `images` schema, release, and elision. [`sdk/image_codec`](../src/albedo/harness/sdk/image_codec.gleam) owns historical image row packing, validated loading with lazy readers, and legacy compaction fingerprints. It also owns image externalization, referenced-hash scans, and legacy base64 decoding. The packed shapes are private constructors in `image_codec` and `transcript_codec`, so rows keep the bytes earlier daemons wrote. [`transcript_codec_golden_test`](../test/harness/transcript_codec_golden_test.gleam) checks packing and the decoding of historical rows against [golden rows](../test/fixtures/transcript-codec-golden.txt) from the earlier Erlang codec. Change a packed shape only with a migration, and keep those rows passing. The daemon retains migration transactions. Publish notifications after commit. `extension.Daemon.invalidate` announces service changes. `host.Context.progress` is bound to its session. `host.Context.session_state` is the calling session's [`command.Context`](../src/albedo/harness/sdk/command.gleam). `extension.Daemon.session_state` returns the context of the session a service request names. Both reach session state through `command.StateOp` values, which the session's actor answers. The daemon owns the lookup from session ID to actor in [`command_state`](../src/albedo/daemon/command_state.gleam). The SDK cannot discover a session's state callback, so use the context the host supplies. Do not call `state` from inside the session's actor, because the call waits on that actor. `host.Context.read_shell_output` reads only that session's captured user-command output. A background service without a request context keeps the `extension.Startup.invalidate` callback its `StartupPlugin` received and calls it after commit. [`sdk/notice`](../src/albedo/harness/sdk/notice.gleam) decodes the completion notices a kernel posts under its own keys and withdraws them by key once their result was read. Its `post`, `withdraw`, and `waiting` take the route's `host.Context.inbox`. [`sdk/webhook_address`](../src/albedo/harness/sdk/webhook_address.gleam) builds delivery paths and addresses from a port. `extension.Daemon.intake_port` and `extension.Preparation.intake_port` read the daemon intake listener's current port, or `Error(Nil)` while it has none. Read it when you show an address. See [webhooks](webhooks.md#setup). [`sdk/session_control`](../src/albedo/harness/sdk/session_control.gleam) exposes typed session operations. It also defines the coordinator's `Op` and `Reply` values, which only the daemon's session registry handles. Each typed function takes the `session_control.Control` that `host.Context.control` and `extension.Daemon.control` carry. See [agents](agent-sessions.md). [`sdk/family`](../src/albedo/harness/sdk/family.gleam) owns the family tables, their schema, and the extension-facing family operations. [`daemon/family`](../src/albedo/daemon/family.gleam) keeps child admission, limits, closing, family revisions, remote stubs, and deletion claims. [`sdk/session_identity`](../src/albedo/harness/sdk/session_identity.gleam) owns the shared family member, address, stub, and local or remote destination values. `host.Context.ask_moved`, `extension.Daemon.tell_refused`, and `extension.Daemon.hook_gone` keep forwarding and refusal behavior for moved sessions with the daemon's [move owner](../src/albedo/daemon/moves.gleam). `extension.Preparation.editor_overlay` resolves an authorized editor overlay for MCP preparation. The daemon binds it to [`acp_overlay.resolve`](../src/albedo/daemon/acp_overlay.gleam). The returned [`sdk/editor_mcp.Overlay`](../src/albedo/harness/sdk/editor_mcp.gleam) captures its catalogue revision in lookup and save callbacks. A stale preparation cannot publish into a newer revision. Keep resource adoption with the MCP preparation owner. Obtaining this value does not allocate a client. [`sdk/profiles`](../src/albedo/harness/sdk/profiles.gleam) owns provider-profile validation and decoding, including generic settings reads. It does not require a session context. Native persistence and settings locking retain their existing owners. [`sdk/bytes`](../src/albedo/harness/sdk/bytes.gleam), [`sdk/text`](../src/albedo/harness/sdk/text.gleam), and [`sdk/term`](../src/albedo/harness/sdk/term.gleam) provide binary framing, native text conversion, and legacy term-order operations. Keep those conversions at foreign-data boundaries. [`sdk/opencode_gateway`](../src/albedo/harness/sdk/opencode_gateway.gleam) shares gateway request encoding, Responses replay reduction, and charged, allowance, and list-cost interpretation. Provider routing, account identity, and headers remain with each provider. ## Public feature dependencies These entrypoints expose intentional feature dependencies. Importing one does not enable that extension or substitute for selection of a provider: - [`models/catalogue`](../src/albedo/harness/extensions/models/catalogue.gleam) owns shared model enrichment and its existing cache refresh policy. - [`lcm/core`](../src/albedo/harness/extensions/lcm/core.gleam) and [`lcm/graph`](../src/albedo/harness/extensions/lcm/graph.gleam) expose the compaction graph shared with persistent-agent. LCM remains its table owner. - [`rolling/strategy`](../src/albedo/harness/extensions/rolling/strategy.gleam) owns the rolling strategy used by snapcompact's fallback. - [`memory/linked`](../src/albedo/harness/extensions/memory/linked.gleam) exposes the memory operation used when linking workspaces. The exact public module list lives in [`extension_cross_import`](../tools/lint/src/albedo_lint/rules/extension_cross_import.gleam). Do not import declaration modules or private workers to reach these features. A feature that touches its owner's tables runs under the owner's handle. Declare its owner as [public features own their tables](#public-features-own-their-tables) describes. ## Boundaries to preserve `extension.invoke` catches a tool crash and returns a refusal that says its effects are unknown. A `Fatal` failure ends the turn when the host could not record what a call did. Inspect effects before retrying an interrupted or crashed operation. Tool output can contain text and images. Consumers must use the provider's image limits. See [extension.gleam](../src/albedo/harness/sdk/extension.gleam). Extensions can expose Python bindings, such as [MCP](mcp.md), [skills](skills.md), and [image generation](imagegen.md). Every session has the kernel these bindings load into, so a binding needs no requirement. A binding is an interface to its host routes, not a separate permission grant. Its module is `priv/python/albedo_plugins/.py`, named in a `ToolPlugin`'s `python_modules`. See [add a Python binding](../docs/extensions.md#add-a-python-binding). Declare a binding's module in a static `ToolPlugin` unless whether it loads depends on the session, as the editor's `mcp` does. Spares import the modules that the harness base and the default extensions declare statically before a session adopts them. A module named only by a managed plugin loads at adoption instead. See [fresh spare kernels](kernel.md#fresh-spare-kernels). An extension owns the tables it creates. Keep SQL that names those tables inside the owning extension and expose operations through its interfaces. Declare them as described in [extension storage](#extension-storage). The [`albedo_table_ownership` lint rule](../tools/lint/src/albedo_lint/rules/table_ownership.gleam) checks that boundary. Use migration and cleanup plugins for extension-owned storage. Follow the [extension change rules](contributing.md#preserve-extension-lifecycle-boundaries) when changing selection, discovery, or resource lifetime. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Compaction](compaction.md) - [Plugins](plugins.md) - [Persisted settings](settings.md) - [Workspace packages](workspace-packages.md)