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.