# Agents The agents extension exposes session relationships and operations to Python code. Its routes are implemented by [`agents/extension.gleam`](../src/albedo/harness/extensions/agents/extension.gleam), with daemon operations reached through [`sdk/session_control`](../src/albedo/harness/sdk/session_control.gleam). 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`](../src/albedo/daemon/session_control.gleam) 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 ` command calls the same function. Each agent is a session. See [session attachment](sessions.md). ## Starting agents The [Python binding](../priv/python/albedo_plugins/agents.py) 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`](../src/albedo/harness/extensions/agents/extension.gleam) passes the request to the daemon. [`with_worktree`](../src/albedo/harness/extensions/agents/extension.gleam) 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](../priv/python/albedo_plugins/agents.py) and [`service.act` and `stop_all`](../src/albedo/harness/extensions/agents/service.gleam). `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`](../src/albedo/harness/extensions/agents/extension.gleam). ## 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](../priv/python/albedo_plugins/agents.py) and [`agents/sessions.gleam`](../src/albedo/harness/extensions/agents/sessions.gleam). A query reads the messages only of sessions that may hold it. The [text index](../src/albedo/daemon/transcript_text.gleam) 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](../priv/python/albedo_plugins/agents.py). Its host implementation is [`agents/resources.gleam`](../src/albedo/harness/extensions/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](../priv/python/albedo_plugins/mail.py) 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](../src/albedo/harness/extensions/agents/extension.gleam) 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`](../src/albedo/daemon/family.gleam), and `family.link_in` enforces them when it records a child. Family tables and the reads extensions use belong to [`sdk/family`](../src/albedo/harness/sdk/family.gleam). 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`](../src/albedo/daemon/family.gleam)). 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](../cli/internal/tui/agents_order.go) and [web ordering](../web/src/lib/agentTree.ts). 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`](../src/albedo/harness/extensions/agents/extension.gleam) and [session lifecycle](sessions.md). `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`](../src/albedo/daemon/registry.gleam) and [`session.close_agent`](../src/albedo/daemon/session.gleam). ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Session attachment](sessions.md) - [Inbox](inbox.md) - [Worktrees](worktrees.md)