@luminascale/shepherd 0.0.0-stage → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (203) 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 +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,199 @@
1
+ # Diagnostics
2
+
3
+ This guide explains how to inspect the system prompts assembled by Pi and
4
+ pi-shepherd. It is useful when checking agent discovery, prompt composition,
5
+ Pi documentation guidance, project instructions, or an agent's configured
6
+ model and tools.
7
+
8
+ ## Quick start
9
+
10
+ Run these commands from the pi-shepherd repository root:
11
+
12
+ ```bash
13
+ # Inspect the parent Pi session (the Shepherd)
14
+ npm run extract:system-prompt -- shepherd
15
+
16
+ # Inspect a discovered child agent (also called a sheep)
17
+ npm run extract:system-prompt -- agent scout
18
+ ```
19
+
20
+ The prompt is written to standard output. To save the raw prompt instead:
21
+
22
+ ```bash
23
+ npm run extract:system-prompt -- agent scout \
24
+ --output /tmp/scout-system-prompt.md
25
+ ```
26
+
27
+ To receive metadata together with the prompt as JSON:
28
+
29
+ ```bash
30
+ npm run extract:system-prompt -- shepherd --json
31
+ ```
32
+
33
+ ## What is captured
34
+
35
+ The extractor starts an ephemeral `pi --mode json` process and captures the
36
+ fully assembled prompt from Pi's `before_agent_start` hook. It stops the
37
+ process immediately after capture, before the first provider request, so this
38
+ diagnostic does not require a model response or an API call.
39
+
40
+ There are two modes:
41
+
42
+ - `shepherd` loads the pi-shepherd parent extension and captures the parent
43
+ session's assembled prompt.
44
+ - `agent <agent>` resolves the named agent using pi-shepherd discovery, then
45
+ captures a child session using that agent's prompt, model, and tools.
46
+
47
+ Only the extension required by the selected mode is loaded explicitly. This
48
+ keeps the diagnostic deterministic and avoids accidentally loading a second
49
+ copy of pi-shepherd from the installed Pi extensions.
50
+
51
+ The captured prompt can include more than the Markdown body of an agent
52
+ file—for example Pi's built-in instructions, project context, skills, tool
53
+ guidance, and pi-shepherd's prompt adjustments.
54
+
55
+ ## Agent discovery options
56
+
57
+ By default, agents are discovered from the user scope. Use `--scope project` or
58
+ `--scope both` when you need project-controlled definitions:
59
+
60
+ ```bash
61
+ npm run extract:system-prompt -- agent scout --scope both
62
+ npm run extract:system-prompt -- agent scout --scope project \
63
+ --cwd /path/to/project
64
+ ```
65
+
66
+ `--cwd` controls discovery and the project context used by the diagnostic
67
+ session. The default is the current working directory.
68
+
69
+ The regular discovery precedence is preserved: user definitions take
70
+ precedence over project definitions, followed by bundled definitions. If the
71
+ agent cannot be found, the command reports an error and exits without
72
+ capturing a prompt.
73
+
74
+ ## Inspecting only the Shepherd contribution
75
+
76
+ If the fully assembled prompt is more detail than you need, use the narrower
77
+ agent-prompt diagnostic:
78
+
79
+ ```bash
80
+ npm run show:shepherd-prompt -- scout
81
+ npm run show:shepherd-prompt -- scout --scope both --cwd /path/to/project
82
+ npm run show:shepherd-prompt -- scout --raw
83
+ ```
84
+
85
+ This command reads the discovered agent definition directly. It shows the
86
+ Markdown system-prompt body and launch mode, but not Pi's built-in prompt,
87
+ project context, skills, or tool instructions.
88
+
89
+ Use this command to answer questions such as:
90
+
91
+ - Which agent definition was selected?
92
+ - Where did it come from?
93
+ - Is it being appended or used as a replacement?
94
+ - What exact Markdown body is being passed to the child?
95
+
96
+ Use `extract:system-prompt` when you need to answer how that body combines
97
+ with the rest of the child session's prompt.
98
+
99
+ ## Useful extractor options
100
+
101
+ ```text
102
+ --cwd <path> Working directory for discovery and Pi (default: current)
103
+ --scope <scope> user, project, or both (agent mode; default: user)
104
+ --output <path> Save raw prompt to this path as well as stdout
105
+ --json Print metadata and prompt as JSON
106
+ --model <model> Override the diagnostic model
107
+ --prompt <text> Use a custom harmless diagnostic user message
108
+ --timeout <sec> Startup timeout in seconds (default: 20)
109
+ --pi <command> Pi executable to run (default: pi)
110
+ ```
111
+
112
+ For example, to compare a project prompt with a user prompt and record the
113
+ source metadata:
114
+
115
+ ```bash
116
+ npm run extract:system-prompt -- agent scout \
117
+ --scope both \
118
+ --cwd /path/to/project \
119
+ --json > /tmp/scout-system-prompt.json
120
+ ```
121
+
122
+ The `--output` file contains only the raw prompt and is written with
123
+ restrictive permissions. JSON output is intended for inspection or automation;
124
+ its `systemPrompt` field contains the same captured prompt.
125
+
126
+ ## Prompt composition details
127
+
128
+ When pi-shepherd launches an agent, the agent Markdown body replaces Pi's
129
+ generic leading identity paragraph unless the agent opts into a different
130
+ configuration. The remaining Pi instructions and context stay available.
131
+
132
+ An agent can omit only Pi's documentation guidance with frontmatter such as:
133
+
134
+ ```markdown
135
+ ---
136
+ name: scout
137
+ description: Fast codebase recon
138
+ omit-pi-documentation: true
139
+ ---
140
+ ```
141
+
142
+ This does not remove project instructions, skills, tools, or the agent body.
143
+
144
+ To inspect a child without Pi’s automatic project context files, set the
145
+ kebab-case frontmatter property to a YAML boolean:
146
+
147
+ ```markdown
148
+ ---
149
+ name: tester
150
+ description: Runs and evaluates GUI tests
151
+ omit-context-files: true
152
+ ---
153
+ ```
154
+
155
+ This makes both a normal Shepherd launch and this diagnostic pass
156
+ `--no-context-files`, disabling automatic `AGENTS.md` and `CLAUDE.md` loading
157
+ for the child Pi session. The agent Markdown body, task/user prompt, Shepherd
158
+ fieldnotes context (when fieldnotes are enabled), configured tools, and model are unchanged. The property is `false` by default; `omit-context-files: false` leaves normal
159
+ loading enabled, and quoted values such as `"true"` are ignored.
160
+
161
+ The extractor is the easiest way to verify the effective result rather than
162
+ inferring it from the agent file alone.
163
+
164
+ ## Troubleshooting
165
+
166
+ ### Agent not found
167
+
168
+ Try listing available agents and check the scope and working directory:
169
+
170
+ ```text
171
+ /shepherd agents
172
+ /shepherd agents both
173
+ ```
174
+
175
+ Then rerun the extractor with `--scope both` and, if needed, `--cwd` pointing
176
+ to the project containing the definition.
177
+
178
+ ### Timeout waiting for capture
179
+
180
+ Confirm that the `pi` executable is available and increase the timeout:
181
+
182
+ ```bash
183
+ npm run extract:system-prompt -- shepherd --timeout 60
184
+ ```
185
+
186
+ Use `--pi <command>` if Pi is not available as `pi` on `PATH`. Any diagnostic
187
+ startup errors are printed by the extractor.
188
+
189
+ ### Unexpected prompt contents
190
+
191
+ Compare the two diagnostics:
192
+
193
+ 1. `show:shepherd-prompt` verifies the selected agent definition and its exact
194
+ body.
195
+ 2. `extract:system-prompt` verifies the final assembled prompt, including Pi
196
+ and project context.
197
+
198
+ Also check `--cwd`, `--scope`, and whether a higher-precedence user definition
199
+ has the same agent name.
@@ -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
+ ```