pi-herdsman 0.44.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 +79 -0
- package/README.md +64 -104
- package/SKILL.md +10 -8
- package/dist/index.js +2164 -751
- package/dist/index.js.map +4 -4
- package/docs/README.md +2 -1
- package/docs/concepts/coordination.md +28 -8
- package/docs/concepts/delegation.md +7 -5
- package/docs/concepts/lifecycle.md +6 -1
- package/docs/coordination-api.md +7 -6
- package/docs/development/documentation.md +3 -2
- package/docs/development/instruction-interface-design.md +11 -0
- package/docs/development/product-philosophy.md +7 -0
- package/docs/development/smoke-testing.md +35 -14
- package/docs/development/validation.md +19 -16
- package/docs/getting-started.md +1 -1
- package/docs/guides/agent-definitions.md +1 -1
- package/docs/guides/container-deployment.md +34 -1
- package/docs/guides/customizing-agents.md +26 -39
- package/docs/guides/handoffs.md +5 -5
- package/docs/guides/recovery.md +8 -3
- package/docs/reference/agent-definition-schema.md +33 -8
- package/docs/reference/agent-states.md +4 -4
- package/docs/reference/agent.md +61 -33
- package/docs/reference/{ask-owner.md → await-owner.md} +8 -8
- package/docs/reference/commands.md +26 -0
- package/docs/reference/notify-owner.md +51 -0
- package/docs/reference/supervisor.md +2 -1
- package/package.json +11 -16
- 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/docs/README.md
CHANGED
|
@@ -43,7 +43,8 @@ Start with [Coordination API](coordination-api.md), then use the focused
|
|
|
43
43
|
references for exact contracts:
|
|
44
44
|
|
|
45
45
|
- [Agent tools](reference/agent.md)
|
|
46
|
-
- [`
|
|
46
|
+
- [`notify_owner`](reference/notify-owner.md)
|
|
47
|
+
- [`await_owner`](reference/await-owner.md)
|
|
47
48
|
- [Staff tools](reference/staff.md)
|
|
48
49
|
- [Supervisor tools](reference/supervisor.md)
|
|
49
50
|
- [Peer tools](reference/peer.md)
|
|
@@ -5,6 +5,26 @@
|
|
|
5
5
|
Pi Herdsman separates supervision, execution ownership, and physical placement.
|
|
6
6
|
Those relationships intentionally do not collapse into one global Agent tree.
|
|
7
7
|
|
|
8
|
+
## Emergent workflows, explicit boundaries
|
|
9
|
+
|
|
10
|
+
Pi Herdsman provides coordination tools, not a prescribed execution graph.
|
|
11
|
+
A Lead decides how to decompose its objective into bounded tasks and which
|
|
12
|
+
permitted Agents to delegate them to. A delegation-enabled Agent can repeat
|
|
13
|
+
that process within its own allowlist and the configured depth limit. At
|
|
14
|
+
project scale, a Manager decides which independent, branch-scoped objectives
|
|
15
|
+
to assign to managed Leads; each Lead directs its own Agent tree. The models
|
|
16
|
+
may choose parallel execution for independent work or sequence dependent work,
|
|
17
|
+
reassessing after handoffs instead of following a fixed pipeline.
|
|
18
|
+
|
|
19
|
+
The execution strategy is adaptive; authority is not. Exact-session Agent
|
|
20
|
+
ownership, delegation permissions, current project assignments, verified
|
|
21
|
+
worktree scope, and supervision boundaries remain enforced by Herdsman.
|
|
22
|
+
Agents cannot grant themselves broader authority by choosing a different
|
|
23
|
+
handoff. Users can still specify a workflow or customize Agent definitions,
|
|
24
|
+
but no predetermined handoff order is required. See [Delegation](delegation.md)
|
|
25
|
+
and [Project orchestration](../guides/project-orchestration.md) for the
|
|
26
|
+
respective execution contracts.
|
|
27
|
+
|
|
8
28
|
## Roles
|
|
9
29
|
|
|
10
30
|
```mermaid
|
|
@@ -209,14 +229,14 @@ live in [Staff tools](../reference/staff.md).
|
|
|
209
229
|
|
|
210
230
|
Coordination crosses one authority edge at a time:
|
|
211
231
|
|
|
212
|
-
| Direction | Interface
|
|
213
|
-
| --------- |
|
|
214
|
-
| Up | `message_supervisor` / automatic results
|
|
215
|
-
| Down | `message_staff` / project operations
|
|
216
|
-
| Up | `message_supervisor`
|
|
217
|
-
| Down | `message_staff`
|
|
218
|
-
| Sideways | `message_peer`
|
|
219
|
-
| Ownership | Agent controls / `
|
|
232
|
+
| Direction | Interface | Boundary |
|
|
233
|
+
| --------- | ------------------------------------------------------------- | --------------------------------------------------- |
|
|
234
|
+
| Up | `message_supervisor` / automatic results | Assigned Lead -> Manager |
|
|
235
|
+
| Down | `message_staff` / project operations | Manager -> assigned Lead |
|
|
236
|
+
| Up | `message_supervisor` | Ordinary Lead -> Manager or Chief; Manager -> Chief |
|
|
237
|
+
| Down | `message_staff` | Manager -> ordinary Lead (cooperative steering) |
|
|
238
|
+
| Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
|
|
239
|
+
| Ownership | Agent controls / `notify_owner`, `await_owner`, `reply_agent` | owner <-> directly owned Agent |
|
|
220
240
|
|
|
221
241
|
### Coordination does not imply dependency
|
|
222
242
|
|
|
@@ -25,7 +25,7 @@ final decision authority for its assignment.
|
|
|
25
25
|
|
|
26
26
|
A managed Agent may delegate to the definitions in its effective
|
|
27
27
|
`agents` allowlist only when delegation is enabled by its tool policy. Every
|
|
28
|
-
managed agent receives `
|
|
28
|
+
managed agent receives `await_owner` and `notify_owner`; qualifying delegating agents also receive
|
|
29
29
|
Agent ownership tools. See the [agent-definition schema](../reference/agent-definition-schema.md#managed-agent-coordination-tools)
|
|
30
30
|
for the exact eligibility, exclusion, and mandatory-tool rules.
|
|
31
31
|
|
|
@@ -58,7 +58,7 @@ allows chains of four agents. Delegation at every level still requires the
|
|
|
58
58
|
launching agent's definition to list `agents`, and each level may delegate only
|
|
59
59
|
to definitions in its own allowlist. When a delegated agent's result is
|
|
60
60
|
delivered and cleaned up, any agents it still owns are closed with it, as they
|
|
61
|
-
are for a root controller. Questions from `
|
|
61
|
+
are for a root controller. Questions from `await_owner`, results, stop, and
|
|
62
62
|
continuation always go through the direct owner, so each level behaves the
|
|
63
63
|
same whatever its depth. Lowering `maxAgentDepth` never removes running
|
|
64
64
|
agents: they stay manageable, but agents at the new limit can no longer start
|
|
@@ -150,10 +150,11 @@ merely to keep the controller active. For the full turn-navigation model, see
|
|
|
150
150
|
|
|
151
151
|
## Clarification across ownership edges
|
|
152
152
|
|
|
153
|
-
An agent may
|
|
153
|
+
An agent may notify its exact direct owner without blocking through
|
|
154
|
+
`notify_owner`, or request an answer required to proceed through `await_owner`.
|
|
154
155
|
|
|
155
156
|
A delegating agent with no unresolved direct-agent work follows normal
|
|
156
|
-
`
|
|
157
|
+
`await_owner` eligibility. If unresolved direct agents exist, every unresolved
|
|
157
158
|
child must itself be validly blocked on an owner question. Ordinary active work
|
|
158
159
|
or an undelivered result still blocks escalation. Questions are not
|
|
159
160
|
automatically forwarded through an ownership chain.
|
|
@@ -166,6 +167,7 @@ closed, the delegating agent is preserved rather than destructively guessing.
|
|
|
166
167
|
|
|
167
168
|
## See also
|
|
168
169
|
|
|
169
|
-
- [`
|
|
170
|
+
- [`await_owner` API](../reference/await-owner.md)
|
|
171
|
+
- [`notify_owner` API](../reference/notify-owner.md)
|
|
170
172
|
- [Lifecycle](lifecycle.md)
|
|
171
173
|
- [Handoffs and files](../guides/handoffs.md)
|
|
@@ -33,6 +33,11 @@ evidence remains `unknown`.
|
|
|
33
33
|
The authoritative final result is correlated to the accepted assignment request
|
|
34
34
|
ID.
|
|
35
35
|
|
|
36
|
+
An Agent may send nonblocking material information to its exact owner with
|
|
37
|
+
`notify_owner`; this does not alter assignment completion eligibility. An
|
|
38
|
+
accepted notification remains in the mailbox until the owner's persisted
|
|
39
|
+
session history confirms receipt, and cleanup waits for that confirmation.
|
|
40
|
+
|
|
36
41
|
An aborted Pi execution is not successful assignment completion, even when the
|
|
37
42
|
conversation contains assistant text. The assignment remains active when an
|
|
38
43
|
accepted interrupt replacement continues the work; otherwise its terminal
|
|
@@ -44,7 +49,7 @@ An agent that requires an owner decision stays on the same assignment:
|
|
|
44
49
|
|
|
45
50
|
```text
|
|
46
51
|
working
|
|
47
|
-
↓
|
|
52
|
+
↓ await_owner
|
|
48
53
|
blocked
|
|
49
54
|
↓ owner reply
|
|
50
55
|
working
|
package/docs/coordination-api.md
CHANGED
|
@@ -15,17 +15,17 @@ supporting native programmatic invocation are `list_agents`, `steer_agent`,
|
|
|
15
15
|
`read_staff_transcript`, `message_staff`, `delegate_work`, `resume_work`,
|
|
16
16
|
`stop_lead`, `remove_worktree`, `integrate_branch`, `message_supervisor`,
|
|
17
17
|
`list_peers`, `message_peer`, `attach_handoff`, `delegate_agent`, and
|
|
18
|
-
`continue_agent`. Delegation tools return after assignment acceptance, not
|
|
18
|
+
`continue_agent`, and `notify_owner`. Delegation tools return after assignment acceptance, not
|
|
19
19
|
completion; eventual results arrive through Herdsman's normal result-delivery
|
|
20
|
-
mechanism. `
|
|
20
|
+
mechanism. `await_owner` also remains `model-only` because it must be a direct,
|
|
21
21
|
exclusive tool call in its turn. See
|
|
22
|
-
[`
|
|
22
|
+
[`await_owner`](reference/await-owner.md) for its contract.
|
|
23
23
|
|
|
24
24
|
Tool access still depends on the active role, ownership, extension loading, and
|
|
25
25
|
runtime authorization. This documents Pi's native contract; behavior through
|
|
26
26
|
third-party code-mode integrations and their approval or foreground settings
|
|
27
27
|
depends on that integration and is not guaranteed here. In environments where
|
|
28
|
-
`
|
|
28
|
+
`await_owner` and Fabric are both registered, Fabric may configure it as a
|
|
29
29
|
foreground tool, for example:
|
|
30
30
|
|
|
31
31
|
```json
|
|
@@ -33,7 +33,7 @@ foreground tool, for example:
|
|
|
33
33
|
"foreground": {
|
|
34
34
|
"tools": [
|
|
35
35
|
{
|
|
36
|
-
"name": "
|
|
36
|
+
"name": "await_owner",
|
|
37
37
|
"owner": "pi-herdsman",
|
|
38
38
|
"reason": "turn-steering"
|
|
39
39
|
}
|
|
@@ -65,7 +65,8 @@ read_agent_transcript
|
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
Managed Agents contact their exact direct owner through
|
|
68
|
-
[`
|
|
68
|
+
[`notify_owner`](reference/notify-owner.md) for nonblocking information or
|
|
69
|
+
[`await_owner`](reference/await-owner.md) when progress depends on an answer.
|
|
69
70
|
|
|
70
71
|
The lifecycle and execution-ownership rules are documented in
|
|
71
72
|
[Lifecycle](concepts/lifecycle.md) and [Delegation](concepts/delegation.md).
|
|
@@ -39,7 +39,8 @@ disagrees.
|
|
|
39
39
|
| Operator recovery | [Recovery](../guides/recovery.md) |
|
|
40
40
|
| Container deployment | [Container deployment](../guides/container-deployment.md) |
|
|
41
41
|
| Agent ownership contract | [Agent tools](../reference/agent.md) |
|
|
42
|
-
| `
|
|
42
|
+
| `notify_owner` contract | [`notify_owner`](../reference/notify-owner.md) |
|
|
43
|
+
| `await_owner` contract | [`await_owner`](../reference/await-owner.md) |
|
|
43
44
|
| Staff and project-work contract | [Staff tools](../reference/staff.md) |
|
|
44
45
|
| Supervisor and ask contract | [Supervisor tools](../reference/supervisor.md) |
|
|
45
46
|
| Peer contract | [Peer tools](../reference/peer.md) |
|
|
@@ -151,7 +152,7 @@ When implementation and prose disagree:
|
|
|
151
152
|
3. stale prose is deleted rather than preserved as another contract
|
|
152
153
|
|
|
153
154
|
Particularly verify runtime implementation for Agent ownership operations,
|
|
154
|
-
`
|
|
155
|
+
`await_owner`, `notify_owner`, staff and project operations, supervisor and ask operations, peer
|
|
155
156
|
operations, `/agents`, `/manager`, `/chief`, states,
|
|
156
157
|
definition composition, project work, recovery, and presentation behavior.
|
|
157
158
|
|
|
@@ -124,6 +124,17 @@ Do not ask the model to infer, remember, reconstruct, or supply information the
|
|
|
124
124
|
|
|
125
125
|
Instructions should describe semantics the system cannot make sufficiently obvious or enforce directly.
|
|
126
126
|
|
|
127
|
+
## Prefer programmatically composable tools
|
|
128
|
+
|
|
129
|
+
Expose Herdsman tools through Pi's native `direct` interface when their
|
|
130
|
+
semantics permit, so models can call them individually or compose them through
|
|
131
|
+
native Code Mode. Reserve `model-only` exposure for tools whose required turn
|
|
132
|
+
isolation, lifecycle, or safety constraints cannot be preserved in nested
|
|
133
|
+
execution. Do not weaken these constraints solely for Code Mode compatibility.
|
|
134
|
+
|
|
135
|
+
This preference applies to Pi's native execution contract; third-party
|
|
136
|
+
integrations may impose additional restrictions.
|
|
137
|
+
|
|
127
138
|
## Keep shared instructions roster-agnostic
|
|
128
139
|
|
|
129
140
|
Shared runtime instructions, tool descriptions, and reusable workflows must not
|
|
@@ -125,6 +125,13 @@ consumption. Prefer eliminating work over adding caches or infrastructure,
|
|
|
125
125
|
and justify optimization complexity with evidence. Never trade correctness,
|
|
126
126
|
reliability, security, or recovery for speed.
|
|
127
127
|
|
|
128
|
+
When independently eligible messages, results, or notifications target the
|
|
129
|
+
same model session, prefer recipient-side fan-in at existing Pi execution
|
|
130
|
+
boundaries over separate model turns. Do not delay time-sensitive delivery just
|
|
131
|
+
to form a batch. Preserve each communication's identity, authority checks,
|
|
132
|
+
ordering requirements, receipts, and recovery; reuse native delivery rather
|
|
133
|
+
than introduce batching infrastructure without demonstrated need.
|
|
134
|
+
|
|
128
135
|
## Decision test
|
|
129
136
|
|
|
130
137
|
For any proposed feature, ask:
|
|
@@ -81,15 +81,16 @@ provider accepts only expected transcript states and requires actual correlated
|
|
|
81
81
|
tool results before producing completion responses. It cannot produce
|
|
82
82
|
successful tool results or directly mutate Herdsman or Herdr state. The
|
|
83
83
|
simulated-only scenarios use real Pi, Herdsman, and Herdr; they do not replace
|
|
84
|
-
live-model acceptance. `agent-crash-recovery`
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
real
|
|
84
|
+
live-model acceptance. `agent-crash-recovery` restarts its isolated Herdr server
|
|
85
|
+
and reopens the exact owner session with its pending-child parent safely
|
|
86
|
+
blocked or unknown. It resolves the original target through an exact persisted aborted
|
|
87
|
+
result or one authorized stop receipt, then waits read-only for the persisted
|
|
88
|
+
acknowledgment/absence of active work and physical quiescence before one exact
|
|
89
|
+
session continuation. It verifies one correlated completed result and fails
|
|
90
|
+
closed on incomplete state or process evidence. An advertised receiverless
|
|
91
|
+
parent steer is attempted once and must be rejected. The process/server
|
|
92
|
+
lifecycle and controller tools are real; the scenario never uses the default
|
|
93
|
+
Herdr server.
|
|
93
94
|
Simulated runs do not require model credentials or inference, but retain runtime
|
|
94
95
|
compatibility checks, build, isolation, Herdr setup, and cleanup. They are
|
|
95
96
|
integration checks, not replacements for real-model acceptance.
|
|
@@ -101,7 +102,7 @@ real Pi, Herdsman, and Herdr, that each of levels 1 through 3 holds the
|
|
|
101
102
|
delegation tool while the level-4 Agent at the limit does not, that each
|
|
102
103
|
Agent's completed result reaches its direct owner, and that the leaf's marker
|
|
103
104
|
bubbles up through every level to the root's final message. The level-4 Agent
|
|
104
|
-
also escalates one `
|
|
105
|
+
also escalates one `await_owner` to its level-3 owner, which answers with
|
|
105
106
|
`reply_agent`, and the scenario asserts both calls. It asserts
|
|
106
107
|
completion and result delivery. It also samples the root's rendered status
|
|
107
108
|
tree and requires every level to be shown there at some sample before the chain
|
|
@@ -230,6 +231,26 @@ Herdsman, copy normal Pi settings or extensions, or run as part of
|
|
|
230
231
|
`npm run validate`. Run selected scenarios according to the change being
|
|
231
232
|
verified; `npm run smoke` defaults to `core`.
|
|
232
233
|
|
|
234
|
+
## Peer federation acceptance
|
|
235
|
+
|
|
236
|
+
Required peer-federation CI runs the shared core acceptance independently for
|
|
237
|
+
real containerized Managers (`manager-core`) and ordinary Leads (`lead-core`).
|
|
238
|
+
Each verifies one successful request, the exact correlated reply persisted
|
|
239
|
+
once, and A's assistant completion after that reply without another prompt.
|
|
240
|
+
The comprehensive ordinary-Lead acceptance remains manually available as the
|
|
241
|
+
`delivery` phase; it covers managed-Lead exclusion and delivery/recovery checks
|
|
242
|
+
not included in the focused CI gate.
|
|
243
|
+
|
|
244
|
+
Run the focused phases with
|
|
245
|
+
`PEER_SMOKE_PHASE=manager-core node scripts/peer-federation-smoke.mjs` and
|
|
246
|
+
`PEER_SMOKE_PHASE=lead-core node scripts/peer-federation-smoke.mjs`.
|
|
247
|
+
The comprehensive Manager recovery scenario remains the default and is
|
|
248
|
+
manually runnable with
|
|
249
|
+
`node scripts/peer-federation-smoke.mjs`. Run comprehensive ordinary-Lead
|
|
250
|
+
delivery with
|
|
251
|
+
`PEER_SMOKE_PHASE=delivery node scripts/peer-federation-smoke.mjs`.
|
|
252
|
+
A failed federation invocation is not retried automatically.
|
|
253
|
+
|
|
233
254
|
## Runtime preflight
|
|
234
255
|
|
|
235
256
|
Before allocating the Herdr environment, the harness validates installed Node,
|
|
@@ -326,8 +347,8 @@ Verify:
|
|
|
326
347
|
Launch a delegating managed agent with an explicit ordinary execution-tool
|
|
327
348
|
allowlist and ask it to delegate one bounded scout task. Verify that it retains
|
|
328
349
|
those ordinary tools and can call all nine coordination tools plus
|
|
329
|
-
`
|
|
330
|
-
and `
|
|
350
|
+
`await_owner`, then verify that the spawned scout is a leaf with its normal tools
|
|
351
|
+
and `await_owner` but no delegation tools. Also verify that role-required tools
|
|
331
352
|
are not removed by `excludeTools`.
|
|
332
353
|
|
|
333
354
|
For a definition with `tools` omitted, verify that launch does not add a
|
|
@@ -363,7 +384,7 @@ Verify the agent obeys that instruction through the expanded private prompt.
|
|
|
363
384
|
Afterward remove the temporary definition and referenced file, confirm discovery
|
|
364
385
|
no longer lists the temporary definition, and verify no repository file changed.
|
|
365
386
|
|
|
366
|
-
## `
|
|
387
|
+
## `await_owner` round trip
|
|
367
388
|
|
|
368
389
|
Owner ask/reply remains manual, unautomated coverage.
|
|
369
390
|
|
|
@@ -371,7 +392,7 @@ Give an agent a task whose correct continuation requires an owner choice.
|
|
|
371
392
|
|
|
372
393
|
Verify:
|
|
373
394
|
|
|
374
|
-
1. agent calls `
|
|
395
|
+
1. agent calls `await_owner` alone;
|
|
375
396
|
2. owner receives one question;
|
|
376
397
|
3. agent becomes `blocked`;
|
|
377
398
|
4. owner replies with exact `reply_agent`;
|
|
@@ -140,31 +140,34 @@ worktree. If `node_modules` is absent, run `npm ci` from that checkout.
|
|
|
140
140
|
### Optional setup for newly created worktrees
|
|
141
141
|
|
|
142
142
|
The repository includes a `post-checkout` hook that runs `npm ci` synchronously
|
|
143
|
-
when Git creates a new linked worktree. It is not enabled automatically.
|
|
144
|
-
enable it, run these steps from the trusted **primary checkout** (not a linked
|
|
145
|
-
worktree).
|
|
143
|
+
when Git creates a new linked worktree. It is not enabled automatically.
|
|
146
144
|
|
|
147
|
-
|
|
145
|
+
For a fresh trusted clone, run this from the **primary checkout** (not a linked
|
|
146
|
+
worktree):
|
|
148
147
|
|
|
149
148
|
```sh
|
|
150
|
-
|
|
149
|
+
npm run setup
|
|
151
150
|
```
|
|
152
151
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
changing it can disable other hooks. If no existing configuration would be
|
|
161
|
-
displaced, enable the repository hook locally:
|
|
152
|
+
This configures the hook and installs dependencies. If dependencies are already
|
|
153
|
+
installed, `npm run setup:hooks` enables only the hook. Setup is idempotent.
|
|
154
|
+
When a repository folder is copied with its `.git` directory, setup repairs a
|
|
155
|
+
repository-local `core.hooksPath` pointing to an old `.githooks` directory
|
|
156
|
+
if that directory is missing or its hook files match the current checkout.
|
|
157
|
+
Unrelated hook managers, global settings, and executable default hooks are
|
|
158
|
+
not overridden. Inspect the current hook configuration and its origin with:
|
|
162
159
|
|
|
163
160
|
```sh
|
|
164
|
-
git config --
|
|
161
|
+
git config --show-origin --get core.hooksPath
|
|
165
162
|
```
|
|
166
163
|
|
|
167
|
-
|
|
164
|
+
If an existing hook configuration or hook manager would be displaced, retain
|
|
165
|
+
it or integrate `.githooks/post-checkout` manually; the repository does not
|
|
166
|
+
install a dispatcher. `core.hooksPath` selects the whole hooks directory, so
|
|
167
|
+
changing it can disable other hooks.
|
|
168
|
+
|
|
169
|
+
When newly configured, this local, optional setting affects only this
|
|
170
|
+
repository. Its absolute path
|
|
168
171
|
deliberately points all linked worktrees to the same trusted script; ordinary
|
|
169
172
|
worktrees share the repository's common Git configuration. Enabling it is an
|
|
170
173
|
explicit developer trust decision: creating a new linked worktree in this
|
package/docs/getting-started.md
CHANGED
|
@@ -51,7 +51,7 @@ Pi to use the bundled `scout` Agent for a read-only reconnaissance task:
|
|
|
51
51
|
|
|
52
52
|
```text
|
|
53
53
|
Use scout to identify this repository's main entry points.
|
|
54
|
-
Explain how the application starts.
|
|
54
|
+
Explain how the application starts.
|
|
55
55
|
```
|
|
56
56
|
|
|
57
57
|
Delegation starts after Herdsman accepts the task. The Agent works
|
|
@@ -290,7 +290,7 @@ the active controller contract remains authoritative for delegation behavior.
|
|
|
290
290
|
|
|
291
291
|
A non-empty `agents` list is required but does not alone enable delegation;
|
|
292
292
|
the effective tool policy also governs eligibility. Every managed agent retains
|
|
293
|
-
mandatory `
|
|
293
|
+
mandatory `await_owner` and `notify_owner`, and an Agent at the configured maximum nesting depth
|
|
294
294
|
is a leaf. See
|
|
295
295
|
[Delegation](../concepts/delegation.md) for the ownership model and the
|
|
296
296
|
[agent-definition schema](../reference/agent-definition-schema.md#managed-agent-coordination-tools)
|
|
@@ -150,7 +150,40 @@ Tailscale provides networking only. SSH remains normal OpenSSH.
|
|
|
150
150
|
|
|
151
151
|
## Update
|
|
152
152
|
|
|
153
|
-
To update
|
|
153
|
+
To update the Pi runtime inside the container, finish active coordination
|
|
154
|
+
first, then run:
|
|
155
|
+
|
|
156
|
+
```sh
|
|
157
|
+
pi update
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Pi downloads the complete official release into an immutable directory under
|
|
161
|
+
`~/.local/share/pi-herdsman/pi/releases/` and atomically selects it. New Pi
|
|
162
|
+
processes use that release; already-running processes continue using their
|
|
163
|
+
original files. The selection survives container restart and recreation and
|
|
164
|
+
takes precedence over the Pi bundled in a newer image. Pulling an image does
|
|
165
|
+
not replace this persistent selection, so review it separately for Pi security
|
|
166
|
+
updates. Forced reinstallations create additional retained release directories;
|
|
167
|
+
the container does not prune them.
|
|
168
|
+
|
|
169
|
+
Pi's `pi update --all` follows upstream behavior: installed packages are
|
|
170
|
+
updated before the Pi runtime, so the operation is not transactional. For
|
|
171
|
+
operationally significant updates, stop coordination and run the Pi update and
|
|
172
|
+
package updates as separate operations.
|
|
173
|
+
|
|
174
|
+
To recover to the image-bundled Pi after stopping work, remove only the
|
|
175
|
+
selection symlink:
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
rm ~/.local/share/pi-herdsman/pi/current
|
|
179
|
+
pi --version
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Do not delete the release directories or the persistent home. The bundled
|
|
183
|
+
runtime remains available at `/opt/pi`.
|
|
184
|
+
|
|
185
|
+
To update Herdsman or other installed Pi packages, finish active coordination
|
|
186
|
+
first, then run:
|
|
154
187
|
|
|
155
188
|
```sh
|
|
156
189
|
pi update npm:pi-herdsman
|
|
@@ -87,9 +87,11 @@ agents: [scout, reviewer]
|
|
|
87
87
|
```
|
|
88
88
|
|
|
89
89
|
An omitted `agents` field leaves Leads unrestricted; `agents: []` disables
|
|
90
|
-
fresh delegation.
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
fresh delegation. Existing owned Agents remain manageable. The policy covers
|
|
91
|
+
direct children only and is independent of ordinary tool selection. For
|
|
92
|
+
concrete inherited lists, `agents: [+scout, -reviewer]` modifies the list.
|
|
93
|
+
Leads with an unrestricted implicit default must first use a plain
|
|
94
|
+
`agents: [scout, reviewer]` allowlist before applying modifiers.
|
|
93
95
|
|
|
94
96
|
Ordinary Leads persist their execution mode separately from role/authority
|
|
95
97
|
state and retain their ordinary tool baseline while a restrictive profile is
|
|
@@ -238,7 +240,9 @@ For a matching higher-precedence definition:
|
|
|
238
240
|
|
|
239
241
|
- omitted fields inherit;
|
|
240
242
|
- strings and booleans replace;
|
|
241
|
-
- arrays replace wholesale, including `[]`;
|
|
243
|
+
- arrays with plain entries replace wholesale, including `[]`;
|
|
244
|
+
- `+name` and `-name` entries modify inherited arrays; in a mixed list,
|
|
245
|
+
plain entries establish the replacement base before ordered modifiers;
|
|
242
246
|
- the complete effective definition is validated after composition.
|
|
243
247
|
|
|
244
248
|
`enabled` is a boolean that defaults to `true`. Use it in a minimal override to
|
|
@@ -320,7 +324,7 @@ append-only and rejects `replace`. A custom replacement prompt does not
|
|
|
320
324
|
automatically preserve Pi's normal system-prompt rules or tool guidelines.
|
|
321
325
|
|
|
322
326
|
Managed agents additionally receive shared herdr agent guidance at launch,
|
|
323
|
-
including the `
|
|
327
|
+
including the `notify_owner` and `await_owner` contracts. This shared guidance is infrastructure and
|
|
324
328
|
is not copied into every bundled role body. Managed project Leads instead use
|
|
325
329
|
the effective `managed-lead` body plus the ordinary Lead runtime charter and
|
|
326
330
|
dynamic project coordination context.
|
|
@@ -407,8 +411,23 @@ The same diagnostic's no-network negative probe can be run with
|
|
|
407
411
|
deterministic forbidden `exec_command` call into an empty tool context and
|
|
408
412
|
asserts Pi returns `Tool exec_command not found` without execution.
|
|
409
413
|
|
|
410
|
-
|
|
411
|
-
|
|
414
|
+
Plain arrays replace the inherited array. Use modifiers to add or remove
|
|
415
|
+
individual values without copying the inherited list. For example, a project
|
|
416
|
+
overlay can adjust an Agent's skills and a private repository overlay can
|
|
417
|
+
remove one inherited extension:
|
|
418
|
+
|
|
419
|
+
```yaml
|
|
420
|
+
# .pi/agents/reviewer.md
|
|
421
|
+
skills: ["+/absolute/path/to/review/SKILL.md"]
|
|
422
|
+
|
|
423
|
+
# <git-common-dir>/pi-herdsman/agents/reviewer.md
|
|
424
|
+
extensions: ["-./extensions/legacy.ts"]
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
For tools, a modifier-only list such as `tools: [+codemode, -write]` is
|
|
428
|
+
relative to Pi's ordinary tool selection, not a closed allowlist. Use a plain
|
|
429
|
+
list when a closed allowlist is intended. Tool modifiers accept exact names;
|
|
430
|
+
put wildcard patterns in `excludeTools`.
|
|
412
431
|
|
|
413
432
|
Skill and extension paths are passed to Pi unchanged; unlike body `@file`
|
|
414
433
|
references, herdr does not resolve them relative to the definition file.
|
|
@@ -471,38 +490,6 @@ execution fields from their spawning controller; `continue` restores saved
|
|
|
471
490
|
session settings. They do not mutate an already-running agent or the lead Pi
|
|
472
491
|
session.
|
|
473
492
|
|
|
474
|
-
## Optional Pi Codex Conversion context sharing
|
|
475
|
-
|
|
476
|
-
The Herdsman adapter for Pi Codex Conversion (PCC) is optional and supports
|
|
477
|
-
Remote storage only. PCC's `shareSubagentContext` setting remains authoritative.
|
|
478
|
-
Load the adapter in both the delegating controller and each participating fresh
|
|
479
|
-
managed child; it is shipped at
|
|
480
|
-
`dist/integrations/pi-codex-context-sharing.js` but is not loaded by default.
|
|
481
|
-
For a normal npm Pi installation, reference it explicitly, for example:
|
|
482
|
-
|
|
483
|
-
```text
|
|
484
|
-
~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
When a managed Agent definition uses `noExtensions: true`, list both PCC and the
|
|
488
|
-
Herdsman adapter in that definition's `extensions`:
|
|
489
|
-
|
|
490
|
-
```yaml
|
|
491
|
-
---
|
|
492
|
-
name: shared-worker
|
|
493
|
-
noExtensions: true
|
|
494
|
-
extensions:
|
|
495
|
-
- "~/.pi/agent/npm/node_modules/@howaboua/pi-codex-conversion/dist/index.js"
|
|
496
|
-
- "~/.pi/agent/npm/node_modules/pi-herdsman/dist/integrations/pi-codex-context-sharing.js"
|
|
497
|
-
---
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
An explicit `tools` allowlist must independently permit the tools needed by the
|
|
501
|
-
current PCC execution mode. The adapter does not modify tools or PCC execution
|
|
502
|
-
mode; consult PCC for mode-specific requirements. PCC restores the saved
|
|
503
|
-
context identity on continuation, so no adapter rebind is needed. Local and
|
|
504
|
-
Tree storage are not supported because they require ongoing context routing.
|
|
505
|
-
|
|
506
493
|
## See also
|
|
507
494
|
|
|
508
495
|
- [Agent-definition schema](../reference/agent-definition-schema.md)
|
package/docs/guides/handoffs.md
CHANGED
|
@@ -118,7 +118,7 @@ Ordinary files supplied to `message_staff`, `message_supervisor`, or
|
|
|
118
118
|
configured per-file and complete-message budgets; unsupported, changed, or
|
|
119
119
|
non-fitting files reject the handoff instead of becoming path-only references.
|
|
120
120
|
Other `files` operations retain their existing preparation behavior. In
|
|
121
|
-
particular, `
|
|
121
|
+
particular, `await_owner` requires supported UTF-8 text attachments to fit fully
|
|
122
122
|
within its per-file and complete-message budgets; rejection does not fall back
|
|
123
123
|
to a path-only reference. Ordinary
|
|
124
124
|
coordination attachments are per-message evidence unless retained through an
|
|
@@ -144,13 +144,13 @@ Pi Herdsman has two text-file mechanisms with different purposes:
|
|
|
144
144
|
- `files` supplies evidence to the coordination operations that accept it:
|
|
145
145
|
`delegate_agent`, `continue_agent`, `steer_agent`, `interrupt_agent`,
|
|
146
146
|
`reply_agent`, `delegate_work`, `message_staff`,
|
|
147
|
-
`message_supervisor`, `message_peer`, and `
|
|
147
|
+
`message_supervisor`, `message_peer`, `notify_owner`, and `await_owner`.
|
|
148
148
|
- whole-line body `@file` references put definition-owned text into the agent
|
|
149
149
|
system prompt when a new agent generation is built.
|
|
150
150
|
|
|
151
151
|
For coordination operations that allow reference fallback, strict UTF-8 text is
|
|
152
152
|
embedded when it fits; ordinary non-text and non-fitting files are canonical
|
|
153
|
-
local references and are not copied or snapshotted. `
|
|
153
|
+
local references and are not copied or snapshotted. `await_owner` is stricter:
|
|
154
154
|
its explicit files must be embedded supported UTF-8 text, or the request is
|
|
155
155
|
rejected. The required-assignment exception preserves supported text snapshots
|
|
156
156
|
and can reference those snapshots when they do not fit inline; see
|
|
@@ -234,8 +234,8 @@ markup frames evidence for the model and is not a security boundary.
|
|
|
234
234
|
|
|
235
235
|
`files` is supported by `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
236
236
|
`interrupt_agent`, `reply_agent`, `delegate_work`, `message_staff`,
|
|
237
|
-
`message_supervisor`, `message_peer`, and `
|
|
238
|
-
relative paths resolve from the calling controller's cwd; for `
|
|
237
|
+
`message_supervisor`, `message_peer`, `notify_owner`, and `await_owner`. For controller actions,
|
|
238
|
+
relative paths resolve from the calling controller's cwd; for `await_owner`, they
|
|
239
239
|
resolve from the managed agent's cwd. Accepted ordinary filesystem paths retain
|
|
240
240
|
canonical absolute-path names; semantic and canonical result refs retain the
|
|
241
241
|
exact supplied reference as the model-facing name.
|
package/docs/guides/recovery.md
CHANGED
|
@@ -40,11 +40,16 @@ Do not intervene solely because a stale threshold was reached.
|
|
|
40
40
|
|
|
41
41
|
The generic attention reasons are `result_error`, live runtime `blocked`, old
|
|
42
42
|
unacknowledged `handoff`, and physical `unknown`. Stale, lost, and delivered
|
|
43
|
-
`
|
|
43
|
+
`await_owner` conditions retain their dedicated message types. A retained
|
|
44
44
|
unacknowledged request must not be duplicated or resubmitted: timeout or lack
|
|
45
45
|
of acknowledgement does not prove non-delivery. `settling` alone does not
|
|
46
46
|
generate generic attention.
|
|
47
47
|
|
|
48
|
+
An Agent may remain `settling` after its result is delivered while accepted
|
|
49
|
+
`notify_owner` records await receipt in the owner's persisted session history.
|
|
50
|
+
Do not treat a successful Pi message submission as confirmation or close the
|
|
51
|
+
Agent; normal cleanup retries after the receipt is recorded.
|
|
52
|
+
|
|
48
53
|
## Agent is `blocked`
|
|
49
54
|
|
|
50
55
|
A blocked agent still has an active assignment.
|
|
@@ -53,7 +58,7 @@ If the agent is waiting for an owner answer, use `reply_agent` with its exact ag
|
|
|
53
58
|
|
|
54
59
|
Otherwise inspect the reported external/runtime condition and resolve it using
|
|
55
60
|
only the currently listed actions. A live Herdr runtime reported as `blocked`
|
|
56
|
-
may generate health attention when no `
|
|
61
|
+
may generate health attention when no `await_owner` question exists. This is
|
|
57
62
|
different from a delegating parent whose public projection is `blocked` while
|
|
58
63
|
it waits for direct child work; parent waiting is not, by itself, evidence of
|
|
59
64
|
an externally blocked runtime. Do not delegate a new task to a blocked agent.
|
|
@@ -134,7 +139,7 @@ Do not guess from pane IDs, process appearance, elapsed time, or stale metadata.
|
|
|
134
139
|
|
|
135
140
|
Physical `unknown` remains fail-closed: it has no mutation actions and receives
|
|
136
141
|
at most one generic attention event for an unresolved episode. Do not infer
|
|
137
|
-
loss, guess a pane or process, or use `
|
|
142
|
+
loss, guess a pane or process, or use `await_owner` as a generic escalation path.
|
|
138
143
|
Refresh with `list_agents` and resolve the identity/lifecycle condition when new exact
|
|
139
144
|
evidence is available. If a cleanup or recovery error is present, inspect its
|
|
140
145
|
exact details.
|