small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs plugins.md
20 kB · 344 lines
Markdown
at main

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.

  • Forked follows a fork or a rewind's archive copy, after the prefix is copied. See history.fork_in.
  • Truncated follows a rewind, after the transcript tail is deleted. See history.remove_tail.
  • WorktreeRemoved follows worktree removal, after the checkout is deleted and before its record is. See worktree.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.

  • QuotaPlugin contributes a usage_feed.Source. accounts lists the extension's sign-in accounts as Target values. profile maps a saved profile that names the extension to one Target, or Error(Nil). Both receive the runtime's key environment for key account reads. heal runs after every report the feed returns for one of the source's targets. Use accounts_source for a source with only sign-in accounts, and key_target for an API key. See quota.
  • ProfileModelPlugin contributes a ProfileModel for saved profiles that name the extension. efforts(home, profile, model) replaces the catalog's effort list when it answers Some. replay(profile, model, inputs) refuses a model switch whose projected history the profile cannot replay. See model efforts.
  • KeyEnvironmentPlugin names the environment variables that may hold an API key for an endpoint. The runtime composes every declared lookup into one key_environment.KeyEnvironment. It passes that value in ModelContext.keys, as the third argument of ModelCatalog.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.