A tour for contributors¶
For someone with the repository open who wants to change something: where things live, running the suite, adding a tool, and how the event log works. Each part stops where a page of this track takes over; operators have their own track.
1. Where things live¶
One Elixir umbrella under apps/, the terminal and desktop clients under clients/ (and
clients/vscode, which opens the terminal client in VS Code), a Helm chart under
charts/troupe, and the documentation. The clients and the plane reach a session only
through the protocol, and mix troupe.boundaries (the umbrella) and mix troupe.xref (the
terminal client) fail the build on any other call
(ARCHITECTURE.md §3), so the place a change goes is
usually the only place it can go.
| To change | Look in |
|---|---|
| what an agent does in a turn | apps/troupe_core/lib/troupe/agent/ — server.ex is the state machine, node.ex its supervisor |
| a tool | apps/troupe_core/lib/troupe/tools/, and the list in tools.ex (§3 below) |
| a built-in agent | apps/troupe_core/priv/agents/*.md |
| the log and replay | apps/troupe_core/lib/troupe/session/log.ex, lib/troupe/log/ (§4 below) |
| a model provider | apps/troupe_core/lib/troupe/llm/ |
| a command or an event on the wire | apps/troupe_protocol (the schema), apps/troupe_gateway/lib/troupe/gateway/dispatch.ex (the handlers), and PROTOCOL.md |
| the daemon's command line | apps/troupe_daemon |
| a worker pod | apps/troupe_worker |
| the plane, the console, an admin method | apps/troupe_plane: admin.ex, admin/api.ex, web/live/ |
| what the operator makes of a profile | apps/troupe_operator |
| the terminal client | clients/tui/lib/troupe/ui/tui/ for the screen, lib/troupe/remote/ for a plane |
| the graphical client | clients/gui/apps/desktop/src/views/, over clients/gui/packages/client/src/ |
| the chart | charts/troupe, its CRDs in charts/troupe/crds/ |
repo-structure.md has the whole tree and the generated files, and ARCHITECTURE.md the apps and where each kind of state is kept, and architecture.md and architecture-remote.md their supervision trees.
2. Running the suite¶
The toolchain is pinned in .tool-versions: Elixir 1.20.4 on OTP 28.5.0.5, Zig 0.16.0 for
the reaper every shell command runs under, and Node 24 for the GUI. On Windows,
scripts/setup-windows-toolchain.ps1 installs it. Then, from the root:
scripts/dev-up # PostgreSQL, OpenBao and MinIO in Docker, for the suites that need them
mix deps.get
mix check # compile --warnings-as-errors, format, credo --strict, boundaries, test
mix test apps/troupe_core/test/troupe/tools/read_tools_test.exs # one file
(cd clients/tui && mix deps.get && mix check) # the TUI
(cd clients/gui && pnpm install && pnpm build && pnpm test) # the GUI
mix check is the gate a pull request is held to. A suite without the services it needs
says so in a SKIPPED: block naming the command that brings them up, rather than passing
quietly (testing.md §2). No suite needs a model: the
fake provider replays a script of steps, one per model call, and records every request,
which is how the harness is tested end to end. local-setup.md has the
rest, including a whole plane on kind.
3. Adding a tool¶
A tool is a module implementing Troupe.Tool, in apps/troupe_core/lib/troupe/tools/.
glob.ex is a short one to copy the shape from.
- The five callbacks.
name/0is what the model calls.description/0is what the model reads to choose it, so say when to use it instead ofshell.schema/0is the JSON Schema of its arguments.default_permission/0is:autofor a tool that only reads and:askfor one that writes or runs anything; an agent definition'spermissions:overrides it.run/2gets the arguments and a%Troupe.Tool.Ctx{}, which is everything a tool may know, and returns{:ok, content}or{:error, reason}. - What the harness already does. The gate in
Troupe.Toolschecks the allowlist and the permission, and asks a person, beforerun/2is called, so a tool never checks either. The runner turns a raise, an exit or a timeout into an error result the model can read, so a tool does not rescue. An{:error, reason}becomes prose throughTroupe.Tool.Result.describe/1: give a new reason a clause there that says what the model should do instead. - What a tool must do itself. Resolve every path with
Troupe.Workspace.resolve/3, so a write never leaves the workspace. Bound the result where it is made — the head and tail of output, a window of a file — with a marker naming the exact call that returns the rest (architecture.md §1.3). Start any OS process withTroupe.Reaper.open/3, so it dies with the VM. - Register it at the end of
@builtinsinapps/troupe_core/lib/troupe/tools.ex. The order is the order the model sees, and a fixed order is what keeps the provider's prompt cache. - Agents. A definition with a
tools:list (explore,plan,reviewer) gets the tool only if it names it; one without a list gets every tool itspermissions:do not deny. - Test it in
apps/troupe_core/test/troupe/tools/, callingrun/2with aCtxover a temporary workspace, asread_tools_test.exsdoes. When it matters what the agent does with the result, drive a session with thefakeprovider.
Nothing on the wire changes: a call arrives at every client as tool_call_started,
tool_call_completed and tool_results, whatever the tool. A judgment call a reader
could have made differently is a file of its own in decisions/.
4. How the event log works¶
The log is the session. Each session has one Troupe.Session.Log process, which owns
one file, events.jsonl under the state directory, and is the only thing that writes
durable events. What an agent does, it logs first and acts on second; what a client sees,
it sees because the log published it.
sequenceDiagram
participant C as Client
participant G as Gateway
participant A as Agent.Server
participant L as Session.Log
participant F as events.jsonl
C->>G: input.send {command_id}
Note over G: the command_id is claimed first,<br/>so a retry gets the same answer
G->>A: the input
G-->>C: accepted
A->>L: append input_accepted
L->>F: write one line, fsync
L-->>A: seq
L-)C: the event, on every subscription
A->>L: append llm_request
Note over A: the model streams back:<br/>llm_delta ephemerals, never logged
A->>L: append llm_response, tool_call_started, …
L-)C: each event, as written
- Append is a synchronous call, and the file is fsynced before it returns, so an
agent never acts on something that was not persisted. One process per session is what
makes
seqgapless and the order of the file the order of the session. - Each event carries
prev_hash, so anyone can check a log from its bytes alone:Troupe.Protocol.Event.verify/1in Elixir, and the Python conformance client in a few lines of the standard library. Ephemerals (llm_delta,presence,agent_state, …) are never written. - Replay. A crashed agent folds its own events back into its state; a dormant session has no processes at all, and the next activating command starts its tree and the fold brings it back (architecture.md §1.2).
- Old logs.
Troupe.Log.Upcastbrings an old event up a step at a time, andfold_test.exsreplays every recorded version intest/fixtures/logs/against the hash of its fold, so a fold that quietly changed meaning fails CI. A moving hash is a bug to find, never a fixture to re-record (architecture.md §5).
Adding an event is a recipe in conventions.md §6; the events, the hash chain and what a client may rely on are in architecture.md §2 and PROTOCOL.md.
Where next¶
conventions.md for the gate, commit style and the other recipes (a command, an admin method, a setting, a GUI view); fixing-issues.md for how issues are worked through; and architecture.md for why it is all this way.