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.
@@ -1,15 +1,15 @@
1
- # `ask_owner` API
1
+ # `await_owner` API
2
2
 
3
3
  [Documentation index](../README.md)
4
4
 
5
- `ask_owner` is mandatory managed agent infrastructure for one direct-owner
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 `ask_owner` tool at launch.
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
- `ask_owner` must be:
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 `ask_owner` eligibility unchanged;
63
- - if unresolved direct agents exist, every unresolved child must have a valid pending `ask_owner`;
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 `ask_owner`
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 `ask_owner` question may be outstanding per assignment at a time.
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`.
@@ -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. Other validation or Git-state uncertainty
355
- fails closed; a `blocked` result may require inspecting the primary checkout
356
- before retrying.
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 `ask_owner` to contact their exact owner.
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.43.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.0",
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.0",
87
- "@earendil-works/pi-coding-agent": "1.5.0",
88
- "@earendil-works/pi-tui": "1.5.0",
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",