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 thatFollowPlugincallbacks 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 thesessionstable 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.requestreturns status, headers, and bytes, including non-2xx responses.failureformats status errors;locationsfollows redirect locations concurrently. The httpc bindingalbedo_httpowns TLS options and the address-family fallback. Itsget/4andrequest/6remain for core Erlang callers.sdk/settings: Extension settings declarations and decoding.sdk/credentials: Credential recovery, persistence, and notifications.textandlenient_texttreat missing or non-string credential fields as empty strings.sdk/key_accounts: Typed snapshots of profile-bound key accounts.fast_modeselects the current connection before invoking the provider's support callback. A selection failure returnsFastUnknownwith the provider's error prefix. The callback owns model and endpoint eligibility, mode, source, and unavailable reasons.sdk/key_environment: The runtime's composedKeyEnvironmentPluginlookups. 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. BuildDeviceFlowinsideoauth.device's start callback so runtime environment overrides are read after sealed declarations load.sdk/oauth_flows: The sign-in service that runsoauth.Logindeclarations. The daemon starts it and passes the opaqueServicehandle 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. Onlyoauth_flowsuses 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 typedrescuethat can raise the crash again, andfinallyfor 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_optionaldistinguishes absence from read failure so a save can preserve an unreadable existing file. Bounded prefix and range reads close descriptors on every outcome.with_lockserializes a complete cache update within this daemon; it is separate from credential transactions and does not coordinate other OS processes.with_path_locktakes 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.refreshstarts at most one background fetch per refresh key when the file is stale.reloadfetches now and reports the failure. A fetch commits throughcommit, a rename that a failed fetch never reaches.isolatedruns 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. Eachputanderasecosts a global garbage collection pass, so pin only values that change rarely. -
sdk/credential_store:creds.jsonreads, private atomic writes, the saved account sections, and cache file age. Hold the settings lock fromsdk/settings_storeacross 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 ascreds.json, read and committed as a group through the settings store. Holdwith_lockacross a read and the commit that depends on it.mcp_secretsreads themcpsection ofcreds.json. -
sdk/term_codec: The Erlang external term format for caches and fingerprints that earlier daemons wrote.decode_saferefuses bytes that would create unknown atoms or functions.tupleandbinarycheck 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, aspinpinned 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, andopen_pythonfor a long-running helper port an extension reads itself. -
sdk/port_program: Typedopen_portsettings 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 optionalalbedo-renderbinary, 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_importflags anyalbedo/daemon/import from an extension. Use SDK helpers or supplied callbacks instead.albedo_extension_harness_importflags harness imports outside the SDK, extension directories, and the domain allow-list above. Use an SDK contract.albedo_extension_externalflags@external(erlang, M, _)unlessMhas an.erlfile 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_importrejects another extension's private modules. Deliberate feature dependencies use the public entrypoints below. Provider contributions still resolve from the active composition.albedo_core_extension_importflags analbedo/harness/extensions/*import from any Gleam module undersrc/albedo/outside the extension directories, including the SDK. It also flags an@external(erlang, M, _)binding in those modules whenMis an Erlang module owned by an extension. The registryextensions.gleamis exempt.albedo_sdk_daemon_importflags analbedo/daemon/import from an SDK module, and an@external(erlang, M, _)binding there whenMhas its.erlfile undersrc/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'snames, given name, family name, and title, from which each caller picks its own precedence (labelgives the one agents andfamily.name_ofuse); itsstanding, whether a transfer is importing it or it moved; which of some sessions areimporting;describe, its names with its workspace; and the discovery readsfind,all, andoccupied.sdk/history: besides the history reads,seqsfor a page of a session's transcript rows,spansfor when ranges of them were written, andcontext_usefor its pin and the prompt tokens of its latest request.sdk/mail:statuses_infor the letters an extension posted, by ID,queued_infor the letters still waiting for some sessions,undelivered_inanddelivered_infor a page of the letters a producer filed under one grouping (input.Filed),file_into file letters posted before, andrequestedfor whom a session asked for work.albedo/transfer:occurred_in, for an occurrence the daemon a session moved from ran after its export.follow.Forkedcarries the branch's copied rows asbranch_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, andcomposition.routeswrap each extension's tools and routes, so onehost.Contextper composition reaches each route with its own extension's handle, bound to the calling session. They wrap when read, not incomposition.compose: the composition is copied between processes, and a stored wrapper copied its handle once per closure, about 18 KB per idle session.composition.definitionsreads tool definitions without wrapping, andcomposition.toolwraps only the tool a call names.composition.commandsandcomposition.command_entriesbind each declaredcommand.Command(command.Invocation)withextension.scoped_commandsinto thecommand.Command(command.Context)the dispatchers run. Each call turns the handle-freecommand.Contextthe host built into acommand.Invocationthat carries the command's extension's handle, bound to the context's session, asstorage. Acommand.Context, such ashost.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.hooksgives each hook, from aHookPluginor a managed contribution, ahook.Contextthat carries its extension's handle bound to the session it asks for, built byextension.hook_contextwhen 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.servicescopes theDaemonits handler receives.extension.upstream,fast_mode,cyber_catalog, andcyber_accessscope theModelContextfor the provider they ask.extension.compactionandextension.notesscope thecompaction.Context.extension.searchesscopes each provider'sweb_search.Query.extension.transfersscopes each adapter'sBindingsContext, itsActivation, and the handle itsdisarm,occurrences, andrefusereceive, and gates the inbox in theActivation. The daemon passes themextension.unscoped.extension.installbuilds each extension'sSetupandStartup.
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_storeflags an import ofalbedo/harness/sdk/storeand any use ofstorage.new,storage.host,storage.grant,storage.declare,storage.bind, orstorage.ledger, and any use of an SDK reader that takes a raw connection and reads a session's stored data. It also flagsstorage.owned_byoutside a public feature module.albedo_table_ownershipflags 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'ssqlite_schema tables,pragma_functions,json_each, andjson_treeare exempt. Core tables are not exempt: read them through the typed operations above. The rule also flags atablesentry 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. Makeapplyidempotent.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/strategydeclaresrolling.owner(). Its strategy andinitialiseread and writerolling_compaction_stateunder rolling's handle.snapcompactandsnapcompact-memorydeclare it, because the text fallback and their setup use rolling's strategy and table.lcm/graphdeclaresgraph.owner(), owned bylcm-memory. Every graph function that takes a handle runs under it, including thoselcm/corecalls.coding-lcmandpersistent-agentdeclare it.models/catalogueandmemory/linkedtouch 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
ResultanswersError("<extension> does not declare <capability>"). The inbox'spostandpost_inanswerinput.Failedwith that text, andintake_portanswersError(Nil), as it does while the listener is down. Daemon.models,Daemon.efforts, andDaemon.sessionsanswer an empty list.invalidateandtell_refuseddo nothing.hook_goneanswers the refusal text as its description, andintake_urlanswersNone.- The four provider lists on
host.Contexthave no failing path, so a deniedProviderspasses 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, andmail.requested; - a name resolved to an ID:
family.resolve,family.locate,family.remote, andsessions.find; - a related session's ID:
family.get, which names the parent, andfamily.started_by; - the session a worktree records or runs:
worktree.get,for_session,for_workspace,list,remove, andrunning_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, andQueueArrangeneedCorrespondence.ContextSummary,ContextPage,KernelJobs, andKernelReadneedHistory. 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/catalogueowns shared model enrichment and its existing cache refresh policy.lcm/coreandlcm/graphexpose the compaction graph shared with persistent-agent. LCM remains its table owner.rolling/strategyowns the rolling strategy used by snapcompact's fallback.memory/linkedexposes 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.