@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,417 @@
1
+ /**
2
+ * Shared CLI grammar for pi-shepherd.
3
+ *
4
+ * One options table defines how a shepherd command is spelled as a line of
5
+ * flags and positionals:
6
+ * - `parseShepherdCli` turns `/shepherd …` tokens into doAction args
7
+ * (the human command surface),
8
+ * - `formatShepherdCommand` renders doAction args back into the compact
9
+ * CLI-style text used by tool-call previews (the model surface).
10
+ *
11
+ * The two are the inverse of each other: they read and write the same
12
+ * `OPTION_SPECS` table, so a rendered line always parses back to the same
13
+ * args.
14
+ */
15
+
16
+ import { resolve } from 'node:path';
17
+ import { lifecycleRegistry } from '../runtimes/herdr/orchestration.ts';
18
+
19
+ export const SCOPE_VALUES = ['user', 'project', 'both'] as const;
20
+ export const PLACEMENT_VALUES = ['pane_right', 'pane_down', 'tab', 'workspace'] as const;
21
+ export const SOURCE_VALUES = ['visible', 'recent', 'recent-unwrapped', 'detection'] as const;
22
+
23
+ interface OptionSpec {
24
+ /** Canonical CLI flag name (without `--`). */
25
+ flag: string;
26
+ /** Extra accepted spellings for the human CLI. */
27
+ aliases?: string[];
28
+ /** doAction args key. */
29
+ key: string;
30
+ /** Restricted value set (validated, and used in error hints). */
31
+ values?: readonly string[];
32
+ /** Value must be an integer (coerced from string). */
33
+ integer?: boolean;
34
+ /** Value must be `true`/`false` (coerced to boolean). */
35
+ boolean?: boolean;
36
+ /** Bare flag: no value, always sets true. */
37
+ bare?: boolean;
38
+ }
39
+
40
+ const OPTION_SPECS: Record<string, OptionSpec> = {
41
+ // Scope remains available for `agents` discovery; it is intentionally not a
42
+ // spawn option because spawn must use the persisted settings scope.
43
+ agentScope: { flag: 'scope', aliases: ['agent-scope'], key: 'agentScope', values: SCOPE_VALUES },
44
+ label: { flag: 'label', key: 'label' },
45
+ placement: { flag: 'placement', key: 'placement', values: PLACEMENT_VALUES },
46
+ cwd: { flag: 'cwd', key: 'cwd' },
47
+ lines: { flag: 'lines', key: 'lines', integer: true },
48
+ source: { flag: 'source', key: 'source', values: SOURCE_VALUES },
49
+ timeout: { flag: 'timeout', key: 'timeout', integer: true },
50
+ };
51
+
52
+ const FLAG_LOOKUP = new Map<string, OptionSpec>();
53
+ for (const spec of Object.values(OPTION_SPECS)) {
54
+ FLAG_LOOKUP.set(spec.flag, spec);
55
+ for (const alias of spec.aliases ?? []) FLAG_LOOKUP.set(alias, spec);
56
+ }
57
+
58
+ // Which option keys each command verb accepts (renderer and parser agree).
59
+ const SPAWN_OPTION_KEYS = ['label', 'placement', 'cwd'];
60
+ const READ_OPTION_KEYS = ['lines', 'source'];
61
+
62
+ const USAGE =
63
+ 'Usage: /shepherd <agents [user|project|both] | herd | spawn <agent> [options] | status <agent|id> | read <target> [options] | settings>\n' +
64
+ ' spawn options: --label \"task label\", --placement pane_right|pane_down|tab|workspace, --cwd <path>\n' +
65
+ ' read options: --lines <n>, --source ' +
66
+ SOURCE_VALUES.join('|');
67
+
68
+ // ── Parsing ──────────────────────────────────────────────────────────────────
69
+
70
+ /**
71
+ * Split a command line into tokens. The inverse of `formatShepherdCommand`'s
72
+ * CLI quoting: whitespace separates tokens, and a `"` starts a quoted run that
73
+ * is decoded as a JSON string (so `--cwd="/a b"` re-parses to the value `/a b`).
74
+ * A quoted run may appear mid-token (e.g. immediately after `--cwd=`), so its
75
+ * decoded value is appended to the surrounding token. Because `cliValue` wraps
76
+ * values via `JSON.stringify`, every quoted run is a valid JSON string literal.
77
+ */
78
+ export function tokenizeCli(input: string): string[] {
79
+ const tokens: string[] = [];
80
+ let cur = '';
81
+ let i = 0;
82
+ const push = () => {
83
+ if (cur !== '') tokens.push(cur);
84
+ cur = '';
85
+ };
86
+ while (i < input.length) {
87
+ const c = input[i];
88
+ if (c === '"') {
89
+ // Capture one JSON string literal and decode it, appending to `cur`
90
+ // so `--cwd=<quoted>` keeps the flag prefix attached.
91
+ let j = i + 1;
92
+ let body = '';
93
+ while (j < input.length) {
94
+ if (input[j] === '\\') {
95
+ body += input[j] + (input[j + 1] ?? '');
96
+ j += 2;
97
+ continue;
98
+ }
99
+ if (input[j] === '"') break;
100
+ body += input[j];
101
+ j++;
102
+ }
103
+ try {
104
+ cur += JSON.parse('"' + body + '"');
105
+ } catch {
106
+ cur += body; // malformed quote — keep the raw run rather than crashing
107
+ }
108
+ i = j + 1;
109
+ continue;
110
+ }
111
+ if (c === ' ' || c === '\t') {
112
+ push();
113
+ i++;
114
+ continue;
115
+ }
116
+ cur += c;
117
+ i++;
118
+ }
119
+ push();
120
+ return tokens;
121
+ }
122
+
123
+ export type ParsedShepherdCommand =
124
+ | { action: 'agents'; args: Record<string, unknown> }
125
+ | { action: 'herd'; args: Record<string, unknown> }
126
+ | { action: 'spawn'; args: Record<string, unknown> }
127
+ | { action: 'status'; args: Record<string, unknown> }
128
+ | { action: 'read'; args: Record<string, unknown> };
129
+
130
+ export type ParseShepherdCliResult = ParsedShepherdCommand | { error: string };
131
+
132
+ /**
133
+ * Parse `--flag value` / `--flag=value` / bare flags tokens into an options
134
+ * object using the shared table. Non-`--` tokens are collected into
135
+ * `positional` (the caller decides how many are allowed).
136
+ */
137
+ function parseFlags(
138
+ tokens: string[],
139
+ from: number,
140
+ allowed: readonly string[],
141
+ positional: string[]
142
+ ): { options: Record<string, unknown>; error?: string } {
143
+ const allowedSet = new Set(allowed);
144
+ const options: Record<string, unknown> = {};
145
+ for (let i = from; i < tokens.length; i++) {
146
+ const token = tokens[i];
147
+ if (!token.startsWith('--')) {
148
+ positional.push(token);
149
+ continue;
150
+ }
151
+ const eq = token.indexOf('=');
152
+ const flag = (eq >= 0 ? token.slice(0, eq) : token).replace(/^--/, '');
153
+ const spec = FLAG_LOOKUP.get(flag);
154
+ if (!spec || !allowedSet.has(spec.key))
155
+ return { options, error: `Unknown option "--${flag}".` };
156
+ if (spec.bare) {
157
+ if (eq >= 0) return { options, error: `Option --${spec.flag} takes no value.` };
158
+ options[spec.key] = true;
159
+ continue;
160
+ }
161
+ const raw = eq >= 0 ? token.slice(eq + 1) : tokens[++i];
162
+ if (raw === undefined || raw === '' || raw.startsWith('--'))
163
+ return { options, error: `Missing value for --${spec.flag}.` };
164
+ if (spec.values && !spec.values.includes(raw))
165
+ return {
166
+ options,
167
+ error: `Invalid value "${raw}" for --${spec.flag}; use ${spec.values.join(', ')}.`,
168
+ };
169
+ if (spec.integer) {
170
+ if (!/^-?\d+$/.test(raw))
171
+ return { options, error: `Value "${raw}" for --${spec.flag} must be an integer.` };
172
+ options[spec.key] = Number(raw);
173
+ } else if (spec.boolean) {
174
+ if (raw !== 'true' && raw !== 'false')
175
+ return { options, error: `Value "${raw}" for --${spec.flag} must be true or false.` };
176
+ options[spec.key] = raw === 'true';
177
+ } else {
178
+ options[spec.key] = raw;
179
+ }
180
+ }
181
+ return { options };
182
+ }
183
+
184
+ /**
185
+ * Resolve a human status target (agent name, lifecycle id, or pane id) to the
186
+ * opaque lifecycle id the status action uses. Falls back to the supplied value
187
+ * so the registry can return its useful unknown-id error.
188
+ */
189
+ export function statusHandleTarget(target: string): string {
190
+ for (const handle of lifecycleRegistry.allAgents()) {
191
+ if (handle.id === target || handle.agent === target || handle.paneId === target) {
192
+ return handle.id;
193
+ }
194
+ }
195
+ return target;
196
+ }
197
+
198
+ /**
199
+ * Parse the tokens of a `/shepherd` invocation into doAction args.
200
+ * `settings` is command-only and handled by the caller before parsing.
201
+ */
202
+ export function parseShepherdCli(tokens: string[]): ParseShepherdCliResult {
203
+ const action = tokens[0] ?? '';
204
+
205
+ if (action === 'herd') {
206
+ if (tokens.length > 1) return { error: `/shepherd herd takes no arguments.\n${USAGE}` };
207
+ return { action: 'herd', args: { action: 'herd' } };
208
+ }
209
+
210
+ if (action === 'agents') {
211
+ // Scope may be a positional (`agents both`) or a flag (`agents --scope both`).
212
+ const positional: string[] = [];
213
+ const { options, error } = parseFlags(tokens, 1, ['agentScope'], positional);
214
+ if (error) return { error: `${error}\n${USAGE}` };
215
+ const positionalScope = positional[0];
216
+ if (positional.length > 1 || (positionalScope && 'agentScope' in options))
217
+ return {
218
+ error: `/shepherd agents takes at most one scope argument (positional or --scope).\n${USAGE}`,
219
+ };
220
+ const scope = positionalScope ?? (options.agentScope as string | undefined);
221
+ if (scope && !SCOPE_VALUES.includes(scope as 'user'))
222
+ return { error: `Invalid scope "${scope}"; use ${SCOPE_VALUES.join(', ')}.` };
223
+ return {
224
+ action: 'agents',
225
+ args: { action: 'agents', ...(scope ? { agentScope: scope } : {}) },
226
+ };
227
+ }
228
+
229
+ if (action === 'spawn') {
230
+ const positional: string[] = [];
231
+ const { options, error } = parseFlags(tokens, 1, SPAWN_OPTION_KEYS, positional);
232
+ if (error) return { error: `${error}\n${USAGE}` };
233
+ const [agent, ...extra] = positional;
234
+ if (!agent) return { error: `spawn requires an agent name.\n${USAGE}` };
235
+ if (extra.length > 0) return { error: `Unexpected argument "${extra[0]}".\n${USAGE}` };
236
+ return {
237
+ action: 'spawn',
238
+ args: { action: 'spawn', agent, label: options.label ?? '', ...options },
239
+ };
240
+ }
241
+
242
+ if (action === 'status') {
243
+ if (tokens.length > 2) return { error: `/shepherd status takes exactly one target.\n${USAGE}` };
244
+ const target = tokens[1];
245
+ if (!target) return { error: `status requires an agent name or lifecycle id.\n${USAGE}` };
246
+ return { action: 'status', args: { action: 'status', id: statusHandleTarget(target) } };
247
+ }
248
+
249
+ if (action === 'read') {
250
+ const positional: string[] = [];
251
+ const { options, error } = parseFlags(tokens, 1, READ_OPTION_KEYS, positional);
252
+ if (error) return { error: `${error}\n${USAGE}` };
253
+ const [name, ...extra] = positional;
254
+ if (!name)
255
+ return { error: `read requires a target (agent name, pane id, or lifecycle id).\n${USAGE}` };
256
+ if (extra.length > 0) return { error: `Unexpected argument "${extra[0]}".\n${USAGE}` };
257
+ return { action: 'read', args: { action: 'read', name, ...options } };
258
+ }
259
+
260
+ if (tokens.length === 0)
261
+ return {
262
+ error: `Provide an action. Try: agents, herd, spawn <agent>, status <target>, read <target>, or settings.\n${USAGE}`,
263
+ };
264
+ return {
265
+ error: `Unknown action "${action}". Try: agents, herd, spawn <agent>, status <target>, read <target>, or settings.\n${USAGE}`,
266
+ };
267
+ }
268
+
269
+ // ── Rendering (inverse of the parser) ───────────────────────────────────────
270
+
271
+ /**
272
+ * Tool transports may materialize optional spawn defaults before the renderer
273
+ * sees them. Keep those implementation defaults out of user-facing text so a
274
+ * required-only call still reads like a required-only call.
275
+ */
276
+ export function omitMaterializedDefaults(
277
+ verb: string,
278
+ options: Record<string, any>,
279
+ defaultCwd = process.cwd()
280
+ ): Record<string, any> {
281
+ const result = { ...options };
282
+ if (verb !== 'spawn') return result;
283
+ if (result.placement === 'tab') delete result.placement;
284
+ if (typeof result.cwd === 'string' && resolve(result.cwd) === resolve(defaultCwd))
285
+ delete result.cwd;
286
+ return result;
287
+ }
288
+
289
+ /** Keep tool-call previews compact without rendering an empty placeholder. */
290
+ function previewText(value: unknown, maxLength = 40): string {
291
+ const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : String(value ?? '');
292
+ return text.length > maxLength ? `${text.slice(0, maxLength)}…` : text;
293
+ }
294
+
295
+ /** Render opaque lifecycle ids as compact CLI-like values. */
296
+ function handlePreview(value: unknown, maxLength = 40): string {
297
+ const rawId =
298
+ typeof value === 'string'
299
+ ? value
300
+ : value && typeof value === 'object' && 'id' in value
301
+ ? (value as any).id
302
+ : undefined;
303
+ if (typeof rawId === 'string') {
304
+ try {
305
+ const agent = lifecycleRegistry.getAgent(rawId);
306
+ return previewText(
307
+ `${agent.handle.agent}${agent.handle.label ? `: ${agent.handle.label}` : ''}`,
308
+ maxLength
309
+ );
310
+ } catch {
311
+ try {
312
+ const prompt = lifecycleRegistry.getPrompt(rawId) as any;
313
+ const agent = lifecycleRegistry.getAgent(prompt.handle.agentId);
314
+ return previewText(
315
+ `${agent.handle.agent}${agent.handle.label ? `: ${agent.handle.label}` : ''}`,
316
+ maxLength
317
+ );
318
+ } catch {
319
+ /* retain opaque id for unknown handles */
320
+ }
321
+ }
322
+ }
323
+ if (Array.isArray(value)) {
324
+ return `[${value.map(item => handlePreview(item, maxLength)).join(', ')}]`;
325
+ }
326
+
327
+ if (value && typeof value === 'object' && 'id' in value) {
328
+ return previewText((value as { id?: unknown }).id, maxLength);
329
+ }
330
+
331
+ // A few providers serialize nested legacy handle arguments before they reach the
332
+ // renderer. Keep the display useful even though prepareArguments normalizes
333
+ // them before execution.
334
+ if (typeof value === 'string') {
335
+ try {
336
+ const parsed: unknown = JSON.parse(value);
337
+ if (parsed && typeof parsed === 'object') return handlePreview(parsed, maxLength);
338
+ } catch {
339
+ // It may simply be an id, so fall through.
340
+ }
341
+ }
342
+
343
+ return previewText(value, maxLength);
344
+ }
345
+
346
+ /** Quote values that would otherwise be ambiguous in a command-like preview. */
347
+ function cliValue(value: unknown, maxLength = 80): string {
348
+ const text = previewText(value, maxLength);
349
+ return /[\s"'=]/.test(text) ? JSON.stringify(text) : text;
350
+ }
351
+
352
+ function cliOption(key: string, value: unknown, maxLength = 80): string {
353
+ if (value === undefined || value === null || value === '') return '';
354
+ const spec = OPTION_SPECS[key];
355
+ // Bare flags render without a value; `false` cannot be expressed as a bare
356
+ // flag, so it is omitted (the schema default applies).
357
+ if (spec.bare) return value ? `--${spec.flag}` : '';
358
+ // Booleans render as `--flag=true|false` so the parser round-trips them.
359
+ const text = typeof value === 'boolean' ? String(value) : cliValue(value, maxLength);
360
+ return `--${spec.flag}=${text}`;
361
+ }
362
+
363
+ export interface ShepherdCommandRender {
364
+ verb: string;
365
+ /** Positional args + options as `x y --flag=v …` (no leading verb/space). */
366
+ rest: string;
367
+ }
368
+
369
+ /**
370
+ * Render doAction args into the compact CLI-style line the tool-call preview
371
+ * shows. Flags come from the shared OPTION_SPECS table so every rendered line
372
+ * parses back with `parseShepherdCli`. Defaults that were not supplied are
373
+ * intentionally omitted, which keeps options like --scope visible without
374
+ * dumping internal implementation details (paneId, tabId, workspaceId).
375
+ */
376
+ export function formatShepherdCommand(
377
+ verb: string,
378
+ options: Record<string, any>,
379
+ expanded = false
380
+ ): ShepherdCommandRender {
381
+ const displayOptions = omitMaterializedDefaults(verb, options);
382
+ const valueLimit = expanded ? Number.POSITIVE_INFINITY : 80;
383
+ const idLimit = expanded ? Number.POSITIVE_INFINITY : 48;
384
+ const tokens: string[] = [];
385
+ const add = (key: string) => {
386
+ const option = cliOption(key, options[key], valueLimit);
387
+ if (option) tokens.push(option);
388
+ };
389
+
390
+ switch (verb) {
391
+ case 'spawn':
392
+ tokens.push(cliValue(displayOptions.agent, valueLimit));
393
+ for (const key of SPAWN_OPTION_KEYS) {
394
+ const option = cliOption(key, displayOptions[key], valueLimit);
395
+ if (option) tokens.push(option);
396
+ }
397
+ break;
398
+ case 'prompt':
399
+ tokens.push(handlePreview(options.id, idLimit));
400
+ if (options.message !== undefined) tokens.push(cliValue(options.message, valueLimit));
401
+ add('timeout');
402
+ break;
403
+ case 'status':
404
+ case 'close':
405
+ tokens.push(handlePreview(options.id, idLimit));
406
+ break;
407
+ case 'agents':
408
+ add('agentScope');
409
+ break;
410
+ case 'read':
411
+ tokens.push(cliValue(options.name, valueLimit));
412
+ for (const key of READ_OPTION_KEYS) add(key);
413
+ break;
414
+ }
415
+
416
+ return { verb, rest: tokens.join(' ') };
417
+ }
@@ -0,0 +1 @@
1
+ export * from '../core/config.ts';