@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.
- 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 +424 -2
- package/docs/README.md +25 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -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 +599 -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 +259 -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 +35 -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 +69 -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,135 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Phase 3 verification for the child side of the task-mislabel fix (issue
|
|
4
|
+
* #13). Spawn-then-delegate children are launched without a task id, so
|
|
5
|
+
* shepherd_done must validate the LLM's echoed id against the most recently
|
|
6
|
+
* delegated task and correct a fabricated one instead of publishing it.
|
|
7
|
+
*/
|
|
8
|
+
import assert from 'node:assert/strict';
|
|
9
|
+
import {
|
|
10
|
+
createChildBroker,
|
|
11
|
+
createEnvelope,
|
|
12
|
+
createParentBroker,
|
|
13
|
+
pollParentInbox,
|
|
14
|
+
publishFromParent,
|
|
15
|
+
registerChild,
|
|
16
|
+
} from '../src/core/messaging.ts';
|
|
17
|
+
import { withTempDirectory } from './helpers/test-utils.mjs';
|
|
18
|
+
|
|
19
|
+
const envNames = [
|
|
20
|
+
'PI_SHEPHERD_BROKER_DIR',
|
|
21
|
+
'PI_SHEPHERD_BROKER_SESSION_ID',
|
|
22
|
+
'PI_SHEPHERD_BROKER_ID',
|
|
23
|
+
'PI_SHEPHERD_AGENT_ID',
|
|
24
|
+
'PI_SHEPHERD_BROKER_TOKEN',
|
|
25
|
+
'PI_SHEPHERD_AGENT_INBOX',
|
|
26
|
+
'PI_SHEPHERD_TASK_ID',
|
|
27
|
+
];
|
|
28
|
+
const savedEnv = Object.fromEntries(envNames.map(name => [name, process.env[name]]));
|
|
29
|
+
|
|
30
|
+
try {
|
|
31
|
+
await withTempDirectory('pi-shepherd-child-mislabel-', async root => {
|
|
32
|
+
const broker = createParentBroker('child-mislabel-session', { rootDir: `${root}/broker` });
|
|
33
|
+
const capability = registerChild(broker, 'shepherd-agent-mislabel-child');
|
|
34
|
+
const child = createChildBroker({ rootDir: broker.rootDir, ...capability });
|
|
35
|
+
// Spawn-then-delegate: the launch carries no task id of its own.
|
|
36
|
+
process.env.PI_SHEPHERD_BROKER_DIR = broker.rootDir;
|
|
37
|
+
process.env.PI_SHEPHERD_BROKER_SESSION_ID = capability.sessionId;
|
|
38
|
+
process.env.PI_SHEPHERD_BROKER_ID = capability.brokerId;
|
|
39
|
+
process.env.PI_SHEPHERD_AGENT_ID = capability.agentId;
|
|
40
|
+
process.env.PI_SHEPHERD_BROKER_TOKEN = capability.token;
|
|
41
|
+
process.env.PI_SHEPHERD_AGENT_INBOX = capability.inboxPath;
|
|
42
|
+
delete process.env.PI_SHEPHERD_TASK_ID;
|
|
43
|
+
|
|
44
|
+
const registered = [];
|
|
45
|
+
const handlers = new Map();
|
|
46
|
+
const pi = {
|
|
47
|
+
registerTool(tool) {
|
|
48
|
+
registered.push(tool);
|
|
49
|
+
},
|
|
50
|
+
on(event, handler) {
|
|
51
|
+
handlers.set(event, handler);
|
|
52
|
+
},
|
|
53
|
+
sendUserMessage() {},
|
|
54
|
+
};
|
|
55
|
+
const { default: registerChildExtension } = await import(
|
|
56
|
+
'../src/extension/shepherd-done.ts'
|
|
57
|
+
);
|
|
58
|
+
registerChildExtension(pi);
|
|
59
|
+
const doneTool = registered.find(tool => tool.name === 'shepherd_done');
|
|
60
|
+
assert.ok(doneTool, 'shepherd_done is registered');
|
|
61
|
+
|
|
62
|
+
// 1. shepherd_done before any task arrives is rejected, not fabricated.
|
|
63
|
+
const rejected = await doneTool.execute('pre-task', {
|
|
64
|
+
taskId: 'T1234-1',
|
|
65
|
+
status: 'completed',
|
|
66
|
+
summary: 'Too early.',
|
|
67
|
+
});
|
|
68
|
+
assert.equal(rejected.details.returnCode, 1);
|
|
69
|
+
assert.equal(rejected.details.code, 'no_delegated_task');
|
|
70
|
+
assert.deepEqual(pollParentInbox(broker), []);
|
|
71
|
+
console.log('PASS child shepherd_done before any delegated task is rejected');
|
|
72
|
+
|
|
73
|
+
// 2. The delegated task id arrives with the kind: 'task' envelope.
|
|
74
|
+
const delegated = createEnvelope(
|
|
75
|
+
{ sessionId: broker.sessionId, brokerId: broker.brokerId, senderId: broker.parentId },
|
|
76
|
+
{
|
|
77
|
+
kind: 'task',
|
|
78
|
+
targetId: capability.agentId,
|
|
79
|
+
taskId: 'shepherd-task-mislabel-7ff36112',
|
|
80
|
+
delivery: 'followUp',
|
|
81
|
+
content: 'Implement the M2 engine wiring.',
|
|
82
|
+
}
|
|
83
|
+
);
|
|
84
|
+
publishFromParent(broker, delegated);
|
|
85
|
+
handlers.get('session_start')();
|
|
86
|
+
|
|
87
|
+
// 3. A fabricated echoed id is corrected to the delegated task id.
|
|
88
|
+
const corrected = await doneTool.execute('mislabel', {
|
|
89
|
+
taskId: 'T2854-9715',
|
|
90
|
+
status: 'completed',
|
|
91
|
+
summary: 'M2 engine wiring complete.',
|
|
92
|
+
});
|
|
93
|
+
assert.equal(corrected.details.returnCode, 0);
|
|
94
|
+
assert.equal(corrected.details.taskId, 'shepherd-task-mislabel-7ff36112');
|
|
95
|
+
assert.match(corrected.details.idMismatch, /T2854-9715/);
|
|
96
|
+
const published = pollParentInbox(broker).find(envelope => envelope.kind === 'task_done');
|
|
97
|
+
assert.ok(published, 'the completion is published');
|
|
98
|
+
assert.equal(published.taskId, 'shepherd-task-mislabel-7ff36112');
|
|
99
|
+
assert.equal(published.status, 'completed');
|
|
100
|
+
assert.equal(published.summary, 'M2 engine wiring complete.');
|
|
101
|
+
console.log('PASS child shepherd_done corrects a fabricated task id to the delegated task');
|
|
102
|
+
|
|
103
|
+
// 4. A matching id is published unchanged, with no correction note.
|
|
104
|
+
const clean = await doneTool.execute('clean', {
|
|
105
|
+
taskId: 'shepherd-task-mislabel-7ff36112',
|
|
106
|
+
status: 'completed',
|
|
107
|
+
summary: 'Again.',
|
|
108
|
+
});
|
|
109
|
+
assert.equal(clean.details.returnCode, 0);
|
|
110
|
+
assert.equal(clean.details.idMismatch, undefined);
|
|
111
|
+
const second = pollParentInbox(broker).find(envelope => envelope.kind === 'task_done');
|
|
112
|
+
assert.equal(second.taskId, 'shepherd-task-mislabel-7ff36112');
|
|
113
|
+
console.log('PASS child shepherd_done with the delegated task id is published unchanged');
|
|
114
|
+
|
|
115
|
+
// 5. Omitting the id completes the current delegated task (the default
|
|
116
|
+
// flow: the id is inferred from the child context, not pasted).
|
|
117
|
+
const omitted = await doneTool.execute('omit', {
|
|
118
|
+
status: 'completed',
|
|
119
|
+
summary: 'Omitted the id entirely.',
|
|
120
|
+
});
|
|
121
|
+
assert.equal(omitted.details.returnCode, 0);
|
|
122
|
+
assert.equal(omitted.details.taskId, 'shepherd-task-mislabel-7ff36112');
|
|
123
|
+
assert.equal(omitted.details.idMismatch, undefined);
|
|
124
|
+
const third = pollParentInbox(broker).find(envelope => envelope.kind === 'task_done');
|
|
125
|
+
assert.equal(third.taskId, 'shepherd-task-mislabel-7ff36112');
|
|
126
|
+
console.log('PASS child shepherd_done without a task id completes the current delegated task');
|
|
127
|
+
});
|
|
128
|
+
} finally {
|
|
129
|
+
for (const name of envNames) {
|
|
130
|
+
if (savedEnv[name] === undefined) delete process.env[name];
|
|
131
|
+
else process.env[name] = savedEnv[name];
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
console.log('All child mislabel assertions passed.');
|
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/** Phase 3 verification for the child-side messaging/completion extension. */
|
|
3
|
+
import assert from 'node:assert/strict';
|
|
4
|
+
import * as fs from 'node:fs';
|
|
5
|
+
import {
|
|
6
|
+
createChildBroker,
|
|
7
|
+
createEnvelope,
|
|
8
|
+
createParentBroker,
|
|
9
|
+
pollParentInbox,
|
|
10
|
+
publishFromChild,
|
|
11
|
+
publishFromParent,
|
|
12
|
+
registerChild,
|
|
13
|
+
} from '../src/core/messaging.ts';
|
|
14
|
+
import { withTempDirectory } from './helpers/test-utils.mjs';
|
|
15
|
+
|
|
16
|
+
const envNames = [
|
|
17
|
+
'PI_SHEPHERD_BROKER_DIR',
|
|
18
|
+
'PI_SHEPHERD_BROKER_SESSION_ID',
|
|
19
|
+
'PI_SHEPHERD_BROKER_ID',
|
|
20
|
+
'PI_SHEPHERD_AGENT_ID',
|
|
21
|
+
'PI_SHEPHERD_BROKER_TOKEN',
|
|
22
|
+
'PI_SHEPHERD_AGENT_INBOX',
|
|
23
|
+
'PI_SHEPHERD_TASK_ID',
|
|
24
|
+
'PI_SHEPHERD_SESSION',
|
|
25
|
+
];
|
|
26
|
+
const savedEnv = Object.fromEntries(envNames.map(name => [name, process.env[name]]));
|
|
27
|
+
|
|
28
|
+
try {
|
|
29
|
+
await withTempDirectory('pi-shepherd-child-', async root => {
|
|
30
|
+
const broker = createParentBroker('child-surface-session', { rootDir: `${root}/broker` });
|
|
31
|
+
const capability = registerChild(broker, 'shepherd-agent-child-surface');
|
|
32
|
+
const peerCapability = registerChild(broker, 'shepherd-agent-peer-surface');
|
|
33
|
+
const peerChild = createChildBroker({ rootDir: broker.rootDir, ...peerCapability });
|
|
34
|
+
process.env.PI_SHEPHERD_BROKER_DIR = broker.rootDir;
|
|
35
|
+
process.env.PI_SHEPHERD_BROKER_SESSION_ID = capability.sessionId;
|
|
36
|
+
process.env.PI_SHEPHERD_BROKER_ID = capability.brokerId;
|
|
37
|
+
process.env.PI_SHEPHERD_AGENT_ID = capability.agentId;
|
|
38
|
+
process.env.PI_SHEPHERD_BROKER_TOKEN = capability.token;
|
|
39
|
+
process.env.PI_SHEPHERD_AGENT_INBOX = capability.inboxPath;
|
|
40
|
+
process.env.PI_SHEPHERD_TASK_ID = 'shepherd-task-child-surface';
|
|
41
|
+
process.env.PI_SHEPHERD_SESSION = `${root}/child-session.jsonl`;
|
|
42
|
+
|
|
43
|
+
const registered = [];
|
|
44
|
+
const handlers = new Map();
|
|
45
|
+
const sentUserMessages = [];
|
|
46
|
+
const pi = {
|
|
47
|
+
registerTool(tool) {
|
|
48
|
+
registered.push(tool);
|
|
49
|
+
},
|
|
50
|
+
on(event, handler) {
|
|
51
|
+
handlers.set(event, handler);
|
|
52
|
+
},
|
|
53
|
+
sendUserMessage(content, options) {
|
|
54
|
+
sentUserMessages.push({ content, options });
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
const { default: registerChildExtension } = await import('../src/extension/shepherd-done.ts');
|
|
58
|
+
registerChildExtension(pi);
|
|
59
|
+
|
|
60
|
+
assert.deepEqual(
|
|
61
|
+
registered.map(tool => tool.name),
|
|
62
|
+
['shepherd_message', 'shepherd_done']
|
|
63
|
+
);
|
|
64
|
+
for (const tool of registered) {
|
|
65
|
+
assert.equal(tool.parameters.type, 'object');
|
|
66
|
+
assert.equal(typeof tool.name, 'string');
|
|
67
|
+
assert.equal(typeof tool.label, 'string');
|
|
68
|
+
assert.equal(typeof tool.description, 'string');
|
|
69
|
+
assert.equal(typeof tool.promptSnippet, 'string');
|
|
70
|
+
assert.equal(typeof tool.execute, 'function');
|
|
71
|
+
}
|
|
72
|
+
assert.ok(handlers.has('session_start'));
|
|
73
|
+
assert.ok(handlers.has('session_shutdown'));
|
|
74
|
+
assert.ok(handlers.has('agent_end'));
|
|
75
|
+
const messageTool = registered.find(tool => tool.name === 'shepherd_message');
|
|
76
|
+
assert.ok(messageTool.description.includes('exact opaque agent id returned by shepherd_spawn'));
|
|
77
|
+
assert.ok(messageTool.description.includes('agent definition name'));
|
|
78
|
+
assert.ok(messageTool.description.includes('will be rejected'));
|
|
79
|
+
assert.ok(messageTool.promptGuidelines.join(' ').includes('angle-bracket placeholder'));
|
|
80
|
+
console.log('PASS child registers only messaging and explicit completion tools');
|
|
81
|
+
|
|
82
|
+
const doneTool = registered.find(tool => tool.name === 'shepherd_done');
|
|
83
|
+
const messageResult = await messageTool.execute('message-call', {
|
|
84
|
+
target: 'shepherd',
|
|
85
|
+
message: 'Please review the authentication flow.',
|
|
86
|
+
expectsReply: true,
|
|
87
|
+
threadId: 'thread-child-surface',
|
|
88
|
+
delivery: 'followUp',
|
|
89
|
+
});
|
|
90
|
+
assert.equal(messageResult.details.returnCode, 0);
|
|
91
|
+
assert.match(messageResult.content[0].text, /call:\n shepherd_message/);
|
|
92
|
+
const inbox = pollParentInbox(broker);
|
|
93
|
+
const sentMessage = inbox.find(m => m.kind === 'message');
|
|
94
|
+
assert.ok(sentMessage, 'question envelope is queued in the parent inbox');
|
|
95
|
+
assert.equal(sentMessage.senderId, capability.agentId);
|
|
96
|
+
assert.equal(sentMessage.targetId, 'shepherd');
|
|
97
|
+
assert.equal(sentMessage.expectsReply, true);
|
|
98
|
+
assert.equal(sentMessage.threadId, 'thread-child-surface');
|
|
99
|
+
const mirror = inbox.find(m => m.kind === 'runtime');
|
|
100
|
+
assert.ok(mirror, 'tracked request is mirrored to the parent for task correlation');
|
|
101
|
+
assert.equal(mirror.requestOpen, true);
|
|
102
|
+
assert.equal(mirror.replyTo, sentMessage.messageId);
|
|
103
|
+
assert.equal(mirror.targetId, 'shepherd');
|
|
104
|
+
console.log('PASS child shepherd_message publishes an asynchronous correlated envelope');
|
|
105
|
+
|
|
106
|
+
const invalidTargetResult = await messageTool.execute('invalid-target-call', {
|
|
107
|
+
target: 'planner',
|
|
108
|
+
message: 'This must not be routed by display name.',
|
|
109
|
+
});
|
|
110
|
+
assert.equal(invalidTargetResult.details.returnCode, 1);
|
|
111
|
+
assert.equal(invalidTargetResult.details.code, 'invalid_target');
|
|
112
|
+
assert.match(
|
|
113
|
+
invalidTargetResult.content[0].text,
|
|
114
|
+
/exact opaque agent id returned by shepherd_spawn/
|
|
115
|
+
);
|
|
116
|
+
assert.match(invalidTargetResult.content[0].text, /agent name such as "planner"/);
|
|
117
|
+
assert.deepEqual(
|
|
118
|
+
pollParentInbox(broker),
|
|
119
|
+
[],
|
|
120
|
+
'invalid peer target is rejected before any message is queued'
|
|
121
|
+
);
|
|
122
|
+
console.log(
|
|
123
|
+
'PASS child shepherd_message rejects agent names instead of treating them as peer ids'
|
|
124
|
+
);
|
|
125
|
+
|
|
126
|
+
const doneResult = await doneTool.execute('done-call', {
|
|
127
|
+
taskId: 'shepherd-task-child-surface',
|
|
128
|
+
status: 'completed',
|
|
129
|
+
summary: 'Review completed.',
|
|
130
|
+
});
|
|
131
|
+
assert.equal(doneResult.details.returnCode, 0);
|
|
132
|
+
assert.match(doneResult.content[0].text, /call:\n shepherd_done/);
|
|
133
|
+
const completion = pollParentInbox(broker)[0];
|
|
134
|
+
assert.equal(completion.kind, 'task_done');
|
|
135
|
+
assert.equal(completion.taskId, 'shepherd-task-child-surface');
|
|
136
|
+
assert.equal(completion.status, 'completed');
|
|
137
|
+
assert.equal(completion.summary, 'Review completed.');
|
|
138
|
+
console.log('PASS child shepherd_done publishes an explicit task-done envelope');
|
|
139
|
+
const duplicateDone = await doneTool.execute('done-call-again', {
|
|
140
|
+
taskId: 'shepherd-task-child-surface',
|
|
141
|
+
status: 'completed',
|
|
142
|
+
summary: 'A different summary must not create a second completion.',
|
|
143
|
+
});
|
|
144
|
+
assert.equal(duplicateDone.details.returnCode, 0);
|
|
145
|
+
const retryCompletion = pollParentInbox(broker)[0];
|
|
146
|
+
assert.equal(retryCompletion.kind, 'task_done');
|
|
147
|
+
assert.equal(retryCompletion.taskId, 'shepherd-task-child-surface');
|
|
148
|
+
console.log(
|
|
149
|
+
'PASS repeated child shepherd_done calls remain safe for parent idempotent settlement'
|
|
150
|
+
);
|
|
151
|
+
|
|
152
|
+
const omittedDone = await doneTool.execute('done-call-omitted', {
|
|
153
|
+
status: 'completed',
|
|
154
|
+
summary: 'Completed without pasting the id.',
|
|
155
|
+
});
|
|
156
|
+
assert.equal(omittedDone.details.returnCode, 0);
|
|
157
|
+
assert.equal(omittedDone.details.taskId, 'shepherd-task-child-surface');
|
|
158
|
+
assert.equal(omittedDone.details.idMismatch, undefined);
|
|
159
|
+
const omittedEnvelope = pollParentInbox(broker).find(envelope => envelope.kind === 'task_done');
|
|
160
|
+
assert.equal(omittedEnvelope.taskId, 'shepherd-task-child-surface');
|
|
161
|
+
console.log('PASS child shepherd_done without a task id uses the launch-time task id');
|
|
162
|
+
|
|
163
|
+
let shutdowns = 0;
|
|
164
|
+
await handlers.get('agent_end')(
|
|
165
|
+
{ messages: [{ role: 'assistant', stopReason: 'stop' }] },
|
|
166
|
+
{
|
|
167
|
+
shutdown() {
|
|
168
|
+
shutdowns += 1;
|
|
169
|
+
},
|
|
170
|
+
}
|
|
171
|
+
);
|
|
172
|
+
assert.equal(shutdowns, 0);
|
|
173
|
+
assert.equal(fs.existsSync(`${root}/child-session.jsonl.exit`), false);
|
|
174
|
+
console.log('PASS normal agent_end does not complete or shut down a tracked task');
|
|
175
|
+
|
|
176
|
+
const incoming = createEnvelope(
|
|
177
|
+
{ sessionId: broker.sessionId, brokerId: broker.brokerId, senderId: broker.parentId },
|
|
178
|
+
{
|
|
179
|
+
kind: 'reply',
|
|
180
|
+
targetId: capability.agentId,
|
|
181
|
+
taskId: 'shepherd-task-child-surface',
|
|
182
|
+
threadId: 'thread-child-surface',
|
|
183
|
+
replyTo: 'request-123',
|
|
184
|
+
delivery: 'steer',
|
|
185
|
+
content: 'The middleware is in src/auth/session.ts.',
|
|
186
|
+
}
|
|
187
|
+
);
|
|
188
|
+
publishFromParent(broker, incoming);
|
|
189
|
+
await handlers.get('session_start')({}, {});
|
|
190
|
+
assert.equal(sentUserMessages.length, 1);
|
|
191
|
+
assert.match(sentUserMessages[0].content, /Shepherd message from Shepherd/);
|
|
192
|
+
assert.match(sentUserMessages[0].content, /Reply to: request-123/);
|
|
193
|
+
assert.equal(sentUserMessages[0].options.deliverAs, 'steer');
|
|
194
|
+
assert.equal(sentUserMessages[0].options.triggerTurn, true);
|
|
195
|
+
assert.ok(
|
|
196
|
+
messageTool.promptGuidelines.some(guideline =>
|
|
197
|
+
guideline.includes('request, not your own task ID')
|
|
198
|
+
),
|
|
199
|
+
'child guidance explains requester task id for replies'
|
|
200
|
+
);
|
|
201
|
+
await new Promise(resolve => setTimeout(resolve, 300));
|
|
202
|
+
const mismatchedReply = await messageTool.execute('mismatched-reply', {
|
|
203
|
+
target: 'shepherd',
|
|
204
|
+
message: 'This must be rejected.',
|
|
205
|
+
taskId: 'shepherd-task-wrong-owner',
|
|
206
|
+
replyTo: 'request-123',
|
|
207
|
+
});
|
|
208
|
+
assert.equal(mismatchedReply.details.returnCode, 1);
|
|
209
|
+
assert.equal(mismatchedReply.details.code, 'reply_task_mismatch');
|
|
210
|
+
const inferredReply = await messageTool.execute('inferred-reply', {
|
|
211
|
+
target: 'shepherd',
|
|
212
|
+
message: 'The reply task id should be inferred.',
|
|
213
|
+
replyTo: 'request-123',
|
|
214
|
+
});
|
|
215
|
+
assert.equal(inferredReply.details.returnCode, 0);
|
|
216
|
+
const inferredEnvelope = pollParentInbox(broker).find(m => m.replyTo === 'request-123');
|
|
217
|
+
assert.ok(inferredEnvelope, 'reply with omitted taskId is published');
|
|
218
|
+
assert.equal(inferredEnvelope.taskId, 'shepherd-task-child-surface');
|
|
219
|
+
console.log('PASS child replies infer the requester task id and reject mismatched task ids');
|
|
220
|
+
|
|
221
|
+
const peerRequest = createEnvelope(
|
|
222
|
+
{ sessionId: peerChild.sessionId, brokerId: peerChild.brokerId, senderId: peerChild.agentId },
|
|
223
|
+
{
|
|
224
|
+
kind: 'message',
|
|
225
|
+
targetId: capability.agentId,
|
|
226
|
+
taskId: 'shepherd-task-child-surface',
|
|
227
|
+
replyTo: undefined,
|
|
228
|
+
expectsReply: true,
|
|
229
|
+
delivery: 'followUp',
|
|
230
|
+
content: 'Reply directly to this peer request.',
|
|
231
|
+
}
|
|
232
|
+
);
|
|
233
|
+
publishFromChild(peerChild, peerRequest);
|
|
234
|
+
await new Promise(resolve => setTimeout(resolve, 300));
|
|
235
|
+
const directPeerReply = await messageTool.execute('direct-peer-reply', {
|
|
236
|
+
target: peerChild.agentId,
|
|
237
|
+
message: 'pong',
|
|
238
|
+
replyTo: peerRequest.messageId,
|
|
239
|
+
});
|
|
240
|
+
assert.equal(directPeerReply.details.returnCode, 0);
|
|
241
|
+
const replyMirror = pollParentInbox(broker).find(
|
|
242
|
+
message =>
|
|
243
|
+
message.kind === 'runtime' &&
|
|
244
|
+
message.replyReceived === true &&
|
|
245
|
+
message.replyTo === peerRequest.messageId
|
|
246
|
+
);
|
|
247
|
+
assert.ok(replyMirror, 'direct peer replies mirror correlation to the parent');
|
|
248
|
+
assert.equal(replyMirror.taskId, 'shepherd-task-child-surface');
|
|
249
|
+
console.log('PASS direct peer replies notify the parent without requiring a duplicate relay');
|
|
250
|
+
|
|
251
|
+
// A failed local delivery is reported to the parent as a runtime
|
|
252
|
+
// diagnostic correlated with the undelivered message id.
|
|
253
|
+
const failing = [
|
|
254
|
+
{ sessionId: broker.sessionId, brokerId: broker.brokerId, senderId: broker.parentId },
|
|
255
|
+
{
|
|
256
|
+
kind: 'message',
|
|
257
|
+
targetId: capability.agentId,
|
|
258
|
+
delivery: 'followUp',
|
|
259
|
+
content: 'This one cannot be delivered.',
|
|
260
|
+
},
|
|
261
|
+
];
|
|
262
|
+
const failingEnvelope = createEnvelope(failing[0], failing[1]);
|
|
263
|
+
publishFromParent(broker, failingEnvelope);
|
|
264
|
+
let deliverFailures = 0;
|
|
265
|
+
const realSend = pi.sendUserMessage.bind(pi);
|
|
266
|
+
pi.sendUserMessage = (content, options) => {
|
|
267
|
+
deliverFailures += 1;
|
|
268
|
+
throw new Error('renderer unavailable');
|
|
269
|
+
};
|
|
270
|
+
// The 250ms poll interval from the earlier session_start delivers the
|
|
271
|
+
// message through the now-failing sender.
|
|
272
|
+
await new Promise(resolve => setTimeout(resolve, 400));
|
|
273
|
+
assert.equal(deliverFailures, 1);
|
|
274
|
+
const diagnostics = pollParentInbox(broker);
|
|
275
|
+
const diagnostic = diagnostics.find(
|
|
276
|
+
m => m.kind === 'runtime' && String(m.content).includes(failingEnvelope.messageId)
|
|
277
|
+
);
|
|
278
|
+
assert.ok(diagnostic, 'failed delivery produces a runtime diagnostic in the parent inbox');
|
|
279
|
+
assert.equal(diagnostic.error, 'renderer unavailable');
|
|
280
|
+
assert.equal(
|
|
281
|
+
diagnostic.summary,
|
|
282
|
+
undefined || diagnostic.summary,
|
|
283
|
+
'diagnostic carries the failure detail'
|
|
284
|
+
);
|
|
285
|
+
pi.sendUserMessage = realSend;
|
|
286
|
+
await handlers.get('session_shutdown')({}, {});
|
|
287
|
+
console.log('PASS failed local message delivery is reported to the parent with the message id');
|
|
288
|
+
console.log('PASS child polling queues incoming messages with requested delivery mode');
|
|
289
|
+
});
|
|
290
|
+
|
|
291
|
+
// The child surface remains loadable for legacy launches that have not yet
|
|
292
|
+
// been wired to a parent broker. Tool calls fail clearly instead of trying
|
|
293
|
+
// to invent a session or writing outside an owned mailbox.
|
|
294
|
+
for (const name of envNames) delete process.env[name];
|
|
295
|
+
const registered = [];
|
|
296
|
+
const pi = {
|
|
297
|
+
registerTool(tool) {
|
|
298
|
+
registered.push(tool);
|
|
299
|
+
},
|
|
300
|
+
on() {},
|
|
301
|
+
sendUserMessage() {
|
|
302
|
+
throw new Error('must not deliver without broker');
|
|
303
|
+
},
|
|
304
|
+
};
|
|
305
|
+
const { default: registerChildExtension } = await import('../src/extension/shepherd-done.ts');
|
|
306
|
+
registerChildExtension(pi);
|
|
307
|
+
const result = await registered[0].execute('missing-broker', {
|
|
308
|
+
target: 'shepherd',
|
|
309
|
+
message: 'This should be rejected.',
|
|
310
|
+
});
|
|
311
|
+
assert.equal(result.details.returnCode, 1);
|
|
312
|
+
assert.equal(result.details.code, 'broker_unavailable');
|
|
313
|
+
console.log('PASS child tools fail safely when no broker capability is configured');
|
|
314
|
+
} finally {
|
|
315
|
+
for (const name of envNames) {
|
|
316
|
+
if (savedEnv[name] === undefined) delete process.env[name];
|
|
317
|
+
else process.env[name] = savedEnv[name];
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
console.log('All child-surface assertions passed.');
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
// verify-cli.mjs
|
|
2
|
+
//
|
|
3
|
+
// The CLI grammar in cli.ts is the shared contract between the human
|
|
4
|
+
// `/shepherd` command (parse) and the tool-call previews (format). It must:
|
|
5
|
+
// - parse every command action into doAction args,
|
|
6
|
+
// - reject bad input with a usage hint,
|
|
7
|
+
// - round-trip: render(parse(x)) parses back to the same args
|
|
8
|
+
// (the renderer and parser share one OPTION_SPECS table).
|
|
9
|
+
// (see docs/plans/tool-surface-split.md §4).
|
|
10
|
+
import {
|
|
11
|
+
parseShepherdCli,
|
|
12
|
+
formatShepherdCommand,
|
|
13
|
+
statusHandleTarget,
|
|
14
|
+
tokenizeCli,
|
|
15
|
+
} from '../src/extension/cli.ts';
|
|
16
|
+
import { lifecycleRegistry } from '../src/core/orchestration.ts';
|
|
17
|
+
|
|
18
|
+
let failures = 0;
|
|
19
|
+
function check(ok, label) {
|
|
20
|
+
console.log(`${ok ? 'PASS' : 'FAIL'} ${label}`);
|
|
21
|
+
if (!ok) failures++;
|
|
22
|
+
}
|
|
23
|
+
function isError(result) {
|
|
24
|
+
return typeof result === 'object' && result !== null && 'error' in result;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
// Parse -> doAction args (action + the parsed payload).
|
|
28
|
+
function parsed(toks) {
|
|
29
|
+
const p = parseShepherdCli(toks);
|
|
30
|
+
if (isError(p)) return { error: p.error };
|
|
31
|
+
return { args: p.args, action: p.action };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// ── Positive parses ─────────────────────────────────────────────────────────
|
|
35
|
+
|
|
36
|
+
const a = parsed(['agents']);
|
|
37
|
+
check(!isError(a) && a.args.agentScope === undefined, 'agents: no scope');
|
|
38
|
+
check(parsed(['agents', 'both']).args.agentScope === 'both', 'agents both: positional scope');
|
|
39
|
+
check(
|
|
40
|
+
parsed(['agents', '--scope', 'project']).args.agentScope === 'project',
|
|
41
|
+
'agents --scope: flag scope'
|
|
42
|
+
);
|
|
43
|
+
|
|
44
|
+
const okHerd = parsed(['herd']);
|
|
45
|
+
check(
|
|
46
|
+
!isError(okHerd) && JSON.stringify(okHerd.args) === JSON.stringify({ action: 'herd' }),
|
|
47
|
+
'herd: bare'
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
const okSpawn = parsed(['spawn', 'worker']);
|
|
51
|
+
check(
|
|
52
|
+
!isError(okSpawn) && okSpawn.args.agent === 'worker' && okSpawn.action === 'spawn',
|
|
53
|
+
'spawn worker: agent name'
|
|
54
|
+
);
|
|
55
|
+
|
|
56
|
+
const okSpawnFlags = parsed(['spawn', 'worker', '--placement=pane_down', '--label=down-split']);
|
|
57
|
+
check(
|
|
58
|
+
okSpawnFlags.args.placement === 'pane_down' &&
|
|
59
|
+
okSpawnFlags.args.label === 'down-split' &&
|
|
60
|
+
!('direction' in okSpawnFlags.args),
|
|
61
|
+
'spawn: placement encodes pane direction'
|
|
62
|
+
);
|
|
63
|
+
|
|
64
|
+
const okSpawnSpace = parsed(['spawn', 'scout', '--cwd', '/tmp/x']);
|
|
65
|
+
check(
|
|
66
|
+
okSpawnSpace.args.cwd === '/tmp/x' &&
|
|
67
|
+
!('model' in okSpawnSpace.args) &&
|
|
68
|
+
!('agentScope' in okSpawnSpace.args),
|
|
69
|
+
'spawn: optional cwd value; model comes from the agent definition'
|
|
70
|
+
);
|
|
71
|
+
|
|
72
|
+
okReadChecks();
|
|
73
|
+
function okReadChecks() {
|
|
74
|
+
const okRead = parsed(['read', 'pane123', '--lines=10', '--source=recent']);
|
|
75
|
+
check(
|
|
76
|
+
okRead.args.name === 'pane123' && okRead.args.lines === 10 && okRead.args.source === 'recent',
|
|
77
|
+
'read: name + integer lines + source enum'
|
|
78
|
+
);
|
|
79
|
+
const okReadSpace = parsed(['read', 'p5', '--lines', '7', '--source', 'visible']);
|
|
80
|
+
check(
|
|
81
|
+
okReadSpace.args.lines === 7 && okReadSpace.args.source === 'visible',
|
|
82
|
+
'read: space-separated options'
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const okStatus = parsed(['status', 'worker']);
|
|
87
|
+
check(
|
|
88
|
+
!isError(okStatus) && okStatus.args.id === 'worker',
|
|
89
|
+
'status: unknown target degrades to opaque id'
|
|
90
|
+
);
|
|
91
|
+
|
|
92
|
+
// statusHandleTarget resolves a live agent by name or pane id.
|
|
93
|
+
const liveAgent = lifecycleRegistry.registerAgent({ agent: 'live-scout', paneId: 'wT:p1' });
|
|
94
|
+
check(
|
|
95
|
+
statusHandleTarget('live-scout') === liveAgent.id,
|
|
96
|
+
'status target resolves live agent by name'
|
|
97
|
+
);
|
|
98
|
+
check(statusHandleTarget('wT:p1') === liveAgent.id, 'status target resolves live agent by pane id');
|
|
99
|
+
|
|
100
|
+
// ── Negative parses ─────────────────────────────────────────────────────────
|
|
101
|
+
|
|
102
|
+
const shouldFail = [
|
|
103
|
+
[['spawn'], 'spawn requires an agent name'],
|
|
104
|
+
[['spawn', 'a', 'b'], 'Unexpected argument "b"'],
|
|
105
|
+
[['herd', 'x'], 'herd takes no arguments'],
|
|
106
|
+
[['agents', 'both', 'user'], 'agents takes at most one'],
|
|
107
|
+
[['agents', 'both', '--scope=user'], 'agents takes at most one'],
|
|
108
|
+
[['spawn', 'w', '--placement=up'], 'Invalid value "up" for --placement'],
|
|
109
|
+
[['spawn', 'w', '--direction=down'], 'Unknown option "--direction"'],
|
|
110
|
+
[['spawn', 'w', '--scope=project'], 'Unknown option "--scope"'],
|
|
111
|
+
[['spawn', 'w', '--confirm-project-agents=false'], 'Unknown option "--confirm-project-agents"'],
|
|
112
|
+
[['spawn', 'w', '--omit-system-prompt'], 'Unknown option "--omit-system-prompt"'],
|
|
113
|
+
[['spawn', 'w', '--bogus=1'], 'Unknown option "--bogus"'],
|
|
114
|
+
[['read', 'p', '--scope=user'], 'Unknown option "--scope"'], // spawn flag not allowed for read
|
|
115
|
+
[['read', 'p', '--lines=abc'], 'must be an integer'],
|
|
116
|
+
[['read', 'p', '--source=bogus'], 'Invalid value "bogus" for --source'],
|
|
117
|
+
[['wat'], 'Unknown action'],
|
|
118
|
+
[[], 'Provide an action'],
|
|
119
|
+
[['status'], 'status requires'],
|
|
120
|
+
[['status', 'a', 'b'], 'takes exactly one'],
|
|
121
|
+
[['spawn', 'w', '--cwd'], 'Missing value for --cwd'],
|
|
122
|
+
];
|
|
123
|
+
for (const [toks, hint] of shouldFail) {
|
|
124
|
+
const p = parsed(toks);
|
|
125
|
+
const pass = isError(p) && p.error.includes(hint) && p.error.includes('Usage');
|
|
126
|
+
check(
|
|
127
|
+
pass,
|
|
128
|
+
`rejects ${JSON.stringify(toks)}${p.error ? '' : ' (parsed: ' + JSON.stringify(p.args) + ')'}`
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// ── Round-trip: parse(x) → render → tokenize → reparse → same args ─────────
|
|
133
|
+
|
|
134
|
+
// tokenizeCli is the exact inverse of formatShepherdCommand's quoting: quoted
|
|
135
|
+
// values are decoded and rejoined onto their `--flag=` prefix, so a rendered
|
|
136
|
+
// line reparses to the same args.
|
|
137
|
+
function tokenizePreview(rest) {
|
|
138
|
+
return tokenizeCli(rest);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function roundTrip(toks) {
|
|
142
|
+
const p = parsed(toks);
|
|
143
|
+
if (isError(p)) return `parse error unexpectedly: ${p.error}`;
|
|
144
|
+
const fmt = formatShepherdCommand(p.action, p.args);
|
|
145
|
+
const reparsed = parseShepherdCli([p.action, ...tokenizePreview(fmt.rest)]);
|
|
146
|
+
if (isError(reparsed)) return `reparse error: ${reparsed.error}`;
|
|
147
|
+
const drop = o => {
|
|
148
|
+
const copy = { ...o };
|
|
149
|
+
// Key insertion order can differ between the parsed line and the
|
|
150
|
+
// rendered one (positional vs. --scope spellings); compare canonically.
|
|
151
|
+
return Object.fromEntries(Object.entries(copy).sort(([a], [b]) => a.localeCompare(b)));
|
|
152
|
+
};
|
|
153
|
+
return p.action === reparsed.action &&
|
|
154
|
+
JSON.stringify(drop(p.args)) === JSON.stringify(drop(reparsed.args))
|
|
155
|
+
? null
|
|
156
|
+
: `mismatch: ${JSON.stringify(p.args)} vs ${JSON.stringify(reparsed.args)}`;
|
|
157
|
+
}
|
|
158
|
+
for (const toks of [
|
|
159
|
+
['agents'],
|
|
160
|
+
['agents', 'project'],
|
|
161
|
+
['herd'],
|
|
162
|
+
['spawn', 'worker'],
|
|
163
|
+
['spawn', 'worker', '--placement=pane_down'],
|
|
164
|
+
['spawn', 'scout', '--cwd=/a b'],
|
|
165
|
+
['read', 'p5', '--lines=7', '--source=visible'],
|
|
166
|
+
]) {
|
|
167
|
+
const err = roundTrip(toks);
|
|
168
|
+
check(err === null, `round-trip ${toks.join(' ')}${err ? ` — ${err}` : ''}`);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// The spawn preview is CLI-style: `spawn scout --cwd=/a b` (quoted if needed).
|
|
172
|
+
const preview = formatShepherdCommand('spawn', { agent: 'scout', cwd: '/a b' });
|
|
173
|
+
check(
|
|
174
|
+
preview.verb === 'spawn' &&
|
|
175
|
+
preview.rest.includes('scout') &&
|
|
176
|
+
preview.rest.includes('--cwd="') &&
|
|
177
|
+
!preview.rest.includes('--scope') &&
|
|
178
|
+
!preview.rest.includes('--direction'),
|
|
179
|
+
'preview: spawn renders verb + positional + quoted --cwd'
|
|
180
|
+
);
|
|
181
|
+
|
|
182
|
+
const defaultsPreview = formatShepherdCommand('spawn', {
|
|
183
|
+
agent: 'scout',
|
|
184
|
+
label: '10-second required-args smoke test',
|
|
185
|
+
placement: 'tab',
|
|
186
|
+
cwd: process.cwd(),
|
|
187
|
+
});
|
|
188
|
+
check(
|
|
189
|
+
defaultsPreview.rest === 'scout --label="10-second required-args smoke test"',
|
|
190
|
+
'preview: spawn omits materialized default placement and cwd'
|
|
191
|
+
);
|
|
192
|
+
|
|
193
|
+
if (failures > 0) {
|
|
194
|
+
console.log(`\n${failures} CLI assertion(s) failed.`);
|
|
195
|
+
process.exit(1);
|
|
196
|
+
}
|
|
197
|
+
console.log('\nAll CLI grammar assertions passed.');
|