@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,212 @@
|
|
|
1
|
+
# Tasks: Low-Level Agent Orchestration
|
|
2
|
+
|
|
3
|
+
Work through these tasks in order unless a task is explicitly marked as
|
|
4
|
+
independent. Cross off a task only after its implementation and verification
|
|
5
|
+
are complete.
|
|
6
|
+
|
|
7
|
+
## Phase 1 — Foundations
|
|
8
|
+
|
|
9
|
+
- [x] **1.1 Define public lifecycle types**
|
|
10
|
+
- Add serializable `AgentHandle`, `PromptHandle`, `Status`, and `Result`
|
|
11
|
+
shapes.
|
|
12
|
+
- Define supported lifecycle states and structured error fields.
|
|
13
|
+
- Keep public handles opaque; do not require callers to pass raw pane IDs.
|
|
14
|
+
|
|
15
|
+
- [x] **1.2 Add agent and prompt registries**
|
|
16
|
+
- Track live agents by stable handle ID.
|
|
17
|
+
- Track prompts by stable prompt ID.
|
|
18
|
+
- Associate each prompt with its owning agent.
|
|
19
|
+
- Track one unresolved prompt per agent.
|
|
20
|
+
- Add lookup, invalidation, settlement, and cleanup helpers.
|
|
21
|
+
|
|
22
|
+
- [x] **1.3 Preserve ownership and safety invariants**
|
|
23
|
+
- Reuse the created-pane registry for ownership checks.
|
|
24
|
+
- Reject foreign, unknown, and closed handles clearly.
|
|
25
|
+
- Ensure raw pane IDs cannot bypass close ownership checks.
|
|
26
|
+
- Define behavior for stale registries and extension reloads.
|
|
27
|
+
|
|
28
|
+
## Phase 2 — Persistent `start`
|
|
29
|
+
|
|
30
|
+
- [x] **2.1 Separate launch from task submission**
|
|
31
|
+
- Refactor Herdr launch helpers so starting pi does not require a task.
|
|
32
|
+
- Preserve agent system prompt, tools, model, cwd, and prompt-mode behavior.
|
|
33
|
+
- Remove `stayOpen` from the new low-level start path.
|
|
34
|
+
- Ensure the launched agent remains alive until explicitly closed.
|
|
35
|
+
|
|
36
|
+
- [x] **2.2 Add placement options**
|
|
37
|
+
- Support requested tab or sibling-pane placement.
|
|
38
|
+
- Preserve caller cwd unless overridden.
|
|
39
|
+
- Use `--no-focus` by default for background agents.
|
|
40
|
+
- Parse all Herdr IDs from command results rather than predicting them.
|
|
41
|
+
|
|
42
|
+
- [x] **2.3 Implement `start(agent, options)`
|
|
43
|
+
- Discover the agent fresh from disk.
|
|
44
|
+
- Apply user/project scope and trust confirmation.
|
|
45
|
+
- Ensure Herdr is available.
|
|
46
|
+
- Create and record the pane/tab.
|
|
47
|
+
- Launch pi with no initial user message.
|
|
48
|
+
- Wait for shell readiness and Herdr agent detection.
|
|
49
|
+
- Register and return an `AgentHandle`.
|
|
50
|
+
- Clean up safely if startup fails after pane creation.
|
|
51
|
+
|
|
52
|
+
- [x] **2.4 Verify `start`**
|
|
53
|
+
- Confirmed `startAgent("scout", ...)` returned a stable serialized handle.
|
|
54
|
+
- Confirmed the agent was detected and reported `idle` through `statusAgent`.
|
|
55
|
+
- Confirmed the persistent agent remained addressable after `start` returned.
|
|
56
|
+
- Confirmed the created Herdr tab/pane was closed through the ownership-safe path.
|
|
57
|
+
- The live check used the current workspace and explicit cwd; placement is currently tab-based.
|
|
58
|
+
- Project-agent trust gating remains implemented in `startAgent`.
|
|
59
|
+
|
|
60
|
+
## Phase 3 — Non-blocking `prompt`
|
|
61
|
+
|
|
62
|
+
- [x] **3.1 Add non-blocking prompt submission**
|
|
63
|
+
- Resolve and validate the `AgentHandle`.
|
|
64
|
+
- Reject agents with an unresolved prompt.
|
|
65
|
+
- Confirm Herdr detects the agent before sending.
|
|
66
|
+
- Submit exactly one message without waiting for completion.
|
|
67
|
+
- Detect failed submission and settle it without returning a usable handle.
|
|
68
|
+
- Register and immediately return a `PromptHandle`.
|
|
69
|
+
|
|
70
|
+
- [x] **3.2 Track prompt lifecycle**
|
|
71
|
+
- Store submission time and timeout.
|
|
72
|
+
- Associate prompt state with its agent.
|
|
73
|
+
- Ensure submission errors do not leave phantom active prompts.
|
|
74
|
+
- Ensure an agent becomes promptable again after settlement.
|
|
75
|
+
|
|
76
|
+
- [x] **3.3 Verify `prompt`**
|
|
77
|
+
- Confirmed `promptAgent` returned a prompt handle without waiting for completion.
|
|
78
|
+
- Confirmed a second prompt on the same agent was rejected while active.
|
|
79
|
+
- Confirmed waiting settled the prompt and a subsequent prompt was accepted.
|
|
80
|
+
- Confirmed prompt/result IDs remained associated across both prompts.
|
|
81
|
+
- Submission failure handling is implemented; a dedicated forced-failure check remains useful.
|
|
82
|
+
|
|
83
|
+
## Phase 4 — `wait`
|
|
84
|
+
|
|
85
|
+
- [x] **4.1 Implement single-prompt wait**
|
|
86
|
+
- Waits for a post-submission Herdr transition rather than accepting pre-submit idle.
|
|
87
|
+
- Handles idle, done, blocked, timeout, and cancellation results.
|
|
88
|
+
- Recovers diagnostic response text from the pane after settlement.
|
|
89
|
+
- Does not read or delete the live child session file.
|
|
90
|
+
- Returns a structured `Result` tied to prompt and agent IDs.
|
|
91
|
+
- Clears the agent's active prompt exactly once.
|
|
92
|
+
|
|
93
|
+
- [x] **4.2 Implement multi-prompt wait**
|
|
94
|
+
- Accepts one prompt handle or an array of handles.
|
|
95
|
+
- Waits concurrently for arrays using `Promise.all`.
|
|
96
|
+
- Preserves input ordering in the result array.
|
|
97
|
+
- Returns one structured result per input, including failures.
|
|
98
|
+
- Converts individual wait errors into failed results so successful results remain visible.
|
|
99
|
+
- Supports wait-for-all only.
|
|
100
|
+
|
|
101
|
+
- [x] **4.3 Verify `wait`**
|
|
102
|
+
- Verified prompt results preserve their corresponding prompt IDs.
|
|
103
|
+
- Verified two prompts were waited concurrently.
|
|
104
|
+
- Verified multi-wait preserves input order.
|
|
105
|
+
- Verified an unknown prompt produced a failed result alongside a successful result.
|
|
106
|
+
- Verified settled prompts can be reused for subsequent lifecycle checks.
|
|
107
|
+
|
|
108
|
+
## Phase 5 — `status` and `close`
|
|
109
|
+
|
|
110
|
+
- [x] **5.1 Implement handle-based `status`**
|
|
111
|
+
- Resolves an `AgentHandle`.
|
|
112
|
+
- Queries Herdr without focusing or mutating the pane.
|
|
113
|
+
- Returns stable identity and placement metadata.
|
|
114
|
+
- Maps missing panes to `failed` and closed handles to `closed`.
|
|
115
|
+
- Handles stale and closed handles with clear errors/results.
|
|
116
|
+
|
|
117
|
+
- [x] **5.2 Implement handle-based `close`**
|
|
118
|
+
- Resolves only valid lifecycle handles.
|
|
119
|
+
- Refuses panes absent from the pi-shepherd ownership registry.
|
|
120
|
+
- Cancels unresolved prompts deterministically.
|
|
121
|
+
- Closes the pane through the existing safe path.
|
|
122
|
+
- Cleans temporary resources only after pane disappearance.
|
|
123
|
+
- Repeated close calls are idempotent.
|
|
124
|
+
|
|
125
|
+
- [x] **5.3 Verify lifecycle termination**
|
|
126
|
+
- Verified `wait` leaves the agent alive after normal settlement.
|
|
127
|
+
- Verified `close` terminated the created Herdr pane.
|
|
128
|
+
- Verified waiting after close returned `cancelled`.
|
|
129
|
+
- Verified status after close returned `closed`.
|
|
130
|
+
- Verified an unowned/foreign handle is rejected without closing its pane.
|
|
131
|
+
|
|
132
|
+
## Phase 6 — Shepherd tool integration
|
|
133
|
+
|
|
134
|
+
- [x] **6.1 Add tool schemas**
|
|
135
|
+
- Add `action: "start"` with agent and launch/placement options.
|
|
136
|
+
- Add `action: "prompt"` with agent handle and message.
|
|
137
|
+
- Add `action: "wait"` with one or many prompt handles.
|
|
138
|
+
- Update `status` and `close` to accept agent handles.
|
|
139
|
+
- Keep `sheep`, `herd`, `read`, and `prune`.
|
|
140
|
+
|
|
141
|
+
- [x] **6.2 Update tool execution**
|
|
142
|
+
- Route actions to the lifecycle primitives.
|
|
143
|
+
- Return structured handles, statuses, and results.
|
|
144
|
+
- Preserve useful human-readable text output.
|
|
145
|
+
- Return partial multi-wait results on failure.
|
|
146
|
+
- Maintain clear invalid-handle errors.
|
|
147
|
+
|
|
148
|
+
- [x] **6.3 Update model-facing guidance**
|
|
149
|
+
- Explain start-without-task semantics.
|
|
150
|
+
- Explain prompt-then-wait semantics.
|
|
151
|
+
- Show parallel work using `wait([promptA, promptB])`.
|
|
152
|
+
- Show chains as explicit caller composition.
|
|
153
|
+
- Explain that `close` is explicit.
|
|
154
|
+
|
|
155
|
+
## Phase 7 — Compatibility migration
|
|
156
|
+
|
|
157
|
+
- [x] **7.1 Remove legacy delegation**
|
|
158
|
+
- Deleted the legacy `delegate` action and workflow modes.
|
|
159
|
+
- Removed `subagent.ts` and the one-shot delegation runner.
|
|
160
|
+
- Low-level lifecycle primitives are now the only orchestration API.
|
|
161
|
+
|
|
162
|
+
- [x] **7.2 Resolve lifecycle cleanup policy**
|
|
163
|
+
- Legacy compatibility cleanup is no longer applicable because delegation was removed.
|
|
164
|
+
- `start` never closes automatically; callers explicitly call `close`.
|
|
165
|
+
- One-shot behavior is explicitly composed as `start + prompt + wait + close`.
|
|
166
|
+
- `stayOpen` is not exposed on the low-level `start` schema.
|
|
167
|
+
|
|
168
|
+
- [x] **7.3 Update slash commands**
|
|
169
|
+
- Keep existing slash-command compatibility where useful.
|
|
170
|
+
- Ensure its implementation does not depend on task-bearing `start`.
|
|
171
|
+
- Update output to show returned handles where relevant.
|
|
172
|
+
|
|
173
|
+
## Phase 8 — Documentation and tests
|
|
174
|
+
|
|
175
|
+
- [x] **8.1 Update README**
|
|
176
|
+
- Documents the low-level primitive API.
|
|
177
|
+
- Replaces workflow examples with explicit composition examples.
|
|
178
|
+
- Documents persistent start and explicit close.
|
|
179
|
+
- Documents that legacy delegation modes were removed.
|
|
180
|
+
|
|
181
|
+
- [x] **8.2 Update root `PLAN.md`**
|
|
182
|
+
- Replaced the workflow-centric architecture description.
|
|
183
|
+
- Recorded lifecycle primitive implementation status.
|
|
184
|
+
- Kept runtime, Herdr, and security invariants accurate.
|
|
185
|
+
|
|
186
|
+
- [x] **8.3 Add registry tests**
|
|
187
|
+
- Added `test/verify-registry.mjs` covering serialization, lookup, unknown handles,
|
|
188
|
+
active-prompt enforcement, idempotent settlement, and cancellation.
|
|
189
|
+
|
|
190
|
+
- [x] **8.4 Add multi-wait tests**
|
|
191
|
+
- Added `test/verify-multi-wait.mjs` covering concurrent waiting and input order.
|
|
192
|
+
- Live verification covered partial failure results and cancellation handling.
|
|
193
|
+
|
|
194
|
+
- [x] **8.5 Run live Herdr verification**
|
|
195
|
+
- Started idle `scout` agents in live Herdr tabs.
|
|
196
|
+
- Confirmed non-blocking prompt return and exact response recovery.
|
|
197
|
+
- Waited for a single result and verified prompt/result association.
|
|
198
|
+
- Started two agents, prompted both, and waited concurrently with ordered results.
|
|
199
|
+
- Exercised iterative prompting on one persistent agent.
|
|
200
|
+
- Closed agents and verified cancellation, closed status, and cleanup.
|
|
201
|
+
- Verified background starts preserved the focused caller pane.
|
|
202
|
+
- Verified ownership protection refused a foreign pane handle.
|
|
203
|
+
|
|
204
|
+
## Completion checklist
|
|
205
|
+
|
|
206
|
+
- [x] All Phase 1–5 lifecycle primitives work independently of workflow modes.
|
|
207
|
+
- [x] All Phase 6 tool actions are available and documented.
|
|
208
|
+
- [x] Legacy workflows were removed rather than retained as wrappers.
|
|
209
|
+
- [x] Existing discovery, trust, Herdr, and temp-file safety behavior remains
|
|
210
|
+
intact.
|
|
211
|
+
- [x] README and root `PLAN.md` are synchronized with the implementation.
|
|
212
|
+
- [x] Tests and live Herdr verification pass.
|
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
# Implementation Plan: Shepherd-bound Note Sessions
|
|
2
|
+
|
|
3
|
+
This plan implements `spec.md` by restoring the durable note layer as a
|
|
4
|
+
parent-pi-session concern while preserving the low-level lifecycle API from
|
|
5
|
+
`specs/002-simplify-agent-orchestration/`.
|
|
6
|
+
|
|
7
|
+
The central invariant is:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
same parent pi session + same project root
|
|
11
|
+
=> one persistent note session directory
|
|
12
|
+
=> one note per submitted child invocation
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
A child pane, child JSONL file, agent handle, prompt handle, or
|
|
16
|
+
`LifecycleRegistry.sessionId` must never allocate a new persistent note
|
|
17
|
+
session.
|
|
18
|
+
|
|
19
|
+
## Target architecture
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
pi parent context
|
|
23
|
+
ctx.sessionManager.getSessionId()
|
|
24
|
+
ctx.cwd
|
|
25
|
+
│
|
|
26
|
+
▼
|
|
27
|
+
parent-session binding
|
|
28
|
+
{ parentPiSessionId, projectRoot, noteSession }
|
|
29
|
+
│
|
|
30
|
+
├── startAgent(...)
|
|
31
|
+
│ └── starts idle child; reuses binding; no note yet
|
|
32
|
+
│
|
|
33
|
+
└── promptAgent(...)
|
|
34
|
+
├── reserve note in binding.sessionPath
|
|
35
|
+
├── append note context to child message
|
|
36
|
+
├── submit message
|
|
37
|
+
└── finalize note from wait result
|
|
38
|
+
|
|
39
|
+
artifact-sessions.ts
|
|
40
|
+
filesystem allocation, lookup, locking, fieldnotes, metadata, notes
|
|
41
|
+
|
|
42
|
+
orchestration.ts
|
|
43
|
+
in-memory handles/prompts plus internal note association
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Design decisions
|
|
47
|
+
|
|
48
|
+
1. **Parent identity source** — use the pi-provided
|
|
49
|
+
`ctx.sessionManager.getSessionId()` as the opaque parent identity. Use
|
|
50
|
+
`getSessionFile()` as diagnostic/resume metadata, not as the child note
|
|
51
|
+
file. Do not derive identity from a task, agent name, pane ID, or lifecycle
|
|
52
|
+
UUID.
|
|
53
|
+
2. **Binding root** — use the parent tool context's effective `ctx.cwd` as the
|
|
54
|
+
note project root. A child `start` `cwd` override affects child launch
|
|
55
|
+
only; it does not move the shared note session to another project.
|
|
56
|
+
3. **Lazy shared allocation** — the first `start` resolves and creates the
|
|
57
|
+
parent-bound note session so its result can expose the shared path.
|
|
58
|
+
`start` itself reserves no per-agent note. Later starts in the same
|
|
59
|
+
parent/project binding reuse the existing directory.
|
|
60
|
+
4. **Per-invocation reservation** — `prompt` reserves one note immediately
|
|
61
|
+
before message submission. This represents actual work and gives each
|
|
62
|
+
prompt a stable note path. Parallel prompt calls reserve under the
|
|
63
|
+
session lock.
|
|
64
|
+
5. **Internal association** — attach the resolved note session to each
|
|
65
|
+
registered agent record and the reserved note to each prompt record.
|
|
66
|
+
Public handles remain lifecycle handles; note paths are returned in tool
|
|
67
|
+
details and are not caller-supplied handle identity.
|
|
68
|
+
6. **No implicit legacy continuation** — old sessions lacking parent binding
|
|
69
|
+
metadata are not selected by slug/name alone. Any migration must be
|
|
70
|
+
explicit and separate from normal allocation.
|
|
71
|
+
7. **Durability boundary** — note writes are finalized after the existing
|
|
72
|
+
completion signal/state boundary. Closing a child never removes the shared
|
|
73
|
+
note session.
|
|
74
|
+
|
|
75
|
+
## Phase 1 — Establish the parent-session contract
|
|
76
|
+
|
|
77
|
+
### 1.1 Add parent context types
|
|
78
|
+
|
|
79
|
+
Add an internal type, for example `ParentNoteContext`, containing:
|
|
80
|
+
|
|
81
|
+
- opaque `parentPiSessionId`;
|
|
82
|
+
- optional `parentSessionFile` for diagnostics;
|
|
83
|
+
- canonical `projectRoot`;
|
|
84
|
+
- resolved persistent note-session metadata/path.
|
|
85
|
+
|
|
86
|
+
Add an `NoteSessionRef` and `NoteRef` type for the data needed by
|
|
87
|
+
lifecycle records and tool result details. Keep filesystem implementation
|
|
88
|
+
objects out of public TypeBox schemas where possible.
|
|
89
|
+
|
|
90
|
+
### 1.2 Resolve identity from pi
|
|
91
|
+
|
|
92
|
+
Add a helper at the Shepherd tool boundary that receives the real extension
|
|
93
|
+
context and obtains:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const parentPiSessionId = ctx.sessionManager.getSessionId();
|
|
97
|
+
const parentSessionFile = ctx.sessionManager.getSessionFile();
|
|
98
|
+
const projectRoot = path.resolve(ctx.cwd);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Validate that the identity is non-empty and that the project root is usable.
|
|
102
|
+
Do not use `lifecycleRegistry.sessionId` for this purpose.
|
|
103
|
+
|
|
104
|
+
Confirm the session manager behavior for a resumed session: the same pi
|
|
105
|
+
session must return an identity that finds the existing note directory.
|
|
106
|
+
Document the fallback policy if a non-persisted/in-memory pi context has no
|
|
107
|
+
session file.
|
|
108
|
+
|
|
109
|
+
### 1.3 Add parent-binding cache
|
|
110
|
+
|
|
111
|
+
Create a small parent binding registry, either in a new `parent-session.ts` or
|
|
112
|
+
inside the note session module. It should:
|
|
113
|
+
|
|
114
|
+
- key entries by `(parentPiSessionId, projectRoot)`;
|
|
115
|
+
- return the same binding for repeated tool calls;
|
|
116
|
+
- be safe if the extension receives an equivalent context object each call;
|
|
117
|
+
- never key by child handle, agent, or prompt;
|
|
118
|
+
- allow reloading the binding from disk after an extension restart.
|
|
119
|
+
|
|
120
|
+
The cache is an optimization, not the source of truth. `session.json` remains
|
|
121
|
+
the durable authority.
|
|
122
|
+
|
|
123
|
+
## Phase 2 — Restore the filesystem note module
|
|
124
|
+
|
|
125
|
+
### 2.1 Reintroduce the historical persistence code
|
|
126
|
+
|
|
127
|
+
Create `artifact-sessions.ts` (or restore `sessions.ts` with the new contract)
|
|
128
|
+
by extracting the useful filesystem behavior from the deleted historical
|
|
129
|
+
`sessions.ts`:
|
|
130
|
+
|
|
131
|
+
- safe session and agent slugging;
|
|
132
|
+
- numbered session allocation;
|
|
133
|
+
- exact metadata lookup;
|
|
134
|
+
- `.alloc`/exclusive allocation locking;
|
|
135
|
+
- note reservation and per-agent ordinals;
|
|
136
|
+
- atomic same-directory writes;
|
|
137
|
+
- serialized session updates;
|
|
138
|
+
- fieldnotes rendering;
|
|
139
|
+
- note status transitions and finalization.
|
|
140
|
+
|
|
141
|
+
Keep this module independent of pi, Herdr, and TUI imports so it can be tested
|
|
142
|
+
with temporary directories.
|
|
143
|
+
|
|
144
|
+
### 2.2 Implement parent-bound lookup/allocation
|
|
145
|
+
|
|
146
|
+
Implement an API similar to:
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
resolveOrCreateParentNoteSession({
|
|
150
|
+
projectRoot,
|
|
151
|
+
parentPiSessionId,
|
|
152
|
+
parentSessionFile,
|
|
153
|
+
}): NoteSession
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Under the project `.shepherd/sessions/` directory:
|
|
157
|
+
|
|
158
|
+
1. acquire the root allocation lock;
|
|
159
|
+
2. scan only validated numbered session directories;
|
|
160
|
+
3. parse and validate `session.json`;
|
|
161
|
+
4. find an exact binding match for both parent identity and project root;
|
|
162
|
+
5. return that directory if found;
|
|
163
|
+
6. otherwise allocate a unique ordinal and create one new directory;
|
|
164
|
+
7. write versioned `session.json` and `shepherd.md` atomically; and
|
|
165
|
+
8. release the lock.
|
|
166
|
+
|
|
167
|
+
The persisted metadata must include a note-session version and parent
|
|
168
|
+
binding fields. Do not trust persisted absolute paths; derive paths from the
|
|
169
|
+
current validated project/session root.
|
|
170
|
+
|
|
171
|
+
If metadata is malformed or an old session lacks the binding, skip it for
|
|
172
|
+
normal lookup and leave it untouched. Do not silently attach it to the current
|
|
173
|
+
parent.
|
|
174
|
+
|
|
175
|
+
### 2.3 Preserve collision and path safety
|
|
176
|
+
|
|
177
|
+
Retain and test the existing behavior for:
|
|
178
|
+
|
|
179
|
+
- traversal/control-character rejection;
|
|
180
|
+
- safe lowercase slugs;
|
|
181
|
+
- same-slug/different-identity suffixes;
|
|
182
|
+
- unique ordinals under concurrent allocation;
|
|
183
|
+
- note filename collisions;
|
|
184
|
+
- descendant checks for all generated paths.
|
|
185
|
+
|
|
186
|
+
No global `.shepherd/shepherd.md` file is introduced.
|
|
187
|
+
|
|
188
|
+
### 2.4 Add note lifecycle operations
|
|
189
|
+
|
|
190
|
+
Expose operations for:
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
reserveNotes(session, planned)
|
|
194
|
+
markNoteStarted(session, note, metadata)
|
|
195
|
+
markNoteStatus(session, note, status, metadata)
|
|
196
|
+
finalizeNote(session, note, result)
|
|
197
|
+
updateSessionMoc(session, update)
|
|
198
|
+
readSessionMetadata(sessionPath)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Every mutating operation must lock the session, reload current metadata,
|
|
202
|
+
update it, and atomically rewrite `session.json`, note content, and fieldnotes as
|
|
203
|
+
needed. Preserve agent-authored note content while appending orchestration
|
|
204
|
+
metadata/output.
|
|
205
|
+
|
|
206
|
+
## Phase 3 — Integrate binding with lifecycle state
|
|
207
|
+
|
|
208
|
+
### 3.1 Extend internal records
|
|
209
|
+
|
|
210
|
+
Update `orchestration.ts` so `AgentRecord` can reference the parent note
|
|
211
|
+
session and `PromptRecord` can reference its reserved note. These fields
|
|
212
|
+
are internal and must not change handle validation semantics.
|
|
213
|
+
|
|
214
|
+
The record association must survive all operations in one parent extension
|
|
215
|
+
process:
|
|
216
|
+
|
|
217
|
+
```text
|
|
218
|
+
AgentRecord -> NoteSessionRef
|
|
219
|
+
PromptRecord -> NoteRef + NoteSessionRef
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Do not replace or repurpose `LifecycleRegistry.sessionId`.
|
|
223
|
+
|
|
224
|
+
### 3.2 Resolve the binding on `start`
|
|
225
|
+
|
|
226
|
+
Update the model-facing `doAction` path in `shepherd.ts` and the lifecycle
|
|
227
|
+
boundary so `start`:
|
|
228
|
+
|
|
229
|
+
1. resolves the parent binding from the current `ctx`;
|
|
230
|
+
2. creates/reuses the single note session;
|
|
231
|
+
3. starts the idle Herdr child exactly as today;
|
|
232
|
+
4. registers the agent with the note-session reference; and
|
|
233
|
+
5. returns the handle plus shared session details.
|
|
234
|
+
|
|
235
|
+
A failed child launch may leave the already-created shared session directory,
|
|
236
|
+
but must not create a second session during cleanup and must not create an
|
|
237
|
+
agent note for an idle start.
|
|
238
|
+
|
|
239
|
+
### 3.3 Reserve and inject context on `prompt`
|
|
240
|
+
|
|
241
|
+
Before submitting a prompt:
|
|
242
|
+
|
|
243
|
+
1. resolve the canonical agent handle;
|
|
244
|
+
2. obtain its parent note-session reference;
|
|
245
|
+
3. reserve one note under the session lock;
|
|
246
|
+
4. mark it running or pending according to the chosen lifecycle boundary;
|
|
247
|
+
5. append the note context block to the original message;
|
|
248
|
+
6. create the prompt record with the note reference; and
|
|
249
|
+
7. submit the augmented message without waiting.
|
|
250
|
+
|
|
251
|
+
The original task must remain intact. The context block must include absolute
|
|
252
|
+
and project-relative session/fieldnotes/note paths and the read/write ownership
|
|
253
|
+
instructions from the spec.
|
|
254
|
+
|
|
255
|
+
If submission fails, finalize the reserved note as `failed` or `cancelled`
|
|
256
|
+
and return no usable prompt handle. Do not allocate a replacement session or
|
|
257
|
+
note.
|
|
258
|
+
|
|
259
|
+
### 3.4 Finalize from `wait`
|
|
260
|
+
|
|
261
|
+
Update `waitOne` so every terminal path finalizes the prompt's note:
|
|
262
|
+
|
|
263
|
+
- completed/idle/done: preserve final text;
|
|
264
|
+
- blocked: preserve blocked state and available output;
|
|
265
|
+
- timeout: record timeout details without reading a still-live child file;
|
|
266
|
+
- cancellation/close: record cancellation;
|
|
267
|
+
- failure: record error and diagnostic output.
|
|
268
|
+
|
|
269
|
+
Ensure finalization is idempotent when multiple callers wait on the same
|
|
270
|
+
settled prompt. Keep current prompt settlement and active-slot behavior.
|
|
271
|
+
|
|
272
|
+
### 3.5 Handle close and parent lifecycle
|
|
273
|
+
|
|
274
|
+
`closeAgent` must:
|
|
275
|
+
|
|
276
|
+
- cancel/finalize any unresolved note owned by the agent;
|
|
277
|
+
- close only the owned pane;
|
|
278
|
+
- remove only safe temporary child launch resources after pane exit; and
|
|
279
|
+
- retain the shared note session and all notes.
|
|
280
|
+
|
|
281
|
+
Add a parent-session shutdown/reload policy that flushes in-memory metadata if
|
|
282
|
+
needed but never deletes the persistent note directory.
|
|
283
|
+
|
|
284
|
+
## Phase 4 — Tool results and child guidance
|
|
285
|
+
|
|
286
|
+
### 4.1 Extend result details
|
|
287
|
+
|
|
288
|
+
Update `shepherd.ts` result details so note-producing actions expose the
|
|
289
|
+
shared session without making callers reconstruct paths:
|
|
290
|
+
|
|
291
|
+
- `start`: opaque `id` plus `noteSession`/`sessionPath`;
|
|
292
|
+
- `prompt`: opaque `id` plus reserved `note` and shared session path;
|
|
293
|
+
- `wait`: result(s) including note reference where available.
|
|
294
|
+
|
|
295
|
+
Use relative paths for project-internal links and absolute paths where the
|
|
296
|
+
child needs to write. Keep the public lifecycle id schemas compatible with the opaque-id contract;
|
|
297
|
+
full handles remain internal implementation state.
|
|
298
|
+
|
|
299
|
+
### 4.2 Update tool descriptions and previews
|
|
300
|
+
|
|
301
|
+
Update the tool description, prompt snippet, guidelines, and call preview only
|
|
302
|
+
as needed to explain:
|
|
303
|
+
|
|
304
|
+
- all agents started by one parent share one note session;
|
|
305
|
+
- prompt notes are reserved before submission;
|
|
306
|
+
- children must read the shared fieldnotes and write only their assigned note;
|
|
307
|
+
- lifecycle ids must be passed as top-level strings (or an array of strings for multi-wait); and
|
|
308
|
+
- notes are retained and not automatically cleaned up.
|
|
309
|
+
|
|
310
|
+
Do not expose a user option that lets an individual child force a new
|
|
311
|
+
note-session directory.
|
|
312
|
+
|
|
313
|
+
### 4.3 Preserve child completion signaling
|
|
314
|
+
|
|
315
|
+
Keep `shepherd_done.ts` and the completion sidecar focused on child execution
|
|
316
|
+
completion. If completion signaling needs to identify a note, pass the
|
|
317
|
+
assigned note reference through the child launch/prompt context or retain
|
|
318
|
+
it in the parent prompt record. The child must not allocate a session from its
|
|
319
|
+
own environment.
|
|
320
|
+
|
|
321
|
+
## Phase 5 — Tests
|
|
322
|
+
|
|
323
|
+
### 5.1 Filesystem tests
|
|
324
|
+
|
|
325
|
+
Add `test/verify-artifact-sessions.mjs` covering:
|
|
326
|
+
|
|
327
|
+
- safe slugs and traversal rejection;
|
|
328
|
+
- first parent binding allocation;
|
|
329
|
+
- repeated lookup of the same parent/project pair;
|
|
330
|
+
- same task with different parent IDs producing separate sessions;
|
|
331
|
+
- same parent ID across repeated calls retaining notes;
|
|
332
|
+
- project-root isolation;
|
|
333
|
+
- note ordinals and collision-safe filenames;
|
|
334
|
+
- fieldnotes and metadata updates;
|
|
335
|
+
- parallel reservation before execution;
|
|
336
|
+
- atomic writes and no temporary-file leftovers;
|
|
337
|
+
- failure/timeout/cancellation finalization;
|
|
338
|
+
- concurrent numbering and binding allocation; and
|
|
339
|
+
- legacy unbound sessions not being implicitly selected.
|
|
340
|
+
|
|
341
|
+
Use temporary project roots and fake opaque parent IDs. Never write tests into
|
|
342
|
+
the repository's real `.shepherd/sessions/` tree.
|
|
343
|
+
|
|
344
|
+
### 5.2 Registry/lifecycle tests
|
|
345
|
+
|
|
346
|
+
Extend `test/verify-registry.mjs` or add a focused test for:
|
|
347
|
+
|
|
348
|
+
- agent records retaining note-session references;
|
|
349
|
+
- prompts retaining note references;
|
|
350
|
+
- lifecycle UUID changes not changing note paths;
|
|
351
|
+
- duplicate finalization being harmless;
|
|
352
|
+
- close cancellation retaining note metadata; and
|
|
353
|
+
- handles from a different parent binding being rejected or clearly invalid.
|
|
354
|
+
|
|
355
|
+
### 5.3 Integration seam
|
|
356
|
+
|
|
357
|
+
If direct lifecycle tests would require a live Herdr server, add a narrow
|
|
358
|
+
injectable seam around the note resolver/reserver rather than mocking the
|
|
359
|
+
whole Herdr CLI. Verify that two `start` calls and two `prompt` calls made with
|
|
360
|
+
the same parent context receive one session path.
|
|
361
|
+
|
|
362
|
+
A live Herdr check should then cover one scout and one planner in the same
|
|
363
|
+
parent session, with both note paths reported under the same directory.
|
|
364
|
+
|
|
365
|
+
## Phase 6 — Documentation and migration
|
|
366
|
+
|
|
367
|
+
Update:
|
|
368
|
+
|
|
369
|
+
- `README.md` with the shared parent-session note behavior and layout;
|
|
370
|
+
- `PLAN.md` with the note binding architecture and lifecycle boundaries;
|
|
371
|
+
- relevant comments in `shepherd.ts`, `lifecycle.ts`, and
|
|
372
|
+
`orchestration.ts`; and
|
|
373
|
+
- the spec's migration notes if implementation choices differ.
|
|
374
|
+
|
|
375
|
+
Keep `.shepherd/` ignored as runtime data. Do not add automatic cleanup or
|
|
376
|
+
silently migrate existing unbound sessions.
|
|
377
|
+
|
|
378
|
+
## Verification and completion order
|
|
379
|
+
|
|
380
|
+
Run in this order:
|
|
381
|
+
|
|
382
|
+
1. `git diff --check`.
|
|
383
|
+
2. Filesystem note-session tests.
|
|
384
|
+
3. Registry/lifecycle tests.
|
|
385
|
+
4. Full `npm test`.
|
|
386
|
+
5. Live Herdr verification of two agents sharing one directory.
|
|
387
|
+
6. Manual inspection of `session.json`, `shepherd.md`, and both notes.
|
|
388
|
+
|
|
389
|
+
Completion requires the regression assertion:
|
|
390
|
+
|
|
391
|
+
```text
|
|
392
|
+
one parent session, two child invocations
|
|
393
|
+
=> one .shepherd/sessions/NNNN-* directory
|
|
394
|
+
=> two distinct note files in that directory
|
|
395
|
+
=> one fieldnotes collection linking both files
|
|
396
|
+
```
|