@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,194 @@
1
+ #!/usr/bin/env node
2
+ /** Phase 1 verification for tracked task records and state transitions. */
3
+ import assert from 'node:assert/strict';
4
+ import { LifecycleError, LifecycleRegistry } from '../src/core/orchestration.ts';
5
+ import { createManualClock, withFakeDateNow } from './helpers/fake-clock.mjs';
6
+
7
+ const registry = new LifecycleRegistry();
8
+ const scout = registry.registerAgent({ agent: 'scout', label: 'task registry' });
9
+ const planner = registry.registerAgent({ agent: 'planner', label: 'task registry' });
10
+ const worker = registry.registerAgent({ agent: 'worker', label: 'task registry' });
11
+
12
+ function expectLifecycleError(fn, code, label) {
13
+ assert.throws(fn, error => {
14
+ assert.ok(error instanceof LifecycleError, `${label}: expected LifecycleError`);
15
+ assert.equal(error.code, code, `${label}: error code`);
16
+ return true;
17
+ });
18
+ console.log(`PASS ${label}`);
19
+ }
20
+
21
+ const task = registry.createTask(scout, 'Investigate the authentication flow.');
22
+ assert.match(task.id, /^shepherd-task-/);
23
+ assert.equal(task.agentId, scout.id);
24
+ assert.equal(registry.getTask(task.id).state, 'created');
25
+ assert.equal(registry.canonicalTaskHandle(task.id).id, task.id);
26
+ assert.equal(registry.taskResult(task.id), undefined);
27
+ console.log('PASS task creation returns a session-scoped opaque task id');
28
+
29
+ expectLifecycleError(
30
+ () => registry.getTask(JSON.stringify(task)),
31
+ 'unknown_task',
32
+ 'quoted task object is rejected'
33
+ );
34
+ expectLifecycleError(
35
+ () => registry.getTask('not-a-task'),
36
+ 'unknown_task',
37
+ 'unknown task id is rejected'
38
+ );
39
+ expectLifecycleError(
40
+ () => registry.createTask(scout, 'A second task'),
41
+ 'active_task',
42
+ 'one active task per agent is enforced'
43
+ );
44
+ expectLifecycleError(
45
+ () => registry.createTask(planner, ' '),
46
+ 'invalid_task',
47
+ 'empty task descriptions are rejected'
48
+ );
49
+
50
+ const taskWithDeadline = registry.createTask(planner, 'Deadline task', { timeoutMs: 30_000 });
51
+ assert.equal(taskWithDeadline.agentId, planner.id);
52
+ assert.equal(registry.getTask(taskWithDeadline.id).deadlineAt, taskWithDeadline.createdAt + 30_000);
53
+ console.log('PASS task deadlines are recorded at creation');
54
+ const artifactSession = { sessionPath: '/tmp/session', mocPath: '/tmp/shepherd.md' };
55
+ const artifact = {
56
+ id: 'artifact-1',
57
+ filePath: '/tmp/session/worker.md',
58
+ relativePath: '.shepherd/worker.md',
59
+ };
60
+ registry.attachTaskArtifact(taskWithDeadline.id, artifactSession, artifact);
61
+ assert.equal(registry.taskArtifact(taskWithDeadline.id).artifact.id, 'artifact-1');
62
+ assert.equal(registry.getTask(taskWithDeadline.id).artifactSession.sessionPath, '/tmp/session');
63
+ console.log('PASS task records retain artifact associations independently of settlement');
64
+
65
+ registry.setTaskRunning(task.id);
66
+ assert.equal(registry.getTask(task.id).state, 'running');
67
+ assert.ok(registry.getTask(task.id).startedAt);
68
+ console.log('PASS created task transitions to running');
69
+
70
+ expectLifecycleError(
71
+ () => registry.setTaskWaiting(task.id),
72
+ 'invalid_transition',
73
+ 'task cannot wait without a pending request'
74
+ );
75
+ registry.addPendingRequest(task.id, 'request-one');
76
+ registry.addPendingRequest(task.id, 'request-two');
77
+ assert.deepEqual(registry.getTask(task.id).pendingRequestIds, ['request-one', 'request-two']);
78
+ registry.setTaskWaiting(task.id);
79
+ const waiting = registry.getTask(task.id);
80
+ assert.equal(waiting.state, 'waiting');
81
+ assert.ok(waiting.waitingSince);
82
+ assert.equal(waiting.pendingRequestIds.length, 2);
83
+ console.log('PASS running task enters waiting with pending requests and wait timestamp');
84
+
85
+ // The process/agent can become idle while the task remains waiting. This is
86
+ // the boundary that prevents future task watchers from copying prompt idle
87
+ // inference into the tracked-task protocol.
88
+ registry.setAgentState(scout, 'idle');
89
+ assert.equal(registry.status(scout).state, 'idle');
90
+ assert.equal(registry.getTask(task.id).state, 'waiting');
91
+ assert.equal(registry.taskResult(task.id), undefined);
92
+ console.log('PASS idle agent state does not settle a waiting task');
93
+ expectLifecycleError(
94
+ () => registry.setTaskRunning(task.id),
95
+ 'invalid_transition',
96
+ 'waiting task cannot resume while requests remain pending'
97
+ );
98
+
99
+ registry.markTaskStaleNotified(task.id, 12_345);
100
+ assert.equal(registry.getTask(task.id).staleNotifiedAt, 12_345);
101
+ registry.clearTaskStaleNotification(task.id);
102
+ assert.equal(registry.getTask(task.id).staleNotifiedAt, undefined);
103
+ console.log('PASS stale-notification tracking is separate from task settlement');
104
+
105
+ registry.resolvePendingRequest(task.id, 'request-one');
106
+ assert.equal(registry.getTask(task.id).state, 'waiting');
107
+ assert.deepEqual(registry.getTask(task.id).pendingRequestIds, ['request-two']);
108
+ registry.resolvePendingRequest(task.id, 'request-two');
109
+ assert.equal(registry.getTask(task.id).state, 'running');
110
+ assert.equal(registry.getTask(task.id).waitingSince, undefined);
111
+ console.log('PASS task resumes only after all pending requests resolve');
112
+
113
+ const clock = createManualClock(100_000);
114
+ await withFakeDateNow(clock.now(), async controlled => {
115
+ const clocked = registry.createTask(worker, 'Task with controlled timestamps');
116
+ registry.setTaskRunning(clocked.id);
117
+ registry.addPendingRequest(clocked.id, 'clock-request');
118
+ controlled.advance(1_500);
119
+ registry.setTaskWaiting(clocked.id);
120
+ assert.equal(registry.getTask(clocked.id).waitingSince, 101_500);
121
+ registry.settleTask(clocked.id, { status: 'cancelled', error: 'test cleanup' });
122
+ });
123
+ console.log('PASS task timestamps use the injected test clock boundary');
124
+
125
+ expectLifecycleError(
126
+ () => registry.settleTaskForAgent(task.id, planner, { status: 'completed' }),
127
+ 'task_agent_mismatch',
128
+ 'foreign agent cannot complete another agent task'
129
+ );
130
+ assert.equal(registry.assertTaskOwner(task.id, scout).taskId, task.id);
131
+ console.log('PASS task ownership is checked before lifecycle completion');
132
+
133
+ const completed = registry.settleTask(task.id, {
134
+ status: 'completed',
135
+ text: 'Authentication flow documented.',
136
+ completedAt: 200_000,
137
+ });
138
+ assert.equal(completed.ok, true);
139
+ assert.equal(completed.returnCode, 0);
140
+ assert.equal(completed.status, 'completed');
141
+ assert.equal(registry.getTask(task.id).state, 'completed');
142
+ assert.deepEqual(registry.getTask(task.id).pendingRequestIds, []);
143
+ assert.equal(registry.activeTaskForAgent(scout), undefined);
144
+ console.log('PASS task settlement clears requests and releases the active slot');
145
+
146
+ const duplicate = registry.settleTask(task.id, {
147
+ status: 'failed',
148
+ error: 'must not replace the first result',
149
+ });
150
+ assert.deepEqual(duplicate, completed);
151
+ console.log('PASS terminal task settlement is idempotent');
152
+
153
+ expectLifecycleError(
154
+ () => registry.setTaskRunning(task.id),
155
+ 'invalid_transition',
156
+ 'terminal task cannot become running'
157
+ );
158
+ expectLifecycleError(
159
+ () => registry.markTaskStaleNotified(task.id),
160
+ 'invalid_transition',
161
+ 'terminal task cannot be marked waiting/stale'
162
+ );
163
+
164
+ registry.setTaskRunning(taskWithDeadline.id);
165
+ const cancelled = registry.cancelTask(planner, 'Planner closed before completing the task.');
166
+ assert.equal(cancelled.status, 'cancelled');
167
+ assert.equal(cancelled.returnCode, 130);
168
+ assert.equal(registry.getTask(taskWithDeadline.id).state, 'cancelled');
169
+ console.log('PASS cancelling an agent task produces a cancelled terminal result');
170
+
171
+ const timeoutTask = registry.createTask(worker, 'Task that times out');
172
+ registry.setTaskRunning(timeoutTask.id);
173
+ const timedOut = registry.settleTask(timeoutTask.id, {
174
+ status: 'timed_out',
175
+ error: 'deadline reached',
176
+ });
177
+ assert.equal(timedOut.ok, false);
178
+ assert.equal(timedOut.returnCode, 124);
179
+ console.log('PASS timed-out task receives the standard timeout return code');
180
+
181
+ const blockedTask = registry.createTask(planner, 'Blocked task');
182
+ registry.setTaskRunning(blockedTask.id);
183
+ const blocked = registry.settleTask(blockedTask.id, { status: 'blocked', text: 'Needs input.' });
184
+ assert.equal(blocked.ok, false);
185
+ assert.equal(blocked.returnCode, 2);
186
+ assert.equal(registry.status(planner).state, 'blocked');
187
+ console.log('PASS blocked task receives the standard blocked result');
188
+
189
+ const snapshots = registry.allTasks();
190
+ assert.ok(snapshots.some(record => record.taskId === task.id && record.state === 'completed'));
191
+ assert.ok(snapshots.every(record => Array.isArray(record.pendingRequestIds)));
192
+ console.log('PASS task listing returns JSON-safe task snapshots');
193
+
194
+ console.log('All task registry assertions passed.');
@@ -0,0 +1,217 @@
1
+ #!/usr/bin/env node
2
+ /** Phase 7 verification for task-aware, non-blocking one-shot watchers. */
3
+ import assert from 'node:assert/strict';
4
+ import { LifecycleRegistry, LifecycleError } from '../src/core/orchestration.ts';
5
+ import { TaskWatcherService, taskWatcherService } from '../src/core/lifecycle.ts';
6
+ import { lifecycleRegistry } from '../src/core/orchestration.ts';
7
+ import { registerShepherdTools, setTaskWatcherSessionActive } from '../src/extension/shepherd.ts';
8
+
9
+ // ── Core registry + TaskWatcherService ─────────────────────────────────
10
+ const registry = new LifecycleRegistry();
11
+ const worker = registry.registerAgent({ agent: 'worker', label: 'watcher-worker' });
12
+ const planner = registry.registerAgent({ agent: 'planner', label: 'watcher-planner' });
13
+ const scout = registry.registerAgent({ agent: 'scout', label: 'watcher-scout' });
14
+
15
+ const events = [];
16
+ const service = new TaskWatcherService(registry, event => events.push(event), 5);
17
+
18
+ const taskA = registry.createTask(worker, 'A');
19
+ const taskB = registry.createTask(planner, 'B');
20
+ const taskC = registry.createTask(scout, 'C');
21
+
22
+ // Pending task registration returns synchronously; nothing is delivered yet.
23
+ const regA = service.watch(taskA.id);
24
+ assert.equal(regA.pending.length, 1);
25
+ assert.deepEqual(regA.completed, []);
26
+ assert.equal(regA.taskIds[0], taskA.id);
27
+ console.log('PASS a pending task registers non-blocking and returns immediately');
28
+
29
+ // Entering `waiting` must NOT fire the watcher (only settlement does).
30
+ registry.setTaskRunning(taskA.id);
31
+ registry.addPendingRequest(taskA.id, 'request-x');
32
+ registry.setTaskWaiting(taskA.id);
33
+ await new Promise(resolve => setTimeout(resolve, 15));
34
+ assert.ok(
35
+ !events.some(e => e.completions.some(c => c.taskId === taskA.id)),
36
+ 'waiting state is not a watcher completion'
37
+ );
38
+ console.log('PASS a task entering waiting does not complete its watcher');
39
+
40
+ // No watcher delivery until an explicit settlement.
41
+ assert.equal(events.length, 0);
42
+ console.log('PASS no completion is delivered while the task is still running/waiting');
43
+
44
+ // Settling fires exactly one notification enriched with agent identity.
45
+ registry.settleTask(taskA.id, { status: 'completed', text: 'done A', ok: true });
46
+ await new Promise(resolve => setTimeout(resolve, 20));
47
+ const aEvents = events.filter(e => e.completions.some(c => c.taskId === taskA.id));
48
+ assert.equal(aEvents.length, 1, 'exactly one notification for a settled task');
49
+ const aCompletion = aEvents[0].completions.find(c => c.taskId === taskA.id);
50
+ assert.equal(aCompletion.status, 'completed');
51
+ assert.equal(aCompletion.ok, true);
52
+ assert.equal(aCompletion.returnCode, 0);
53
+ assert.equal(aCompletion.text, 'done A');
54
+ assert.equal(aCompletion.agentId, worker.id);
55
+ assert.equal(aCompletion.agent, 'worker');
56
+ assert.equal(aCompletion.label, 'watcher-worker');
57
+ console.log('PASS a completed task produces one terminal notification with agent + text');
58
+
59
+ // Already-settled task returns immediately and is not delivered again.
60
+ const regA2 = service.watch(taskA.id);
61
+ assert.equal(regA2.pending.length, 0);
62
+ assert.equal(regA2.completed.length, 1);
63
+ await new Promise(resolve => setTimeout(resolve, 10));
64
+ assert.equal(
65
+ events.filter(e => e.completions.some(c => c.taskId === taskA.id)).length,
66
+ 1,
67
+ 'already-settled task is not re-delivered'
68
+ );
69
+ console.log('PASS an already-completed task returns immediately and is not duplicated');
70
+
71
+ // Multiple task ids in one watcher; coalesced completions preserve input order.
72
+ const regAB = service.watch([taskB.id, taskC.id]);
73
+ assert.deepEqual(
74
+ regAB.pending.map(id => id),
75
+ [taskB.id, taskC.id]
76
+ );
77
+ registry.setTaskRunning(taskB.id);
78
+ registry.setTaskRunning(taskC.id);
79
+ registry.settleTask(taskC.id, { status: 'failed', error: 'boom', ok: false });
80
+ registry.settleTask(taskB.id, { status: 'blocked', error: 'stuck', ok: false });
81
+ await new Promise(resolve => setTimeout(resolve, 25));
82
+ const abEvent = events.find(e => e.watcherId === regAB.watcherId);
83
+ assert.ok(abEvent, 'array watcher is notified');
84
+ assert.deepEqual(
85
+ abEvent.completions.map(c => c.taskId),
86
+ [taskB.id, taskC.id],
87
+ 'coalesced completions preserve the watch input order'
88
+ );
89
+ const bCompletion = abEvent.completions.find(c => c.taskId === taskB.id);
90
+ const cCompletion = abEvent.completions.find(c => c.taskId === taskC.id);
91
+ assert.equal(bCompletion.status, 'blocked');
92
+ assert.equal(bCompletion.returnCode, 2);
93
+ assert.equal(cCompletion.status, 'failed');
94
+ assert.equal(cCompletion.returnCode, 1);
95
+ assert.equal(cCompletion.error, 'boom');
96
+ console.log(
97
+ 'PASS multiple task ids settle independently, in watch input order, with correct codes'
98
+ );
99
+
100
+ // Terminal outcomes carry the right status + return code.
101
+ const cancelledAgent = registry.registerAgent({ agent: 'worker', label: 'watcher-cancelled' });
102
+ const cancelled = registry.createTask(cancelledAgent, 'will be cancelled');
103
+ const regCancelled = service.watch(cancelled.id);
104
+ registry.setTaskRunning(cancelled.id);
105
+ registry.settleTask(cancelled.id, { status: 'cancelled', error: 'Agent was closed.' });
106
+ const timedOutAgent = registry.registerAgent({ agent: 'worker', label: 'watcher-timeout' });
107
+ const timedOut = registry.createTask(timedOutAgent, 'will time out');
108
+ const regTimedOut = service.watch(timedOut.id);
109
+ registry.setTaskRunning(timedOut.id);
110
+ registry.settleTask(timedOut.id, { status: 'timed_out', error: 'Tracked task deadline reached.' });
111
+ await new Promise(resolve => setTimeout(resolve, 20));
112
+ const cancelledCompletion = events
113
+ .find(e => e.completions.some(c => c.taskId === cancelled.id))
114
+ .completions.find(c => c.taskId === cancelled.id);
115
+ const timedOutCompletion = events
116
+ .find(e => e.completions.some(c => c.taskId === timedOut.id))
117
+ .completions.find(c => c.taskId === timedOut.id);
118
+ assert.equal(cancelledCompletion.status, 'cancelled');
119
+ assert.equal(cancelledCompletion.returnCode, 130);
120
+ assert.match(cancelledCompletion.error, /closed/i);
121
+ assert.equal(timedOutCompletion.status, 'timed_out');
122
+ assert.equal(timedOutCompletion.returnCode, 124);
123
+ console.log('PASS cancelled and timed-out tasks report their terminal status and return code');
124
+
125
+ // Independent watchers each get exactly one notification for the same task.
126
+ const idle = registry.registerAgent({ agent: 'planner', label: 'watcher-shared' });
127
+ const shared = registry.createTask(idle, 'shared');
128
+ const regShared1 = service.watch(shared.id);
129
+ const regShared2 = service.watch(shared.id);
130
+ registry.setTaskRunning(shared.id);
131
+ registry.settleTask(shared.id, { status: 'completed', text: 'shared done', ok: true });
132
+ await new Promise(resolve => setTimeout(resolve, 20));
133
+ const perWatcher = [regShared1.watcherId, regShared2.watcherId].map(
134
+ watcherId =>
135
+ events.filter(e => e.watcherId === watcherId && e.completions.some(c => c.taskId === shared.id))
136
+ .length
137
+ );
138
+ assert.deepEqual(perWatcher, [1, 1], 'each independent watcher observes exactly one completion');
139
+ service.shutdown();
140
+ console.log('PASS independent watchers each observe the same task exactly once');
141
+
142
+ // Reject agent ids / pane ids / unknown ids as watcher targets; no duplicates.
143
+ expectRejectTaskWatcher(() => service.watch('shepherd-agent-unknown'), 'unknown task is rejected');
144
+ expectRejectTaskWatcher(
145
+ () => service.watch([taskA.id, taskA.id]),
146
+ 'duplicate task ids are rejected'
147
+ );
148
+ function expectRejectTaskWatcher(fn, label) {
149
+ assert.throws(fn, e => e instanceof LifecycleError, label);
150
+ console.log(`PASS ${label}`);
151
+ }
152
+
153
+ // ── Extension bridge ─────────────────────────────────────────────────────
154
+ // The parent extension's task watcher sends a custom follow-up that triggers a
155
+ // turn, uses the task id as the correlation key, and stays silent on shutdown.
156
+ const sentTask = [];
157
+ let taskMessageRenderer;
158
+ registerShepherdTools({
159
+ registerTool() {},
160
+ registerMessageRenderer(customType, renderer) {
161
+ if (customType === 'shepherd.task.completion') taskMessageRenderer = renderer;
162
+ },
163
+ sendMessage(message, options) {
164
+ sentTask.push({ message, options });
165
+ },
166
+ });
167
+
168
+ const bridgeAgent = lifecycleRegistry.registerAgent({ agent: 'worker', label: 'task-bridge' });
169
+ const bridgeTask = lifecycleRegistry.createTask(bridgeAgent, 'Bridge task.');
170
+ lifecycleRegistry.setTaskRunning(bridgeTask.id);
171
+ setTaskWatcherSessionActive(true);
172
+ taskWatcherService.watch(bridgeTask.id);
173
+ lifecycleRegistry.settleTask(bridgeTask.id, {
174
+ status: 'completed',
175
+ text: 'bridge task done',
176
+ ok: true,
177
+ });
178
+ await new Promise(resolve => setTimeout(resolve, 40));
179
+ assert.equal(sentTask.length, 1, 'task bridge sends one custom completion message');
180
+ assert.equal(typeof taskMessageRenderer, 'function');
181
+ assert.equal(sentTask[0].message.customType, 'shepherd.task.completion');
182
+ assert.equal(sentTask[0].message.details.completions[0].taskId, bridgeTask.id);
183
+ assert.equal(sentTask[0].message.details.completions[0].agentId, bridgeAgent.id);
184
+ assert.equal(
185
+ sentTask[0].message.content,
186
+ 'shepherd_watcher completion: worker: task-bridge completed'
187
+ );
188
+ assert.ok(Array.isArray(sentTask[0].message.details.completions));
189
+ assert.doesNotMatch(sentTask[0].message.content, /\n(?:call|return|details):/);
190
+ assert.deepEqual(sentTask[0].options, { deliverAs: 'steer', triggerTurn: true });
191
+ console.log(
192
+ 'PASS the parent bridge delivers task completions as a turn-triggering follow-up with the task id'
193
+ );
194
+
195
+ // A completion is not re-sent after the shutdown path releases state.
196
+ const bridgeAgent2 = lifecycleRegistry.registerAgent({ agent: 'worker', label: 'task-bridge-2' });
197
+ const bridgeTask2 = lifecycleRegistry.createTask(bridgeAgent2, 'Bridge task 2.');
198
+ lifecycleRegistry.setTaskRunning(bridgeTask2.id);
199
+ taskWatcherService.watch(bridgeTask2.id);
200
+ setTaskWatcherSessionActive(false);
201
+ lifecycleRegistry.settleTask(bridgeTask2.id, {
202
+ status: 'completed',
203
+ text: 'should not be sent',
204
+ ok: true,
205
+ });
206
+ await new Promise(resolve => setTimeout(resolve, 40));
207
+ assert.equal(
208
+ sentTask.length,
209
+ 1,
210
+ 'no task completion is delivered after the session bridge is deactivated'
211
+ );
212
+ setTaskWatcherSessionActive(true);
213
+ console.log('PASS task-watcher delivery is suppressed after the parent session goes inactive');
214
+
215
+ // Clean up the global task watcher timers so the process can exit.
216
+ taskWatcherService.shutdown();
217
+ console.log('All task-watcher assertions passed.');
@@ -0,0 +1,120 @@
1
+ // verify-tool-schemas.mjs
2
+ //
3
+ // Invariant: every model-facing tool parameter schema must have a root
4
+ // "type": "object". Bare anyOf roots break grammar/schema-constrained
5
+ // sampling backends, which emit `{}` arguments for every call
6
+ // (see docs/plans/tool-surface-split.md §1).
7
+ //
8
+ // This is the permanent guard for the flat-object schema invariant introduced
9
+ // during phases 2–3. It probes the real registrations produced by
10
+ // registerShepherdTools() through a mock ExtensionAPI instead of duplicating
11
+ // the schemas by hand.
12
+ import assert from 'node:assert/strict';
13
+ import { registerShepherdTools } from '../src/extension/shepherd.ts';
14
+
15
+ const registered = [];
16
+ registerShepherdTools({
17
+ registerTool(tool) {
18
+ registered.push(tool);
19
+ },
20
+ registerMessageRenderer() {},
21
+ });
22
+
23
+ const expectedNames = [
24
+ 'shepherd',
25
+ 'shepherd_spawn',
26
+ 'shepherd_delegate',
27
+ 'shepherd_message',
28
+ 'shepherd_prompt',
29
+ 'shepherd_watch',
30
+ 'shepherd_status',
31
+ 'shepherd_close',
32
+ 'shepherd_read',
33
+ ];
34
+ assert.deepEqual(
35
+ registered.map(tool => tool.name),
36
+ expectedNames,
37
+ 'registerShepherdTools must register the nine shepherd tools'
38
+ );
39
+
40
+ let failed = 0;
41
+ for (const tool of registered) {
42
+ const schema = tool.parameters;
43
+ try {
44
+ assert.ok(schema && typeof schema === 'object', 'schema missing');
45
+ assert.equal(schema.type, 'object', 'root schema must have type "object"');
46
+ assert.ok(
47
+ schema.properties && typeof schema.properties === 'object',
48
+ 'root schema must declare properties'
49
+ );
50
+ if (
51
+ ['shepherd_prompt', 'shepherd_watch', 'shepherd_status', 'shepherd_close'].includes(tool.name)
52
+ ) {
53
+ assert.ok('id' in schema.properties, `${tool.name} must expose a top-level id`);
54
+ assert.ok(!('handle' in schema.properties), `${tool.name} must not expose a public handle`);
55
+ }
56
+ if (tool.name === 'shepherd_delegate') {
57
+ assert.deepEqual(
58
+ schema.required,
59
+ ['target', 'task'],
60
+ 'shepherd_delegate requires target and task'
61
+ );
62
+ assert.deepEqual(
63
+ Object.keys(schema.properties).sort(),
64
+ ['target', 'task', 'timeout'],
65
+ 'shepherd_delegate exposes only the public delegation arguments'
66
+ );
67
+ }
68
+ if (tool.name === 'shepherd_message') {
69
+ assert.deepEqual(
70
+ schema.required,
71
+ ['target', 'message'],
72
+ 'shepherd_message requires target and message'
73
+ );
74
+ assert.deepEqual(
75
+ Object.keys(schema.properties).sort(),
76
+ ['delivery', 'expectsReply', 'message', 'replyTo', 'target', 'taskId', 'threadId'],
77
+ 'shepherd_message exposes only the public message arguments'
78
+ );
79
+ }
80
+ if (tool.name === 'shepherd_spawn') {
81
+ assert.deepEqual(
82
+ schema.required,
83
+ ['agent', 'label'],
84
+ 'shepherd_spawn requires only agent and label'
85
+ );
86
+ assert.deepEqual(
87
+ Object.keys(schema.properties).sort(),
88
+ ['agent', 'cwd', 'label', 'placement'],
89
+ 'shepherd_spawn exposes only the public spawn arguments'
90
+ );
91
+ for (const removed of [
92
+ 'agentScope',
93
+ 'direction',
94
+ 'confirmProjectAgents',
95
+ 'omitSystemPrompt',
96
+ 'model',
97
+ ]) {
98
+ assert.ok(!(removed in schema.properties), `shepherd_spawn must not expose ${removed}`);
99
+ }
100
+ assert.deepEqual(schema.properties.placement.enum, [
101
+ 'pane_right',
102
+ 'pane_down',
103
+ 'tab',
104
+ 'workspace',
105
+ ]);
106
+ }
107
+ console.log(`PASS ${tool.name}: root is a flat object with the intended fields`);
108
+ } catch (error) {
109
+ failed++;
110
+ console.log(
111
+ `FAIL ${tool.name}: ${error.message} (keys: ${Object.keys(schema ?? {}).join(', ')})`
112
+ );
113
+ }
114
+ }
115
+
116
+ if (failed > 0) {
117
+ console.log(`\n${failed}/${registered.length} tool schemas violate the flat-object invariant.`);
118
+ process.exit(1);
119
+ }
120
+ console.log('\nAll tool schemas satisfy the flat-object invariant.');