@luminascale/shepherd 0.0.0-stage → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env node
2
+ const { LifecycleRegistry } = await import('../src/core/orchestration.ts');
3
+ let failures = 0;
4
+ function assert(ok, label) {
5
+ if (ok) console.log(`PASS ${label}`);
6
+ else {
7
+ failures++;
8
+ console.log(`FAIL ${label}`);
9
+ }
10
+ }
11
+ const { prepareShepherdArguments, formatIdForModel } = await import('../src/extension/shepherd.ts');
12
+ const preparedHandle = prepareShepherdArguments({
13
+ action: 'prompt',
14
+ handle: JSON.stringify({ id: 'agent-1', agent: 'worker' }),
15
+ message: 'say hi',
16
+ });
17
+ const preparedId = prepareShepherdArguments({ action: 'prompt', id: 'agent-1', message: 'say hi' });
18
+ assert(preparedId.id === 'agent-1', 'native lifecycle id is preserved');
19
+ const preparedLegacy = prepareShepherdArguments({
20
+ action: 'prompt',
21
+ handle: JSON.stringify({ id: 'agent-1', agent: 'worker' }),
22
+ message: 'say hi',
23
+ });
24
+ assert(
25
+ preparedLegacy.id === 'agent-1' && !('handle' in preparedLegacy),
26
+ 'legacy handle is migrated to id'
27
+ );
28
+ const preparedArray = prepareShepherdArguments({
29
+ action: 'wait',
30
+ id: JSON.stringify(['prompt-1', 'prompt-2']),
31
+ });
32
+ assert(
33
+ JSON.stringify(preparedArray.id) === JSON.stringify(['prompt-1', 'prompt-2']),
34
+ 'stringified id array is normalized before validation'
35
+ );
36
+ assert(
37
+ formatIdForModel('shepherd-agent-1') === 'shepherd-agent-1',
38
+ 'model-facing id text remains copyable'
39
+ );
40
+ const normalizedOptions = prepareShepherdArguments({
41
+ action: 'spawn',
42
+ agent: 'worker',
43
+ agentScope: 'project',
44
+ direction: 'down',
45
+ confirmProjectAgents: 'False',
46
+ omitSystemPrompt: 'True',
47
+ timeout: '120000',
48
+ });
49
+ assert(
50
+ !('agentScope' in normalizedOptions) &&
51
+ !('direction' in normalizedOptions) &&
52
+ !('confirmProjectAgents' in normalizedOptions) &&
53
+ !('omitSystemPrompt' in normalizedOptions),
54
+ 'settings-owned spawn options are discarded'
55
+ );
56
+ assert(normalizedOptions.timeout === 120000, 'stringified integer is normalized');
57
+
58
+ const registry = new LifecycleRegistry();
59
+ const agent = registry.registerAgent({ agent: 'scout', paneId: 'owned-pane' });
60
+ assert(
61
+ JSON.parse(JSON.stringify(agent)).id === agent.id,
62
+ 'stable internal agent handle serialization'
63
+ );
64
+ assert(registry.getAgent(agent.id).handle.id === agent.id, 'agent id resolves in registry');
65
+ try {
66
+ registry.getAgent(JSON.stringify(agent));
67
+ assert(false, 'quoted agent object rejected');
68
+ } catch (e) {
69
+ assert(e.code === 'unknown_handle', 'quoted agent object rejected');
70
+ assert(e.message.includes('pane id'), 'agent id error explains pane distinction');
71
+ }
72
+ const prompt = registry.createPrompt(agent);
73
+ assert(
74
+ JSON.parse(JSON.stringify(prompt)).agentId === agent.id,
75
+ 'stable internal prompt handle serialization'
76
+ );
77
+ assert(registry.getPrompt(prompt.id).handle.id === prompt.id, 'prompt id resolves in registry');
78
+ try {
79
+ registry.getPrompt(JSON.stringify(prompt));
80
+ assert(false, 'quoted prompt object rejected');
81
+ } catch (e) {
82
+ assert(e.code === 'unknown_handle', 'quoted prompt object rejected');
83
+ assert(e.message.includes('agent id'), 'prompt id error explains id distinction');
84
+ }
85
+ try {
86
+ registry.createPrompt(agent);
87
+ assert(false, 'duplicate active prompt rejected');
88
+ } catch (e) {
89
+ assert(e.code === 'active_prompt', 'duplicate active prompt rejected');
90
+ }
91
+ registry.settlePrompt(prompt, {
92
+ promptId: prompt.id,
93
+ agentId: agent.id,
94
+ status: 'done',
95
+ ok: true,
96
+ text: 'ok',
97
+ });
98
+ assert((await registry.wait(prompt)).returnCode === 0, 'successful prompt includes return code 0');
99
+ assert(registry.status(agent).state === 'done', 'settlement updates agent state');
100
+ assert(
101
+ registry.settlePrompt(prompt, {
102
+ promptId: prompt.id,
103
+ agentId: agent.id,
104
+ status: 'failed',
105
+ ok: false,
106
+ }).status === 'done',
107
+ 'settlement is idempotent'
108
+ );
109
+ const second = registry.createPrompt(agent);
110
+ registry.close(agent);
111
+ assert((await registry.wait(second)).status === 'cancelled', 'close cancels unresolved prompt');
112
+ assert(
113
+ (await registry.wait(second)).returnCode === 130,
114
+ 'cancelled prompt includes return code 130'
115
+ );
116
+ assert(registry.status(agent).state === 'closed', 'close marks agent closed');
117
+ try {
118
+ registry.getAgent({ id: 'foreign' });
119
+ assert(false, 'unknown handle rejected');
120
+ } catch (e) {
121
+ assert(e.code === 'unknown_handle', 'unknown handle rejected');
122
+ }
123
+ if (failures) process.exit(1);
124
+ console.log('All registry assertions passed.');
@@ -0,0 +1,111 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * T019 — `@luminascale/pi-shepherd` → `@luminascale/shepherd`.
4
+ *
5
+ * Verifies the npm name changed while functional identifiers stayed frozen,
6
+ * and simulates old-install → remove → new-install to prove settings and
7
+ * herd registrations survive (SC-005).
8
+ */
9
+ import assert from 'node:assert/strict';
10
+ import fs from 'node:fs';
11
+ import os from 'node:os';
12
+ import path from 'node:path';
13
+ import { execFileSync } from 'node:child_process';
14
+
15
+ const repo = path.resolve(import.meta.dirname, '..');
16
+ const pkg = JSON.parse(fs.readFileSync(path.join(repo, 'package.json'), 'utf8'));
17
+ assert.equal(pkg.name, '@luminascale/shepherd', 'manifest carries the new npm name');
18
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-shepherd-rename-'));
19
+ process.env.HOME = tmp;
20
+ process.env.PI_CODING_AGENT_DIR = path.join(tmp, 'pi-agent');
21
+ process.env.OPENCODE_CONFIG_DIR = path.join(tmp, 'opencode');
22
+ const { setHostCapabilities } = await import('../src/core/host.ts');
23
+ setHostCapabilities({
24
+ getAgentDir: () => process.env.PI_CODING_AGENT_DIR,
25
+ projectConfigDirName: '.pi',
26
+ dataDirName: 'pi-shepherd',
27
+ parseFrontmatter: () => ({ frontmatter: {}, body: '' }),
28
+ });
29
+ const { hostCapabilities } = await import('../src/core/host.ts');
30
+ const { loadSettings, userConfigFile } = await import('../src/core/config.ts');
31
+ const { loadCreatedPanes } = await import('../src/runtimes/herdr/herdr.ts');
32
+
33
+ const dataDir = path.join(hostCapabilities().getAgentDir(), hostCapabilities().dataDirName);
34
+ assert.equal(dataDir, path.join(tmp, 'pi-agent', 'pi-shepherd'), 'user data path stays frozen');
35
+ const settingsFile = userConfigFile();
36
+ const registryFile = path.join(dataDir, 'created-panes.json');
37
+
38
+ // Frozen functional identifiers must not mention the package name.
39
+ assert.equal(hostCapabilities().dataDirName, 'pi-shepherd');
40
+ assert.equal(path.basename(settingsFile), 'config.json');
41
+ assert.doesNotMatch(fs.readFileSync(path.join(repo, 'src/opencode/host.ts'), 'utf8'), /@luminascale\//);
42
+ const configSource = fs.readFileSync(path.join(repo, 'src/core/config.ts'), 'utf8');
43
+ assert.match(configSource, /['"]\.shepherd['"]/);
44
+ assert.match(configSource, /['"]config\.json['"]/);
45
+ console.log('PASS npm name changed; tool/env/config/registry identifiers stay frozen');
46
+
47
+ // Old install: data in the frozen paths, plus an old-name package directory.
48
+ const oldPackageDir = path.join(tmp, 'consumer', 'node_modules', '@luminascale', 'pi-shepherd');
49
+ fs.mkdirSync(oldPackageDir, { recursive: true });
50
+ fs.writeFileSync(
51
+ path.join(oldPackageDir, 'package.json'),
52
+ JSON.stringify({ name: '@luminascale/pi-shepherd', version: '0.5.1' })
53
+ );
54
+ fs.mkdirSync(path.dirname(settingsFile), { recursive: true });
55
+ fs.writeFileSync(
56
+ settingsFile,
57
+ JSON.stringify({ timeout: 17, fieldnotes: false, backend: 'herdr', projectScope: false })
58
+ );
59
+ fs.writeFileSync(
60
+ registryFile,
61
+ JSON.stringify([
62
+ {
63
+ paneId: 'wF:p7',
64
+ name: 'scout',
65
+ cwd: tmp,
66
+ createdAt: 1234,
67
+ ownerSession: 'ses-old-install',
68
+ dir: path.join(tmp, 'launch-old'),
69
+ },
70
+ ])
71
+ );
72
+ assert.equal(loadSettings().timeout, 17);
73
+ assert.equal(loadSettings().fieldnotes, false);
74
+ assert.equal(loadCreatedPanes()[0].ownerSession, 'ses-old-install');
75
+ console.log('PASS old install has settings and a live herd registration');
76
+
77
+ // Remove old install, then install the renamed package from a fresh tarball.
78
+ fs.rmSync(path.join(tmp, 'consumer', 'node_modules'), { recursive: true, force: true });
79
+ const consumer = path.join(tmp, 'consumer');
80
+ fs.mkdirSync(consumer, { recursive: true });
81
+ fs.writeFileSync(
82
+ path.join(consumer, 'package.json'),
83
+ JSON.stringify({ name: 'rename-consumer', private: true, version: '1.0.0' })
84
+ );
85
+ const packResult = JSON.parse(
86
+ execFileSync('npm', ['pack', '--json', '--pack-destination', tmp], {
87
+ cwd: repo,
88
+ encoding: 'utf8',
89
+ stdio: ['ignore', 'pipe', 'pipe'],
90
+ })
91
+ );
92
+ const packed = Array.isArray(packResult) ? packResult[0] : Object.values(packResult)[0];
93
+ const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('npm_config_')));
94
+ execFileSync('npm', ['install', path.join(tmp, packed.filename), '--legacy-peer-deps', '--no-audit', '--no-fund'], {
95
+ cwd: consumer,
96
+ env,
97
+ stdio: 'ignore',
98
+ });
99
+ assert.equal(fs.existsSync(path.join(consumer, 'node_modules', '@luminascale', 'shepherd')), true);
100
+ assert.equal(fs.existsSync(oldPackageDir), false, 'old name is gone after remove + install');
101
+ assert.equal(loadSettings().timeout, 17, 'settings survive the rename');
102
+ assert.equal(loadSettings().fieldnotes, false);
103
+ assert.equal(loadCreatedPanes()[0].ownerSession, 'ses-old-install', 'herd survives the rename');
104
+ assert.match(
105
+ fs.readFileSync(settingsFile, 'utf8'),
106
+ /"timeout":17/,
107
+ 'frozen user config file was not rewritten'
108
+ );
109
+ console.log('PASS remove + new install keeps settings and herd intact (SC-005)');
110
+
111
+ console.log('\nAll rename assertions passed.');
@@ -0,0 +1,379 @@
1
+ #!/usr/bin/env node
2
+ import assert from 'node:assert/strict';
3
+ import {
4
+ formatExpandedToolResult,
5
+ formatParentMessageNotification,
6
+ formatCollapsedNotification,
7
+ renderCollapsedLifecycleResult,
8
+ formatStaleWaitNotification,
9
+ formatWatcherNotification,
10
+ styleExpandedToolResult,
11
+ } from '../src/extension/shepherd.ts';
12
+
13
+ const spawnResult = {
14
+ content: [{ type: 'text', text: 'shepherd_spawn spawned worker: code review' }],
15
+ details: {
16
+ call: {
17
+ name: 'shepherd_spawn',
18
+ arguments: {
19
+ agent: 'worker',
20
+ label: 'code review',
21
+ placement: 'tab',
22
+ },
23
+ },
24
+ id: 'shepherd-agent-123',
25
+ agent: 'worker',
26
+ label: 'code review',
27
+ model: 'github-copilot/gpt-5.6-luna',
28
+ returnValue: {
29
+ id: 'shepherd-agent-123',
30
+ agent: 'worker',
31
+ label: 'code review',
32
+ model: 'github-copilot/gpt-5.6-luna',
33
+ },
34
+ fieldnote: '.shepherd/sessions/secret',
35
+ artifactSession: { parentSessionId: 'secret' },
36
+ returnCode: 0,
37
+ },
38
+ };
39
+ assert.equal(
40
+ formatExpandedToolResult(spawnResult),
41
+ [
42
+ 'call',
43
+ 'agent: worker',
44
+ 'label: code review',
45
+ 'placement: tab',
46
+ '',
47
+ 'return',
48
+ 'status: spawned',
49
+ 'agent id: shepherd-agent-123',
50
+ 'model: github-copilot/gpt-5.6-luna',
51
+ ].join('\n'),
52
+ 'spawn expanded output uses minimal headers, spacing, and curated return fields'
53
+ );
54
+ console.log('PASS spawn expanded output has minimal spaced call/return sections');
55
+
56
+ const plainTheme = {
57
+ fg: (_color, text) => text,
58
+ bold: text => text,
59
+ };
60
+ const collapsedStatus = renderCollapsedLifecycleResult(
61
+ {
62
+ content: [{ type: 'text', text: 'agent done.\n\ncall:\n shepherd_status {}' }],
63
+ details: { call: { name: 'shepherd_status' }, returnCode: 0 },
64
+ },
65
+ 'shepherd_status',
66
+ plainTheme,
67
+ {}
68
+ );
69
+ assert.equal(collapsedStatus, 'agent done.');
70
+ console.log('PASS collapsed status results hide protocol call/return/details text');
71
+
72
+ const expandedStatus = formatExpandedToolResult({
73
+ content: [{ type: 'text', text: 'agent working; task shepherd-task-status running.' }],
74
+ details: {
75
+ call: { name: 'shepherd_status', arguments: { id: 'shepherd-agent-status' } },
76
+ returnValue: {
77
+ id: 'shepherd-agent-status',
78
+ state: 'working',
79
+ task: { id: 'shepherd-task-status', state: 'running' },
80
+ },
81
+ status: {
82
+ id: 'shepherd-agent-status',
83
+ state: 'working',
84
+ task: { id: 'shepherd-task-status', state: 'running' },
85
+ },
86
+ returnCode: 0,
87
+ },
88
+ });
89
+ assert.equal(
90
+ expandedStatus,
91
+ [
92
+ 'call',
93
+ 'id: shepherd-agent-status',
94
+ '',
95
+ 'return',
96
+ 'status: working',
97
+ 'task:',
98
+ ' id: shepherd-task-status',
99
+ ' state: running',
100
+ ].join('\n')
101
+ );
102
+ console.log('PASS expanded status results remove duplicated status metadata');
103
+
104
+ const expandedCompletedWatch = formatExpandedToolResult({
105
+ content: [{ type: 'text', text: 'watch completed' }],
106
+ details: {
107
+ call: { name: 'shepherd_watch', arguments: { id: 'shepherd-task-123' } },
108
+ returnValue: {
109
+ watcherId: 'shepherd-watcher-123',
110
+ pending: [],
111
+ completed: [
112
+ {
113
+ taskId: 'shepherd-task-123',
114
+ agentId: 'shepherd-agent-123',
115
+ status: 'completed',
116
+ returnCode: 0,
117
+ text: 'First line\nSecond line',
118
+ artifact: { id: 'large/session-note.md', task: 'omit this metadata' },
119
+ },
120
+ ],
121
+ },
122
+ returnCode: 0,
123
+ },
124
+ });
125
+ assert.match(expandedCompletedWatch, /completions:\n/);
126
+ assert.match(expandedCompletedWatch, /text:\nFirst line\nSecond line/);
127
+ assert.doesNotMatch(expandedCompletedWatch, /omit this metadata|artifact:/);
128
+ console.log(
129
+ 'PASS expanded completed watcher results omit artifact metadata and preserve text blocks'
130
+ );
131
+
132
+ const collapsedHerd = renderCollapsedLifecycleResult(
133
+ {
134
+ content: [
135
+ { type: 'text', text: '• pi (self/focused) ●(shepherd) [working] pane=w1:p1 cwd=/private' },
136
+ ],
137
+ details: {
138
+ call: { name: 'shepherd' },
139
+ agents: [
140
+ {
141
+ name: 'pi',
142
+ state: 'working',
143
+ focused: true,
144
+ shepherd: true,
145
+ paneId: 'w1:p1',
146
+ cwd: '/private',
147
+ },
148
+ ],
149
+ returnCode: 0,
150
+ },
151
+ },
152
+ 'shepherd',
153
+ plainTheme,
154
+ {}
155
+ );
156
+ assert.equal(collapsedHerd, 'Active agents: 1');
157
+ assert.doesNotMatch(collapsedHerd, /pane=|cwd=|pi \(self\/focused\)/);
158
+ console.log('PASS collapsed herd results show only the active-agent count');
159
+
160
+ const collapsedAgents = renderCollapsedLifecycleResult(
161
+ {
162
+ content: [
163
+ {
164
+ type: 'text',
165
+ text: 'Available agent names (copy the name exactly; names are case-sensitive):',
166
+ },
167
+ ],
168
+ details: {
169
+ call: { name: 'shepherd' },
170
+ scope: 'both',
171
+ agents: [
172
+ { name: 'planner', description: 'Creates plans' },
173
+ { name: 'reviewer', description: 'Reviews code' },
174
+ { name: 'worker', description: 'Does work' },
175
+ ],
176
+ returnCode: 0,
177
+ },
178
+ },
179
+ 'shepherd',
180
+ plainTheme,
181
+ {}
182
+ );
183
+ assert.equal(collapsedAgents, 'Available agents: planner, reviewer, worker');
184
+ const styledCollapsedAgents = renderCollapsedLifecycleResult(
185
+ {
186
+ content: [{ type: 'text', text: 'Available agent names:' }],
187
+ details: {
188
+ call: { name: 'shepherd' },
189
+ scope: 'both',
190
+ agents: [{ name: 'planner' }],
191
+ returnCode: 0,
192
+ },
193
+ },
194
+ 'shepherd',
195
+ {
196
+ bold: text => `<bold>${text}</bold>`,
197
+ fg: (color, text) => `<${color}>${text}</${color}>`,
198
+ },
199
+ {}
200
+ );
201
+ assert.equal(
202
+ styledCollapsedAgents,
203
+ '<accent>Available agents:</accent> <toolOutput>planner</toolOutput>'
204
+ );
205
+ console.log('PASS collapsed available-agent labels use accent styling');
206
+
207
+ const expandedHerd = formatExpandedToolResult({
208
+ content: [{ type: 'text', text: '• pi (self/focused) [working]' }],
209
+ details: {
210
+ call: { name: 'shepherd', arguments: { agentScope: 'both' } },
211
+ agents: [
212
+ { name: 'pi', state: 'working', focused: true, shepherd: true },
213
+ { name: 'pi', state: 'idle', focused: false, shepherd: false },
214
+ ],
215
+ returnCode: 0,
216
+ },
217
+ });
218
+ assert.match(expandedHerd, /agents:\n agent id: shepherd\n state: working/);
219
+ assert.doesNotMatch(expandedHerd, /\n\s+- /);
220
+ assert.doesNotMatch(expandedHerd, /paneId|cwd/);
221
+ console.log('PASS expanded herd arrays keep each item marker beside its first field');
222
+
223
+ const spawnWithoutOptionalPlacement = structuredClone(spawnResult);
224
+ delete spawnWithoutOptionalPlacement.details.call.arguments.placement;
225
+ assert.doesNotMatch(
226
+ formatExpandedToolResult(spawnWithoutOptionalPlacement),
227
+ /placement:/,
228
+ 'absent optional spawn placement is omitted'
229
+ );
230
+ console.log('PASS optional call arguments are omitted when absent');
231
+
232
+ const messageResult = {
233
+ content: [{ type: 'text', text: 'Message queued to worker' }],
234
+ details: {
235
+ call: {
236
+ name: 'shepherd_message',
237
+ arguments: {
238
+ target: 'shepherd-agent-123',
239
+ message: 'First line\nStatus: pending\nThird line',
240
+ },
241
+ },
242
+ returnValue: {
243
+ messageId: 'shepherd-message-123',
244
+ accepted: true,
245
+ delivery: 'queued',
246
+ },
247
+ returnCode: 0,
248
+ },
249
+ };
250
+ const messageExpanded = formatExpandedToolResult(messageResult);
251
+ assert.match(
252
+ messageExpanded,
253
+ /call\ntarget: shepherd-agent-123\nmessage:\nFirst line\nStatus: pending\nThird line\n\nreturn\nstatus: queued/
254
+ );
255
+ console.log('PASS multiline message content uses a raw copy-friendly block');
256
+
257
+ const theme = {
258
+ bold: text => `<bold>${text}</bold>`,
259
+ fg: (color, text) => `<${color}>${text}</${color}>`,
260
+ };
261
+ const styledMessage = styleExpandedToolResult(messageExpanded, theme);
262
+ assert.match(styledMessage, /<accent>message:<\/accent>/);
263
+ assert.match(styledMessage, /<toolOutput>Status: pending<\/toolOutput>/);
264
+ assert.doesNotMatch(styledMessage, /<accent>Status:/);
265
+ assert.match(styledMessage, /<bold>call<\/bold>/);
266
+ assert.match(styledMessage, /<bold>return<\/bold>/);
267
+ console.log('PASS raw message lines stay normal while headers and labels are styled');
268
+
269
+ const longSingleLine =
270
+ 'A long single-line message that should wrap naturally in the terminal without introducing explicit line breaks.';
271
+ const longMessage = formatExpandedToolResult({
272
+ content: [{ type: 'text', text: 'Message queued to worker' }],
273
+ details: {
274
+ call: {
275
+ name: 'shepherd_message',
276
+ arguments: { target: 'shepherd-agent-123', message: longSingleLine },
277
+ },
278
+ returnValue: { messageId: 'shepherd-message-long', delivery: 'queued' },
279
+ returnCode: 0,
280
+ },
281
+ });
282
+ assert.match(
283
+ longMessage,
284
+ new RegExp(`message:\\n${longSingleLine.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\n\\nreturn`)
285
+ );
286
+ console.log('PASS long single-line messages stay single-line in the raw block');
287
+
288
+ const parentMessage = formatParentMessageNotification({
289
+ kind: 'reply',
290
+ senderId: 'shepherd-agent-123',
291
+ messageId: 'shepherd-message-123',
292
+ taskId: 'shepherd-task-123',
293
+ threadId: 'shepherd-message-001',
294
+ replyTo: 'shepherd-message-000',
295
+ content: 'Reply line one\nReply line two',
296
+ });
297
+ assert.match(parentMessage, /^Shepherd reply from shepherd-agent-123\n\nmessage id:/);
298
+ assert.match(
299
+ parentMessage,
300
+ /reply to: shepherd-message-000\n\nmessage:\nReply line one\nReply line two/
301
+ );
302
+ assert.doesNotMatch(parentMessage, /\ncall:\n|\nreturn:\n|\ndetails:/);
303
+ const styledParentMessage = styleExpandedToolResult(parentMessage, theme, {
304
+ boldFields: ['message'],
305
+ });
306
+ assert.match(styledParentMessage, /<bold>message:<\/bold>/);
307
+ assert.match(styledParentMessage, /<accent>message id:<\/accent>/);
308
+ console.log('PASS incoming replies use spacious metadata and a bold message label');
309
+ const collapsedReply = formatCollapsedNotification(
310
+ {
311
+ details: {
312
+ messageId: 'shepherd-message-123',
313
+ senderId: 'shepherd-agent-123',
314
+ content: 'Reply line one\nReply line two',
315
+ },
316
+ },
317
+ parentMessage
318
+ );
319
+ assert.equal(
320
+ collapsedReply,
321
+ 'Shepherd reply from shepherd-agent-123\nReply line one Reply line two'
322
+ );
323
+ const collapsedLongReply = formatCollapsedNotification(
324
+ {
325
+ details: {
326
+ messageId: 'shepherd-message-long',
327
+ content: 'A very long message '.repeat(20),
328
+ },
329
+ },
330
+ parentMessage
331
+ );
332
+ assert.equal(collapsedLongReply.split('\n').length, 2);
333
+ assert.ok(collapsedLongReply.split('\n')[1].endsWith('…'));
334
+ assert.ok(collapsedLongReply.split('\n')[1].length <= 160);
335
+ console.log('PASS collapsed incoming replies show a concise sender and message summary');
336
+
337
+ const watcher = formatWatcherNotification(
338
+ {
339
+ watcherId: 'shepherd-watcher-123',
340
+ taskIds: ['shepherd-task-123'],
341
+ completions: [
342
+ {
343
+ taskId: 'shepherd-task-123',
344
+ agentId: 'shepherd-agent-123',
345
+ status: 'completed',
346
+ text: 'Finished the task.\nSecond line of the result.',
347
+ returnCode: 0,
348
+ artifact: { id: 'session/worker-01.md', task: 'large durable metadata' },
349
+ },
350
+ ],
351
+ },
352
+ 'task'
353
+ );
354
+ assert.match(watcher, /^Shepherd watcher/);
355
+ assert.match(watcher, /watcher id: shepherd-watcher-123/);
356
+ assert.match(watcher, /completions:/);
357
+ assert.match(watcher, /text:\nFinished the task\.\nSecond line of the result\./);
358
+ assert.doesNotMatch(watcher, /large durable metadata|artifact:/);
359
+ assert.doesNotMatch(watcher, /\ncall:\n|\nreturn:\n|\ndetails:/);
360
+ console.log('PASS watcher notifications use structured human-readable fields');
361
+
362
+ const stale = formatStaleWaitNotification({
363
+ taskId: 'shepherd-task-123',
364
+ agentId: 'shepherd-agent-123',
365
+ agent: 'worker',
366
+ label: 'code review',
367
+ elapsedMs: 61000,
368
+ thresholdMinutes: 1,
369
+ description: 'Review the implementation.',
370
+ question: 'Should the notification be reformatted?',
371
+ requestMessageId: 'shepherd-message-000',
372
+ recipientName: 'planner',
373
+ });
374
+ assert.match(stale, /^Shepherd stale wait/);
375
+ assert.match(stale, /question:\nShould the notification be reformatted\?/);
376
+ assert.match(stale, /actions:\n/);
377
+ console.log('PASS stale-wait notifications use readable raw question/action blocks');
378
+
379
+ console.log('All rendering assertions passed.');