small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
11 kB · 195 lines
Markdown
at main

MCP extension #

The MCP extensions provide session-owned connections and expose discovered operations through Python. Configured servers and editor-provided servers have separate host routes but share the mcp binding. See MCP extension and Python binding.

Configure servers #

The mcp settings section accepts stdio and http servers. Stdio requires command and accepts args, cwd, and env. HTTP requires url and accepts headers and bearerTokenEnvVar. Environment and header values can be literal strings or environment references. Servers default to enabled. enabledTools and disabledTools select tools. Startup and call timeouts default to 20,000 and 60,000 milliseconds. Both must be positive and at most 3,600,000 milliseconds. retryMs defaults to 30,000. See server_decoder and config_section in extension.gleam.

The daemon's mcp settings group saves definitions in extensions.json and secrets in creds.json. It reaches the configured extension's checks through its McpServersPlugin, described in plugins. servers.gleam owns validate_settings, server names, the URL rule, and the client transport. Validation never resolves environment references. A transport resolves them when it is built. secrets.gleam reads a server's creds.json entry. It refuses a creds.json that is not a regular file, is larger than 1 MiB, or grants group or other permissions. daemon/settings.gleam calls validate for each changed server and check when validate_connection is true. It calls signed_out when a patch sets oauth to null. These checks run while mcp is disabled. If no installed extension contributes the plugin, a patch that saves a server fails with 503 mcp_unavailable. Removing a server still works.

An HTTP server's OAuth sign-in comes from sign_in.resolve. Its keep callback writes the credential into the server's creds.json entry and keeps the registration of an earlier sign-in. Its exchange checks the issuer on the oauth.Grant it receives against the authorization server's issuer. See sign-in. oauth.gleam owns discovery, client registration, the token exchange, and the token a request sends. A token response must name the bearer type, case-insensitively, or leave token_type out; any other value, including one that is not a string, refuses the token. Refreshes of one server are single-flight within the daemon. Record updates hold the settings lock through sdk/settings_documents.

Tools and lifecycle #

The configured extension prepares an owned managed contribution. It saves the last catalogue by server name and configuration fingerprint. An unavailable server produces a warning. The session can refresh when its catalogue changes. The host closes the connection when the contribution closes. Cold clients monitor both the preparer and runtime before opening their transport, through discovery and catalogue saving. Ownership transfers to a connector before preparation returns. See prepare and initialise_catalogues in extension.gleam. bundle.gleam owns the prepared bundle: preparation entrypoints, calls, adoption, close, and the settings and editor probes.

Server names, descriptions, and results are untrusted data. A failed or interrupted call may have had effects, so inspect those effects before retrying. A server-reported error appears in isError. A host failure raises McpError. See extension.gleam and mcp.py. dispatch.gleam builds each call's request and refuses a result larger than 4 MiB. bundle.call runs it in a worker that it kills 250 milliseconds after the operation's timeout. It then closes that server's client, because a request the server never answered leaves the connection in an unknown state.

Catalogue policy and cache #

catalogue.gleam owns filtering, advertised identifiers, operation schemas, summaries, and context and Python definition rendering. Operations and summaries stay typed inside the runtime. Schemas retain the server's native JSON-compatible values without a JSON text round trip. Keep feature policy here and follow the shared contribution rules.

Tool and resource list failures fail discovery. Resource templates and prompt lists are optional and become empty on failure. Discovery preserves server order and permits at most 256 selected tools per server. The joined catalogue permits at most 512 operations and rejects duplicate advertised identifiers. Descriptions and resource identifiers are bounded untrusted text.

param_headers.gleam validates x-mcp-header annotations and converts call arguments to header values. HTTP discovery warns and excludes a tool with invalid annotations. Stdio discovery retains that tool without mirrored headers.

catalogue.encode and catalogue.saved write and read the existing version 2 external-term cache through albedo_bytes/term_codec. The cache holds atom-keyed maps, not Gleam records. Keep that saved shape compatible with existing catalogues. saved decodes safely, so it creates the cache's atoms first; add any new key to cache_atoms. servers.fingerprint keys each saved catalogue, so keep its term encoding stable as well. client.gleam owns each connection's process and its stdio port, which it opens, writes and reads through albedo_ports. The extension keeps no Erlang. servers.gleam resolves daemon variables, executables, and the launcher path. A stdio server's port unsets every daemon variable except a short safe list, then sets the server's own. See exact_environment in albedo_ports/subprocess.

Preparation and connection ownership #

preparation.gleam owns cached versus cold discovery and bundle sequencing. A thrown cache save closes the newly discovered client and earlier cold clients. Catalogue validation precedes watcher and connector allocation. A failed connector handoff closes completed connectors and clients still awaiting transfer.

connector.gleam owns connection, dial, refresh, waiter, and lifetime decisions. The connector process in connection.gleam owns monitors and attempts, with typed messages. Each dial attempt retains its client until client ownership transfer is acknowledged. The connector then acknowledges the attempt before answering waiters. Obsolete dial results close their own clients. A live connection remains usable during catalogue refresh.

watcher.gleam owns reason accumulation, activity coalescing, and completion-relative probe backoff. The watcher process in the same module probes offline servers only on session activity, without an idle polling timer. Coalesced events retain the first callback, and refresh runs only when a turn has ended. Reasons remain pending until replacement.

Readiness, adoption, and runtime publication are separate acknowledgments. Close uses bounded waits and can leave transport cleanup to owner-death handling after forced connector termination. Do not interpret connector death alone as confirmation that an external process has been reaped. Follow the shared lifecycle rules.

owned.gleam starts the connectors and the watcher. Each monitors the preparer and the runtime before it initializes. Until the runtime adopts it, it answers only adoption and stop, and its business messages stay queued. Only the runtime may adopt, and a repeated adoption by the runtime succeeds. Adoption drops the preparer monitor; the runtime's death still ends the process. bundle.adopt adopts the connectors in order and then the watcher, stopping at the first refusal. bundle.close stops them all within one shared deadline and is idempotent. Owned processes trap exits, so a crashed dial or refresh worker settles its attempt, and killing a connector also ends its linked workers.

endpoint.Seams names the discovery, client transfer, and connector start points that the ownership tests hold or fail. Production passes endpoint.seams(). Drive new lifecycle tests through the bundle's API and these seams, not through process internals.

Editor servers over ACP #

editor-mcp obtains the editor's session overlay and uses editor_mcp routes. Its overlay and catalogues live in daemon memory. The editor cannot reuse a configured server name. See editor_extension and prepare_editor in extension.gleam, and ACP.

The shared server configuration types live in sdk/editor_mcp. prepare_editor calls Preparation.editor_overlay, which the host binds to acp_overlay.resolve. It authorizes the marker and captures catalogue lookup and save operations for that revision. The attachment owner rejects a save after the overlay changes. Keep this captured capability through preparation rather than looking up a newer overlay halfway through it.

From Python #

await mcp.tools() lists operations, await mcp.search(query) ranks them, and await mcp.describe(name) returns a schema. await mcp.call(name, arguments) calls an advertised name or server/tool. The binding also mints mcp.<server>.<tool> methods from the catalogue at kernel boot. Operations added later or whose names cannot be minted remain reachable through call. See mcp.py.

Outbound routing #

The mcp outbound route applies to remote HTTP servers, discovery, and OAuth. A client resolves it when it starts and keeps it until it restarts. Stdio servers are not routed.