pi-herdsman 0.1.4 → 0.2.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/README.md +33 -29
- package/SKILL.md +81 -70
- package/dist/agent-definitions/{worker.md → generalist.md} +3 -3
- package/dist/agent-definitions/implementer.md +3 -3
- package/dist/agent-definitions/researcher.md +1 -1
- package/dist/agent-definitions/reviewer.md +2 -2
- package/dist/agent-definitions/scout.md +2 -2
- package/dist/index.js +139 -104
- package/docs/README.md +11 -11
- package/docs/agent-api.md +18 -18
- package/docs/concepts/{workers.md → agents.md} +36 -33
- package/docs/concepts/delegation.md +32 -32
- package/docs/concepts/lifecycle.md +26 -26
- package/docs/concepts/supervision.md +15 -11
- package/docs/development/documentation.md +4 -4
- package/docs/development/smoke-testing.md +52 -52
- package/docs/getting-started.md +20 -20
- package/docs/guides/agent-definitions.md +24 -19
- package/docs/guides/customizing-agents.md +14 -12
- package/docs/guides/handoffs.md +47 -17
- package/docs/guides/recovery.md +24 -24
- package/docs/reference/agent-definition-schema.md +40 -37
- package/docs/reference/{worker-states.md → agent-states.md} +17 -17
- package/docs/reference/{worker.md → agent.md} +81 -56
- package/docs/reference/ask-owner.md +23 -23
- package/docs/reference/commands.md +28 -23
- package/docs/reference/configuration.md +16 -13
- package/docs/reference/errors.md +6 -6
- package/docs/reference/status-widget.md +22 -22
- package/docs/reference/supervision.md +54 -19
- package/package.json +6 -4
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# `
|
|
1
|
+
# `agent` API
|
|
2
2
|
|
|
3
3
|
[Documentation index](../README.md) · [supervision reference](supervision.md)
|
|
4
4
|
|
|
5
|
-
`
|
|
5
|
+
`agent` is the structured model-facing API for managed agents. It has exactly six actions:
|
|
6
6
|
|
|
7
7
|
```text
|
|
8
8
|
list
|
|
@@ -14,7 +14,7 @@ inspect
|
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
Unknown fields and unsupported selector combinations fail with `invalid_request`.
|
|
17
|
-
The tool is registered only for the lead controller and authorized delegating
|
|
17
|
+
The tool is registered only for the lead controller and authorized delegating agent
|
|
18
18
|
controllers.
|
|
19
19
|
|
|
20
20
|
## `delegate`
|
|
@@ -35,12 +35,12 @@ Every variant rejects additional properties.
|
|
|
35
35
|
|
|
36
36
|
Allowed fields are `action`, `definition`, `task`, optional `label`, `cwd`,
|
|
37
37
|
`files`, `fork`, and `timeoutMs`. The definition is resolved from
|
|
38
|
-
the effective roster and delegating
|
|
38
|
+
the effective roster and delegating agent controllers may use only their allowlisted
|
|
39
39
|
definitions. Project definitions still require trusted project approval.
|
|
40
40
|
`fork`, when supplied, is an exact saved Pi session path or full UUID used as
|
|
41
41
|
the source for a new derived context; otherwise a new Pi session is launched.
|
|
42
|
-
Each accepted definition delegation creates one
|
|
43
|
-
assignment. The terminal result is delivered once and the
|
|
42
|
+
Each accepted definition delegation creates one agent generation for one
|
|
43
|
+
assignment. The terminal result is delivered once and the agent is cleaned up.
|
|
44
44
|
|
|
45
45
|
### Session
|
|
46
46
|
|
|
@@ -52,19 +52,26 @@ assignment. The terminal result is delivered once and the worker is cleaned up.
|
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
Allowed fields are `action`, `session`, `task`, optional `files`, and
|
|
55
|
+
Allowed fields are `action`, `session`, `task`, optional `label`, `files`, and
|
|
56
56
|
`timeoutMs`. The exact saved session supplies its cwd, definition identity, and
|
|
57
|
-
historical Pi context. Session delegation always creates a new
|
|
58
|
-
for one assignment; it never assigns work to an existing
|
|
59
|
-
definition must currently resolve to an enabled, authorized
|
|
60
|
-
definition, whose current configuration is used for the new
|
|
57
|
+
historical Pi context. Session delegation always creates a new agent generation
|
|
58
|
+
for one assignment with a live label; it never assigns work to an existing
|
|
59
|
+
agent. The saved definition must currently resolve to an enabled, authorized
|
|
60
|
+
effective definition, whose current configuration is used for the new
|
|
61
|
+
generation.
|
|
61
62
|
Concurrent or otherwise conflicting managed representations of the exact
|
|
62
63
|
session fail closed. The controller's own active Pi session cannot be delegated
|
|
63
64
|
to itself; use definition delegation with `fork` when a separate derived
|
|
64
65
|
context is required.
|
|
65
66
|
|
|
67
|
+
`label` is optional on both delegation variants and identifies the live
|
|
68
|
+
generation, not the continuation session. When omitted, Herdsman chooses a
|
|
69
|
+
fresh available label derived from the effective agent definition. An explicit
|
|
70
|
+
label is used exactly as the live label; if that label is occupied, delegation
|
|
71
|
+
fails with `agent_label_exists`.
|
|
72
|
+
|
|
66
73
|
All successful delegation results use `action: "delegate"` and include
|
|
67
|
-
`
|
|
74
|
+
`agent`, `definition`, request, session, and startup evidence where available.
|
|
68
75
|
Delegation returns after durable acceptance, not completion. A terminal result
|
|
69
76
|
also makes the exact session identity prominent so it can be used with a later
|
|
70
77
|
`delegate.session` call.
|
|
@@ -78,54 +85,63 @@ Request:
|
|
|
78
85
|
```
|
|
79
86
|
|
|
80
87
|
No selectors or other fields are accepted. A successful result includes the
|
|
81
|
-
effective `agent_definitions` roster and visible
|
|
82
|
-
|
|
83
|
-
Each actionable live
|
|
84
|
-
|
|
85
|
-
| Field | Meaning
|
|
86
|
-
| --------------------------------------------------------------- |
|
|
87
|
-
| `
|
|
88
|
-
| `state` | Safe lifecycle state for observability.
|
|
89
|
-
| `available_actions` | Snapshot of operations currently eligible for this controller.
|
|
90
|
-
| `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence.
|
|
91
|
-
| `cwd`, `pi_session_id`, `pi_session_path` |
|
|
92
|
-
| `owner_session_id` | Exact direct owner Pi session.
|
|
93
|
-
| `agent_definition` | Effective definition name.
|
|
94
|
-
| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence.
|
|
95
|
-
| `parent_label`, `orphan` | Visible direct-owner ancestry and proven orphan recovery evidence.
|
|
96
|
-
| `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present.
|
|
88
|
+
effective `agent_definitions` roster and visible agent records.
|
|
89
|
+
|
|
90
|
+
Each actionable live agent record includes:
|
|
91
|
+
|
|
92
|
+
| Field | Meaning |
|
|
93
|
+
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `agent` | Exact live logical agent identity to copy into `steer.agent`, `reply.agent`, or `close.agent`. It is not a continuation identity. |
|
|
95
|
+
| `state` | Safe lifecycle state for observability. |
|
|
96
|
+
| `available_actions` | Snapshot of operations currently eligible for this controller. |
|
|
97
|
+
| `workspace_id`, `pane_id`, `tab_id`, `tab_label` | Herdr identity evidence. |
|
|
98
|
+
| `cwd`, `pi_session_id`, `pi_session_path` | Agent location and Pi session evidence. |
|
|
99
|
+
| `owner_session_id` | Exact direct owner Pi session. |
|
|
100
|
+
| `agent_definition` | Effective definition name. |
|
|
101
|
+
| `active_request_id`, `last_activity_at`, `stale`, `inactive_ms` | Assignment and advisory activity evidence. |
|
|
102
|
+
| `parent_label`, `orphan` | Visible direct-owner ancestry and proven orphan recovery evidence. |
|
|
103
|
+
| `cleanup_error`, `result_error`, `diagnostic`, `tokens` | Bounded recovery and presentation evidence when present. |
|
|
97
104
|
|
|
98
105
|
`available_actions` is authoritative model guidance for the current snapshot.
|
|
99
106
|
Do not infer eligibility from `state`. Active work may list `steer`; a valid
|
|
100
107
|
correlated pending `ask_owner` may list `reply`; exact direct ownership may list
|
|
101
|
-
`close`. `available_actions` never lists `delegate`:
|
|
108
|
+
`close`. `available_actions` never lists `delegate`: an agent cannot receive a
|
|
102
109
|
second assignment. Descendant visibility does not grant control. Lead orphan
|
|
103
110
|
recovery may expose only `close`. Unknown and recovery-only records are
|
|
104
111
|
non-actionable. Every operation rechecks identity, ownership, mailbox state, and
|
|
105
112
|
lifecycle immediately before mutation.
|
|
106
113
|
The public record does not expose `steerable`.
|
|
107
114
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
115
|
+
The session-start instructions include the same complete definition metadata
|
|
116
|
+
projection returned by `list` for that controller. It is a startup snapshot;
|
|
117
|
+
use `list` for live agent state, ownership, or a refreshed definition roster
|
|
118
|
+
after configuration changes. Leaf agents do not receive a definition roster.
|
|
119
|
+
|
|
120
|
+
Lead controllers see the complete effective definition roster and agents visible
|
|
121
|
+
through their ownership boundary. Delegating agents see only allowed enabled
|
|
122
|
+
leaf definitions and their visible agents. Unknown mailbox diagnostics remain
|
|
111
123
|
non-actionable.
|
|
112
124
|
|
|
113
125
|
## `inspect`
|
|
114
126
|
|
|
115
127
|
```json
|
|
116
|
-
{ "action": "inspect", "
|
|
128
|
+
{ "action": "inspect", "agent": "implementer-1" }
|
|
117
129
|
```
|
|
118
130
|
|
|
119
|
-
`inspect` accepts only `action` and the exact live
|
|
120
|
-
only to that
|
|
121
|
-
unambiguous managed identity. The result is read-only
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
131
|
+
`inspect` accepts only `action` and the exact live agent label. It is available
|
|
132
|
+
only to that agent's direct owner, and only when the agent is a current,
|
|
133
|
+
unambiguous managed identity. The result is read-only live terminal/process
|
|
134
|
+
evidence only: it contains the exact session/pane identity, Herdr's up to 80
|
|
135
|
+
recent-unwrapped terminal lines, and advisory foreground process evidence when
|
|
136
|
+
available. Herdsman applies a local 16 KiB byte cap to the captured terminal
|
|
137
|
+
output. The public `recent_output_truncated` boolean is true only when that
|
|
138
|
+
local byte cap truncates the output and false otherwise; process evidence has
|
|
139
|
+
separate bounds. The result does not expose persisted Pi session-message
|
|
140
|
+
history. Its model-facing text includes the agent, session, pane, useful
|
|
141
|
+
foreground commands, and recent activity; raw process and recent-output
|
|
142
|
+
evidence remains in the structured result details.
|
|
127
143
|
The identity is checked again after capture; if the pane or Pi session was
|
|
128
|
-
replaced, inspection fails closed. Inspection does not change
|
|
144
|
+
replaced, inspection fails closed. Inspection does not change agent state,
|
|
129
145
|
mailbox records, lifecycle, or available controls.
|
|
130
146
|
|
|
131
147
|
## `files` and `timeoutMs`
|
|
@@ -137,17 +153,26 @@ when the exact message limit permits. Otherwise they remain canonical references
|
|
|
137
153
|
|
|
138
154
|
`timeoutMs` is valid on definition and session delegation and must be an integer
|
|
139
155
|
from `5001` through `300000`. The startup budget reserves one bounded diagnostic
|
|
140
|
-
window. Current message limits are governed by
|
|
156
|
+
window. Current message limits are governed by global/default
|
|
141
157
|
settings and the fixed mailbox protocol ceiling. Managed mailbox records use
|
|
142
|
-
protocol
|
|
143
|
-
`
|
|
158
|
+
protocol V4 in the `mailboxes-v4` namespace, and control requests use the marker prefix
|
|
159
|
+
`__PI_HERDSMAN_AGENT_V4__:`.
|
|
160
|
+
|
|
161
|
+
Do not attach or mention agent instruction files such as `AGENTS.md`, `CLAUDE.md`,
|
|
162
|
+
`GEMINI.md`, or equivalents merely because they exist. Rely on normal project or
|
|
163
|
+
runtime discovery. Attach one only when the task requires inspecting,
|
|
164
|
+
modifying, comparing, or transmitting it, the user requests it, or its required
|
|
165
|
+
instructions would not otherwise reach the target. Attach a required `SKILL.md`
|
|
166
|
+
only when the task needs it and the selected definition does not already provide
|
|
167
|
+
that skill. Ordinary relevant source, documentation, configuration, and
|
|
168
|
+
evidence files remain attachable.
|
|
144
169
|
|
|
145
170
|
## `steer`
|
|
146
171
|
|
|
147
172
|
```json
|
|
148
173
|
{
|
|
149
174
|
"action": "steer",
|
|
150
|
-
"
|
|
175
|
+
"agent": "implementer-1",
|
|
151
176
|
"message": "Also update the focused regression.",
|
|
152
177
|
"files": [".pi-herdsman/review.md"]
|
|
153
178
|
}
|
|
@@ -161,7 +186,7 @@ current assignment and does not create another final result.
|
|
|
161
186
|
```json
|
|
162
187
|
{
|
|
163
188
|
"action": "reply",
|
|
164
|
-
"
|
|
189
|
+
"agent": "implementer-1",
|
|
165
190
|
"message": "Use option B."
|
|
166
191
|
}
|
|
167
192
|
```
|
|
@@ -175,13 +200,13 @@ See [`ask_owner` API](ask-owner.md).
|
|
|
175
200
|
## `close`
|
|
176
201
|
|
|
177
202
|
```json
|
|
178
|
-
{ "action": "close", "
|
|
203
|
+
{ "action": "close", "agent": "implementer-1" }
|
|
179
204
|
```
|
|
180
205
|
|
|
181
|
-
Only `action` and `
|
|
206
|
+
Only `action` and `agent` are accepted. Close requires exact direct ownership,
|
|
182
207
|
or the lead-only evidence-backed orphan recovery condition. Closing abandons a
|
|
183
|
-
pending owner question; closing a delegating
|
|
184
|
-
owned
|
|
208
|
+
pending owner question; closing a delegating agent cascades through directly
|
|
209
|
+
owned agents first. Cleanup remains fail-closed when exact identity or ownership
|
|
185
210
|
cannot be proved.
|
|
186
211
|
|
|
187
212
|
## Result delivery and errors
|
|
@@ -189,13 +214,13 @@ cannot be proved.
|
|
|
189
214
|
An accepted delegated task remains the internal mailbox `kind: "task"` request
|
|
190
215
|
and has one correlated final result. Delivery goes to the exact owning Pi
|
|
191
216
|
session and occurs exactly once. Model-visible completion wording uses
|
|
192
|
-
`
|
|
193
|
-
`request=<id>`, and status. Details retain durable `
|
|
217
|
+
`agent=<agent>`, `definition=<definition>`, `session=<id>`,
|
|
218
|
+
`request=<id>`, and status. Details retain durable `agentLabel`,
|
|
194
219
|
`agentDefinition`, `piSessionId`, `piSessionFile`, result paths, elapsed time,
|
|
195
|
-
context usage, truncation, and persistence-error evidence. The
|
|
220
|
+
context usage, truncation, and persistence-error evidence. The agent is cleaned
|
|
196
221
|
up after the terminal result is delivered; the Pi session remains available for
|
|
197
222
|
continuation.
|
|
198
223
|
|
|
199
224
|
Tool failures return structured details for normal public errors. See
|
|
200
|
-
[Errors](errors.md), [
|
|
201
|
-
[
|
|
225
|
+
[Errors](errors.md), [agent states](agent-states.md), and
|
|
226
|
+
[agents and identity](../concepts/agents.md).
|
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
[Documentation index](../README.md)
|
|
4
4
|
|
|
5
|
-
`ask_owner` is mandatory managed
|
|
5
|
+
`ask_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
|
|
12
|
+
Every valid managed agent receives the `ask_owner` tool at launch.
|
|
13
13
|
|
|
14
14
|
Normal definition `tools`, `excludeTools`, and `noTools` policy cannot remove
|
|
15
15
|
this infrastructure capability.
|
|
@@ -24,42 +24,42 @@ this infrastructure capability.
|
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
`question` must contain non-whitespace text.
|
|
27
|
-
`files` supplies supporting evidence using the same rules as `
|
|
27
|
+
`files` supplies supporting evidence using the same rules as `agent`: complete
|
|
28
28
|
strict UTF-8 text may be embedded, while other files are canonical local
|
|
29
|
-
references and are not copied or snapshotted. Relative paths use the
|
|
29
|
+
references and are not copied or snapshotted. Relative paths use the agent's
|
|
30
30
|
working directory. This does not weaken the sole-final-tool-call rule.
|
|
31
31
|
|
|
32
32
|
## Turn rule
|
|
33
33
|
|
|
34
34
|
`ask_owner` must be:
|
|
35
35
|
|
|
36
|
-
- the
|
|
36
|
+
- the agent's only tool call in the turn;
|
|
37
37
|
- the final tool call of the turn.
|
|
38
38
|
|
|
39
|
-
The
|
|
39
|
+
The agent then stops and waits.
|
|
40
40
|
|
|
41
41
|
A call made alongside another tool call is rejected.
|
|
42
42
|
|
|
43
43
|
## Eligibility
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
An agent can ask only while it has a valid active assignment and:
|
|
46
46
|
|
|
47
47
|
- has no outstanding ask;
|
|
48
48
|
- has no completed/final result pending;
|
|
49
49
|
- has no pending state transition;
|
|
50
50
|
- has no unacknowledged owner request;
|
|
51
|
-
- has no ordinary unresolved direct-
|
|
51
|
+
- has no ordinary unresolved direct-agent work.
|
|
52
52
|
|
|
53
|
-
A delegation-enabled
|
|
54
|
-
|
|
55
|
-
|
|
53
|
+
A delegation-enabled agent may ask its own owner when its unresolved direct
|
|
54
|
+
agents are themselves validly blocked on owner questions. Ordinary active
|
|
55
|
+
agents and pending agent results still block escalation.
|
|
56
56
|
|
|
57
57
|
## Durable effect
|
|
58
58
|
|
|
59
59
|
On acceptance, Pi Herdsman creates one correlated ask record and sets
|
|
60
60
|
`pendingAskId` while preserving the original active assignment request ID.
|
|
61
61
|
|
|
62
|
-
The tool result tells the
|
|
62
|
+
The tool result tells the agent that the assignment is blocked and returns
|
|
63
63
|
details containing:
|
|
64
64
|
|
|
65
65
|
```text
|
|
@@ -67,7 +67,7 @@ askId
|
|
|
67
67
|
assignmentRequestId
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
The
|
|
70
|
+
The agent public state projects as `blocked` after the turn settles.
|
|
71
71
|
|
|
72
72
|
Final assignment settlement is disabled while the ask remains pending.
|
|
73
73
|
|
|
@@ -76,20 +76,20 @@ Final assignment settlement is disabled while the ask remains pending.
|
|
|
76
76
|
The exact direct owner receives the question through the existing owner-session
|
|
77
77
|
delivery path.
|
|
78
78
|
|
|
79
|
-
The system does not automatically forward
|
|
79
|
+
The system does not automatically forward an agent question through an ownership
|
|
80
80
|
chain.
|
|
81
81
|
|
|
82
|
-
If a delegating
|
|
82
|
+
If a delegating agent needs a lead decision, it independently calls `ask_owner`
|
|
83
83
|
on its own direct ownership edge.
|
|
84
84
|
|
|
85
85
|
## Reply
|
|
86
86
|
|
|
87
|
-
The direct owner answers through the `
|
|
87
|
+
The direct owner answers through the `agent` tool:
|
|
88
88
|
|
|
89
89
|
```json
|
|
90
90
|
{
|
|
91
91
|
"action": "reply",
|
|
92
|
-
"
|
|
92
|
+
"agent": "<exact agent>",
|
|
93
93
|
"message": "Use option B."
|
|
94
94
|
}
|
|
95
95
|
```
|
|
@@ -101,13 +101,13 @@ The reply is correlated to:
|
|
|
101
101
|
- run ID;
|
|
102
102
|
- owner session;
|
|
103
103
|
- workspace;
|
|
104
|
-
-
|
|
104
|
+
- agent label;
|
|
105
105
|
- pane;
|
|
106
106
|
- Pi session.
|
|
107
107
|
|
|
108
108
|
A mismatched or stale reply fails closed.
|
|
109
109
|
|
|
110
|
-
The
|
|
110
|
+
The agent clears the pending ask, acknowledges the reply request, and resumes
|
|
111
111
|
the same assignment with the owner answer.
|
|
112
112
|
|
|
113
113
|
## One outstanding question
|
|
@@ -116,18 +116,18 @@ Only one `ask_owner` question may be outstanding per assignment at a time.
|
|
|
116
116
|
|
|
117
117
|
There is no ask timeout.
|
|
118
118
|
|
|
119
|
-
The
|
|
119
|
+
The agent must not guess the owner answer and complete while blocked.
|
|
120
120
|
|
|
121
121
|
Rejected calls identify the known eligibility reason, such as no active
|
|
122
122
|
assignment, an existing owner question, settling state, a pending control
|
|
123
|
-
request, or active direct-
|
|
123
|
+
request, or active direct-agent work.
|
|
124
124
|
|
|
125
125
|
## Close
|
|
126
126
|
|
|
127
|
-
Closing the
|
|
127
|
+
Closing the agent abandons the pending question as part of agent teardown.
|
|
128
128
|
|
|
129
129
|
## See also
|
|
130
130
|
|
|
131
|
-
- [`
|
|
131
|
+
- [`agent` `reply`](agent.md#reply)
|
|
132
132
|
- [Lifecycle](../concepts/lifecycle.md)
|
|
133
133
|
- [Delegation](../concepts/delegation.md)
|
|
@@ -1,29 +1,30 @@
|
|
|
1
|
-
# `/
|
|
1
|
+
# `/agents` commands
|
|
2
2
|
|
|
3
3
|
[Documentation index](../README.md)
|
|
4
4
|
|
|
5
|
-
`/
|
|
5
|
+
`/agents` is the human-facing agent-management command namespace.
|
|
6
6
|
|
|
7
|
-
It is separate from the structured model-facing `
|
|
7
|
+
It is separate from the structured model-facing `agent` API.
|
|
8
8
|
|
|
9
9
|
Commands require a lead Pi session with UI.
|
|
10
10
|
|
|
11
11
|
## Usage
|
|
12
12
|
|
|
13
13
|
```text
|
|
14
|
-
/
|
|
15
|
-
/
|
|
16
|
-
/
|
|
17
|
-
/
|
|
14
|
+
/agents
|
|
15
|
+
/agents definitions
|
|
16
|
+
/agents placement [tab|split]
|
|
17
|
+
/agents stop
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
The plain command opens a native Pi selection menu with `Running`,
|
|
21
21
|
`Definitions`, `Layout`, `Message limits`, and `Stop all…` destinations. The
|
|
22
|
-
Message limits view edits the independent inline attachment and mailbox
|
|
23
|
-
payload limits
|
|
24
|
-
|
|
22
|
+
Message limits view edits the independent global inline attachment and mailbox
|
|
23
|
+
payload limits. It is available only to a lead Pi session with UI. Current
|
|
24
|
+
values and presets show a rough token equivalent using four UTF-8 bytes per
|
|
25
|
+
token. The enforced limits are bytes, not tokens.
|
|
25
26
|
|
|
26
|
-
## `/
|
|
27
|
+
## `/agents definitions`
|
|
27
28
|
|
|
28
29
|
Opens the native Definitions menu for the effective bundled, project, and
|
|
29
30
|
global roster. Project definitions are included only when the trusted project
|
|
@@ -44,10 +45,10 @@ The details view can show:
|
|
|
44
45
|
|
|
45
46
|
Bundled implementation paths are intentionally hidden from the human overview.
|
|
46
47
|
|
|
47
|
-
Structured `
|
|
48
|
+
Structured `agent list` keeps exact deterministic metadata, including exact
|
|
48
49
|
source and skill paths when available.
|
|
49
50
|
|
|
50
|
-
`/
|
|
51
|
+
`/agents definitions` does not probe runtime tool availability.
|
|
51
52
|
|
|
52
53
|
Selecting a definition opens:
|
|
53
54
|
|
|
@@ -73,49 +74,53 @@ The command edits only the selected top-level `model`, `thinking`, or `enabled`
|
|
|
73
74
|
line in the global Markdown override. It preserves unrelated frontmatter and
|
|
74
75
|
the complete body.
|
|
75
76
|
|
|
77
|
+
Details re-resolves the selected definition when opened, so it reflects current
|
|
78
|
+
overlays and body references even if the menu remained open while configuration
|
|
79
|
+
changed.
|
|
80
|
+
|
|
76
81
|
Changes apply to future definition delegations and session continuations, not
|
|
77
|
-
already-running
|
|
82
|
+
already-running agents or the lead Pi session.
|
|
78
83
|
|
|
79
84
|
Standalone global definitions are editable too. Removing a field from one uses
|
|
80
85
|
Pi's normal default; removing a field from a bundled override restores the
|
|
81
86
|
bundled value.
|
|
82
87
|
|
|
83
|
-
## `/
|
|
88
|
+
## `/agents` Running
|
|
84
89
|
|
|
85
90
|
Select a live managed agent from the shared status projection to focus its pane.
|
|
86
91
|
Pi Herdsman refreshes and verifies the exact label, pane, and session identity
|
|
87
|
-
before issuing herdr's focus command. If the
|
|
92
|
+
before issuing herdr's focus command. If the agent changed, no focus command
|
|
88
93
|
is sent.
|
|
89
94
|
|
|
90
|
-
## `/
|
|
95
|
+
## `/agents placement`
|
|
91
96
|
|
|
92
97
|
Selecting Layout opens a native selector showing the effective setting.
|
|
93
98
|
Explicit values continue to set directly:
|
|
94
99
|
|
|
95
100
|
```text
|
|
96
|
-
/
|
|
97
|
-
/
|
|
101
|
+
/agents placement tab
|
|
102
|
+
/agents placement split
|
|
98
103
|
```
|
|
99
104
|
|
|
100
105
|
See [Configuration](configuration.md).
|
|
101
106
|
|
|
102
|
-
## `/
|
|
107
|
+
## `/agents stop`
|
|
103
108
|
|
|
104
109
|
Destructive lead-only emergency control.
|
|
105
110
|
|
|
106
111
|
It aborts the current lead turn and attempts to close the exactly proven owned
|
|
107
|
-
|
|
112
|
+
agent tree.
|
|
108
113
|
|
|
109
114
|
It reports discarded active work or durable pending results when present.
|
|
110
115
|
|
|
111
116
|
Cleanup uses existing exact ownership proofs and proceeds conservatively across
|
|
112
117
|
independent failures.
|
|
113
118
|
|
|
114
|
-
Use ordinary `
|
|
119
|
+
Use ordinary `agent close` for normal targeted model-driven control.
|
|
115
120
|
|
|
116
121
|
## See also
|
|
117
122
|
|
|
118
123
|
- [`/chief` and chief mode](supervision.md)
|
|
119
|
-
- [`
|
|
124
|
+
- [`agent` API](agent.md)
|
|
120
125
|
- [Configuration](configuration.md)
|
|
121
126
|
- [Status widget](status-widget.md)
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
Pi Herdsman intentionally has very little settings state.
|
|
6
6
|
|
|
7
7
|
Agent behavior lives in Markdown definitions. The extension settings currently
|
|
8
|
-
own
|
|
8
|
+
own agent placement.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Agent placement
|
|
11
11
|
|
|
12
12
|
Settings shape:
|
|
13
13
|
|
|
@@ -32,12 +32,12 @@ Default:
|
|
|
32
32
|
tab
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
`tab` places future
|
|
35
|
+
`tab` places future agents in the managed agent-tab workflow.
|
|
36
36
|
|
|
37
|
-
`split` places future
|
|
37
|
+
`split` places future agents by splitting from the caller's tab/pane placement
|
|
38
38
|
boundary.
|
|
39
39
|
|
|
40
|
-
This affects future starts, not existing
|
|
40
|
+
This affects future starts, not existing agents.
|
|
41
41
|
|
|
42
42
|
## Message limits
|
|
43
43
|
|
|
@@ -56,13 +56,16 @@ Each accepts an integer from 1024 bytes (1 KiB) through 1048576 bytes (1 MiB)
|
|
|
56
56
|
and defaults to 131072 bytes (128 KiB). The inline limit applies per file;
|
|
57
57
|
eligible complete strict UTF-8 files are embedded in caller order only when
|
|
58
58
|
the exact serialized mailbox record fits. Other files remain canonical
|
|
59
|
-
references. The mailbox limit is the exact serialized `RequestRecord
|
|
60
|
-
`AskRecord
|
|
59
|
+
references. The mailbox limit is the exact serialized `RequestRecord`,
|
|
60
|
+
`AskRecord`, or text-only chief supervision record admission size. Chief
|
|
61
|
+
supervision also has an existing fixed 8 KiB record ceiling, so its effective
|
|
62
|
+
admission limit is the smaller of the configured mailbox limit and 8 KiB.
|
|
61
63
|
|
|
62
|
-
|
|
63
|
-
ignored rather than clamped
|
|
64
|
-
|
|
65
|
-
reading existing
|
|
64
|
+
Only valid global values affect runtime behavior. Invalid global values are
|
|
65
|
+
ignored rather than clamped, and project-local values for these two keys are
|
|
66
|
+
inert. Configure the global values through `/agents` → `Message limits`; the
|
|
67
|
+
fixed 1 MiB protocol safety ceiling remains in force for reading existing
|
|
68
|
+
mailbox records.
|
|
66
69
|
|
|
67
70
|
## Settings scope
|
|
68
71
|
|
|
@@ -84,7 +87,7 @@ A project placement value is effective only when:
|
|
|
84
87
|
|
|
85
88
|
If no valid trusted project placement is active, the global value is used.
|
|
86
89
|
|
|
87
|
-
`/
|
|
90
|
+
`/agents placement` opens a native selector showing the effective value and
|
|
88
91
|
offering `tab` or `split`. Selecting a value writes to the current effective
|
|
89
92
|
scope and verifies the value after writing; the confirmation reports whether
|
|
90
93
|
that scope is `project` or `global`.
|
|
@@ -126,5 +129,5 @@ identity/restore behavior.
|
|
|
126
129
|
|
|
127
130
|
## See also
|
|
128
131
|
|
|
129
|
-
- [`/
|
|
132
|
+
- [`/agents` commands](commands.md)
|
|
130
133
|
- [Getting started](../getting-started.md)
|
package/docs/reference/errors.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[Documentation index](../README.md)
|
|
4
4
|
|
|
5
|
-
Normal public `
|
|
5
|
+
Normal public `agent` failures use structured error details.
|
|
6
6
|
|
|
7
7
|
## Shape
|
|
8
8
|
|
|
@@ -38,12 +38,12 @@ must not be presented as exhausted cleanup.
|
|
|
38
38
|
| Category | Meaning |
|
|
39
39
|
| -------------------------- | ----------------------------------------------------------------------------------- |
|
|
40
40
|
| `not_running_inside_herdr` | Required herdr environment is missing. |
|
|
41
|
-
| `
|
|
42
|
-
| `pane_not_ready` |
|
|
41
|
+
| `agent_label_exists` | Requested/generated live label conflicts with an existing agent. |
|
|
42
|
+
| `pane_not_ready` | Agent pane/startup did not reach the required readiness boundary. |
|
|
43
43
|
| `target_not_found` | Exact requested identity or ownership evidence was not found. |
|
|
44
44
|
| `target_ambiguous` | More than one live candidate matched an identity that must be exact. |
|
|
45
45
|
| `rollback_failure` | Primary operation failed and cleanup did not fully converge. |
|
|
46
|
-
| `
|
|
46
|
+
| `agent_busy` | Agent state does not allow the requested control action. |
|
|
47
47
|
| `invalid_request` | Request fields, values, definition input, file input, or preconditions are invalid. |
|
|
48
48
|
| `internal_failure` | An invariant or underlying operation failed outside a narrower public category. |
|
|
49
49
|
|
|
@@ -58,7 +58,7 @@ Both are fail-closed behavior.
|
|
|
58
58
|
|
|
59
59
|
## Rollback
|
|
60
60
|
|
|
61
|
-
When
|
|
61
|
+
When an agent launch fails, exact resources created by that attempt are cleaned
|
|
62
62
|
only when ownership is proved.
|
|
63
63
|
|
|
64
64
|
A `rollback_failure` can preserve:
|
|
@@ -84,4 +84,4 @@ This is output presentation behavior, not an error category.
|
|
|
84
84
|
## See also
|
|
85
85
|
|
|
86
86
|
- [Recovery](../guides/recovery.md)
|
|
87
|
-
- [`
|
|
87
|
+
- [`agent` API](agent.md)
|