agents-relay 2.0.203 → 2.0.205
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/dist/agent-content-resolver.js +23 -10
- package/dist/agent-shortcut.js +469 -0
- package/dist/cli-context.js +21 -0
- package/dist/cli-help.js +26 -5
- package/dist/cli-job-create.js +3 -2
- package/dist/cli-shortcut.js +93 -0
- package/dist/cli.js +26 -21
- package/dist/events-bus-runtime.js +3 -1
- package/dist/job-execution-slot.js +10 -2
- package/dist/outcome-review.js +4 -1
- package/dist/pool.js +1 -1
- package/dist/reconciler-context.js +18 -0
- package/dist/reconciler-shortcut.js +66 -0
- package/dist/reconciler.js +22 -19
- package/dist/relay-job-snapshot-reads.js +1 -1
- package/dist/relay-workflow-operations.js +12 -3
- package/dist/relayd-control.js +6 -3
- package/dist/task-actions.js +17 -2
- package/dist/workflow/action-ledger.js +1 -1
- package/dist/workflow/contracts.js +27 -0
- package/dist/workflow/definitions-v2.js +7 -1
- package/dist/workflow/runtime.js +9 -0
- package/dist/workflow/task-resolution.js +7 -2
- package/package.json +1 -1
- package/workflow/job-lifecycle.mmd +4 -0
- package/workflow/task-lifecycle.mmd +31 -1
- package/workflow/task-resolution.mmd +6 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
2
|
import { readFile, realpath } from 'node:fs/promises';
|
|
3
|
-
import { dirname, join, resolve } from 'node:path';
|
|
3
|
+
import { dirname, isAbsolute, join, resolve } from 'node:path';
|
|
4
4
|
const parseList = (raw) => raw.trim().replace(/^\[/, '').replace(/\]$/, '').split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
|
|
5
5
|
/** Restrict the frontmatter grammar to the explicitly supported scalar/list fields. */
|
|
6
6
|
function parseDocument(raw) {
|
|
@@ -18,7 +18,7 @@ function parseDocument(raw) {
|
|
|
18
18
|
if (field[1] === 'name')
|
|
19
19
|
name = field[2].trim();
|
|
20
20
|
if (field[1] === 'extends')
|
|
21
|
-
extendsAgent = field[2].trim();
|
|
21
|
+
extendsAgent = field[2].trim().replace(/^[\'"]|[\'"]$/g, '');
|
|
22
22
|
if (field[1] === 'mode') {
|
|
23
23
|
if (!['extend', 'replace'].includes(field[2].trim()))
|
|
24
24
|
throw new Error(`Invalid agent mode: ${field[2]}`);
|
|
@@ -125,7 +125,7 @@ function mergeSections(base, child) {
|
|
|
125
125
|
export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoRoot) {
|
|
126
126
|
if (!/^[a-zA-Z0-9_-]+$/.test(name))
|
|
127
127
|
throw new Error(`Invalid agent name ${name}`);
|
|
128
|
-
const load = async (path, root) => {
|
|
128
|
+
const load = async (path, root, expectedName) => {
|
|
129
129
|
const canonical = await realpath(path);
|
|
130
130
|
const canonicalRoot = await realpath(root);
|
|
131
131
|
if (!(canonical === canonicalRoot || canonical.startsWith(canonicalRoot + '/')))
|
|
@@ -133,8 +133,8 @@ export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoR
|
|
|
133
133
|
const raw = await readFile(canonical, 'utf8');
|
|
134
134
|
const source = parseDocument(raw);
|
|
135
135
|
source.body = absoluteAgentLinks(source.body, canonical);
|
|
136
|
-
if (source.name && source.name !==
|
|
137
|
-
throw new Error(`Agent name mismatch ${source.name} != ${
|
|
136
|
+
if (expectedName && source.name && source.name !== expectedName)
|
|
137
|
+
throw new Error(`Agent name mismatch ${source.name} != ${expectedName}`);
|
|
138
138
|
return { ...source, path: canonical, metadata: Object.fromEntries(raw.match(/^---\r?\n([\s\S]*?)\r?\n---/m)?.[1].split(/\r?\n/).flatMap(line => {
|
|
139
139
|
const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
|
|
140
140
|
return field ? [[field[1], field[2].trim().replace(/^['"]|['"]$/g, '')]] : [];
|
|
@@ -143,7 +143,7 @@ export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoR
|
|
|
143
143
|
const loadLayer = async (root) => {
|
|
144
144
|
for (const suffix of ['.agent.md', '.md']) {
|
|
145
145
|
try {
|
|
146
|
-
return await load(join(root, `${name}${suffix}`), root);
|
|
146
|
+
return await load(join(root, `${name}${suffix}`), root, name);
|
|
147
147
|
}
|
|
148
148
|
catch (error) {
|
|
149
149
|
if (error.code !== 'ENOENT')
|
|
@@ -181,8 +181,8 @@ export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoR
|
|
|
181
181
|
const hasOperations = overlay.replace.length || overlay.extend.length;
|
|
182
182
|
if (hasOperations && !overlay.extendsAgent)
|
|
183
183
|
throw new Error('Section operations require extends');
|
|
184
|
-
if (overlay.extendsAgent && ![`relay/${name}`, `neo/${name}`].includes(overlay.extendsAgent))
|
|
185
|
-
throw new Error(`Only extends: relay/${name}
|
|
184
|
+
if (overlay.extendsAgent && !isAbsolute(overlay.extendsAgent) && ![`relay/${name}`, `neo/${name}`].includes(overlay.extendsAgent))
|
|
185
|
+
throw new Error(`Only extends: relay/${name}, neo/${name}, or an absolute Markdown path is supported`);
|
|
186
186
|
if (layer === 'neo' && overlay.extendsAgent === `neo/${name}`)
|
|
187
187
|
throw new Error(`Missing Neo base for agent ${name}`);
|
|
188
188
|
if (overlay.extendsAgent === `relay/${name}` && !base)
|
|
@@ -195,10 +195,23 @@ export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoR
|
|
|
195
195
|
sources = [overlay.path];
|
|
196
196
|
}
|
|
197
197
|
else {
|
|
198
|
-
|
|
198
|
+
// An explicit absolute base is supplied by the author of this Agent, not discovered by Relay.
|
|
199
|
+
// Keep the base's own name; it need not match the project Agent's name.
|
|
200
|
+
let external;
|
|
201
|
+
if (isAbsolute(overlay.extendsAgent)) {
|
|
202
|
+
const path = overlay.extendsAgent;
|
|
203
|
+
if (!path.endsWith('.md'))
|
|
204
|
+
throw new Error('Absolute Agent base must be a Markdown file');
|
|
205
|
+
external = await load(path, dirname(path));
|
|
206
|
+
if (!external.name || !external.body)
|
|
207
|
+
throw new Error('Absolute Agent base requires name frontmatter and nonempty body');
|
|
208
|
+
if (external.extendsAgent)
|
|
209
|
+
throw new Error('Absolute Agent base must be a standalone definition');
|
|
210
|
+
}
|
|
211
|
+
const parent = external ?? (overlay.extendsAgent === `relay/${name}` ? base : overlay.extendsAgent === `neo/${name}` ? shared : effective);
|
|
199
212
|
effective = { ...overlay, body: mergeSections(parent.body, overlay) };
|
|
200
213
|
metadata = { ...parent.metadata };
|
|
201
|
-
sources = [...(overlay.extendsAgent === `relay/${name}` ? [base.path] : overlay.extendsAgent === `neo/${name}` ? sharedSources : sources), overlay.path];
|
|
214
|
+
sources = [...(external ? [external.path] : overlay.extendsAgent === `relay/${name}` ? [base.path] : overlay.extendsAgent === `neo/${name}` ? sharedSources : sources), overlay.path];
|
|
202
215
|
}
|
|
203
216
|
Object.assign(metadata, overlay.metadata);
|
|
204
217
|
if (layer === 'neo') {
|
|
@@ -0,0 +1,469 @@
|
|
|
1
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
2
|
+
import { existsSync } from 'node:fs';
|
|
3
|
+
import { readFile } from 'node:fs/promises';
|
|
4
|
+
import { resolve, relative, isAbsolute, sep } from 'node:path';
|
|
5
|
+
import { realpath } from 'node:fs/promises';
|
|
6
|
+
import { once } from 'node:events';
|
|
7
|
+
import { pathToFileURL } from 'node:url';
|
|
8
|
+
import { spawnOwnedProcess } from './owned-process.js';
|
|
9
|
+
import { parseAgentGraph } from './agent-graph.js';
|
|
10
|
+
import { DurableTaskTransitionRuntime } from './workflow/durable-transition.js';
|
|
11
|
+
import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
|
|
12
|
+
import { dependencyReady } from './task-transitions.js';
|
|
13
|
+
const digest = (value) => createHash('sha256').update(value).digest('hex');
|
|
14
|
+
const digestBytes = (value) => createHash('sha256').update(value).digest('hex');
|
|
15
|
+
function canonical(value) {
|
|
16
|
+
if (Array.isArray(value))
|
|
17
|
+
return `[${value.map(canonical).join(',')}]`;
|
|
18
|
+
if (value && typeof value === 'object')
|
|
19
|
+
return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
|
|
20
|
+
return JSON.stringify(value) ?? 'null';
|
|
21
|
+
}
|
|
22
|
+
function checkpoint(task) {
|
|
23
|
+
const data = task.result?.data?.shortcut;
|
|
24
|
+
return data && typeof data === 'object' ? structuredClone(data) : { version: 1, graphHash: '', inputHash: '', shortcutHash: '', nodes: {}, waits: {}, artifactHashes: {} };
|
|
25
|
+
}
|
|
26
|
+
function validOutput(value) {
|
|
27
|
+
return Boolean(value && typeof value === 'object' && !Array.isArray(value) && value.status === 'COMPLETED'
|
|
28
|
+
&& value.output && typeof value.output === 'object'
|
|
29
|
+
&& !Array.isArray(value.output)
|
|
30
|
+
&& ((Array.isArray(value.artifacts) && value.artifacts.every(item => typeof item === 'string'))
|
|
31
|
+
|| (Boolean(value.artifacts) && typeof value.artifacts === 'object' && !Array.isArray(value.artifacts))));
|
|
32
|
+
}
|
|
33
|
+
export function shortcutContentSha256(output) { return digest(canonical(output)); }
|
|
34
|
+
export async function recordShortcutReceipt(store, identity) {
|
|
35
|
+
if (!store.mutateJob)
|
|
36
|
+
throw new Error('Shortcut receipts require atomic Relay SQLite mutation');
|
|
37
|
+
if (!validOutput(identity.output))
|
|
38
|
+
throw new Error('Shortcut receipt output must satisfy the completed shortcut result contract');
|
|
39
|
+
if (!/^[0-9a-f]{64}$/i.test(identity.contentSha256) || shortcutContentSha256(identity.output) !== identity.contentSha256.toLowerCase())
|
|
40
|
+
throw new Error('Shortcut receipt content SHA256 does not match output');
|
|
41
|
+
const receipt = { jobId: identity.jobId, taskId: identity.taskId, nodeId: identity.nodeId, waitId: identity.waitId,
|
|
42
|
+
revision: identity.revision, executionId: identity.executionId, contentSha256: identity.contentSha256.toLowerCase(),
|
|
43
|
+
output: structuredClone(identity.output), recordedAt: new Date().toISOString() };
|
|
44
|
+
await store.mutateJob(identity.jobId, job => {
|
|
45
|
+
const task = job.tasks.find(item => item.id === identity.taskId);
|
|
46
|
+
const checkpoint = task?.result?.data?.shortcut;
|
|
47
|
+
const wait = checkpoint?.waits?.[identity.nodeId];
|
|
48
|
+
if (job.executionMode !== 'shortcut' || job.contentOnly !== true || job.state !== 'ACTIVE' || job.pause || !task || !checkpoint || task.state !== 'RUNNING'
|
|
49
|
+
|| task.leaseOwner !== null || task.executionId !== identity.executionId || wait?.kind !== 'nonhuman_result'
|
|
50
|
+
|| wait.id !== identity.waitId || wait.revision !== identity.revision || wait.contentHash !== identity.contentSha256.toLowerCase()
|
|
51
|
+
|| wait.executionId !== identity.executionId)
|
|
52
|
+
throw new Error('Shortcut receipt does not match an active persisted wait and execution');
|
|
53
|
+
checkpoint.receipts ??= {};
|
|
54
|
+
const existing = checkpoint.receipts[identity.nodeId];
|
|
55
|
+
if (existing) {
|
|
56
|
+
if (existing.jobId === receipt.jobId && existing.taskId === receipt.taskId && existing.nodeId === receipt.nodeId && existing.waitId === receipt.waitId
|
|
57
|
+
&& existing.revision === receipt.revision && existing.executionId === receipt.executionId && existing.contentSha256 === receipt.contentSha256
|
|
58
|
+
&& canonical(existing.output) === canonical(receipt.output))
|
|
59
|
+
return job;
|
|
60
|
+
throw new Error('Conflicting shortcut receipt already exists for this wait');
|
|
61
|
+
}
|
|
62
|
+
if (checkpoint.nodes?.[identity.nodeId])
|
|
63
|
+
throw new Error('Shortcut wait result was already consumed');
|
|
64
|
+
checkpoint.receipts[identity.nodeId] = receipt;
|
|
65
|
+
return job;
|
|
66
|
+
});
|
|
67
|
+
return receipt;
|
|
68
|
+
}
|
|
69
|
+
function taskShortcutInput(input) {
|
|
70
|
+
try {
|
|
71
|
+
const parsed = JSON.parse(input);
|
|
72
|
+
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
|
|
73
|
+
return parsed;
|
|
74
|
+
}
|
|
75
|
+
catch { /* plain Task text remains available */ }
|
|
76
|
+
return { taskInput: input };
|
|
77
|
+
}
|
|
78
|
+
function shortcutJobCompletionAllowed(job) {
|
|
79
|
+
const graphs = job.tasks.filter(task => task.agentGraph);
|
|
80
|
+
return job.state === 'ACTIVE' && job.executionMode === 'shortcut' && job.contentOnly === true && job.prNumber === 0 && !job.localMerge && job.autoMerge === false
|
|
81
|
+
&& job.reviewEnabled === false && !job.review && !(job.plans?.length) && job.tasks.length > 0 && graphs.length > 0
|
|
82
|
+
&& job.tasks.every(task => task.state === 'SUCCEEDED')
|
|
83
|
+
&& graphs.every(task => {
|
|
84
|
+
const run = task.result?.data?.shortcut;
|
|
85
|
+
return Boolean(run && run.graphHash && Object.keys(run.waits).length === 0 && Object.keys(run.nodes).length === parseAgentGraph(task.agentGraph).nodes.length);
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
async function runCommand(args, cwd, signal) {
|
|
89
|
+
if (!Array.isArray(args) || args.length === 0 || args.some(item => typeof item !== 'string'))
|
|
90
|
+
throw new Error('runCommand requires a non-empty argument array');
|
|
91
|
+
const child = spawnOwnedProcess(args[0], args.slice(1), { invocation: 'shortcut.run-command', timeoutMs: 300_000, signal, spawn: { cwd, stdio: ['ignore', 'pipe', 'pipe'] } });
|
|
92
|
+
let stdout = '', stderr = '';
|
|
93
|
+
child.stdout?.setEncoding('utf8');
|
|
94
|
+
child.stderr?.setEncoding('utf8');
|
|
95
|
+
child.stdout?.on('data', chunk => { stdout += String(chunk); });
|
|
96
|
+
child.stderr?.on('data', chunk => { stderr += String(chunk); });
|
|
97
|
+
const [code] = await once(child, 'close');
|
|
98
|
+
return { stdout, stderr, code: code ?? -1 };
|
|
99
|
+
}
|
|
100
|
+
async function discoverShortcut(agent, projectPath, neoRoot) {
|
|
101
|
+
const file = `${agent}.agent.mjs`;
|
|
102
|
+
const root = await realpath(projectPath);
|
|
103
|
+
const project = resolve(root, 'agents', '.shortcut', file);
|
|
104
|
+
if (existsSync(project)) {
|
|
105
|
+
const actual = await realpath(project);
|
|
106
|
+
if (!inside(root, actual))
|
|
107
|
+
throw new Error('Project shortcut symlink escapes project root');
|
|
108
|
+
return actual;
|
|
109
|
+
}
|
|
110
|
+
const shared = neoRoot ? resolve(neoRoot, 'agents', '.shortcut', file) : null;
|
|
111
|
+
if (!shared || !existsSync(shared))
|
|
112
|
+
return null;
|
|
113
|
+
const sharedRoot = await realpath(resolve(neoRoot, 'agents', '.shortcut'));
|
|
114
|
+
const actual = await realpath(shared);
|
|
115
|
+
if (!inside(sharedRoot, actual))
|
|
116
|
+
throw new Error('Shared shortcut symlink escapes shortcut root');
|
|
117
|
+
return actual;
|
|
118
|
+
}
|
|
119
|
+
function inside(root, path) { const rel = relative(root, path); return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)); }
|
|
120
|
+
async function validateVisionerResult(result, projectRoot) {
|
|
121
|
+
const artifacts = result.artifacts, output = result.output;
|
|
122
|
+
if (!artifacts || Array.isArray(artifacts) || typeof artifacts !== 'object' || !['vision-evidence.json', 'vision-segment-index.json', 'metadata.json'].every(name => Object.prototype.hasOwnProperty.call(artifacts, name) && typeof output[name] === 'string'))
|
|
123
|
+
throw new Error('Visioner requires evidence, index, and metadata artifacts');
|
|
124
|
+
const files = artifacts;
|
|
125
|
+
const evidence = files['vision-evidence.json'];
|
|
126
|
+
const index = files['vision-segment-index.json'];
|
|
127
|
+
const metadata = files['metadata.json'];
|
|
128
|
+
if (!evidence || evidence.status !== 'EVIDENCE_READY_UNREVIEWED' || evidence.stage !== 'visioner' || !Array.isArray(evidence.sources) || !Array.isArray(evidence.observations)
|
|
129
|
+
|| !index || index.status !== 'SOURCE_LINKED_UNREVIEWED' || !Array.isArray(index.sources) || !Array.isArray(index.observations) || !metadata || typeof metadata !== 'object')
|
|
130
|
+
throw new Error('Visioner artifacts do not satisfy the source-linked evidence contract');
|
|
131
|
+
const artifactFiles = new Map();
|
|
132
|
+
for (const name of ['vision-evidence.json', 'vision-segment-index.json', 'metadata.json']) {
|
|
133
|
+
const actual = await realpath(resolve(projectRoot, String(output[name])));
|
|
134
|
+
if (!inside(projectRoot, actual))
|
|
135
|
+
throw new Error(`Visioner artifact escapes project root: ${name}`);
|
|
136
|
+
const bytes = await readFile(actual), parsed = JSON.parse(bytes.toString('utf8'));
|
|
137
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || canonical(parsed) !== canonical(files[name]))
|
|
138
|
+
throw new Error(`Visioner structured artifact differs from file: ${name}`);
|
|
139
|
+
artifactFiles.set(name, { bytes, parsed: parsed });
|
|
140
|
+
}
|
|
141
|
+
const evidenceFile = artifactFiles.get('vision-evidence.json'), indexFile = artifactFiles.get('vision-segment-index.json'), metadataFile = artifactFiles.get('metadata.json');
|
|
142
|
+
if (evidence.vision_segment_index_sha256 !== digestBytes(indexFile.bytes) || evidence.manifest_hash !== index.manifest_hash
|
|
143
|
+
|| evidence.markcut_metadata_sha256 !== index.markcut_metadata_sha256 || index.markcut_metadata_sha256 !== digestBytes(metadataFile.bytes)
|
|
144
|
+
|| evidenceFile.parsed.status !== 'EVIDENCE_READY_UNREVIEWED')
|
|
145
|
+
throw new Error('Visioner evidence hashes or artifact contents do not match');
|
|
146
|
+
}
|
|
147
|
+
export async function runAgentShortcut(options) {
|
|
148
|
+
const { store, job, task, projectPath, neoRoot } = options;
|
|
149
|
+
if (!store.mutateJob)
|
|
150
|
+
throw new Error('Shortcut execution requires atomic Relay SQLite mutation');
|
|
151
|
+
const leaseMs = options.leaseMs ?? 300_000, heartbeatMs = options.heartbeatMs ?? 30_000;
|
|
152
|
+
if (!Number.isSafeInteger(leaseMs) || leaseMs < 100 || !Number.isSafeInteger(heartbeatMs) || heartbeatMs < 10 || heartbeatMs >= leaseMs)
|
|
153
|
+
throw new Error('Shortcut lease heartbeat must be positive and shorter than its lease');
|
|
154
|
+
if (!task.agentGraph)
|
|
155
|
+
throw new Error(`Task ${task.id} has no Agent Graph`);
|
|
156
|
+
const graph = parseAgentGraph(task.agentGraph);
|
|
157
|
+
const graphHash = digest(task.agentGraph);
|
|
158
|
+
const inputHash = digest(task.input);
|
|
159
|
+
const projectReal = await realpath(projectPath);
|
|
160
|
+
const shortcuts = await Promise.all(graph.nodes.map(async (node) => {
|
|
161
|
+
const path = await discoverShortcut(node.agent, projectReal, neoRoot);
|
|
162
|
+
return { nodeId: node.id, path, hash: path ? digestBytes(await readFile(path)) : 'missing' };
|
|
163
|
+
}));
|
|
164
|
+
const shortcutHash = digest(canonical(shortcuts.map(item => [item.nodeId, item.hash])));
|
|
165
|
+
const transitions = new DurableTaskTransitionRuntime(store);
|
|
166
|
+
const owner = `shortcut-${process.pid}-${randomUUID()}`;
|
|
167
|
+
let currentJob = await store.load(job.id);
|
|
168
|
+
let currentTask = currentJob.tasks.find(item => item.id === task.id);
|
|
169
|
+
if (!currentTask)
|
|
170
|
+
throw new Error(`Task ${task.id} not found`);
|
|
171
|
+
if (currentTask.agentGraph !== task.agentGraph || currentTask.input !== task.input)
|
|
172
|
+
throw new Error('Shortcut invocation Task snapshot is stale; reload the durable Task before execution or receipt consumption');
|
|
173
|
+
if (currentJob.executionMode !== 'shortcut' || currentJob.contentOnly !== true)
|
|
174
|
+
throw new Error('Shortcut execution requires durable shortcut and content-only Job policy');
|
|
175
|
+
const existingShortcut = currentTask.result?.data?.shortcut;
|
|
176
|
+
if (existingShortcut?.workerFallback === true)
|
|
177
|
+
throw new Error('Task is durably routed to the original Worker; shortcut execution is not authorized');
|
|
178
|
+
if (currentJob.state !== 'ACTIVE' || currentJob.pause)
|
|
179
|
+
throw new Error(`Job ${job.id} is not runnable (${currentJob.state}${currentJob.pause ? ' paused' : ''})`);
|
|
180
|
+
if (currentTask.state === 'QUEUED' && !dependencyReady(currentTask, new Map(currentJob.tasks.map(item => [item.id, item]))))
|
|
181
|
+
throw new Error(`Task ${task.id} dependencies are not satisfied`);
|
|
182
|
+
let state = checkpoint(currentTask);
|
|
183
|
+
if (state.graphHash && (state.version !== 1 || state.graphHash !== graphHash || state.inputHash !== inputHash || state.shortcutHash !== shortcutHash))
|
|
184
|
+
throw new Error('Shortcut checkpoint fingerprint changed; refusing to reuse prior node output');
|
|
185
|
+
state.version = 1;
|
|
186
|
+
state.graphHash = graphHash;
|
|
187
|
+
state.inputHash = inputHash;
|
|
188
|
+
state.shortcutHash = shortcutHash;
|
|
189
|
+
for (const [nodeId, receipt] of Object.entries(state.receipts ?? {})) {
|
|
190
|
+
const wait = state.waits[nodeId];
|
|
191
|
+
if (!wait || receipt.jobId !== job.id || receipt.taskId !== task.id || receipt.nodeId !== nodeId || receipt.waitId !== wait.id
|
|
192
|
+
|| receipt.revision !== wait.revision || receipt.executionId !== currentTask.executionId || receipt.executionId !== wait.executionId
|
|
193
|
+
|| receipt.contentSha256 !== wait.contentHash || shortcutContentSha256(receipt.output) !== receipt.contentSha256 || !validOutput(receipt.output))
|
|
194
|
+
throw new Error(`Durable shortcut receipt ${nodeId} no longer matches its wait, execution, or content fingerprint`);
|
|
195
|
+
}
|
|
196
|
+
state.inFlight ??= {};
|
|
197
|
+
if (currentTask.state === 'QUEUED' && Object.keys(state.inFlight).length > 0)
|
|
198
|
+
throw new Error('Shortcut checkpoint contains an interrupted module execution; refusing automatic replay');
|
|
199
|
+
state.artifactHashes ??= {};
|
|
200
|
+
for (const [nodeId, hashes] of Object.entries(state.artifactHashes ?? {}))
|
|
201
|
+
for (const [artifact, expected] of Object.entries(hashes)) {
|
|
202
|
+
const actualPath = resolve(projectReal, artifact);
|
|
203
|
+
let actual;
|
|
204
|
+
try {
|
|
205
|
+
actual = await realpath(actualPath);
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
throw new Error(`Checkpoint artifact is missing: ${artifact}`);
|
|
209
|
+
}
|
|
210
|
+
if (!inside(projectReal, actual) || digestBytes(await readFile(actual)) !== expected)
|
|
211
|
+
throw new Error(`Checkpoint artifact changed or escaped project: ${artifact}`);
|
|
212
|
+
if (!state.nodes[nodeId])
|
|
213
|
+
throw new Error(`Checkpoint artifact has no completed node: ${nodeId}`);
|
|
214
|
+
}
|
|
215
|
+
if (currentTask.state === 'QUEUED') {
|
|
216
|
+
await store.mutateJob(job.id, fresh => {
|
|
217
|
+
const t = fresh.tasks.find(item => item.id === task.id);
|
|
218
|
+
if (fresh.state !== 'ACTIVE' || fresh.pause || !t || t.state !== 'QUEUED' || t.executionId !== null || t.agentGraph !== task.agentGraph || t.input !== task.input
|
|
219
|
+
|| !dependencyReady(t, new Map(fresh.tasks.map(item => [item.id, item]))))
|
|
220
|
+
throw new Error('Task is not available for shortcut claim or its input changed');
|
|
221
|
+
t.attempt += 1;
|
|
222
|
+
t.executionId = randomUUID();
|
|
223
|
+
t.leaseOwner = owner;
|
|
224
|
+
t.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString();
|
|
225
|
+
t.executionHistory = [...(t.executionHistory ?? []), { id: t.executionId, attempt: t.attempt, startedAt: new Date().toISOString() }].slice(-8);
|
|
226
|
+
return fresh;
|
|
227
|
+
});
|
|
228
|
+
currentTask = (await store.load(job.id)).tasks.find(item => item.id === task.id);
|
|
229
|
+
}
|
|
230
|
+
else if (currentTask.state !== 'RUNNING')
|
|
231
|
+
throw new Error(`Task ${task.id} cannot run shortcuts from ${currentTask.state}`);
|
|
232
|
+
if (currentTask.state === 'QUEUED') {
|
|
233
|
+
if (!currentTask.executionId || !currentTask.leaseOwner || !store.reserveWorkflowLaunch)
|
|
234
|
+
throw new Error('Shortcut execution requires the durable Graph-authorized launch claim');
|
|
235
|
+
const reserved = await store.reserveWorkflowLaunch({ jobId: job.id, taskId: task.id, executionId: currentTask.executionId, attempt: currentTask.attempt, leaseOwner: currentTask.leaseOwner });
|
|
236
|
+
if (!reserved)
|
|
237
|
+
throw new Error('Shortcut launch was already reserved; refusing duplicate execution');
|
|
238
|
+
const started = await transitions.apply(job.id, task.id, 'task.started', { eligible: (_j, t) => t.state === 'QUEUED' && t.leaseOwner === owner });
|
|
239
|
+
if (!started?.decision.accepted || !currentTask.executionId || await store.verifyWorkflowLaunch?.(job.id, task.id, currentTask.executionId) !== 'Verified')
|
|
240
|
+
throw new Error('Shortcut Task start did not verify against the durable launch claim');
|
|
241
|
+
}
|
|
242
|
+
else if (currentTask.leaseOwner && currentTask.leaseOwner !== owner) {
|
|
243
|
+
throw new Error(`Task ${task.id} has an active or unreconciled execution lease`);
|
|
244
|
+
}
|
|
245
|
+
else if (!currentTask.leaseOwner) {
|
|
246
|
+
if (!currentTask.executionId || !state.waits || !Object.keys(state.waits).some(nodeId => state.receipts?.[nodeId]))
|
|
247
|
+
throw new Error('Only a persisted wait with a durable receipt can resume an unleased RUNNING Task');
|
|
248
|
+
if (options.resumeReceiptSelected !== true)
|
|
249
|
+
throw new Error('Shortcut receipt consumption must be selected by the Task Lifecycle graph');
|
|
250
|
+
await store.mutateJob(job.id, fresh => {
|
|
251
|
+
const t = fresh.tasks.find(item => item.id === task.id);
|
|
252
|
+
if (fresh.state !== 'ACTIVE' || fresh.pause || !t || t.state !== 'RUNNING' || t.executionId !== currentTask.executionId || t.leaseOwner !== null)
|
|
253
|
+
throw new Error('Shortcut wait claim was fenced by another execution');
|
|
254
|
+
if (t.agentGraph !== task.agentGraph || t.input !== task.input)
|
|
255
|
+
throw new Error('Shortcut Task input changed before receipt claim');
|
|
256
|
+
t.leaseOwner = owner;
|
|
257
|
+
t.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString();
|
|
258
|
+
return fresh;
|
|
259
|
+
});
|
|
260
|
+
}
|
|
261
|
+
for (const [nodeId, receipt] of Object.entries(state.receipts ?? {})) {
|
|
262
|
+
const wait = state.waits[nodeId];
|
|
263
|
+
if (!wait)
|
|
264
|
+
throw new Error(`Durable shortcut receipt ${nodeId} has no persisted wait`);
|
|
265
|
+
if (state.nodes[nodeId])
|
|
266
|
+
throw new Error(`Shortcut receipt ${nodeId} was already consumed`);
|
|
267
|
+
const artifactHashes = {};
|
|
268
|
+
const output = receipt.output;
|
|
269
|
+
const artifactPaths = Array.isArray(output.artifacts) ? output.artifacts : Object.entries(output.artifacts).map(([name, value]) => {
|
|
270
|
+
if (!(name in output.output) || typeof output.output[name] !== 'string' || !value || typeof value !== 'object')
|
|
271
|
+
throw new Error(`shortcut artifact ${name} lacks a structured artifact and output path`);
|
|
272
|
+
return output.output[name];
|
|
273
|
+
});
|
|
274
|
+
for (const artifact of artifactPaths) {
|
|
275
|
+
const actual = await realpath(isAbsolute(artifact) ? resolve(artifact) : resolve(projectReal, artifact));
|
|
276
|
+
if (!inside(projectReal, actual))
|
|
277
|
+
throw new Error(`shortcut artifact outside project: ${artifact}`);
|
|
278
|
+
artifactHashes[relative(projectReal, actual)] = digestBytes(await readFile(actual));
|
|
279
|
+
}
|
|
280
|
+
const nodeAgent = graph.nodes.find(node => node.id === nodeId)?.agent;
|
|
281
|
+
if (nodeAgent?.toLowerCase() === 'visioner')
|
|
282
|
+
await validateVisionerResult(output, projectReal);
|
|
283
|
+
state.nodes[nodeId] = structuredClone(output);
|
|
284
|
+
state.artifactHashes[nodeId] = artifactHashes;
|
|
285
|
+
delete state.waits[nodeId];
|
|
286
|
+
delete state.receipts?.[nodeId];
|
|
287
|
+
}
|
|
288
|
+
if (Object.keys(state.nodes).length > Object.keys(checkpoint(currentTask).nodes).length)
|
|
289
|
+
await persist(state);
|
|
290
|
+
const executionAbort = new AbortController();
|
|
291
|
+
let leaseHeartbeatError;
|
|
292
|
+
let heartbeatInFlight = false;
|
|
293
|
+
const heartbeat = setInterval(() => {
|
|
294
|
+
if (heartbeatInFlight || executionAbort.signal.aborted)
|
|
295
|
+
return;
|
|
296
|
+
heartbeatInFlight = true;
|
|
297
|
+
void store.mutateJob(job.id, fresh => {
|
|
298
|
+
const t = fresh.tasks.find(item => item.id === task.id);
|
|
299
|
+
if (fresh.state !== 'ACTIVE' || fresh.pause || !t || t.state !== 'RUNNING' || t.executionId !== currentTask.executionId || t.leaseOwner !== owner) {
|
|
300
|
+
throw new Error('Shortcut execution lease was fenced during module execution');
|
|
301
|
+
}
|
|
302
|
+
t.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString();
|
|
303
|
+
return fresh;
|
|
304
|
+
}).catch(error => { leaseHeartbeatError = error; executionAbort.abort(error); }).finally(() => { heartbeatInFlight = false; });
|
|
305
|
+
}, heartbeatMs);
|
|
306
|
+
heartbeat.unref();
|
|
307
|
+
const stopHeartbeat = () => clearInterval(heartbeat);
|
|
308
|
+
let effectsStarted = false;
|
|
309
|
+
let shortcutModuleEntered = false;
|
|
310
|
+
try {
|
|
311
|
+
const incoming = new Map(graph.nodes.map(node => [node.id, graph.edges.filter(edge => edge.to === node.id).map(edge => edge.from)]));
|
|
312
|
+
const max = Math.max(1, Math.min(8, options.concurrency ?? 4));
|
|
313
|
+
const shortcutByNode = new Map(shortcuts.map(item => [item.nodeId, item.path]));
|
|
314
|
+
for (const wave of graph.waves) {
|
|
315
|
+
const ready = wave.filter(id => !state.nodes[id] && !state.waits[id] && (incoming.get(id) ?? []).every(parent => Boolean(state.nodes[parent])));
|
|
316
|
+
for (let offset = 0; offset < ready.length; offset += max) {
|
|
317
|
+
const batch = ready.slice(offset, offset + max);
|
|
318
|
+
for (const id of batch)
|
|
319
|
+
if (shortcutByNode.get(id))
|
|
320
|
+
state.inFlight[id] = currentTask.executionId;
|
|
321
|
+
if (batch.some(id => Boolean(shortcutByNode.get(id))))
|
|
322
|
+
await persist(state);
|
|
323
|
+
const outcomes = await Promise.all(batch.map(async (id) => {
|
|
324
|
+
const node = graph.nodes.find(item => item.id === id);
|
|
325
|
+
const shortcut = shortcutByNode.get(id) ?? null;
|
|
326
|
+
if (!shortcut)
|
|
327
|
+
return { id, value: null };
|
|
328
|
+
try {
|
|
329
|
+
shortcutModuleEntered = true;
|
|
330
|
+
const module = await import(pathToFileURL(shortcut).href);
|
|
331
|
+
const predecessorOutputs = Object.fromEntries((incoming.get(id) ?? []).map(parent => [parent, state.nodes[parent]?.output]));
|
|
332
|
+
const trackedRunCommand = async (args, cwd) => {
|
|
333
|
+
if (executionAbort.signal.aborted)
|
|
334
|
+
throw new Error(`Shortcut execution was cancelled: ${String(leaseHeartbeatError ?? 'lease lost')}`);
|
|
335
|
+
effectsStarted = true;
|
|
336
|
+
return runCommand(args, cwd, executionAbort.signal);
|
|
337
|
+
};
|
|
338
|
+
const raw = await module.run({ input: { ...taskShortcutInput(task.input), projectPath, jobId: job.id, taskId: task.id, nodeId: id, agent: node.agent, predecessorOutputs }, signal: executionAbort.signal, runCommand: trackedRunCommand });
|
|
339
|
+
if (leaseHeartbeatError)
|
|
340
|
+
throw new Error(`Shortcut lease renewal failed: ${String(leaseHeartbeatError)}`);
|
|
341
|
+
if (!raw || typeof raw !== 'object')
|
|
342
|
+
throw new Error('shortcut result must be an object');
|
|
343
|
+
const result = raw;
|
|
344
|
+
if (result.status === 'WAITING_EVENT' && result.event && typeof result.event === 'object')
|
|
345
|
+
return { id, value: result };
|
|
346
|
+
if (!validOutput(result))
|
|
347
|
+
throw new Error('shortcut returned an invalid COMPLETED result contract');
|
|
348
|
+
const artifactPaths = Array.isArray(result.artifacts) ? result.artifacts
|
|
349
|
+
: Object.entries(result.artifacts).map(([name, value]) => {
|
|
350
|
+
if (!(name in result.output) || typeof result.output[name] !== 'string' || !value || typeof value !== 'object')
|
|
351
|
+
throw new Error(`shortcut artifact ${name} lacks a structured artifact and output path`);
|
|
352
|
+
return result.output[name];
|
|
353
|
+
});
|
|
354
|
+
const projectReal = await realpath(projectPath);
|
|
355
|
+
if (node.agent.toLowerCase() === 'visioner')
|
|
356
|
+
await validateVisionerResult(result, projectReal);
|
|
357
|
+
const artifactHashes = {};
|
|
358
|
+
for (const artifact of artifactPaths) {
|
|
359
|
+
if (!artifact)
|
|
360
|
+
throw new Error('shortcut artifact path cannot be empty');
|
|
361
|
+
const artifactPath = isAbsolute(artifact) ? resolve(artifact) : resolve(projectReal, artifact);
|
|
362
|
+
let actual;
|
|
363
|
+
try {
|
|
364
|
+
actual = await realpath(artifactPath);
|
|
365
|
+
}
|
|
366
|
+
catch {
|
|
367
|
+
throw new Error(`shortcut artifact missing: ${artifact}`);
|
|
368
|
+
}
|
|
369
|
+
if (!inside(projectReal, actual))
|
|
370
|
+
throw new Error(`shortcut artifact missing or outside project: ${artifact}`);
|
|
371
|
+
const relativePath = relative(projectReal, actual);
|
|
372
|
+
artifactHashes[relativePath] = digestBytes(await readFile(actual));
|
|
373
|
+
}
|
|
374
|
+
return { id, value: result, artifactHashes };
|
|
375
|
+
}
|
|
376
|
+
catch (error) {
|
|
377
|
+
return { id, value: null, error: error instanceof Error ? error.message : String(error) };
|
|
378
|
+
}
|
|
379
|
+
}));
|
|
380
|
+
for (const result of outcomes) {
|
|
381
|
+
if (!result.value)
|
|
382
|
+
return await fallback(`No valid shortcut for ${result.id}${result.error ? `: ${result.error}` : ''}`);
|
|
383
|
+
if (result.value.status === 'WAITING_EVENT') {
|
|
384
|
+
const evt = result.value.event;
|
|
385
|
+
if (evt.kind !== 'nonhuman_result')
|
|
386
|
+
return await fallback('Shortcut event wait must be a nonhuman result; human approval must use Relay hostInvocation');
|
|
387
|
+
if (typeof evt.id !== 'string' || typeof evt.revision !== 'string' || typeof evt.contentHash !== 'string'
|
|
388
|
+
|| (evt.nodeId !== undefined && evt.nodeId !== result.id) || !/^[0-9a-f]{64}$/i.test(evt.contentHash))
|
|
389
|
+
return await fallback(`Invalid event wait from ${result.id}`);
|
|
390
|
+
delete state.inFlight[result.id];
|
|
391
|
+
state.waits[result.id] = { kind: 'nonhuman_result', id: evt.id, revision: evt.revision, contentHash: evt.contentHash, executionId: currentTask.executionId };
|
|
392
|
+
}
|
|
393
|
+
else {
|
|
394
|
+
delete state.inFlight[result.id];
|
|
395
|
+
state.nodes[result.id] = result.value;
|
|
396
|
+
state.artifactHashes[result.id] = result.artifactHashes ?? {};
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
await persist(state);
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
if (Object.keys(state.waits).length) {
|
|
403
|
+
const released = await transitions.apply(job.id, task.id, 'shortcut.waiting', { eligible: (_j, t) => t.state === 'RUNNING' && t.leaseOwner === owner });
|
|
404
|
+
if (!released?.decision.accepted)
|
|
405
|
+
throw new Error('Task lifecycle graph rejected shortcut.waiting');
|
|
406
|
+
stopHeartbeat();
|
|
407
|
+
const nodeId = Object.keys(state.waits)[0];
|
|
408
|
+
return { outcome: { status: 'WAITING_EVENT', event: { nodeId, ...state.waits[nodeId] } }, task: await findTask(), fallback: false };
|
|
409
|
+
}
|
|
410
|
+
const finalResult = { summary: `Shortcut Agent Graph completed (${graph.nodes.length} nodes)`, data: { shortcut: state } };
|
|
411
|
+
const done = await transitions.apply(job.id, task.id, 'task.completed', {
|
|
412
|
+
eligible: (_j, t) => t.state === 'RUNNING' && t.leaseOwner === owner,
|
|
413
|
+
mutate: (_j, t) => { t.result = finalResult; t.leaseOwner = null; t.leaseExpiresAt = null; t.executionId = null; }
|
|
414
|
+
});
|
|
415
|
+
if (!done?.decision.accepted)
|
|
416
|
+
throw new Error('Task lifecycle graph rejected task.completed');
|
|
417
|
+
stopHeartbeat();
|
|
418
|
+
await store.mutateJob(job.id, current => {
|
|
419
|
+
const allowed = shortcutJobCompletionAllowed(current);
|
|
420
|
+
dispatchJobLifecycleSync(current, 'shortcut.completed', { shortcutCompletionAllowed: allowed });
|
|
421
|
+
return current;
|
|
422
|
+
});
|
|
423
|
+
return { outcome: { status: 'COMPLETED', output: { nodes: state.nodes }, artifacts: Object.values(state.nodes).flatMap(node => {
|
|
424
|
+
if (Array.isArray(node.artifacts))
|
|
425
|
+
return node.artifacts;
|
|
426
|
+
const output = node.output;
|
|
427
|
+
return output && typeof output === 'object' ? Object.values(output).filter((value) => typeof value === 'string') : [];
|
|
428
|
+
}) }, task: await findTask(), fallback: false };
|
|
429
|
+
}
|
|
430
|
+
finally {
|
|
431
|
+
stopHeartbeat();
|
|
432
|
+
}
|
|
433
|
+
async function persist(next) {
|
|
434
|
+
await store.mutateJob(job.id, fresh => {
|
|
435
|
+
const t = fresh.tasks.find(item => item.id === task.id);
|
|
436
|
+
if (fresh.state !== 'ACTIVE' || fresh.pause || !t || t.state !== 'RUNNING' || t.leaseOwner !== owner || !t.executionId)
|
|
437
|
+
throw new Error('Shortcut checkpoint fenced by execution lease');
|
|
438
|
+
const previous = t.result ?? { summary: 'Shortcut execution in progress', data: {} };
|
|
439
|
+
t.result = { ...previous, data: { ...(previous.data ?? {}), shortcut: structuredClone(next) } };
|
|
440
|
+
t.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString();
|
|
441
|
+
return fresh;
|
|
442
|
+
});
|
|
443
|
+
}
|
|
444
|
+
async function findTask() { const fresh = await store.load(job.id); const found = fresh.tasks.find(item => item.id === task.id); if (!found)
|
|
445
|
+
throw new Error('Task disappeared'); return found; }
|
|
446
|
+
async function fallback(reason) {
|
|
447
|
+
const safe = !effectsStarted && !shortcutModuleEntered && Object.keys(state.inFlight ?? {}).length === 0 && Object.keys(state.nodes).length === 0;
|
|
448
|
+
stopHeartbeat();
|
|
449
|
+
const result = await transitions.apply(job.id, task.id, 'shortcut.failed', {
|
|
450
|
+
eligible: (_j, t) => t.state === 'RUNNING' && t.leaseOwner === owner,
|
|
451
|
+
facts: () => ({ shortcutEffectsSafe: safe }),
|
|
452
|
+
mutate: (_j, t, decision) => {
|
|
453
|
+
const workerFallback = decision.actions.includes('mutation.markShortcutWorkerFallback');
|
|
454
|
+
const failure = workerFallback ? reason : `Shortcut stopped after possible partial effects; Troubleshooter recovery required: ${reason}`;
|
|
455
|
+
t.error = failure;
|
|
456
|
+
const prior = t.result ?? { summary: 'Shortcut execution failed', data: {} };
|
|
457
|
+
t.result = { ...prior, data: { ...(prior.data ?? {}), shortcut: { ...state, ...(workerFallback ? { workerFallback: true } : {}) } } };
|
|
458
|
+
},
|
|
459
|
+
});
|
|
460
|
+
if (!result?.decision.accepted)
|
|
461
|
+
throw new Error(`Task lifecycle graph rejected shortcut failure: ${reason}`);
|
|
462
|
+
const workerFallback = result.decision.actions.includes('mutation.markShortcutWorkerFallback');
|
|
463
|
+
const failure = result.task.error ?? reason;
|
|
464
|
+
return { outcome: { status: 'FAILED', reason: failure }, task: await findTask(), fallback: workerFallback };
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
export function shortcutResumeEvent(_value) {
|
|
468
|
+
throw new Error('--event-json is disabled: manual JSON cannot authenticate a human approval or durable event receipt');
|
|
469
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { resolveExecutionContext } from './execution-context.js';
|
|
2
|
+
import { arg } from './cli-support.js';
|
|
3
|
+
import { usage } from './cli-help.js';
|
|
4
|
+
export async function runContextCommand(action, args) {
|
|
5
|
+
if (action !== 'resolve')
|
|
6
|
+
throw new Error(usage);
|
|
7
|
+
const projectPath = arg(args, '--project-path');
|
|
8
|
+
if (!projectPath)
|
|
9
|
+
throw new Error('context resolve requires --project-path');
|
|
10
|
+
const roleValue = arg(args, '--role', 'orchestrator');
|
|
11
|
+
const roles = ['orchestrator', 'planner', 'reviewer', 'worker', 'nested-worker'];
|
|
12
|
+
if (!roles.includes(roleValue))
|
|
13
|
+
throw new Error('--role must be orchestrator, planner, reviewer, worker, or nested-worker');
|
|
14
|
+
const context = await resolveExecutionContext(projectPath, roleValue, {
|
|
15
|
+
workspaceRoot: arg(args, '--workspace-root') || undefined,
|
|
16
|
+
globalRoot: arg(args, '--global-root') || undefined,
|
|
17
|
+
explicitSkills: arg(args, '--skills').split(',').filter(Boolean),
|
|
18
|
+
explicitAgents: arg(args, '--agents').split(',').filter(Boolean),
|
|
19
|
+
});
|
|
20
|
+
console.log(JSON.stringify(context, null, 2));
|
|
21
|
+
}
|