Plugins #
Plugins are contributions declared by an extension, not
independently installed packages.
Plugin defines the host
contracts. See the
SDK helper contracts for HTTP,
subprocesses, cache expiry, and background jobs. The
extension API reference provides function-level
documentation; Write an extension walks through a
complete extension that uses the common contributions.
Session contributions #
ContextPlugin loads workspace context. ToolPlugin declares instructions,
tools, Python modules, and routes without allocating resources or doing I/O in
the declaration. ManagedPlugin prepares a session contribution from the
extension's storage handle, the session ID,
and the workspace. OwnedManagedPlugin receives an extension.Preparation for
resources that must survive handoff safely. It holds the preparation owner, the
extension's storage handle in storage, the daemon's letters, session ID, and
workspace, plus an editor_overlay callback that resolves the session's ACP
editor overlay without allocating a client, and an intake_port callback that
reads the webhook intake's current port. The agents extension uses it for a hook
that reads letters, and the webhooks extension for routes and a command that
show intake addresses. Both use the empty contribution's callbacks, because a
ManagedPlugin receives only the handle, session ID, and workspace. Both
handles are bound to the prepared session, so they read its history without a
capability (see extension capabilities).
letters, editor_overlay, and intake_port are
capabilities: the host denies each one
the preparing extension does not declare in uses. CommandPlugin contributes
session commands. HookPlugin contributes a static hook, asked with
the same hook.Context as a managed contribution's hook, so a hook that needs
nothing prepared does not need a ManagedPlugin. See
extension.gleam.
composition.gleam
collects these contributions in registry order. Managed contributions can
observe session events, provide a hook that needs what preparation supplies, and
define adoption and close callbacks. Observers run inside the session actor and
must only send and return. Resource close callbacks must be idempotent.
OwnedManagedPlugin returns Result(Option(Owned), String).
extension.owned(contribution, adopt, close) constructs the opaque value with
both callbacks. None retains no resource or contribution. The opaque result
prevents accidentally returning an ordinary contribution with default callbacks.
Resource monitoring remains the allocator's responsibility.
Host route context #
host.Context supplies the store, the
daemon's inbox and letters, session ID, workspace, and the loaded search,
worktree, and image generation providers to kernel host routes. Its storage is
the storage handle of the extension whose
route runs, bound to the calling session. The composition sets it for each
extension's routes, and replaces each
capability the extension does not
declare in uses with a denying stand-in. Every field below except the session
ID, workspace, progress, and storage is a capability. See
inbox. Its followers are every declared
extension's FollowPlugin callbacks, enabled or quarantined or not. Pass them
to core changes that take them, such as worktree.remove. Its progress,
read_shell_output, and send_mail callbacks are bound to that session, as is
its session_state command context. The commands route runs commands with
that context, and the harness base's cells.no_reply ends the turn quietly
through it. send_mail sends an agent letter from the session through
forwarding.send. ask_moved relays a
call to the daemon a session moved to through
moves.ask_moved. correspondents finds a
session on another daemon that wrote to a caller, from the daemon's mail tables.
Pass it to family.locate and family.remote. control is the daemon's
session coordinator for the typed
sdk/session_control
functions. See agents.
kernels.kernel_routes builds it
from the same loaded Cached snapshot as the route composition. Reloads replace
the callback for later calls. Calls already running keep their captured context,
including the old workspace while a family move is deferred.
Routes that need only these values can be static ToolPlugin contributions, as
in work and
paperclips. Use
context.workspace for their loaded workspace. The database's desired workspace
and the process working directory can differ from it.
Image generation drivers #
ImagegenPlugin contributes a named
imagegen.Provider. Its generate
callback receives validated reference images and the session, profile, and call
identities. It returns encoded image data and optional request and generation
identifiers. The shared image generation extension owns driver
selection and admission; Python owns local publication.
Run the request once. Do not retry an uncertain outcome or fall back to another service. The callback runs in a cancellable worker, so keep sockets there and ensure any resource-owning child terminates when that worker dies.
Owned worker helper #
worker.observer(owner, run, observed, wait_ms)
starts an owned worker with worker.start and returns its opaque
extension.Owned contribution. The contribution starts from
extension.empty(). Its observe sends observed(handle, event) to the worker
inbox. Its adopt and close are the started worker callbacks.
observer returns Error(Nil) when the worker does not start. The caller maps
that error to its own startup message with result.replace_error. wait_ms is
the startup wait passed to worker.start.
Daemon contributions #
The same Plugin type declares provider and model catalogs, login, services,
startup, migrations, settings, cleanup, state transfer, history and worktree
following, and scheduled prompts. ServicePlugin defines an admission policy
and a body limit for its routes. MigrationPlugin distinguishes schema
migrations from data migrations, and each names itself and declares whether it
is breaking. CleanPlugin runs for installed
extensions when a session is deleted, including extensions that are disabled.
StartupPlugin receives an extension.Startup with the store, the extension's
storage handle, the daemon's inbox, and an
invalidate callback. The inbox and invalidate are
capabilities the extension declares in
uses. A background service that starts there keeps that callback to notify
clients after it commits a change. The callback returns the plugins that reach
what it started, described below. extension.install quarantines an extension
named after a settings section that the daemon passes as reserved, which
core_settings.names lists.
FeaturePlugin names the owner of a
public feature the extension calls.
It contributes nothing to a session. The host grants the extension's storage
handle that owner, as
extension storage describes.
See extension.gleam. The kernel's
own tables, startup reconciliation, and session cleanup are not plugins. The
runtime owns them.
FollowPlugin keeps an extension's rows in step with core changes that its rows
depend on. Its callback receives a
follow.Change and the connection of
the transaction that makes the change. An error rolls that change back. Every
declared extension's follower runs in registry order, enabled for the session or
not, and quarantined or not. A quarantined extension's tables can still hold
rows that must follow the change. Skip when your tables do not exist, and ignore
the changes your extension keeps nothing for. Core reads the list with
runtime.followers.
Forkedfollows a fork or a rewind's archive copy, after the prefix is copied. Seehistory.fork_in.Truncatedfollows a rewind, after the transcript tail is deleted. Seehistory.remove_tail.WorktreeRemovedfollows worktree removal, after the checkout is deleted and before its record is. Seeworktree.remove.
lcm-memory follows forks and truncations for the LCM graph. work follows
worktree removal for the work ledger.
SchedulePlugin contributes a due callback, given the extension's storage
handle, that returns the scheduled prompts due at a given time as
extension.Due values. The
registry's dispatcher calls every declared extension's callback on its tick,
quarantined ones included, and posts each prompt. The extension owns the timing
and repetition. Each Due carries an advance callback that runs in the
posting transaction and returns False when another tick already advanced the
occurrence. See inbox rows.
Startup callbacks run after the schema transaction commits. The host does not roll back an earlier successful startup if a later startup or dependency check fails. Extensions own the lifetime of long-lived startup resources.
A startup callback returns the plugins that need what it started. Use this to
hand a process handle to the extension's routes, service, commands, prepared
contributions, or transfer adapter. Build those plugins inside the callback so
their closures capture the handle. Install places them in the extension right
after the StartupPlugin, and the host reads them from the installed list as it
reads declared ones. Do not find a started process through a registered name or
another process-wide lookup.
The callback returns
extension.Started values.
StartedTool, StartedCommand, StartedManaged, StartedOwnedManaged,
StartedService, and StartedTransfer carry the payloads of ToolPlugin,
CommandPlugin, ManagedPlugin, OwnedManagedPlugin, ServicePlugin, and
TransferPlugin, and install converts each to that plugin. The host reads every
other kind before startup or from the declarations, so the type has no variant
for them and the compiler rejects returning one. Install checks the default
selection again after startup, so a returned tool, command, route, or Python
module that clashes quarantines its extension. Declarations that need no started
resource stay in the static plugin list. The
Discord extension returns its routes, service, and
transfer adapter this way. The
image generation extension returns the
prepared contribution whose routes reach its call admission.
Provider account and profile contributions #
Core reaches these provider contracts through the installed extensions, enabled or not. A quarantined extension contributes nothing, so its accounts are not polled for quota. Do not import a provider extension from core to reach the same behavior.
QuotaPlugincontributes ausage_feed.Source.accountslists the extension's sign-in accounts asTargetvalues.profilemaps a saved profile that names the extension to oneTarget, orError(Nil). Both receive the runtime's key environment for key account reads.healruns after every report the feed returns for one of the source's targets. Useaccounts_sourcefor a source with only sign-in accounts, andkey_targetfor an API key. See quota.ProfileModelPlugincontributes aProfileModelfor saved profiles that name the extension.efforts(home, profile, model)replaces the catalog's effort list when it answersSome.replay(profile, model, inputs)refuses a model switch whose projected history the profile cannot replay. See model efforts.KeyEnvironmentPluginnames the environment variables that may hold an API key for an endpoint. The runtime composes every declared lookup into onekey_environment.KeyEnvironment. It passes that value inModelContext.keys, as the third argument ofModelCatalog.list, and to quota sources. Key account readers take it as an argument instead of reading shared state. See typed key accounts.
Helpers in extension.gleam collect
them: quota_sources, profile_model, and key_environment.
Persisted extension settings #
Use settings.Section for a typed
section decoder and validation. settings.update(section, encode, change)
performs a locked read-modify-write of that section without extension-owned
native code. Follow the
typed update contract for encoder
overlays, pure callbacks, defaults, and failure behavior. Credentials and
multi-document mutations retain specialized owners.
MCP settings and editor probes #
McpServersPlugin supplies an
McpServers record for the
daemon's mcp settings group and for ACP overlays. names lists configured
server names. validate checks one server's saved definition and secrets
without resolving environment references or starting anything. check starts an
enabled server once and closes it. signed_out drops the tokens from a saved
OAuth record. EditorMcpPlugin contributes probe, which starts an editor's
candidate servers once and returns their catalogues without publishing them.
The daemon looks these up with extension.mcp_servers and
extension.editor_mcp_probe over the installed extensions, so a disabled MCP
extension still answers. A quarantined one does not. The first contribution in
registry order wins. See MCP and
ACP for what happens when none is installed.
HTTP services #
ServicePlugin serves routes below /extensions/<name>/ while the extension is
enabled globally. Session selection does not control these routes. The
daemon ingress applies the service's
admission policy before calling its handler. After a successful feature write,
use the supplied Daemon.invalidate callback to notify clients. A route that
acts on a session its path names, such as the
run jobs and
mail queue routes, reaches
that session's state through Daemon.session_state(id). A missing session
answers session unavailable. See the
session data and effects contract.
Daemon.control is the session coordinator, as host.Context.control is for
kernel routes. Daemon.storage is the serving extension's
storage handle. It is bound to no session, so
a service reads the history of a session its path names only when its extension
declares History. Daemon.intake_port reads the webhook intake's current
port. Every Daemon field except home and storage is a
capability. extension.service replaces
each one the serving extension does not declare in uses with a denying
stand-in.
service.json(body_limit, handle)
supplies daemon-token authentication and a fixed body limit. Its handler
receives the daemon, path segments below the mount, and a buffered
Request(BitArray). It returns a response or http_api.Failure. The adapter
renders failures as problem responses and rejects negotiation that selects an
event stream with 406 not_acceptable.
sdk/http_api owns the HTTP
contract that extension services share with the daemon. It defines Failure,
problem and bounded JSON replies, strict body and query decoding, Accept
negotiation, validators, timestamps, and paging tokens. The daemon's
HTTP adapter imports these definitions
and keeps session creation, input admission, ACP attachment, and daemon failure
codes. Extensions import the SDK module, never the daemon adapter.
Route dispatch, query and body decoding, and domain error mapping remain
extension-owned. Services that stream, serve non-JSON content, or need different
admission policies use
extension.Service directly. See
Expose a JSON service for
registration steps.
http_api.resource(url, etag, value)
encodes resource envelopes. revision_etag(namespace, id, revision) formats
integer-ID validators, and notification(status) encodes NotRequested,
Queued, or Failed(detail). Callers retain URL and payload selection,
fingerprint inputs, notification effects, invalidation, transactions, and
precondition checks.
Client declarations #
client_api owns typed field
kinds, declarative request bindings, and resource pages. ClientPlugin commands
are validated during installation, before the extension initializer runs. A
malformed command quarantines its extension with the command and field in the
error. Installation behavior is owned by
extension.install. After
preparation, composition
requires each client binding to name a command contributed by the same
extension. A missing command makes that extension inactive for the session,
closes its prepared contributions, and reports the extension and command names.
Commands prepared by managed plugins are checked at this stage.
Build page actions with client_api.actions, which returns validated Actions
or an error naming the action. Page requires this validated value. JSON
services return declaration failures as 500 invalid_client_declaration instead
of sending malformed controls to clients.
Validation rejects repeated or empty field names, action names, and binding keys, choices on other field kinds, empty choice lists, incompatible defaults, malformed JSON pointers, undeclared form inputs, and unmatched path placeholders. A null default means no preset value. Displayed defaults may bind only to row or session data. Actual row and session values are resolved and checked by the clients when the user opens a form. These declaration checks do not authorize requests or validate submitted domain values.