@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.
Files changed (204) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,61 @@
1
+ # Installation
2
+
3
+ Shepherd is one npm package — `@luminascale/shepherd` — with two host entry
4
+ points. Install the one that matches your host; neither host needs anything
5
+ from the other. You need [Herdr](https://github.com/herdrdev/herdr) and Node.js
6
+ 22 or newer in either case.
7
+
8
+ - [Pi](#pi)
9
+ - [OpenCode](#opencode)
10
+
11
+ ## Pi
12
+
13
+ Install with pi's package installer:
14
+
15
+ ```bash
16
+ pi install npm:@luminascale/shepherd
17
+ ```
18
+
19
+ Reload pi, then verify the extension is available with `/shepherd agents`. You
20
+ should see the bundled agent definitions, including `scout`, `planner`,
21
+ `worker`, and `reviewer`.
22
+
23
+ Pi uses the `/shepherd settings` menu for configuration (see
24
+ [Settings](../README.md#settings)), and pi's steer mode for completion notices.
25
+ No OpenCode setup is required.
26
+
27
+ ## OpenCode
28
+
29
+ Add the package to your OpenCode plugin list:
30
+
31
+ ```jsonc
32
+ // ~/.config/opencode/opencode.json (or the project-level .opencode/opencode.json)
33
+ {
34
+ "$schema": "https://opencode.ai/config.json",
35
+ "plugins": ["@luminascale/shepherd"]
36
+ }
37
+ ```
38
+
39
+ Restart OpenCode, then verify with `/shepherd agents`. The `shepherd_*` tools
40
+ and `/shepherd` command have the same names and semantics as in Pi. You do not
41
+ need to install pi to use Shepherd from OpenCode.
42
+
43
+ OpenCode differences:
44
+
45
+ - Settings are file-based: `~/.config/opencode/pi-shepherd/config.json` (user)
46
+ and `.shepherd/config.json` (project, with `"projectScope": true`). There is
47
+ no settings menu yet.
48
+ - Human `/shepherd …` command output is display-only — it renders in full and
49
+ returns control without starting an assistant turn.
50
+ - Completion notices arrive as normal parent-session messages that wake the
51
+ model.
52
+ - Fieldnotes are bound to the OpenCode session id and the session's working
53
+ directory, on the same `.shepherd/sessions/` layout Pi uses.
54
+ - After an OpenCode server restart, sheep keep running but their opaque ids are
55
+ lost. You get one display-only notice listing the orphaned sheep; use
56
+ `shepherd({ action: "reap" })` to close them safely (or respawn and close the
57
+ old panes). Fieldnotes and queued envelopes remain on disk until reaped.
58
+
59
+ ---
60
+
61
+ [Back to README](../README.md)
@@ -0,0 +1,55 @@
1
+ # Tool reference
2
+
3
+ pi-shepherd exposes these structured tools to the Shepherd. Lifecycle IDs are opaque, session-scoped handles; do not substitute Herdr pane IDs.
4
+
5
+ ## Discovery and inspection
6
+
7
+ | Tool | Arguments | Purpose |
8
+ | --- | --- | --- |
9
+ | `shepherd` | `action`: `agents`, `herd`, or `prune`; optional `agentScope`: `user`, `project`, or `both` | Discover definitions, list active agents, or remove stale registrations. |
10
+ | `shepherd_status` | `id`: agent ID | Inspect an agent without focusing its pane. For an open task the result carries the task ID, state, waiting age, pending request, recipient, and stale flag. |
11
+ | `shepherd_read` | `name`: agent name, agent ID, or pane ID; optional `lines`, `source` | Read recent terminal output for diagnostics. |
12
+
13
+ ## Lifecycle
14
+
15
+ | Tool | Arguments | Purpose |
16
+ | --- | --- | --- |
17
+ | `shepherd_spawn` | `agent`, `label`; optional `placement`, `cwd` | Create an idle persistent agent. Placement is `pane_right`, `pane_down`, `tab`, or `workspace`; the default is a background tab. The model and requested thinking level come from the agent definition Markdown frontmatter. |
18
+ | `shepherd_delegate` | `target`: agent ID, `task`: description; optional `timeout` | Start a tracked task and return a task ID without waiting. One active task per agent. |
19
+ | `shepherd_message` | `target`: agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | Send an asynchronous message (parent or peer). `expectsReply` opens a tracked reply request; the sender's task enters `waiting` until the reply. |
20
+ | `shepherd_prompt` | `id`: agent ID, `message`: one-turn message | **Deprecated** compatibility path. Ties completion to one child turn; prefer `shepherd_delegate` for tracked work. |
21
+ | `shepherd_watch` | `id`: task ID(s) (preferred) or legacy prompt ID(s) | Register a non-blocking completion watcher; completions arrive as steered notifications. An unwatched settlement surfaces at the next settle boundary or as one coalesced idle wake (identical wording on Herdr and hc; only opaque ids differ). |
22
+ | `shepherd_close` | `id`: agent ID | Close an owned agent, cancel its active task (and unresolved prompt), and clear pending requests. |
23
+
24
+ `shepherd_watch` is the explicit observation point: watching an already-settled task returns its result synchronously, and a pending watch delivers steered notifications as tasks settle. An unwatched settlement is still surfaced at the next settle boundary (one extra model request) while the Shepherd is busy, or as one coalesced idle wake; the notice names the `shepherd_watch` call that retrieves the full results. This holds on both backends: Herdr pane settles and hc terminal settles use identical notice wording. On hc, `shepherd_watch` registration and the status view drain first, and a 250 ms background poll keeps the registry fresh while work is open.
25
+
26
+ Example:
27
+
28
+ ```text
29
+ shepherd_spawn({
30
+ agent: "worker",
31
+ label: "implementation",
32
+ placement: "pane_right",
33
+ cwd: "/path/to/project"
34
+ })
35
+ ```
36
+
37
+ `cwd` defaults to the Shepherd session. The model and requested thinking level come from the discovered agent definition; omission, `null`, or `default` inherit the Shepherd session's corresponding settings. Agent scope, project approval, and prompt-shaping options come from settings and the discovered definition rather than spawn arguments. Only panes created and recorded by pi-shepherd can be closed by the extension.
38
+
39
+ ## Child-side tools
40
+
41
+ | Tool | Arguments | Purpose |
42
+ | --- | --- | --- |
43
+ | `shepherd_message` | `target`: `parent` or an owned agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | A child sends an asynchronous message to the parent or a peer. `expectsReply` (to a parent task) opens the tracked reply request. |
44
+ | `shepherd_done` | `taskId`, `summary`; optional `ok`, `returnCode`, `error` | The only normal successful completion for a tracked task. Repeated calls are idempotent. |
45
+
46
+ A child that ends a turn with its tracked task still open feeds itself one reminder turn asking for `shepherd_done` (budget: one per task, `PI_SHEPHERD_DONE_NUDGES` overrides, `0` disables). Aborted or errored turns and turns waiting on an `expectsReply` request are never nudged; a task that survives every reminder is reported to the parent as a stalled completion.
47
+
48
+ ## IDs at a glance
49
+
50
+ - **Agent id** – from `shepherd_spawn`; accepted by `delegate`, `message`, `status`, `close`.
51
+ - **Task id** – from `shepherd_delegate`; the tracked unit of work; accepted by `wait`, `watch`, `message` (`taskId`), and `shepherd_done`.
52
+ - **Prompt id** – from the deprecated `shepherd_prompt`; accepted by `wait` and `watch` (legacy path).
53
+ - **Message id** – returned by `shepherd_message`; used as `replyTo` by the agent answering the request.
54
+
55
+ None of these can be substituted with a Herdr pane ID; pane IDs are diagnostic targets for `shepherd_read` only.
@@ -0,0 +1,147 @@
1
+ # Manual test: ping-pong peer messaging
2
+
3
+ Use this smoke test to verify that two live Shepherd children can exchange a
4
+ correlated request and reply, resume the requester, and complete through
5
+ `shepherd_done`.
6
+
7
+ ## Preconditions
8
+
9
+ - Run inside a live Herdr-managed Shepherd session.
10
+ - Reload the extension after changing the implementation.
11
+ - Use visible child panes (`pane_right` and `pane_down`) when possible.
12
+ - Use generous task deadlines; provider startup can take more than a minute.
13
+ - Do **not** use the removed blocking `shepherd_wait` operation.
14
+
15
+ ## Procedure
16
+
17
+ ### 1. Spawn the children
18
+
19
+ Spawn a planner and a worker, recording the opaque agent IDs returned by each
20
+ call:
21
+
22
+ ```json
23
+ {"agent":"planner","label":"manual planner","placement":"pane_right"}
24
+ {"agent":"worker","label":"manual worker","placement":"pane_down"}
25
+ ```
26
+
27
+ Do not substitute display names, Herdr pane IDs, or agent-kind names for the
28
+ returned lifecycle IDs.
29
+
30
+ ### 2. Delegate the planner task
31
+
32
+ Use the planner's returned agent ID and a deadline of at least 10 minutes:
33
+
34
+ > Watch for one incoming peer request. When you receive it, reply to the exact
35
+ > `replyTo` using `shepherd_message`, omit `taskId` so it is inferred, then call
36
+ > `shepherd_done` with text `planner replied`. Do not use `shepherd_wait`.
37
+
38
+ Record the returned planner task ID.
39
+
40
+ ### 3. Delegate the worker task
41
+
42
+ Use the worker's returned agent ID and put the planner's **actual opaque ID**
43
+ from Step 1 into the task text. Do not pass the planner's definition name,
44
+ display label, Herdr pane ID, or angle-bracket placeholder.
45
+
46
+ > Send planner a peer request using `shepherd_message`: set `target` to the
47
+ > planner spawn result's `id` field (the full opaque `shepherd-agent-...` string),
48
+ > message `Reply with exactly pong`, `expectsReply: true`. Wait for the reply
49
+ > using normal turns (never `shepherd_wait`), then call `shepherd_done` with text
50
+ > containing the reply. Do not call `shepherd_wait`.
51
+
52
+ Do not copy a documentation placeholder into the worker task. Before calling
53
+ `shepherd_delegate`, interpolate the exact ID copied from the planner's spawn
54
+ result into the task text. `planner`, `manual planner`, Herdr pane IDs, and
55
+ angle-bracket placeholders are invalid targets; the child tool rejects them.
56
+
57
+ Record the returned worker task ID.
58
+
59
+ ### 4. Register non-blocking watchers
60
+
61
+ Register a watcher for both task IDs:
62
+
63
+ ```json
64
+ {"id":["<planner task ID>","<worker task ID>"]}
65
+ ```
66
+
67
+ The call must return immediately with both tasks in `pending`. Use
68
+ `shepherd_status` periodically to inspect intermediate state; do not block the
69
+ Shepherd turn waiting for completion.
70
+
71
+ Expected intermediate behavior:
72
+
73
+ - Planner may become idle while its task remains active until it receives the
74
+ request.
75
+ - Worker enters `waiting` after sending the request.
76
+ - Planner replies with `pong` using the request's exact `replyTo`; omitting
77
+ `taskId` exercises child-side task-ID inference.
78
+ - Worker resumes and calls `shepherd_done`.
79
+
80
+ If a watcher was already consumed or completed, register a fresh watcher using
81
+ the task ID. A watcher ID itself is not a valid `shepherd_watch` target.
82
+
83
+ ### 5. Verify terminal results
84
+
85
+ Watch each task ID again, or use the follow-up completion notification. Both
86
+ results must contain:
87
+
88
+ ```text
89
+ status: completed
90
+ ok: true
91
+ returnCode: 0
92
+ ```
93
+
94
+ The worker result text should contain:
95
+
96
+ ```text
97
+ Planner reply: pong
98
+ ```
99
+
100
+ The planner result should contain:
101
+
102
+ ```text
103
+ planner replied
104
+ ```
105
+
106
+ ### 6. Clean up
107
+
108
+ Only after both tasks are terminal, close both agents using their opaque agent
109
+ IDs. Do not close an agent while its watcher is still pending.
110
+
111
+ ## Pass criteria
112
+
113
+ The test passes when:
114
+
115
+ 1. Both children launch in visible panes.
116
+ 2. The worker request reaches the planner.
117
+ 3. The planner's correlated reply reaches the worker.
118
+ 4. The worker resumes without a redundant acknowledgment step.
119
+ 5. Both tasks settle as `completed` with return code `0`.
120
+ 6. `shepherd_watch` reports both terminal results.
121
+ 7. Both agents close cleanly afterward.
122
+
123
+ ## Failure notes
124
+
125
+ - `Agent pane disappeared before the task completed` means the live lifecycle
126
+ test failed; do not count it as a pass even if a response later appears.
127
+ - A short deadline may expire during provider startup. Retry with 10 minutes or
128
+ more before diagnosing messaging behavior.
129
+ - If the child appears idle, inspect `shepherd_status`: idle process state does
130
+ not necessarily mean the tracked task is complete.
131
+ - If a reply is rejected, verify that `replyTo` is the exact incoming request
132
+ message ID and that any explicit `taskId` is the requester's task ID, not the
133
+ responder's task ID.
134
+ - The large `artifactSession` object in a watcher result includes historical
135
+ session artifacts. Use the top-level task result for current status.
136
+
137
+ ## Recorded successful run
138
+
139
+ The reloaded-extension run on 2026-09-01 (steered watcher delivery, issue #10
140
+ fix) succeeded with:
141
+
142
+ - Planner result: `completed`, `ok: true`, `returnCode: 0`, `planner replied`
143
+ - Worker result: `completed`, `ok: true`, `returnCode: 0`, `received reply: pong`
144
+ - Completion observation: both watcher completions were delivered as steered
145
+ follow-ups **mid-turn**, before any cleanup; the combined watcher settled
146
+ both tasks before the agents were closed
147
+ - Cleanup: both agents closed after terminal completion
@@ -0,0 +1,257 @@
1
+ # pi-shepherd — Task-Specific Agent Labels Plan
2
+
3
+ ## Goal
4
+
5
+ Give each spawned agent an optional, human-facing task label while retaining the
6
+ opaque lifecycle ID as the authoritative identifier used by code and lifecycle
7
+ calls.
8
+
9
+ Example:
10
+
11
+ ```text
12
+ shepherd_spawn({ agent: "reviewer", label: "code review" })
13
+ → reviewer: code review
14
+ ```
15
+
16
+ ## Proposed semantics
17
+
18
+ - `agent` remains the discovered agent definition name, such as `reviewer`.
19
+ - `label` is a short, task-specific instance label selected by the calling
20
+ agent.
21
+ - `id` remains the unique lifecycle handle used by `prompt`, `wait`, `status`,
22
+ and `close`.
23
+ - No automatic numbering scheme is introduced.
24
+ - An unlabeled spawn has an empty label and is displayed using its agent type
25
+ alone everywhere, including the Herdr tab, pane, or workspace name:
26
+
27
+ ```text
28
+ /shepherd spawn reviewer
29
+ → reviewer
30
+ ```
31
+
32
+ The display-name rule is intentionally simple: use `<agent>: <label>` when a
33
+ non-empty label is present; otherwise use `<agent>` unchanged. In other words,
34
+ an unlabeled user-created reviewer should produce a Herdr name of `reviewer`,
35
+ not `reviewer:`, `reviewer-`, or an automatically numbered variant.
36
+
37
+ - A labeled spawn combines the agent name and label for human-facing output:
38
+
39
+ ```text
40
+ reviewer + code review → reviewer: code review
41
+ ```
42
+
43
+ The model-facing `shepherd_spawn` input requires a label so every spawned
44
+ instance has a short, task-specific human identifier. Tool guidance should make
45
+ providing that label explicit. The label is separate from the discovered agent
46
+ name and is validated for safe display. The human `/shepherd spawn reviewer`
47
+ command remains valid without a label and passes an empty label through
48
+ unchanged. A human can provide one explicitly with:
49
+
50
+ ```text
51
+ /shepherd spawn reviewer --label "code review"
52
+ ```
53
+
54
+ ## Handle shape
55
+
56
+ The resolved handle may represent an empty label explicitly:
57
+
58
+ ```ts
59
+ {
60
+ id: "shepherd-agent-...",
61
+ agent: "reviewer",
62
+ label: ""
63
+ }
64
+ ```
65
+
66
+ The friendly display name is derived rather than stored separately:
67
+
68
+ ```text
69
+ label present → reviewer: code review
70
+ label empty → reviewer
71
+ ```
72
+
73
+ This can be implemented conceptually as a presence check: if `label` is null,
74
+ undefined, or empty after trimming, return the agent type; otherwise return the
75
+ agent type, separator, and label.
76
+
77
+ Use the same representation for the user-visible tool call/result, the herd
78
+ widget, and the Herdr pane, tab, or workspace label. The recommended format is
79
+ `<agent>: <label>` because the colon clearly separates the role from the
80
+ human-readable task description. A hyphenated form such as
81
+ `reviewer-code-review` is more compact but looks like a machine slug and makes
82
+ the boundary less obvious.
83
+
84
+ This avoids storing redundant `displayName` state and keeps the definition name,
85
+ instance label, and lifecycle identity distinct.
86
+
87
+ ## Identity and lookup
88
+
89
+ The label is for recognition and presentation in the user-facing tool call and
90
+ result, the herd widget, Herdr labels, status, and diagnostics. The TUI should
91
+ show the derived representation instead of exposing the long opaque ID in those
92
+ places.
93
+
94
+ This is a presentation change, not a protocol change. The underlying tool
95
+ arguments and lifecycle registry continue to use the opaque ID so `prompt`,
96
+ `wait`, `status`, and `close` remain unambiguous. Tool results may retain the ID
97
+ for the parent model while `renderCall`/`renderResult` hide it from the user.
98
+ Changing the actual tool protocol to accept only labels is out of scope.
99
+
100
+ Duplicate labels do not change lifecycle identity. Empty labels may be
101
+ repeated, so multiple unlabeled agents can exist as `reviewer`. Non-empty labels
102
+ must be unique for the complete display name within the parent session; reject a
103
+ duplicate rather than silently suffixing it. A label shared by different agent
104
+ types is valid because the complete display names differ:
105
+
106
+ ```text
107
+ reviewer: code review ✅
108
+ reviewer: api review ✅
109
+ reviewer: code review ❌ duplicate
110
+ scout: code review ✅
111
+ ```
112
+
113
+ Labels are not accepted as lifecycle IDs. Lifecycle operations continue to
114
+ resolve agents exclusively by opaque ID.
115
+
116
+ ## Validation
117
+
118
+ Because `label` is a human-facing label rather than a machine slug, preserve
119
+ readable spaces instead of forcing a hyphenated form. Apply these rules:
120
+
121
+ - trim leading and trailing whitespace;
122
+ - treat an empty-after-trimming value as no label;
123
+ - reject control characters and newlines;
124
+ - allow letters, numbers, spaces, `_`, `-`, and `.`;
125
+ - reject `:` because it is the role/label separator;
126
+ - preserve the user's casing; and
127
+ - limit the label to 64 characters.
128
+
129
+ The label must not be confused with the discovered agent name or a Herdr pane
130
+ ID. Any machine-safe value needed for temporary files or launch arguments should
131
+ be derived separately and should not become the user-facing label.
132
+
133
+ ## Implementation areas
134
+
135
+ - Extend spawn arguments and `AgentHandle` with `label`, keeping it separate
136
+ from the discovered agent name.
137
+ - Resolve the optional input to an empty label when omitted; do not maintain a
138
+ per-agent counter or generate labels such as `reviewer-01`.
139
+ - Propagate the label to the user-facing tool call/result, herd widget, and
140
+ Herdr tab/pane/workspace presentation without changing agent discovery or
141
+ launch semantics.
142
+ - Derive the friendly display name at presentation boundaries instead of adding
143
+ a stored `displayName` field.
144
+ - Keep the opaque ID in the underlying model-facing lifecycle protocol even when
145
+ the TUI renders the label instead.
146
+ - Update tool descriptions and prompt guidance so calling agents normally
147
+ provide a short task-specific label.
148
+ - Update `/shepherd` parsing and help text while preserving unlabeled human
149
+ commands.
150
+ - Update README examples and documentation.
151
+
152
+ ## Phased implementation plan
153
+
154
+ ### Phase 1 — Lock down the contract
155
+
156
+ - Use `label` as the public field name; it is optional at the spawn boundary.
157
+ - Use the resolved representation where `agent` is the agent definition name,
158
+ `label` is an empty or non-empty task label, and `id` remains the opaque
159
+ lifecycle identifier.
160
+ - Define the display formatter once:
161
+
162
+ ```text
163
+ non-empty label → <agent>: <label>
164
+ empty label → <agent>
165
+ ```
166
+
167
+ - Apply the decided validation rules: trim whitespace, reject control
168
+ characters/newlines and `:`, allow letters, numbers, spaces, `_`, `-`, and `.`,
169
+ preserve case, and limit labels to 64 characters.
170
+ - Permit repeated empty labels, but reject duplicate non-empty complete display
171
+ names within the parent session. Do not add automatic numbering.
172
+ - Use `/shepherd spawn reviewer --label "code review"` as the documented human
173
+ command syntax; the label remains optional.
174
+
175
+ ### Phase 2 — Extend the lifecycle data model
176
+
177
+ - Add `label` to the spawn input and resolved `AgentHandle`.
178
+ - Resolve omitted, null, or whitespace-only input to an empty label.
179
+ - Preserve the existing opaque-ID registry and lookup behavior.
180
+ - Ensure labels are assigned consistently before the handle is returned and are
181
+ available to status, prompt results, and close-related output.
182
+ - Add registry-level tests for labeled and unlabeled handles.
183
+
184
+ ### Phase 3 — Add shared presentation formatting
185
+
186
+ - Add one shared formatter for the friendly agent name rather than duplicating
187
+ string concatenation across adapters.
188
+ - Verify that an empty label returns exactly the agent type, with no separator,
189
+ suffix, or generated number.
190
+ - Verify that a labeled instance returns the chosen `<agent>: <label>` form.
191
+ - Keep the formatter presentation-only; it must not become a lifecycle lookup
192
+ key or replace the opaque ID.
193
+
194
+ ### Phase 4 — Update spawn surfaces and Herdr presentation
195
+
196
+ - Extend model-facing `shepherd_spawn` schema, descriptions, and guidance so
197
+ calling agents normally provide a short task-specific label.
198
+ - Keep `/shepherd spawn reviewer` valid without a label and pass the empty label
199
+ through unchanged.
200
+ - Use the derived friendly name for Herdr tab, pane, and workspace labels.
201
+ - Use the agent type alone for an unlabeled user-created instance, such as a tab
202
+ named `reviewer`.
203
+ - Preserve the discovered agent name for discovery and launch semantics; do not
204
+ use the composite display name to resolve agent definitions.
205
+ - Ensure background placement and pane ownership behavior remain unchanged.
206
+
207
+ ### Phase 5 — Update user-facing tool and widget rendering
208
+
209
+ - Render the friendly name instead of the long opaque ID in user-facing tool
210
+ calls and results.
211
+ - Update the herd/status widget to show the same friendly name consistently.
212
+ - Retain the opaque ID in the underlying tool result data or model-facing text
213
+ wherever it is needed for follow-up lifecycle calls.
214
+ - Verify that user-facing rendering does not make labels usable accidentally as
215
+ lifecycle IDs.
216
+
217
+ ### Phase 6 — Documentation and compatibility
218
+
219
+ - Update the README, lifecycle examples, command help, and tool guidance.
220
+ - Document labeled and unlabeled spawn behavior, including the exact Herdr name
221
+ for an unlabeled spawn.
222
+ - Document that labels are for human recognition while IDs remain authoritative.
223
+ - Review diagnostics, fieldnotes, and persisted metadata for places where the
224
+ friendly name should be shown without changing stored identity semantics.
225
+
226
+ ### Phase 7 — Verification and live smoke testing
227
+
228
+ - Run all automated schema, CLI, registry, launch, widget, and lifecycle tests.
229
+ - Run a live Herdr check for a labeled spawn and verify the tab/pane/workspace
230
+ name.
231
+ - Run a live Herdr check for `/shepherd spawn reviewer` and verify the name is
232
+ exactly `reviewer`.
233
+ - Verify prompt, wait, status, and close still work using the opaque ID.
234
+ - Verify multiple labels, repeated empty labels, and rejection of duplicate
235
+ non-empty complete display names.
236
+ - Verify no numbering state or generated labels exist.
237
+
238
+ ## Verification
239
+
240
+ Add coverage for:
241
+
242
+ - schema acceptance of labeled and unlabeled spawns;
243
+ - `/shepherd spawn reviewer` producing an empty label;
244
+ - a supplied label producing the expected friendly name (`reviewer: code review`);
245
+ - no automatic numbering or counter state;
246
+ - label normalization and validation;
247
+ - repeated empty labels and duplicate non-empty display-name rejection;
248
+ - propagation to tool-call rendering, the herd widget, and Herdr presentation;
249
+ - user-facing rendering hiding the opaque ID while model-facing results retain
250
+ whatever ID data is required for follow-up calls; and
251
+ - lifecycle calls continuing to use the opaque ID.
252
+
253
+ Run the existing test suite with:
254
+
255
+ ```bash
256
+ npm test
257
+ ```
@@ -0,0 +1,110 @@
1
+ # pi-shepherd — Implementation Plan
2
+
3
+ pi-shepherd is a Herdr-native pi extension for explicit agent lifecycle
4
+ orchestration **and asynchronous tracked-task delegation**. There is no
5
+ subprocess fallback; coordination between agents happens over a parent-
6
+ mediated message broker.
7
+
8
+ ## Architecture
9
+
10
+ ```
11
+ index.ts extension entry and /shepherd command
12
+ src/core/discovery.ts fresh agent discovery and frontmatter parsing
13
+ src/core/orchestration.ts opaque serializable handles and in-memory registries
14
+ src/core/lifecycle.ts spawn, prompt, wait, status, and close primitives
15
+ src/core/herdr.ts Herdr CLI, launch, pane, and ownership helpers
16
+ src/core/artifact-sessions.ts durable parent-bound session, note, and fieldnotes persistence
17
+ src/extension/shepherd.ts umbrella control tool plus separate lifecycle tools
18
+ src/extension/shepherd-done.ts in-tab completion extension
19
+ .agents/agents/ bundled pi-format and shared-format agents
20
+ ```
21
+
22
+ ## Public lifecycle API
23
+
24
+ - `shepherd_spawn({ agent, ...options })` creates an idle persistent agent and
25
+ submits no task.
26
+ - `shepherd_delegate({ target, task, timeout? })` starts a **tracked task** on
27
+ an agent and returns a task id without waiting. Delegation is the preferred
28
+ way to assign work that may need to survive peer replies.
29
+ - `shepherd_message({ target, message, ... })` sends an asynchronous,
30
+ parent-mediated message to the parent or to an owned agent. With
31
+ `expectsReply` it opens a tracked reply request: the sender's task enters
32
+ `waiting` (its pi process may go idle) until a matching reply, a
33
+ `shepherd_done`, or the reply deadline.
34
+ - `shepherd_done` (child-side) is the only normal successful completion
35
+ signal for a tracked task; idle/`agent_end`/`agent_settled` never settle a
36
+ task.
37
+ - `shepherd_watch({ id })` compatibility wait: task ids (preferred) or legacy
38
+ prompt ids; a wait timeout bounds the wait only.
39
+ - `shepherd_watch({ id })` non-blocking task-watcher; completions arrive as
40
+ follow-ups.
41
+ - `shepherd_status({ id })` performs non-mutating inspection; reports
42
+ process state and task state independently.
43
+ - `shepherd_close({ id })` explicitly terminates an owned agent, cancels its
44
+ active tracked task (and unresolved prompt), and clears pending requests.
45
+ - `shepherd_read({ name, lines?, source? })` reads recent terminal output.
46
+ - `shepherd_prompt({ id, message })` is a **deprecated** one-turn
47
+ compatibility path (see docs/guides/tool-reference.md).
48
+
49
+ The umbrella `shepherd` control tool handles `agents`, `herd`, and `prune` and
50
+ contains the shared lifecycle and fieldnotes guidance. The `/shepherd` command
51
+ supports the human-facing `agents`, `herd`, `spawn`, `status`, `read`, and
52
+ `settings` actions.
53
+
54
+ Parallel work and chains are caller composition, not first-class workflow
55
+ modes. A one-shot tracked operation is
56
+ `shepherd_spawn + shepherd_delegate + shepherd_watch + shepherd_close`.
57
+
58
+ ## Completed implementation
59
+
60
+ - Agent, task, prompt, and message references are opaque session-scoped ids exposed in tool arguments and result text. Full handle objects remain internal registry state.
61
+ - Tracked tasks are independent of Herdr process state: `running`,
62
+ `waiting`, and the terminal states (`completed`, `blocked`, `failed`,
63
+ `cancelled`, `timed_out`) live in the lifecycle registry. Only
64
+ `shepherd_done` (or explicit failure/cancellation/timeout) settles a task;
65
+ a child's idle or `agent_end` never does.
66
+ - Cross-agent communication is parent-mediated: the parent broker routes
67
+ envelopes between owned agents with provenance (sender, thread, replyTo)
68
+ and delivers them as queued follow-ups (`followUp`) or urgent input
69
+ (`steer`). Request/reply correlation uses `replyTo` == pending reply
70
+ `messageId`; one outstanding request per task is the initial policy.
71
+ - Stale-wait reminders are informational only: at most one per waiting
72
+ episode, `triggerTurn: false`, and the reply deadline remains the only
73
+ mechanism that settles a stale wait to `blocked`.
74
+ - Registries enforce one unresolved prompt per agent, idempotent settlement, and
75
+ deterministic cancellation.
76
+ - Persistent Herdr tabs launch pi with discovered system prompt, tools, model,
77
+ cwd, and no initial user message.
78
+ - Prompt submission is non-blocking and requires Herdr detection.
79
+ - Wait ignores pre-submit idle state, tracks post-submit transitions, returns
80
+ structured per-prompt results, and supports concurrent multi-wait.
81
+ - Status and close use lifecycle ids and retain the created-pane ownership invariant.
82
+ - Project agent scope remains opt-in and trust-gated.
83
+ - Legacy `delegate`, workflow modes, and `subagent.ts` have been removed.
84
+ - When enabled, durable notes are allocated once per parent pi session/project
85
+ binding, with one fieldnotes collection and distinct per-prompt note files.
86
+ - Fieldnotes can be disabled in settings; the setting is snapshotted when a
87
+ parent pi session starts.
88
+ - README and focused registry/multi-wait tests document and verify the API.
89
+
90
+ ## Verification
91
+
92
+ Run:
93
+
94
+ ```bash
95
+ npm test
96
+ ```
97
+
98
+ Live Herdr checks cover idle spawn, non-blocking prompt, wait/result recovery,
99
+ parallel multi-wait, iterative prompting, cancellation on close, focus
100
+ preservation, and ownership protection.
101
+
102
+ ## Security invariants
103
+
104
+ - User agent discovery is the default.
105
+ - Project-controlled agent definitions require explicit scope and confirmation.
106
+ - Agents have the host user's normal pi tool permissions.
107
+ - Background placement uses `--no-focus`.
108
+ - Only panes recorded in the pi-shepherd created-pane registry may be closed.
109
+ - Launch/session resources are removed only after the child pane is gone.
110
+ - Note sessions are retained and never automatically cleaned up.