pi-herdsman 0.40.0 → 0.41.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 +44 -0
- package/README.md +18 -1
- package/SKILL.md +8 -6
- package/dist/coordinators/manager.md +5 -6
- package/dist/index.js +1643 -1300
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +23 -13
- package/dist/peer-bridge.js.map +3 -3
- package/docs/README.md +2 -2
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/lifecycle.md +6 -4
- package/docs/coordination-api.md +3 -2
- package/docs/development/validation.md +12 -8
- package/docs/getting-started.md +9 -2
- package/docs/guides/container-deployment.md +126 -38
- package/docs/guides/project-orchestration.md +10 -0
- package/docs/guides/recovery.md +12 -11
- package/docs/reference/agent-definition-schema.md +1 -1
- package/docs/reference/agent-states.md +10 -10
- package/docs/reference/agent.md +26 -25
- package/docs/reference/commands.md +1 -1
- package/docs/reference/staff.md +9 -2
- package/package.json +3 -2
package/docs/reference/agent.md
CHANGED
|
@@ -11,7 +11,7 @@ continue_agent
|
|
|
11
11
|
steer_agent
|
|
12
12
|
interrupt_agent
|
|
13
13
|
reply_agent
|
|
14
|
-
|
|
14
|
+
stop_agent
|
|
15
15
|
inspect_agent
|
|
16
16
|
read_agent_transcript
|
|
17
17
|
read_evidence
|
|
@@ -233,22 +233,22 @@ eligible callable coordination tools for the active record.
|
|
|
233
233
|
|
|
234
234
|
Each actionable live agent record includes:
|
|
235
235
|
|
|
236
|
-
| Field | Meaning
|
|
237
|
-
| --------------------------------------------------------------- |
|
|
238
|
-
| `agent` | Exact live logical agent identity to pass to the applicable `inspect_agent`, `read_agent_transcript`, `steer_agent`, `interrupt_agent`, `reply_agent`, or `
|
|
239
|
-
| `state` | Safe lifecycle state for observability.
|
|
240
|
-
| `available_tools` | Snapshot of currently eligible callable tools, using their exact names.
|
|
241
|
-
| `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence.
|
|
242
|
-
| `cwd`, `pi_session_id`, `pi_session_path` | Agent location and Pi session evidence.
|
|
243
|
-
| `owner_session_id` | Exact direct owner Pi session.
|
|
244
|
-
| `agent_definition` | Effective definition name.
|
|
245
|
-
| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence.
|
|
246
|
-
| `parent_label` | Durable parent assignment when the parent is visible.
|
|
247
|
-
| `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present.
|
|
236
|
+
| Field | Meaning |
|
|
237
|
+
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
238
|
+
| `agent` | Exact live logical agent identity to pass to the applicable `inspect_agent`, `read_agent_transcript`, `steer_agent`, `interrupt_agent`, `reply_agent`, or `stop_agent` tool. It is not a continuation identity. |
|
|
239
|
+
| `state` | Safe lifecycle state for observability. |
|
|
240
|
+
| `available_tools` | Snapshot of currently eligible callable tools, using their exact names. |
|
|
241
|
+
| `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence. |
|
|
242
|
+
| `cwd`, `pi_session_id`, `pi_session_path` | Agent location and Pi session evidence. |
|
|
243
|
+
| `owner_session_id` | Exact direct owner Pi session. |
|
|
244
|
+
| `agent_definition` | Effective definition name. |
|
|
245
|
+
| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence. |
|
|
246
|
+
| `parent_label` | Durable parent assignment when the parent is visible. |
|
|
247
|
+
| `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present. |
|
|
248
248
|
|
|
249
249
|
`available_tools` is authoritative model guidance for the current snapshot.
|
|
250
250
|
Do not infer eligibility from `state`.
|
|
251
|
-
`
|
|
251
|
+
`stop_agent` is listed only when the current snapshot passes the applicable stop
|
|
252
252
|
preflight. For a root-owned delegating agent, that preflight covers the complete
|
|
253
253
|
owned descendant cascade because closing the parent closes that cascade
|
|
254
254
|
child-first. Invocation always reacquires current evidence and revalidates
|
|
@@ -262,7 +262,7 @@ controller tools, not controls on an already-live agent. An agent cannot
|
|
|
262
262
|
receive a second assignment. Directly owned live agents may expose the
|
|
263
263
|
applicable live controls; directly owned live or proven `lost` records expose
|
|
264
264
|
`read_agent_transcript` when their materialized persisted Pi session file exists. Directly
|
|
265
|
-
owned live or proven `lost` records may expose `
|
|
265
|
+
owned live or proven `lost` records may expose `stop_agent` when the applicable stop
|
|
266
266
|
preflight currently succeeds. Unknown records and non-direct descendants expose
|
|
267
267
|
no mutation actions. Every operation rechecks identity, ownership, mailbox
|
|
268
268
|
state, and lifecycle immediately before mutation.
|
|
@@ -295,7 +295,7 @@ Health reconciliation is event-driven with a 30-second fallback scan. It
|
|
|
295
295
|
reconciles fresh mailbox and Herdr state and sends attention only to the exact
|
|
296
296
|
direct owner while that owner is idle. The `available_tools` included in an
|
|
297
297
|
attention event is an advisory snapshot of current authority; every later
|
|
298
|
-
`steer_agent`, `interrupt_agent`, `reply_agent`, or `
|
|
298
|
+
`steer_agent`, `interrupt_agent`, `reply_agent`, or `stop_agent` call revalidates identity, ownership,
|
|
299
299
|
mailbox state, and lifecycle.
|
|
300
300
|
|
|
301
301
|
Persistent actionable attention may repeat while the same condition remains
|
|
@@ -349,7 +349,7 @@ stale episode means no qualifying execution boundary occurred, so a steer queued
|
|
|
349
349
|
during that episode cannot yet have taken effect. Continue waiting only while
|
|
350
350
|
existing evidence positively supports legitimate long-running work; otherwise
|
|
351
351
|
use `interrupt_agent` to preempt the active Pi operation and continue the same
|
|
352
|
-
assignment. It supersedes earlier undelivered steering. Use `
|
|
352
|
+
assignment. It supersedes earlier undelivered steering. Use `stop_agent` only
|
|
353
353
|
when abandoning the assignment is intended. Do not poll or create another
|
|
354
354
|
delivery path for health attention.
|
|
355
355
|
|
|
@@ -435,7 +435,7 @@ not disclose storage paths.
|
|
|
435
435
|
|
|
436
436
|
`files` is valid on `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
437
437
|
`interrupt_agent`, and `reply_agent`; it is not valid on `list_agents`,
|
|
438
|
-
`
|
|
438
|
+
`stop_agent`, `inspect_agent`, or `read_agent_transcript`. It accepts
|
|
439
439
|
ordinary paths,
|
|
440
440
|
reusable direct-agent refs such as `result:researcher#1`, and canonical
|
|
441
441
|
`result:<request-id>` refs already supplied as evidence. Semantic refs use the
|
|
@@ -535,7 +535,7 @@ removed from execution by Pi's native abort behavior and is not retained in the
|
|
|
535
535
|
child editor.
|
|
536
536
|
|
|
537
537
|
Cancellation uses Pi's native abort mechanism. Non-cooperative third-party
|
|
538
|
-
tools may not stop immediately; `
|
|
538
|
+
tools may not stop immediately; `stop_agent` remains the destructive fallback.
|
|
539
539
|
|
|
540
540
|
## `reply_agent`
|
|
541
541
|
|
|
@@ -552,21 +552,22 @@ contains its request, ask, assignment, and session correlation evidence.
|
|
|
552
552
|
|
|
553
553
|
See [`ask_owner` API](ask-owner.md).
|
|
554
554
|
|
|
555
|
-
## `
|
|
555
|
+
## `stop_agent`
|
|
556
556
|
|
|
557
557
|
```json
|
|
558
558
|
{ "agent": "implementer-1" }
|
|
559
559
|
```
|
|
560
560
|
|
|
561
|
-
Call `
|
|
562
|
-
and a current applicable
|
|
561
|
+
Call `stop_agent` with `agent`. Stopping requires exact direct ownership
|
|
562
|
+
and a current applicable stop preflight. For a root-owned parent, that
|
|
563
563
|
preflight covers the complete owned descendant cascade because closing the
|
|
564
564
|
parent closes that cascade child-first. Invocation always reacquires current
|
|
565
565
|
evidence and revalidates identity, ownership, mailbox state, durable results,
|
|
566
|
-
and lifecycle before mutation.
|
|
567
|
-
|
|
566
|
+
and lifecycle before mutation. Stopping abandons the unfinished assignment,
|
|
567
|
+
including a pending owner question; stopping a delegating agent cascades through
|
|
568
|
+
directly owned agents first. Cleanup
|
|
568
569
|
remains fail-closed when exact identity or ownership cannot be proved. A direct
|
|
569
|
-
owner may also
|
|
570
|
+
owner may also stop a proven `lost` generation after a fresh absence proof when
|
|
570
571
|
the applicable close preflight succeeds; `unknown` presence remains
|
|
571
572
|
non-actionable.
|
|
572
573
|
|
|
@@ -229,7 +229,7 @@ It reports discarded active work or durable pending results when present.
|
|
|
229
229
|
Cleanup uses existing exact ownership proofs and proceeds conservatively across
|
|
230
230
|
independent failures.
|
|
231
231
|
|
|
232
|
-
Use ordinary `
|
|
232
|
+
Use ordinary `stop_agent` for normal targeted model-driven control.
|
|
233
233
|
|
|
234
234
|
`Project manager` offers `Start Manager mode` when inactive, or `Overview`,
|
|
235
235
|
`Refresh profile`, and `Leave Manager mode` while active. `Advanced…` opens
|
package/docs/reference/staff.md
CHANGED
|
@@ -194,8 +194,15 @@ binary, or oversized files fail instead of becoming required evidence. A
|
|
|
194
194
|
supported snapshot that does not fit inline is delivered by reference to the
|
|
195
195
|
preserved snapshot.
|
|
196
196
|
|
|
197
|
-
|
|
198
|
-
decision
|
|
197
|
+
Herdsman-managed Leads inherit the Manager's effective Pi project-trust
|
|
198
|
+
decision when launched into a verified linked worktree. A trusted Manager
|
|
199
|
+
authorizes project and private-repository definitions in that worktree, even
|
|
200
|
+
if a separate saved decision for the worktree differs. An untrusted Manager
|
|
201
|
+
launches the Lead restricted. The decision applies to the managed process and
|
|
202
|
+
does not modify Pi's persistent trust store. Same-worktree delegated Agents
|
|
203
|
+
inherit their parent's effective trust. Already-running Leads are not
|
|
204
|
+
reconfigured. Trust controls configuration access; it is not an
|
|
205
|
+
operating-system sandbox.
|
|
199
206
|
|
|
200
207
|
## `resume_work`
|
|
201
208
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-herdsman",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.41.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",
|
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
"build": "node scripts/build.mjs",
|
|
72
72
|
"typecheck": "tsc --project tsconfig.json",
|
|
73
73
|
"package:audit": "node scripts/package-audit.mjs",
|
|
74
|
-
"validate": "npm run format:check && npm run check && npm run build && npm run package:audit",
|
|
74
|
+
"validate": "npm run format:check && npm run typecheck && npm run lint -- --deny-warnings && npm run check && npm run build && npm run package:audit",
|
|
75
75
|
"release:check": "npm run validate && npm publish --dry-run --ignore-scripts",
|
|
76
76
|
"prepack": "npm run build"
|
|
77
77
|
},
|
|
@@ -87,6 +87,7 @@
|
|
|
87
87
|
"@earendil-works/pi-coding-agent": "1.5.0",
|
|
88
88
|
"@earendil-works/pi-tui": "1.5.0",
|
|
89
89
|
"@howaboua/pi-codex-conversion": "4.0.4",
|
|
90
|
+
"@modelcontextprotocol/sdk": "1.32.0",
|
|
90
91
|
"@types/node": "22.19.19",
|
|
91
92
|
"@types/proper-lockfile": "4.1.4",
|
|
92
93
|
"esbuild": "^0.28.2",
|