@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,838 @@
|
|
|
1
|
+
# Tasks: Asynchronous Shepherd Tasks and Agent Messaging
|
|
2
|
+
|
|
3
|
+
This checklist tracks implementation of:
|
|
4
|
+
|
|
5
|
+
- `docs/specs/005-agent-messaging-and-task-lifecycle/spec.md`
|
|
6
|
+
- `docs/specs/005-agent-messaging-and-task-lifecycle/plan.md`
|
|
7
|
+
|
|
8
|
+
## How to use this checklist
|
|
9
|
+
|
|
10
|
+
- Complete tasks in phase order unless a task explicitly says it can run in
|
|
11
|
+
parallel.
|
|
12
|
+
- Check an item only when the implementation and its focused tests are done.
|
|
13
|
+
- Keep compatibility behavior explicit; do not silently mix prompt and task
|
|
14
|
+
completion semantics.
|
|
15
|
+
- Every phase has an exit gate. Do not begin dependent phases until its gate is
|
|
16
|
+
satisfied.
|
|
17
|
+
|
|
18
|
+
## Overall status
|
|
19
|
+
|
|
20
|
+
- [x] Feature implementation complete
|
|
21
|
+
- [x] Focused tests written and passing
|
|
22
|
+
- [x] Existing regression tests updated and passing
|
|
23
|
+
- [x] Live Herdr verification complete
|
|
24
|
+
- [x] README and user documentation updated
|
|
25
|
+
- [x] Documentation and migration notes complete
|
|
26
|
+
- [x] `npm test` passes
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Phase 0 — Baseline and guardrails
|
|
31
|
+
|
|
32
|
+
### Repository baseline
|
|
33
|
+
|
|
34
|
+
- [x] Read and confirm the requirements in `spec.md`.
|
|
35
|
+
- [x] Read and confirm the sequencing and decisions in `plan.md`.
|
|
36
|
+
- [x] Run the existing `npm test` suite and record the baseline result.
|
|
37
|
+
- [x] Record the current public tool list and schemas.
|
|
38
|
+
- [x] Record the current parent/child extension registration behavior.
|
|
39
|
+
- [x] Confirm the current completion path uses `agent_end` and sidecar signals.
|
|
40
|
+
- [x] Confirm the current registry enforces one unresolved prompt per agent.
|
|
41
|
+
- [x] Confirm current fieldnote finalization is attached to prompt settlement.
|
|
42
|
+
- [x] Capture the findings in `docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md`.
|
|
43
|
+
|
|
44
|
+
### Test scaffolding
|
|
45
|
+
|
|
46
|
+
- [x] Add a reusable temporary-directory helper for mailbox tests.
|
|
47
|
+
- [x] Add deterministic clock/timer helpers for stale-wait tests.
|
|
48
|
+
- [x] Add a test helper for creating fake parent and child identities.
|
|
49
|
+
- [x] Add schema-test placeholders for `shepherd_delegate`.
|
|
50
|
+
- [x] Add schema-test placeholders for `shepherd_message`.
|
|
51
|
+
- [x] Add schema-test placeholders for `shepherd_done`.
|
|
52
|
+
- [x] Add schema-test placeholders for task-aware `shepherd_watch`.
|
|
53
|
+
- [x] Add parent/child surface test placeholders.
|
|
54
|
+
- [x] Add the Phase 0 task-state boundary test in `test/verify-phase0.mjs`.
|
|
55
|
+
- [x] Centralize the Phase 0 contracts in `test/helpers/feature-contracts.mjs` for later phase tests.
|
|
56
|
+
|
|
57
|
+
### Exit gate
|
|
58
|
+
|
|
59
|
+
- [x] Baseline `npm test` result is recorded.
|
|
60
|
+
- [x] New tests can create isolated parent/child identities without Herdr.
|
|
61
|
+
- [x] No runtime behavior has changed yet; only test scaffolding and guardrail documentation were added.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Phase 1 — Task registry and task state
|
|
66
|
+
|
|
67
|
+
### Task identifiers and types
|
|
68
|
+
|
|
69
|
+
- [x] Define an opaque task ID format scoped to the parent Shepherd session.
|
|
70
|
+
- [x] Add task ID validation and canonicalization.
|
|
71
|
+
- [x] Add `TaskRecord` internal type.
|
|
72
|
+
- [x] Add `TaskResult` internal type.
|
|
73
|
+
- [x] Add task state union:
|
|
74
|
+
`created`, `running`, `waiting`, `completed`, `blocked`, `failed`,
|
|
75
|
+
`cancelled`, `timed_out`.
|
|
76
|
+
- [x] Add pending request tracking to task records.
|
|
77
|
+
- [x] Add `waitingSince` tracking.
|
|
78
|
+
- [x] Add task deadline tracking.
|
|
79
|
+
- [x] Add stale-notification tracking.
|
|
80
|
+
- [x] Add task-to-artifact association fields.
|
|
81
|
+
|
|
82
|
+
### Task registry operations
|
|
83
|
+
|
|
84
|
+
- [x] Implement task creation.
|
|
85
|
+
- [x] Implement task lookup by opaque task ID.
|
|
86
|
+
- [x] Implement task canonicalization.
|
|
87
|
+
- [x] Implement transition to `running`.
|
|
88
|
+
- [x] Implement transition to `waiting`.
|
|
89
|
+
- [x] Implement transition from `waiting` to `running`.
|
|
90
|
+
- [x] Implement terminal task settlement.
|
|
91
|
+
- [x] Implement task cancellation.
|
|
92
|
+
- [x] Implement task timeout settlement.
|
|
93
|
+
- [x] Implement task listing for status projection.
|
|
94
|
+
- [x] Make terminal settlement idempotent.
|
|
95
|
+
- [x] Reject invalid task IDs with the standard lifecycle error shape.
|
|
96
|
+
- [x] Reject completion of a task owned by another agent.
|
|
97
|
+
- [x] Reject mutation of a terminal task.
|
|
98
|
+
- [x] Ensure waiting does not clear active task ownership.
|
|
99
|
+
- [x] Ensure task settlement clears pending request associations.
|
|
100
|
+
|
|
101
|
+
### Separation from current prompts
|
|
102
|
+
|
|
103
|
+
- [x] Decide the exact compatibility mapping between prompt IDs and task IDs:
|
|
104
|
+
Phase 1 keeps prompt IDs and task IDs separate; compatibility mapping is
|
|
105
|
+
deferred until the delegation adapter is implemented.
|
|
106
|
+
- [x] Add an explicit prompt-to-task mapping if compatibility is retained.
|
|
107
|
+
- [x] Ensure ordinary messages do not create task records.
|
|
108
|
+
- [x] Ensure ordinary messages do not consume the active task slot.
|
|
109
|
+
- [x] Keep existing prompt tests passing during the transition.
|
|
110
|
+
|
|
111
|
+
### Tests
|
|
112
|
+
|
|
113
|
+
- [x] Add `test/verify-task-registry.mjs`.
|
|
114
|
+
- [x] Test opaque task ID validation.
|
|
115
|
+
- [x] Test valid state transitions.
|
|
116
|
+
- [x] Test invalid state transitions.
|
|
117
|
+
- [x] Test one active task per agent.
|
|
118
|
+
- [x] Test multiple ordinary messages while one task is active; messaging is
|
|
119
|
+
introduced in Phase 6.
|
|
120
|
+
- [x] Test idle process plus waiting task remains non-terminal.
|
|
121
|
+
- [x] Test idempotent completion.
|
|
122
|
+
- [x] Test idempotent cancellation.
|
|
123
|
+
- [x] Test idempotent timeout.
|
|
124
|
+
- [x] Test pending request association and clearing.
|
|
125
|
+
|
|
126
|
+
### Exit gate
|
|
127
|
+
|
|
128
|
+
- [x] Task state is independent of Pi/Herdr process state.
|
|
129
|
+
- [x] A task remains open when its owner is idle and waiting.
|
|
130
|
+
- [x] Registry tests pass.
|
|
131
|
+
- [x] Existing tests still pass.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Phase 2 — Parent-owned mailbox transport
|
|
136
|
+
|
|
137
|
+
### Mailbox layout
|
|
138
|
+
|
|
139
|
+
- [x] Choose and document the runtime root for session mailboxes.
|
|
140
|
+
- [x] Create one mailbox per parent Shepherd session.
|
|
141
|
+
- [x] Create the mailbox with owner-only permissions.
|
|
142
|
+
- [x] Create a parent inbox.
|
|
143
|
+
- [x] Create a per-agent inbox for each registered child.
|
|
144
|
+
- [x] Define outgoing, pending, acknowledged, and failed file locations:
|
|
145
|
+
writers publish directly to target inboxes; `processed`, `rejected`, and
|
|
146
|
+
`acks` retain transport state.
|
|
147
|
+
- [x] Define mailbox cleanup ownership and lifetime.
|
|
148
|
+
|
|
149
|
+
### Envelope format
|
|
150
|
+
|
|
151
|
+
- [x] Define the JSON-safe message envelope type.
|
|
152
|
+
- [x] Define envelope `kind` values.
|
|
153
|
+
- [x] Define task-done envelope fields.
|
|
154
|
+
- [x] Define runtime-observation envelope fields.
|
|
155
|
+
- [x] Define sender and target identity fields.
|
|
156
|
+
- [x] Define `messageId`, `threadId`, `replyTo`, and `taskId` fields.
|
|
157
|
+
- [x] Define delivery mode fields.
|
|
158
|
+
- [x] Define creation and deadline timestamps.
|
|
159
|
+
- [x] Define maximum envelope size.
|
|
160
|
+
- [x] Define maximum content length.
|
|
161
|
+
|
|
162
|
+
### Publication and consumption
|
|
163
|
+
|
|
164
|
+
- [x] Implement atomic temporary-file-plus-rename publication.
|
|
165
|
+
- [x] Implement complete-envelope reads.
|
|
166
|
+
- [x] Ignore incomplete or malformed files without crashing the monitor.
|
|
167
|
+
- [x] Implement parent inbox polling.
|
|
168
|
+
- [x] Implement child inbox polling.
|
|
169
|
+
- [x] Implement message acknowledgement.
|
|
170
|
+
- [x] Implement duplicate message detection.
|
|
171
|
+
- [x] Implement bounded queue depth.
|
|
172
|
+
- [x] Implement message retention or safe post-ack deletion.
|
|
173
|
+
- [x] Implement transport errors with message correlation.
|
|
174
|
+
- [x] Keep the transport timer-free; integration polling timers will be owned by
|
|
175
|
+
the parent/child extensions and must be unref-safe.
|
|
176
|
+
|
|
177
|
+
### Identity and authorization
|
|
178
|
+
|
|
179
|
+
- [x] Bind the mailbox to the parent session owner identity.
|
|
180
|
+
- [x] Generate child capabilities for publishing as a specific agent.
|
|
181
|
+
- [x] Validate the sender identity on every child envelope.
|
|
182
|
+
- [x] Validate that the target is registered in the same parent session.
|
|
183
|
+
- [x] Reject foreign session identities.
|
|
184
|
+
- [x] Reject attempts to publish as another agent.
|
|
185
|
+
- [x] Keep transport identities separate from raw Herdr pane IDs; public
|
|
186
|
+
adapters will resolve only registered opaque Shepherd agent IDs.
|
|
187
|
+
|
|
188
|
+
### Tests
|
|
189
|
+
|
|
190
|
+
- [x] Add `test/verify-messaging.mjs`.
|
|
191
|
+
- [x] Test mailbox creation and permissions where supported.
|
|
192
|
+
- [x] Test atomic publication.
|
|
193
|
+
- [x] Test partial-file handling.
|
|
194
|
+
- [x] Test parent-to-child publication.
|
|
195
|
+
- [x] Test child-to-parent publication.
|
|
196
|
+
- [x] Test duplicate envelope handling.
|
|
197
|
+
- [x] Test malformed envelope handling.
|
|
198
|
+
- [x] Test invalid sender handling.
|
|
199
|
+
- [x] Test invalid target handling.
|
|
200
|
+
- [x] Test queue depth limits.
|
|
201
|
+
- [x] Test message size limits.
|
|
202
|
+
- [x] Test mailbox cleanup after all children are gone.
|
|
203
|
+
|
|
204
|
+
### Exit gate
|
|
205
|
+
|
|
206
|
+
- [x] Parent and child can exchange JSON envelopes without Herdr.
|
|
207
|
+
- [x] Invalid and duplicate envelopes are safe.
|
|
208
|
+
- [x] Mailbox tests pass.
|
|
209
|
+
- [x] Transport APIs do not expose raw pane IDs.
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Phase 3 — Child-side Shepherd extension
|
|
214
|
+
|
|
215
|
+
### Extension structure
|
|
216
|
+
|
|
217
|
+
- [x] Document the decision to extend `shepherd-done.ts` instead of creating a
|
|
218
|
+
second child extension entrypoint.
|
|
219
|
+
- [x] Keep parent-only Shepherd tools out of child sessions.
|
|
220
|
+
- [x] Preserve the existing child system-prompt behavior.
|
|
221
|
+
- [x] Preserve the existing child process lifecycle behavior.
|
|
222
|
+
- [x] Make the child extension load from the Herdr launch path.
|
|
223
|
+
- [x] Pass broker location through the launch environment.
|
|
224
|
+
- [x] Pass parent session identity through the launch environment.
|
|
225
|
+
- [x] Pass child agent ID through the launch environment.
|
|
226
|
+
- [x] Pass active task ID through task context/environment.
|
|
227
|
+
|
|
228
|
+
### Child `shepherd_message`
|
|
229
|
+
|
|
230
|
+
- [x] Register the child-side `shepherd_message` tool.
|
|
231
|
+
- [x] Use a flat root object schema.
|
|
232
|
+
- [x] Declare `name`, `label`, `description`, `promptSnippet`, and
|
|
233
|
+
`parameters` directly in the registration.
|
|
234
|
+
- [x] Validate non-empty message content.
|
|
235
|
+
- [x] Validate target syntax.
|
|
236
|
+
- [x] Validate delivery mode.
|
|
237
|
+
- [x] Validate optional task and reply references.
|
|
238
|
+
- [x] Publish the message envelope to the parent broker.
|
|
239
|
+
- [x] Return acceptance without waiting for a response.
|
|
240
|
+
- [x] Return the generated message ID.
|
|
241
|
+
- [x] Return structured delivery acceptance details.
|
|
242
|
+
|
|
243
|
+
### Child `shepherd_done`
|
|
244
|
+
|
|
245
|
+
- [x] Register the child-side `shepherd_done` tool.
|
|
246
|
+
- [x] Use a flat root object schema.
|
|
247
|
+
- [x] Require a task ID.
|
|
248
|
+
- [x] Require a terminal status.
|
|
249
|
+
- [x] Accept an optional summary.
|
|
250
|
+
- [x] Validate that the task ID belongs to the child context.
|
|
251
|
+
- [x] Publish a `task_done` envelope.
|
|
252
|
+
- [x] Return acceptance without shutting down a persistent child.
|
|
253
|
+
- [x] Ensure repeated completion calls remain safe; parent task settlement is idempotent.
|
|
254
|
+
|
|
255
|
+
### Incoming delivery
|
|
256
|
+
|
|
257
|
+
- [x] Poll the child inbox.
|
|
258
|
+
- [x] Validate incoming envelope identity and target.
|
|
259
|
+
- [x] Render sender and message ID in the child context.
|
|
260
|
+
- [x] Preserve `taskId`, `threadId`, and `replyTo` metadata.
|
|
261
|
+
- [x] Deliver normal messages with `pi.sendUserMessage`.
|
|
262
|
+
- [x] Implement default `followUp` delivery.
|
|
263
|
+
- [x] Implement explicit `steer` delivery.
|
|
264
|
+
- [x] Delegate steering safety to Pi's supported `sendUserMessage` queue API.
|
|
265
|
+
- [x] Trigger an idle child when a follow-up reply is delivered.
|
|
266
|
+
- [x] Acknowledge successful child delivery through mailbox polling.
|
|
267
|
+
- [x] Record failed child delivery as a best-effort runtime diagnostic envelope.
|
|
268
|
+
|
|
269
|
+
### Child task instructions
|
|
270
|
+
|
|
271
|
+
- [x] Add task ID to delegated task context.
|
|
272
|
+
- [x] Tell the child that ending a Pi turn does not complete the task.
|
|
273
|
+
- [x] Tell the child to use `shepherd_message` for questions.
|
|
274
|
+
- [x] Tell the child to use `shepherd_done` only for actual task completion.
|
|
275
|
+
- [x] Tell the child how to reply to another agent's request.
|
|
276
|
+
- [x] Tell the child what to do when a task is blocked.
|
|
277
|
+
- [x] Ensure task instructions do not create duplicate system context.
|
|
278
|
+
|
|
279
|
+
### Tests
|
|
280
|
+
|
|
281
|
+
- [x] Add `test/verify-child-surface.mjs`.
|
|
282
|
+
- [x] Verify child tools are registered.
|
|
283
|
+
- [x] Verify parent-only tools are absent from child sessions.
|
|
284
|
+
- [x] Verify child messages return immediately.
|
|
285
|
+
- [x] Verify child done envelopes are published.
|
|
286
|
+
- [x] Verify incoming messages call the correct Pi queue API.
|
|
287
|
+
- [x] Verify follow-up and steer delivery modes.
|
|
288
|
+
- [x] Verify task context contains the task ID.
|
|
289
|
+
- [x] Update `test/verify-launch.mjs` for child extension wiring.
|
|
290
|
+
|
|
291
|
+
### Exit gate
|
|
292
|
+
|
|
293
|
+
- [x] A child can send an asynchronous message.
|
|
294
|
+
- [x] A child can explicitly complete a task.
|
|
295
|
+
- [x] A child can receive a queued message while idle.
|
|
296
|
+
- [x] Child and parent tool surfaces remain isolated.
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## Phase 4 — Tracked delegation
|
|
301
|
+
|
|
302
|
+
### Core delegation
|
|
303
|
+
|
|
304
|
+
- [x] Add `delegateAgent()` to `src/core/lifecycle.ts`.
|
|
305
|
+
- [x] Resolve the target through the opaque agent registry.
|
|
306
|
+
- [x] Enforce one active delegated task per agent.
|
|
307
|
+
- [x] Create the task record before publishing the task envelope.
|
|
308
|
+
- [x] Set the task to `running` after acceptance.
|
|
309
|
+
- [x] Reserve a task artifact when fieldnotes are enabled.
|
|
310
|
+
- [x] Attach the artifact to the task record.
|
|
311
|
+
- [x] Include task ID and task instructions in the child envelope.
|
|
312
|
+
- [x] Publish the task through the mailbox.
|
|
313
|
+
- [x] Return once the broker accepts the task.
|
|
314
|
+
- [x] Settle publication failures as task failures.
|
|
315
|
+
- [x] Finalize task artifacts on publication failure.
|
|
316
|
+
|
|
317
|
+
### Parent tool
|
|
318
|
+
|
|
319
|
+
- [x] Register `shepherd_delegate` in `src/extension/shepherd.ts`.
|
|
320
|
+
- [x] Add the flat tool schema.
|
|
321
|
+
- [x] Require target and task fields.
|
|
322
|
+
- [x] Add optional task timeout.
|
|
323
|
+
- [x] Return task ID and agent ID.
|
|
324
|
+
- [x] Use the standard Shepherd call/return/details result format.
|
|
325
|
+
- [x] Add concise tool description and prompt guidance.
|
|
326
|
+
- [x] Add call preview rendering.
|
|
327
|
+
- [x] Add tool schema coverage.
|
|
328
|
+
|
|
329
|
+
### Busy-agent behavior
|
|
330
|
+
|
|
331
|
+
- [x] Reject a second active delegated task clearly.
|
|
332
|
+
- [x] Ensure ordinary messages remain accepted while a task is active; ordinary
|
|
333
|
+
messages are introduced in Phase 6.
|
|
334
|
+
- [x] Define behavior when the target agent is not detected.
|
|
335
|
+
- [x] Define behavior when the target agent is closed.
|
|
336
|
+
- [x] Ensure task creation is rolled back if delivery cannot start.
|
|
337
|
+
|
|
338
|
+
### Tests
|
|
339
|
+
|
|
340
|
+
- [x] Add `test/verify-delegate.mjs`.
|
|
341
|
+
- [x] Test non-blocking delegation.
|
|
342
|
+
- [x] Test task ID creation.
|
|
343
|
+
- [x] Test one active task per agent.
|
|
344
|
+
- [x] Test task artifact association.
|
|
345
|
+
- [x] Test publication failure.
|
|
346
|
+
- [x] Test delegation to a closed agent.
|
|
347
|
+
- [x] Test ordinary messages during an active task; messaging is introduced in
|
|
348
|
+
Phase 6.
|
|
349
|
+
- [x] Update schema tests for `shepherd_delegate`.
|
|
350
|
+
|
|
351
|
+
### Exit gate
|
|
352
|
+
|
|
353
|
+
- [x] Delegation creates a tracked task.
|
|
354
|
+
- [x] Delegation does not require `shepherd_wait`.
|
|
355
|
+
- [x] The task remains open independently of the child turn.
|
|
356
|
+
- [x] Delegation tests pass.
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## Phase 5 — Explicit task completion and failures
|
|
361
|
+
|
|
362
|
+
### Parent task-done handling
|
|
363
|
+
|
|
364
|
+
- [x] Add parent handling for `task_done` envelopes.
|
|
365
|
+
- [x] Validate task ownership.
|
|
366
|
+
- [x] Validate task status.
|
|
367
|
+
- [x] Reject unknown task IDs.
|
|
368
|
+
- [x] Reject task completion from a foreign child.
|
|
369
|
+
- [x] Reject completion of a cancelled task by preserving the existing terminal result.
|
|
370
|
+
- [x] Reject successful completion with unresolved required requests, unless
|
|
371
|
+
they are explicitly cancelled or overridden by policy.
|
|
372
|
+
- [x] Record completion summary.
|
|
373
|
+
- [x] Record completion timestamp.
|
|
374
|
+
- [x] Settle the task exactly once.
|
|
375
|
+
- [x] Finalize the associated artifact exactly once.
|
|
376
|
+
|
|
377
|
+
### Runtime and process failures
|
|
378
|
+
|
|
379
|
+
- [x] Treat `agent_end` as a non-terminal runtime event.
|
|
380
|
+
- [x] Treat `agent_settled` as a non-terminal runtime event by keeping it out of
|
|
381
|
+
the task settlement path.
|
|
382
|
+
- [x] Treat Herdr idle state as a non-terminal runtime observation.
|
|
383
|
+
- [x] Preserve runtime observations for status output; deferred to Phase 9.
|
|
384
|
+
- [x] Map unexpected child exit to task failure.
|
|
385
|
+
- [x] Map provider errors to task failure.
|
|
386
|
+
- [x] Map close to task cancellation.
|
|
387
|
+
- [x] Map deadline expiry to task timeout.
|
|
388
|
+
- [x] Preserve useful child output in failure results; deferred to the
|
|
389
|
+
completion diagnostics follow-up tracked in
|
|
390
|
+
https://github.com/MikkelKappelPersson/shepherd/issues/11 (spec closed
|
|
391
|
+
with this item intentionally outstanding).
|
|
392
|
+
- [x] Ensure persistent children remain open after successful task completion.
|
|
393
|
+
|
|
394
|
+
### Completion extension changes
|
|
395
|
+
|
|
396
|
+
- [x] Refactor `shepherd-done.ts` so normal `agent_end` does not claim task
|
|
397
|
+
success.
|
|
398
|
+
- [x] Add task ID to any retained completion sidecar.
|
|
399
|
+
- [x] Distinguish process completion from task completion.
|
|
400
|
+
- [x] Emit explicit task completion only for `shepherd_done`.
|
|
401
|
+
- [x] Preserve provider-error reporting.
|
|
402
|
+
- [x] Preserve aborted-turn behavior.
|
|
403
|
+
- [x] Ensure queued follow-ups cannot cause premature task completion.
|
|
404
|
+
|
|
405
|
+
### Tests
|
|
406
|
+
|
|
407
|
+
- [x] Add `test/verify-task-completion.mjs`.
|
|
408
|
+
- [x] Test completion from the owning child.
|
|
409
|
+
- [x] Test completion from the wrong child.
|
|
410
|
+
- [x] Test duplicate completion.
|
|
411
|
+
- [x] Test completion with pending requests.
|
|
412
|
+
- [x] Test blocked task completion.
|
|
413
|
+
- [x] Test provider failure.
|
|
414
|
+
- [x] Test unexpected child exit.
|
|
415
|
+
- [x] Test close cancellation.
|
|
416
|
+
- [x] Test timeout.
|
|
417
|
+
- [x] Test no completion from `agent_end`.
|
|
418
|
+
- [x] Test no completion from `agent_settled`.
|
|
419
|
+
- [x] Test no completion from idle state.
|
|
420
|
+
|
|
421
|
+
### Exit gate
|
|
422
|
+
|
|
423
|
+
- [x] `shepherd_done` is the only normal successful completion path.
|
|
424
|
+
- [x] The canonical idle-while-waiting scenario does not complete early.
|
|
425
|
+
- [x] Failure and cancellation paths produce terminal task results.
|
|
426
|
+
- [x] Completion tests pass.
|
|
427
|
+
|
|
428
|
+
---
|
|
429
|
+
|
|
430
|
+
## Phase 6 — Asynchronous message routing
|
|
431
|
+
|
|
432
|
+
### Parent-side message tool
|
|
433
|
+
|
|
434
|
+
- [x] Register the parent-side `shepherd_message` tool.
|
|
435
|
+
- [x] Use a flat root object schema.
|
|
436
|
+
- [x] Require target and non-empty message.
|
|
437
|
+
- [x] Add optional task ID.
|
|
438
|
+
- [x] Add optional thread ID.
|
|
439
|
+
- [x] Add optional reply-to ID.
|
|
440
|
+
- [x] Add optional expects-reply flag.
|
|
441
|
+
- [x] Add optional delivery mode.
|
|
442
|
+
- [x] Return message ID and acceptance state.
|
|
443
|
+
- [x] Use standard Shepherd result formatting.
|
|
444
|
+
- [x] Add tool description and prompt guidance.
|
|
445
|
+
- [x] Add call preview rendering.
|
|
446
|
+
|
|
447
|
+
### Routing
|
|
448
|
+
|
|
449
|
+
- [x] Route parent-to-child messages through the mailbox.
|
|
450
|
+
- [x] Route child-to-parent messages into the parent session.
|
|
451
|
+
- [x] Route child-to-child messages through the parent broker.
|
|
452
|
+
- [x] Permit a child to target the Shepherd.
|
|
453
|
+
- [x] Permit a child to target validated peer agent IDs.
|
|
454
|
+
- [x] Reject targets outside the current parent session.
|
|
455
|
+
- [x] Preserve sender provenance.
|
|
456
|
+
- [x] Preserve message and task correlation metadata.
|
|
457
|
+
- [x] Ensure accepted means broker accepted, not recipient replied.
|
|
458
|
+
|
|
459
|
+
### Request/reply behavior
|
|
460
|
+
|
|
461
|
+
- [x] Create a pending request when `expectsReply` is true.
|
|
462
|
+
- [x] Associate the request with the sender task when a task ID is supplied.
|
|
463
|
+
- [x] Transition the task to `waiting` for a required reply.
|
|
464
|
+
- [x] Preserve the task's active ownership while waiting.
|
|
465
|
+
- [x] Accept replies with `replyTo`.
|
|
466
|
+
- [x] Clear the matching pending request on a valid reply.
|
|
467
|
+
- [x] Transition the task back to `running` after required reply delivery.
|
|
468
|
+
- [x] Reject duplicate replies or make them idempotent.
|
|
469
|
+
- [x] Add request deadlines.
|
|
470
|
+
- [x] Define request timeout behavior.
|
|
471
|
+
|
|
472
|
+
### Pi queue integration
|
|
473
|
+
|
|
474
|
+
- [x] Deliver child messages with `pi.sendUserMessage`.
|
|
475
|
+
- [x] Use `followUp` as the default.
|
|
476
|
+
- [x] Support explicit `steer`.
|
|
477
|
+
- [x] Ensure an idle child is triggered after reply delivery.
|
|
478
|
+
- [x] Ensure a busy child receives the message at the correct queue point.
|
|
479
|
+
- [x] Ensure message delivery does not create a second delegated task.
|
|
480
|
+
- [x] Queue parent notifications with custom Shepherd messages.
|
|
481
|
+
|
|
482
|
+
### Tests
|
|
483
|
+
|
|
484
|
+
- [x] Add `test/verify-message-routing.mjs`.
|
|
485
|
+
- [x] Test parent-to-child messages.
|
|
486
|
+
- [x] Test child-to-parent messages.
|
|
487
|
+
- [x] Test child-to-child messages.
|
|
488
|
+
- [x] Test messages to a busy recipient.
|
|
489
|
+
- [x] Test messages to an idle recipient.
|
|
490
|
+
- [x] Test `expectsReply` request creation.
|
|
491
|
+
- [x] Test valid replies.
|
|
492
|
+
- [x] Test invalid replies.
|
|
493
|
+
- [x] Test reply timeout.
|
|
494
|
+
- [x] Test no-reply messages leave task state unchanged.
|
|
495
|
+
- [x] Test message delivery failures.
|
|
496
|
+
- [x] Test message provenance.
|
|
497
|
+
|
|
498
|
+
### Exit gate
|
|
499
|
+
|
|
500
|
+
- [x] Worker can ask planner a question while planner is busy.
|
|
501
|
+
- [x] Planner receives the question as a queued follow-up.
|
|
502
|
+
- [x] Worker task remains waiting rather than completed.
|
|
503
|
+
- [x] Planner can reply to worker.
|
|
504
|
+
- [x] Worker receives the reply and returns to running.
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
## Phase 7 — Task-aware watchers
|
|
509
|
+
|
|
510
|
+
### Watcher core
|
|
511
|
+
|
|
512
|
+
- [x] Generalize or extend the watcher registry to accept task IDs.
|
|
513
|
+
- [x] Support one task ID.
|
|
514
|
+
- [x] Support an array of task IDs.
|
|
515
|
+
- [x] Return already-completed task results on registration.
|
|
516
|
+
- [x] Keep watcher registration non-blocking.
|
|
517
|
+
- [x] Preserve one-shot watcher behavior.
|
|
518
|
+
- [x] Make watcher delivery idempotent.
|
|
519
|
+
- [x] Preserve deterministic ordering for coalesced arrays.
|
|
520
|
+
- [x] Release watcher state after all tasks settle.
|
|
521
|
+
- [x] Release watcher timers at parent shutdown.
|
|
522
|
+
|
|
523
|
+
### Completion behavior
|
|
524
|
+
|
|
525
|
+
- [x] Watch only terminal task states.
|
|
526
|
+
- [x] Do not settle on child idle state.
|
|
527
|
+
- [x] Do not settle on `agent_end`.
|
|
528
|
+
- [x] Do not settle on `agent_settled`.
|
|
529
|
+
- [x] Do not settle when a task enters `waiting`.
|
|
530
|
+
- [x] Include task ID in every completion.
|
|
531
|
+
- [x] Include agent ID in every completion.
|
|
532
|
+
- [x] Include terminal status and return code.
|
|
533
|
+
- [x] Include summary text where available.
|
|
534
|
+
- [x] Include error data where available.
|
|
535
|
+
|
|
536
|
+
### Parent notification bridge
|
|
537
|
+
|
|
538
|
+
- [x] Deliver watcher results through a custom Shepherd parent message.
|
|
539
|
+
- [x] Use follow-up delivery for completion notifications.
|
|
540
|
+
- [x] Trigger a parent turn only according to watcher policy.
|
|
541
|
+
- [x] Suppress notifications after parent shutdown.
|
|
542
|
+
- [x] Preserve standard call/return/details formatting.
|
|
543
|
+
|
|
544
|
+
### Compatibility
|
|
545
|
+
|
|
546
|
+
- [x] Decide whether `shepherd_watch` accepts legacy prompt IDs.
|
|
547
|
+
- [x] If accepted, map prompt IDs explicitly to task IDs.
|
|
548
|
+
- [x] Reject agent IDs and pane IDs as watcher targets.
|
|
549
|
+
- [x] Document the chosen compatibility behavior.
|
|
550
|
+
- [x] Update the existing watcher tests or retain a compatibility test suite.
|
|
551
|
+
|
|
552
|
+
### Tests
|
|
553
|
+
|
|
554
|
+
- [x] Add `test/verify-task-watchers.mjs`.
|
|
555
|
+
- [x] Test a pending task.
|
|
556
|
+
- [x] Test an already-completed task.
|
|
557
|
+
- [x] Test multiple task IDs.
|
|
558
|
+
- [x] Test independent watchers.
|
|
559
|
+
- [x] Test completion ordering.
|
|
560
|
+
- [x] Test blocked completion.
|
|
561
|
+
- [x] Test failed completion.
|
|
562
|
+
- [x] Test cancelled completion.
|
|
563
|
+
- [x] Test timeout completion.
|
|
564
|
+
- [x] Test no completion from waiting state.
|
|
565
|
+
- [x] Test no duplicate completion notification.
|
|
566
|
+
- [x] Test parent shutdown.
|
|
567
|
+
|
|
568
|
+
### Exit gate
|
|
569
|
+
|
|
570
|
+
- [x] `shepherd_watch` tracks tasks rather than turns.
|
|
571
|
+
- [x] The canonical scout/planner scenario remains pending during the wait.
|
|
572
|
+
- [x] The watcher reports exactly one result after `shepherd_done`.
|
|
573
|
+
|
|
574
|
+
---
|
|
575
|
+
|
|
576
|
+
## Phase 8 — Stale-wait monitoring
|
|
577
|
+
|
|
578
|
+
### Configuration
|
|
579
|
+
|
|
580
|
+
- [x] Add a `staleWaitThreshold` setting.
|
|
581
|
+
- [x] Choose and document the default threshold.
|
|
582
|
+
- [x] Add validation and fallback behavior.
|
|
583
|
+
- [x] Add the setting to user-layer configuration.
|
|
584
|
+
- [x] Add project-delta support where appropriate.
|
|
585
|
+
- [x] Add the setting to the settings UI.
|
|
586
|
+
- [x] Add the setting to user-facing documentation.
|
|
587
|
+
|
|
588
|
+
### Monitor
|
|
589
|
+
|
|
590
|
+
- [x] Start the monitor only when waiting tasks exist.
|
|
591
|
+
- [x] Inspect task state rather than raw agent state.
|
|
592
|
+
- [x] Require an unresolved expected reply.
|
|
593
|
+
- [x] Track `waitingSince`.
|
|
594
|
+
- [x] Calculate elapsed wait time.
|
|
595
|
+
- [x] Emit one notification per waiting episode.
|
|
596
|
+
- [x] Record notification delivery time.
|
|
597
|
+
- [x] Reset stale-notification state after a reply.
|
|
598
|
+
- [x] Add request timeout handling.
|
|
599
|
+
- [x] Stop the monitor when no waiting tasks remain.
|
|
600
|
+
- [x] Ensure the timer does not keep the process alive.
|
|
601
|
+
|
|
602
|
+
### Notification content
|
|
603
|
+
|
|
604
|
+
- [x] Include task ID.
|
|
605
|
+
- [x] Include owning agent.
|
|
606
|
+
- [x] Include task description.
|
|
607
|
+
- [x] Include elapsed waiting time.
|
|
608
|
+
- [x] Include pending request ID.
|
|
609
|
+
- [x] Include question content.
|
|
610
|
+
- [x] Include recipient identity.
|
|
611
|
+
- [x] Include recipient process/task state.
|
|
612
|
+
- [x] Include possible Shepherd actions.
|
|
613
|
+
- [x] Preserve message/request correlation.
|
|
614
|
+
|
|
615
|
+
### Parent delivery
|
|
616
|
+
|
|
617
|
+
- [x] Deliver stale-wait notifications as custom Shepherd messages.
|
|
618
|
+
- [x] Queue notifications as follow-ups.
|
|
619
|
+
- [x] Decide when stale notifications trigger an idle parent turn.
|
|
620
|
+
- [x] Avoid waking the parent on every normal waiting transition.
|
|
621
|
+
- [x] Avoid repeated notification storms.
|
|
622
|
+
- [x] Add optional later escalation only if justified by usage.
|
|
623
|
+
|
|
624
|
+
### Tests
|
|
625
|
+
|
|
626
|
+
- [x] Add `test/verify-stale-wait.mjs`.
|
|
627
|
+
- [x] Test threshold crossing.
|
|
628
|
+
- [x] Test one notification per waiting episode.
|
|
629
|
+
- [x] Test notification content.
|
|
630
|
+
- [x] Test reset after reply.
|
|
631
|
+
- [x] Test completed task has no stale notification.
|
|
632
|
+
- [x] Test idle agent without a waiting task has no stale notification.
|
|
633
|
+
- [x] Test request timeout.
|
|
634
|
+
- [x] Test parent shutdown.
|
|
635
|
+
|
|
636
|
+
### Exit gate
|
|
637
|
+
|
|
638
|
+
- [x] A waiting scout produces one useful stale-wait notification.
|
|
639
|
+
- [x] A reply clears the stale condition.
|
|
640
|
+
- [x] Completed and ordinary idle agents do not generate stale notifications.
|
|
641
|
+
|
|
642
|
+
---
|
|
643
|
+
|
|
644
|
+
## Phase 9 — Status and TUI integration
|
|
645
|
+
|
|
646
|
+
### Status model
|
|
647
|
+
|
|
648
|
+
- [x] Extend `shepherd_status` with process state.
|
|
649
|
+
- [x] Extend `shepherd_status` with task state.
|
|
650
|
+
- [x] Include task ID when a task is active.
|
|
651
|
+
- [x] Include waiting age when applicable.
|
|
652
|
+
- [x] Include pending request ID when applicable.
|
|
653
|
+
- [x] Include waiting recipient when applicable.
|
|
654
|
+
- [x] Include stale flag when applicable.
|
|
655
|
+
- [x] Keep Herdr pane identity internal to diagnostics.
|
|
656
|
+
- [x] Preserve opaque agent IDs in public lifecycle results.
|
|
657
|
+
|
|
658
|
+
### Status widget
|
|
659
|
+
|
|
660
|
+
- [x] Include waiting tasks in the status projection.
|
|
661
|
+
- [x] Do not filter waiting tasks out because the process is idle.
|
|
662
|
+
- [x] Render waiting distinctly from working.
|
|
663
|
+
- [x] Render waiting recipient where available.
|
|
664
|
+
- [x] Render waiting elapsed time.
|
|
665
|
+
- [x] Render stale state distinctly.
|
|
666
|
+
- [x] Preserve current session ownership filtering.
|
|
667
|
+
- [x] Avoid mailbox reads during every render frame.
|
|
668
|
+
- [x] Reuse bounded polling/snapshot behavior.
|
|
669
|
+
|
|
670
|
+
### Tests
|
|
671
|
+
|
|
672
|
+
- [x] Update `test/verify-status-widget.mjs`.
|
|
673
|
+
- [x] Test idle process with waiting task.
|
|
674
|
+
- [x] Test working process with running task.
|
|
675
|
+
- [x] Test completed task removal.
|
|
676
|
+
- [x] Test stale waiting display.
|
|
677
|
+
- [x] Test session ownership filtering.
|
|
678
|
+
- [x] Test parent/child status separation.
|
|
679
|
+
|
|
680
|
+
### Exit gate
|
|
681
|
+
|
|
682
|
+
- [x] Status shows process state and task state independently.
|
|
683
|
+
- [x] An idle waiting scout remains visible.
|
|
684
|
+
- [x] Status/widget tests pass.
|
|
685
|
+
|
|
686
|
+
---
|
|
687
|
+
|
|
688
|
+
## Phase 10 — Artifacts, cleanup, compatibility, and documentation
|
|
689
|
+
|
|
690
|
+
### Artifacts
|
|
691
|
+
|
|
692
|
+
- [x] Allocate artifacts for delegated tasks only.
|
|
693
|
+
- [x] Do not allocate artifacts for ordinary messages.
|
|
694
|
+
- [x] Keep task artifacts open while waiting.
|
|
695
|
+
- [x] Finalize artifacts on task completion.
|
|
696
|
+
- [x] Finalize artifacts on blocked state.
|
|
697
|
+
- [x] Finalize artifacts on failure.
|
|
698
|
+
- [x] Finalize artifacts on cancellation.
|
|
699
|
+
- [x] Finalize artifacts on timeout.
|
|
700
|
+
- [x] Preserve final summaries and errors.
|
|
701
|
+
- [x] Avoid duplicate finalization from duplicate events.
|
|
702
|
+
- [x] Add useful request/message references without creating one note per chat.
|
|
703
|
+
|
|
704
|
+
### Cleanup and shutdown
|
|
705
|
+
|
|
706
|
+
- [x] Stop parent mailbox polling on parent shutdown.
|
|
707
|
+
- [x] Stop child mailbox polling on child shutdown.
|
|
708
|
+
- [x] Preserve already-persisted task outcomes.
|
|
709
|
+
- [x] Cancel or fail tasks whose child disappears.
|
|
710
|
+
- [x] Cancel unresolved requests when an agent closes.
|
|
711
|
+
- [x] Close the broker only after child panes are confirmed gone.
|
|
712
|
+
- [x] Preserve existing temporary launch-directory cleanup rules.
|
|
713
|
+
- [x] Verify no foreign pane can be closed.
|
|
714
|
+
- [x] Verify no foreign session can consume the mailbox.
|
|
715
|
+
|
|
716
|
+
### Compatibility
|
|
717
|
+
|
|
718
|
+
- [x] Decide whether `shepherd_prompt` remains as an alias.
|
|
719
|
+
- [x] Implement the chosen `shepherd_prompt` migration behavior.
|
|
720
|
+
- [x] Decide whether `shepherd_wait` remains as a compatibility adapter.
|
|
721
|
+
- [x] Implement the chosen `shepherd_wait` behavior.
|
|
722
|
+
- [x] Ensure old prompt completion semantics are not silently active.
|
|
723
|
+
- [x] Add compatibility tests for old calls where retained.
|
|
724
|
+
- [x] Add migration guidance to documentation.
|
|
725
|
+
- [x] Remove stale prompt-only assumptions from active descriptions.
|
|
726
|
+
|
|
727
|
+
### Documentation
|
|
728
|
+
|
|
729
|
+
- [x] Update `README.md` with the new task/message workflow.
|
|
730
|
+
- [x] Add a README example showing `shepherd_delegate` followed by
|
|
731
|
+
`shepherd_watch`.
|
|
732
|
+
- [x] Add a README example showing child-to-child `shepherd_message` usage.
|
|
733
|
+
- [x] Document that an idle child may still own a waiting task.
|
|
734
|
+
- [x] Document explicit `shepherd_done` completion.
|
|
735
|
+
- [x] Update `docs/guides/tool-reference.md`.
|
|
736
|
+
- [x] Update `docs/reference/dictionary`.
|
|
737
|
+
- [x] Update `docs/plans/architecture.md`.
|
|
738
|
+
- [x] Document task IDs versus message IDs.
|
|
739
|
+
- [x] Document `shepherd_delegate`.
|
|
740
|
+
- [x] Document `shepherd_message`.
|
|
741
|
+
- [x] Document `shepherd_done`.
|
|
742
|
+
- [x] Document `shepherd_watch`.
|
|
743
|
+
- [x] Document waiting tasks with idle child processes.
|
|
744
|
+
- [x] Document `followUp` versus `steer`.
|
|
745
|
+
- [x] Document stale-wait notifications.
|
|
746
|
+
- [x] Document compatibility status of `shepherd_prompt`.
|
|
747
|
+
- [x] Document compatibility status of `shepherd_wait`.
|
|
748
|
+
- [x] Document child messaging behavior and reply correlation.
|
|
749
|
+
|
|
750
|
+
### Exit gate
|
|
751
|
+
|
|
752
|
+
- [x] Artifacts follow task lifecycle correctly.
|
|
753
|
+
- [x] Shutdown and cleanup are safe.
|
|
754
|
+
- [x] Compatibility behavior is explicit.
|
|
755
|
+
- [x] Active documentation is updated.
|
|
756
|
+
|
|
757
|
+
---
|
|
758
|
+
|
|
759
|
+
## Phase 11 — Full verification and release readiness
|
|
760
|
+
|
|
761
|
+
### Automated verification
|
|
762
|
+
|
|
763
|
+
- [x] Run task registry tests.
|
|
764
|
+
- [x] Run mailbox tests.
|
|
765
|
+
- [x] Run child-surface tests.
|
|
766
|
+
- [x] Run delegation tests.
|
|
767
|
+
- [x] Run task-completion tests.
|
|
768
|
+
- [x] Run message-routing tests.
|
|
769
|
+
- [x] Run task-watcher tests.
|
|
770
|
+
- [x] Run stale-wait tests.
|
|
771
|
+
- [x] Run status-widget tests.
|
|
772
|
+
- [x] Run schema tests.
|
|
773
|
+
- [x] Run parent-surface tests.
|
|
774
|
+
- [x] Run launch tests.
|
|
775
|
+
- [x] Run artifact-session tests.
|
|
776
|
+
- [x] Run the complete `npm test` suite.
|
|
777
|
+
- [x] Resolve all regressions without weakening task completion invariants.
|
|
778
|
+
|
|
779
|
+
### Live Herdr matrix
|
|
780
|
+
|
|
781
|
+
- [x] Start or attach to a Herdr session.
|
|
782
|
+
- [x] Spawn persistent scout and planner agents.
|
|
783
|
+
- [x] Delegate a tracked task to scout.
|
|
784
|
+
- [x] Confirm delegation returns without blocking.
|
|
785
|
+
- [x] Have scout send a question to planner.
|
|
786
|
+
- [x] Keep planner busy while scout’s turn settles.
|
|
787
|
+
- [x] Confirm scout's Pi process becomes idle.
|
|
788
|
+
- [x] Confirm scout's task remains `waiting`.
|
|
789
|
+
- [x] Confirm no watcher completion is emitted.
|
|
790
|
+
- [x] Confirm the stale-wait notification appears after the threshold.
|
|
791
|
+
- [x] Have planner receive the queued question.
|
|
792
|
+
- [x] Have planner reply with the correct `replyTo` value.
|
|
793
|
+
- [x] Confirm scout receives the reply as a queued follow-up.
|
|
794
|
+
- [x] Confirm scout's task returns to `running`.
|
|
795
|
+
- [x] Have scout call `shepherd_done`.
|
|
796
|
+
- [x] Confirm exactly one watcher completion notification.
|
|
797
|
+
- [x] Confirm the completion contains the task summary.
|
|
798
|
+
- [x] Verify status output during `running`.
|
|
799
|
+
- [x] Verify status output during `waiting`.
|
|
800
|
+
- [x] Verify status output after completion.
|
|
801
|
+
- [x] Verify child-to-Shepherd messaging.
|
|
802
|
+
- [x] Verify Shepherd-to-child messaging.
|
|
803
|
+
- [x] Verify peer messaging through the parent broker.
|
|
804
|
+
- [x] Verify planner closure while scout waits.
|
|
805
|
+
- [x] Verify scout closure while planner has a queued question.
|
|
806
|
+
- [x] Verify task timeout.
|
|
807
|
+
- [x] Verify provider failure (model-not-found error observed; spawn readiness race recorded for follow-up).
|
|
808
|
+
- [x] Verify parent shutdown.
|
|
809
|
+
- [x] Verify pane ownership protection.
|
|
810
|
+
- [x] Verify temporary-resource cleanup.
|
|
811
|
+
|
|
812
|
+
### Final review
|
|
813
|
+
|
|
814
|
+
- [x] Review all public tool schemas for flat object roots.
|
|
815
|
+
- [x] Review all public results for standard call/return/details formatting.
|
|
816
|
+
- [x] Review all child/parent identity checks.
|
|
817
|
+
- [x] Review all task terminal transitions.
|
|
818
|
+
- [x] Review all waiting-task transitions.
|
|
819
|
+
- [x] Review stale-wait notification rate limiting.
|
|
820
|
+
- [x] Review message queue limits and failure behavior.
|
|
821
|
+
- [x] Review fieldnote finalization behavior.
|
|
822
|
+
- [x] Review documentation against implemented behavior.
|
|
823
|
+
- [x] Mark the specification status as implemented only after all gates pass.
|
|
824
|
+
|
|
825
|
+
## Definition of done
|
|
826
|
+
|
|
827
|
+
- [x] A delegated task can span multiple Pi turns.
|
|
828
|
+
- [x] A child can ask another participant a question and end its current turn.
|
|
829
|
+
- [x] An idle child with an outstanding request remains a waiting task, not a
|
|
830
|
+
completed task.
|
|
831
|
+
- [x] A queued reply can resume the child later.
|
|
832
|
+
- [x] Only explicit `shepherd_done` normally completes the task.
|
|
833
|
+
- [x] `shepherd_watch` reports terminal task completion without requiring
|
|
834
|
+
`shepherd_wait`.
|
|
835
|
+
- [x] Long waits notify the Shepherd without producing notification storms.
|
|
836
|
+
- [x] Parent and child messaging works through the owned broker.
|
|
837
|
+
- [x] Existing pane ownership and fieldnote safety invariants remain intact.
|
|
838
|
+
- [x] All focused tests, live Herdr checks, and `npm test` pass.
|