small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
albedo robot-docs commands.md
4.0 kB · 77 lines
Markdown

Commands #

A command declaration describes its slash name, arguments, caller permissions, and result. command.gleam owns the declaration, dispatch, catalog projection, and host routes. Clients also have presentation-only commands that are not daemon command declarations.

The catalog #

The session command catalog describes prepared commands. command.catalog_json projects their metadata. The CLI catalog client reads it. Resource commands identify their HTTP operation rather than exposing an endpoint for arbitrary slash-command execution.

Contributing commands #

Extensions can declare commands through CommandPlugin, while managed extensions can supply dynamic commands. An extension declares a Command(Invocation). Its handler receives an Invocation, which carries the session, the extension's storage handle bound to it, and the typed StateOp interface to session state. The host binds each declared command with command.bind into a Command(Context), which the dispatchers run with a handle-free Context. Neither carries an inbox: a command reaches its own session through StateOps and turns, and posting belongs to host routes and startup workers, whose contexts carry a gated inbox (add a slash command). See Command, Invocation, Context, and StateOp and the extension types.

The daemon builds every Context. command_state keeps each session actor's state closure by session ID. command_state.context serializes a state call through that actor. State calls return command.StateError: a missing actor is SessionUnavailable, a missing job is JobNotFound, and an output page no longer retained is OutputLost(detail). Other failures carry their message in Other(detail). A failed or timed-out state call returns Other("session state call failed; outcome unknown"). Match these variants when choosing a response. Use command.state_error_text only when displaying the failure. Core dispatch calls it directly. Extensions receive a context from the host instead: host.Context.session_state for the calling session, and extension.Daemon.session_state for a session a service request names.

Command handlers run outside the session actor. A handler already running inside that actor must not call a command whose state operation waits on the actor, because that would deadlock. Model calls cannot invoke a command declared user-only or submit a user turn. user_turn controls delivery for a user invocation. See command.call.

Python bindings #

At kernel boot, the Python commands plugin creates an async method for each eligible model-callable command. Its signature and docstring come from the declaration. commands.catalog() reads the current catalog, and commands.invoke(name, arguments) invokes a model-callable command by name with text or a dictionary. Reserved, invalid, or later-added method names remain available through invoke. Model calls return data rather than submitting a turn.

Client commands #

The CLI command handling combines catalog entries with client presentation. Session settings changed by commands have the same persistence owners described in settings. Workspace-related operations are described in workspaces, and kernel operations in kernel.

Title inference and /retitle are described under generated titles.