@luminascale/shepherd 0.0.0-stage → 0.6.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/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,1093 @@
|
|
|
1
|
+
# Implementation Plan: Asynchronous Shepherd Tasks and Agent Messaging
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Proposed implementation plan for
|
|
6
|
+
`docs/specs/005-agent-messaging-and-task-lifecycle/spec.md`.
|
|
7
|
+
|
|
8
|
+
No implementation is included in this plan. The plan is intentionally staged so
|
|
9
|
+
that task lifecycle correctness is established before peer messaging and UI
|
|
10
|
+
conveniences are added.
|
|
11
|
+
|
|
12
|
+
## 1. Implementation decisions
|
|
13
|
+
|
|
14
|
+
The following decisions are normative for the implementation unless the
|
|
15
|
+
specification is amended first.
|
|
16
|
+
|
|
17
|
+
### 1.1 Public operations
|
|
18
|
+
|
|
19
|
+
The new canonical operations are:
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
shepherd_delegate parent -> child, tracked task, returns taskId
|
|
23
|
+
shepherd_message Shepherd/child -> Shepherd/child, asynchronous message
|
|
24
|
+
shepherd_done child -> parent, explicit task terminal signal
|
|
25
|
+
shepherd_watch parent -> task completion subscription
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Existing operations remain available where they are still meaningful:
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
shepherd_spawn
|
|
32
|
+
shepherd_status
|
|
33
|
+
shepherd_close
|
|
34
|
+
shepherd_read
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`shepherd_wait` is not used by the new workflow. It may remain as a
|
|
38
|
+
compatibility adapter, but no new message or task path may depend on it.
|
|
39
|
+
|
|
40
|
+
`shepherd_prompt` becomes a deprecated compatibility name for the old
|
|
41
|
+
parent-to-child task submission path. It must not retain a separate completion
|
|
42
|
+
model after the new task registry is active. Compatibility calls should map to
|
|
43
|
+
a task record and return an identifier that can be observed through the task
|
|
44
|
+
watcher. The migration behavior must be documented and tested explicitly.
|
|
45
|
+
|
|
46
|
+
### 1.2 Task completion
|
|
47
|
+
|
|
48
|
+
A child Pi turn is not a task. The following are non-terminal runtime events:
|
|
49
|
+
|
|
50
|
+
- `agent_end`;
|
|
51
|
+
- `agent_settled`;
|
|
52
|
+
- Herdr `idle`;
|
|
53
|
+
- a child becoming quiet while waiting for another agent; and
|
|
54
|
+
- an intermediate assistant response.
|
|
55
|
+
|
|
56
|
+
The normal successful terminal event is an explicit child `shepherd_done` call.
|
|
57
|
+
The parent may also settle a task as failed, cancelled, or timed out when an
|
|
58
|
+
external lifecycle event requires it.
|
|
59
|
+
|
|
60
|
+
This is the central correctness rule. No implementation may restore the old
|
|
61
|
+
behavior of treating a successful `agent_end` sidecar as task completion.
|
|
62
|
+
|
|
63
|
+
### 1.3 Message delivery
|
|
64
|
+
|
|
65
|
+
Messages are accepted asynchronously. The initial delivery mode is:
|
|
66
|
+
|
|
67
|
+
- `followUp` by default;
|
|
68
|
+
- `steer` only when explicitly requested; and
|
|
69
|
+
- no synchronous parent wait.
|
|
70
|
+
|
|
71
|
+
The child-side extension calls Pi's local API, equivalent to:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
pi.sendUserMessage(renderedMessage, { deliverAs: "followUp" });
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The implementation must not try to access a child `AgentSession` object from
|
|
78
|
+
the parent process. Parent and child processes communicate through the
|
|
79
|
+
Shepherd broker.
|
|
80
|
+
|
|
81
|
+
### 1.4 Transport
|
|
82
|
+
|
|
83
|
+
Use a parent-owned, session-scoped filesystem mailbox for the first
|
|
84
|
+
implementation rather than a Unix socket. A mailbox is easier to inspect,
|
|
85
|
+
works from separate Herdr panes, and does not require a long-lived socket
|
|
86
|
+
server or reconnect protocol.
|
|
87
|
+
|
|
88
|
+
The mailbox must use:
|
|
89
|
+
|
|
90
|
+
- a directory created with owner-only permissions;
|
|
91
|
+
- one immutable JSON envelope per message or control event;
|
|
92
|
+
- temporary-file-plus-rename writes for atomic publication;
|
|
93
|
+
- polling with bounded intervals on both parent and child sides;
|
|
94
|
+
- sender and target identity validation; and
|
|
95
|
+
- bounded queue, message-size, and retention limits.
|
|
96
|
+
|
|
97
|
+
The transport boundary must be replaceable later by a socket without changing
|
|
98
|
+
the task or message records.
|
|
99
|
+
|
|
100
|
+
### 1.5 Task concurrency
|
|
101
|
+
|
|
102
|
+
An agent has at most one active delegated task in the first version. This
|
|
103
|
+
restriction applies only to delegated tasks. An agent may send and receive
|
|
104
|
+
ordinary messages while its task is running or waiting.
|
|
105
|
+
|
|
106
|
+
Messages do not create an active-task slot and do not settle a task.
|
|
107
|
+
|
|
108
|
+
### 1.6 Waiting semantics
|
|
109
|
+
|
|
110
|
+
A message with `expectsReply: true` creates a pending request. If it is linked
|
|
111
|
+
to the sender's active task, the task enters `waiting`.
|
|
112
|
+
|
|
113
|
+
A task can therefore be represented as:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
Pi process: idle
|
|
117
|
+
Task: waiting
|
|
118
|
+
Pending request: request-123
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
A reply clears the pending request and returns the task to `running`. A task
|
|
122
|
+
remains open until `shepherd_done`, cancellation, failure, or timeout.
|
|
123
|
+
|
|
124
|
+
### 1.7 Explicit completion tool
|
|
125
|
+
|
|
126
|
+
`shepherd_done` is a child-facing lifecycle tool, not a conversational
|
|
127
|
+
message. It is the reliable semantic completion signal. The child prompt and
|
|
128
|
+
runtime context must instruct the model to call it only when the delegated
|
|
129
|
+
task is actually complete.
|
|
130
|
+
|
|
131
|
+
The child runtime may report turn-settled events for observability, but those
|
|
132
|
+
events must never substitute for `shepherd_done`.
|
|
133
|
+
|
|
134
|
+
## 2. Target architecture
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
Parent Shepherd process
|
|
138
|
+
┌──────────────────────────────────────────────────────────────────────┐
|
|
139
|
+
│ parent tools: delegate/message/watch/status/close/read │
|
|
140
|
+
│ │
|
|
141
|
+
│ TaskRegistry MessageBroker TaskWatcher/StaleWaitMonitor │
|
|
142
|
+
│ │ │ │ │
|
|
143
|
+
│ └──────────────┬─────┴─────────────────────────┘ │
|
|
144
|
+
│ │ │
|
|
145
|
+
│ session mailbox directory │
|
|
146
|
+
└─────────────────────┼───────────────────────────────────────────────────┘
|
|
147
|
+
│ atomic JSON envelopes
|
|
148
|
+
┌────────────────┴───────────────────┐
|
|
149
|
+
│ │
|
|
150
|
+
Child scout process Child planner process
|
|
151
|
+
┌─────────────────────────┐ ┌─────────────────────────┐
|
|
152
|
+
│ shepherd-agent.ts │ │ shepherd-agent.ts │
|
|
153
|
+
│ shepherd_message tool │ │ shepherd_message tool │
|
|
154
|
+
│ shepherd_done tool │ │ shepherd_done tool │
|
|
155
|
+
│ Pi sendUserMessage() │ │ Pi sendUserMessage() │
|
|
156
|
+
└─────────────────────────┘ └─────────────────────────┘
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The existing `LifecycleRegistry` remains the parent-session authority for
|
|
160
|
+
opaque identifiers, but task and message records should be separated from the
|
|
161
|
+
old prompt-specific assumptions. The likely split is:
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
src/core/orchestration.ts opaque ids, task records, message/request records
|
|
165
|
+
src/core/messaging.ts envelopes, mailbox transport, routing and polling
|
|
166
|
+
src/core/lifecycle.ts delegate, done, watch, status, close adapters
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A separate `task-registry.ts` may be used if `orchestration.ts` becomes too
|
|
170
|
+
large. It must still use the same parent-session identity and opaque-ID rules.
|
|
171
|
+
|
|
172
|
+
## 3. Data model and contracts
|
|
173
|
+
|
|
174
|
+
### 3.1 Task record
|
|
175
|
+
|
|
176
|
+
Add an internal task record with at least:
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
interface TaskRecord {
|
|
180
|
+
taskId: string;
|
|
181
|
+
agentId: string;
|
|
182
|
+
description: string;
|
|
183
|
+
state: 'created' | 'running' | 'waiting' | 'completed' |
|
|
184
|
+
'blocked' | 'failed' | 'cancelled' | 'timed_out';
|
|
185
|
+
createdAt: number;
|
|
186
|
+
startedAt?: number;
|
|
187
|
+
waitingSince?: number;
|
|
188
|
+
deadlineAt?: number;
|
|
189
|
+
pendingRequestIds: Set<string>;
|
|
190
|
+
staleNotifiedAt?: number;
|
|
191
|
+
result?: TaskResult;
|
|
192
|
+
artifactSession?: ShepherdSession;
|
|
193
|
+
artifact?: ArtifactReservation;
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`Set` is an internal representation only. Any data crossing the tool or
|
|
198
|
+
mailbox boundary must use arrays and JSON-safe values.
|
|
199
|
+
|
|
200
|
+
The task registry must provide methods equivalent to:
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
createTask(agent, description, options)
|
|
204
|
+
getTask(taskId)
|
|
205
|
+
canonicalTaskId(input)
|
|
206
|
+
setRunning(taskId)
|
|
207
|
+
addPendingRequest(taskId, requestId)
|
|
208
|
+
resolvePendingRequest(taskId, requestId)
|
|
209
|
+
setWaiting(taskId)
|
|
210
|
+
settleTask(taskId, result)
|
|
211
|
+
cancelTask(taskId, reason)
|
|
212
|
+
listTasks()
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
All terminal settlement must be idempotent. A second `done`, timeout, failure,
|
|
216
|
+
or cancellation event must return the existing terminal result without
|
|
217
|
+
modifying it.
|
|
218
|
+
|
|
219
|
+
### 3.2 Task result
|
|
220
|
+
|
|
221
|
+
Use a task-oriented result shape:
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
interface TaskResult {
|
|
225
|
+
taskId: string;
|
|
226
|
+
agentId: string;
|
|
227
|
+
status: 'completed' | 'blocked' | 'failed' |
|
|
228
|
+
'cancelled' | 'timed_out';
|
|
229
|
+
ok: boolean;
|
|
230
|
+
returnCode: number;
|
|
231
|
+
text?: string;
|
|
232
|
+
error?: string;
|
|
233
|
+
completedAt: number;
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
`text` should contain the explicit `shepherd_done` summary when present, with
|
|
238
|
+
the child's latest assistant text as a fallback for diagnostic results. A
|
|
239
|
+
fallback must not turn an otherwise idle child into a successful task.
|
|
240
|
+
|
|
241
|
+
### 3.3 Message envelope
|
|
242
|
+
|
|
243
|
+
Create a JSON-safe envelope shared by parent and child:
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
interface ShepherdMessageEnvelope {
|
|
247
|
+
kind: 'message' | 'task' | 'reply' | 'task_done' | 'runtime';
|
|
248
|
+
messageId: string;
|
|
249
|
+
senderId: string;
|
|
250
|
+
targetId: string;
|
|
251
|
+
taskId?: string;
|
|
252
|
+
threadId?: string;
|
|
253
|
+
replyTo?: string;
|
|
254
|
+
expectsReply?: boolean;
|
|
255
|
+
delivery: 'followUp' | 'steer';
|
|
256
|
+
content?: string;
|
|
257
|
+
status?: 'completed' | 'blocked' | 'failed';
|
|
258
|
+
summary?: string;
|
|
259
|
+
error?: string;
|
|
260
|
+
createdAt: number;
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Use a dedicated `task_done` envelope for `shepherd_done` rather than
|
|
265
|
+
pretending that completion is an ordinary chat message. `runtime` envelopes
|
|
266
|
+
may be used for non-terminal turn status and diagnostics, but they must never
|
|
267
|
+
settle a task.
|
|
268
|
+
|
|
269
|
+
The public tool result should expose only the relevant opaque identifier and
|
|
270
|
+
structured acceptance status. Internal sender/session capabilities must not be
|
|
271
|
+
returned as public handles.
|
|
272
|
+
|
|
273
|
+
### 3.4 Pending requests
|
|
274
|
+
|
|
275
|
+
Maintain a request record or request fields on the message record:
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
interface RequestRecord {
|
|
279
|
+
requestId: string;
|
|
280
|
+
messageId: string;
|
|
281
|
+
senderId: string;
|
|
282
|
+
targetId: string;
|
|
283
|
+
taskId?: string;
|
|
284
|
+
state: 'pending' | 'replied' | 'cancelled' | 'timed_out';
|
|
285
|
+
createdAt: number;
|
|
286
|
+
deadlineAt?: number;
|
|
287
|
+
repliedAt?: number;
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
The first implementation may allow only one unresolved required request per
|
|
292
|
+
task. The data model should use a collection so multiple-request support can
|
|
293
|
+
be added without changing the task state representation.
|
|
294
|
+
|
|
295
|
+
## 4. Implementation phases
|
|
296
|
+
|
|
297
|
+
### Phase 0 — Baseline and specification guardrails
|
|
298
|
+
|
|
299
|
+
Before changing runtime behavior:
|
|
300
|
+
|
|
301
|
+
1. Run `npm test` and record the current baseline.
|
|
302
|
+
2. Add a small test helper for deterministic clock control where stale-wait
|
|
303
|
+
behavior needs time advancement.
|
|
304
|
+
3. Add schema placeholders for the new tools to
|
|
305
|
+
`test/verify-tool-schemas.mjs`.
|
|
306
|
+
4. Add comments or assertions documenting that Pi idle/settled state is not
|
|
307
|
+
task completion.
|
|
308
|
+
5. Keep the existing prompt/watcher tests green until the compatibility
|
|
309
|
+
adapter is introduced.
|
|
310
|
+
|
|
311
|
+
Files:
|
|
312
|
+
|
|
313
|
+
```text
|
|
314
|
+
test/verify-tool-schemas.mjs
|
|
315
|
+
package.json
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Acceptance:
|
|
319
|
+
|
|
320
|
+
- Existing tests pass.
|
|
321
|
+
- The new test harness can inspect parent and child tool registrations.
|
|
322
|
+
|
|
323
|
+
### Phase 1 — Add task records and task-state transitions
|
|
324
|
+
|
|
325
|
+
Implement the task registry before adding mailbox traffic.
|
|
326
|
+
|
|
327
|
+
1. Add task IDs with the same parent-session-scoped opaque-ID strategy used by
|
|
328
|
+
agent and prompt IDs.
|
|
329
|
+
2. Add `TaskRecord` and `TaskResult` types.
|
|
330
|
+
3. Implement the task state transition methods.
|
|
331
|
+
4. Reject invalid transitions with structured lifecycle errors.
|
|
332
|
+
5. Ensure `waiting` does not clear the task's active ownership.
|
|
333
|
+
6. Ensure task settlement clears any pending request associations and runs
|
|
334
|
+
artifact finalization exactly once.
|
|
335
|
+
7. Keep the existing prompt registry intact temporarily, but introduce an
|
|
336
|
+
explicit mapping type for compatibility prompt IDs to task IDs.
|
|
337
|
+
|
|
338
|
+
Files:
|
|
339
|
+
|
|
340
|
+
```text
|
|
341
|
+
src/core/orchestration.ts
|
|
342
|
+
src/core/lifecycle.ts
|
|
343
|
+
possibly src/core/task-registry.ts
|
|
344
|
+
|
|
345
|
+
test/verify-task-registry.mjs
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Required unit cases:
|
|
349
|
+
|
|
350
|
+
```text
|
|
351
|
+
created -> running
|
|
352
|
+
running -> waiting
|
|
353
|
+
waiting -> running
|
|
354
|
+
running -> completed
|
|
355
|
+
waiting -> completed only after requests are resolved/cancelled
|
|
356
|
+
running/waiting -> failed
|
|
357
|
+
running/waiting -> cancelled
|
|
358
|
+
running/waiting -> timed_out
|
|
359
|
+
idle process + waiting task remains non-terminal
|
|
360
|
+
repeated terminal events are idempotent
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Acceptance:
|
|
364
|
+
|
|
365
|
+
- No task can settle from a synthetic idle or turn-ended event.
|
|
366
|
+
- A task can remain waiting while its child process is idle.
|
|
367
|
+
|
|
368
|
+
### Phase 2 — Implement the parent-owned mailbox
|
|
369
|
+
|
|
370
|
+
Create the transport independently of Pi and Herdr behavior.
|
|
371
|
+
|
|
372
|
+
1. Add a parent-session mailbox directory under the Shepherd runtime area.
|
|
373
|
+
2. Create the directory with mode `0700`.
|
|
374
|
+
3. Create per-agent inboxes and a parent inbox.
|
|
375
|
+
4. Publish each envelope by writing a random temporary file and atomically
|
|
376
|
+
renaming it to a filename containing the message ID.
|
|
377
|
+
5. Read only complete JSON files.
|
|
378
|
+
6. Move processed files to an archive or delete them after an acknowledgement,
|
|
379
|
+
while retaining enough state to deduplicate repeated delivery.
|
|
380
|
+
7. Enforce maximum message size and queue depth.
|
|
381
|
+
8. Validate the envelope schema before routing.
|
|
382
|
+
9. Add sender capability validation so a child can only publish as its own
|
|
383
|
+
agent ID.
|
|
384
|
+
10. Add parent-session and broker identity fields so a child cannot submit to
|
|
385
|
+
another Shepherd session's mailbox by guessing a path.
|
|
386
|
+
|
|
387
|
+
Files:
|
|
388
|
+
|
|
389
|
+
```text
|
|
390
|
+
src/core/messaging.ts
|
|
391
|
+
src/core/messaging-types.ts (if useful)
|
|
392
|
+
src/core/herdr.ts mailbox creation and launch environment
|
|
393
|
+
|
|
394
|
+
test/verify-messaging.mjs
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
The initial polling API should support:
|
|
398
|
+
|
|
399
|
+
```text
|
|
400
|
+
createParentBroker(sessionOwner)
|
|
401
|
+
registerChild(agentId)
|
|
402
|
+
publishFromParent(envelope)
|
|
403
|
+
publishFromChild(capability, envelope)
|
|
404
|
+
pollParentInbox()
|
|
405
|
+
pollAgentInbox(agentId)
|
|
406
|
+
acknowledge(messageId)
|
|
407
|
+
closeBrokerWhenChildrenGone()
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
Acceptance:
|
|
411
|
+
|
|
412
|
+
- Parent-to-child and child-to-parent envelopes survive partial writes.
|
|
413
|
+
- Duplicate files do not result in duplicate task settlement or duplicate
|
|
414
|
+
message delivery.
|
|
415
|
+
- Invalid sender, target, session, and envelope data are rejected.
|
|
416
|
+
- Transport tests do not require a running Herdr instance.
|
|
417
|
+
|
|
418
|
+
### Phase 3 — Add the child-side Shepherd extension
|
|
419
|
+
|
|
420
|
+
Create the child extension that bridges the mailbox to the local Pi session.
|
|
421
|
+
|
|
422
|
+
1. Add `src/extension/shepherd-agent.ts` as the child-only extension, or
|
|
423
|
+
refactor `shepherd-done.ts` into a shared child extension while preserving
|
|
424
|
+
its default entrypoint behavior.
|
|
425
|
+
2. Register `shepherd_message` with a flat TypeBox object schema.
|
|
426
|
+
3. Register `shepherd_done` with a flat TypeBox object schema.
|
|
427
|
+
4. Obtain the child identity, broker path, parent identity, and current task ID
|
|
428
|
+
from launch environment/context.
|
|
429
|
+
5. Publish outgoing messages and task-done envelopes to the mailbox.
|
|
430
|
+
6. Poll the child inbox at a bounded interval.
|
|
431
|
+
7. Deliver incoming messages through `pi.sendUserMessage` using the requested
|
|
432
|
+
`followUp` or `steer` behavior.
|
|
433
|
+
8. Include sender, message ID, task ID, thread ID, and reply metadata in the
|
|
434
|
+
rendered message text.
|
|
435
|
+
9. Return an acknowledgement from the child tool once the envelope has been
|
|
436
|
+
accepted by the broker; do not wait for the recipient to answer.
|
|
437
|
+
10. Make child polling timers `unref`-safe and clean them up on shutdown.
|
|
438
|
+
|
|
439
|
+
The child message presentation should be explicit, for example:
|
|
440
|
+
|
|
441
|
+
```text
|
|
442
|
+
[Shepherd message from planner]
|
|
443
|
+
Message ID: shepherd-message-...
|
|
444
|
+
Reply to: shepherd-message-...
|
|
445
|
+
|
|
446
|
+
<message content>
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
The child task context should be explicit, for example:
|
|
450
|
+
|
|
451
|
+
```text
|
|
452
|
+
[Shepherd delegated task]
|
|
453
|
+
Task ID: shepherd-task-...
|
|
454
|
+
|
|
455
|
+
<task description>
|
|
456
|
+
|
|
457
|
+
Do not consider the task complete merely because this Pi turn ends. If you
|
|
458
|
+
need information, use shepherd_message. Call shepherd_done only when the
|
|
459
|
+
whole delegated task is complete.
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
Files:
|
|
463
|
+
|
|
464
|
+
```text
|
|
465
|
+
src/extension/shepherd-agent.ts
|
|
466
|
+
src/extension/shepherd-done.ts
|
|
467
|
+
src/core/herdr.ts
|
|
468
|
+
index.ts
|
|
469
|
+
|
|
470
|
+
test/verify-child-surface.mjs
|
|
471
|
+
test/verify-launch.mjs
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Acceptance:
|
|
475
|
+
|
|
476
|
+
- Child sessions receive only child messaging/completion tools, never the
|
|
477
|
+
parent-only lifecycle surface.
|
|
478
|
+
- A child can send a message without blocking its current model workflow.
|
|
479
|
+
- A child can call `shepherd_done` and publish a task terminal event.
|
|
480
|
+
- Incoming follow-up messages are delivered through Pi's supported queue API.
|
|
481
|
+
|
|
482
|
+
### Phase 4 — Replace prompt submission with tracked delegation
|
|
483
|
+
|
|
484
|
+
Implement the parent-side delegation path.
|
|
485
|
+
|
|
486
|
+
1. Add `delegateAgent()` in `src/core/lifecycle.ts`.
|
|
487
|
+
2. Resolve the target agent using the existing opaque agent registry.
|
|
488
|
+
3. Enforce one active delegated task per agent.
|
|
489
|
+
4. Create the task record before publishing the task envelope.
|
|
490
|
+
5. Reserve and attach the fieldnote artifact to the task, not to an ordinary
|
|
491
|
+
message.
|
|
492
|
+
6. Add the task context to the delegated child message.
|
|
493
|
+
7. Publish the task envelope through the broker.
|
|
494
|
+
8. Return as soon as the broker accepts the task.
|
|
495
|
+
9. If publication fails, settle the task as failed and finalize its artifact.
|
|
496
|
+
10. Do not use Herdr's current `agent_end` completion sidecar as the task
|
|
497
|
+
success signal.
|
|
498
|
+
|
|
499
|
+
Add the `shepherd_delegate` registration in `src/extension/shepherd.ts`:
|
|
500
|
+
|
|
501
|
+
```text
|
|
502
|
+
required: target, task
|
|
503
|
+
optional: timeout
|
|
504
|
+
returns: taskId, agentId, accepted
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
The tool must follow the repository convention that `name`, `label`,
|
|
508
|
+
`description`, `promptSnippet`, and `parameters` are written directly in the
|
|
509
|
+
registration.
|
|
510
|
+
|
|
511
|
+
Files:
|
|
512
|
+
|
|
513
|
+
```text
|
|
514
|
+
src/core/lifecycle.ts
|
|
515
|
+
src/core/orchestration.ts
|
|
516
|
+
src/extension/shepherd.ts
|
|
517
|
+
src/core/types.ts
|
|
518
|
+
src/core/herdr.ts
|
|
519
|
+
|
|
520
|
+
test/verify-delegate.mjs
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
Acceptance:
|
|
524
|
+
|
|
525
|
+
- Delegation is non-blocking.
|
|
526
|
+
- A second delegated task to the same agent is rejected clearly while the
|
|
527
|
+
first task remains active.
|
|
528
|
+
- Messages to that agent are still accepted while the task is active.
|
|
529
|
+
- Fieldnotes are created for tasks only.
|
|
530
|
+
|
|
531
|
+
### Phase 5 — Consume `shepherd_done` and external terminal events
|
|
532
|
+
|
|
533
|
+
Connect child task-done events to the parent task registry.
|
|
534
|
+
|
|
535
|
+
1. Add a parent broker handler for `task_done` envelopes.
|
|
536
|
+
2. Validate child identity and task ownership.
|
|
537
|
+
3. Reject completion of unknown, closed, or foreign tasks.
|
|
538
|
+
4. Reject successful completion when unresolved required requests remain,
|
|
539
|
+
unless the task explicitly cancels those requests.
|
|
540
|
+
5. Settle the task once and record its final summary/status.
|
|
541
|
+
6. Finalize the task's artifact through the existing artifact callback path.
|
|
542
|
+
7. Preserve the child session and pane according to existing `keepOpen` and
|
|
543
|
+
`stayOpen` settings.
|
|
544
|
+
8. Map child provider errors, unexpected process exit, close, and timeout to
|
|
545
|
+
task failure/cancellation/timeout.
|
|
546
|
+
9. Remove any logic that interprets a normal `agent_end` sidecar as successful
|
|
547
|
+
completion for a delegated task.
|
|
548
|
+
10. If the child extension reports `agent_settled`, treat it as an observation
|
|
549
|
+
only. Do not settle the task.
|
|
550
|
+
|
|
551
|
+
Refactor `shepherd-done.ts` so its completion responsibilities are task-aware.
|
|
552
|
+
The launch script and sidecar may remain as a process-health fallback, but the
|
|
553
|
+
sidecar must include an explicit task ID and must not claim task success for a
|
|
554
|
+
turn that ended while the task is waiting.
|
|
555
|
+
|
|
556
|
+
Files:
|
|
557
|
+
|
|
558
|
+
```text
|
|
559
|
+
src/extension/shepherd-done.ts
|
|
560
|
+
src/core/lifecycle.ts
|
|
561
|
+
src/core/orchestration.ts
|
|
562
|
+
src/core/herdr.ts
|
|
563
|
+
|
|
564
|
+
test/verify-task-completion.mjs
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Acceptance scenario:
|
|
568
|
+
|
|
569
|
+
```text
|
|
570
|
+
delegate scout task
|
|
571
|
+
scout sends question
|
|
572
|
+
scout turn settles
|
|
573
|
+
no task completion is emitted
|
|
574
|
+
scout calls shepherd_done later
|
|
575
|
+
watcher receives exactly one completed result
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
### Phase 6 — Implement asynchronous message routing
|
|
579
|
+
|
|
580
|
+
Add parent and child `shepherd_message` behavior.
|
|
581
|
+
|
|
582
|
+
1. Register the parent-side `shepherd_message` tool.
|
|
583
|
+
2. Register the child-side tool with the same conceptual name but a
|
|
584
|
+
child-specific adapter.
|
|
585
|
+
3. Permit child targets of `shepherd` and validated peer agent IDs.
|
|
586
|
+
4. Permit parent targets of owned child IDs.
|
|
587
|
+
5. Resolve `replyTo` and `threadId` without exposing pane IDs.
|
|
588
|
+
6. When `expectsReply` is true and a task ID is supplied, add the request to
|
|
589
|
+
the task's pending set and transition the task to `waiting`.
|
|
590
|
+
7. Queue incoming child messages into the parent with `pi.sendMessage` as a
|
|
591
|
+
custom Shepherd message using follow-up delivery.
|
|
592
|
+
8. Queue incoming child messages into child Pi sessions with
|
|
593
|
+
`pi.sendUserMessage`.
|
|
594
|
+
9. On a valid reply, clear the request and transition the owner task from
|
|
595
|
+
`waiting` to `running`.
|
|
596
|
+
10. Trigger a waiting child when a reply is delivered and the child is idle.
|
|
597
|
+
11. Keep ordinary messages independent of task completion and artifact
|
|
598
|
+
finalization.
|
|
599
|
+
12. Add a reply deadline and settle unresolved requests as blocked or timed out
|
|
600
|
+
according to task policy.
|
|
601
|
+
|
|
602
|
+
The initial implementation should keep routing parent-mediated. Do not add
|
|
603
|
+
automatic final-answer forwarding from one child to another; a recipient
|
|
604
|
+
should send its answer explicitly with `shepherd_message` and `replyTo`.
|
|
605
|
+
|
|
606
|
+
Files:
|
|
607
|
+
|
|
608
|
+
```text
|
|
609
|
+
src/core/messaging.ts
|
|
610
|
+
src/core/lifecycle.ts
|
|
611
|
+
src/extension/shepherd.ts
|
|
612
|
+
src/extension/shepherd-agent.ts
|
|
613
|
+
src/extension/types.ts or src/core/types.ts
|
|
614
|
+
|
|
615
|
+
test/verify-message-routing.mjs
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
Acceptance:
|
|
619
|
+
|
|
620
|
+
- Worker can ask planner while planner is busy.
|
|
621
|
+
- Planner receives the question as a queued follow-up.
|
|
622
|
+
- Worker remains waiting rather than completed.
|
|
623
|
+
- Planner can reply to worker.
|
|
624
|
+
- Worker resumes from the reply and can complete its task.
|
|
625
|
+
- A regular message with no `expectsReply` does not alter task state.
|
|
626
|
+
|
|
627
|
+
### Phase 7 — Generalize watching from prompts to tasks
|
|
628
|
+
|
|
629
|
+
Adapt the watcher implementation while preserving non-blocking delivery.
|
|
630
|
+
|
|
631
|
+
1. Add task watcher registration keyed by task IDs.
|
|
632
|
+
2. Accept one task ID or an array of task IDs.
|
|
633
|
+
3. Report only terminal task states.
|
|
634
|
+
4. Preserve one-shot, idempotent delivery.
|
|
635
|
+
5. Keep completion order deterministic for arrays while allowing individual
|
|
636
|
+
notifications as tasks settle.
|
|
637
|
+
6. Include task ID, agent ID, task status, summary, error, and return code.
|
|
638
|
+
7. Deliver completion notifications as custom parent messages with follow-up
|
|
639
|
+
semantics.
|
|
640
|
+
8. Do not trigger a parent turn for every intermediate message or waiting
|
|
641
|
+
transition.
|
|
642
|
+
9. Decide whether to preserve the current public prompt-ID spelling through a
|
|
643
|
+
compatibility adapter; document the decision in the migration section.
|
|
644
|
+
10. Remove any watcher path that reads child idle state as task success.
|
|
645
|
+
|
|
646
|
+
The new watcher flow is:
|
|
647
|
+
|
|
648
|
+
```text
|
|
649
|
+
shepherd_delegate -> taskId
|
|
650
|
+
shepherd_watch(taskId) -> immediate registration
|
|
651
|
+
child sends messages / waits / resumes
|
|
652
|
+
child shepherd_done -> task settlement
|
|
653
|
+
watcher -> parent custom completion notification
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
Files:
|
|
657
|
+
|
|
658
|
+
```text
|
|
659
|
+
src/core/lifecycle.ts
|
|
660
|
+
src/core/orchestration.ts
|
|
661
|
+
src/extension/shepherd.ts
|
|
662
|
+
src/core/types.ts
|
|
663
|
+
|
|
664
|
+
test/verify-task-watchers.mjs
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
Acceptance:
|
|
668
|
+
|
|
669
|
+
- Watching a waiting task remains pending.
|
|
670
|
+
- Watching a completed task returns its result immediately.
|
|
671
|
+
- Multiple watchers receive independent, idempotent notifications.
|
|
672
|
+
- Parent shutdown stops polling without corrupting settled task records.
|
|
673
|
+
|
|
674
|
+
### Phase 8 — Add stale-wait monitoring
|
|
675
|
+
|
|
676
|
+
Implement notification for tasks waiting too long for replies.
|
|
677
|
+
|
|
678
|
+
1. Add a configurable `staleWaitThreshold` setting, defaulting to a conservative
|
|
679
|
+
value such as two minutes.
|
|
680
|
+
2. Preserve the existing two-layer user/project settings model.
|
|
681
|
+
3. Add the setting to config validation, defaults, settings UI, and docs.
|
|
682
|
+
4. Start a parent-owned monitor only while there are waiting tasks.
|
|
683
|
+
5. Inspect task state, not raw Herdr idle state.
|
|
684
|
+
6. Require at least one unresolved `expectsReply` request.
|
|
685
|
+
7. Emit one stale notification per waiting episode.
|
|
686
|
+
8. Include task ID, agent, task description, waiting age, request ID, question,
|
|
687
|
+
target recipient, and recipient status.
|
|
688
|
+
9. Mark the notification as delivered without changing the task's lifecycle
|
|
689
|
+
state.
|
|
690
|
+
10. Clear the notification marker when a reply returns the task to `running`.
|
|
691
|
+
11. Add a separate long escalation interval only if real usage demonstrates a
|
|
692
|
+
need; do not repeatedly notify by default.
|
|
693
|
+
12. Do not trigger a parent model turn for every normal waiting transition.
|
|
694
|
+
A stale notification may use `pi.sendMessage` with follow-up delivery and
|
|
695
|
+
`triggerTurn: true` when the parent is idle.
|
|
696
|
+
|
|
697
|
+
Files:
|
|
698
|
+
|
|
699
|
+
```text
|
|
700
|
+
src/extension/config.ts
|
|
701
|
+
src/extension/settings-ui.ts
|
|
702
|
+
src/core/lifecycle.ts or src/core/task-monitor.ts
|
|
703
|
+
src/extension/shepherd.ts
|
|
704
|
+
|
|
705
|
+
test/verify-stale-wait.mjs
|
|
706
|
+
test/verify-settings.mjs
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
Acceptance:
|
|
710
|
+
|
|
711
|
+
- A waiting scout produces one notification after the threshold.
|
|
712
|
+
- A reply prevents additional notifications for that waiting episode.
|
|
713
|
+
- A later waiting episode can produce a new notification.
|
|
714
|
+
- A completed task never produces a stale-wait notification.
|
|
715
|
+
|
|
716
|
+
### Phase 9 — Update status and the TUI widget
|
|
717
|
+
|
|
718
|
+
Expose process and task state separately.
|
|
719
|
+
|
|
720
|
+
1. Extend `shepherd_status` to include task ID, task state, waiting age, pending
|
|
721
|
+
request, recipient, and stale flag when applicable.
|
|
722
|
+
2. Keep Herdr process state as a separate field.
|
|
723
|
+
3. Update `workingSubagents()` or add a task-aware status projection so an idle
|
|
724
|
+
process with a waiting task remains visible.
|
|
725
|
+
4. Render waiting rows distinctly from completed or working rows.
|
|
726
|
+
5. Preserve the current pane ownership filtering.
|
|
727
|
+
6. Avoid making widget rendering depend on direct mailbox reads on every frame;
|
|
728
|
+
poll into a snapshot at the existing widget interval.
|
|
729
|
+
|
|
730
|
+
Files:
|
|
731
|
+
|
|
732
|
+
```text
|
|
733
|
+
src/core/herdr.ts
|
|
734
|
+
src/core/lifecycle.ts
|
|
735
|
+
src/extension/shepherd.ts
|
|
736
|
+
index.ts
|
|
737
|
+
|
|
738
|
+
test/verify-status-widget.mjs
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
Acceptance example:
|
|
742
|
+
|
|
743
|
+
```text
|
|
744
|
+
○ 02:14 scout idle / waiting for planner
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
The status widget must not display the scout as completed merely because its
|
|
748
|
+
Pi process is idle.
|
|
749
|
+
|
|
750
|
+
### Phase 10 — Artifacts, cleanup, and compatibility
|
|
751
|
+
|
|
752
|
+
Integrate the new lifecycle with existing persistence and ownership rules.
|
|
753
|
+
|
|
754
|
+
1. Allocate one artifact reservation for each delegated task when the task is
|
|
755
|
+
created.
|
|
756
|
+
2. Do not allocate artifacts for ordinary messages or replies.
|
|
757
|
+
3. Keep the task artifact open during `waiting`.
|
|
758
|
+
4. Finalize it on completed, blocked, failed, cancelled, or timed-out task
|
|
759
|
+
settlement.
|
|
760
|
+
5. Include message/request references in the task artifact only if they are
|
|
761
|
+
useful task context; do not create one note per chat message.
|
|
762
|
+
6. Ensure broker cleanup happens only after all child panes are confirmed gone,
|
|
763
|
+
following the existing temporary-resource invariant.
|
|
764
|
+
7. Ensure closing an agent cancels its active task and unresolved requests.
|
|
765
|
+
8. Ensure a parent restart cannot accidentally claim another session's tasks or
|
|
766
|
+
panes.
|
|
767
|
+
9. Update the compatibility adapter for `shepherd_prompt` and
|
|
768
|
+
`shepherd_wait`, or remove them with an explicit migration note. Do not
|
|
769
|
+
silently expose two different meanings for the same prompt ID.
|
|
770
|
+
10. Update the shared Shepherd narrative and child instructions.
|
|
771
|
+
|
|
772
|
+
Files:
|
|
773
|
+
|
|
774
|
+
```text
|
|
775
|
+
src/core/artifact-sessions.ts
|
|
776
|
+
src/core/lifecycle.ts
|
|
777
|
+
src/core/herdr.ts
|
|
778
|
+
src/core/orchestration.ts
|
|
779
|
+
src/extension/shepherd.ts
|
|
780
|
+
src/extension/shepherd-agent.ts
|
|
781
|
+
index.ts
|
|
782
|
+
README.md
|
|
783
|
+
docs/guides/tool-reference.md
|
|
784
|
+
docs/reference/dictionary
|
|
785
|
+
docs/plans/architecture.md
|
|
786
|
+
```
|
|
787
|
+
|
|
788
|
+
Acceptance:
|
|
789
|
+
|
|
790
|
+
- Task artifacts remain open while a child waits.
|
|
791
|
+
- Message-only conversations do not create artifacts.
|
|
792
|
+
- Close, crash, timeout, and parent shutdown leave no unsafe temporary
|
|
793
|
+
resources.
|
|
794
|
+
- Public documentation describes task IDs, message IDs, and their different
|
|
795
|
+
lifetimes.
|
|
796
|
+
|
|
797
|
+
## 5. Tool schemas and model-facing surface
|
|
798
|
+
|
|
799
|
+
Every registration must use a flat root `Type.Object` schema and spell out
|
|
800
|
+
`name`, `label`, `description`, `promptSnippet`, and `parameters` directly in
|
|
801
|
+
the registration.
|
|
802
|
+
|
|
803
|
+
### `shepherd_delegate`
|
|
804
|
+
|
|
805
|
+
Parent-only:
|
|
806
|
+
|
|
807
|
+
```text
|
|
808
|
+
target: required opaque agent ID
|
|
809
|
+
task: required non-empty string
|
|
810
|
+
timeout: optional integer task deadline in minutes
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
Returns `taskId`, `agentId`, and acceptance state.
|
|
814
|
+
|
|
815
|
+
### `shepherd_message`
|
|
816
|
+
|
|
817
|
+
Parent and child adapters:
|
|
818
|
+
|
|
819
|
+
```text
|
|
820
|
+
target: required Shepherd, parent, or opaque agent ID
|
|
821
|
+
message: required non-empty string
|
|
822
|
+
taskId: optional active task ID
|
|
823
|
+
threadId: optional conversation ID
|
|
824
|
+
replyTo: optional request/message ID
|
|
825
|
+
expectsReply: optional boolean, default false
|
|
826
|
+
delivery: optional followUp|steer, default followUp
|
|
827
|
+
```
|
|
828
|
+
|
|
829
|
+
The child adapter may restrict `target` based on the child capability, but it
|
|
830
|
+
must use the same conceptual envelope.
|
|
831
|
+
|
|
832
|
+
### `shepherd_done`
|
|
833
|
+
|
|
834
|
+
Child-only:
|
|
835
|
+
|
|
836
|
+
```text
|
|
837
|
+
taskId: required opaque task ID
|
|
838
|
+
status: required completed|blocked|failed
|
|
839
|
+
summary: optional completion or failure summary
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
### `shepherd_watch`
|
|
843
|
+
|
|
844
|
+
Parent-only:
|
|
845
|
+
|
|
846
|
+
```text
|
|
847
|
+
id: required task ID or non-empty task ID array
|
|
848
|
+
```
|
|
849
|
+
|
|
850
|
+
If compatibility prompt IDs remain accepted, the adapter must explicitly state
|
|
851
|
+
that they resolve to associated task IDs and must not guess from agent IDs or
|
|
852
|
+
pane IDs.
|
|
853
|
+
|
|
854
|
+
## 6. Compatibility and migration strategy
|
|
855
|
+
|
|
856
|
+
The existing implementation has prompt records, prompt watchers, completion
|
|
857
|
+
sidecars, fieldnote callbacks, and tests built around one unresolved prompt per
|
|
858
|
+
agent. The migration must avoid a period where a single child can be governed
|
|
859
|
+
by two contradictory completion mechanisms.
|
|
860
|
+
|
|
861
|
+
Recommended migration sequence:
|
|
862
|
+
|
|
863
|
+
1. Introduce task records and task IDs without changing existing public calls.
|
|
864
|
+
2. Add the mailbox and child extension behind new `shepherd_delegate` and
|
|
865
|
+
`shepherd_message` tools.
|
|
866
|
+
3. Route new delegated tasks exclusively through task records.
|
|
867
|
+
4. Make `shepherd_watch` task-aware.
|
|
868
|
+
5. Add a compatibility mapping from old prompt IDs to task IDs.
|
|
869
|
+
6. Update `shepherd_prompt` to call the compatibility delegation adapter.
|
|
870
|
+
7. Update `shepherd_wait` to wait on the mapped task only if it is retained.
|
|
871
|
+
8. Remove prompt-specific successful completion detection from the child
|
|
872
|
+
sidecar.
|
|
873
|
+
9. Update all active documentation and tests.
|
|
874
|
+
10. Retain historical prompt terminology only in migration notes or archived
|
|
875
|
+
plans.
|
|
876
|
+
|
|
877
|
+
Do not support both of these simultaneously for the same delegated task:
|
|
878
|
+
|
|
879
|
+
```text
|
|
880
|
+
agent_end sidecar means success
|
|
881
|
+
shepherd_done means success
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
The explicit task protocol must be authoritative.
|
|
885
|
+
|
|
886
|
+
## 7. Test plan
|
|
887
|
+
|
|
888
|
+
### 7.1 Registry and state tests
|
|
889
|
+
|
|
890
|
+
Add `test/verify-task-registry.mjs` covering:
|
|
891
|
+
|
|
892
|
+
- opaque task IDs are session-scoped;
|
|
893
|
+
- one active task per agent;
|
|
894
|
+
- messages do not consume the task slot;
|
|
895
|
+
- waiting tasks remain non-terminal;
|
|
896
|
+
- all valid state transitions;
|
|
897
|
+
- invalid transitions;
|
|
898
|
+
- idempotent terminal settlement;
|
|
899
|
+
- request resolution and cancellation;
|
|
900
|
+
- task timeout and close cancellation.
|
|
901
|
+
|
|
902
|
+
### 7.2 Mailbox tests
|
|
903
|
+
|
|
904
|
+
Add `test/verify-messaging.mjs` covering:
|
|
905
|
+
|
|
906
|
+
- atomic publication and complete-file reads;
|
|
907
|
+
- parent-to-child delivery;
|
|
908
|
+
- child-to-parent delivery;
|
|
909
|
+
- duplicate envelope handling;
|
|
910
|
+
- malformed envelope rejection;
|
|
911
|
+
- invalid sender capability rejection;
|
|
912
|
+
- unknown target rejection;
|
|
913
|
+
- queue depth and message-size limits;
|
|
914
|
+
- broker cleanup after child disappearance.
|
|
915
|
+
|
|
916
|
+
### 7.3 Child surface tests
|
|
917
|
+
|
|
918
|
+
Add `test/verify-child-surface.mjs` covering:
|
|
919
|
+
|
|
920
|
+
- child sessions receive `shepherd_message` and `shepherd_done` only;
|
|
921
|
+
- parent sessions receive parent lifecycle tools;
|
|
922
|
+
- child message tools return acceptance without waiting for replies;
|
|
923
|
+
- `shepherd_done` publishes a task-done control envelope;
|
|
924
|
+
- incoming messages invoke Pi queue APIs with the requested delivery mode.
|
|
925
|
+
|
|
926
|
+
Update `test/verify-launch.mjs` to verify:
|
|
927
|
+
|
|
928
|
+
- broker environment wiring;
|
|
929
|
+
- child identity wiring;
|
|
930
|
+
- task identity wiring;
|
|
931
|
+
- child extension wiring; and
|
|
932
|
+
- no parent-only surface in the child.
|
|
933
|
+
|
|
934
|
+
### 7.4 Conversation and task tests
|
|
935
|
+
|
|
936
|
+
Add `test/verify-task-messaging.mjs` covering the canonical scenario:
|
|
937
|
+
|
|
938
|
+
```text
|
|
939
|
+
1. delegate task to scout
|
|
940
|
+
2. scout sends expectsReply question to busy planner
|
|
941
|
+
3. scout turn settles
|
|
942
|
+
4. scout process is idle
|
|
943
|
+
5. scout task remains waiting
|
|
944
|
+
6. no watcher completion is delivered
|
|
945
|
+
7. planner receives the queued question
|
|
946
|
+
8. planner replies with replyTo
|
|
947
|
+
9. scout receives the reply as followUp
|
|
948
|
+
10. scout task returns to running
|
|
949
|
+
11. scout calls shepherd_done
|
|
950
|
+
12. watcher receives exactly one completed result
|
|
951
|
+
```
|
|
952
|
+
|
|
953
|
+
Also cover:
|
|
954
|
+
|
|
955
|
+
- a non-reply message while a task is running;
|
|
956
|
+
- a message to the Shepherd;
|
|
957
|
+
- multiple independent messages;
|
|
958
|
+
- a peer reply arriving while the child is idle;
|
|
959
|
+
- reply timeout;
|
|
960
|
+
- planner closure while scout waits;
|
|
961
|
+
- scout closure while planner has a queued question; and
|
|
962
|
+
- duplicate replies and duplicate done events.
|
|
963
|
+
|
|
964
|
+
### 7.5 Watcher and notification tests
|
|
965
|
+
|
|
966
|
+
Add `test/verify-task-watchers.mjs` covering:
|
|
967
|
+
|
|
968
|
+
- immediate registration;
|
|
969
|
+
- already-completed tasks;
|
|
970
|
+
- one and multiple task IDs;
|
|
971
|
+
- independent watcher delivery;
|
|
972
|
+
- completion ordering;
|
|
973
|
+
- failed, blocked, cancelled, and timed-out outcomes;
|
|
974
|
+
- no settlement on `agent_end`, `agent_settled`, or idle; and
|
|
975
|
+
- no parent turn after watcher shutdown.
|
|
976
|
+
|
|
977
|
+
Add `test/verify-stale-wait.mjs` covering:
|
|
978
|
+
|
|
979
|
+
- threshold crossing;
|
|
980
|
+
- one notification per waiting episode;
|
|
981
|
+
- notification content and correlation IDs;
|
|
982
|
+
- reset after a reply;
|
|
983
|
+
- no notification for completed tasks;
|
|
984
|
+
- no notification for ordinary idle agents; and
|
|
985
|
+
- request timeout/escalation behavior.
|
|
986
|
+
|
|
987
|
+
### 7.6 Schema and documentation tests
|
|
988
|
+
|
|
989
|
+
Update:
|
|
990
|
+
|
|
991
|
+
```text
|
|
992
|
+
test/verify-tool-schemas.mjs
|
|
993
|
+
test/verify-parent-surface.mjs
|
|
994
|
+
test/verify-status-widget.mjs
|
|
995
|
+
```
|
|
996
|
+
|
|
997
|
+
The schema test must verify that every new model-facing registration has a
|
|
998
|
+
flat object root and explicit required fields. The parent-surface test must
|
|
999
|
+
verify role-specific registration in parent and child processes.
|
|
1000
|
+
|
|
1001
|
+
### 7.7 Live Herdr verification
|
|
1002
|
+
|
|
1003
|
+
After focused tests pass, run the live matrix:
|
|
1004
|
+
|
|
1005
|
+
1. Start or attach to Herdr.
|
|
1006
|
+
2. Spawn scout and planner as persistent agents.
|
|
1007
|
+
3. Delegate a task to scout.
|
|
1008
|
+
4. Prompt scout, through its task context, to ask planner a question.
|
|
1009
|
+
5. Keep planner busy so scout's current turn settles first.
|
|
1010
|
+
6. Confirm scout's Herdr state becomes idle while task state remains waiting.
|
|
1011
|
+
7. Confirm no `shepherd_watch` completion occurs.
|
|
1012
|
+
8. Confirm the stale-wait notification after the configured threshold.
|
|
1013
|
+
9. Allow planner to answer.
|
|
1014
|
+
10. Confirm scout receives the answer and resumes.
|
|
1015
|
+
11. Confirm scout calls `shepherd_done`.
|
|
1016
|
+
12. Confirm exactly one watcher completion notification.
|
|
1017
|
+
13. Verify status and widget output during the waiting interval.
|
|
1018
|
+
14. Repeat with close, timeout, provider failure, and parent shutdown.
|
|
1019
|
+
15. Verify pane ownership and temporary-resource cleanup.
|
|
1020
|
+
|
|
1021
|
+
Finally run:
|
|
1022
|
+
|
|
1023
|
+
```bash
|
|
1024
|
+
npm test
|
|
1025
|
+
```
|
|
1026
|
+
|
|
1027
|
+
## 8. Documentation updates
|
|
1028
|
+
|
|
1029
|
+
Update active documentation only after the API and compatibility behavior are
|
|
1030
|
+
settled.
|
|
1031
|
+
|
|
1032
|
+
Required updates:
|
|
1033
|
+
|
|
1034
|
+
```text
|
|
1035
|
+
README.md
|
|
1036
|
+
docs/guides/tool-reference.md
|
|
1037
|
+
docs/reference/dictionary
|
|
1038
|
+
docs/plans/architecture.md
|
|
1039
|
+
```
|
|
1040
|
+
|
|
1041
|
+
Document:
|
|
1042
|
+
|
|
1043
|
+
- task IDs versus message IDs;
|
|
1044
|
+
- `shepherd_delegate` versus `shepherd_message`;
|
|
1045
|
+
- explicit `shepherd_done` completion;
|
|
1046
|
+
- `shepherd_watch` as the preferred non-blocking observer;
|
|
1047
|
+
- waiting tasks whose agents may be idle;
|
|
1048
|
+
- `followUp` versus `steer` delivery;
|
|
1049
|
+
- stale-wait notifications; and
|
|
1050
|
+
- the compatibility status of `shepherd_prompt` and `shepherd_wait`.
|
|
1051
|
+
|
|
1052
|
+
The umbrella Shepherd description should explain that a Pi turn ending does
|
|
1053
|
+
not complete a delegated task and that agents should use `shepherd_message`
|
|
1054
|
+
for questions and `shepherd_done` only for actual task completion.
|
|
1055
|
+
|
|
1056
|
+
## 9. Delivery order and review gates
|
|
1057
|
+
|
|
1058
|
+
Each phase should be implemented and reviewed before the next phase begins.
|
|
1059
|
+
|
|
1060
|
+
```text
|
|
1061
|
+
Phase 0 baseline and guardrails
|
|
1062
|
+
Phase 1 task registry
|
|
1063
|
+
Phase 2 mailbox transport
|
|
1064
|
+
Phase 3 child extension
|
|
1065
|
+
Phase 4 delegation
|
|
1066
|
+
Phase 5 explicit completion
|
|
1067
|
+
Phase 6 message routing
|
|
1068
|
+
Phase 7 task watchers
|
|
1069
|
+
Phase 8 stale-wait monitor
|
|
1070
|
+
Phase 9 status and widget
|
|
1071
|
+
Phase 10 artifacts, cleanup, compatibility, docs
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
Review gates:
|
|
1075
|
+
|
|
1076
|
+
- After Phase 1: verify that idle is not completion.
|
|
1077
|
+
- After Phase 3: verify child and parent surfaces are isolated.
|
|
1078
|
+
- After Phase 5: verify explicit `shepherd_done` is authoritative.
|
|
1079
|
+
- After Phase 6: verify the scout/planner waiting scenario manually.
|
|
1080
|
+
- After Phase 8: verify stale notifications do not create message storms.
|
|
1081
|
+
- After Phase 10: run the full test suite and live Herdr matrix.
|
|
1082
|
+
|
|
1083
|
+
The feature is complete only when the canonical waiting scenario is correct:
|
|
1084
|
+
|
|
1085
|
+
```text
|
|
1086
|
+
scout's Pi turn ends
|
|
1087
|
+
scout is idle
|
|
1088
|
+
scout's task is waiting, not done
|
|
1089
|
+
planner replies
|
|
1090
|
+
scout resumes
|
|
1091
|
+
scout explicitly calls shepherd_done
|
|
1092
|
+
shepherd_watch reports completion
|
|
1093
|
+
```
|