small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
albedo robot-docs extensions.md
65 kB · 1,040 lines
Markdown

Extensions #

An extension is a named bundle of plugins. The registry in extensions.gleam declares installed extensions and defaults. The extension types define their contributions. See plugins for the host contracts, Write an extension for a working Gleam example, and the extension API reference 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 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), 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.

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.

Session composition #

composition.compose 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.

During reload, application workers borrow the adopted candidate and previous session. The runtime settles their results and closes the losing resources. See reload ownership for rejection, worker death, and late-result cleanup.

Extension settings #

SettingsPlugin registers an extension's settings declaration. settings/declared.gleam collects declarations and validates declared values. core_settings.all lists the daemon's own sections before each extension's extension.settings_sections. The daemon exposes them through its settings resources. See persisted settings for conditional updates and recovery, and plugins 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, remain available.

Extensions import nothing from albedo/daemon/. Storage is the scoped sdk/storage handle described in extension storage, and the HTTP contract is sdk/http_api. 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, which owns live and saved job reads and fallback rules, and kernel/resources, which exposes the supported kernel resource types. Any extension may import the core skills modules under albedo/harness/skills/. Every other kernel module is private to core, including albedo/harness/kernel, kernel/journal, kernel/tool, and 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, albedo/text_scalars, and albedo/actor_call. Transfer adapters import albedo/transfer 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.

The existing SDK modules are:

  • sdk/extension: Extension declarations, contributions, preparation and startup contexts, and preparation ownership.
  • sdk/storage: An extension's storage handle and the store operations it runs its own SQL through. See extension storage.
  • sdk/service: Buffered JSON extension HTTP services.
  • sdk/http_api: HTTP failures, problem and JSON replies, strict request decoding, negotiation, validators, and paging tokens shared with the daemon.
  • sdk/worker: Owned worker startup and adoption.
  • sdk/host: Context and routes for kernel host calls.
  • sdk/rpc: Host-call dispatch and argument decoding.
  • sdk/command: Session command declarations and state operations.
  • sdk/follow: Core history and worktree changes that FollowPlugin callbacks receive.
  • sdk/hook: Turn and tool hook events and verdicts.
  • sdk/tool: Retrieval tool schemas, paging, and rendering.
  • sdk/client_api: Declarative client HTTP operations.
  • sdk/imagegen: Provider-neutral image generation contracts.
  • sdk/web_search: Web search provider contracts and selection.
  • sdk/search: Transcript search with bounded database reads.
  • sdk/sessions: What the sessions table says about sessions: their names, workspaces, and whether a transfer is importing them or moved them. See extension storage.
  • sdk/page: Sidebar rows and command argument parsing.
  • sdk/http: 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 owns TLS options and the address-family fallback. Its get/4 and request/6 remain for core Erlang callers.
  • sdk/settings: Extension settings declarations and decoding.
  • sdk/credentials: Credential recovery, persistence, and notifications. text and lenient_text treat missing or non-string credential fields as empty strings.
  • sdk/key_accounts: 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: The runtime's composed KeyEnvironmentPlugin lookups. Pass the value from the context you receive to key account readers. See typed key accounts.
  • sdk/accounts: Pure account pool ordering.
  • sdk/rotation: Rate-limit account rotation.
  • sdk/oauth: 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: 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.
  • sdk/oauth_listener: The loopback listener that serves a sign-in flow's browser callback. Only oauth_flows uses it. See sign-in.
  • sdk/google_oauth: Shared Google token renewal.
  • sdk/model_lists: Provider model-list helpers.
  • sdk/concurrent: Linked concurrent calls with caller lifetime.
  • sdk/protect: 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: Usage driver execution and bounded I/O.

The SDK also provides these helpers.

  • sdk/digest: Hash, hex, base64, HMAC, and constant-time comparison helpers.

  • sdk/ids: Random and unique identifier helpers, including a version-4-shaped UUID derived from a seed.

  • sdk/env: Environment variable lookup, returning an empty string when unset. Read it during resolution or startup callbacks, never while constructing cached declarations.

  • sdk/file: 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: 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: A file's size and modification time, for caches derived once per file revision.

  • sdk/pinned: 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: creds.json reads, private atomic writes, the saved account sections, and cache file age. Hold the settings lock from sdk/settings_store across a read and the write that depends on it.

  • sdk/file_status: 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: 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: 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: Warning and debug messages for the daemon's log. Never include secrets or tokens.

  • sdk/process_flag: Flags in the calling process's dictionary that last as long as that process. Use a key type your module owns.

  • sdk/zlib: zlib compression and inflation bounded by a caller's byte limit. A damaged stream or checksum mismatch is an error.

  • sdk/priv: 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: Credential helpers with bounded stdout and timeouts, the command environment allowlist, and PATH lookup.

  • sdk/helper: Python helper subprocess execution with explicit outcomes, and open_python for a long-running helper port an extension reads itself.

  • sdk/port_program: 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: RS256 signing for provider authentication.

  • sdk/renderer: Runs of the optional albedo-render binary, its report lines, and a scratch directory deleted after each render.

  • sdk/memo: 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: Single-flight work shared by concurrent callers. The returned process runs the job; killing it cancels that job.

  • sdk/subscriptions: 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 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, lives in src/albedo/ so every layer can use it. albedo_registry holds keyed ETS registries whose tables outlive their callers. sdk/priv 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, such as the coordinator in session_control and the state closures in command_state. Extensions reach them only through capabilities in their context, such as control and session_state, that they declare. 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.

The first four rules do not restrict SDK implementation imports or JavaScript external bindings. The lint profiles 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. 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 describes what each check matches.

Extension storage #

Each extension declares the tables it creates in the tables field of its extension.Extension. 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 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), 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.

The typed core reads that extensions use are:

  • sdk/sessions: 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: 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: 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: occurred_in, for an occurrence the daemon a session moved from ran after its export.
  • follow.Forked 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. 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 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.
  • 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). 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 take a name and a migration.Compatibility:

  • 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.

Public features own their tables #

A public feature 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): 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 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 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 and memory/linked 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 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. Write the list as a constant of capability.Capability 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: 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 holds this table. The host gate denies exactly those fields, which extension_capability_test 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("<extension> does not declare <capability>"). 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 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 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 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 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("<extension> does not declare <capability>"), 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 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 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 and sdk/session_info own the shared value types, including a session stage's stored spelling. sdk/transcript_codec owns the stored row format, and sdk/image_fit 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, sdk/message_content, sdk/note, and sdk/image. sdk/request_history 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 with the shared sdk/letter 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. Agents' letters to each other go through host.Context.send_mail, which is bound to the calling session. The mail.Letters on host.Context and extension.Preparation reads the requests a session owes and has open. sdk/images 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 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 checks packing and the decoding of historical rows against golden rows 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. 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. 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 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 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.

sdk/session_control 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. sdk/family owns the family tables, their schema, and the extension-facing family operations. daemon/family keeps child admission, limits, closing, family revisions, remote stubs, and deletion claims. sdk/session_identity 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.

extension.Preparation.editor_overlay resolves an authorized editor overlay for MCP preparation. The daemon binds it to acp_overlay.resolve. The returned sdk/editor_mcp.Overlay 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 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, sdk/text, and sdk/term provide binary framing, native text conversion, and legacy term-order operations. Keep those conversions at foreign-data boundaries.

sdk/opencode_gateway 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 owns shared model enrichment and its existing cache refresh policy.
  • lcm/core and lcm/graph expose the compaction graph shared with persistent-agent. LCM remains its table owner.
  • rolling/strategy owns the rolling strategy used by snapcompact's fallback.
  • memory/linked exposes the memory operation used when linking workspaces.

The exact public module list lives in extension_cross_import. 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 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.

Extensions can expose Python bindings, such as MCP, skills, and image generation. 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/<module>.py, named in a ToolPlugin's python_modules. See 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.

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. The albedo_table_ownership lint rule checks that boundary. Use migration and cleanup plugins for extension-owned storage. Follow the extension change rules when changing selection, discovery, or resource lifetime.