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
|
@@ -38,8 +38,33 @@ skills:
|
|
|
38
38
|
|
|
39
39
|
Unknown frontmatter fields fail validation.
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
Array fields (`tools`, `excludeTools`, `skills`, `extensions`, and
|
|
42
|
+
`agents`) replace the inherited array when they contain only plain values.
|
|
43
|
+
An empty array explicitly clears the inherited values. A list containing
|
|
44
|
+
`+name` or `-name` entries modifies an inherited array: additions are
|
|
45
|
+
appended once, removals delete matching values, and removing a missing value is
|
|
46
|
+
a no-op. In a mixed list, plain values form the replacement base before the
|
|
47
|
+
modifiers are applied. Tool entries continue to accept comma-separated names;
|
|
48
|
+
the other array fields treat each item as one complete path or name.
|
|
49
|
+
|
|
50
|
+
For example, a matching Agent overlay can add a skill without copying inherited
|
|
51
|
+
skills:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
skills: ["+/absolute/path/to/review/SKILL.md"]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
A modifier-only `tools` list with no explicit inherited tool list remains
|
|
58
|
+
relative to Pi's normal or active tool selection. It does not create a closed
|
|
59
|
+
allowlist. Explicit removals are enforced at dispatch, including nested Code
|
|
60
|
+
Mode calls; `excludeTools` remains an additional exclusion policy. Tool
|
|
61
|
+
modifiers require exact names (no wildcards). Use a plain `tools` list for a
|
|
62
|
+
closed allowlist, and `excludeTools` for wildcard exclusions.
|
|
63
|
+
|
|
64
|
+
An omitted `agents` field retains each profile's default. Leads remain
|
|
65
|
+
unrestricted when omitted, so a modifier-only `agents` overlay requires an
|
|
66
|
+
explicit inherited allowlist; Manager, Chief, and ordinary Agents default to no
|
|
67
|
+
direct Agent delegation and can add names from that empty default.
|
|
43
68
|
|
|
44
69
|
Bundled Agents and the managed Lead enable Pi's native `codemode` by default.
|
|
45
70
|
Definitions that specify `noExtensions: true` also load only
|
|
@@ -51,7 +76,7 @@ ordinary Pi tool selection.
|
|
|
51
76
|
|
|
52
77
|
Code Mode does not add `bash`, `edit`, or `write` to a role's tool policy.
|
|
53
78
|
Ordinary Lead profiles with explicit tools also enforce that policy during
|
|
54
|
-
nested tool execution. `
|
|
79
|
+
nested tool execution. `await_owner` remains model-only and cannot be called from
|
|
55
80
|
Code Mode scripts. `delegate_agent` and `continue_agent` are direct tools when
|
|
56
81
|
active for the role; they return after acceptance, while completion arrives
|
|
57
82
|
through the normal result-delivery mechanism. Other extensions may have
|
|
@@ -267,7 +292,7 @@ the fallback.
|
|
|
267
292
|
| `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
293
|
| `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
294
|
| `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 `
|
|
295
|
+
| `noTools` | boolean | Pi normal tool policy | `true` emits `--no-tools`; managed `await_owner` and `notify_owner` remain infrastructure. |
|
|
271
296
|
| `noBuiltinTools` | boolean | Pi normal built-in tool policy | `true` emits `--no-builtin-tools`. |
|
|
272
297
|
| `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
298
|
| `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 +403,7 @@ ordinary tools permit it unless one of those opt-outs applies. An omitted or
|
|
|
378
403
|
empty `agents` list always makes the agent a leaf, as does reaching the
|
|
379
404
|
configured `maxAgentDepth` (see [Configuration](configuration.md)); the depth
|
|
380
405
|
limit applies even to a definition that lists `agents`. Every managed agent
|
|
381
|
-
receives `
|
|
406
|
+
receives `await_owner` and `notify_owner`.
|
|
382
407
|
|
|
383
408
|
The tool name `agent` is configuration-policy evidence only; it is not
|
|
384
409
|
registered or callable. In `tools`, it opts into delegation when `noTools: true`
|
|
@@ -387,7 +412,7 @@ leaf, `agent` is removed from its `tools` list.
|
|
|
387
412
|
|
|
388
413
|
`tools` and `excludeTools` configure ordinary execution tools, not this
|
|
389
414
|
mandatory role infrastructure. They cannot remove required coordination tools
|
|
390
|
-
or `
|
|
415
|
+
or `await_owner` and `notify_owner`. When `tools` is omitted, Pi Herdsman emits no `--tools` option
|
|
391
416
|
and Pi's configured/default selection remains in effect. An explicit `tools`
|
|
392
417
|
allowlist is augmented with the managed agent's mandatory role tools; the
|
|
393
418
|
configuration-only `agent` name is excluded from that allowlist.
|
|
@@ -511,8 +536,8 @@ Additional local review instructions.
|
|
|
511
536
|
```
|
|
512
537
|
|
|
513
538
|
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.
|
|
539
|
+
managed agent receives all nine coordination tools and `await_owner` and
|
|
540
|
+
`notify_owner`, in addition to the explicitly selected ordinary tools.
|
|
516
541
|
|
|
517
542
|
To disable a bundled role without copying its definition, use a minimal global
|
|
518
543
|
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
|
|
@@ -97,44 +98,55 @@ During synchronous `prepare` event dispatch, listeners may synchronously call
|
|
|
97
98
|
`register(id, prepare)`. IDs must be unique within a spawn and match
|
|
98
99
|
`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$`. Herdsman then sequentially awaits each
|
|
99
100
|
registered callback. Return `undefined` to opt out, or return an opaque string
|
|
100
|
-
payload and optional parent-side commit callback
|
|
101
|
+
payload and optional parent-side commit callback. A participant that needs the
|
|
102
|
+
child's native Pi session ID may call `reserveChildSessionId()` during
|
|
103
|
+
preparation:
|
|
101
104
|
|
|
102
105
|
```ts
|
|
103
106
|
pi.events.on("pi-herdsman:managed-agent-bootstrap", (value) => {
|
|
104
107
|
const event = value as any;
|
|
105
108
|
if (event.protocol !== 1 || event.phase !== "prepare") return;
|
|
106
|
-
event.register("example/
|
|
107
|
-
const
|
|
109
|
+
event.register("example/session-aware", async () => {
|
|
110
|
+
const childSessionId = event.reserveChildSessionId();
|
|
108
111
|
return {
|
|
109
|
-
payload:
|
|
110
|
-
commit: () =>
|
|
112
|
+
payload: JSON.stringify({ childSessionId }),
|
|
113
|
+
commit: async () => {
|
|
114
|
+
// Optional parent-side finalization after child readiness.
|
|
115
|
+
},
|
|
111
116
|
};
|
|
112
117
|
});
|
|
113
118
|
});
|
|
114
119
|
```
|
|
115
120
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
121
|
+
The reservation is generated by Herdsman, is valid only during preparation,
|
|
122
|
+
and all participants in that delegation receive the same ID. It applies only
|
|
123
|
+
to a fresh child; continuation does not prepare, reserve, initialize, or commit
|
|
124
|
+
bootstrap participants. A reservation is used only if at least one participant
|
|
125
|
+
returns payload data. Herdsman transports opaque data without interpreting
|
|
126
|
+
extension-owned semantics. Preparation must be safe to abandon if launch fails;
|
|
127
|
+
durable parent-side finalization belongs in the optional commit callback.
|
|
128
|
+
|
|
129
|
+
Each prepared participant must implement a matching child `initialize`
|
|
130
|
+
listener and validate its own payload. Exactly one matching child extension
|
|
131
|
+
must synchronously call `accept(initialize)` during event dispatch. Herdsman
|
|
132
|
+
invokes and awaits initializers sequentially after all Pi `session_start`
|
|
133
|
+
handlers have completed, but before publishing managed state or readiness.
|
|
134
|
+
Bootstrap storage is transient and removed before readiness. The participant
|
|
135
|
+
owns payload serialization, compatibility, and interpretation. The aggregate
|
|
136
|
+
bootstrap sidecar is limited to 64 KiB.
|
|
137
|
+
|
|
138
|
+
A missing or duplicate initializer, a rejected or throwing initializer, a
|
|
139
|
+
build/identity mismatch, invalid participant data, or an oversized payload
|
|
140
|
+
fails startup. No task is delivered and the existing startup rollback applies.
|
|
141
|
+
After normal child readiness and identity/integration validation, Herdsman
|
|
142
|
+
awaits parent commit callbacks before it delivers the first assignment. With no
|
|
143
|
+
participant data, delegation follows its ordinary startup path.
|
|
144
|
+
|
|
145
|
+
The child publishes a transient startup outcome only after initialization and
|
|
146
|
+
request observation are complete. The parent requires a matching ready outcome
|
|
147
|
+
and valid state before submitting an assignment; the assignment still requires
|
|
148
|
+
its own acknowledgement. Startup outcomes do not establish continuing
|
|
149
|
+
liveness.
|
|
138
150
|
|
|
139
151
|
## `continue_agent`
|
|
140
152
|
|
|
@@ -256,7 +268,7 @@ covers the complete owned descendant cascade at every depth because closing the
|
|
|
256
268
|
parent closes that cascade child-first. Invocation always reacquires current evidence and revalidates
|
|
257
269
|
identity, ownership, mailbox state, durable results, and lifecycle before
|
|
258
270
|
mutation. Active work may list `steer_agent`; a valid correlated pending
|
|
259
|
-
`
|
|
271
|
+
`await_owner` may list `reply_agent`. A currently working agent may list
|
|
260
272
|
`interrupt_agent`; a delegating agent blocked while waiting on children may
|
|
261
273
|
still list `steer_agent` but not `interrupt_agent`.
|
|
262
274
|
`available_tools` never lists `delegate_agent` or `continue_agent`: these are
|
|
@@ -304,6 +316,15 @@ attention event is an advisory snapshot of current authority; every later
|
|
|
304
316
|
`steer_agent`, `interrupt_agent`, `reply_agent`, or `stop_agent` call revalidates identity, ownership,
|
|
305
317
|
mailbox state, and lifecycle.
|
|
306
318
|
|
|
319
|
+
When several attention conditions are due in one scan, Herdsman submits their
|
|
320
|
+
original, independently identifiable messages together, with one triggering
|
|
321
|
+
message to wake the idle owner. Collection is limited by the existing
|
|
322
|
+
recipient fan-in message and byte budgets; overflow remains eligible for a
|
|
323
|
+
later scan. This scan-local budget is separate from the subsequent startup
|
|
324
|
+
fan-in budget. A scan attempts at most one first-time stale live diagnostic,
|
|
325
|
+
so additional initial stale inspections wait for another scan. Submission is
|
|
326
|
+
best-effort and is not an acknowledgment that the owner consumed a message.
|
|
327
|
+
|
|
307
328
|
Persistent actionable attention may repeat while the same condition remains
|
|
308
329
|
unresolved. Reminder timing is process-local and advisory, not a mailbox API;
|
|
309
330
|
restarting may cause an unresolved condition to be reminded again. The normal
|
|
@@ -322,14 +343,14 @@ Generic attention reasons are:
|
|
|
322
343
|
|
|
323
344
|
- `result_error`: a terminal result could not be durably persisted; follow the
|
|
324
345
|
stored recovery details and `nextAction`;
|
|
325
|
-
- `blocked`: the live Herdr runtime is blocked without a pending `
|
|
346
|
+
- `blocked`: the live Herdr runtime is blocked without a pending `await_owner`
|
|
326
347
|
question;
|
|
327
348
|
- `handoff`: an old durable request remains unacknowledged; do not duplicate or
|
|
328
349
|
resubmit it because non-acknowledgement does not prove non-delivery;
|
|
329
350
|
- `unknown`: physical identity is ambiguous and remains fail-closed, with no
|
|
330
351
|
mutation actions and at most one attention event per episode.
|
|
331
352
|
|
|
332
|
-
Stale and lost assignments, and delivered `
|
|
353
|
+
Stale and lost assignments, and delivered `await_owner` questions, retain their
|
|
333
354
|
dedicated message types. Stale attention is advisory and does not by itself
|
|
334
355
|
justify intervention. `settling` alone does not generate generic attention.
|
|
335
356
|
The public `blocked` projection can also mean that a delegating parent is
|
|
@@ -339,7 +360,7 @@ from a live Herdr runtime reporting `blocked`.
|
|
|
339
360
|
Initial attention eligibility is: stale after ten minutes without qualifying
|
|
340
361
|
progress; lost, `result_error`, live runtime `blocked`, and physical `unknown`
|
|
341
362
|
immediately; an old retained handoff after ten minutes; and a delivered
|
|
342
|
-
`
|
|
363
|
+
`await_owner` reminder approximately five minutes after health reconciliation
|
|
343
364
|
first observes that the original ask was successfully delivered. The reminder
|
|
344
365
|
path never duplicates first ask delivery. Unknown is the exception to repeated
|
|
345
366
|
attention: it is one notification per unresolved physical-identity episode.
|
|
@@ -543,6 +564,13 @@ child editor.
|
|
|
543
564
|
Cancellation uses Pi's native abort mechanism. Non-cooperative third-party
|
|
544
565
|
tools may not stop immediately; `stop_agent` remains the destructive fallback.
|
|
545
566
|
|
|
567
|
+
## `notify_owner`
|
|
568
|
+
|
|
569
|
+
Use `notify_owner` to send material information to your exact direct owner
|
|
570
|
+
while continuing the active assignment. It is nonblocking, accepts optional
|
|
571
|
+
evidence files, and does not create a reply obligation. See the
|
|
572
|
+
[`notify_owner` API](notify-owner.md) for acceptance and delivery semantics.
|
|
573
|
+
|
|
546
574
|
## `reply_agent`
|
|
547
575
|
|
|
548
576
|
```json
|
|
@@ -553,10 +581,10 @@ tools may not stop immediately; `stop_agent` remains the destructive fallback.
|
|
|
553
581
|
```
|
|
554
582
|
|
|
555
583
|
Call `reply_agent` only when `available_tools` lists it for a valid correlated
|
|
556
|
-
pending `
|
|
584
|
+
pending `await_owner` question. The reply continues the same assignment and
|
|
557
585
|
contains its request, ask, assignment, and session correlation evidence.
|
|
558
586
|
|
|
559
|
-
See [`
|
|
587
|
+
See [`await_owner` API](await-owner.md).
|
|
560
588
|
|
|
561
589
|
## `stop_agent`
|
|
562
590
|
|
|
@@ -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
|
|
|
@@ -132,6 +132,32 @@ action. Use `/manager refresh` or `/chief refresh` to validate and apply the
|
|
|
132
132
|
active role's definition. Definition files are not watched while a profile is
|
|
133
133
|
active.
|
|
134
134
|
|
|
135
|
+
The `Details…` action appends a read-only inspection entry to the normal Pi chat
|
|
136
|
+
transcript and closes the Definitions menu. The compact entry reports the
|
|
137
|
+
inspection context and preview; use Pi's native `Ctrl+O` expansion to reveal
|
|
138
|
+
sequential instruction sections rendered with Pi's Markdown component.
|
|
139
|
+
Expanded content occupies its natural transcript height and uses ordinary
|
|
140
|
+
terminal scrolling. The inspection snapshot, including applicable context
|
|
141
|
+
text, is saved with the Pi session but is excluded from model context. The
|
|
142
|
+
compact view reports the effective configuration, definition source count,
|
|
143
|
+
selected context-file count, execution context, and preview limitation. The
|
|
144
|
+
expanded sections follow known prompt-input ordering; source headers identify
|
|
145
|
+
instruction files and known runtime contributions. Definition overlays appear
|
|
146
|
+
as concise configuration provenance separate from surviving instruction text. `+` and `-` identify added and removed explicit values;
|
|
147
|
+
`~` identifies changed values or body operations. Context files follow Pi's
|
|
148
|
+
loader order and the Agent's global/project inheritance settings. Configured
|
|
149
|
+
skills and extensions are selections, not proof that those resources loaded.
|
|
150
|
+
For an active Lead or Manager, the expanded view uses the verified role-contract
|
|
151
|
+
producer and current Pi system-prompt options for known context inputs; ordinary
|
|
152
|
+
Lead execution profile text is shown separately. Chief uses its forced-prompt
|
|
153
|
+
producer, which includes applicable global user instructions and excludes
|
|
154
|
+
ordinary project context. Inactive Coordinator profiles are shown prospectively;
|
|
155
|
+
current active contracts are not substituted for them. Managed Lead previews place its append-only definition body and shared guidance
|
|
156
|
+
before inherited context, followed by the verified runtime role section when
|
|
157
|
+
active. Other session-dependent sections are identified as such. The preview
|
|
158
|
+
is not an exact provider prompt: role/session runtime inputs and provider-side
|
|
159
|
+
transformations may add content.
|
|
160
|
+
|
|
135
161
|
The details view shows applicable effective metadata:
|
|
136
162
|
|
|
137
163
|
- name and description;
|
|
@@ -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`.
|
|
@@ -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.46.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": {
|
|
@@ -62,6 +62,8 @@
|
|
|
62
62
|
}
|
|
63
63
|
},
|
|
64
64
|
"scripts": {
|
|
65
|
+
"setup": "npm run setup:hooks && npm ci",
|
|
66
|
+
"setup:hooks": "node scripts/setup-hooks.mjs",
|
|
65
67
|
"test": "node --experimental-test-module-mocks --import=./scripts/test-env.mjs --test --test-timeout=10000",
|
|
66
68
|
"smoke": "node scripts/smoke.mjs",
|
|
67
69
|
"format": "prettier . --write",
|
|
@@ -79,20 +81,18 @@
|
|
|
79
81
|
"@earendil-works/pi-ai": "*",
|
|
80
82
|
"@earendil-works/pi-coding-agent": "*",
|
|
81
83
|
"@earendil-works/pi-tui": "*",
|
|
82
|
-
"@howaboua/pi-codex-conversion": "^3.0.45 || ^4.0.0",
|
|
83
84
|
"typebox": "*"
|
|
84
85
|
},
|
|
85
86
|
"devDependencies": {
|
|
86
|
-
"@earendil-works/pi-ai": "1.5.
|
|
87
|
-
"@earendil-works/pi-coding-agent": "1.5.
|
|
88
|
-
"@earendil-works/pi-tui": "1.5.
|
|
89
|
-
"@
|
|
90
|
-
"@
|
|
91
|
-
"@types/node": "22.19.19",
|
|
87
|
+
"@earendil-works/pi-ai": "1.5.2",
|
|
88
|
+
"@earendil-works/pi-coding-agent": "1.5.2",
|
|
89
|
+
"@earendil-works/pi-tui": "1.5.2",
|
|
90
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
91
|
+
"@types/node": "22.20.5",
|
|
92
92
|
"@types/proper-lockfile": "4.1.4",
|
|
93
93
|
"esbuild": "^0.28.2",
|
|
94
|
-
"oxlint": "1.
|
|
95
|
-
"prettier": "3.
|
|
94
|
+
"oxlint": "1.93.0",
|
|
95
|
+
"prettier": "3.10.1",
|
|
96
96
|
"typebox": "^1.3.7",
|
|
97
97
|
"typescript": "7.0.2"
|
|
98
98
|
},
|
|
@@ -114,11 +114,6 @@
|
|
|
114
114
|
"publishConfig": {
|
|
115
115
|
"registry": "https://registry.npmjs.org/"
|
|
116
116
|
},
|
|
117
|
-
"peerDependenciesMeta": {
|
|
118
|
-
"@howaboua/pi-codex-conversion": {
|
|
119
|
-
"optional": true
|
|
120
|
-
}
|
|
121
|
-
},
|
|
122
117
|
"dependencies": {
|
|
123
118
|
"proper-lockfile": "4.1.2"
|
|
124
119
|
}
|
|
@@ -85,9 +85,13 @@ repository`), including which files contribute to the effective
|
|
|
85
85
|
definition.
|
|
86
86
|
- Preserve unrelated frontmatter, body content, and existing source files.
|
|
87
87
|
- The frontmatter `name` is the definition identity; the filename is not.
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
|
|
88
|
+
- Plain array values replace the inherited array, including `[]`. Use
|
|
89
|
+
`+name` and `-name` entries to add or remove individual inherited values;
|
|
90
|
+
mixed lists use their plain entries as a replacement base before modifiers.
|
|
91
|
+
Modifier-only `tools` lists remain relative to Pi's ordinary selection,
|
|
92
|
+
while plain `tools` lists are closed allowlists. Leads with unrestricted
|
|
93
|
+
implicit `agents` defaults need a concrete allowlist before using
|
|
94
|
+
modifiers.
|
|
91
95
|
- For additive prompt instructions, prefer an overlay body with
|
|
92
96
|
`bodyMode: append`; replace the body only when replacement is intended.
|
|
93
97
|
- Express capability restrictions structurally through definition fields
|
|
@@ -1,42 +0,0 @@
|
|
|
1
|
-
// extension/integrations/pi-codex-context-sharing.ts
|
|
2
|
-
import { connectCodexContextSharing } from "@howaboua/pi-codex-conversion/context-sharing";
|
|
3
|
-
var BOOTSTRAP_EVENT = "pi-herdsman:managed-agent-bootstrap";
|
|
4
|
-
var PARTICIPANT_ID = "pi-codex/context-sharing";
|
|
5
|
-
function register(pi) {
|
|
6
|
-
const connection = connectCodexContextSharing(pi);
|
|
7
|
-
const offBootstrap = pi.events.on(BOOTSTRAP_EVENT, (value) => {
|
|
8
|
-
const event = value;
|
|
9
|
-
if (event?.protocol !== 1) return;
|
|
10
|
-
if (event.phase === "prepare") {
|
|
11
|
-
event.register(PARTICIPANT_ID, async () => {
|
|
12
|
-
const service = connection.service;
|
|
13
|
-
if (!service?.canCreateChild(event.context)) return void 0;
|
|
14
|
-
const identity = service.describe(event.context);
|
|
15
|
-
if (identity?.storage !== "remote") return void 0;
|
|
16
|
-
const { binding, adopt } = await service.createChild(event.context, {
|
|
17
|
-
name: event.agent
|
|
18
|
-
});
|
|
19
|
-
return {
|
|
20
|
-
payload: JSON.stringify(binding),
|
|
21
|
-
commit: adopt
|
|
22
|
-
};
|
|
23
|
-
});
|
|
24
|
-
return;
|
|
25
|
-
}
|
|
26
|
-
if (event.participant?.id !== PARTICIPANT_ID) return;
|
|
27
|
-
event.accept(async () => {
|
|
28
|
-
const service = connection.service;
|
|
29
|
-
if (!service)
|
|
30
|
-
throw new Error("Pi Codex Conversion context sharing is unavailable");
|
|
31
|
-
await service.bind(event.context, JSON.parse(event.participant.payload));
|
|
32
|
-
});
|
|
33
|
-
});
|
|
34
|
-
pi.on("session_shutdown", () => {
|
|
35
|
-
offBootstrap();
|
|
36
|
-
connection.dispose();
|
|
37
|
-
});
|
|
38
|
-
}
|
|
39
|
-
export {
|
|
40
|
-
register as default
|
|
41
|
-
};
|
|
42
|
-
//# sourceMappingURL=pi-codex-context-sharing.js.map
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"version": 3,
|
|
3
|
-
"sources": ["../../extension/integrations/pi-codex-context-sharing.ts"],
|
|
4
|
-
"sourcesContent": ["import type {\n ExtensionAPI,\n ExtensionContext,\n} from \"@earendil-works/pi-coding-agent\";\nimport { connectCodexContextSharing } from \"@howaboua/pi-codex-conversion/context-sharing\";\n\nconst BOOTSTRAP_EVENT = \"pi-herdsman:managed-agent-bootstrap\";\nconst PARTICIPANT_ID = \"pi-codex/context-sharing\";\n\ntype Preparation = {\n payload: string;\n commit?: () => void | Promise<void>;\n};\n\ntype PrepareEvent = {\n protocol: 1;\n phase: \"prepare\";\n context: ExtensionContext;\n agent: string;\n register(\n id: string,\n prepare: () => Preparation | undefined | Promise<Preparation | undefined>,\n ): void;\n};\n\ntype InitializeEvent = {\n protocol: 1;\n phase: \"initialize\";\n context: ExtensionContext;\n agent: string;\n participant: {\n id: string;\n payload: string;\n };\n accept(initialize: () => void | Promise<void>): void;\n};\n\ntype BootstrapEvent = PrepareEvent | InitializeEvent;\n\nexport default function register(pi: ExtensionAPI): void {\n const connection = connectCodexContextSharing(pi);\n\n const offBootstrap = pi.events.on(BOOTSTRAP_EVENT, (value) => {\n const event = value as BootstrapEvent;\n if (event?.protocol !== 1) return;\n\n if (event.phase === \"prepare\") {\n event.register(PARTICIPANT_ID, async () => {\n const service = connection.service;\n if (!service?.canCreateChild(event.context)) return undefined;\n\n const identity = service.describe(event.context);\n if (identity?.storage !== \"remote\") return undefined;\n\n const { binding, adopt } = await service.createChild(event.context, {\n name: event.agent,\n });\n\n return {\n payload: JSON.stringify(binding),\n commit: adopt,\n };\n });\n return;\n }\n\n if (event.participant?.id !== PARTICIPANT_ID) return;\n\n event.accept(async () => {\n const service = connection.service;\n if (!service)\n throw new Error(\"Pi Codex Conversion context sharing is unavailable\");\n\n await service.bind(event.context, JSON.parse(event.participant.payload));\n });\n });\n\n pi.on(\"session_shutdown\", () => {\n offBootstrap();\n connection.dispose();\n });\n}\n"],
|
|
5
|
-
"mappings": ";AAIA,SAAS,kCAAkC;AAE3C,IAAM,kBAAkB;AACxB,IAAM,iBAAiB;AAgCR,SAAR,SAA0B,IAAwB;AACvD,QAAM,aAAa,2BAA2B,EAAE;AAEhD,QAAM,eAAe,GAAG,OAAO,GAAG,iBAAiB,CAAC,UAAU;AAC5D,UAAM,QAAQ;AACd,QAAI,OAAO,aAAa,EAAG;AAE3B,QAAI,MAAM,UAAU,WAAW;AAC7B,YAAM,SAAS,gBAAgB,YAAY;AACzC,cAAM,UAAU,WAAW;AAC3B,YAAI,CAAC,SAAS,eAAe,MAAM,OAAO,EAAG,QAAO;AAEpD,cAAM,WAAW,QAAQ,SAAS,MAAM,OAAO;AAC/C,YAAI,UAAU,YAAY,SAAU,QAAO;AAE3C,cAAM,EAAE,SAAS,MAAM,IAAI,MAAM,QAAQ,YAAY,MAAM,SAAS;AAAA,UAClE,MAAM,MAAM;AAAA,QACd,CAAC;AAED,eAAO;AAAA,UACL,SAAS,KAAK,UAAU,OAAO;AAAA,UAC/B,QAAQ;AAAA,QACV;AAAA,MACF,CAAC;AACD;AAAA,IACF;AAEA,QAAI,MAAM,aAAa,OAAO,eAAgB;AAE9C,UAAM,OAAO,YAAY;AACvB,YAAM,UAAU,WAAW;AAC3B,UAAI,CAAC;AACH,cAAM,IAAI,MAAM,oDAAoD;AAEtE,YAAM,QAAQ,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,YAAY,OAAO,CAAC;AAAA,IACzE,CAAC;AAAA,EACH,CAAC;AAED,KAAG,GAAG,oBAAoB,MAAM;AAC9B,iBAAa;AACb,eAAW,QAAQ;AAAA,EACrB,CAAC;AACH;",
|
|
6
|
-
"names": []
|
|
7
|
-
}
|