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

Agents #

The agents extension exposes session relationships and operations to Python code. Its routes are implemented by agents/extension.gleam, with daemon operations reached through sdk/session_control. The host passes the daemon's coordinator as a session_control.Control in host.Context.control for kernel routes and extension.Daemon.control for the agents service. Pass that value to the typed functions, such as spawn and stop, and do not build Op values. Do not keep it in process-wide state.

The daemon's session registry installs the coordinator's handler in daemon/session_control when it starts, and the host binds session_control.call into both contexts. A call runs in the caller's process, outside every actor. Before the handler is installed it answers agents are unavailable. A handler that crashes mid-call answers agents are unavailable; outcome unknown. The daemon's own /kernel restart <session> command calls the same function. Each agent is a session. See session attachment.

Starting agents #

The Python binding exposes agents.start for a root peer and agents.self.spawn for a child. Both return an Agent handle. Spawn also accepts a verifier and cyber access choice. The host rejects an empty task or model, validates the name, and limits the verifier to 4096 Unicode scalars. dispatch passes the request to the daemon.

with_worktree handles the requested workspace before starting an agent. A workspace and its files are shared resources unless the chosen worktree gives the agent a separate directory.

Relationships and operations #

agents.self is the caller's handle. agents.get resolves another handle. A handle's children and siblings methods report family state, while switch, close, and cancel operate on an owned target. A deferred switch is stored on sessions (pending_switch_*), survives a restart, and clears once applied or replaced. agents.models asks for available models. agents.cancel_all can include descendants. See the Python binding and service.act and stop_all.

agents.set_role permits changing the caller's role or that of an owned child or peer. Only a child's parent can call child.set_verifier. agents.progress publishes a nonempty status of at most 512 Unicode scalars. These checks are in dispatch.

Messages and resources #

An Agent handle's messages method reads its transcript with sequence and pagination arguments. search_messages searches that transcript. agents.sessions searches sessions and clamps its result limit to 1 through 100. See the Python binding and agents/sessions.gleam.

A query reads the messages only of sessions that may hold it. The text index keeps the trigrams of each row's text, lowercased, in an FTS5 table that stores no text and no positions. search.candidates asks it for the rows holding every trigram of the query and adds the rows it has not read yet, which wait in transcript_text_pending. Waiting rows are indexed newest first, in store turns bounded by rows and payload bytes: all of them by a drain the registry starts when it opens, then those written since by each maintenance sweep, for up to two seconds. Triggers on transcript send a rewritten row back to wait and drop a deleted one, under any build, so the index only narrows a search and its results are those of reading every message. A query shorter than three code points has no trigram and reads every session.

resources.query reports process and session resource observations through the Python binding. Its host implementation is agents/resources.gleam. An observation does not guarantee that a process remains alive after the read.

Agent workflow #

Read agents.models() before choosing a model for a child. agents.self.spawn returns a handle, not the child's answer. Use mail for the result rather than treating an idle snapshot as proof of completion.

Use child.set_verifier(command) for an observable completion check. The agents hook checks normal parent submissions and stops while a reply is owed. Ask questions with mail.request("parent", ...). Report a blocker with mail.submit("parent", ..., blocker=True) when the verifier cannot pass. Clear or replace a verifier whose condition is no longer relevant.

Limits #

The subagents settings section defaults to 12 open children per parent and three generations below a root. -1 removes either cap. The declarations are in family.limits_section, and family.link_in enforces them when it records a child. Family tables and the reads extensions use belong to sdk/family. Remote lookups check the family's own family_remote stubs first. Correspondents, sessions on another daemon that wrote to the caller, come from mail storage, so the daemon supplies that lookup as family.Correspondents (family.correspondents). Use mail by session ID to reach another session rather than adding nesting solely for communication.

The order of agents #

Clients rank working agents before idle agents, then closed agents. More recent activity ranks first within a state. A branch uses its best descendant rank so a working child can bring its ancestors forward. Equal branches use creation order and ID. See TUI ordering and web ordering. Check both clients when changing this policy.

Deletion boundary #

agents.delete refuses the request. Its error directs the user to delete through the session browser because deletion loses the child's work. agents.close is a separate operation. See dispatch and session lifecycle.

Agent.close() marks the family member closed before cleaning up, so new mail cannot enter during shutdown. It returns True after the kernel and its jobs stop. The session saves its namespace before shutdown and keeps the transcript, files, and worktree. Saving or shutdown failures raise an error while the family member remains closed. A timeout can leave cleanup pending. Repeat close to reconcile cleanup, including recorded kernels with no session worker. See registry.run_agent_plan and session.close_agent.