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
5 changes: 3 additions & 2 deletions docs/ssh-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The protocol is the remote host's own CLI, run over SSH as `agent-manager <comma
| 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` |
| Groups | `create-group`, `delete-group`, and `delete-group --with-sessions=<id,...>` for `d` on a 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,6 +38,7 @@ 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.
- `delete-group --with-sessions=<id,...>` deletes the group with every session in it, the way `d` does on that host, and runs only with no calling session. The ids are the sessions the confirm counted from the last snapshot, none for an empty group, and the host refuses when the sessions it now holds there are not exactly those. A host too old to know the flag refuses it, and the status line says to update agent-manager there.
- `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.
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.
- Rename, move, deleting a group in the archived view, restart and fork.
- Diff review.
- The editor.
- Copying a reply, marking idle, cancelling an after-turn end, reordering.
Expand Down
5 changes: 3 additions & 2 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -352,7 +352,7 @@ Registration is per tool. Claude gets a generated `--mcp-config` file. Codex get

Pi does not include an MCP client. Its sessions reach the same workspace through the subcommands: `agent-manager --help` lists them, from `sessions`, `spawn`, `send` and `wait` to the shared task list, file reservations, terminals and the review declarations. `update` and `settings` need no caller at all, and `issue` and `feature` use only the session id the launch exported. Every other subcommand acts as the session or [terminal tab](#terminal-tabs) whose pane started it, so the same subcommands work from a shell you opened with `T`. A Claude Code conversation the manager launched keeps acting as its session after `/background`, `/fork` or the agent view moves it into Claude's daemon, since its startup hook reports the conversation as the session's own. A Claude started by hand in a pane and moved there has no caller. A `spawn` from a terminal tab with no `--tool` runs the CLI picked in Settings. `move` also takes a `host::id` from one of your [SSH connections](#ssh-connections) and moves that session there, as `move_session` does.

`sessions`, `groups`, `snapshot`, `spawn`, `read`, `wait`, `kill`, `delete`, `revive`, `archive`, `move`, `create-group` and `delete-group` also run with no caller at all (a `move` of a `host::id` excepted, which needs one the way the MCP tools do), so a script, a cron job or a CI step outside Agent Manager can open sessions that show up in your list. Such a `spawn` runs the CLI picked in Settings, in the root group and the directory the script runs in, unless `--tool`, `--group` or `--directory` says otherwise:
`sessions`, `groups`, `snapshot`, `spawn`, `read`, `wait`, `kill`, `delete`, `revive`, `archive`, `move`, `create-group` and `delete-group` also run with no caller at all (a `move` of a `host::id` excepted, which needs one the way the MCP tools do, and `delete-group --with-sessions=<id,...>` runs only that way), so a script, a cron job or a CI step outside Agent Manager can open sessions that show up in your list. Such a `spawn` runs the CLI picked in Settings, in the root group and the directory the script runs in, unless `--tool`, `--group` or `--directory` says otherwise:

```bash
agent-manager spawn --tool claude --group "Sprint Manager" --worktree \
Expand Down Expand Up @@ -439,9 +439,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`.
- `d` on a group deletes it there with its subgroups and every session in them, archived ones and terminals included, the way it does here. It asks first with that machine's counts, and if the sessions there changed before you answer, the other machine refuses and nothing is deleted.
- 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.
Rename, move, deleting a group in the archived view, 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
2 changes: 1 addition & 1 deletion internal/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ func Help(version string, proactive bool) string {
if !proactive {
help.WriteString("Work with those other agents only when the user asks: on your own, do not list, message, spawn or wait on them, or create or claim shared tasks.\n")
}
help.WriteString("update and settings need no caller, and issue and feature use only the exported session id. Every other command acts as the session or terminal whose pane started it, so run them from your own shell, not from a daemon or a process that outlived its pane. The exception is a Claude conversation Agent Manager launched that /background, /fork or the agent view moved out of its pane: it still acts as the session that launched it, while one started by hand has no caller. sessions, groups, snapshot, spawn, read, wait, kill, delete, revive, archive, move, create-group and delete-group also run from a script outside Agent Manager (a move of a host::id excepted), where spawn defaults to the CLI picked in settings, the root group and the script's directory. So do send with --from <name>, whose message says no reply can reach the sender, and terminal create, send, read and close, which there open a terminal under no session and drive only terminals under none. type runs only there: it is the user's own quick bar prompt from another machine, so an agent never uses it.\n")
help.WriteString("update and settings need no caller, and issue and feature use only the exported session id. Every other command acts as the session or terminal whose pane started it, so run them from your own shell, not from a daemon or a process that outlived its pane. The exception is a Claude conversation Agent Manager launched that /background, /fork or the agent view moved out of its pane: it still acts as the session that launched it, while one started by hand has no caller. sessions, groups, snapshot, spawn, read, wait, kill, delete, revive, archive, move, create-group and delete-group also run from a script outside Agent Manager (a move of a host::id excepted, and delete-group --with-sessions runs only there), where spawn defaults to the CLI picked in settings, the root group and the script's directory. So do send with --from <name>, whose message says no reply can reach the sender, and terminal create, send, read and close, which there open a terminal under no session and drive only terminals under none. type runs only there: it is the user's own quick bar prompt from another machine, so an agent never uses it.\n")
for _, section := range sections(version, nil) {
help.WriteString("\n" + section.title + "\n")
help.WriteString(usageLines(section.commands))
Expand Down
7 changes: 7 additions & 0 deletions internal/cli/cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ type fakeSessions struct {
ttl time.Duration
deleted bool
notice string
confirmed []string

session sessioncmd.Session
wait sessioncmd.WaitResult
Expand Down Expand Up @@ -175,6 +176,11 @@ func (f *fakeSessions) DeleteGroup(sessionID, path string) (sessioncmd.GroupRemo
return sessioncmd.GroupRemoval{Removed: []string{path}, Moved: []string{"beef1234"}}, f.failWith
}

func (f *fakeSessions) DeleteGroupWithSessions(sessionID, path string, confirmed []string) (sessioncmd.GroupDeletion, error) {
f.callerID, f.groupPath, f.confirmed, f.deleted = sessionID, path, confirmed, true
return sessioncmd.GroupDeletion{Removed: []string{path, path + "/web"}, Deleted: confirmed, Notice: f.notice}, f.failWith
}

func (f *fakeSessions) Tasks(sessionID string) ([]sessioncmd.Task, error) {
f.callerID = sessionID
return []sessioncmd.Task{f.task}, f.failWith
Expand Down Expand Up @@ -306,6 +312,7 @@ func TestALayerFailureReachesTheCaller(t *testing.T) {
{"groups", nil, func(out io.Writer, args []string) error { return runGroups(out, sessions, args, "cafe0001") }},
{"create-group", []string{"api/web"}, func(out io.Writer, args []string) error { return runCreateGroup(out, sessions, args, "cafe0001") }},
{"delete-group", []string{"api/web"}, func(out io.Writer, args []string) error { return runDeleteGroup(out, sessions, args, "cafe0001") }},
{"delete-group --with-sessions", []string{"api/web", "--with-sessions=a1,b2"}, func(out io.Writer, args []string) error { return runDeleteGroup(out, sessions, args, "") }},
{"task list", nil, func(out io.Writer, args []string) error { return runTaskList(out, sessions, args, "cafe0001") }},
{"task create", []string{"ship the api"}, func(out io.Writer, args []string) error { return runTaskCreate(out, sessions, args, "cafe0001") }},
{"task claim", nil, func(out io.Writer, args []string) error { return runTaskClaim(out, sessions, args, "cafe0001") }},
Expand Down
22 changes: 20 additions & 2 deletions internal/cli/session.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import (
"io"
"path/filepath"
"strconv"
"strings"
"time"

"github.com/YoanWai/agent-manager/internal/remote"
Expand All @@ -33,7 +34,7 @@ const (
usageKillSelf = "kill-self [--cancel] [--json]"
usageGroups = "groups [--json]"
usageCreateGroup = "create-group <path> [--directory <path>] [--json]"
usageDeleteGroup = "delete-group <path> [--json]"
usageDeleteGroup = "delete-group <path> [--with-sessions=<id,...>] [--json]"
)

type sessionCommands interface {
Expand All @@ -58,6 +59,7 @@ type sessionCommands interface {
Groups(sessionID string) ([]sessioncmd.Group, error)
CreateGroup(sessionID, path, directory string) (sessioncmd.Group, error)
DeleteGroup(sessionID, path string) (sessioncmd.GroupRemoval, error)
DeleteGroupWithSessions(sessionID, path string, confirmed []string) (sessioncmd.GroupDeletion, error)
}

func newSessions(configDir string) sessionCommands {
Expand Down Expand Up @@ -117,7 +119,7 @@ func sessionSectionWith(open func(string) sessionCommands) section {
{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: "delete-group", usage: usageDeleteGroup, about: "remove a group whose work is done; sessions still in it move to the root rather than stopping, unless --with-sessions deletes them with it as the user's delete key does", run: bind(open, runDeleteGroup)},
},
}
}
Expand Down Expand Up @@ -465,11 +467,27 @@ func runCreateGroup(out io.Writer, sessions sessionCommands, args []string, sess

func runDeleteGroup(out io.Writer, sessions sessionCommands, args []string, sessionID string) error {
set := newFlagSet(usageDeleteGroup)
var withSessions bool
var confirmed []string
set.Func("with-sessions", "delete the sessions in the group too, as the delete key does; the ids are the ones the user confirmed, empty for none, and any other set there refuses", func(value string) error {
withSessions = true
if value != "" {
confirmed = strings.Split(value, ",")
}
return nil
})
asJSON := jsonFlag(set)
operands, err := parseCommand(out, set, args, 1, 1)
if err != nil {
return err
}
if withSessions {
deletion, err := sessions.DeleteGroupWithSessions(sessionID, operands[0], confirmed)
if err != nil {
return err
}
return emit(out, *asJSON, deletion, sessioncmd.FormatGroupDeletion(deletion))
}
removal, err := sessions.DeleteGroup(sessionID, operands[0])
if err != nil {
return err
Expand Down
27 changes: 27 additions & 0 deletions internal/cli/session_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,19 @@ func TestSessionCommandsParseArgumentsAndPrintSentences(t *testing.T) {
}
},
},
{
name: "delete-group --with-sessions deletes them with the group",
run: func(out *bytes.Buffer, f *fakeSessions, args []string) error {
return runDeleteGroup(out, f, args, "")
},
args: []string{"fleet", "--with-sessions=a1,b2,c3"},
want: "deleted fleet, fleet/web and the 3 session(s) in them",
inspect: func(t *testing.T, f *fakeSessions) {
if !f.deleted || f.groupPath != "fleet" || !slices.Equal(f.confirmed, []string{"a1", "b2", "c3"}) {
t.Fatalf("delete-group --with-sessions got %q with %q, deleting %v", f.groupPath, f.confirmed, f.deleted)
}
},
},
{
name: "create-group takes a path and a directory",
run: func(out *bytes.Buffer, f *fakeSessions, args []string) error {
Expand Down Expand Up @@ -251,6 +264,20 @@ func TestSessionCommandsParseArgumentsAndPrintSentences(t *testing.T) {
}
}

// The flag itself opts in, so an empty value is a group the user confirmed
// holding nothing, not a plain delete-group that moves sessions to the root.
func TestDeleteGroupWithSessionsTakesTheConfirmedIDs(t *testing.T) {
fake := &fakeSessions{}
if err := runDeleteGroup(&bytes.Buffer{}, fake, []string{"fleet", "--with-sessions="}, ""); err != nil || !fake.deleted || len(fake.confirmed) != 0 {
t.Fatalf("--with-sessions= = %v, deleting %v with %q", err, fake.deleted, fake.confirmed)
}
fake = &fakeSessions{}
var out bytes.Buffer
if err := runDeleteGroup(&out, fake, []string{"fleet"}, ""); err != nil || fake.deleted || !strings.Contains(out.String(), "moved") {
t.Fatalf("delete-group without the flag = %v, deleting %v, printing %q", err, fake.deleted, out.String())
}
}

// A delete that kept a shared worktree says so on its own line, and --json
// carries the same notice for a script to read.
func TestDeletePrintsTheNoticeAndTheRecord(t *testing.T) {
Expand Down
21 changes: 21 additions & 0 deletions internal/remote/operations.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"errors"
"fmt"
"strconv"
"strings"

"github.com/YoanWai/agent-manager/internal/sessioncmd"
)
Expand Down Expand Up @@ -285,6 +286,26 @@ func (c *Client) DeleteGroup(ctx context.Context, host, path string) (sessioncmd
return cleanRemoval(removal), err
}

// DeleteGroupWithSessions deletes the group on its host with every session
// filed in it, the way the delete key does there. confirmed holds the ids of
// the sessions the user was asked about, and the host refuses when it holds
// another set.
func (c *Client) DeleteGroupWithSessions(ctx context.Context, host, path string, confirmed []string) (sessioncmd.GroupDeletion, error) {
for _, id := range confirmed {
if err := validID(id); err != nil {
return sessioncmd.GroupDeletion{}, &Error{Host: host, Err: err}
}
}
var deletion sessioncmd.GroupDeletion
// --json goes first: a host that predates --with-sessions then names the
// flag it does not know, which is the answer reworded below.
err := c.decode(ctx, host, callTimeout, &deletion, "delete-group", "--json", "--with-sessions="+strings.Join(confirmed, ","), "--", path)
if err != nil && strings.Contains(err.Error(), "flag provided but not defined: -with-sessions") {
return deletion, &Error{Host: host, Err: errors.New("agent-manager there is too old to delete a group with its sessions; update agent-manager on that host")}
}
return cleanDeletion(deletion), err
}

func validRef(ref Ref) error {
if err := validID(ref.ID); err != nil {
return &Error{Host: ref.Host, Err: err}
Expand Down
Loading
Loading