Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/ssh-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ The protocol is the remote host's own CLI, run over SSH as `agent-manager <comma
| Message an agent | `send --from=<sender> --json -- <id> <text>` |
| Answer an agent from the quick bar | `type --json -- <id> <text>` |
| Spawn | `spawn --json ...`, `terminal create --json ...` |
| Lifecycle | `kill`, `delete`, `revive`, `archive [--restore]`, `move`, `terminal close` |
| Groups | `create-group`, `delete-group` |
| Lifecycle | `kill`, `delete`, `revive`, `archive [--restore]`, `move`, `rename-session`, `terminal close` |
| Groups | `create-group`, `delete-group`, `rename-group` |
| Attach | `ssh -t <dest>` running `tmux -L agentmgr attach-session -t <session>`, then taking back any review or editor request the host's keys left on its tmux server |

The snapshot envelope carries `version`. A remote that does not know `snapshot`, or answers with an older version, says to update agent-manager on that host. One that answers with a newer version says to update it on this machine.
Expand All @@ -38,12 +38,13 @@ Once a connection is saved, every agent on this machine can reach that host thro

An SSH call has no calling session on the remote host. The commands it uses run without one:
- `kill`, `delete`, `revive`, `archive`, `move`, `create-group` and `delete-group` act as the user would.
- `rename-session` and `rename-group` rename a row the way the user's rename key does, and are refused from inside a session, which names itself with `rename` through its manager. They write the host's store directly, as `kill` and `move` do.
- `terminal create` opens a terminal that belongs to no session. `terminal send`, `read` and `close` drive only such terminals. A terminal nested under a session stays that session's.
- Every SSH call is the same caller there, so the local MCP server tells them apart: it records which session's `create_terminal` opened a remote terminal, and `send_terminal` and `close_terminal` on a `host::id` refuse any other session before calling ssh. A terminal opened with `T` on the connection row has no such record, so only the user drives it. The record goes when the terminal is closed through MCP or its session is deleted.
- `send --from` names the sender, at most 64 bytes. The delivered message says it came from another of the user's machines and that a reply cannot reach it. Every `--from` sender shares one rate limit per target.
- `type` submits the user's quick bar prompt in an agent's pane at once, as the local quick bar does. It is refused from inside a session. It carries no envelope and no rate limit, so it sits outside the guardrail the other commands keep: anything that escapes caller detection can type into any agent as the user. Each pane's send holds a lock file beside the tmux socket, so a typed prompt and the host manager's own delivery never interleave. When the host's paste started before the send failed, `type` exits with status 3; that, or a call cut off after agent-manager started there, means the prompt may sit in the pane, so the quick bar drops it rather than type it again, as it does on this machine.

Tasks, file reservations, rename and review still need a calling session.
Tasks, file reservations, `rename` and review still need a calling session.

### SSH invocation

Expand Down Expand Up @@ -75,7 +76,7 @@ The local machine can be Linux, macOS or Windows. The remote host must be Linux
## Not in scope

These are refused on a remote row with a message naming the gap:
- Rename, move, deleting a group, restart and fork.
- Move, deleting a group, restart and fork.
- Diff review.
- The editor.
- Copying a reply, marking idle, cancelling an after-turn end, reordering.
Expand Down
5 changes: 4 additions & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,8 @@ agent-manager spawn --tool claude --group "Sprint Manager" --worktree \

`type <session-id> "<prompt>"` submits a prompt in an agent's pane at once, as you, the way quick prompt mode does: no envelope, no queue, no wait for the agent to be at rest. It is how another machine's quick prompt mode answers an agent here over SSH, and it is refused from inside a session, which sends instead.

`rename-session <session-id> "<name>"` renames an agent or a terminal the way `r` does, its worktree branch included, and `rename-group <path> "<name>"` renames a group where it stands, its subgroups and sessions moving with it, the way the name on the Edit Group card does. They are how another machine's `r` reaches a row here over SSH. Both are refused from inside a session, which names itself once with `rename`.

`terminal create` takes `--name`, the way `spawn` does, so a shell opened for a long job reads for that job instead of the session it hangs under. `terminal create`, `send`, `read` and `close` run with no caller too. There a new terminal hangs under no session, in the group `--group` names or the root, and only terminals opened that way can be driven: a terminal nested under a session stays that session's, and one you opened in the manager or a session opened stays out of reach.

The commands that run with no caller are a convenience for a manager reaching this machine over SSH and for scripts, not an isolation boundary. Anything running as your user can call them, and an agent that drops its session environment is treated as a caller with no session. What they keep is a guardrail: such a caller cannot drive a terminal it did not open, and every `send --from` counts against one shared set of message limits, whatever name it gives. `type` is outside that guardrail: it speaks as you, with no envelope and no limit, so a process that escapes caller detection can type into any agent as you. It waits for a send already reaching the same pane, from this or another process, so the two never submit as one prompt.
Expand Down Expand Up @@ -439,9 +441,10 @@ On a connection's rows:
- `enter` and `A` attach over SSH in this terminal; detaching returns to the manager. A remote pane is never embedded.
- Quick prompt mode types into a remote agent's pane as you, the way it does on this machine, or starts a new agent on the CLI, model, effort and profile the bar shows when a connection or remote group is selected. `n` starts one there too; the directory and the worktree default are the other machine's unless you set them.
- `T` opens a terminal there and `g` creates a group there, under the selected one; `x` kills an agent or closes a terminal, `v` revives, `a` and `u` archive and restore. `d` deletes an agent there the way it does here, its worktree included when clean, and asks first; on a terminal it closes it, like `x`.
- `r` types a new name into an agent's, terminal's or group's row, and the other machine renames it the way `r` does here: an agent's worktree branch follows its name, and a group keeps its parent while its subgroups and sessions move with it. The Edit Group card's other fields, the default path, worktree, base and environment, stay as that machine has them.
- On the connection row itself, `r` edits it and `d` removes it. Removing asks first; its sessions keep running on that host.

Rename, move, deleting a group, restart, fork, review, the editor, copying a reply, reordering, marking idle, cancelling an after-turn end and kill all or revive all are refused on a remote row with a message naming the gap. A failed call shows the other machine's error. Nothing from a connection is written to this machine's store. See [SSH connections](ssh-connections.md) for the protocol.
Move, deleting a group, restart, fork, review, the editor, copying a reply, reordering, marking idle, cancelling an after-turn end and kill all or revive all are refused on a remote row with a message naming the gap. A failed call shows the other machine's error. Nothing from a connection is written to this machine's store. See [SSH connections](ssh-connections.md) for the protocol.

## Status

Expand Down
16 changes: 14 additions & 2 deletions internal/cli/cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,18 @@ func (f *fakeSessions) Move(sessionID, targetID, group string) (sessioncmd.Sessi
return moved, f.failWith
}

func (f *fakeSessions) RenameGroup(sessionID, path, name string) (sessioncmd.Group, error) {
f.callerID, f.groupPath, f.message = sessionID, path, name
return sessioncmd.Group{Path: "renamed"}, f.failWith
}

func (f *fakeSessions) RenameSession(sessionID, targetID, name string) (sessioncmd.Session, error) {
f.callerID, f.targetID, f.message = sessionID, targetID, name
renamed := f.session
renamed.Name = name
return renamed, f.failWith
}

func (f *fakeSessions) EndAfterTurn(sessionID, action string) (sessioncmd.AfterTurn, error) {
f.callerID, f.action = sessionID, action
return sessioncmd.AfterTurn{Pending: action, ManagerAwake: true}, f.failWith
Expand Down Expand Up @@ -568,8 +580,8 @@ func TestCommandsThatActAsNoSessionNeverResolveACaller(t *testing.T) {
func TestCommandsAndHelpCoverEverySection(t *testing.T) {
table := Commands("dev", sampleSpecs)
registered := []string{
"sessions", "snapshot", "spawn", "send", "type", "read", "wait", "message-status", "kill", "delete", "revive", "archive", "move", "archive-self", "kill-self", "prompts", "env",
"groups", "create-group", "delete-group", "task", "reserve", "release-files", "reservations", "terminal",
"sessions", "snapshot", "spawn", "send", "type", "read", "wait", "message-status", "kill", "delete", "revive", "archive", "move", "rename-session", "archive-self", "kill-self", "prompts", "env",
"groups", "create-group", "delete-group", "rename-group", "task", "reserve", "release-files", "reservations", "terminal",
"rename", "review-repo", "review-base", "review-mode", "review-comment", "issue", "feature", "settings", "export", "import", "update",
}
for _, name := range registered {
Expand Down
34 changes: 34 additions & 0 deletions internal/cli/session.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,13 @@ const (
usageRevive = "revive <session-id> [--json]"
usageArchive = "archive <session-id> [--restore] [--json]"
usageMove = "move <session-id> <group> [--json]"
usageRenameSession = `rename-session <session-id> "<name>" [--json]`
usageArchiveSelf = "archive-self [--cancel] [--json]"
usageKillSelf = "kill-self [--cancel] [--json]"
usageGroups = "groups [--json]"
usageCreateGroup = "create-group <path> [--directory <path>] [--json]"
usageDeleteGroup = "delete-group <path> [--json]"
usageRenameGroup = `rename-group <path> "<name>" [--json]`
)

type sessionCommands interface {
Expand All @@ -53,11 +55,13 @@ type sessionCommands interface {
Revive(sessionID, targetID string) (sessioncmd.Session, error)
Archive(sessionID, targetID string, archived bool) (sessioncmd.Session, error)
Move(sessionID, targetID, group string) (sessioncmd.Session, error)
RenameSession(sessionID, targetID, name string) (sessioncmd.Session, error)
EndAfterTurn(sessionID, action string) (sessioncmd.AfterTurn, error)
CancelAfterTurn(sessionID string) (sessioncmd.AfterTurn, error)
Groups(sessionID string) ([]sessioncmd.Group, error)
CreateGroup(sessionID, path, directory string) (sessioncmd.Group, error)
DeleteGroup(sessionID, path string) (sessioncmd.GroupRemoval, error)
RenameGroup(sessionID, path, name string) (sessioncmd.Group, error)
}

func newSessions(configDir string) sessionCommands {
Expand Down Expand Up @@ -113,11 +117,13 @@ func sessionSectionWith(open func(string) sessionCommands) section {
{name: "revive", usage: usageRevive, about: "bring a dead session back on its old row, resuming the conversation it held; an agent that quit inside a live pane comes back there", run: bind(open, runRevive)},
{name: "archive", usage: usageArchive, about: "file a finished session out of the active list, or restore it with --restore", run: bind(open, runArchive)},
{name: "move", usage: usageMove, about: "file a session under another existing group, the way the move key does; an empty group is the root, and a host::id moves it on that SSH connection", run: bind(func(configDir string) moveLayer { return moveLayer{open(configDir), storedHosts(configDir)} }, runMove)},
{name: "rename-session", usage: usageRenameSession, about: "rename an agent or a terminal the way the rename key does, its worktree branch included; only for a caller with no session here, such as a manager on another machine over SSH", run: bind(open, runRenameSession)},
{name: "archive-self", usage: usageArchiveSelf, about: "archive this session once the current turn ends, the way the archive key does; --cancel withdraws a pending archive or kill", run: bind(open, runArchiveSelf)},
{name: "kill-self", usage: usageKillSelf, about: "stop this session's agent once the current turn ends, keeping its row for revive; --cancel withdraws a pending archive or kill", run: bind(open, runKillSelf)},
{name: "groups", usage: usageGroups, about: "list the groups sessions and terminals are filed under", run: bind(open, runGroups)},
{name: "create-group", usage: usageCreateGroup, about: "create a group so a fleet you spawn stays together in the user's list", run: bind(open, runCreateGroup)},
{name: "delete-group", usage: usageDeleteGroup, about: "remove a group whose work is done; sessions still in it move to the root rather than stopping", run: bind(open, runDeleteGroup)},
{name: "rename-group", usage: usageRenameGroup, about: "rename a group where it stands, its subgroups and sessions moving with it, the way the edit card's name does; only for a caller with no session here", run: bind(open, runRenameGroup)},
},
}
}
Expand Down Expand Up @@ -407,6 +413,20 @@ func moveOnHost(layer moveLayer, ref remote.Ref, group, sessionID string) (sessi
return moved, nil
}

func runRenameSession(out io.Writer, sessions sessionCommands, args []string, sessionID string) error {
set := newFlagSet(usageRenameSession)
asJSON := jsonFlag(set)
operands, err := parseCommand(out, set, args, 2, 2)
if err != nil {
return err
}
renamed, err := sessions.RenameSession(sessionID, operands[0], operands[1])
if err != nil {
return err
}
return emit(out, *asJSON, renamed, "renamed "+sessioncmd.FormatSession(renamed))
}

func runArchiveSelf(out io.Writer, sessions sessionCommands, args []string, sessionID string) error {
return runEndSelf(out, sessions, args, sessionID, usageArchiveSelf, store.AfterTurnArchive)
}
Expand Down Expand Up @@ -476,3 +496,17 @@ func runDeleteGroup(out io.Writer, sessions sessionCommands, args []string, sess
}
return emit(out, *asJSON, removal, sessioncmd.FormatGroupRemoval(removal))
}

func runRenameGroup(out io.Writer, sessions sessionCommands, args []string, sessionID string) error {
set := newFlagSet(usageRenameGroup)
asJSON := jsonFlag(set)
operands, err := parseCommand(out, set, args, 2, 2)
if err != nil {
return err
}
renamed, err := sessions.RenameGroup(sessionID, operands[0], operands[1])
if err != nil {
return err
}
return emit(out, *asJSON, renamed, "renamed group "+operands[0]+" to "+renamed.Path)
}
38 changes: 38 additions & 0 deletions internal/cli/session_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,44 @@ func TestTypeReachesTheLayerWithItsPrompt(t *testing.T) {
}
}

// The SSH client's form, like type's: the id and the name after a bare --,
// so a name that starts with a dash stays the name.
func TestRenameSessionReachesTheLayerWithItsName(t *testing.T) {
out := &bytes.Buffer{}
fake := &fakeSessions{session: sampleSession()}
if err := runRenameSession(out, fake, []string{"--json", "--", "beef1234", "-new name"}, ""); err != nil {
t.Fatalf("rename-session --json -- id name: %v", err)
}
if fake.callerID != "" || fake.targetID != "beef1234" || fake.message != "-new name" {
t.Fatalf("rename-session reached the layer as caller=%q target=%q name=%q", fake.callerID, fake.targetID, fake.message)
}
var renamed sessioncmd.Session
if err := json.Unmarshal(out.Bytes(), &renamed); err != nil || renamed.ID != "beef1234" {
t.Fatalf("rename-session --json = %q (%v)", out.String(), err)
}
if err := runRenameSession(&bytes.Buffer{}, &fakeSessions{}, []string{"beef1234"}, ""); err == nil || err.Error() != "usage: agent-manager "+usageRenameSession {
t.Fatalf("rename-session without a name = %v, want the usage", err)
}
}

func TestRenameGroupReachesTheLayerWithItsName(t *testing.T) {
out := &bytes.Buffer{}
fake := &fakeSessions{}
if err := runRenameGroup(out, fake, []string{"--json", "--", "-team/a", "b c"}, ""); err != nil {
t.Fatalf("rename-group --json -- path name: %v", err)
}
if fake.callerID != "" || fake.groupPath != "-team/a" || fake.message != "b c" {
t.Fatalf("rename-group reached the layer as caller=%q path=%q name=%q", fake.callerID, fake.groupPath, fake.message)
}
var renamed sessioncmd.Group
if err := json.Unmarshal(out.Bytes(), &renamed); err != nil || renamed.Path != "renamed" {
t.Fatalf("rename-group --json = %q (%v)", out.String(), err)
}
if err := runRenameGroup(&bytes.Buffer{}, &fakeSessions{}, []string{"web"}, ""); err == nil || err.Error() != "usage: agent-manager "+usageRenameGroup {
t.Fatalf("rename-group without a name = %v, want the usage", err)
}
}

func TestSnapshotPrintsOnlyJSON(t *testing.T) {
fake := &fakeSessions{session: sampleSession()}
err := runSnapshot(&bytes.Buffer{}, fake, nil, "")
Expand Down
70 changes: 70 additions & 0 deletions internal/execution/poller_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,76 @@ func TestPendingRenameForADeletedSessionDoesNotFailThePoll(t *testing.T) {
}
}

// A group renamed by another writer after this pass listed the sessions,
// such as rename-group over SSH, is the group the renamed pane's label shows.
func TestPendingRenameLabelsThePaneWithTheGroupAsStoredNow(t *testing.T) {
m := buildModel(t)
createSession(t, m, "worker", t.TempDir(), "web")
sess := m.sessionRows()[0]
if err := m.store.RenameGroup("web", "api"); err != nil {
t.Fatalf("rename group: %v", err)
}
writeName(t, m, sess.ID, "renamed")

if err := m.poller.applyPendingRename(&sess); err != nil {
t.Fatalf("rename: %v", err)
}
out, err := exec.Command(tmux.Binary, "-L", m.tmux.SocketName(), "show-options", "-v", "-t", "am_"+sess.ID, "status-left").CombinedOutput()
if err != nil {
t.Fatalf("status-left: %v: %s", err, out)
}
if got := strings.TrimSpace(string(out)); got != sessioncmd.SessionLabel("api", "renamed") {
t.Fatalf("status-left = %q, want the group as stored now", got)
}
}

// A rename-session that landed after this pass listed the sessions moved
// the branch; the agent's own rename starts from the branch that one left.
func TestPendingRenameStartsFromTheBranchAsStoredNow(t *testing.T) {
m := buildModel(t)
spawned := createWorktreeSession(t, m, "first", seedRepo(t))
if _, err := sessioncmd.ApplyName(m.gitDrv, m.store, spawned.ID, "second"); err != nil {
t.Fatalf("rename meanwhile: %v", err)
}
writeName(t, m, spawned.ID, "third")

sess := spawned
if err := m.poller.applyPendingRename(&sess); err != nil {
t.Fatalf("rename: %v", err)
}
stored, err := m.store.Get(spawned.ID)
if err != nil || stored.Name != "third" || stored.WorktreeBranch != "am/third" || sess.WorktreeBranch != "am/third" {
t.Fatalf("stored %+v, pass copy branch %q (%v); want both on am/third", stored, sess.WorktreeBranch, err)
}
if head := gitOutput(t, spawned.Cwd, "rev-parse", "--abbrev-ref", "HEAD"); head != "am/third" {
t.Fatalf("HEAD = %q, want am/third", head)
}
}

// The agent asking for the name this pass read, after a rename-session gave
// the row another, still gets that name: the verdict says what is stored.
func TestPendingRenameToTheNameThePassReadStillApplies(t *testing.T) {
m := buildModel(t)
spawned := createWorktreeSession(t, m, "first", seedRepo(t))
if _, err := sessioncmd.ApplyName(m.gitDrv, m.store, spawned.ID, "second"); err != nil {
t.Fatalf("rename meanwhile: %v", err)
}
request := writeName(t, m, spawned.ID, "first")

sess := spawned
if err := m.poller.applyPendingRename(&sess); err != nil {
t.Fatalf("rename: %v", err)
}
stored, err := m.store.Get(spawned.ID)
if err != nil || stored.Name != "first" || stored.WorktreeBranch != "am/first" {
t.Fatalf("stored %+v (%v), want first on am/first", stored, err)
}
verdict, found, err := m.hooks.ReadNameResult(spawned.ID, request)
if err != nil || !found || verdict.Refusal != nil || verdict.Applied != "first" {
t.Fatalf("result = %+v, %v, %v; want first applied", verdict, found, err)
}
}

func TestPendingRenameKeepsTheWorktreeDirectory(t *testing.T) {
m := buildModel(t)
repo := seedRepo(t)
Expand Down
Loading
Loading