pi-herdsman 0.44.0 → 0.45.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 +39 -0
- package/SKILL.md +10 -8
- package/dist/index.js +1021 -353
- package/dist/index.js.map +3 -3
- package/docs/README.md +2 -1
- package/docs/concepts/coordination.md +8 -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 +15 -14
- package/docs/guides/agent-definitions.md +1 -1
- package/docs/guides/customizing-agents.md +1 -1
- package/docs/guides/handoffs.md +5 -5
- package/docs/guides/recovery.md +8 -3
- package/docs/reference/agent-definition-schema.md +6 -6
- package/docs/reference/agent-states.md +4 -4
- package/docs/reference/agent.md +23 -6
- package/docs/reference/{ask-owner.md → await-owner.md} +8 -8
- package/docs/reference/notify-owner.md +51 -0
- package/docs/reference/supervisor.md +2 -1
- package/package.json +5 -5
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)
|
|
@@ -209,14 +209,14 @@ live in [Staff tools](../reference/staff.md).
|
|
|
209
209
|
|
|
210
210
|
Coordination crosses one authority edge at a time:
|
|
211
211
|
|
|
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 / `
|
|
212
|
+
| Direction | Interface | Boundary |
|
|
213
|
+
| --------- | ------------------------------------------------------------- | --------------------------------------------------- |
|
|
214
|
+
| Up | `message_supervisor` / automatic results | Assigned Lead -> Manager |
|
|
215
|
+
| Down | `message_staff` / project operations | Manager -> assigned Lead |
|
|
216
|
+
| Up | `message_supervisor` | Ordinary Lead -> Manager or Chief; Manager -> Chief |
|
|
217
|
+
| Down | `message_staff` | Manager -> ordinary Lead (cooperative steering) |
|
|
218
|
+
| Sideways | `message_peer` | Lead <-> Lead or Manager <-> Manager |
|
|
219
|
+
| Ownership | Agent controls / `notify_owner`, `await_owner`, `reply_agent` | owner <-> directly owned Agent |
|
|
220
220
|
|
|
221
221
|
### Coordination does not imply dependency
|
|
222
222
|
|
|
@@ -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
|
|
@@ -326,8 +327,8 @@ Verify:
|
|
|
326
327
|
Launch a delegating managed agent with an explicit ordinary execution-tool
|
|
327
328
|
allowlist and ask it to delegate one bounded scout task. Verify that it retains
|
|
328
329
|
those ordinary tools and can call all nine coordination tools plus
|
|
329
|
-
`
|
|
330
|
-
and `
|
|
330
|
+
`await_owner`, then verify that the spawned scout is a leaf with its normal tools
|
|
331
|
+
and `await_owner` but no delegation tools. Also verify that role-required tools
|
|
331
332
|
are not removed by `excludeTools`.
|
|
332
333
|
|
|
333
334
|
For a definition with `tools` omitted, verify that launch does not add a
|
|
@@ -363,7 +364,7 @@ Verify the agent obeys that instruction through the expanded private prompt.
|
|
|
363
364
|
Afterward remove the temporary definition and referenced file, confirm discovery
|
|
364
365
|
no longer lists the temporary definition, and verify no repository file changed.
|
|
365
366
|
|
|
366
|
-
## `
|
|
367
|
+
## `await_owner` round trip
|
|
367
368
|
|
|
368
369
|
Owner ask/reply remains manual, unautomated coverage.
|
|
369
370
|
|
|
@@ -371,7 +372,7 @@ Give an agent a task whose correct continuation requires an owner choice.
|
|
|
371
372
|
|
|
372
373
|
Verify:
|
|
373
374
|
|
|
374
|
-
1. agent calls `
|
|
375
|
+
1. agent calls `await_owner` alone;
|
|
375
376
|
2. owner receives one question;
|
|
376
377
|
3. agent becomes `blocked`;
|
|
377
378
|
4. owner replies with exact `reply_agent`;
|
|
@@ -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)
|
|
@@ -320,7 +320,7 @@ append-only and rejects `replace`. A custom replacement prompt does not
|
|
|
320
320
|
automatically preserve Pi's normal system-prompt rules or tool guidelines.
|
|
321
321
|
|
|
322
322
|
Managed agents additionally receive shared herdr agent guidance at launch,
|
|
323
|
-
including the `
|
|
323
|
+
including the `notify_owner` and `await_owner` contracts. This shared guidance is infrastructure and
|
|
324
324
|
is not copied into every bundled role body. Managed project Leads instead use
|
|
325
325
|
the effective `managed-lead` body plus the ordinary Lead runtime charter and
|
|
326
326
|
dynamic project coordination context.
|
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.
|
|
@@ -51,7 +51,7 @@ ordinary Pi tool selection.
|
|
|
51
51
|
|
|
52
52
|
Code Mode does not add `bash`, `edit`, or `write` to a role's tool policy.
|
|
53
53
|
Ordinary Lead profiles with explicit tools also enforce that policy during
|
|
54
|
-
nested tool execution. `
|
|
54
|
+
nested tool execution. `await_owner` remains model-only and cannot be called from
|
|
55
55
|
Code Mode scripts. `delegate_agent` and `continue_agent` are direct tools when
|
|
56
56
|
active for the role; they return after acceptance, while completion arrives
|
|
57
57
|
through the normal result-delivery mechanism. Other extensions may have
|
|
@@ -267,7 +267,7 @@ the fallback.
|
|
|
267
267
|
| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `false` | spawning controller for fresh `delegate`; saved session for `continue` | Explicit value wins; `false` launches as `off`. |
|
|
268
268
|
| `systemPromptMode` | `append` or `replace` | `append` | Controls whether the effective body is appended to or replaces Pi's base system prompt. `replace` is an explicit escape hatch for ordinary custom definitions; `managed-lead` rejects it. |
|
|
269
269
|
| `bodyMode` | `append` or `replace` | `replace` for non-empty matching overlay body | Valid only when overlaying an existing lower-precedence definition; consumed during body composition. |
|
|
270
|
-
| `noTools` | boolean | Pi normal tool policy | `true` emits `--no-tools`; managed `
|
|
270
|
+
| `noTools` | boolean | Pi normal tool policy | `true` emits `--no-tools`; managed `await_owner` and `notify_owner` remain infrastructure. |
|
|
271
271
|
| `noBuiltinTools` | boolean | Pi normal built-in tool policy | `true` emits `--no-builtin-tools`. |
|
|
272
272
|
| `tools` | array of non-empty strings | no explicit allowlist | Passed to Pi as a source-agnostic tool-name allowlist; matching overlay replaces whole array. |
|
|
273
273
|
| `excludeTools` | array of non-empty strings | no explicit exclusions | Passed to Pi as source-agnostic tool-name exclusions; matching override replaces whole array. |
|
|
@@ -378,7 +378,7 @@ ordinary tools permit it unless one of those opt-outs applies. An omitted or
|
|
|
378
378
|
empty `agents` list always makes the agent a leaf, as does reaching the
|
|
379
379
|
configured `maxAgentDepth` (see [Configuration](configuration.md)); the depth
|
|
380
380
|
limit applies even to a definition that lists `agents`. Every managed agent
|
|
381
|
-
receives `
|
|
381
|
+
receives `await_owner` and `notify_owner`.
|
|
382
382
|
|
|
383
383
|
The tool name `agent` is configuration-policy evidence only; it is not
|
|
384
384
|
registered or callable. In `tools`, it opts into delegation when `noTools: true`
|
|
@@ -387,7 +387,7 @@ leaf, `agent` is removed from its `tools` list.
|
|
|
387
387
|
|
|
388
388
|
`tools` and `excludeTools` configure ordinary execution tools, not this
|
|
389
389
|
mandatory role infrastructure. They cannot remove required coordination tools
|
|
390
|
-
or `
|
|
390
|
+
or `await_owner` and `notify_owner`. When `tools` is omitted, Pi Herdsman emits no `--tools` option
|
|
391
391
|
and Pi's configured/default selection remains in effect. An explicit `tools`
|
|
392
392
|
allowlist is augmented with the managed agent's mandatory role tools; the
|
|
393
393
|
configuration-only `agent` name is excluded from that allowlist.
|
|
@@ -511,8 +511,8 @@ Additional local review instructions.
|
|
|
511
511
|
```
|
|
512
512
|
|
|
513
513
|
Because `agents` is non-empty, and none of the delegation opt-outs apply, this
|
|
514
|
-
managed agent receives all nine coordination tools and `
|
|
515
|
-
addition to the explicitly selected ordinary tools.
|
|
514
|
+
managed agent receives all nine coordination tools and `await_owner` and
|
|
515
|
+
`notify_owner`, in addition to the explicitly selected ordinary tools.
|
|
516
516
|
|
|
517
517
|
To disable a bundled role without copying its definition, use a minimal global
|
|
518
518
|
override:
|
|
@@ -20,7 +20,7 @@ Use only tools currently listed there; do not infer control eligibility
|
|
|
20
20
|
from `state` alone. `steer_agent` means active work accepts cooperative steering,
|
|
21
21
|
`interrupt_agent` means a currently working Pi operation may be preempted,
|
|
22
22
|
superseding earlier undelivered steering with replacement direction,
|
|
23
|
-
`reply_agent` means a correlated pending `
|
|
23
|
+
`reply_agent` means a correlated pending `await_owner` is valid, and
|
|
24
24
|
`stop_agent` means exact direct ownership and the current applicable stop
|
|
25
25
|
preflight permit teardown. For a
|
|
26
26
|
Lead-owned parent, that preflight includes its owned descendant cascade.
|
|
@@ -46,7 +46,7 @@ non-direct descendants remain fail-closed with no actions.
|
|
|
46
46
|
|
|
47
47
|
## `blocked` and owner questions
|
|
48
48
|
|
|
49
|
-
An agent waiting on a valid `
|
|
49
|
+
An agent waiting on a valid `await_owner` reply projects as `blocked` after its ask
|
|
50
50
|
turn settles. Answer through the exact direct owner using `reply_agent` with the exact `agent` identity.
|
|
51
51
|
|
|
52
52
|
A delegating parent can also project as `blocked` while it waits for direct
|
|
@@ -56,7 +56,7 @@ work may advertise `steer_agent` while remaining `blocked`; only the managed
|
|
|
56
56
|
receiver's acknowledgement confirms acceptance. It does not advertise
|
|
57
57
|
`interrupt_agent` unless a Pi operation is working. Recovery attention for
|
|
58
58
|
`blocked` is reserved for a live Herdr runtime that reports `blocked` while an
|
|
59
|
-
active request exists and no `
|
|
59
|
+
active request exists and no `await_owner` question is pending.
|
|
60
60
|
|
|
61
61
|
## `settling`
|
|
62
62
|
|
|
@@ -90,7 +90,7 @@ model metadata, missing activity, a guessed session, or an old agent identity.
|
|
|
90
90
|
|
|
91
91
|
When physical identity is ambiguous for an otherwise valid direct-owned record,
|
|
92
92
|
Herdsman may emit one generic `unknown` attention event for that unresolved
|
|
93
|
-
episode. It does not add mutation actions, prove loss, or broaden `
|
|
93
|
+
episode. It does not add mutation actions, prove loss, or broaden `await_owner`.
|
|
94
94
|
When exact physical evidence changes, re-evaluate the record from fresh state.
|
|
95
95
|
|
|
96
96
|
`lost` is different: a coherent Herdr inventory proves the expected pane,
|
package/docs/reference/agent.md
CHANGED
|
@@ -16,6 +16,7 @@ inspect_agent
|
|
|
16
16
|
read_agent_transcript
|
|
17
17
|
read_evidence
|
|
18
18
|
attach_handoff
|
|
19
|
+
notify_owner
|
|
19
20
|
```
|
|
20
21
|
|
|
21
22
|
Each tool accepts only its operation's fields. Schemas require necessary fields
|
|
@@ -256,7 +257,7 @@ covers the complete owned descendant cascade at every depth because closing the
|
|
|
256
257
|
parent closes that cascade child-first. Invocation always reacquires current evidence and revalidates
|
|
257
258
|
identity, ownership, mailbox state, durable results, and lifecycle before
|
|
258
259
|
mutation. Active work may list `steer_agent`; a valid correlated pending
|
|
259
|
-
`
|
|
260
|
+
`await_owner` may list `reply_agent`. A currently working agent may list
|
|
260
261
|
`interrupt_agent`; a delegating agent blocked while waiting on children may
|
|
261
262
|
still list `steer_agent` but not `interrupt_agent`.
|
|
262
263
|
`available_tools` never lists `delegate_agent` or `continue_agent`: these are
|
|
@@ -304,6 +305,15 @@ attention event is an advisory snapshot of current authority; every later
|
|
|
304
305
|
`steer_agent`, `interrupt_agent`, `reply_agent`, or `stop_agent` call revalidates identity, ownership,
|
|
305
306
|
mailbox state, and lifecycle.
|
|
306
307
|
|
|
308
|
+
When several attention conditions are due in one scan, Herdsman submits their
|
|
309
|
+
original, independently identifiable messages together, with one triggering
|
|
310
|
+
message to wake the idle owner. Collection is limited by the existing
|
|
311
|
+
recipient fan-in message and byte budgets; overflow remains eligible for a
|
|
312
|
+
later scan. This scan-local budget is separate from the subsequent startup
|
|
313
|
+
fan-in budget. A scan attempts at most one first-time stale live diagnostic,
|
|
314
|
+
so additional initial stale inspections wait for another scan. Submission is
|
|
315
|
+
best-effort and is not an acknowledgment that the owner consumed a message.
|
|
316
|
+
|
|
307
317
|
Persistent actionable attention may repeat while the same condition remains
|
|
308
318
|
unresolved. Reminder timing is process-local and advisory, not a mailbox API;
|
|
309
319
|
restarting may cause an unresolved condition to be reminded again. The normal
|
|
@@ -322,14 +332,14 @@ Generic attention reasons are:
|
|
|
322
332
|
|
|
323
333
|
- `result_error`: a terminal result could not be durably persisted; follow the
|
|
324
334
|
stored recovery details and `nextAction`;
|
|
325
|
-
- `blocked`: the live Herdr runtime is blocked without a pending `
|
|
335
|
+
- `blocked`: the live Herdr runtime is blocked without a pending `await_owner`
|
|
326
336
|
question;
|
|
327
337
|
- `handoff`: an old durable request remains unacknowledged; do not duplicate or
|
|
328
338
|
resubmit it because non-acknowledgement does not prove non-delivery;
|
|
329
339
|
- `unknown`: physical identity is ambiguous and remains fail-closed, with no
|
|
330
340
|
mutation actions and at most one attention event per episode.
|
|
331
341
|
|
|
332
|
-
Stale and lost assignments, and delivered `
|
|
342
|
+
Stale and lost assignments, and delivered `await_owner` questions, retain their
|
|
333
343
|
dedicated message types. Stale attention is advisory and does not by itself
|
|
334
344
|
justify intervention. `settling` alone does not generate generic attention.
|
|
335
345
|
The public `blocked` projection can also mean that a delegating parent is
|
|
@@ -339,7 +349,7 @@ from a live Herdr runtime reporting `blocked`.
|
|
|
339
349
|
Initial attention eligibility is: stale after ten minutes without qualifying
|
|
340
350
|
progress; lost, `result_error`, live runtime `blocked`, and physical `unknown`
|
|
341
351
|
immediately; an old retained handoff after ten minutes; and a delivered
|
|
342
|
-
`
|
|
352
|
+
`await_owner` reminder approximately five minutes after health reconciliation
|
|
343
353
|
first observes that the original ask was successfully delivered. The reminder
|
|
344
354
|
path never duplicates first ask delivery. Unknown is the exception to repeated
|
|
345
355
|
attention: it is one notification per unresolved physical-identity episode.
|
|
@@ -543,6 +553,13 @@ child editor.
|
|
|
543
553
|
Cancellation uses Pi's native abort mechanism. Non-cooperative third-party
|
|
544
554
|
tools may not stop immediately; `stop_agent` remains the destructive fallback.
|
|
545
555
|
|
|
556
|
+
## `notify_owner`
|
|
557
|
+
|
|
558
|
+
Use `notify_owner` to send material information to your exact direct owner
|
|
559
|
+
while continuing the active assignment. It is nonblocking, accepts optional
|
|
560
|
+
evidence files, and does not create a reply obligation. See the
|
|
561
|
+
[`notify_owner` API](notify-owner.md) for acceptance and delivery semantics.
|
|
562
|
+
|
|
546
563
|
## `reply_agent`
|
|
547
564
|
|
|
548
565
|
```json
|
|
@@ -553,10 +570,10 @@ tools may not stop immediately; `stop_agent` remains the destructive fallback.
|
|
|
553
570
|
```
|
|
554
571
|
|
|
555
572
|
Call `reply_agent` only when `available_tools` lists it for a valid correlated
|
|
556
|
-
pending `
|
|
573
|
+
pending `await_owner` question. The reply continues the same assignment and
|
|
557
574
|
contains its request, ask, assignment, and session correlation evidence.
|
|
558
575
|
|
|
559
|
-
See [`
|
|
576
|
+
See [`await_owner` API](await-owner.md).
|
|
560
577
|
|
|
561
578
|
## `stop_agent`
|
|
562
579
|
|
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# `
|
|
1
|
+
# `await_owner` API
|
|
2
2
|
|
|
3
3
|
[Documentation index](../README.md)
|
|
4
4
|
|
|
5
|
-
`
|
|
5
|
+
`await_owner` is mandatory managed agent infrastructure for one direct-owner
|
|
6
6
|
decision required to continue the current assignment.
|
|
7
7
|
|
|
8
8
|
It is not a generic messaging channel.
|
|
9
9
|
|
|
10
10
|
## Availability
|
|
11
11
|
|
|
12
|
-
Every valid managed agent receives the `
|
|
12
|
+
Every valid managed agent receives the `await_owner` tool at launch.
|
|
13
13
|
|
|
14
14
|
Normal definition `tools`, `excludeTools`, and `noTools` policy cannot remove
|
|
15
15
|
this infrastructure capability.
|
|
@@ -37,7 +37,7 @@ working directory. This does not weaken the sole-final-tool-call rule.
|
|
|
37
37
|
|
|
38
38
|
## Turn rule
|
|
39
39
|
|
|
40
|
-
`
|
|
40
|
+
`await_owner` must be:
|
|
41
41
|
|
|
42
42
|
- the agent's only tool call in the turn;
|
|
43
43
|
- the final tool call of the turn.
|
|
@@ -59,8 +59,8 @@ An agent can ask only while it has a valid active assignment and:
|
|
|
59
59
|
|
|
60
60
|
For a delegation-enabled agent, direct-agent state adds one gate:
|
|
61
61
|
|
|
62
|
-
- no unresolved direct-agent work leaves normal `
|
|
63
|
-
- if unresolved direct agents exist, every unresolved child must have a valid pending `
|
|
62
|
+
- no unresolved direct-agent work leaves normal `await_owner` eligibility unchanged;
|
|
63
|
+
- if unresolved direct agents exist, every unresolved child must have a valid pending `await_owner`;
|
|
64
64
|
- ordinary active children, pending results, result errors, or unverifiable child asks block escalation.
|
|
65
65
|
|
|
66
66
|
## Durable effect
|
|
@@ -88,7 +88,7 @@ delivery path.
|
|
|
88
88
|
The system does not automatically forward an agent question through an ownership
|
|
89
89
|
chain.
|
|
90
90
|
|
|
91
|
-
If a delegating agent needs a lead decision, it independently calls `
|
|
91
|
+
If a delegating agent needs a lead decision, it independently calls `await_owner`
|
|
92
92
|
on its own direct ownership edge.
|
|
93
93
|
|
|
94
94
|
## Reply
|
|
@@ -120,7 +120,7 @@ the same assignment with the owner answer.
|
|
|
120
120
|
|
|
121
121
|
## One outstanding question
|
|
122
122
|
|
|
123
|
-
Only one `
|
|
123
|
+
Only one `await_owner` question may be outstanding per assignment at a time.
|
|
124
124
|
|
|
125
125
|
There is no ask timeout.
|
|
126
126
|
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# `notify_owner` API
|
|
2
|
+
|
|
3
|
+
[Documentation index](../README.md)
|
|
4
|
+
|
|
5
|
+
`notify_owner` sends material information to a managed Agent's exact direct
|
|
6
|
+
owner without blocking the assignment or requiring a reply.
|
|
7
|
+
|
|
8
|
+
## Availability and request
|
|
9
|
+
|
|
10
|
+
Every valid managed Agent receives the tool, including leaf Agents and
|
|
11
|
+
Agents with active child work. It is available through direct Pi tool dispatch.
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"message": "The upstream API changed; I am adapting the implementation.",
|
|
16
|
+
"files": ["findings.md"]
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`message` must contain non-whitespace text. Optional `files` use the same
|
|
21
|
+
strict UTF-8 and result-binding rules as managed-Agent handoffs. File content
|
|
22
|
+
is resolved and snapshotted before the notification is accepted.
|
|
23
|
+
|
|
24
|
+
## Acceptance and delivery
|
|
25
|
+
|
|
26
|
+
Acceptance requires a valid active assignment that is not settling. Herdsman
|
|
27
|
+
atomically stores the notification in the Agent mailbox before reporting
|
|
28
|
+
success. At most eight undelivered notifications may be outstanding for one
|
|
29
|
+
Agent; a rejected call does not remove previously accepted records.
|
|
30
|
+
|
|
31
|
+
The notification goes only to the exact direct owner. Pi's persisted owner
|
|
32
|
+
session history confirms receipt. A successful message submission is not
|
|
33
|
+
confirmation; unresolved records remain durable and are reconciled after
|
|
34
|
+
restart. Because Pi message submission is asynchronous, recovery may replay a
|
|
35
|
+
notification if interruption occurred before its receipt became visible.
|
|
36
|
+
Delivery is therefore recoverable and may be at-least-once, not exactly-once.
|
|
37
|
+
|
|
38
|
+
Notifications do not set `pendingAskId`, block completion, or create a reply
|
|
39
|
+
obligation. The owner may use `steer_agent` when that operation is eligible.
|
|
40
|
+
Ordinary Agent cleanup waits until accepted notifications have confirmed
|
|
41
|
+
receipts. Explicit `stop_agent` retains its intentional abandonment behavior.
|
|
42
|
+
|
|
43
|
+
## Choosing the owner tool
|
|
44
|
+
|
|
45
|
+
Use `notify_owner` when your direct owner needs material information but you
|
|
46
|
+
can continue working. Use `await_owner` only when your assignment cannot
|
|
47
|
+
proceed without the owner's answer. After an accepted `await_owner` call, end
|
|
48
|
+
your turn; Herdsman retains the blocked assignment until the owner replies.
|
|
49
|
+
|
|
50
|
+
See [`await_owner`](await-owner.md) for the blocking, correlated request
|
|
51
|
+
contract and [Agent tools](agent.md) for `steer_agent`.
|