@luminascale/shepherd 0.0.0-stage → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
|
@@ -0,0 +1,560 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Phase 6 verification: asynchronous message routing.
|
|
4
|
+
*
|
|
5
|
+
* Covers the canonical waiting scenario end-to-end at the service level:
|
|
6
|
+
* - parent-to-child messages (plain and expectsReply),
|
|
7
|
+
* - child questions that put the sender's task into `waiting`,
|
|
8
|
+
* - replies that resolve the request (task -> running) and are relayed
|
|
9
|
+
* back to the asker's inbox with preserved provenance,
|
|
10
|
+
* - mismatched and duplicate replies,
|
|
11
|
+
* - reply deadline expiry (task -> blocked),
|
|
12
|
+
* - delivery rejections and task-state invariants for plain messages.
|
|
13
|
+
*/
|
|
14
|
+
import assert from 'node:assert/strict';
|
|
15
|
+
import * as fs from 'node:fs';
|
|
16
|
+
import * as path from 'path';
|
|
17
|
+
import {
|
|
18
|
+
currentParentBroker,
|
|
19
|
+
ensureParentBroker,
|
|
20
|
+
processParentBrokerMessages,
|
|
21
|
+
sendParentMessage,
|
|
22
|
+
shutdownParentBroker,
|
|
23
|
+
} from '../src/core/lifecycle.ts';
|
|
24
|
+
import {
|
|
25
|
+
createChildBroker,
|
|
26
|
+
pollChildInbox,
|
|
27
|
+
publishFromChild,
|
|
28
|
+
registerChild,
|
|
29
|
+
createEnvelope,
|
|
30
|
+
} from '../src/core/messaging.ts';
|
|
31
|
+
import { lifecycleRegistry, LifecycleError } from '../src/core/orchestration.ts';
|
|
32
|
+
import { withTempDirectory } from './helpers/test-utils.mjs';
|
|
33
|
+
|
|
34
|
+
function writeFakeHerdr(fakePath, stateFile) {
|
|
35
|
+
const body = [
|
|
36
|
+
'#!/usr/bin/env node',
|
|
37
|
+
'const fs = require("node:fs");',
|
|
38
|
+
`const state = JSON.parse(fs.readFileSync('${stateFile}', "utf8"));`,
|
|
39
|
+
'const [cmd, sub, target] = process.argv.slice(2);',
|
|
40
|
+
'if (cmd === "pane" && sub === "list") {',
|
|
41
|
+
' process.stdout.write(JSON.stringify({ result: { panes: (state.panes ?? []).map(id => ({ pane_id: id })) } }));',
|
|
42
|
+
'} else if (cmd === "agent" && sub === "read") {',
|
|
43
|
+
' if ((state.errorPanes ?? []).includes(target)) {',
|
|
44
|
+
' process.stdout.write("Error: provider authentication failed\\n");',
|
|
45
|
+
' }',
|
|
46
|
+
'}',
|
|
47
|
+
'process.exit(0);',
|
|
48
|
+
'',
|
|
49
|
+
].join('\n');
|
|
50
|
+
fs.writeFileSync(fakePath, body);
|
|
51
|
+
fs.chmodSync(fakePath, 0o755);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
await withTempDirectory('pi-shepherd-message-routing-', async root => {
|
|
55
|
+
const bin = path.join(root, 'bin');
|
|
56
|
+
const stateFile = path.join(root, 'herdr-state.json');
|
|
57
|
+
fs.mkdirSync(bin);
|
|
58
|
+
writeFakeHerdr(path.join(bin, 'herdr'), stateFile);
|
|
59
|
+
fs.writeFileSync(stateFile, JSON.stringify({ panes: ['pane-timeout'], errorPanes: [] }));
|
|
60
|
+
|
|
61
|
+
const oldPath = process.env.PATH;
|
|
62
|
+
process.env.PATH = `${bin}${path.delimiter}${oldPath ?? ''}`;
|
|
63
|
+
|
|
64
|
+
const SESSION = 'message-routing-test-session';
|
|
65
|
+
ensureParentBroker(SESSION);
|
|
66
|
+
const broker = currentParentBroker();
|
|
67
|
+
assert.ok(broker);
|
|
68
|
+
|
|
69
|
+
// Participants: scout sends, planner is the (busy) recipient.
|
|
70
|
+
const scout = lifecycleRegistry.registerAgent({ agent: 'scout', label: 'routing scout' });
|
|
71
|
+
const planner = lifecycleRegistry.registerAgent({ agent: 'planner', label: 'routing planner' });
|
|
72
|
+
for (const agent of [scout, planner]) {
|
|
73
|
+
const capability = registerChild(broker, agent.id);
|
|
74
|
+
lifecycleRegistry.attachAgentChildCapability(agent, capability);
|
|
75
|
+
}
|
|
76
|
+
const scoutChild = createChildBroker({
|
|
77
|
+
rootDir: broker.rootDir,
|
|
78
|
+
...lifecycleRegistry.agentChildCapability(scout),
|
|
79
|
+
});
|
|
80
|
+
const plannerChild = createChildBroker({
|
|
81
|
+
rootDir: broker.rootDir,
|
|
82
|
+
...lifecycleRegistry.agentChildCapability(planner),
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
const scoutTask = lifecycleRegistry.createTask(scout, 'Investigate the authentication flow.');
|
|
86
|
+
lifecycleRegistry.setTaskRunning(scoutTask.id);
|
|
87
|
+
|
|
88
|
+
// A separate busy-task on planner so the question targets a busy recipient.
|
|
89
|
+
const plannerTask = lifecycleRegistry.createTask(planner, 'Design the session middleware.');
|
|
90
|
+
lifecycleRegistry.setTaskRunning(plannerTask.id);
|
|
91
|
+
|
|
92
|
+
try {
|
|
93
|
+
// ── Message to an idle recipient (no active task) ────────────────────
|
|
94
|
+
const idleAgent = lifecycleRegistry.registerAgent({
|
|
95
|
+
agent: 'reviewer',
|
|
96
|
+
label: 'idle recipient',
|
|
97
|
+
});
|
|
98
|
+
const idleCapability = registerChild(broker, idleAgent.id);
|
|
99
|
+
lifecycleRegistry.attachAgentChildCapability(idleAgent, idleCapability);
|
|
100
|
+
const idleChild = createChildBroker({ rootDir: broker.rootDir, ...idleCapability });
|
|
101
|
+
const idleMessage = sendParentMessage({
|
|
102
|
+
target: idleAgent.id,
|
|
103
|
+
message: 'Are you free to review?',
|
|
104
|
+
});
|
|
105
|
+
assert.equal(idleMessage.accepted, true);
|
|
106
|
+
assert.equal('requestId' in idleMessage, false, 'no reply tracking without expectsReply');
|
|
107
|
+
const idleInbox = pollChildInbox(idleChild);
|
|
108
|
+
assert.equal(idleInbox.length, 1);
|
|
109
|
+
assert.equal(idleInbox[0].content, 'Are you free to review?');
|
|
110
|
+
assert.equal(
|
|
111
|
+
lifecycleRegistry.activeTaskForAgent(idleAgent),
|
|
112
|
+
undefined,
|
|
113
|
+
'a message never creates a task'
|
|
114
|
+
);
|
|
115
|
+
console.log('PASS a message to an idle recipient is queued without creating task state');
|
|
116
|
+
|
|
117
|
+
assert.throws(
|
|
118
|
+
() =>
|
|
119
|
+
sendParentMessage({ target: 'planner', message: 'This must not resolve by agent name.' }),
|
|
120
|
+
error => {
|
|
121
|
+
assert.ok(error instanceof LifecycleError);
|
|
122
|
+
assert.equal(error.code, 'invalid_target');
|
|
123
|
+
assert.match(error.message, /exact opaque agent id returned by shepherd_spawn/);
|
|
124
|
+
assert.match(error.message, /agent name such as "planner"/);
|
|
125
|
+
return true;
|
|
126
|
+
},
|
|
127
|
+
'parent shepherd_message rejects agent definition names with actionable target guidance'
|
|
128
|
+
);
|
|
129
|
+
console.log('PASS parent shepherd_message rejects agent names instead of resolving them');
|
|
130
|
+
|
|
131
|
+
// ── Parent reply settles a child-originated request locally ────────────
|
|
132
|
+
const parentReplyTask = lifecycleRegistry.createTask(
|
|
133
|
+
idleAgent,
|
|
134
|
+
'Complete the parent reply handshake.'
|
|
135
|
+
);
|
|
136
|
+
lifecycleRegistry.setTaskRunning(parentReplyTask.id);
|
|
137
|
+
const childQuestion = createEnvelope(
|
|
138
|
+
{ sessionId: idleChild.sessionId, brokerId: idleChild.brokerId, senderId: idleChild.agentId },
|
|
139
|
+
{
|
|
140
|
+
kind: 'message',
|
|
141
|
+
targetId: 'shepherd',
|
|
142
|
+
taskId: parentReplyTask.id,
|
|
143
|
+
expectsReply: true,
|
|
144
|
+
delivery: 'followUp',
|
|
145
|
+
content: 'CHILD_REQUEST: please answer directly.',
|
|
146
|
+
}
|
|
147
|
+
);
|
|
148
|
+
assert.equal(publishFromChild(idleChild, childQuestion).accepted, true);
|
|
149
|
+
const childRequestMirror = createEnvelope(
|
|
150
|
+
{ sessionId: idleChild.sessionId, brokerId: idleChild.brokerId, senderId: idleChild.agentId },
|
|
151
|
+
{
|
|
152
|
+
kind: 'runtime',
|
|
153
|
+
targetId: 'shepherd',
|
|
154
|
+
taskId: parentReplyTask.id,
|
|
155
|
+
replyTo: childQuestion.messageId,
|
|
156
|
+
requestOpen: true,
|
|
157
|
+
requestTargetId: broker.parentId,
|
|
158
|
+
summary: childQuestion.content,
|
|
159
|
+
delivery: 'followUp',
|
|
160
|
+
}
|
|
161
|
+
);
|
|
162
|
+
assert.equal(publishFromChild(idleChild, childRequestMirror).accepted, true);
|
|
163
|
+
await processParentBrokerMessages();
|
|
164
|
+
assert.equal(lifecycleRegistry.getTask(parentReplyTask.id).state, 'waiting');
|
|
165
|
+
const directAnswer = sendParentMessage({
|
|
166
|
+
target: idleAgent.id,
|
|
167
|
+
taskId: parentReplyTask.id,
|
|
168
|
+
replyTo: childQuestion.messageId,
|
|
169
|
+
message: 'PARENT_DIRECT_REPLY: request answered.',
|
|
170
|
+
});
|
|
171
|
+
assert.equal(directAnswer.accepted, true);
|
|
172
|
+
assert.equal(directAnswer.targetTaskState, 'running');
|
|
173
|
+
assert.equal(lifecycleRegistry.getTask(parentReplyTask.id).state, 'running');
|
|
174
|
+
const directAnswerEnvelope = pollChildInbox(idleChild).find(
|
|
175
|
+
message => message.replyTo === childQuestion.messageId
|
|
176
|
+
);
|
|
177
|
+
assert.ok(directAnswerEnvelope, 'the direct parent reply reaches the child');
|
|
178
|
+
const directCompletion = lifecycleRegistry.settleTask(parentReplyTask.id, {
|
|
179
|
+
status: 'completed',
|
|
180
|
+
text: 'Completed after the direct parent reply.',
|
|
181
|
+
});
|
|
182
|
+
assert.equal(directCompletion.status, 'completed');
|
|
183
|
+
console.log(
|
|
184
|
+
'PASS parent reply resolves a child-originated request without a redundant child acknowledgment'
|
|
185
|
+
);
|
|
186
|
+
|
|
187
|
+
// ── Parent -> child: plain message leaves task state unchanged ────────
|
|
188
|
+
const plain = sendParentMessage({
|
|
189
|
+
target: scout.id,
|
|
190
|
+
message: 'Any progress so far?',
|
|
191
|
+
taskId: scoutTask.id,
|
|
192
|
+
});
|
|
193
|
+
assert.match(plain.messageId, /^shepherd-message-/);
|
|
194
|
+
assert.equal(plain.accepted, true);
|
|
195
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'running');
|
|
196
|
+
const scoutInbox = pollChildInbox(scoutChild);
|
|
197
|
+
assert.equal(scoutInbox.length, 1);
|
|
198
|
+
assert.equal(scoutInbox[0].content, 'Any progress so far?');
|
|
199
|
+
assert.equal(scoutInbox[0].senderId, broker.parentId);
|
|
200
|
+
assert.equal(scoutInbox[0].delivery, 'steer'); // 012: steer is the default; pass followUp explicitly for passive FYI
|
|
201
|
+
console.log('PASS parent-to-child message is queued without altering task state');
|
|
202
|
+
|
|
203
|
+
// ── Parent -> child: expectsReply puts the task into waiting ──────────
|
|
204
|
+
const question = sendParentMessage({
|
|
205
|
+
target: scout.id,
|
|
206
|
+
message: 'Confirm the middleware location.',
|
|
207
|
+
taskId: scoutTask.id,
|
|
208
|
+
expectsReply: true,
|
|
209
|
+
});
|
|
210
|
+
assert.equal(question.targetTaskState, 'waiting');
|
|
211
|
+
assert.equal(question.requestId, question.messageId);
|
|
212
|
+
const waitingTask = lifecycleRegistry.getTask(scoutTask.id);
|
|
213
|
+
assert.equal(waitingTask.state, 'waiting');
|
|
214
|
+
assert.equal(waitingTask.pendingReplyMessageId, question.messageId);
|
|
215
|
+
assert.ok(waitingTask.pendingReplyDeadlineAt > Date.now());
|
|
216
|
+
console.log(
|
|
217
|
+
'PASS parent expectsReply message creates a tracked request and sets the task waiting'
|
|
218
|
+
);
|
|
219
|
+
|
|
220
|
+
// The child answers the parent question through the parent mailbox.
|
|
221
|
+
const parentReply = createEnvelope(
|
|
222
|
+
{
|
|
223
|
+
sessionId: scoutChild.sessionId,
|
|
224
|
+
brokerId: scoutChild.brokerId,
|
|
225
|
+
senderId: scoutChild.agentId,
|
|
226
|
+
},
|
|
227
|
+
{
|
|
228
|
+
kind: 'reply',
|
|
229
|
+
targetId: 'shepherd',
|
|
230
|
+
taskId: scoutTask.id,
|
|
231
|
+
replyTo: question.messageId,
|
|
232
|
+
delivery: 'followUp',
|
|
233
|
+
content: 'The middleware is in src/auth/session.ts.',
|
|
234
|
+
}
|
|
235
|
+
);
|
|
236
|
+
assert.equal(publishFromChild(scoutChild, parentReply).accepted, true);
|
|
237
|
+
await processParentBrokerMessages();
|
|
238
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'running');
|
|
239
|
+
const selfRelays = pollChildInbox(scoutChild).filter(
|
|
240
|
+
m => m.kind === 'reply' && m.replyTo === question.messageId
|
|
241
|
+
);
|
|
242
|
+
assert.equal(
|
|
243
|
+
selfRelays.length,
|
|
244
|
+
0,
|
|
245
|
+
'the owner answering its own tracked request is not echoed back to its own inbox'
|
|
246
|
+
);
|
|
247
|
+
console.log('PASS a matching reply clears the request and returns the task to running');
|
|
248
|
+
|
|
249
|
+
// ── Canonical scenario: worker asks a busy planner ────────────────────
|
|
250
|
+
const busyQuestion = createEnvelope(
|
|
251
|
+
{
|
|
252
|
+
sessionId: scoutChild.sessionId,
|
|
253
|
+
brokerId: scoutChild.brokerId,
|
|
254
|
+
senderId: scoutChild.agentId,
|
|
255
|
+
},
|
|
256
|
+
{
|
|
257
|
+
kind: 'message',
|
|
258
|
+
targetId: planner.id,
|
|
259
|
+
taskId: scoutTask.id,
|
|
260
|
+
threadId: 'thread-auth-flow',
|
|
261
|
+
expectsReply: true,
|
|
262
|
+
delivery: 'followUp',
|
|
263
|
+
content: 'What have you found about the authentication flow?',
|
|
264
|
+
}
|
|
265
|
+
);
|
|
266
|
+
// The question goes directly to the busy planner inbox...
|
|
267
|
+
assert.equal(publishFromChild(scoutChild, busyQuestion).delivery, 'queued');
|
|
268
|
+
// ...and the child mirrors the tracked request to the parent mailbox.
|
|
269
|
+
const mirror = createEnvelope(
|
|
270
|
+
{
|
|
271
|
+
sessionId: scoutChild.sessionId,
|
|
272
|
+
brokerId: scoutChild.brokerId,
|
|
273
|
+
senderId: scoutChild.agentId,
|
|
274
|
+
},
|
|
275
|
+
{
|
|
276
|
+
kind: 'runtime',
|
|
277
|
+
targetId: 'shepherd',
|
|
278
|
+
taskId: scoutTask.id,
|
|
279
|
+
threadId: 'thread-auth-flow',
|
|
280
|
+
replyTo: busyQuestion.messageId,
|
|
281
|
+
requestOpen: true,
|
|
282
|
+
requestTargetId: planner.id,
|
|
283
|
+
summary: 'What have you found about the authentication flow?',
|
|
284
|
+
delivery: 'followUp',
|
|
285
|
+
}
|
|
286
|
+
);
|
|
287
|
+
assert.equal(publishFromChild(scoutChild, mirror).accepted, true);
|
|
288
|
+
await processParentBrokerMessages();
|
|
289
|
+
|
|
290
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'waiting');
|
|
291
|
+
assert.equal(
|
|
292
|
+
lifecycleRegistry.getTask(scoutTask.id).pendingReplyMessageId,
|
|
293
|
+
busyQuestion.messageId
|
|
294
|
+
);
|
|
295
|
+
const queuedForPlanner = pollChildInbox(plannerChild).find(
|
|
296
|
+
m => m.messageId === busyQuestion.messageId
|
|
297
|
+
);
|
|
298
|
+
assert.ok(
|
|
299
|
+
queuedForPlanner,
|
|
300
|
+
'the question is delivered to the busy planner inbox as a follow-up'
|
|
301
|
+
);
|
|
302
|
+
assert.equal(queuedForPlanner.expectsReply, true);
|
|
303
|
+
assert.equal(
|
|
304
|
+
lifecycleRegistry.getTask(plannerTask.id).state,
|
|
305
|
+
'running',
|
|
306
|
+
'planner busy-task is untouched by the incoming question'
|
|
307
|
+
);
|
|
308
|
+
console.log(
|
|
309
|
+
'PASS worker asking a busy planner queues a follow-up and keeps the worker task waiting'
|
|
310
|
+
);
|
|
311
|
+
|
|
312
|
+
// ── Invalid reply: mismatched replyTo leaves the request pending ──────
|
|
313
|
+
const mismatchedReply = createEnvelope(
|
|
314
|
+
{
|
|
315
|
+
sessionId: plannerChild.sessionId,
|
|
316
|
+
brokerId: plannerChild.brokerId,
|
|
317
|
+
senderId: plannerChild.agentId,
|
|
318
|
+
},
|
|
319
|
+
{
|
|
320
|
+
kind: 'reply',
|
|
321
|
+
targetId: 'shepherd',
|
|
322
|
+
taskId: scoutTask.id,
|
|
323
|
+
replyTo: 'shepherd-message-not-the-question',
|
|
324
|
+
delivery: 'followUp',
|
|
325
|
+
content: 'Stray answer.',
|
|
326
|
+
}
|
|
327
|
+
);
|
|
328
|
+
assert.equal(publishFromChild(plannerChild, mismatchedReply).accepted, true);
|
|
329
|
+
await processParentBrokerMessages();
|
|
330
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'waiting');
|
|
331
|
+
assert.equal(
|
|
332
|
+
lifecycleRegistry.getTask(scoutTask.id).pendingReplyMessageId,
|
|
333
|
+
busyQuestion.messageId
|
|
334
|
+
);
|
|
335
|
+
console.log('PASS a mismatched reply is rejected and the task stays waiting');
|
|
336
|
+
|
|
337
|
+
// ── Valid reply: planner answers; scout resumes; relay preserves provenance ──
|
|
338
|
+
const peerReply = createEnvelope(
|
|
339
|
+
{
|
|
340
|
+
sessionId: plannerChild.sessionId,
|
|
341
|
+
brokerId: plannerChild.brokerId,
|
|
342
|
+
senderId: plannerChild.agentId,
|
|
343
|
+
},
|
|
344
|
+
{
|
|
345
|
+
kind: 'reply',
|
|
346
|
+
targetId: 'shepherd',
|
|
347
|
+
taskId: scoutTask.id,
|
|
348
|
+
threadId: 'thread-auth-flow',
|
|
349
|
+
replyTo: busyQuestion.messageId,
|
|
350
|
+
delivery: 'followUp',
|
|
351
|
+
content: 'Sessions are validated by middleware in src/auth/session.ts.',
|
|
352
|
+
}
|
|
353
|
+
);
|
|
354
|
+
assert.equal(publishFromChild(plannerChild, peerReply).accepted, true);
|
|
355
|
+
await processParentBrokerMessages();
|
|
356
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'running');
|
|
357
|
+
const peerRelay = pollChildInbox(scoutChild).find(
|
|
358
|
+
m => m.kind === 'reply' && m.replyTo === busyQuestion.messageId
|
|
359
|
+
);
|
|
360
|
+
assert.ok(peerRelay, 'the answer is relayed to the worker inbox');
|
|
361
|
+
assert.equal(
|
|
362
|
+
peerRelay.originSenderId,
|
|
363
|
+
plannerChild.agentId,
|
|
364
|
+
'provenance: origin sender stays the planner'
|
|
365
|
+
);
|
|
366
|
+
assert.equal(peerRelay.content, 'Sessions are validated by middleware in src/auth/session.ts.');
|
|
367
|
+
assert.notEqual(peerRelay.messageId, peerReply.messageId, 'relay uses a fresh message id');
|
|
368
|
+
console.log(
|
|
369
|
+
'PASS planner reply resolves the request, the worker resumes, and the relay preserves sender provenance'
|
|
370
|
+
);
|
|
371
|
+
|
|
372
|
+
// A peer may answer directly to the requester's inbox. The child-side
|
|
373
|
+
// reply mirror still lets the parent clear the tracked waiting task, while
|
|
374
|
+
// avoiding a second parent-generated relay.
|
|
375
|
+
const directQuestion = createEnvelope(
|
|
376
|
+
{
|
|
377
|
+
sessionId: scoutChild.sessionId,
|
|
378
|
+
brokerId: scoutChild.brokerId,
|
|
379
|
+
senderId: scoutChild.agentId,
|
|
380
|
+
},
|
|
381
|
+
{
|
|
382
|
+
kind: 'message',
|
|
383
|
+
targetId: planner.id,
|
|
384
|
+
taskId: scoutTask.id,
|
|
385
|
+
expectsReply: true,
|
|
386
|
+
delivery: 'followUp',
|
|
387
|
+
content: 'Can you answer directly?',
|
|
388
|
+
}
|
|
389
|
+
);
|
|
390
|
+
assert.equal(publishFromChild(scoutChild, directQuestion).delivery, 'queued');
|
|
391
|
+
const directRequestMirror = createEnvelope(
|
|
392
|
+
{
|
|
393
|
+
sessionId: scoutChild.sessionId,
|
|
394
|
+
brokerId: scoutChild.brokerId,
|
|
395
|
+
senderId: scoutChild.agentId,
|
|
396
|
+
},
|
|
397
|
+
{
|
|
398
|
+
kind: 'runtime',
|
|
399
|
+
targetId: 'shepherd',
|
|
400
|
+
taskId: scoutTask.id,
|
|
401
|
+
replyTo: directQuestion.messageId,
|
|
402
|
+
requestOpen: true,
|
|
403
|
+
requestTargetId: planner.id,
|
|
404
|
+
summary: directQuestion.content,
|
|
405
|
+
delivery: 'followUp',
|
|
406
|
+
}
|
|
407
|
+
);
|
|
408
|
+
assert.equal(publishFromChild(scoutChild, directRequestMirror).accepted, true);
|
|
409
|
+
await processParentBrokerMessages();
|
|
410
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'waiting');
|
|
411
|
+
const directPeerReply = createEnvelope(
|
|
412
|
+
{
|
|
413
|
+
sessionId: plannerChild.sessionId,
|
|
414
|
+
brokerId: plannerChild.brokerId,
|
|
415
|
+
senderId: plannerChild.agentId,
|
|
416
|
+
},
|
|
417
|
+
{
|
|
418
|
+
kind: 'reply',
|
|
419
|
+
targetId: scout.id,
|
|
420
|
+
taskId: scoutTask.id,
|
|
421
|
+
replyTo: directQuestion.messageId,
|
|
422
|
+
delivery: 'followUp',
|
|
423
|
+
content: 'Direct pong.',
|
|
424
|
+
}
|
|
425
|
+
);
|
|
426
|
+
assert.equal(publishFromChild(plannerChild, directPeerReply).delivery, 'queued');
|
|
427
|
+
const directReplyMirror = createEnvelope(
|
|
428
|
+
{
|
|
429
|
+
sessionId: plannerChild.sessionId,
|
|
430
|
+
brokerId: plannerChild.brokerId,
|
|
431
|
+
senderId: plannerChild.agentId,
|
|
432
|
+
},
|
|
433
|
+
{
|
|
434
|
+
kind: 'runtime',
|
|
435
|
+
targetId: 'shepherd',
|
|
436
|
+
taskId: scoutTask.id,
|
|
437
|
+
replyTo: directQuestion.messageId,
|
|
438
|
+
replyReceived: true,
|
|
439
|
+
summary: directPeerReply.content,
|
|
440
|
+
delivery: 'followUp',
|
|
441
|
+
}
|
|
442
|
+
);
|
|
443
|
+
assert.equal(publishFromChild(plannerChild, directReplyMirror).accepted, true);
|
|
444
|
+
await processParentBrokerMessages();
|
|
445
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'running');
|
|
446
|
+
assert.deepEqual(pollChildInbox(scoutChild), [directPeerReply]);
|
|
447
|
+
console.log(
|
|
448
|
+
'PASS direct peer reply mirrors resolve the waiting task without duplicate delivery'
|
|
449
|
+
);
|
|
450
|
+
|
|
451
|
+
// ── Duplicate reply: idempotent, no second relay, no state change ─────
|
|
452
|
+
const duplicateReply = createEnvelope(
|
|
453
|
+
{
|
|
454
|
+
sessionId: plannerChild.sessionId,
|
|
455
|
+
brokerId: plannerChild.brokerId,
|
|
456
|
+
senderId: plannerChild.agentId,
|
|
457
|
+
},
|
|
458
|
+
{
|
|
459
|
+
kind: 'reply',
|
|
460
|
+
targetId: 'shepherd',
|
|
461
|
+
taskId: scoutTask.id,
|
|
462
|
+
threadId: 'thread-auth-flow',
|
|
463
|
+
replyTo: busyQuestion.messageId,
|
|
464
|
+
delivery: 'followUp',
|
|
465
|
+
content: 'Sessions are validated by middleware in src/auth/session.ts.',
|
|
466
|
+
}
|
|
467
|
+
);
|
|
468
|
+
assert.equal(publishFromChild(plannerChild, duplicateReply).accepted, true);
|
|
469
|
+
await processParentBrokerMessages();
|
|
470
|
+
assert.equal(lifecycleRegistry.getTask(scoutTask.id).state, 'running');
|
|
471
|
+
const relaysForQuestion = pollChildInbox(scoutChild).filter(
|
|
472
|
+
m => m.kind === 'reply' && m.replyTo === busyQuestion.messageId
|
|
473
|
+
);
|
|
474
|
+
assert.equal(
|
|
475
|
+
relaysForQuestion.length,
|
|
476
|
+
0,
|
|
477
|
+
'a reply for an already-resolved request is not relayed again'
|
|
478
|
+
);
|
|
479
|
+
console.log('PASS a duplicate reply is idempotent and does not re-deliver');
|
|
480
|
+
|
|
481
|
+
// ── Reply deadline expiry settles the task as blocked ─────────────────
|
|
482
|
+
const timeoutAgent = lifecycleRegistry.registerAgent({
|
|
483
|
+
agent: 'worker',
|
|
484
|
+
label: 'timeout target',
|
|
485
|
+
paneId: 'pane-timeout',
|
|
486
|
+
});
|
|
487
|
+
const timeoutTask = lifecycleRegistry.createTask(
|
|
488
|
+
timeoutAgent,
|
|
489
|
+
'Task that waits for a dead reply.'
|
|
490
|
+
);
|
|
491
|
+
lifecycleRegistry.setTaskRunning(timeoutTask.id);
|
|
492
|
+
lifecycleRegistry.openPendingRequest(timeoutTask.id, {
|
|
493
|
+
messageId: 'shepherd-message-timeout-question',
|
|
494
|
+
targetAgentId: planner.id,
|
|
495
|
+
deadlineAt: Date.now() - 1_000,
|
|
496
|
+
text: 'Question that will never be answered.',
|
|
497
|
+
});
|
|
498
|
+
assert.equal(lifecycleRegistry.getTask(timeoutTask.id).state, 'waiting');
|
|
499
|
+
let blocked = false;
|
|
500
|
+
for (let i = 0; i < 8 && !blocked; i++) {
|
|
501
|
+
await processParentBrokerMessages();
|
|
502
|
+
blocked = lifecycleRegistry.getTask(timeoutTask.id).state === 'blocked';
|
|
503
|
+
if (!blocked) await new Promise(resolve => setTimeout(resolve, 300));
|
|
504
|
+
}
|
|
505
|
+
const timeoutResult = lifecycleRegistry.taskResult(timeoutTask.id);
|
|
506
|
+
assert.equal(timeoutResult?.status, 'blocked');
|
|
507
|
+
assert.equal(timeoutResult?.returnCode, 2);
|
|
508
|
+
assert.match(timeoutResult?.error ?? '', /reply deadline/i);
|
|
509
|
+
console.log('PASS a reply deadline expiry settles the waiting task as blocked');
|
|
510
|
+
|
|
511
|
+
// ── Rejections: closed target, unknown target, mismatched task owner ──
|
|
512
|
+
const closedAgent = lifecycleRegistry.registerAgent({
|
|
513
|
+
agent: 'planner',
|
|
514
|
+
label: 'closed message target',
|
|
515
|
+
});
|
|
516
|
+
lifecycleRegistry.close(closedAgent);
|
|
517
|
+
assert.throws(
|
|
518
|
+
() => sendParentMessage({ target: closedAgent.id, message: 'Hello.' }),
|
|
519
|
+
error => error instanceof LifecycleError && error.code === 'closed_handle'
|
|
520
|
+
);
|
|
521
|
+
console.log('PASS messaging a closed agent is rejected');
|
|
522
|
+
|
|
523
|
+
assert.throws(
|
|
524
|
+
() => sendParentMessage({ target: 'not-an-agent', message: 'Hello.' }),
|
|
525
|
+
error => error instanceof LifecycleError && error.code === 'invalid_target'
|
|
526
|
+
);
|
|
527
|
+
console.log('PASS messaging an unknown target id is rejected as an invalid message target');
|
|
528
|
+
|
|
529
|
+
const foreignTask = lifecycleRegistry.createTask(timeoutAgent, 'Task for the other worker.');
|
|
530
|
+
lifecycleRegistry.setTaskRunning(foreignTask.id);
|
|
531
|
+
assert.throws(
|
|
532
|
+
() =>
|
|
533
|
+
sendParentMessage({
|
|
534
|
+
target: scout.id,
|
|
535
|
+
message: 'Wrong owner.',
|
|
536
|
+
taskId: foreignTask.id,
|
|
537
|
+
expectsReply: true,
|
|
538
|
+
}),
|
|
539
|
+
error => error instanceof LifecycleError && error.code === 'task_agent_mismatch'
|
|
540
|
+
);
|
|
541
|
+
assert.equal(lifecycleRegistry.getTask(foreignTask.id).state, 'running');
|
|
542
|
+
console.log('PASS expectsReply against a task owned by another agent is rejected');
|
|
543
|
+
} finally {
|
|
544
|
+
process.env.PATH = oldPath;
|
|
545
|
+
for (const agent of lifecycleRegistry.allAgents()) {
|
|
546
|
+
const active = lifecycleRegistry.activeTaskForAgent(agent);
|
|
547
|
+
if (active) {
|
|
548
|
+
try {
|
|
549
|
+
lifecycleRegistry.settleTask(active.taskId, {
|
|
550
|
+
status: 'cancelled',
|
|
551
|
+
error: 'test cleanup',
|
|
552
|
+
});
|
|
553
|
+
} catch {}
|
|
554
|
+
}
|
|
555
|
+
}
|
|
556
|
+
shutdownParentBroker(() => true);
|
|
557
|
+
}
|
|
558
|
+
});
|
|
559
|
+
|
|
560
|
+
console.log('All message routing assertions passed.');
|