/agents is a manager over the daemon's agents.* methods: the list says each agent's layer, model, tools, read-only badge, turns and windows; an edit is the person's own editor on a temporary copy, checked at once and kept when refused; every save names what runs without asking and asks again when it adds an auto; Tab in a window chooses its agent; the palette tells a command, an agent and a file's command apart¶
TUI decision 156 · accepted · 2026-10-10 · issue #503
- The manager.
/agentsopens a page (Troupe.UI.TUI.Agents), a list beside the selected agent: fromagents.list, each row's name, its layer (built-in, bundle, mine, repository), its model, how many tools it holds,read-only,max N turnsand the windows on this screen that run it (from the model, so a switch shows at once); the files that did not parse are listed after, with why. The detail isagents.getwith the session (permissions, tools, the file, what it hides, why it is not editable) and the first lines of its instruction; Enter reads the instruction whole, scrolled. - Editing is the person's editor, the writing is the daemon's.
ewrites the file's text (agents.get'stext) to a temporary file and opensVISUAL, thenEDITOR(Notepad on Windows,vielsewhere without either) on it (Troupe.Editor, throughTroupe.Client.edit_file/2, as the clipboard goes through the client). What comes back is checked withagents.validateat once. Refused, the errors are on the page, each with its field, and the text is kept: the nexteopens the kept text, not the file, andzlets it go. Unchanged, nothing is saved. Accepted, the save asks where:rthe repository's.troupe/agents/,mmine (<config>/agents/), Enter where it already is; Esc keeps the edit. A built-in is edited the same way, since what is saved is a copy that then answers to its name. The TUI never writes an agent file itself. Not chosen: a form for the frontmatter in the terminal (the desktop app's way; a terminal person has an editor), and opening the real file (a half-written file would be read by every session meanwhile, and the daemon's check would come after the damage). - What the agent may do, before it is saved. The save shows the permissions the text
sets, every
autofirst and by name. A save that lets a tool run without asking that did not before asks once more,yor back, compared as the desktop app compares (root Decision 842): with the file it replaces, the agent answering to the name now when it is in the layer saved to; anything else is a new file there, and everyautoin it counts. So a copy from the repository's layer, where anautowaits for the workspace to be trusted (root Decision 825), into the person's, where nothing holds it back, is asked about, and the question says so. A save that adds none goes at once. - Copy, new, delete.
ccopies the selected agent into the repository under its own name in one key (the common case: a built-in made the repository's), and the repository's own into mine; it is a save like any other, so the same question guards anauto.nasks for a name and opens the editor on a template (a read-only primary agent, which passes the check as it is).xdeletes the copy in the layer it is in, naming that layer first, and says what answers to the name after (agents.delete'slayer); a built-in is not deleted, and says how it is changed instead. - Read-only, and why. A bundle's agent says the console changes it
(
editable_reason), fore,candxalike. On a pod the remote client addsread_onlytoagents.list, the sentence the worker refuses a write with, and never sendsagents.putoragents.delete: the list says "read-only here", and every key that would write says the sentence. - The terminal goes to the editor. On Linux and macOS the editor is started by
/bin/shwith:nouse_stdio, so it has the TUI's terminal as its standard input and output; the shell first turns off mouse reporting and bracketed paste and leaves the alternate screen, and after it returns to it and turns them on again (mouse only when the screen had it). The TUI is waiting meanwhile, so nothing else reads the terminal. On Windows the editor is a program with a window of its own (Notepad,code --wait); one that wants the console is not supported there. This is the one process the TUI starts outsideTroupe.OS.Processbeside the file watcher (Decision 19): the reaper takes the child's standard input and output for its own pipe, and an editor needs the terminal; the person's editor on the person's file is left open if the TUI goes. - Each window says its agent, and Tab chooses it. The tile title is
1 build-1 (plan)and the pane'sbuild-1 (plan), and command mode's row for the window (TUI Decision 155) names the same agent: the window keeps the name it started with, and the agent followssession_created,agent_startedandprofile_switched(translated to:agent_named), so a session started without naming one saysbuild, notroot. Tab in a window with nothing typed (Decision 22's Tab, no longer a blind cycle) opens a chooser over it (Troupe.UI.TUI.AgentChooser, the server'sswitcher; Ctrl-N's chooser of an agent for a new branch is command mode's own): the primary agents fromagents.list, the one in use marked, each with its layer and badges, and the highlighted one's description, permissions and instruction beside them. Enter sendsprofile.switchfor that window's session; the window keeps its conversation and the daemon'sprofile_switchedis a line in its transcript with the layer and the tools it gained and lost. The popup takesagents.listrows and hands back a name, so anything else that asks for an agent can open it. - The palette's three kinds. Each row has a kind column:
command(Troupe's own, muted),agent(accent),repositoryoryours(a file's command). An agent's row carries its layer, its model (defaultfor the session's),read-only, andworktreeorcheckout(whatagents.listsays a session on it would get), ahead of its description; its detail says it is an agent, not a command, and where it is managed. An agent the daemon says cannot run here (a model the provider does not serve) is greyed with the reason, as any row that cannot run now. The rows areagents.list's, asked for the first time the palette opens, from a task and over the session's own socket as the command table is, so neither the first frame nor the palette waits on them (the badges come a moment after), and read again whenever an agent is written here oragents.changedarrives, so a save in the desktop app is a row here at once. - The palette's rows the audit found wrong (D107). Opened over a window, a command the
palette takes to finish typing (one that wants an argument, or taken with Tab or Space)
goes into that window's box, where Enter runs it on that window as a command typed there
is run (TUI Decision 155):
/upload <path>from a window,/copytaken with Tab. A new query's cursor lands on the exact name, else the first name or alias it begins, soworand Tab give/worktree. A command a file defines that takes arguments (itsargument-hint) is put
Governs: clients/tui/lib/troupe/ui/tui/agents.ex, clients/tui/lib/troupe/ui/tui/agent_chooser.ex, clients/tui/lib/troupe/ui/tui/model.ex