Sessions¶
A session is one agent working in one directory, with a durable log: active, dormant
(stopped, log kept, woken when used), read_only, or erased. In the TUI /new starts
another beside it (--private, --remote PROFILE, or --branch for a fork that goes on
from this one's conversation) and /back returns; troupe resume latest opens the newest
in the directory, and troupe resume ID --headless "message" runs one more turn on it and
exits (command reference). A session you erase reads
erasure_pending until the plane has destroyed its key. Erased on your machine, it is
erased at the plane too and goes from your machine once the key is gone; erased elsewhere,
the copy on your machine goes the next time your client signs your daemon in. Erasing one
on your machine needs that sign-in: without it the daemon erases nothing and says which
plane it is sealed at.
A session on your machine whose agent cannot read something in its log does not wake: the
message you send is refused with what the agent raised. You can wake it anyway, with w in
the TUI, the composer's Wake it anyway in the desktop app, or troupe resume ID
--repair: each event the agent cannot read is skipped, the log keeps it and says so, and
the transcript shows "An event from … could not be read and was skipped" where it was.
Inviting somebody into a session, archiving, renaming and keeping one at the top, its task list, and links into the desktop app are on sharing a session by name.
Starting a session¶
Starting a session begins with the message (New session, /new). One sentence under
it says how it runs, "Runs on the platform with dev as build · everyone on core can open
it", each word a picker; the profile is the last used with room, else the first with room,
and a line says which. @dev, #plan, /local in the message set those and are removed
before the agent reads it; a full profile says Queue it and starts when a place frees. If
two of your teams may use the profile you pick the team once (its budget pays); it is kept.
What a profile gives the session is on profiles, and the terminal's screen
for it on a new session.
Private session¶
A session on your machine sealed under your own key, listed by the
plane and opened from another device: troupe --private, or Keep it private in the
desktop app, which uses your account on this computer once you sign in. Your client hands the daemon its
sign-in to the plane, again as it renews it and after the daemon restarts, and the daemon
keeps it in memory only; one started while it had none is sealed once it has. Signing out
(troupe logout, or Sign out in the desktop app) takes it back, and nothing is sealed
until you sign in again, when each private session carries on where it stopped. One with
nothing running goes dormant on its own a while after you stop looking at it, even while
it waits on your answer, so it does not keep the daemon up; answering later wakes it, and
the turn carries on.
Local only¶
Local only is a promise the daemon keeps, not only the client: the desktop app's
Use this computer only, or local_only: true in your own config for troupe
(settings), tells the daemon when the client connects. For the
sessions that client runs the daemon then calls no plane: remember to your own memory is
refused and offers the repository's, a session is not offered for steering, and it reads
the memory this machine already holds, as its first instructions_loaded says. While every
client attached is in Local only, the daemon's own checks with the plane wait too.
Steering from another device¶
A session on your machine you offer to the plane you are
signed in to, so you can follow and steer it from the desktop app or the console on
another device (the console's Mine, which anybody the plane knows signs in to, not only
its administrators): /steer on in the terminal, or Steer from elsewhere in the session's
head in the desktop app. Name the people who may steer it too (/steer on
bea@example.com), or only follow it (cy@example.com:observe). Your machine keeps one
connection to the plane while it is offered and nothing listens on it; your rules and
approvals hold for every prompt, and an approval answered from elsewhere is for that one
call. Elsewhere it is listed as Remote, with Offline since … while your machine is
away, as soon as it is offered, withdrawn or goes away, since the plane tells the desktop
app and the console rather than being asked again; the desktop app names who is steering
your session as they arrive and leave; in the terminal, HQ (/remote) lists the sessions offered to you beside the plane's,
as laptop rows, and opens one to steer it. Who joins and leaves is said in the session's
window, and the status line names who is there. At your first offer the daemon signs in
for itself and keeps that sign-in in your computer's credential store, so the offer stays
online after you close the terminal or the app, and the daemon does not stop while
something is offered. After a restart the offer comes back where the daemon starts when
you log in (troupe daemon login on); otherwise it is shown as offered until this
machine restarts, and comes back only once something starts the daemon again. /steer
off, or Withdraw, ends every remote view at once; with
the last one withdrawn, signing out or troupe logout, the daemon lets its sign-in go.
Your team's administrators may turn offering off for the team.
A private session is offered only after you say yes to what that means (a private session).
Goal and loop¶
/goal <text> in the TUI sets what the session works towards; the
agent sees it on every later turn until /goal clear, and it survives a restart. /loop
[n] lets the session work towards it on its own for up to n turns (10 unless you say,
loop_max_iterations). Each turn ends with the agent saying whether the goal is met, and
the loop stops when it is, at the limit, after three failed turns in a row, when the
budget asks you, or on /loop stop. The status line shows how far it has got, and you can
keep typing while it runs.
Approvals¶
Writing or editing a file and running a shell command ask first: the session
stops that one call and waits for allow, deny or allow-for-this-session. Anyone attached
with control rights can answer; the first answer wins and everyone is told who gave it.
Publishing an artifact asks too, and the approval is where you say whom it
is for: the agent proposes an audience only when you named one, and otherwise you choose
it there, whatever your permission rules or --auto-approve say.
Budget¶
Limits on turns, tokens and working time, plus your team's money budget on the plane.
When one is reached the agent says which and asks, or stops where the session's terms set a turn or time limit, as a trigger's may; it never silently continues.
The question says what the session has used and spent, and you answer with how much more
and for how long: pick a size for this run, this session or this workspace (which writes
it to the repository's .troupe/config.yaml, so the next session there starts with it),
or type an amount (+25, +50k tokens, +15 min, with session or workspace after
it). "No limit this session" lifts the limit it asked about for the rest of the session,
and the others still ask. Apart from the budget, a tool that fails ten times in a row
stops the turn and asks whether to go on, even with every limit lifted.
A repository¶
A session on the plane may be created with a GitHub repository
(owner/name), and its pod starts from a clone of it. On a profile that allows it, the
agent then pushes its work to a troupe/* branch, opens a draft pull request, reads CI on
it and pushes fixes, as your organisation's GitHub App and never as you; after three red
CI rounds it stops, says on the pull request what still fails, and leaves the draft for a
person. Each push and the pull request's link are in the transcript, and the session's
listing shows its branch, last commit and pull request
(the GitHub App).