@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,181 @@
1
+ #!/usr/bin/env node
2
+ import assert from 'node:assert/strict';
3
+ import { LifecycleRegistry } from '../src/core/orchestration.ts';
4
+ import { PromptWatcherService, promptWatcherService } from '../src/core/lifecycle.ts';
5
+ import { lifecycleRegistry } from '../src/core/orchestration.ts';
6
+ import { registerShepherdTools } from '../src/extension/shepherd.ts';
7
+
8
+ const registry = new LifecycleRegistry();
9
+ const agent = registry.registerAgent({ agent: 'worker', label: 'watch test' });
10
+ const first = registry.createPrompt(agent);
11
+ const events = [];
12
+ const service = new PromptWatcherService(registry, event => events.push(event), 5, 5);
13
+
14
+ const registration = service.watch(first.id);
15
+ assert.equal(registration.promptIds.length, 1);
16
+ assert.deepEqual(registration.pending, [first.id]);
17
+ assert.deepEqual(registration.completed, []);
18
+ registry.settlePrompt(first, {
19
+ promptId: first.id,
20
+ agentId: first.agentId,
21
+ status: 'done',
22
+ ok: true,
23
+ text: 'finished',
24
+ });
25
+ await new Promise(resolve => setTimeout(resolve, 20));
26
+ assert.equal(events.length, 1, 'settlement produces one notification');
27
+ assert.equal(events[0].watcherId, registration.watcherId);
28
+ assert.equal(events[0].completions[0].promptId, first.id);
29
+ assert.equal(events[0].completions[0].agentId, agent.id);
30
+ assert.equal(events[0].completions[0].label, 'watch test');
31
+ assert.equal(events[0].completions[0].text, 'finished');
32
+ assert.equal(events[0].completions[0].returnCode, 0);
33
+
34
+ // A completion that predates registration is returned immediately, not sent
35
+ // again as an asynchronous duplicate.
36
+ const completedRegistration = service.watch(first.id);
37
+ assert.deepEqual(
38
+ completedRegistration.completed.map(result => result.promptId),
39
+ [first.id]
40
+ );
41
+ await new Promise(resolve => setTimeout(resolve, 10));
42
+ assert.equal(events.length, 1, 'already-settled prompt is not duplicated');
43
+
44
+ const second = registry.createPrompt(agent);
45
+ const thirdAgent = registry.registerAgent({ agent: 'scout' });
46
+ const third = registry.createPrompt(thirdAgent);
47
+ const arrayRegistration = service.watch([second.id, third.id]);
48
+ assert.deepEqual(arrayRegistration.pending, [second.id, third.id]);
49
+ registry.settlePrompt(third, {
50
+ promptId: third.id,
51
+ agentId: third.agentId,
52
+ status: 'failed',
53
+ ok: false,
54
+ error: 'nope',
55
+ });
56
+ registry.settlePrompt(second, {
57
+ promptId: second.id,
58
+ agentId: second.agentId,
59
+ status: 'blocked',
60
+ ok: false,
61
+ });
62
+ await new Promise(resolve => setTimeout(resolve, 20));
63
+ const arrayEvent = events.find(event => event.watcherId === arrayRegistration.watcherId);
64
+ assert.ok(arrayEvent, 'array watcher receives a completion notification');
65
+ assert.deepEqual(
66
+ arrayEvent.completions.map(result => result.promptId),
67
+ [second.id, third.id],
68
+ 'coalesced completions preserve watch input order'
69
+ );
70
+ assert.equal(arrayEvent.completions[0].returnCode, 2);
71
+ assert.equal(arrayEvent.completions[1].returnCode, 1);
72
+
73
+ service.shutdown();
74
+
75
+ // The extension bridge sends a custom follow-up, never a synthetic user
76
+ // message, and preserves structured completion details.
77
+ const sent = [];
78
+ let registeredMessageRenderer;
79
+ let registeredReplyRenderer;
80
+ registerShepherdTools({
81
+ registerTool() {},
82
+ registerMessageRenderer(customType, renderer) {
83
+ assert.ok(
84
+ [
85
+ 'shepherd.prompt.completion',
86
+ 'shepherd.task.completion',
87
+ 'shepherd.message.incoming',
88
+ 'shepherd.message.reply',
89
+ 'shepherd.message.warning',
90
+ 'shepherd.stale.wait',
91
+ ].includes(customType),
92
+ 'unexpected custom message renderer: ' + customType
93
+ );
94
+ if (customType === 'shepherd.prompt.completion') registeredMessageRenderer = renderer;
95
+ if (customType === 'shepherd.message.reply') registeredReplyRenderer = renderer;
96
+ },
97
+ sendMessage(message, options) {
98
+ sent.push({ message, options });
99
+ },
100
+ });
101
+ const bridgeAgent = lifecycleRegistry.registerAgent({ agent: 'planner', label: 'bridge' });
102
+ const bridgePrompt = lifecycleRegistry.createPrompt(bridgeAgent);
103
+ promptWatcherService.watch(bridgePrompt.id);
104
+ lifecycleRegistry.settlePrompt(bridgePrompt, {
105
+ promptId: bridgePrompt.id,
106
+ agentId: bridgePrompt.agentId,
107
+ status: 'done',
108
+ ok: true,
109
+ text: 'bridge result',
110
+ });
111
+ await new Promise(resolve => setTimeout(resolve, 40));
112
+ assert.equal(sent.length, 1, 'bridge sends one custom completion message');
113
+ assert.equal(typeof registeredMessageRenderer, 'function');
114
+ const renderedNotification = registeredMessageRenderer(
115
+ sent[0].message,
116
+ { expanded: false, outputPad: 0 },
117
+ { fg: (_color, text) => text, bold: text => text, bg: (_color, text) => text }
118
+ );
119
+ const renderedLines = renderedNotification.render(200).map(line => line.trimEnd());
120
+ assert.ok(renderedLines.some(line => line.includes(`shepherd_watch ${bridgePrompt.id}`)));
121
+ assert.ok(renderedLines.some(line => line.includes('✓ success')));
122
+ assert.equal(
123
+ renderedLines.some(line => line.includes('watcher id:')),
124
+ false
125
+ );
126
+ assert.equal(
127
+ renderedLines.some(line => line.includes('completions:')),
128
+ false
129
+ );
130
+ assert.equal(
131
+ renderedLines.some(line => /^(call:|return:|details:)$/.test(line)),
132
+ false
133
+ );
134
+ const expandedNotification = registeredMessageRenderer(
135
+ sent[0].message,
136
+ { expanded: true, outputPad: 0 },
137
+ { fg: (_color, text) => text, bold: text => text, bg: (_color, text) => text }
138
+ );
139
+ const expandedLines = expandedNotification.render(200).map(line => line.trimEnd());
140
+ assert.ok(expandedLines.includes('Shepherd watcher'));
141
+ assert.ok(
142
+ expandedLines.some(line => line.includes(`watcher id: ${sent[0].message.details.watcherId}`))
143
+ );
144
+ assert.ok(expandedLines.some(line => line.includes('completions:')));
145
+ assert.equal(sent[0].message.customType, 'shepherd.prompt.completion');
146
+ assert.equal(typeof registeredReplyRenderer, 'function');
147
+ const expandedReply = registeredReplyRenderer(
148
+ {
149
+ customType: 'shepherd.message.reply',
150
+ details: {
151
+ kind: 'reply',
152
+ messageId: 'shepherd-message-rendering',
153
+ senderId: bridgeAgent.id,
154
+ content: 'Reply text',
155
+ },
156
+ },
157
+ { expanded: true, outputPad: 0 },
158
+ {
159
+ fg: (color, text) => `<${color}>${text}</${color}>`,
160
+ bold: text => `<bold>${text}</bold>`,
161
+ bg: (_color, text) => text,
162
+ }
163
+ );
164
+ const expandedReplyText = expandedReply.render(200).join('\n');
165
+ assert.match(
166
+ expandedReplyText,
167
+ /<toolTitle><bold>Shepherd<\/bold><\/toolTitle> <accent>reply from planner: bridge<\/accent>/
168
+ );
169
+ assert.doesNotMatch(expandedReplyText, /<bold>Shepherd reply from planner/);
170
+ assert.equal(sent[0].message.details.completions[0].promptId, bridgePrompt.id);
171
+ assert.equal(sent[0].message.details.completions[0].agentId, bridgeAgent.id);
172
+ const notificationFirstLine = sent[0].message.content.split('\n')[0];
173
+ assert.equal(notificationFirstLine, 'shepherd_watcher completion: planner: bridge done');
174
+ assert.doesNotMatch(notificationFirstLine, /shepherd-(?:watch|prompt)-/);
175
+ assert.equal(sent[0].message.content, 'shepherd_watcher completion: planner: bridge done');
176
+ assert.doesNotMatch(sent[0].message.content, /\nreturn:\n/);
177
+ assert.ok(Array.isArray(sent[0].message.details.completions));
178
+ assert.doesNotMatch(sent[0].message.content, /\ncall:\n|\nreturn:\n|\ndetails:/);
179
+ assert.deepEqual(sent[0].options, { deliverAs: 'steer', triggerTurn: true });
180
+ promptWatcherService.shutdown();
181
+ console.log('All watcher assertions passed.');