pi-herdsman 0.13.2 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -17
- package/docs/README.md +32 -25
- package/docs/getting-started.md +3 -0
- package/docs/guides/container-deployment.md +178 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -7,15 +7,21 @@
|
|
|
7
7
|
[](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
**Asynchronous [Pi](https://github.com/earendil-works/pi) subagents and agent fleet orchestration with nested delegation,
|
|
10
|
+
**Asynchronous [Pi](https://github.com/earendil-works/pi) subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in [herdr](https://github.com/herdrdev/herdr).**
|
|
11
11
|
|
|
12
12
|
Keep the conversation. Delegate the work.
|
|
13
13
|
|
|
14
|
-
Pi Herdsman is a Pi extension for asynchronous subagents
|
|
15
|
-
tasks to managed background agents running in
|
|
16
|
-
the lead conversation stays interactive. Run
|
|
17
|
-
delegation, steer active agents, route
|
|
18
|
-
owning agent, and supervise multiple leads
|
|
14
|
+
Pi Herdsman is a Pi extension for asynchronous subagents and multi-agent
|
|
15
|
+
coding. Delegate coding tasks to managed background agents running in
|
|
16
|
+
independent Pi sessions while the lead conversation stays interactive. Run
|
|
17
|
+
coding agents in parallel, nest delegation, steer active agents, route
|
|
18
|
+
questions and results back to their owning agent, and supervise multiple leads
|
|
19
|
+
through one coordinated hierarchy.
|
|
20
|
+
|
|
21
|
+
Use it in an existing Pi/herdr setup or deploy the SSH-ready container as a
|
|
22
|
+
portable remote coding-agent environment. [herdr Machines](https://herdr.dev/docs/connecting-machines/)
|
|
23
|
+
can bring local and remote workspaces and agents into one herdr window over
|
|
24
|
+
normal SSH.
|
|
19
25
|
|
|
20
26
|
Pi Herdsman calls its managed subagents **agents**.
|
|
21
27
|
|
|
@@ -34,22 +40,14 @@ agents, and a delegation-enabled agent may own permitted agents of its own.
|
|
|
34
40
|
Agent definitions, models, tools, extensions, and development process remain up
|
|
35
41
|
to you.
|
|
36
42
|
|
|
37
|
-
Chief supervision is separate from ownership:
|
|
38
|
-
|
|
39
|
-
```text
|
|
40
|
-
chief
|
|
41
|
-
├─ herd A / lead A
|
|
42
|
-
│ └─ agents...
|
|
43
|
-
└─ herd B / lead B
|
|
44
|
-
└─ agents...
|
|
45
|
-
```
|
|
46
|
-
|
|
47
43
|
## Demo
|
|
48
44
|
|
|
49
45
|
|
|
50
46
|
|
|
51
47
|
## Install
|
|
52
48
|
|
|
49
|
+
### Existing Pi / herdr
|
|
50
|
+
|
|
53
51
|
```sh
|
|
54
52
|
pi install npm:pi-herdsman
|
|
55
53
|
herdr integration install pi
|
|
@@ -67,6 +65,22 @@ Then run Pi in the Herdr pane:
|
|
|
67
65
|
pi
|
|
68
66
|
```
|
|
69
67
|
|
|
68
|
+
### Docker / remote machine
|
|
69
|
+
|
|
70
|
+
For a self-contained, SSH-ready remote coding-agent environment, see
|
|
71
|
+
[Container deployment](docs/guides/container-deployment.md).
|
|
72
|
+
|
|
73
|
+
Once normal SSH access works, the same container can be saved as a herdr
|
|
74
|
+
machine:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
herdr machine add ssh://herdsman@host:2222 --label my-herd
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
A host defined in normal SSH configuration can be used directly instead.
|
|
81
|
+
|
|
82
|
+
## Try it
|
|
83
|
+
|
|
70
84
|
Ask Pi normally:
|
|
71
85
|
|
|
72
86
|
```text
|
|
@@ -97,6 +111,16 @@ To supervise independent leads across the current herdr runtime, use:
|
|
|
97
111
|
/chief
|
|
98
112
|
```
|
|
99
113
|
|
|
114
|
+
Chief supervision is separate from ownership:
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
chief
|
|
118
|
+
├─ herd A / lead A
|
|
119
|
+
│ └─ agents...
|
|
120
|
+
└─ herd B / lead B
|
|
121
|
+
└─ agents...
|
|
122
|
+
```
|
|
123
|
+
|
|
100
124
|
Leave chief mode with:
|
|
101
125
|
|
|
102
126
|
```text
|
|
@@ -158,7 +182,8 @@ tools, extensions, skills, and instructions.
|
|
|
158
182
|
- Pi `>=0.87.0 <0.88.0` (supported)
|
|
159
183
|
- Node `>=22.19.0`
|
|
160
184
|
|
|
161
|
-
CI validates Node 22.19.0
|
|
185
|
+
Package CI validates the minimum supported Node 22.19.0 runtime. The container
|
|
186
|
+
separately ships and validates Node 26.
|
|
162
187
|
|
|
163
188
|
Install or refresh the herdr Pi integration:
|
|
164
189
|
|
package/docs/README.md
CHANGED
|
@@ -33,6 +33,12 @@ Continue with:
|
|
|
33
33
|
- [Agent-definition schema](reference/agent-definition-schema.md)
|
|
34
34
|
- [Recovery](guides/recovery.md)
|
|
35
35
|
|
|
36
|
+
### Deploy Pi Herdsman in a container
|
|
37
|
+
|
|
38
|
+
Use the canonical [container deployment guide](guides/container-deployment.md)
|
|
39
|
+
for the SSH-ready Docker image, persistent state, updates, and optional
|
|
40
|
+
Tailscale networking.
|
|
41
|
+
|
|
36
42
|
### Coordinate through agent APIs
|
|
37
43
|
|
|
38
44
|
Start with [Agent coordination API](agent-api.md).
|
|
@@ -71,31 +77,32 @@ before choosing the material relevant to them.
|
|
|
71
77
|
|
|
72
78
|
## Canonical ownership
|
|
73
79
|
|
|
74
|
-
| Subject | Canonical page
|
|
75
|
-
| ------------------------------------- |
|
|
76
|
-
| Human UI first use | [Getting started](getting-started.md)
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
| `
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
80
|
+
| Subject | Canonical page |
|
|
81
|
+
| ------------------------------------- | ------------------------------------------------------------------------------- |
|
|
82
|
+
| Human UI first use | [Getting started](getting-started.md) |
|
|
83
|
+
| Container deployment | [Container deployment](guides/container-deployment.md) |
|
|
84
|
+
| Agent/API first use | [Agent coordination API](agent-api.md) |
|
|
85
|
+
| Asynchronous orchestration | [Lifecycle](concepts/lifecycle.md) |
|
|
86
|
+
| Agent identity | [Agents and identity](concepts/agents.md) |
|
|
87
|
+
| State transitions | [Lifecycle](concepts/lifecycle.md) |
|
|
88
|
+
| Delegation model | [Delegation](concepts/delegation.md) |
|
|
89
|
+
| Creating definitions | [Agent definitions](guides/agent-definitions.md) |
|
|
90
|
+
| Overrides and prompt composition | [Customizing bundled agents](guides/customizing-agents.md) |
|
|
91
|
+
| `files`, body references, and results | [Handoffs and files](guides/handoffs.md) |
|
|
92
|
+
| Operator recovery | [Recovery](guides/recovery.md) |
|
|
93
|
+
| `agent` request contract | [`agent` API](reference/agent.md) |
|
|
94
|
+
| `ask_owner` contract | [`ask_owner` API](reference/ask-owner.md) |
|
|
95
|
+
| Pi Herdsman supervision concept | [Supervision](concepts/supervision.md) |
|
|
96
|
+
| Chief and staff tools | [Supervision reference](reference/supervision.md) |
|
|
97
|
+
| Frontmatter fields | [Agent-definition schema](reference/agent-definition-schema.md) |
|
|
98
|
+
| Public agent states | [Agent states](reference/agent-states.md) |
|
|
99
|
+
| `/agents` human commands | [`/agents` commands](reference/commands.md) |
|
|
100
|
+
| Settings | [Configuration](reference/configuration.md) |
|
|
101
|
+
| TUI agent widget | [Status widget](reference/status-widget.md) |
|
|
102
|
+
| Error categories | [Errors](reference/errors.md) |
|
|
103
|
+
| Repository checks | [Validation](development/validation.md) |
|
|
104
|
+
| Live acceptance | [Smoke testing](development/smoke-testing.md) |
|
|
105
|
+
| Instruction and interface design | [Instruction and interface design](development/instruction-interface-design.md) |
|
|
99
106
|
|
|
100
107
|
When another page needs one of these subjects, it summarizes only enough to
|
|
101
108
|
establish context and links to the canonical page instead of restating the full
|
package/docs/getting-started.md
CHANGED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Container deployment
|
|
2
|
+
|
|
3
|
+
[Documentation index](../README.md)
|
|
4
|
+
|
|
5
|
+
The Pi Herdsman container is a portable, self-hosted execution environment for
|
|
6
|
+
coding agents. It packages Pi, herdr, Pi Herdsman, developer tooling, and
|
|
7
|
+
OpenSSH while keeping mutable user state under `/home/herdsman`.
|
|
8
|
+
|
|
9
|
+
Use it locally or as a remote coding-agent machine. OpenSSH is the access
|
|
10
|
+
boundary; connect with your own SSH key and use Pi and herdr normally.
|
|
11
|
+
|
|
12
|
+
Pi sessions automatically receive image-owned environment context from
|
|
13
|
+
`/AGENTS.md`, including persistence boundaries, available tool categories, and
|
|
14
|
+
how to install additional tools. User and project context files continue to
|
|
15
|
+
layer normally through Pi's native context-file discovery.
|
|
16
|
+
|
|
17
|
+
## Direct SSH
|
|
18
|
+
|
|
19
|
+
Start the service with a public key authorized for the `herdsman` account:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Connect to the host's configured SSH port (2222 by default):
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
ssh -p 2222 herdsman@host
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Start or attach to a Herdr session with:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
herdr
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
SSH password authentication and root login are disabled. On first start,
|
|
38
|
+
`SSH_AUTHORIZED_KEYS` is required to initialize the account's authorized keys.
|
|
39
|
+
The keys are saved in the persistent home volume; changing the environment
|
|
40
|
+
variable later does not replace an existing authorized-keys file. SSH agent
|
|
41
|
+
forwarding remains available, so `ssh -A` can be used when a session needs
|
|
42
|
+
access to private Git repositories without copying private keys into the
|
|
43
|
+
container.
|
|
44
|
+
|
|
45
|
+
## Herdr Machines
|
|
46
|
+
|
|
47
|
+
After normal SSH access works, save the container as a herdr machine from the
|
|
48
|
+
computer running your local herdr client:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
herdr machine add ssh://herdsman@host:2222 --label my-herd
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
For a host already configured in `~/.ssh/config`:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
herdr machine add my-herd --label my-herd
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Each machine keeps its own herdr server, sessions, and running processes.
|
|
61
|
+
Connected machine workspaces and agents appear alongside Local in the same
|
|
62
|
+
herdr window, and disconnecting the client does not stop the remote work.
|
|
63
|
+
|
|
64
|
+
See the [herdr machine documentation](https://herdr.dev/docs/connecting-machines/)
|
|
65
|
+
for machine management and SSH configuration.
|
|
66
|
+
|
|
67
|
+
## Updates
|
|
68
|
+
|
|
69
|
+
Pull the current image and recreate the service:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
docker compose pull
|
|
73
|
+
docker compose up -d
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The container replaces immutable software while the named volumes preserve
|
|
77
|
+
`/home/herdsman` and the SSH host identity.
|
|
78
|
+
|
|
79
|
+
## Persistent state
|
|
80
|
+
|
|
81
|
+
The default Compose setup persists two volumes:
|
|
82
|
+
|
|
83
|
+
- `/home/herdsman` contains Pi authentication, configuration, sessions and
|
|
84
|
+
extensions; Herdr configuration, sessions and worktrees; mise-installed
|
|
85
|
+
tools; npm globals; Git, GitHub and user SSH state; and repositories.
|
|
86
|
+
- `/var/lib/herdsman/ssh` contains the SSH server host key, preserving server
|
|
87
|
+
identity when the container is replaced.
|
|
88
|
+
|
|
89
|
+
The image uses its built-in `herdsman` UID and GID by default. For Linux or NAS
|
|
90
|
+
bind mounts owned by a different host account, set `PUID` and `PGID` to the
|
|
91
|
+
directory owner's numeric IDs:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
PUID="$(id -u docker-user)" \
|
|
95
|
+
PGID="$(id -g docker-user)" \
|
|
96
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
|
|
97
|
+
docker compose up -d
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
You can also set `PUID` and `PGID` in the Compose `.env` file:
|
|
101
|
+
|
|
102
|
+
```dotenv
|
|
103
|
+
PUID=1035
|
|
104
|
+
PGID=65537
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The container remaps the `herdsman` account but does not change ownership of
|
|
108
|
+
the mounted home. Prepare the host directory so the configured IDs can write
|
|
109
|
+
it. Existing volumes are not migrated automatically; startup fails if
|
|
110
|
+
`/home/herdsman` is not writable by the resulting account. Repositories can
|
|
111
|
+
live under the persistent home, for example `~/projects`. Host checkouts can
|
|
112
|
+
be mounted explicitly when needed.
|
|
113
|
+
|
|
114
|
+
## Additional tools
|
|
115
|
+
|
|
116
|
+
Install tools into the persistent home with mise:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
mise use -g uv@latest
|
|
120
|
+
uv run ...
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Mise shims and user-installed tools are available in SSH sessions, including
|
|
124
|
+
non-interactive commands.
|
|
125
|
+
|
|
126
|
+
## Tailscale
|
|
127
|
+
|
|
128
|
+
Tailscale is an optional Compose sidecar. It shares the service network
|
|
129
|
+
namespace; it does not run in the Herdsman container. Start both services with:
|
|
130
|
+
|
|
131
|
+
```sh
|
|
132
|
+
TS_AUTHKEY=... \
|
|
133
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" \
|
|
134
|
+
docker compose \
|
|
135
|
+
-f compose.yaml \
|
|
136
|
+
-f compose.tailscale.yaml \
|
|
137
|
+
up -d
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Connect over the Tailscale hostname using normal OpenSSH:
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
ssh herdsman@pi-herdsman
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Set `TAILSCALE_HOSTNAME` if a different hostname is desired. The overlay uses
|
|
147
|
+
Tailscale networking, not Tailscale SSH.
|
|
148
|
+
|
|
149
|
+
## Interactive sessions
|
|
150
|
+
|
|
151
|
+
Interactive SSH logins automatically open Herdr. This also applies when SSH is
|
|
152
|
+
reached through the optional Tailscale sidecar.
|
|
153
|
+
|
|
154
|
+
Exit Herdr to return to the normal shell.
|
|
155
|
+
|
|
156
|
+
For interactive Docker access as the normal container user, run:
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
docker exec -it --user herdsman <container> bash
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
or with Compose:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
docker compose exec --user herdsman herdsman bash
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Bare `docker exec` uses the container's root user and is intended for
|
|
169
|
+
administrative debugging; it does not automatically open Herdr.
|
|
170
|
+
|
|
171
|
+
Non-interactive SSH commands are unaffected.
|
|
172
|
+
|
|
173
|
+
## Container restart behavior
|
|
174
|
+
|
|
175
|
+
Herdr detach and reattach keep processes alive while the container itself
|
|
176
|
+
remains alive. Replacing or restarting the Docker container kills its
|
|
177
|
+
processes. Herdr can restore layout and supported Pi conversations, but
|
|
178
|
+
arbitrary processes do not survive a container restart.
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-herdsman",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "Asynchronous Pi subagents and agent fleet orchestration with nested delegation,
|
|
5
|
+
"description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
|
@@ -22,10 +22,12 @@
|
|
|
22
22
|
"agents",
|
|
23
23
|
"ai-agents",
|
|
24
24
|
"coding-agents",
|
|
25
|
+
"coding-agent-orchestration",
|
|
25
26
|
"multi-agent",
|
|
26
27
|
"multi-agent-coding",
|
|
27
28
|
"agent-fleet",
|
|
28
29
|
"parallel-agents",
|
|
30
|
+
"parallel-coding-agents",
|
|
29
31
|
"background-agents",
|
|
30
32
|
"nested-agents",
|
|
31
33
|
"agent-orchestration",
|