@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,175 @@
1
+ # Plan: Shepherd Tool Rendering and TUI States
2
+
3
+ Related specification: [spec.md](spec.md)
4
+
5
+ ## Status
6
+
7
+ Implementation complete. The renderer, lifecycle tool previews, custom
8
+ notification presenters, focused rendering tests, and documentation are in
9
+ place. The full suite reaches the pre-existing stale-wait assertion failure.
10
+
11
+ ## Design decisions
12
+
13
+ - Keep model/API-facing `content` and `details` complete and structured.
14
+ - Treat the TUI as a separate presentation layer.
15
+ - Use Pi's native `isError` state by throwing execution failures.
16
+ - Keep the collapsed spawn view compact:
17
+ `shepherd_spawn worker · label · placement` followed by a status.
18
+ - Use minimal expanded section headers: `call` and `return`.
19
+ - Keep top-level call and return fields flat rather than indented.
20
+ - Show optional call arguments when they were provided; omit absent optional
21
+ arguments.
22
+ - Put prose values such as `message`, `task`, `question`, `description`, and
23
+ `output` on the line after their label.
24
+ - Do not use Markdown fences or per-line prefixes for raw prose blocks. Pi's
25
+ `Text` component does not render fences as special blocks, and raw content is
26
+ easier to copy.
27
+ - Style section headers with bold only. Style field labels with accent color;
28
+ leave values and prose content in normal output styling.
29
+ - Omit a separate human-facing `details` section. Keep the complete underlying
30
+ `details` object available to the model/API.
31
+ - Curate the human-facing return fields: show useful IDs, state, delivery,
32
+ model, and errors; hide duplicate call arguments and recursive session
33
+ metadata.
34
+
35
+ ## Phase 1 — Establish the renderer boundary
36
+
37
+ - [x] Separate collapsed TUI output from model/API protocol output.
38
+ - [x] Rename `formatUserFacingText()` to `formatToolResultText()`.
39
+ - [x] Rename `withUserFacingContent()` to `withToolResultText()`.
40
+ - [x] Keep `details.call`, `details.returnValue`, and raw metadata available in
41
+ tool results.
42
+ - [x] Document that `call`, `return`, and `details` are Shepherd presentation
43
+ conventions, not separate Pi result channels.
44
+
45
+ ## Phase 2 — Implement spawn status rendering
46
+
47
+ - [x] Render the invocation preview with agent, label, and placement.
48
+ - [x] Emit a partial update while the child pane is starting.
49
+ - [x] Render the collapsed states:
50
+ - `spawning…`
51
+ - `✓ success`
52
+ - `✗ failed · <error>`
53
+ - [x] Use `context.isError` and thrown execution errors for native Pi error
54
+ styling.
55
+ - [x] Preserve structured failure text for the model/API.
56
+
57
+ ## Phase 3 — Implement human-readable expanded results
58
+
59
+ - [x] Add `formatExpandedToolResult()` and human-value helpers.
60
+ - [x] Render minimal `call` and `return` headers.
61
+ - [x] Render top-level call arguments without indentation.
62
+ - [x] Render optional arguments only when present.
63
+ - [x] Render curated return fields without a separate details dump.
64
+ - [x] Suppress duplicate spawn fields where appropriate.
65
+ - [x] Suppress recursive `artifactSession`, fieldnote, and parent-session
66
+ metadata from the normal human view.
67
+ - [x] Render prose values as raw blocks below their labels.
68
+ - [x] Preserve natural terminal wrapping for long single-line prose values.
69
+ - [x] Add blank lines between status, call, and return sections.
70
+ - [x] Style headers and field labels independently from their values.
71
+ - [x] Prevent colon-containing prose from being mistaken for field labels.
72
+
73
+ ## Phase 4 — Apply the presentation to custom notifications
74
+
75
+ The current worker reply and completion notifications are delivered through
76
+ `pi.sendMessage()` and do not pass through a tool's `renderResult()` renderer.
77
+ They still expose the old protocol-shaped `call` / `return` / `details` text to
78
+ the renderer input, while the human-facing renderer now presents structured
79
+ notification details instead.
80
+
81
+ - [x] Add a notification-specific human formatter using the same flat layout.
82
+ - [x] Render incoming messages and replies as:
83
+
84
+ Shepherd reply from worker: <label>
85
+ message id: ...
86
+ thread id: ...
87
+ reply to: ...
88
+
89
+ message:
90
+ <raw message content>
91
+
92
+ - [x] Apply the same treatment to task completion, prompt completion, and
93
+ stale-wait notifications.
94
+ - [x] Keep notification `details` available internally for model/API use.
95
+ - [x] Confirm that notification prose is not accidentally field-styled.
96
+
97
+ ## Phase 5 — Extend lifecycle tool renderers
98
+
99
+ Apply the same collapsed/expanded contract to the remaining tool family:
100
+
101
+ - [x] `shepherd_delegate`
102
+ - call fields: target and task;
103
+ - return fields: task ID, agent ID, and state.
104
+ - [x] `shepherd_message`
105
+ - call fields: target, delivery options, reply options, and raw message;
106
+ - return fields: message ID, delivery, request ID, and target state.
107
+ - [x] `shepherd_prompt`
108
+ - call fields: agent ID, timeout, and raw prompt;
109
+ - return fields: prompt ID and completion state.
110
+ - [x] `shepherd_watch`
111
+ - call fields: watched IDs and timeout;
112
+ - return fields: completion state and task/prompt IDs.
113
+ - [x] `shepherd_status`
114
+ - call fields: target;
115
+ - return fields: state, task state, waiting information, and errors.
116
+ - [x] `shepherd_close`
117
+ - call fields: agent ID;
118
+ - return fields: closed agent ID and state.
119
+ - [x] `shepherd_read`
120
+ - call fields: target, source, and line count;
121
+ - return fields: terminal output and read metadata.
122
+
123
+ The umbrella `shepherd herd` view also has a curated collapsed renderer:
124
+ show only an `Active agents: <count>` summary. Expanded entries use opaque
125
+ agent IDs (the parent uses the stable `shepherd` alias), indent state fields
126
+ beneath the identity without list markers, and hide pane IDs, workspace IDs,
127
+ and working directories. The collapsed `shepherd agents` result is reduced to
128
+ an `Available agents:` list of names.
129
+
130
+ Each tool should preserve `expanded` and `isPartial` behavior and must not
131
+ change `doAction()` lifecycle semantics.
132
+
133
+ ## Phase 6 — Verification
134
+
135
+ - [x] Add renderer-focused tests for:
136
+ - flat call fields;
137
+ - optional arguments present/absent;
138
+ - raw multiline message content;
139
+ - long single-line wrapping input;
140
+ - colon-containing prose;
141
+ - blank section spacing;
142
+ - bold unaccented section headers;
143
+ - accent field labels and normal values;
144
+ - curated return fields;
145
+ - hidden recursive session metadata.
146
+ - [x] Verify native red tool-shell rendering for thrown failures.
147
+ - [x] Verify partial spawn rendering while Herdr starts.
148
+ - [x] Live-test spawn, message, delegate, watch, status, read, and close.
149
+ - [x] Verify incoming notifications separately from tool results.
150
+ - [x] Run `git diff --check` and the full test suite.
151
+ - [x] Record the existing unrelated stale-wait test failure: the suite still
152
+ fails at `verify-stale-wait.mjs` with `one notification after crossing the
153
+ threshold`.
154
+
155
+ ## Phase 7 — Completion
156
+
157
+ - [ ] Review the final expanded output at narrow and wide terminal widths.
158
+ - [x] Confirm copy/paste behavior for multiline and wrapped single-line values.
159
+ - [x] Update the stable specification and implementation plan.
160
+ - [ ] Commit the implementation and specification updates together.
161
+
162
+ ## Acceptance criteria
163
+
164
+ - The normal spawn view is compact and does not duplicate invocation data.
165
+ - Spawn failures use Pi's native error background and show an actionable error.
166
+ - Expanded output has only `call` and `return` sections.
167
+ - Section headers are bold but not accent-colored.
168
+ - Field labels are accent-colored; values are normal output text.
169
+ - Optional arguments appear when supplied and disappear when absent.
170
+ - Message content starts on the line after `message:` and contains no visual
171
+ fence or per-line prefix.
172
+ - Long single-line messages wrap naturally without changing their content.
173
+ - Recursive artifact/session metadata is not shown in the normal human view.
174
+ - Full structured result data remains available to the model/API.
175
+ - Custom notifications eventually follow the same human-readable contract.
@@ -0,0 +1,469 @@
1
+ # Shepherd Tool Rendering and TUI States
2
+
3
+ ## Status
4
+
5
+ Draft specification — `shepherd_spawn` is the first implementation target.
6
+
7
+ ## Summary
8
+
9
+ Define a consistent user-facing rendering approach for Shepherd tools without
10
+ changing the model-facing lifecycle protocol. Shepherd tool rows should present
11
+ compact, human-readable status in the normal TUI view, while preserving the
12
+ structured `call` / `return` / `details` representation for the model, API
13
+ consumers, and expanded/debug views.
14
+
15
+ The first implementation applies this approach to `shepherd_spawn`:
16
+
17
+ ```text
18
+ shepherd_spawn worker · code review · pane_right
19
+ spawning…
20
+ ```
21
+
22
+ On completion:
23
+
24
+ ```text
25
+ shepherd_spawn worker · code review · pane_right
26
+ ✓ success
27
+ ```
28
+
29
+ On failure:
30
+
31
+ ```text
32
+ shepherd_spawn worker · code review · tab
33
+ ✗ failed · Unknown agent "worker" in user scope. No agents are available.
34
+ ```
35
+
36
+ ## Problem
37
+
38
+ The model and the human operator need different representations of a tool
39
+ result.
40
+
41
+ The model needs opaque lifecycle identifiers and structured return information
42
+ so it can make follow-up calls such as `shepherd_delegate`,
43
+ `shepherd_status`, and `shepherd_close`. A human normally does not need to see
44
+ those identifiers, serialized arguments, fieldnote paths, or return metadata in
45
+ the default TUI view.
46
+
47
+ Previously, Shepherd rendered the complete protocol result as the primary TUI
48
+ output. This caused several problems:
49
+
50
+ - the call row and result row repeated the same agent and label information;
51
+ - successful output was too verbose for routine use;
52
+ - errors could appear with success styling because Shepherd returned a normal
53
+ result containing `returnCode: 1` instead of throwing;
54
+ - Pi's native error background was not activated;
55
+ - partial startup state was not visible while the child pane was being created.
56
+
57
+ ## Goals
58
+
59
+ - Keep the normal TUI row compact and useful to a human operator.
60
+ - Make the call row identify the requested operation and its important inputs.
61
+ - Render explicit partial, success, and failure states.
62
+ - Use Pi's native error state and `toolErrorBg` for failed tool execution.
63
+ - Keep opaque IDs and protocol details available to the model.
64
+ - Keep full protocol details available when the human expands a tool row.
65
+ - Avoid duplicating call arguments in the normal result line.
66
+ - Establish a pattern that can be reused by all Shepherd lifecycle tools.
67
+
68
+ ## Non-goals
69
+
70
+ - Do not remove opaque IDs from model-visible tool results.
71
+ - Do not change lifecycle semantics, result schemas, or ownership rules.
72
+ - Do not expose Herdr pane IDs in the human-facing summary.
73
+ - Do not make the TUI renderer the source of truth for lifecycle state.
74
+ - Do not replace Pi's default tool shell with a custom shell unless the default
75
+ shell cannot represent the required state.
76
+
77
+ ## Audience boundaries
78
+
79
+ Shepherd has two output audiences:
80
+
81
+ ### Model/API-facing output
82
+
83
+ The tool result content and structured details must continue to contain the
84
+ information needed for orchestration. For a successful spawn this includes the
85
+ opaque agent ID, agent name, label, model, and fieldnote information where
86
+ applicable.
87
+
88
+ The protocol representation remains structured and may look like:
89
+
90
+ ```text
91
+ shepherd_spawn spawned worker: code review
92
+
93
+ call:
94
+ shepherd_spawn {"agent":"worker","label":"code review"}
95
+
96
+ return:
97
+ {"id":"shepherd-agent-...","agent":"worker","label":"code review"}
98
+
99
+ details:
100
+ agent id: shepherd-agent-...
101
+ agent fieldnote: .shepherd/sessions/...
102
+ return code: 0
103
+ ```
104
+
105
+ ### Human TUI output
106
+
107
+ The default view should show only the information needed to understand what
108
+ is happening:
109
+
110
+ - the operation name;
111
+ - the relevant invocation summary;
112
+ - a short status;
113
+ - an actionable error message when execution fails.
114
+
115
+ Opaque IDs, model names, fieldnotes, serialized arguments, and return metadata
116
+ belong in the model/API result and the expanded/debug view unless a future UX
117
+ requirement explicitly says otherwise.
118
+
119
+ ## Rendering contract
120
+
121
+ Pi provides two renderer slots:
122
+
123
+ - `renderCall(args, theme, context)` renders the invocation row;
124
+ - `renderResult(result, { expanded, isPartial }, theme, context)` renders the
125
+ result row.
126
+
127
+ The default Pi tool shell supplies the background. It derives the shell state
128
+ from the execution result:
129
+
130
+ - partial execution → `toolPendingBg`;
131
+ - successful execution → `toolSuccessBg`;
132
+ - thrown execution error → `toolErrorBg`.
133
+
134
+ Therefore, Shepherd must throw execution failures rather than return an
135
+ ordinary result with an error-looking `details` object. Returning
136
+ `returnCode: 1` alone does not set Pi's `isError` state.
137
+
138
+ ## `shepherd_spawn` rendering
139
+
140
+ ### `renderCall`
141
+
142
+ The call row is the concise invocation preview. It should render:
143
+
144
+ ```text
145
+ shepherd_spawn <agent> · <label> · <placement>
146
+ ```
147
+
148
+ Rules:
149
+
150
+ - always show `shepherd_spawn` and the agent name;
151
+ - show the label when present;
152
+ - show placement when explicitly provided;
153
+ - omit absent optional values rather than printing placeholders;
154
+ - use the operation/title theme for the tool name, accent styling for the
155
+ agent, and dim styling for optional context;
156
+ - do not show opaque IDs in the call row.
157
+
158
+ Example:
159
+
160
+ ```text
161
+ shepherd_spawn worker · code review · pane_right
162
+ ```
163
+
164
+ ### Partial result
165
+
166
+ While `startAgent()` is creating and preparing the child pane, the tool emits a
167
+ partial update. The result row is intentionally short:
168
+
169
+ ```text
170
+ spawning…
171
+ ```
172
+
173
+ The call row already identifies the agent, label, and placement, so the
174
+ partial row must not repeat them.
175
+
176
+ ### Successful result
177
+
178
+ The collapsed result row is:
179
+
180
+ ```text
181
+ ✓ success
182
+ ```
183
+
184
+ The call row supplies the operation context. The result row should not repeat
185
+ `worker`, the label, placement, or the opaque agent ID.
186
+
187
+ When expanded, the success result uses the final spaced, human-readable
188
+ layout:
189
+
190
+ ```text
191
+ ✓ success
192
+
193
+ call
194
+ agent: worker
195
+ label: minimal headers verification
196
+ placement: tab
197
+
198
+ return
199
+ status: spawned
200
+ agent id: shepherd-agent-...
201
+ model: github-copilot/gpt-5.6-luna
202
+ ```
203
+
204
+ Optional call arguments remain visible in the expanded call when they were
205
+ provided. For example, `placement: tab` is shown when that placement was part
206
+ of the invocation; absent optional arguments are omitted.
207
+
208
+ ### Failed result
209
+
210
+ The collapsed result row is:
211
+
212
+ ```text
213
+ ✗ failed · <actionable error message>
214
+ ```
215
+
216
+ For example:
217
+
218
+ ```text
219
+ ✗ failed · Unknown agent "worker" in user scope. No agents are available. Call shepherd with action "agents" to list exact names.
220
+ ```
221
+
222
+ The complete tool shell must use Pi's native error background. Expanded output
223
+ retains the status, call, and curated error return:
224
+
225
+ ```text
226
+ ✗ failed · Unknown agent "worker" in user scope. No agents are available.
227
+
228
+ call
229
+ agent: worker
230
+ label: code review
231
+ placement: tab
232
+
233
+ return
234
+ status: failed
235
+ error: Unknown agent "worker" in user scope. No agents are available.
236
+ return code: 1
237
+ ```
238
+
239
+ The error message should come from structured error details when available.
240
+ When Pi has converted a thrown error into a result with empty details, the
241
+ renderer may derive the first-line error message from the formatted content.
242
+
243
+ ## Result and error flow
244
+
245
+ The execution adapter must preserve the structured protocol text while
246
+ allowing Pi to observe the failure:
247
+
248
+ 1. Execute the Shepherd operation.
249
+ 2. For success, return the normal `AgentToolResult` and add the public call
250
+ metadata.
251
+ 3. For failure, construct the same user/model-facing structured error text.
252
+ 4. Throw an `Error` containing that text.
253
+ 5. Pi catches the thrown error, marks the tool execution as `isError`, and uses
254
+ `toolErrorBg` for the complete tool shell.
255
+ 6. The renderer uses `context.isError` and renders `✗ failed · ...`.
256
+
257
+ This deliberately separates:
258
+
259
+ - the textual protocol preserved for the model;
260
+ - Pi's execution-level error flag used by the TUI shell; and
261
+ - the compact human-facing status line.
262
+
263
+ ## Expanded output
264
+
265
+ Expanded output is the human inspection path. It should be semantic and
266
+ copy-friendly rather than a dump of JSON. The expanded renderer should retain the call and return concepts, but format
267
+ each as labeled fields. It should not render a separate details section:
268
+
269
+ ```text
270
+ call
271
+ target: worker
272
+ expects reply: yes
273
+ delivery: followUp
274
+ message:
275
+ First line
276
+ Second line
277
+ Third line
278
+
279
+ return
280
+ status: queued
281
+ message id: shepherd-message-...
282
+ delivery: queued
283
+ ```
284
+
285
+ Message values always start on the line after the `message:` label. Top-level
286
+ call arguments and return fields are rendered without indentation so labels and
287
+ raw message content share the same visual edge. Multiline text is rendered as a raw text
288
+ block without Markdown fences or per-line prefixes. Long single-line messages
289
+ use the same layout and wrap naturally in the terminal. Nested objects and
290
+ arrays may still use indentation. Section headers and argument/return labels
291
+ should use bold styling without accent color while argument and return labels
292
+ use accent styling. Values remain normal output styling. The message content
293
+ itself should remain unstyled normal text. This keeps the
294
+ message content easy to select and paste while avoiding visual fence characters
295
+ that Pi does not render as a special text block.
296
+
297
+ Common scalar values should be rendered as labeled fields rather than JSON:
298
+
299
+ ```text
300
+ agent: worker
301
+ label: code review
302
+ placement: pane_right
303
+ return code: 0
304
+ ```
305
+
306
+ Nested objects should become nested labeled sections, and arrays should use one
307
+ item per line. Ordinary strings should not receive JSON quotes or escaped
308
+ newline sequences. Opaque lifecycle IDs, model names, fieldnote/artifact paths,
309
+ return codes, and structured error information remain available in expanded
310
+ output because this is the inspection path.
311
+
312
+ The return section is curated for human use. It should include the primary
313
+ operation result, useful identifiers, state, delivery information, and errors.
314
+ It should omit duplicate call arguments, successful `returnCode: 0`, recursive
315
+ artifact/session metadata, and internal parent-session paths. The complete
316
+ `details` object remains available to the model/API; it is not rendered as a
317
+ separate human-facing section.
318
+
319
+ A dedicated copy-message interaction is out of scope for this iteration. The
320
+ raw message block is intentionally not prefixed or fenced so selecting its
321
+ content preserves the message text as closely as possible.
322
+
323
+ The expanded section labels are intentionally minimal:
324
+
325
+ ```text
326
+ call
327
+ return
328
+ ```
329
+ The operation name is already present in the outer call row, and the result
330
+ status is rendered as a `status:` field under `return`.
331
+
332
+ The expanded renderer must not change the underlying result content merely to
333
+ make the collapsed view shorter. The model/API-facing result and structured
334
+ `details` remain the source of truth; this is a TUI-only presentation layer.
335
+ Expanded non-spawn results begin with one blank line so the `call` section is
336
+ visually separated from the outer invocation row.
337
+ The final spawn presentation is:
338
+
339
+ ```text
340
+ shepherd_spawn worker · minimal headers verification · tab
341
+ ✓ success
342
+
343
+ call
344
+ agent: worker
345
+ label: minimal headers verification
346
+ placement: tab
347
+
348
+ return
349
+ status: spawned
350
+ agent id: shepherd-agent-...
351
+ model: github-copilot/gpt-5.6-luna
352
+ ```
353
+
354
+ ## Formatting function names
355
+
356
+ The existing `formatUserFacingText()` and `withUserFacingContent()` names are
357
+ misleading because their output is also delivered to the model/API surface.
358
+ Before adding the human-readable expanded formatter, rename them to neutral
359
+ names:
360
+
361
+ ```text
362
+ formatUserFacingText() → formatToolResultText()
363
+ withUserFacingContent() → withToolResultText()
364
+ ```
365
+
366
+ The new TUI-only functions should have clearly separate names, for example:
367
+
368
+ ```text
369
+ formatExpandedToolResult()
370
+ formatHumanValue()
371
+ formatMultilineValue()
372
+ ```
373
+
374
+ `formatToolResultText()` remains responsible for shared protocol-oriented text;
375
+ `formatExpandedToolResult()` is responsible only for the human-readable TUI
376
+ view. The latter renders only `call` and a curated `return`; it does not emit a
377
+ separate `details` section.
378
+
379
+ ## Custom notification rendering
380
+
381
+ Incoming replies, child messages, task completions, prompt completions, and
382
+ stale-wait notices are delivered through `pi.sendMessage()`, so they do not
383
+ use a registered tool's `renderResult()` callback. Their message `content`
384
+ remains protocol-oriented for the model/API, while the custom message renderer
385
+ uses the structured `details` payload for the human-facing view.
386
+
387
+ A reply is rendered as a compact metadata block followed by a raw message
388
+ block:
389
+
390
+ ```text
391
+ Shepherd reply from worker: code review
392
+ message id: shepherd-message-...
393
+ task id: shepherd-task-...
394
+ thread id: shepherd-message-...
395
+ reply to: shepherd-message-...
396
+ message:
397
+ The reply remains plain and copyable.
398
+ ```
399
+
400
+ Watcher and stale-wait notifications use the same flat labels and raw blocks.
401
+ They must not render a separate `call`, `return`, or `details` dump, and prose
402
+ inside notification fields must not be mistaken for field labels.
403
+
404
+ ## Generalization to other lifecycle tools
405
+
406
+ The same two-row pattern should be applied to the remaining lifecycle tools.
407
+ The umbrella `shepherd herd` result is a special compact count. Its collapsed
408
+ result is only `Active agents: <count>`. Agent identities and states belong in
409
+ the expanded view, not the routine collapsed row.
410
+
411
+ In expanded output, lifecycle-owned entries use their opaque ID, with their
412
+ state fields indented beneath the identity and no list-dash noise:
413
+
414
+ ```text
415
+ agents:
416
+ agent id: shepherd-agent-...
417
+ agent: worker
418
+ label: code review
419
+ state: idle
420
+
421
+ agent id: shepherd
422
+ state: working
423
+ focused: yes
424
+ ```
425
+
426
+ The parent Shepherd process has no spawned-agent ID, so it uses the stable
427
+ `agent id: shepherd` alias. Herdr pane IDs, workspace IDs, and working
428
+ directories remain hidden.
429
+
430
+ The collapsed `shepherd agents` result is also name-only:
431
+
432
+ ```text
433
+ Available agents: planner, reviewer, scout, worker
434
+ ```
435
+
436
+ | Tool | Call row | Result row |
437
+ |---|---|---|
438
+ | `shepherd_spawn` | `shepherd_spawn worker · label · placement` | `spawning…`, `✓ success`, or `✗ failed · error` |
439
+ | `shepherd_delegate` | `shepherd_delegate <agent/task summary>` | `✓ delegated` or `✗ failed · error` |
440
+ | `shepherd_message` | `shepherd_message <recipient>` | `✓ queued`, `waiting…`, or `✗ failed · error` |
441
+ | `shepherd_watch` | `shepherd_watch <count> task(s)` | `watching…`, `✓ completed`, or `✗ failed · error` |
442
+ | `shepherd_status` | `shepherd_status <agent>` | compact state summary or `✗ failed · error` |
443
+ | `shepherd_close` | `shepherd_close <agent>` | `✓ closed` or `✗ failed · error` |
444
+ | `shepherd_read` | `shepherd_read <target>` | compact preview; expanded terminal output |
445
+
446
+ These summaries should be semantic rather than copies of the serialized tool
447
+ protocol. In particular, expanded `shepherd_status` output should show one
448
+ status summary and the task fields, not repeat the same nested status record.
449
+ Each renderer should preserve `expanded` and `isPartial` behavior.
450
+
451
+ ## Acceptance criteria
452
+
453
+ - `shepherd_spawn` displays agent, label, and explicit placement once in the
454
+ call row.
455
+ - The normal success result is exactly a compact success state and does not
456
+ repeat invocation arguments.
457
+ - The partial result is a compact `spawning…` state.
458
+ - Failed execution renders `✗ failed · <error>` and the complete Pi tool shell
459
+ uses the error background.
460
+ - Expanded output retains semantic call and curated return sections without a
461
+ separate details dump.
462
+ - Multiline values are rendered inside copy-friendly fences without per-line
463
+ prefixes.
464
+ - The model still receives the opaque agent ID after a successful spawn.
465
+ - A failed tool execution is signaled by throwing, not only by a non-zero
466
+ `returnCode` in returned details.
467
+ - The renderer does not expose Herdr pane IDs.
468
+ - Future lifecycle renderers can follow the same call/result/status contract
469
+ without changing `doAction()` semantics.