@luminascale/shepherd 0.0.0-stage → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,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.
|