pi-herdsman 0.43.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 +59 -0
- package/SKILL.md +10 -8
- package/dist/index.js +1496 -423
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js.map +2 -2
- package/docs/README.md +2 -1
- package/docs/concepts/coordination.md +16 -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/project-orchestration.md +10 -2
- package/docs/guides/recovery.md +8 -3
- package/docs/reference/agent-definition-schema.md +12 -12
- 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/staff.md +11 -3
- package/docs/reference/supervisor.md +2 -1
- package/package.json +5 -5
|
@@ -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`.
|
package/docs/reference/staff.md
CHANGED
|
@@ -341,6 +341,13 @@ preflight unavailable on older Git returns `blocked`. Git success does not
|
|
|
341
341
|
prove tests or semantic acceptance; obtain required combined validation before
|
|
342
342
|
acceptance.
|
|
343
343
|
|
|
344
|
+
New integration requires a matching completed Lead handoff for the accepted
|
|
345
|
+
source revision and no unresolved assigned execution. A visible Git SHA, idle
|
|
346
|
+
status, or interim supervisor message is insufficient. If completion evidence
|
|
347
|
+
is missing or stale, wait for the normal handoff or request a fresh completion
|
|
348
|
+
report; do not poll staff or integration tools. A completed handoff confirms
|
|
349
|
+
the report boundary, not that tests passed or requirements were met.
|
|
350
|
+
|
|
344
351
|
The structured result reports `status`, `integrated`, `checkout_removed`, and
|
|
345
352
|
`assignment_retired` independently. `needs_update` leaves both checkouts
|
|
346
353
|
untouched. Successful integration triggers guarded cleanup of the exact
|
|
@@ -351,9 +358,10 @@ same accepted SHA rechecks the exact assignment and policy and retries
|
|
|
351
358
|
guarded cleanup. If the checkout is already absent, it is reconciled only
|
|
352
359
|
after fresh Git evidence proves the accepted SHA is contained in the verified
|
|
353
360
|
primary branch, plus checkout provenance and exact-assignment checks. Absence
|
|
354
|
-
alone never proves integration.
|
|
355
|
-
|
|
356
|
-
|
|
361
|
+
alone never proves integration. An already-integrated accepted SHA follows
|
|
362
|
+
this existing cleanup-recovery path rather than requiring a new completion
|
|
363
|
+
handoff. Other validation or Git-state uncertainty fails closed; a `blocked`
|
|
364
|
+
result may require inspecting the primary checkout before retrying.
|
|
357
365
|
|
|
358
366
|
## See also
|
|
359
367
|
|
|
@@ -6,7 +6,8 @@
|
|
|
6
6
|
assigned project Lead contacts its Manager through project messaging. An
|
|
7
7
|
ordinary Lead in a verified project worktree group contacts its active project
|
|
8
8
|
Manager; otherwise it contacts Chief when available. A Manager contacts Chief.
|
|
9
|
-
Managed Agents use `
|
|
9
|
+
Managed Agents use `notify_owner` for nonblocking material information and
|
|
10
|
+
`await_owner` when they cannot continue without their exact owner's answer.
|
|
10
11
|
|
|
11
12
|
An ordinary Lead without a verified supervisor continues independently. An
|
|
12
13
|
assigned Lead's Manager role remains its authority even when no Manager process
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-herdsman",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.45.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
},
|
|
50
50
|
"piHerdsman": {
|
|
51
51
|
"runtime": {
|
|
52
|
-
"pi": "1.5.
|
|
52
|
+
"pi": "1.5.2",
|
|
53
53
|
"herdr": {
|
|
54
54
|
"version": "0.9.5",
|
|
55
55
|
"sha256": {
|
|
@@ -83,9 +83,9 @@
|
|
|
83
83
|
"typebox": "*"
|
|
84
84
|
},
|
|
85
85
|
"devDependencies": {
|
|
86
|
-
"@earendil-works/pi-ai": "1.5.
|
|
87
|
-
"@earendil-works/pi-coding-agent": "1.5.
|
|
88
|
-
"@earendil-works/pi-tui": "1.5.
|
|
86
|
+
"@earendil-works/pi-ai": "1.5.2",
|
|
87
|
+
"@earendil-works/pi-coding-agent": "1.5.2",
|
|
88
|
+
"@earendil-works/pi-tui": "1.5.2",
|
|
89
89
|
"@howaboua/pi-codex-conversion": "4.0.4",
|
|
90
90
|
"@modelcontextprotocol/sdk": "1.32.0",
|
|
91
91
|
"@types/node": "22.19.19",
|