pi-herdsman 0.7.0 → 0.7.1
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/SKILL.md +6 -0
- package/dist/index.js +84 -68
- package/docs/concepts/agents.md +4 -3
- package/docs/concepts/lifecycle.md +8 -0
- package/docs/guides/recovery.md +13 -1
- package/docs/reference/agent-states.md +32 -8
- package/docs/reference/agent.md +12 -9
- package/docs/reference/status-widget.md +11 -6
- package/package.json +1 -1
package/docs/concepts/agents.md
CHANGED
|
@@ -71,9 +71,10 @@ A lead Pi session owns its direct agents.
|
|
|
71
71
|
A delegating agent may own direct agents when its effective definition has
|
|
72
72
|
allowed `agents`.
|
|
73
73
|
|
|
74
|
-
Public list visibility follows this ownership boundary.
|
|
75
|
-
|
|
76
|
-
|
|
74
|
+
Public list visibility follows this ownership boundary. Durable descendants
|
|
75
|
+
remain attached to their recorded parent even when that parent is lost or
|
|
76
|
+
physically unresolved; missing durable ancestry is shown as non-actionable
|
|
77
|
+
recovery evidence.
|
|
77
78
|
|
|
78
79
|
## Authority boundaries
|
|
79
80
|
|
|
@@ -23,6 +23,13 @@ cleanup
|
|
|
23
23
|
gone
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
+
If the expected pane, Pi session, and run-scoped alias are all absent from a
|
|
27
|
+
coherent Herdr inventory before a durable result resolves the assignment, the
|
|
28
|
+
assignment projects as `lost`. The mailbox remains the durable owner of that
|
|
29
|
+
generation until the direct owner explicitly closes it; physical disappearance
|
|
30
|
+
does not mean completion or task failure. Moved, conflicting, or incomplete
|
|
31
|
+
evidence remains `unknown`.
|
|
32
|
+
|
|
26
33
|
The authoritative final result is correlated to the accepted assignment request
|
|
27
34
|
ID.
|
|
28
35
|
|
|
@@ -52,6 +59,7 @@ The public states are:
|
|
|
52
59
|
- `blocked`
|
|
53
60
|
- `settling`
|
|
54
61
|
- `unknown`
|
|
62
|
+
- `lost`
|
|
55
63
|
|
|
56
64
|
See [Agent states](../reference/agent-states.md) for their exact control
|
|
57
65
|
meaning.
|
package/docs/guides/recovery.md
CHANGED
|
@@ -47,6 +47,16 @@ Do not guess from pane IDs, process appearance, elapsed time, or stale metadata.
|
|
|
47
47
|
Refresh `list` and resolve the identity/lifecycle condition. If a cleanup or
|
|
48
48
|
recovery error is present, inspect its exact details.
|
|
49
49
|
|
|
50
|
+
## Agent is `lost`
|
|
51
|
+
|
|
52
|
+
`lost` means the expected physical execution is proven gone before a durable
|
|
53
|
+
terminal result resolved the assignment. The durable mailbox remains owned and
|
|
54
|
+
the assignment remains unresolved; loss is not completion or task failure.
|
|
55
|
+
Only the direct owner may use `close` to abandon the lost generation. Close it
|
|
56
|
+
before replacing it or continuing its saved session. Herdsman never
|
|
57
|
+
redelegates or continues it automatically. Moved or conflicting evidence is
|
|
58
|
+
`unknown`, not `lost`, and remains fail-closed.
|
|
59
|
+
|
|
50
60
|
## Inactivity advisory
|
|
51
61
|
|
|
52
62
|
A `working` agent with an exact active assignment can become advisory `stale`
|
|
@@ -106,7 +116,9 @@ uncertain.
|
|
|
106
116
|
|
|
107
117
|
## Close failure
|
|
108
118
|
|
|
109
|
-
Normal `agent close` targets one exact directly owned live agent
|
|
119
|
+
Normal `agent close` targets one exact directly owned live agent or a directly
|
|
120
|
+
owned generation proven `lost` by fresh absence evidence. Unknown presence
|
|
121
|
+
fails closed.
|
|
110
122
|
|
|
111
123
|
Closing a delegating agent cascades through its owned agents first. If a
|
|
112
124
|
agent cannot be proved or closed safely, the delegating agent remains rather
|
|
@@ -5,20 +5,21 @@
|
|
|
5
5
|
The public state is a safe-control projection built from live lifecycle and
|
|
6
6
|
durable assignment/convergence evidence. It is not a raw herdr lifecycle string.
|
|
7
7
|
|
|
8
|
-
| State | Meaning
|
|
9
|
-
| ---------- |
|
|
10
|
-
| `working` | An assignment is active.
|
|
11
|
-
| `blocked` | Active assignment waits for owner attention or another condition.
|
|
12
|
-
| `settling` | Assignment handoff, completion/result delivery, launch, direct-agent gate, or cleanup is converging.
|
|
13
|
-
| `unknown` | Exact safe control state cannot be proved.
|
|
8
|
+
| State | Meaning |
|
|
9
|
+
| ---------- | -------------------------------------------------------------------------------------------------------- |
|
|
10
|
+
| `working` | An assignment is active. |
|
|
11
|
+
| `blocked` | Active assignment waits for owner attention or another condition. |
|
|
12
|
+
| `settling` | Assignment handoff, completion/result delivery, launch, direct-agent gate, or cleanup is converging. |
|
|
13
|
+
| `unknown` | Exact safe control state cannot be proved. |
|
|
14
|
+
| `lost` | Physical execution is proven absent before a durable terminal result; the assignment remains unresolved. |
|
|
14
15
|
|
|
15
16
|
## `available_actions` is authoritative
|
|
16
17
|
|
|
17
18
|
A live agent record in `agent list` includes an `available_actions` snapshot.
|
|
18
19
|
Use only operations currently listed there; do not infer control eligibility
|
|
19
20
|
from `state` alone. `steer` means active work accepts steering, `reply` means a
|
|
20
|
-
correlated pending `ask_owner` is valid, and `close` means exact ownership
|
|
21
|
-
|
|
21
|
+
correlated pending `ask_owner` is valid, and `close` means exact direct ownership
|
|
22
|
+
permits teardown. `available_actions` never includes
|
|
22
23
|
`delegate`; an agent generation handles one assignment only. Every operation
|
|
23
24
|
revalidates identity, ownership, mailbox state, and lifecycle immediately before
|
|
24
25
|
mutation.
|
|
@@ -26,6 +27,9 @@ mutation.
|
|
|
26
27
|
A delegating agent may be blocked while direct agent work is pending and still accept
|
|
27
28
|
steering when `steer` is listed. Descendant visibility does not imply authority;
|
|
28
29
|
records outside the controller's direct ownership can have an empty action list.
|
|
30
|
+
Directly owned live records may expose the applicable live controls, including
|
|
31
|
+
`close`; directly owned proven `lost` records expose `close` only. Unknown
|
|
32
|
+
records and non-direct descendants remain fail-closed with no mutation actions.
|
|
29
33
|
|
|
30
34
|
## `blocked` and owner questions
|
|
31
35
|
|
|
@@ -45,6 +49,26 @@ or validation-failing mailbox state is reported with a bounded diagnostic and an
|
|
|
45
49
|
empty `available_actions` list. Do not substitute pane idleness, elapsed time,
|
|
46
50
|
model metadata, missing activity, a guessed session, or an old agent identity.
|
|
47
51
|
|
|
52
|
+
`lost` is different: a coherent Herdr inventory proves the expected pane,
|
|
53
|
+
session, and run-scoped alias are absent. It is not completion or task failure;
|
|
54
|
+
use direct-owner `close` to abandon the unresolved generation.
|
|
55
|
+
|
|
56
|
+
## Result precedence and actions
|
|
57
|
+
|
|
58
|
+
A durable terminal result or `result_error` takes precedence over physical
|
|
59
|
+
absence and projects as `settling` while delivery or recovery converges. A
|
|
60
|
+
failed inventory never proves `lost`; relocated or conflicting evidence is
|
|
61
|
+
`unknown`.
|
|
62
|
+
|
|
63
|
+
| Record | Direct-owner actions |
|
|
64
|
+
| --------- | ------------------------------------------------------------------------------- |
|
|
65
|
+
| `live` | Existing live controls, including `inspect` and eligible `steer`, plus `close`. |
|
|
66
|
+
| `lost` | `close` only. |
|
|
67
|
+
| `unknown` | None. |
|
|
68
|
+
|
|
69
|
+
Descendants remain visible through durable ancestry but do not gain direct
|
|
70
|
+
control from that visibility.
|
|
71
|
+
|
|
48
72
|
## Inactivity fields
|
|
49
73
|
|
|
50
74
|
A qualifying `working` agent may also report `stale`, `inactive_ms`, and
|
package/docs/reference/agent.md
CHANGED
|
@@ -89,7 +89,8 @@ Request:
|
|
|
89
89
|
No selectors or other fields are accepted. A successful result includes the
|
|
90
90
|
effective `agent_definitions` roster and visible agent records.
|
|
91
91
|
|
|
92
|
-
Each
|
|
92
|
+
Each valid durable generation remains visible, including unresolved `unknown`
|
|
93
|
+
and proven `lost` records. Each actionable live agent record includes:
|
|
93
94
|
|
|
94
95
|
| Field | Meaning |
|
|
95
96
|
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -101,7 +102,7 @@ Each actionable live agent record includes:
|
|
|
101
102
|
| `owner_session_id` | Exact direct owner Pi session. |
|
|
102
103
|
| `agent_definition` | Effective definition name. |
|
|
103
104
|
| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence. |
|
|
104
|
-
| `parent_label
|
|
105
|
+
| `parent_label` | Durable parent assignment when the parent is visible. |
|
|
105
106
|
| `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present. |
|
|
106
107
|
|
|
107
108
|
`available_actions` is authoritative model guidance for the current snapshot.
|
|
@@ -109,10 +110,11 @@ Do not infer eligibility from `state`. Active work may list `steer`; a valid
|
|
|
109
110
|
correlated pending `ask_owner` may list `reply`; exact direct ownership may list
|
|
110
111
|
`close`. `available_actions` never lists `delegate` or `continue`: these are
|
|
111
112
|
controller operations, not controls on an already-live agent. An agent cannot
|
|
112
|
-
receive a second assignment.
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
113
|
+
receive a second assignment. Directly owned live agents may expose the
|
|
114
|
+
applicable live controls, including `close`; directly owned proven `lost`
|
|
115
|
+
records expose `close` only. Unknown records and non-direct descendants expose
|
|
116
|
+
no mutation actions. Every operation rechecks identity, ownership, mailbox
|
|
117
|
+
state, and lifecycle immediately before mutation.
|
|
116
118
|
The public record does not expose `steerable`.
|
|
117
119
|
|
|
118
120
|
The session-start instructions include the same complete definition metadata
|
|
@@ -209,11 +211,12 @@ See [`ask_owner` API](ask-owner.md).
|
|
|
209
211
|
{ "action": "close", "agent": "implementer-1" }
|
|
210
212
|
```
|
|
211
213
|
|
|
212
|
-
Only `action` and `agent` are accepted. Close requires exact direct ownership
|
|
213
|
-
|
|
214
|
+
Only `action` and `agent` are accepted. Close requires exact direct ownership.
|
|
215
|
+
Closing abandons a
|
|
214
216
|
pending owner question; closing a delegating agent cascades through directly
|
|
215
217
|
owned agents first. Cleanup remains fail-closed when exact identity or ownership
|
|
216
|
-
cannot be proved.
|
|
218
|
+
cannot be proved. A direct owner may also close a proven `lost` generation
|
|
219
|
+
after a fresh absence proof; `unknown` presence remains non-actionable.
|
|
217
220
|
|
|
218
221
|
## Result delivery and errors
|
|
219
222
|
|
|
@@ -74,7 +74,7 @@ Example:
|
|
|
74
74
|
```
|
|
75
75
|
|
|
76
76
|
The header reports exact non-zero lifecycle states in the order `working`,
|
|
77
|
-
`blocked`, `settling`, `starting`, and `
|
|
77
|
+
`blocked`, `settling`, `starting`, `unknown`, and `lost`. `starting` is a
|
|
78
78
|
presentation-only count for controller-local assignments that have begun
|
|
79
79
|
startup but have not yet become active or terminal. It is not mailbox state,
|
|
80
80
|
control authority, or Running inventory.
|
|
@@ -102,8 +102,9 @@ every row. The task is the rightmost elastic field and is kept only when it has
|
|
|
102
102
|
useful room before it is truncated.
|
|
103
103
|
|
|
104
104
|
Working rows use `● working`, blocked rows use `◐ blocked`, settling rows use
|
|
105
|
-
`◌ settling`, starting rows use `◌ starting`,
|
|
106
|
-
|
|
105
|
+
`◌ settling`, starting rows use `◌ starting`, unknown rows use `? unknown`, and
|
|
106
|
+
lost rows use `× lost` with the theme's attention/error styling. Working,
|
|
107
|
+
settling, and starting animate; blocked, unknown, and lost rows are static.
|
|
107
108
|
While a controller-local start remains pending, an authoritative `settling`
|
|
108
109
|
row is presented as `starting` so launch and request handoff remain visually
|
|
109
110
|
continuous. `working`, `blocked`, and `unknown` authoritative states are never
|
|
@@ -111,9 +112,13 @@ overridden. A starting row is removed when its exact request becomes active or
|
|
|
111
112
|
terminal, its local runtime is removed, startup fails or rolls back, the
|
|
112
113
|
controller session restarts, or shutdown clears transient state.
|
|
113
114
|
|
|
114
|
-
`
|
|
115
|
-
|
|
116
|
-
|
|
115
|
+
The normal widget retains `lost` and fail-closed `unknown` rows because they
|
|
116
|
+
represent durable unresolved generations whose physical state is either proven
|
|
117
|
+
gone or not safely provable. `Running` inspection excludes `lost` and
|
|
118
|
+
fail-closed `unknown` rows because they are not safely focusable targets; it
|
|
119
|
+
otherwise shows authoritative live agent rows and excludes presentation-only
|
|
120
|
+
starting rows. A terminal result is followed by cleanup; the widget does not
|
|
121
|
+
retain an idle completed agent.
|
|
117
122
|
|
|
118
123
|
## Optional metadata
|
|
119
124
|
|
package/package.json
CHANGED