pi-herdsman 0.40.0 → 0.42.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 +62 -0
- package/README.md +18 -1
- package/SKILL.md +12 -9
- package/dist/coordinators/manager.md +5 -6
- package/dist/index.js +2116 -1368
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +23 -13
- package/dist/peer-bridge.js.map +3 -3
- package/docs/README.md +2 -2
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/delegation.md +22 -8
- package/docs/concepts/lifecycle.md +6 -4
- package/docs/coordination-api.md +3 -2
- package/docs/development/smoke-testing.md +13 -1
- package/docs/development/validation.md +12 -8
- package/docs/getting-started.md +9 -2
- package/docs/guides/agent-definitions.md +14 -1
- package/docs/guides/container-deployment.md +126 -38
- package/docs/guides/customizing-agents.md +5 -3
- package/docs/guides/project-orchestration.md +10 -0
- package/docs/guides/recovery.md +12 -11
- package/docs/reference/agent-definition-schema.md +33 -11
- package/docs/reference/agent-states.md +10 -10
- package/docs/reference/agent.md +36 -31
- package/docs/reference/commands.md +1 -1
- package/docs/reference/configuration.md +27 -0
- package/docs/reference/staff.md +9 -2
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -18,6 +18,68 @@
|
|
|
18
18
|
Move existing role overrides from `agents/` to `pi-herdsman/roles/` in the
|
|
19
19
|
same scope. Reserved role names in `agents/` are rejected.
|
|
20
20
|
|
|
21
|
+
## [0.42.0](https://github.com/boadij/pi-herdsman/compare/v0.41.0...v0.42.0) (2026-11-07)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Features
|
|
25
|
+
|
|
26
|
+
* **agents:** add a configurable maximum agent nesting depth ([#866](https://github.com/boadij/pi-herdsman/issues/866)) ([787601a](https://github.com/boadij/pi-herdsman/commit/787601a0faf35940f247d5e8c2ce031268491923))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Fixes
|
|
30
|
+
|
|
31
|
+
* **agent:** preserve extension-backed models on continuation ([#864](https://github.com/boadij/pi-herdsman/issues/864)) ([8909d29](https://github.com/boadij/pi-herdsman/commit/8909d29e25aae6da8f8282310be1202864e98b86))
|
|
32
|
+
* **manager:** enforce tool policy across late registration ([#868](https://github.com/boadij/pi-herdsman/issues/868)) ([2e189b2](https://github.com/boadij/pi-herdsman/commit/2e189b2e73844687cf46afcdcbe06ec43a5e6e82)), closes [#832](https://github.com/boadij/pi-herdsman/issues/832)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
### Other Changes
|
|
36
|
+
|
|
37
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.4 ([#873](https://github.com/boadij/pi-herdsman/issues/873)) ([c1fd32b](https://github.com/boadij/pi-herdsman/commit/c1fd32bc71646d1989222a9d626d1de5453ead7f))
|
|
38
|
+
|
|
39
|
+
## [0.41.0](https://github.com/boadij/pi-herdsman/compare/v0.40.0...v0.41.0) (2026-11-07)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### ⚠ BREAKING CHANGES
|
|
43
|
+
|
|
44
|
+
* **agent:** rename close_agent to stop_agent ([#860](https://github.com/boadij/pi-herdsman/issues/860))
|
|
45
|
+
|
|
46
|
+
### Fixes
|
|
47
|
+
|
|
48
|
+
* **agent:** allow continuation after empty mailbox cleanup ([#847](https://github.com/boadij/pi-herdsman/issues/847)) ([83670d9](https://github.com/boadij/pi-herdsman/commit/83670d9eaa4e3f0da3d8e994d026ff49a79dc1f6)), closes [#842](https://github.com/boadij/pi-herdsman/issues/842)
|
|
49
|
+
* **ci:** align test suite deadline across platforms ([#851](https://github.com/boadij/pi-herdsman/issues/851)) ([2c37524](https://github.com/boadij/pi-herdsman/commit/2c37524eacdeaafa263b9ffd2778291adead2956))
|
|
50
|
+
* **container:** persist optional Compose deployment selections ([#863](https://github.com/boadij/pi-herdsman/issues/863)) ([330dac4](https://github.com/boadij/pi-herdsman/commit/330dac42155fe02601c178f6139839115b81e995))
|
|
51
|
+
* detect non-repository folders on non-English locales ([#835](https://github.com/boadij/pi-herdsman/issues/835)) ([c34719b](https://github.com/boadij/pi-herdsman/commit/c34719b7cb511ca0082613908a3efa6e9b96930a))
|
|
52
|
+
* **manager:** avoid speculative cross-lead coordination ([#859](https://github.com/boadij/pi-herdsman/issues/859)) ([ae49f01](https://github.com/boadij/pi-herdsman/commit/ae49f017353671be04f141f5696c3ca17829aecb)), closes [#858](https://github.com/boadij/pi-herdsman/issues/858)
|
|
53
|
+
* **manager:** reject submodule-blocked removal before Lead shutdown ([#844](https://github.com/boadij/pi-herdsman/issues/844)) ([69ddb22](https://github.com/boadij/pi-herdsman/commit/69ddb220ce71c30d2bb54f66b9f029b567d8231f))
|
|
54
|
+
* **manager:** remove verified worktrees without Pi session-file provenance ([#855](https://github.com/boadij/pi-herdsman/issues/855)) ([3886f89](https://github.com/boadij/pi-herdsman/commit/3886f89c3e17e6527e580a81f0a607a1655bf961)), closes [#854](https://github.com/boadij/pi-herdsman/issues/854)
|
|
55
|
+
* **manager:** wait for assignment authority during delegation ([#848](https://github.com/boadij/pi-herdsman/issues/848)) ([b524e40](https://github.com/boadij/pi-herdsman/commit/b524e406201366fa58a352524a49c1dd53afb003)), closes [#845](https://github.com/boadij/pi-herdsman/issues/845)
|
|
56
|
+
* **supervision:** consolidate managed Lead reporting guidance ([#856](https://github.com/boadij/pi-herdsman/issues/856)) ([3edf381](https://github.com/boadij/pi-herdsman/commit/3edf3813999a19dfba0f441db001ee2121eb91ca))
|
|
57
|
+
* **trust:** preserve managed worktree trust through nested agents ([#852](https://github.com/boadij/pi-herdsman/issues/852)) ([68a04c0](https://github.com/boadij/pi-herdsman/commit/68a04c08c3676b1e0525a11732a0a869012b4ae6))
|
|
58
|
+
* **types:** eliminate TypeScript and Oxlint diagnostics ([#836](https://github.com/boadij/pi-herdsman/issues/836)) ([833369d](https://github.com/boadij/pi-herdsman/commit/833369db84c82b1f1fc6e06f964bfec1b37860f6))
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
### Refactoring
|
|
62
|
+
|
|
63
|
+
* **agent:** rename close_agent to stop_agent ([#860](https://github.com/boadij/pi-herdsman/issues/860)) ([e04a708](https://github.com/boadij/pi-herdsman/commit/e04a708c1075d4bf62fc4dc5fdc72a4aea424e49))
|
|
64
|
+
* **test:** remove verified Oxlint warnings ([#833](https://github.com/boadij/pi-herdsman/issues/833)) ([c83163b](https://github.com/boadij/pi-herdsman/commit/c83163b99ebd41a50c743944dc9a8c69f2eeb42a))
|
|
65
|
+
* **trust:** inherit Manager trust for managed worktrees ([#857](https://github.com/boadij/pi-herdsman/issues/857)) ([0a4a233](https://github.com/boadij/pi-herdsman/commit/0a4a233d500cb023c57285a10462fadffc2a76ea))
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
### Documentation
|
|
69
|
+
|
|
70
|
+
* **agents:** include static quality in local validation gate ([#849](https://github.com/boadij/pi-herdsman/issues/849)) ([0060b7f](https://github.com/boadij/pi-herdsman/commit/0060b7f0f81d2dbaa7757754c9d722306d84f997))
|
|
71
|
+
* showcase the simple Docker Compose deployment ([#862](https://github.com/boadij/pi-herdsman/issues/862)) ([1b4232f](https://github.com/boadij/pi-herdsman/commit/1b4232f0c093f7f335f6f85a73fe64f48b5bacef))
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
### CI
|
|
75
|
+
|
|
76
|
+
* enforce TypeScript and warning-free lint ([#837](https://github.com/boadij/pi-herdsman/issues/837)) ([062c09c](https://github.com/boadij/pi-herdsman/commit/062c09cd2c0cb9db74b2c50448be9f4094608825))
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
### Other Changes
|
|
80
|
+
|
|
81
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.3 ([#839](https://github.com/boadij/pi-herdsman/issues/839)) ([25786f2](https://github.com/boadij/pi-herdsman/commit/25786f277a72abe59085a717b62d78f079040b8c))
|
|
82
|
+
|
|
21
83
|
## [0.40.0](https://github.com/boadij/pi-herdsman/compare/v0.39.0...v0.40.0) (2026-11-05)
|
|
22
84
|
|
|
23
85
|
|
package/README.md
CHANGED
|
@@ -53,7 +53,24 @@ pi install npm:pi-herdsman
|
|
|
53
53
|
herdr integration install pi
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
**Docker Compose (prebuilt SSH environment):** Requires Docker Compose and an
|
|
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:
|
|
57
74
|
|
|
58
75
|
```sh
|
|
59
76
|
herdr
|
package/SKILL.md
CHANGED
|
@@ -96,7 +96,7 @@ eligibility. Every operation revalidates exact state and identity before
|
|
|
96
96
|
mutation.
|
|
97
97
|
|
|
98
98
|
The live-agent control tools are `steer_agent`, `interrupt_agent`,
|
|
99
|
-
`reply_agent`, and `
|
|
99
|
+
`reply_agent`, and `stop_agent`;
|
|
100
100
|
these mutate
|
|
101
101
|
live agent execution and are available only when listed. Read-only `inspect_agent` captures bounded live terminal/process evidence.
|
|
102
102
|
`read_agent_transcript` captures bounded persisted Pi conversation and tool evidence
|
|
@@ -115,15 +115,17 @@ merely because an agent is slow or marked stale; inactivity is advisory and
|
|
|
115
115
|
does not prove a hang.
|
|
116
116
|
|
|
117
117
|
Use `reply_agent` only to answer a valid outstanding `ask_owner` question. Use
|
|
118
|
-
`
|
|
118
|
+
`stop_agent` only when abandoning the Agent's unfinished assignment is
|
|
119
|
+
intended. Unlike `stop_lead`, which preserves a Manager's project assignment,
|
|
120
|
+
`stop_agent` does not complete or automatically restart the work.
|
|
119
121
|
|
|
120
122
|
A lost agent is a managed assignment whose exact physical execution is proven
|
|
121
123
|
gone before a durable terminal result resolved it. Loss is not completion or
|
|
122
124
|
task failure. Treat the assignment as unresolved. When `read_agent_transcript` is listed,
|
|
123
125
|
use it only when the last persisted work materially affects recovery. When
|
|
124
|
-
`
|
|
125
|
-
continuing its saved session. If `
|
|
126
|
-
blocking its
|
|
126
|
+
`stop_agent` is listed, use it to abandon the lost generation before replacing it or
|
|
127
|
+
continuing its saved session. If `stop_agent` is absent, resolve the condition
|
|
128
|
+
blocking its stop preflight first. Unknown evidence remains fail-closed and is
|
|
127
129
|
not proof of loss.
|
|
128
130
|
|
|
129
131
|
Never guess identities, paths, sessions, or control state. Treat unknown or
|
|
@@ -208,7 +210,8 @@ execution ownership to that agent until the assignment resolves; do not execute
|
|
|
208
210
|
or assign overlapping work while it is delegated.
|
|
209
211
|
Integrate direct agent results after resolution.
|
|
210
212
|
Own only the assigned objective and your direct permitted agents. Agent-started
|
|
211
|
-
agents
|
|
213
|
+
agents delegate further only within the configured maximum nesting depth and
|
|
214
|
+
are leaves beyond it. Delegate bounded execution work when an Agent can
|
|
212
215
|
reasonably own it and delegation is useful. Reuse adequate supplied evidence
|
|
213
216
|
rather than rediscovering it. Integrate direct agent results before completing. The lead
|
|
214
217
|
retains architecture, approved scope, acceptance of Agent outputs, and
|
|
@@ -292,8 +295,8 @@ A Lead may delegate to available definitions permitted by its effective
|
|
|
292
295
|
`agents` field; omission permits all, while an empty list permits none.
|
|
293
296
|
|
|
294
297
|
A delegating agent may delegate only to definitions listed in its effective
|
|
295
|
-
`agents` field and owns only its direct agents. Agent
|
|
296
|
-
|
|
298
|
+
`agents` field and owns only its direct agents. An Agent at the configured
|
|
299
|
+
`maxAgentDepth` is a leaf even when its definition is delegation-capable.
|
|
297
300
|
|
|
298
301
|
A delegating agent integrates agent results before its own completion. Direct
|
|
299
302
|
agent work and undelivered agent results gate completion.
|
|
@@ -553,7 +556,7 @@ managed session remains an Agent at every depth.
|
|
|
553
556
|
Every managed agent receives `ask_owner`. A non-empty effective `agents` list
|
|
554
557
|
is necessary but not sufficient to enable the nine Agent ownership tools:
|
|
555
558
|
`list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
556
|
-
`interrupt_agent`, `reply_agent`, `
|
|
559
|
+
`interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
|
|
557
560
|
`read_agent_transcript`. Delegation is disabled when `excludeTools` contains
|
|
558
561
|
`agent`, when `noTools: true` unless explicit `tools` contains `agent`,
|
|
559
562
|
or when `tools` is explicitly empty. Otherwise, omitted `tools` permits
|
|
@@ -10,12 +10,11 @@ Coordinate assigned project work through Leads.
|
|
|
10
10
|
|
|
11
11
|
Set priorities, resolve project-level decisions and dependency sequencing,
|
|
12
12
|
review outcomes, and request corrections through the responsible Lead.
|
|
13
|
-
When
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
unaffected work continues.
|
|
13
|
+
When cross-assignment coordination is requested by the user or needed to
|
|
14
|
+
carry out an already established direction, prefer direct technical
|
|
15
|
+
exchange between eligible Leads over relaying messages yourself.
|
|
16
|
+
Mediate when peer communication is unavailable or a project-level decision
|
|
17
|
+
requires Manager action. Keep coordination limited to the concrete need.
|
|
19
18
|
Leave technical investigation, implementation, review, validation, and
|
|
20
19
|
integration to that Lead and its Agents rather than doing or delegating
|
|
21
20
|
the work yourself.
|