pi-herdsman 0.45.0 → 0.46.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/CHANGELOG.md +40 -0
- package/README.md +64 -104
- package/dist/index.js +1144 -399
- package/dist/index.js.map +4 -4
- package/docs/concepts/coordination.md +20 -0
- package/docs/development/smoke-testing.md +20 -0
- package/docs/development/validation.md +19 -16
- package/docs/getting-started.md +1 -1
- package/docs/guides/container-deployment.md +34 -1
- package/docs/guides/customizing-agents.md +25 -38
- package/docs/reference/agent-definition-schema.md +27 -2
- package/docs/reference/agent.md +38 -27
- package/docs/reference/commands.md +26 -0
- package/package.json +7 -12
- package/skills/agent-definitions/SKILL.md +7 -3
- package/dist/integrations/pi-codex-context-sharing.js +0 -42
- package/dist/integrations/pi-codex-context-sharing.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.46.0](https://github.com/boadij/pi-herdsman/compare/v0.45.0...v0.46.0) (2026-11-13)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* **agents:** extend generic bootstrap and remove PCC integration ([#951](https://github.com/boadij/pi-herdsman/issues/951)) ([da8ade3](https://github.com/boadij/pi-herdsman/commit/da8ade376656599e7186cb38b8a6ab2db0855364)), closes [#637](https://github.com/boadij/pi-herdsman/issues/637)
|
|
9
|
+
* **config:** support array modifiers in definition overlays ([#941](https://github.com/boadij/pi-herdsman/issues/941)) ([53b5df9](https://github.com/boadij/pi-herdsman/commit/53b5df946216c5c2d793cd03c399d3758dcf648e))
|
|
10
|
+
* **container:** support persistent native Pi self-updates ([#945](https://github.com/boadij/pi-herdsman/issues/945)) ([c95877a](https://github.com/boadij/pi-herdsman/commit/c95877a5a02cb81d7820c502bdd6188409bb37de))
|
|
11
|
+
* **dev:** add one-command setup for worktree hooks ([#947](https://github.com/boadij/pi-herdsman/issues/947)) ([6af00b4](https://github.com/boadij/pi-herdsman/commit/6af00b4b7ecd20a0f1d157768d34b6c9e8ffdd51))
|
|
12
|
+
* **ui:** inspect effective instruction composition in Details ([#946](https://github.com/boadij/pi-herdsman/issues/946)) ([ec84045](https://github.com/boadij/pi-herdsman/commit/ec840458c57c09b4469f54f4f1cf89ef8636ad73)), closes [#942](https://github.com/boadij/pi-herdsman/issues/942)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
### Fixes
|
|
16
|
+
|
|
17
|
+
* **dev:** repair hook setup in copied repositories ([#957](https://github.com/boadij/pi-herdsman/issues/957)) ([9bf4466](https://github.com/boadij/pi-herdsman/commit/9bf4466d8782dcc819f4973e462f6d74ced0f60b))
|
|
18
|
+
* **ui:** present effective instructions as sequential Markdown sections ([#956](https://github.com/boadij/pi-herdsman/issues/956)) ([0519349](https://github.com/boadij/pi-herdsman/commit/0519349e4998bed90cfc2e6435f22c16bf26a82a))
|
|
19
|
+
* **ui:** restore chat scrolling for effective instruction details ([#953](https://github.com/boadij/pi-herdsman/issues/953)) ([556e9c2](https://github.com/boadij/pi-herdsman/commit/556e9c2df47f82963d56f10315e16c790ad7e961))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Documentation
|
|
23
|
+
|
|
24
|
+
* introduce emergent agentic workflows ([#959](https://github.com/boadij/pi-herdsman/issues/959)) ([9d1b078](https://github.com/boadij/pi-herdsman/commit/9d1b078a29604ac04f59d28214865a914d97b701))
|
|
25
|
+
* refresh community contributor acknowledgments ([#964](https://github.com/boadij/pi-herdsman/issues/964)) ([8e9f371](https://github.com/boadij/pi-herdsman/commit/8e9f3713543452399924b1125c6462b1a4a86927))
|
|
26
|
+
* streamline README onboarding and mobile layout ([#960](https://github.com/boadij/pi-herdsman/issues/960)) ([278d5d2](https://github.com/boadij/pi-herdsman/commit/278d5d2ba6fe82b0e156952a4fd4c6f382168d80))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Tests
|
|
30
|
+
|
|
31
|
+
* **ci:** require minimal ordinary Lead federation acceptance ([#954](https://github.com/boadij/pi-herdsman/issues/954)) ([35418b4](https://github.com/boadij/pi-herdsman/commit/35418b452731f8433bb4dbc92a5ad2e618ce4d06))
|
|
32
|
+
* **ci:** use minimal Manager federation acceptance ([#948](https://github.com/boadij/pi-herdsman/issues/948)) ([57c5a4f](https://github.com/boadij/pi-herdsman/commit/57c5a4f6f304df2aec791c144f8a1dae7b190774)), closes [#588](https://github.com/boadij/pi-herdsman/issues/588)
|
|
33
|
+
* **ci:** verify Manager activation through live authority ([#962](https://github.com/boadij/pi-herdsman/issues/962)) ([534aea1](https://github.com/boadij/pi-herdsman/commit/534aea13bde5d27c2241da91d3baa4682ec031e0)), closes [#934](https://github.com/boadij/pi-herdsman/issues/934)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Other Changes
|
|
37
|
+
|
|
38
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.8 ([#958](https://github.com/boadij/pi-herdsman/issues/958)) ([17e680b](https://github.com/boadij/pi-herdsman/commit/17e680b175a6449d8b1d8a3976279a370b0b33dc))
|
|
39
|
+
* **deps:** update npm non-major updates ([#935](https://github.com/boadij/pi-herdsman/issues/935)) ([6193198](https://github.com/boadij/pi-herdsman/commit/6193198849f37049e9038dc6bbe159ef10ed5aed))
|
|
40
|
+
* **deps:** update tailscale/tailscale docker tag to v1.104.7 ([#949](https://github.com/boadij/pi-herdsman/issues/949)) ([f6e8ff9](https://github.com/boadij/pi-herdsman/commit/f6e8ff953acc993dde4945fb08d3e5042868068b))
|
|
41
|
+
* **types:** enforce strict checking across all TypeScript sources ([#961](https://github.com/boadij/pi-herdsman/issues/961)) ([1955406](https://github.com/boadij/pi-herdsman/commit/1955406254edc2f0b8b6158fb75c2afd3c1e22ee))
|
|
42
|
+
|
|
3
43
|
## [0.45.0](https://github.com/boadij/pi-herdsman/compare/v0.44.0...v0.45.0) (2026-11-12)
|
|
4
44
|
|
|
5
45
|
|
package/README.md
CHANGED
|
@@ -9,12 +9,25 @@
|
|
|
9
9
|
|
|
10
10
|
**The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
|
|
11
11
|
|
|
12
|
-
Pi Herdsman lets your AI coding assistant delegate
|
|
13
|
-
while your
|
|
14
|
-
|
|
12
|
+
Pi Herdsman lets your AI coding assistant delegate work to background Agents
|
|
13
|
+
while your conversation stays interactive, or coordinate larger projects across
|
|
14
|
+
independent, branch-based Leads. Pi handles model conversations, herdr manages
|
|
15
|
+
terminal sessions and workspaces, and Herdsman coordinates delegation,
|
|
16
|
+
ownership, and supervision.
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
## Emergent agentic workflows
|
|
19
|
+
|
|
20
|
+
**Define the boundaries, not the workflow.**
|
|
21
|
+
|
|
22
|
+
Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models
|
|
23
|
+
decide how to split work, delegate to permitted Agents or Leads, and sequence or
|
|
24
|
+
parallelize tasks as results arrive. The execution path emerges at runtime,
|
|
25
|
+
while Herdsman enforces delegation permissions, ownership, project assignments,
|
|
26
|
+
and supervision.
|
|
27
|
+
|
|
28
|
+
You can still bring your own workflow and Agent definitions. See
|
|
29
|
+
[Coordination](docs/concepts/coordination.md#emergent-workflows-explicit-boundaries)
|
|
30
|
+
for the underlying model.
|
|
18
31
|
|
|
19
32
|
## Demo
|
|
20
33
|
|
|
@@ -22,16 +35,6 @@ _Advanced orchestration: a live Manager → Lead → Agent workflow._
|
|
|
22
35
|
|
|
23
36
|
[](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
|
|
24
37
|
|
|
25
|
-
## What Pi Herdsman gives you
|
|
26
|
-
|
|
27
|
-
- **Background Agents.** Delegate bounded work without blocking the Lead conversation.
|
|
28
|
-
- **Parallel and nested delegation.** Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
|
|
29
|
-
- **Project orchestration.** A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
|
|
30
|
-
- **Direct supervision.** Chief, Manager, Lead, and Agent responsibilities stay explicit instead of collapsing into one global controller.
|
|
31
|
-
- **Peer communication.** Leads can message eligible peers locally; unassigned ordinary Leads and Managers can also collaborate across connected machines.
|
|
32
|
-
- **Owned usage visibility.** Inspect Pi-native token usage and cost for the current session and its transitively owned managed Agents. An active Manager also sees the Leads in its current durable project assignments and their owned Agent trees.
|
|
33
|
-
- **Your workflow stays yours.** Bring your own Agent definitions, models, tools, skills, extensions, and development process.
|
|
34
|
-
|
|
35
38
|
## Quick start
|
|
36
39
|
|
|
37
40
|
**Linux/macOS:**
|
|
@@ -46,57 +49,39 @@ curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh
|
|
|
46
49
|
irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
|
|
47
50
|
```
|
|
48
51
|
|
|
49
|
-
**Already using Pi and
|
|
52
|
+
**Already using Pi and herdr?**
|
|
50
53
|
|
|
51
54
|
```sh
|
|
52
55
|
pi install npm:pi-herdsman
|
|
53
56
|
herdr integration install pi
|
|
54
57
|
```
|
|
55
58
|
|
|
56
|
-
|
|
57
|
-
SSH public key.
|
|
58
|
-
|
|
59
|
-
```sh
|
|
60
|
-
mkdir -p pi-herdsman && cd pi-herdsman
|
|
61
|
-
curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.yaml
|
|
62
|
-
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
63
|
-
ssh -p 2222 herdsman@localhost
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
The included [Compose file](compose.yaml) uses a prebuilt image and persistent
|
|
67
|
-
Docker volumes. Herdr opens on SSH login; select a workspace and run `pi`.
|
|
68
|
-
Replace `localhost` with the Docker host address for remote access. SSH port
|
|
69
|
-
2222 is published on host interfaces by default; see
|
|
70
|
-
[Container deployment](docs/guides/container-deployment.md) for networking,
|
|
71
|
-
storage, and update options.
|
|
72
|
-
|
|
73
|
-
For a native installation, start herdr in your project directory, then Pi in its pane:
|
|
74
|
-
|
|
75
|
-
```sh
|
|
76
|
-
herdr
|
|
77
|
-
pi
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
If Pi needs model authentication, use `/login`. Then try a read-only first task:
|
|
59
|
+
Start `herdr` in your project directory, then run `pi` in its pane. Try:
|
|
81
60
|
|
|
82
61
|
```text
|
|
83
62
|
Use scout to identify this repository's main entry points.
|
|
84
|
-
Explain how the application starts.
|
|
63
|
+
Explain how the application starts.
|
|
85
64
|
```
|
|
86
65
|
|
|
87
|
-
The Agent works
|
|
88
|
-
|
|
66
|
+
The Agent works asynchronously and returns its result to your Pi conversation.
|
|
67
|
+
Use `/herdsman` to discover controls. See [Getting started](docs/getting-started.md)
|
|
68
|
+
for prerequisites, model login, and troubleshooting, or
|
|
69
|
+
[Container deployment](docs/guides/container-deployment.md) for Docker Compose.
|
|
89
70
|
|
|
90
|
-
|
|
91
|
-
/herdsman
|
|
92
|
-
```
|
|
71
|
+
## What Pi Herdsman gives you
|
|
93
72
|
|
|
94
|
-
|
|
95
|
-
|
|
73
|
+
- **Background Agents.** Delegate bounded work without blocking your conversation.
|
|
74
|
+
- **Parallel and nested delegation.** Run independent work concurrently; permitted Agents can delegate their own subtasks.
|
|
75
|
+
- **Project orchestration.** A Manager coordinates durable, branch-based work across independent Leads.
|
|
76
|
+
- **Explicit authority.** Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
|
|
77
|
+
- **Peer communication.** Eligible sessions can exchange messages locally and, where supported, across connected machines.
|
|
78
|
+
- **Usage visibility.** Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
|
|
79
|
+
- **Your tools, your workflow.** Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.
|
|
96
80
|
|
|
97
81
|
## From one Agent to a project
|
|
98
82
|
|
|
99
|
-
A normal Pi session is a **Lead**. It
|
|
83
|
+
A normal Pi session is a **Lead**. It can own Agents, including permitted
|
|
84
|
+
nested Agents:
|
|
100
85
|
|
|
101
86
|
```text
|
|
102
87
|
You ↔ Lead
|
|
@@ -106,7 +91,8 @@ You ↔ Lead
|
|
|
106
91
|
```
|
|
107
92
|
|
|
108
93
|
For independent project work, an eligible Lead can enter **Manager** mode.
|
|
109
|
-
|
|
94
|
+
The Manager assigns branch-based objectives to Leads, which direct their own
|
|
95
|
+
Agent trees:
|
|
110
96
|
|
|
111
97
|
```text
|
|
112
98
|
You ↔ Manager
|
|
@@ -114,70 +100,44 @@ You ↔ Manager
|
|
|
114
100
|
└─ Lead → Agents
|
|
115
101
|
```
|
|
116
102
|
|
|
117
|
-
|
|
118
|
-
active Manager
|
|
119
|
-
|
|
120
|
-
The important boundaries are:
|
|
121
|
-
|
|
122
|
-
```text
|
|
123
|
-
supervision: Chief → Manager → Lead
|
|
124
|
-
ownership: Lead → Agent → Agent
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Project work is durable by Git branch. It does not belong to the Manager session
|
|
128
|
-
that happened to start it, so assignments can be paused, resumed, or retired
|
|
129
|
-
across Manager turnover.
|
|
130
|
-
|
|
131
|
-
Manager-created project Leads are dedicated Managed Lead sessions: identity stays
|
|
132
|
-
with the exact Pi session, while only a current project assignment authorizes
|
|
133
|
-
execution. Unavailable or retired assignments never enable ordinary Lead tools.
|
|
134
|
-
Use native Pi `/fork` or `/clone` for independent ordinary continuation with copied
|
|
135
|
-
history, not a separate checkout or fresh process configuration. See
|
|
136
|
-
[Project orchestration](docs/guides/project-orchestration.md#dedicated-sessions-and-independent-continuation).
|
|
103
|
+
An optional **Chief** supervises Managers and eligible ordinary Leads without
|
|
104
|
+
an active project Manager. These roles define authority, not a mandatory task
|
|
105
|
+
sequence. Project assignments remain durable across Manager turnover.
|
|
137
106
|
|
|
138
|
-
See [Coordination](docs/concepts/coordination.md) for
|
|
139
|
-
[Project orchestration](docs/guides/project-orchestration.md) for
|
|
140
|
-
|
|
107
|
+
See [Coordination](docs/concepts/coordination.md) for role boundaries and
|
|
108
|
+
[Project orchestration](docs/guides/project-orchestration.md) for assignments,
|
|
109
|
+
recovery, and integration.
|
|
141
110
|
|
|
142
111
|
## Project status & roadmap
|
|
143
112
|
|
|
144
|
-
Pi Herdsman is
|
|
145
|
-
while other areas are being refined or expanded.
|
|
113
|
+
Pi Herdsman is pre-1.0. These capabilities are available today:
|
|
146
114
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
| **Chief coordination** | 🚧 **In progress** | Supervision is available. Repository provisioning and Manager lifecycle orchestration are being developed. |
|
|
152
|
-
| **Federated peer communication** | 🚧 **In progress** | Cross-machine Manager/ordinary Lead messaging and durable replies work. Reverse initiation is planned. |
|
|
115
|
+
- **Lead & Agent orchestration.** Background and nested delegation, result handoffs, and local peer communication.
|
|
116
|
+
- **Manager orchestration.** Branch-based work assignments, supervision, pause/resume, and authorized local integration.
|
|
117
|
+
- **Chief supervision.** Supervises current Managers and eligible ordinary Leads within one herdr runtime.
|
|
118
|
+
- **Federated peer messaging.** Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.
|
|
153
119
|
|
|
154
|
-
**
|
|
155
|
-
an SSH route from the initiating machine
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
for cross-build messaging interoperability.
|
|
120
|
+
**Current federation limitations:** Independent discovery and initiation require
|
|
121
|
+
an SSH route from the initiating machine; an existing correspondence allows
|
|
122
|
+
replies without reverse SSH. Different Herdsman builds cannot yet exchange
|
|
123
|
+
ordinary messages. See [Peer communication](docs/reference/peer.md).
|
|
159
124
|
|
|
160
|
-
**
|
|
161
|
-
|
|
162
|
-
[
|
|
163
|
-
[portable project state](https://github.com/boadij/pi-herdsman/issues/755).
|
|
125
|
+
**Open proposals:** [bidirectional initiation over one-way connections (#790)](https://github.com/boadij/pi-herdsman/issues/790),
|
|
126
|
+
[cross-build messaging (#688)](https://github.com/boadij/pi-herdsman/issues/688),
|
|
127
|
+
and [portable repository runtime (#755)](https://github.com/boadij/pi-herdsman/issues/755).
|
|
164
128
|
|
|
165
|
-
**Early-stage project:**
|
|
166
|
-
|
|
167
|
-
See the [changelog](CHANGELOG.md) for release changes and migration guidance.
|
|
129
|
+
**Early-stage project:** Pre-1.0 releases may introduce breaking changes.
|
|
130
|
+
See the [changelog](CHANGELOG.md) for release and migration guidance.
|
|
168
131
|
|
|
169
132
|
## Choose your next step
|
|
170
133
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
| Build against the model-facing tools | [Coordination API](docs/coordination-api.md) |
|
|
179
|
-
| Deploy an SSH-ready environment | [Container deployment](docs/guides/container-deployment.md) |
|
|
180
|
-
| Contribute to Pi Herdsman | [Contributing](CONTRIBUTING.md) |
|
|
134
|
+
Browse the [documentation index](docs/README.md), or jump to:
|
|
135
|
+
|
|
136
|
+
- **Start:** [Getting started](docs/getting-started.md)
|
|
137
|
+
- **Orchestrate:** [Project orchestration](docs/guides/project-orchestration.md) and [Coordination](docs/concepts/coordination.md)
|
|
138
|
+
- **Customize:** [Agent definitions](docs/guides/agent-definitions.md)
|
|
139
|
+
- **Integrate:** [Coordination API](docs/coordination-api.md) and [Peer communication](docs/reference/peer.md)
|
|
140
|
+
- **Contribute:** [Contributing](CONTRIBUTING.md)
|
|
181
141
|
|
|
182
142
|
## Community
|
|
183
143
|
|