agents-relay 2.0.252 → 2.0.253

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/README.md CHANGED
@@ -19,17 +19,20 @@ Relay appends `--handoff-file`, optional `--on-needs-user-file`, and `--cwd`
19
19
  without using a shell. No Neo executable is assumed. Missing/failed executors
20
20
  produce `technical_failure` rather than silently resolving a blocker.
21
21
 
22
- **Shortcut three-node L3 gate:** `npm run test:l3:shortcut` runs four isolated,
23
- deterministic three-agent DAG scenarios: no review, sequential approvals,
24
- Request Changes for a scripted node with a durable revision Worker, and
25
- Request Changes for a model-only node with re-review. They exercise real
26
- Shortcut CLI/SQLite/Git review identities and the real Reconciler with a
27
- synthetic model adapter; no external model, iPhone, or production Job is used.
28
- The gate is also included in `test:shortcut:dags` and `test:publish`.
22
+ **Unified DAG/Shortcut L3 gate:** `npm run test:l3:shortcut` covers both
23
+ legacy in-flight Shortcut recovery (four three-agent scenarios) and the new
24
+ ordinary Task Runtime: three Script Tasks without Review; all approvals;
25
+ Request Changes and fresh approval for Script and Model Agents; actual Shortcut
26
+ CLI activation; Normal-vs-Shortcut DAG equivalence; restart/idempotency;
27
+ fork/join concurrency; failed child Task using ordinary Relay recovery; EventBus
28
+ wake; and single-Agent Script execution. `Coordinator` only creates dependency-
29
+ ready Agent Tasks; each child uses existing Retry, Troubleshooter and Review.
30
+ No `NodeExecution`, Git Review commit, or second task scheduler. An inbox
31
+ receipt is not user approval. The L3 gate is included in `test:publish`.
29
32
 
30
33
  **Interactive Review:** Relay owns the generic
31
- `review.interactive.begin/wait/ready/fail/abort` lifecycle, immutable revision
32
- binding and decision correlation. The caller (e.g. Neo's Markcut MCP wrapper)
34
+ `review.interactive.begin/wait/fail/abort` lifecycle, execution-bound
35
+ identity and decision correlation. The caller (Neo `review.preview`, backed by Markcut)
33
36
  owns preview generation, media, UI and notifications. New waiting events use
34
37
  `component: interactive-review`; existing recorded events retain their history.
35
38
 
@@ -107,7 +107,7 @@ async function runCommand(args, cwd, signal) {
107
107
  }
108
108
  /** A Shortcut belongs to an Agent source, not to an independent name search.
109
109
  * Only explicit Agent inheritance permits falling back to a parent's Shortcut. */
110
- async function discoverShortcut(agent, projectPath, sharedRoot, workspaceRoot, globalRoot) {
110
+ export async function discoverShortcut(agent, projectPath, sharedRoot, workspaceRoot, globalRoot) {
111
111
  let sources;
112
112
  try {
113
113
  ({ sources } = await resolveAgentMarkdown(agent, BUNDLED_AGENTS_ROOT, projectPath, sharedRoot, agentSourceLayers(projectPath, { sharedRoot, workspaceRoot, globalRoot: globalRoot ?? process.env.AGENTS_HOME ?? join(homedir(), '.agents') })));
@@ -1,3 +1,4 @@
1
+ import { createHash } from 'node:crypto';
1
2
  import { readFile } from 'node:fs/promises';
2
3
  import { missingShortcutNodes, recordShortcutReceipt, runAgentShortcut, shortcutResumeEvent } from './agent-shortcut.js';
3
4
  import { parseAgentGraph } from './agent-graph.js';
@@ -105,6 +106,37 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
105
106
  current.shortcutRunnerContext = ctx;
106
107
  return current;
107
108
  });
109
+ // Shortcut is an explicit activation point, not a separate Task engine.
110
+ // Previously launched, in-flight Shortcut checkpoints retain their legacy
111
+ // foreground owner; new Jobs use the ordinary Reconciler/DAG Task path.
112
+ const oldCheckpoint = task.result?.data?.shortcut;
113
+ const dagCheckpoint = task.result?.data?.dag;
114
+ const unified = dagCheckpoint?.version === 1 || (!hasArg(args, '--legacy-shortcut-runtime') && !oldCheckpoint && !job.shortcutExecutionStartedAt);
115
+ if (unified) {
116
+ if (!loaded.store.mutateJob)
117
+ throw Error('Unified DAG activation requires SQLite');
118
+ const hash = createHash('sha256').update(task.agentGraph).digest('hex');
119
+ await loaded.store.mutateJob(id, current => {
120
+ const root = current.tasks.find(t => t.id === taskId);
121
+ if (current.state !== 'ACTIVE' || !root || !root.agentGraph || root.agentGraph !== task.agentGraph)
122
+ throw Error('DAG activation Task identity changed');
123
+ if (root.state !== 'QUEUED' && root.state !== 'RUNNING')
124
+ throw Error('DAG Task cannot start from ' + root.state);
125
+ const prior = root.result?.data?.dag;
126
+ if (prior && (prior.version !== 1 || prior.graphHash !== hash))
127
+ throw Error('DAG runtime identity changed');
128
+ if (!prior)
129
+ root.result = { summary: 'DAG ready', data: { ...(root.result?.data ?? {}), dag: { version: 1, graphHash: hash } } };
130
+ if (!current.shortcutExecutionStartedAt)
131
+ current.shortcutExecutionStartedAt = new Date().toISOString();
132
+ return current;
133
+ });
134
+ const scheduled = await loaded.store.load(id);
135
+ await withEventBus(args, bus => publishWake(bus, scheduled, taskId, 'Shortcut DAG activation (normal Task scheduler)'));
136
+ console.log(JSON.stringify({ jobId: id, taskId, mode: 'shortcut', scheduled: true, state: scheduled.state,
137
+ graphRuntime: 'tasks', message: 'Task scheduling and Review are owned by the ordinary Relay Reconciler' }, null, 2));
138
+ return;
139
+ }
108
140
  const missing = await missingShortcutNodes(task.agentGraph, projectPath, sharedRoot, workspaceRoot, globalRoot);
109
141
  const previous = task.result?.data?.shortcut;
110
142
  if (previous?.workerFallback === true)
@@ -0,0 +1,48 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
3
+ import { once } from 'node:events';
4
+ import { spawnOwnedProcess } from './owned-process.js';
5
+ import { validateShortcutStageGate } from './shortcut-stage-contract.js';
6
+ /** Validate an Agent DAG Task's required on-disk result before accepting
7
+ * task.completed. Invalid output is an ordinary Task failure and enters the
8
+ * existing Troubleshooter path; it must not strand a running Coordinator. */
9
+ export async function dagCompletionError(task, projectPath) {
10
+ if (!task.dagNode)
11
+ return null;
12
+ if (task.output?.kind !== 'file')
13
+ return 'DAG Agent Task has no file result target';
14
+ let parsed;
15
+ try {
16
+ parsed = JSON.parse(await readFile(task.output.path, 'utf8'));
17
+ }
18
+ catch (error) {
19
+ return `DAG Agent result unreadable: ${error instanceof Error ? error.message : String(error)}`;
20
+ }
21
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
22
+ return 'DAG Agent result is not an object';
23
+ const record = parsed;
24
+ if (record.status !== 'COMPLETED' || !record.output || typeof record.output !== 'object' || Array.isArray(record.output))
25
+ return 'DAG Agent result must contain status COMPLETED and an output object';
26
+ if (!record.artifacts || typeof record.artifacts !== 'object' || Array.isArray(record.artifacts) &&
27
+ !record.artifacts.every(item => typeof item === 'string'))
28
+ return 'DAG Agent result must contain a list or object of artifacts';
29
+ if (projectPath && task.agentName) {
30
+ try {
31
+ await validateShortcutStageGate({ projectPath, agent: task.agentName, runPath: dirname(dirname(task.output.path)),
32
+ execute: async (args, cwd) => {
33
+ const abort = AbortSignal.timeout(300_000);
34
+ const child = spawnOwnedProcess(args[0], args.slice(1), { invocation: 'dag.stage-validation', signal: abort,
35
+ spawn: { cwd, stdio: ['ignore', 'pipe', 'pipe'] } });
36
+ let stdout = '', stderr = '';
37
+ child.stdout?.on('data', chunk => { stdout += String(chunk); });
38
+ child.stderr?.on('data', chunk => { stderr += String(chunk); });
39
+ const [code] = await once(child, 'close');
40
+ return { stdout, stderr, code: code ?? -1 };
41
+ } });
42
+ }
43
+ catch (error) {
44
+ return `DAG Stage contract rejected Task completion: ${error instanceof Error ? error.message : String(error)}`;
45
+ }
46
+ }
47
+ return null;
48
+ }
@@ -0,0 +1,214 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { dirname, isAbsolute, join } from 'node:path';
3
+ import { mkdir, readFile } from 'node:fs/promises';
4
+ import { taskOverallTimeoutMs } from './types.js';
5
+ import { parseAgentGraph } from './agent-graph.js';
6
+ import { discoverShortcut } from './agent-shortcut.js';
7
+ import { createTaskEntity } from './workflow/entity-creation.js';
8
+ import { tryTransitionTaskEvent } from './task-transitions.js';
9
+ import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
10
+ export function dagChildId(parentTaskId, nodeId) { return `dag-${parentTaskId}-${nodeId}`; }
11
+ export function unifiedDAG(job, task) {
12
+ if (!task.agentGraph)
13
+ return false;
14
+ if (job.executionMode !== 'shortcut')
15
+ return true;
16
+ return task.result?.data?.dag?.version === 1;
17
+ }
18
+ export function dagCoordinator(task) { return Boolean(task.agentGraph && task.result?.data?.dag?.version === 1); }
19
+ const sha = (s) => createHash('sha256').update(s).digest('hex');
20
+ const out = (task) => {
21
+ if (task.output?.kind !== 'file' || !isAbsolute(task.output.path))
22
+ throw Error('Graph Task requires a canonical absolute file output');
23
+ return dirname(task.output.path);
24
+ };
25
+ async function graphNodeOutput(task) {
26
+ if (task.state !== 'SUCCEEDED')
27
+ return null;
28
+ const data = task.result?.data;
29
+ if (data?.status === 'COMPLETED' && data.output && typeof data.output === 'object' && !Array.isArray(data.output))
30
+ return data.output;
31
+ if (task.output?.kind === 'file') {
32
+ let value;
33
+ try {
34
+ value = JSON.parse(await readFile(task.output.path, 'utf8'));
35
+ }
36
+ catch {
37
+ return null;
38
+ }
39
+ const record = value;
40
+ if (record?.status === 'COMPLETED' && record.output && typeof record.output === 'object' && !Array.isArray(record.output))
41
+ return record.output;
42
+ }
43
+ return null;
44
+ }
45
+ /** One durable Task is one DAG node. No independent node lease, retry, review or recovery.
46
+ * This is a reconciliation projection, not an execution scheduler: the normal
47
+ * Task graph owns dispatch and dependencies for every materialized child. */
48
+ export async function reconcileDAGTasks(options) {
49
+ const { store, jobId } = options;
50
+ if (!store.mutateJob)
51
+ throw Error('DAG Tasks require an atomic SQLite store');
52
+ const snapshot = await store.load(jobId);
53
+ for (const parent of snapshot.tasks.filter(t => unifiedDAG(snapshot, t))) {
54
+ if (parent.state === 'SUCCEEDED' || parent.state === 'CANCELLED' || parent.state === 'FAILED' || parent.state === 'BLOCKED')
55
+ continue;
56
+ const graph = parseAgentGraph(parent.agentGraph);
57
+ const graphHash = sha(parent.agentGraph);
58
+ const projectPath = await options.projectPathForTask(snapshot, parent);
59
+ const root = parent.output?.kind === 'file' && isAbsolute(parent.output.path) ? out(parent) : join(projectPath, '.relay-dag-results', jobId, parent.id);
60
+ if (parent.state === 'QUEUED') {
61
+ await store.mutateJob(jobId, job => {
62
+ const current = job.tasks.find(t => t.id === parent.id);
63
+ if (job.state !== 'ACTIVE' || job.pause || !current || current.state !== 'QUEUED' || !unifiedDAG(job, current))
64
+ return job;
65
+ const step = tryTransitionTaskEvent(current, 'task.started');
66
+ if (!step.accepted || step.target !== 'RUNNING')
67
+ throw Error('Task lifecycle rejected DAG coordinator start');
68
+ current.title = 'Coordinator';
69
+ current.result = { summary: 'DAG coordinator', data: { dag: { version: 1, graphHash } } };
70
+ current.updatedAt = new Date().toISOString();
71
+ return job;
72
+ });
73
+ }
74
+ const currentJob = await store.load(jobId);
75
+ const currentParent = currentJob.tasks.find(t => t.id === parent.id);
76
+ if (currentParent.state !== 'RUNNING' || !dagCoordinator(currentParent))
77
+ continue;
78
+ if ((currentParent.result?.data?.dag).graphHash !== graphHash)
79
+ throw Error('DAG changed after execution began');
80
+ for (const wave of graph.waves) {
81
+ for (const nodeId of wave) {
82
+ const childId = dagChildId(parent.id, nodeId);
83
+ if (currentJob.tasks.some(t => t.id === childId))
84
+ continue;
85
+ const parents = graph.edges.filter(e => e.to === nodeId).map(e => e.from);
86
+ const incoming = parents.map(id => currentJob.tasks.find(t => t.id === dagChildId(parent.id, id)));
87
+ if (incoming.some(t => !t || t.state !== 'SUCCEEDED'))
88
+ continue;
89
+ const predecessorOutputs = {};
90
+ for (let i = 0; i < parents.length; i++) {
91
+ const value = await graphNodeOutput(incoming[i]);
92
+ if (!value)
93
+ throw Error(`Completed DAG dependency ${parents[i]} has no structured result`);
94
+ predecessorOutputs[parents[i]] = value;
95
+ }
96
+ const node = graph.nodes.find(n => n.id === nodeId);
97
+ const script = await discoverShortcut(node.agent, projectPath, options.roots?.sharedRoot ?? undefined, options.roots?.workspaceRoot ?? undefined, options.roots?.globalRoot ?? undefined);
98
+ const childOut = join(root, '.dag-node-results', childId + '.json');
99
+ let supplied = { taskInput: parent.input };
100
+ try {
101
+ const parsed = JSON.parse(parent.input);
102
+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
103
+ supplied = parsed;
104
+ }
105
+ catch { /* Plain Task Markdown remains taskInput. */ }
106
+ const { reviewDecision: _ignored, interactiveInvocation: _ignored2, jobId: _job, taskId: _task, projectPath: _project, ...projectInput } = supplied;
107
+ const input = JSON.stringify({ ...projectInput, source: 'relay-dag-task', jobId, parentTaskId: parent.id, nodeId, taskId: childId,
108
+ agent: node.agent, projectPath, predecessorOutputs, taskInput: parent.input, outputPath: childOut,
109
+ requiredResult: { status: 'COMPLETED', output: {}, artifacts: [] },
110
+ instruction: 'Execute this Agent DAG role using only declared predecessorOutputs and authorized project inputs. Write the structured result to outputPath. Do not invent source evidence, review decisions or publishing authorization.' });
111
+ await mkdir(dirname(childOut), { recursive: true, mode: 0o700 });
112
+ await store.mutateJob(jobId, job => {
113
+ const current = job.tasks.find(t => t.id === parent.id);
114
+ if (job.state !== 'ACTIVE' || job.pause || current?.state !== 'RUNNING' || !dagCoordinator(current) || job.tasks.some(t => t.id === childId))
115
+ return job;
116
+ if (!parents.every(id => job.tasks.some(t => t.id === dagChildId(parent.id, id) && t.state === 'SUCCEEDED')))
117
+ return job;
118
+ const now = new Date().toISOString();
119
+ const dagNode = { parentTaskId: parent.id, nodeId, graphHash, executor: script ? 'script' : 'model' };
120
+ job.tasks.push(createTaskEntity(job, { jobId, id: childId, parentTaskId: parent.id,
121
+ dagNode, title: node.agent, kind: 'work', agentName: node.agent,
122
+ dependencies: parents.map(id => dagChildId(parent.id, id)), capabilities: script ? ['script'] : ['model'],
123
+ adapter: script ? 'script' : 'codex', workerRequirements: script ? undefined : { capabilities: ['model'] },
124
+ input, output: { kind: 'file', path: childOut }, attempt: 0, maxAttempts: 3,
125
+ leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, error: null,
126
+ timeoutMs: taskOverallTimeoutMs('L'), createdAt: now, updatedAt: now }));
127
+ return job;
128
+ });
129
+ }
130
+ }
131
+ const latest = await store.load(jobId);
132
+ const done = graph.nodes.map(n => latest.tasks.find(t => t.id === dagChildId(parent.id, n.id)));
133
+ if (done.length && done.every(t => t?.state === 'SUCCEEDED')) {
134
+ await store.mutateJob(jobId, job => {
135
+ const current = job.tasks.find(t => t.id === parent.id);
136
+ if (!current || current.state !== 'RUNNING' || !dagCoordinator(current))
137
+ return job;
138
+ if (!graph.nodes.every(n => job.tasks.some(t => t.id === dagChildId(parent.id, n.id) && t.state === 'SUCCEEDED')))
139
+ return job;
140
+ const changed = tryTransitionTaskEvent(current, 'task.completed');
141
+ if (!changed.accepted || changed.target !== 'SUCCEEDED')
142
+ throw Error('Task Lifecycle rejected DAG completion');
143
+ current.result = { summary: 'DAG completed', data: { dag: { version: 1, graphHash },
144
+ nodes: Object.fromEntries(graph.nodes.map(n => [n.id, dagChildId(parent.id, n.id)])) } };
145
+ current.updatedAt = new Date().toISOString();
146
+ return job;
147
+ });
148
+ }
149
+ }
150
+ await completeContentJobIfEligible(store, jobId);
151
+ }
152
+ /** Human Request Changes on a scripted Agent goes to its model Worker within
153
+ * the SAME durable Task. Approval goes back to the Script for stage validation.
154
+ * This is routing, not a second revision Task or recovery state machine. */
155
+ export async function selectDAGReviewExecutors(store, jobId) {
156
+ if (!store.mutateJob)
157
+ return;
158
+ await store.mutateJob(jobId, job => {
159
+ if (job.state !== 'ACTIVE' || job.pause)
160
+ return job;
161
+ for (const task of job.tasks) {
162
+ if (task.dagNode?.executor !== 'script' || task.state !== 'QUEUED' || task.executionId !== null)
163
+ continue;
164
+ const status = task.interactiveInvocation?.status;
165
+ const desired = status === 'changes_requested' ? 'codex' : 'script';
166
+ if (task.adapter === desired)
167
+ continue;
168
+ task.adapter = desired;
169
+ task.capabilities = desired === 'codex' ? ['model'] : ['script'];
170
+ task.workerRequirements = desired === 'codex' ? { capabilities: ['model'] } : undefined;
171
+ task.routing = undefined;
172
+ task.workerSelection = undefined;
173
+ if (status === 'changes_requested') {
174
+ const input = JSON.parse(task.input);
175
+ input.reviewRevision = { status, feedback: task.interactiveInvocation?.feedback ?? '',
176
+ comments: task.interactiveInvocation?.comments ?? [],
177
+ instruction: 'Revise the current Stage Artifact from the human feedback. Verify it, then use agents-relay review interactive --path to submit a NEW review for this same Task Execution. Do not publish or emit task.completed until the new review is approved.' };
178
+ task.input = JSON.stringify(input);
179
+ }
180
+ task.updatedAt = new Date().toISOString();
181
+ }
182
+ return job;
183
+ });
184
+ }
185
+ /** Run the DAG projection at the ordinary Reconciler scheduling boundary. */
186
+ export async function reconcileDAGSchedule(options) {
187
+ if (!options.job.tasks.some(t => unifiedDAG(options.job, t))) {
188
+ await completeContentJobIfEligible(options.store, options.jobId);
189
+ return options.store.load(options.jobId);
190
+ }
191
+ await reconcileDAGTasks(options);
192
+ await selectDAGReviewExecutors(options.store, options.jobId);
193
+ return options.store.load(options.jobId);
194
+ }
195
+ /** Content completion is independent of the Job activation source. Its legal
196
+ * ACTIVE -> COMPLETED transition belongs to the canonical Job graph. */
197
+ export async function completeContentJobIfEligible(store, jobId) {
198
+ if (!store.mutateJob)
199
+ return;
200
+ const eligible = (job) => job.state === 'ACTIVE' && job.contentOnly === true && job.prNumber === 0 &&
201
+ !job.localMerge && job.autoMerge === false && job.reviewEnabled === false && !job.review && !(job.plans?.length) &&
202
+ job.tasks.length > 0 && job.tasks.every(t => t.state === 'SUCCEEDED');
203
+ const snapshot = await store.load(jobId);
204
+ if (!eligible(snapshot))
205
+ return;
206
+ await store.mutateJob(jobId, job => {
207
+ if (!eligible(job))
208
+ return job;
209
+ const decision = dispatchJobLifecycleSync(job, 'content.completed', { contentCompletionAllowed: true });
210
+ if (!decision.accepted || decision.target !== 'COMPLETED')
211
+ throw Error('Content Job completion rejected by canonical Job lifecycle');
212
+ return job;
213
+ });
214
+ }
@@ -1,23 +1,29 @@
1
- /**
2
- * One active execution per Job, irrespective of adapter or current reconciler.
3
- * A claimed QUEUED execution also occupies the slot; synchronous P0/self work
4
- * occupies it by its RUNNING state even though it has no execution UUID.
5
- */
1
+ /** A Coordinator is a durable Task but does not occupy a Worker execution slot.
2
+ * Legacy delegated Shortcut Workers preserve their original foreground semantics. */
3
+ function occupiesSlot(job, task) {
4
+ if (task.agentGraph && task.result?.data?.dag?.version === 1)
5
+ return false;
6
+ const shortcut = task.result?.data?.shortcut;
7
+ const delegatedWorker = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
8
+ && shortcut && typeof shortcut === 'object'
9
+ && Object.keys(shortcut.workerNodes ?? {}).length > 0;
10
+ const durableWait = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
11
+ && task.leaseOwner === null && shortcut && typeof shortcut === 'object'
12
+ && Object.keys(shortcut.waits ?? {}).length > 0;
13
+ return task.state !== 'AWAITING_DECISION' && !durableWait && !delegatedWorker &&
14
+ (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
15
+ }
16
+ function plannerOccupies(job, planId) {
17
+ return (job.plans ?? []).some(plan => plan.id !== planId && plan.executionId !== null && plan.status === 'PLANNING');
18
+ }
6
19
  export function jobHasActiveExecution(job, except = {}) {
7
- const worker = job.tasks.some(task => {
8
- if (task.id === except.taskId)
9
- return false;
10
- const shortcut = task.result?.data?.shortcut;
11
- const delegatedWorker = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
12
- && task.result?.data?.shortcut && typeof task.result.data.shortcut === 'object'
13
- && Object.keys(task.result.data.shortcut.workerNodes ?? {}).length > 0;
14
- const durableWait = job.executionMode === 'shortcut' && job.contentOnly === true && task.state === 'RUNNING'
15
- && task.leaseOwner === null && shortcut && typeof shortcut === 'object'
16
- && shortcut.waits
17
- && Object.keys(shortcut.waits).length > 0;
18
- return task.state !== 'AWAITING_DECISION' && !durableWait && !delegatedWorker && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state)));
19
- });
20
- const planner = (job.plans ?? []).some(plan => plan.id !== except.planId
21
- && plan.executionId !== null && plan.status === 'PLANNING');
22
- return worker || planner;
20
+ return job.tasks.some(task => task.id !== except.taskId && occupiesSlot(job, task)) || plannerOccupies(job, except.planId);
21
+ }
22
+ /** Only sibling DAG Tasks may execute concurrently; unrelated Tasks retain
23
+ * the existing one-active-execution-per-Job safety boundary. */
24
+ export function jobHasConflictingExecution(job, candidate) {
25
+ if (!candidate.dagNode)
26
+ return jobHasActiveExecution(job, { taskId: candidate.id });
27
+ return plannerOccupies(job) || job.tasks.some(task => task.id !== candidate.id && occupiesSlot(job, task) &&
28
+ task.dagNode?.parentTaskId !== candidate.dagNode?.parentTaskId);
23
29
  }
package/dist/pool.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { unifiedDAG } from './dag-task-runtime.js';
1
2
  import { listManagedGitHubJobs } from './store.js';
2
3
  import { eventFor } from './events.js';
3
4
  import { ReconcileCoordinator } from './reconcile-coordinator.js';
@@ -41,6 +42,8 @@ export function needsLifecycleReconciliation(job, now = Date.now()) {
41
42
  if (review.accepted && review.actions.some(action => action.id === 'review.create'))
42
43
  return true;
43
44
  }
45
+ if (job.tasks.some(task => unifiedDAG(job, task) && task.state === 'RUNNING'))
46
+ return true;
44
47
  if (job.tasks.some(task => (task.state === 'QUEUED' && task.executionId === null)
45
48
  || (task.state === 'RUNNING' && task.adapter === 'orchestrator' && task.executionId === null)
46
49
  || (task.state === 'DRAFT' && task.dependencies.length > 0)))
@@ -153,7 +156,7 @@ export class RepositoryWorkerPool {
153
156
  const outcome = await reconciler.applyEvent(signal.event);
154
157
  // The decision is durably applied before invoking the Shortcut CLI hook.
155
158
  // A replay can also wake a still-QUEUED Task without a new decision.
156
- if (signal.event.type === 'task.interactive_decision' &&
159
+ if (signal.event.type === 'task.interactive_decision' && !target.job.tasks.some(t => unifiedDAG(target.job, t)) &&
157
160
  ['task.interactive_decision.accepted', 'task.interactive_decision.duplicate'].includes(outcome.reason) &&
158
161
  await this.onShortcutDecision?.(jobId, signal.event.task_id))
159
162
  continue;
@@ -168,8 +171,8 @@ export class RepositoryWorkerPool {
168
171
  for (const job of jobs) {
169
172
  if (capacity <= 0)
170
173
  break;
171
- // Shortcut starts and review resumes are external CLI invocations, not normal Task dispatch.
172
- if (job.executionMode === 'shortcut')
174
+ // Legacy in-flight Shortcut Jobs retain their original foreground owner.
175
+ if (job.executionMode === 'shortcut' && !job.tasks.some(t => unifiedDAG(job, t)))
173
176
  continue;
174
177
  const store = await this.requireLocalStore(job.id);
175
178
  await store.hydrate?.(job);
@@ -1,3 +1,4 @@
1
+ import { dagCompletionError } from './dag-result-contract.js';
1
2
  import { dependencyRevisionStillCurrent } from './dependency-revision-execution.js';
2
3
  import { isFinalReviewAgent } from './final-review-role.js';
3
4
  import { handleWorkerLaunchFailure } from './worker-failure-recovery.js';
@@ -92,6 +93,13 @@ export class ReconcilerRuntimeBase {
92
93
  if (event.type === 'task.completed') {
93
94
  const latest = await this.store.load(event.job_id);
94
95
  const task = latest.tasks.find(item => item.id === event.task_id);
96
+ if (task?.dagNode) {
97
+ const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(latest, task) : undefined;
98
+ const invalid = await dagCompletionError(task, projectPath);
99
+ if (invalid)
100
+ return this.applyTerminalEvent({ ...event, type: 'task.failed',
101
+ message: invalid, data: { ...event.data, reason: 'invalid_dag_result' } });
102
+ }
95
103
  // Source generation still goes through canonical Task terminal
96
104
  // correlation; convert stale verification into a safe supersede event.
97
105
  if (task?.revision && task.revision.kind !== 'targeted' && !dependencyRevisionStillCurrent(latest, task)) {
@@ -246,7 +254,7 @@ export class ReconcilerRuntimeBase {
246
254
  return true;
247
255
  const sourceId = eventSourceId(event);
248
256
  const expected = executionEventSource(jobId, task.id, task.executionId);
249
- if ((['codex', 'chatgpt', 'z'].includes(task.adapter)) && sourceId !== expected)
257
+ if ((['codex', 'chatgpt', 'z', 'script'].includes(task.adapter)) && sourceId !== expected)
250
258
  return false;
251
259
  if (afterCommit)
252
260
  claimTerminalExecution(expected);
@@ -403,7 +411,7 @@ export class ReconcilerRuntimeBase {
403
411
  const lifecycleEvent = event.type;
404
412
  const transition = await withExecutionBoundary(event.job_id, event.task_id, () => this.taskTransitions.apply(event.job_id, event.task_id, lifecycleEvent, {
405
413
  eligible: (_job, task) => {
406
- if (!['codex', 'chatgpt', 'z', 'orchestrator'].includes(task.adapter))
414
+ if (!['codex', 'chatgpt', 'z', 'script', 'orchestrator'].includes(task.adapter))
407
415
  return false;
408
416
  if (event.type === 'task.blocked' && (!trustedInternal || task.agentName !== 'troubleshooter'))
409
417
  return false;
@@ -416,7 +424,7 @@ export class ReconcilerRuntimeBase {
416
424
  return false;
417
425
  if (event.type === 'task.completed' && task.interactiveInvocation?.status !== undefined && task.interactiveInvocation.status !== 'approved')
418
426
  return false; // current interactive revision requires durable approval
419
- const modelBacked = ['codex', 'chatgpt', 'z'].includes(task.adapter);
427
+ const modelBacked = ['codex', 'chatgpt', 'z', 'script'].includes(task.adapter);
420
428
  if (!trustedInternal && modelBacked && !isCorrelatedWorkerEvent(task, event)) {
421
429
  const eventExecutionId = executionIdFromSource(eventSourceId(event), _job.id, task.id);
422
430
  const prior = eventExecutionId ? task.executionHistory?.find(item => item.id === eventExecutionId) : undefined;
@@ -432,7 +440,7 @@ export class ReconcilerRuntimeBase {
432
440
  return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough, awaitingInteractiveDecision: lifecycleEvent === 'task.interactive_waiting' && task.interactiveInvocation?.status === 'awaiting_decision' };
433
441
  },
434
442
  mutate: (job, task) => {
435
- const modelBacked = ['codex', 'chatgpt', 'z'].includes(task.adapter);
443
+ const modelBacked = ['codex', 'chatgpt', 'z', 'script'].includes(task.adapter);
436
444
  const acceptedExecutionId = task.executionId;
437
445
  const eventExecutionId = executionIdFromSource(eventSourceId(event), job.id, task.id);
438
446
  const terminalExecutionId = eventExecutionId ?? acceptedExecutionId;
@@ -29,7 +29,7 @@ import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
29
29
  import { exhaustedTroubleshooterRecoveries, pendingTroubleshooterTasks, pendingTroubleshooterReopens, pendingTroubleshooterRetries, refreshTroubleshooterInput } from './troubleshooter.js';
30
30
  import { fallbackFailedTroubleshooters, escalateExhaustedTroubleshooters } from './troubleshooter-fallback.js';
31
31
  import { cleanupMergedJobWorktree } from './job-worktree-cleanup.js';
32
- import { jobHasActiveExecution } from './job-execution-slot.js';
32
+ import { jobHasConflictingExecution } from './job-execution-slot.js';
33
33
  import { requiresWorkerInactivityWatchdog } from './task-inactivity-watchdog.js';
34
34
  import { managedWorkerInput } from './managed-worker-input.js';
35
35
  import { launchShortcutEffect, resumeShortcutEffect, resumeShortcutEventWaits } from './reconciler-shortcut.js';
@@ -42,6 +42,8 @@ import { repairLegacyOrchestrators } from './legacy-orchestrator-repair.js';
42
42
  import { launchPlanExecution } from './planner-runtime.js';
43
43
  import { classifyFailure, errorMessage, observability, withObservabilityCorrelation } from './observability.js';
44
44
  import { recoverInteractiveDecisions } from './interactive-resume.js';
45
+ import { reconcileDAGSchedule, unifiedDAG } from './dag-task-runtime.js';
46
+ import { ScriptTaskAdapter } from './script-task-adapter.js';
45
47
  const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
46
48
  export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
47
49
  export class Reconciler extends ReconcilerReviewBase {
@@ -62,9 +64,7 @@ export class Reconciler extends ReconcilerReviewBase {
62
64
  }
63
65
  async dispatchExecutableTasks(jobId) {
64
66
  const scheduled = refreshTaskDependencies(await this.store.load(jobId));
65
- // Ordinary daemon/queue never owns Shortcut Jobs, including recovery Tasks.
66
- // Only the explicit foreground runner may use existing Worker Adapters.
67
- if (scheduled.executionMode === 'shortcut' && !this.options.shortcutRunnerOwner)
67
+ if (scheduled.executionMode === 'shortcut' && !scheduled.tasks.some(t => unifiedDAG(scheduled, t)) && !this.options.shortcutRunnerOwner)
68
68
  return scheduled;
69
69
  if (scheduled.pause)
70
70
  return scheduled;
@@ -72,17 +72,15 @@ export class Reconciler extends ReconcilerReviewBase {
72
72
  this.detach(this.deliverContinuation(scheduled, task), scheduled.id, task.id, 'continuation');
73
73
  }
74
74
  const capacity = Math.max(0, (this.options.maxConcurrent ?? 4) - this.live.size - this.plannerLive.size);
75
- const dispatchable = (jobHasActiveExecution(scheduled) ? [] : scheduled.tasks)
76
- .filter(task => revisionRequestReady(scheduled, task) && task.state === 'QUEUED'
77
- && task.executionId === null
78
- && task.kind !== 'planner'
79
- && task.adapter !== 'orchestrator'
80
- && dependencyReady(task, new Map(scheduled.tasks.map(item => [item.id, item]))))
81
- .sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2'))
82
- .slice(0, Math.min(capacity, 1));
75
+ const ready = scheduled.tasks.filter(task => !unifiedDAG(scheduled, task) && revisionRequestReady(scheduled, task) &&
76
+ task.state === 'QUEUED' && task.executionId === null && task.kind !== 'planner' && task.adapter !== 'orchestrator' &&
77
+ dependencyReady(task, new Map(scheduled.tasks.map(item => [item.id, item]))) && !jobHasConflictingExecution(scheduled, task))
78
+ .sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2'));
79
+ const firstDAG = ready[0]?.dagNode?.parentTaskId;
80
+ const dispatchable = (firstDAG ? ready.filter(t => t.dagNode?.parentTaskId === firstDAG) : ready.slice(0, 1)).slice(0, capacity);
83
81
  for (const task of dispatchable) {
84
82
  const shortcut = task.result?.data?.shortcut;
85
- await transitionTaskEvent(task, 'dispatch', { dispatchable: true, shortcutExecution: scheduled.executionMode === 'shortcut' && scheduled.contentOnly === true && shortcut?.workerFallback !== true && Boolean(task.agentGraph), shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task.agentGraph) }, async (actionId) => {
83
+ await transitionTaskEvent(task, 'dispatch', { dispatchable: true, shortcutExecution: scheduled.executionMode === 'shortcut' && scheduled.contentOnly === true && shortcut?.workerFallback !== true && Boolean(task.agentGraph) && !unifiedDAG(scheduled, task), shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task.agentGraph) }, async (actionId) => {
86
84
  const outcomes = await this.workflowEffects.execute([actionId], { jobId: scheduled.id, taskId: task.id, transitionKey: `dispatch:${task.attempt}`, data: { attempt: task.attempt, ...(task.interactiveInvocation?.decidedAt ? { reviewInvocationId: task.interactiveInvocation.invocationId } : {}) } });
87
85
  await this.applyTaskEffectOutcomes(scheduled, task, outcomes);
88
86
  }, async () => { await this.store.saveTask(task); });
@@ -97,7 +95,7 @@ export class Reconciler extends ReconcilerReviewBase {
97
95
  let job = await this.store.load(jobId);
98
96
  // The same durable Job flag covers children, retries, and Troubleshooters.
99
97
  // Do not let a background Reconciler mutate or dispatch any of them.
100
- if (job.executionMode === 'shortcut' && !this.options.shortcutRunnerOwner)
98
+ if (job.executionMode === 'shortcut' && !job.tasks.some(t => unifiedDAG(job, t)) && !this.options.shortcutRunnerOwner)
101
99
  return job;
102
100
  await drainProductionWorkflowOutbox(this.store, this.options);
103
101
  await deliverPendingEscalations(this.store, jobId, this.options.escalationNotifier);
@@ -206,6 +204,7 @@ export class Reconciler extends ReconcilerReviewBase {
206
204
  scheduled = refreshTaskDependencies(await this.store.load(jobId));
207
205
  }
208
206
  scheduled = refreshTaskDependencies(await this.maybeCreatePlanner(scheduled));
207
+ scheduled = refreshTaskDependencies(await reconcileDAGSchedule({ store: this.store, jobId, job: scheduled, projectPathForTask: async (j, t) => j.shortcutRunnerContext?.projectPath ?? (this.options.projectPathForJob ? this.options.projectPathForJob(j, t) : t.routing?.cwd ?? process.cwd()), roots: this.options.executionContextRoots }));
209
208
  if (scheduled.state !== previousState || scheduled.updatedAt !== job.updatedAt)
210
209
  await this.store.saveJob(scheduled);
211
210
  scheduled = await this.dispatchExecutableTasks(jobId);
@@ -286,11 +285,11 @@ export class Reconciler extends ReconcilerReviewBase {
286
285
  emitFailed: async (task, reason) => { await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error ?? reason, 'user', { reason })); },
287
286
  };
288
287
  }
289
- async recoverLostExecutions(job, now) { if (job.executionMode !== 'shortcut' || this.options.shortcutRunnerOwner)
288
+ async recoverLostExecutions(job, now) { if (job.executionMode !== 'shortcut' || job.tasks.some(t => unifiedDAG(job, t)) || this.options.shortcutRunnerOwner)
290
289
  await recoverExpiredExecutions(job, now, this.executionRecoveryPorts(job)); }
291
290
  async recoverStartupOrphans(jobId) {
292
291
  const job = await this.store.load(jobId);
293
- if (job.state === 'ACTIVE' && (job.executionMode !== 'shortcut' || this.options.shortcutRunnerOwner === true)) {
292
+ if (job.state === 'ACTIVE' && (job.executionMode !== 'shortcut' || job.tasks.some(t => unifiedDAG(job, t)) || this.options.shortcutRunnerOwner === true)) {
294
293
  await recoverStartupExecutionOrphans(job, this.executionRecoveryPorts(job));
295
294
  }
296
295
  return this.store.load(jobId);
@@ -366,12 +365,12 @@ export class Reconciler extends ReconcilerReviewBase {
366
365
  return;
367
366
  if (freshTask.executionId !== null)
368
367
  return;
369
- if (jobHasActiveExecution(freshJob, { taskId: freshTask.id }))
368
+ if (jobHasConflictingExecution(freshJob, freshTask))
370
369
  return;
371
370
  if (isFinalReviewAgent(freshTask.agentName) && freshTask.planningDecisionId && freshTask.dependencies.length)
372
371
  await bindPlannedReviewHead(this.store, freshTask, await this.currentHeadSha(freshJob));
373
372
  const implementationThread = resolveImplementationTaskThreadDestination(freshJob, freshTask);
374
- if ((!freshTask.routing || ((implementationThread || (isFinalReviewAgent(freshTask.agentName) && resolveReviewerThreadDestination(freshJob, this.options.reviewer?.threadId))) && freshTask.adapter !== 'chatgpt')) && freshTask.adapter !== 'orchestrator') {
373
+ if (freshTask.adapter !== 'script' && (!freshTask.routing || ((implementationThread || (isFinalReviewAgent(freshTask.agentName) && resolveReviewerThreadDestination(freshJob, this.options.reviewer?.threadId))) && freshTask.adapter !== 'chatgpt')) && freshTask.adapter !== 'orchestrator') {
375
374
  const routed = await this.routeTaskForExecutionFailClosed(freshJob, freshTask);
376
375
  if (!routed)
377
376
  return;
@@ -456,7 +455,7 @@ export class Reconciler extends ReconcilerReviewBase {
456
455
  if (!reserved)
457
456
  throw new Error('already reserved launch attempt: reconcile existing generation');
458
457
  }
459
- const adapter = this.options.adapters.find(x => x.name === task.adapter);
458
+ const adapter = task.adapter === 'script' ? new ScriptTaskAdapter(event => this.options.eventBus ? this.emit(event) : this.handleEvent(event), this.options.executionContextRoots) : this.options.adapters.find(x => x.name === task.adapter);
460
459
  if (!adapter) {
461
460
  await this.failLaunch(job.id, task.id, task.executionId, 'No adapter ' + task.adapter);
462
461
  return;
@@ -464,7 +463,7 @@ export class Reconciler extends ReconcilerReviewBase {
464
463
  let executionContext;
465
464
  try {
466
465
  const role = isFinalReviewAgent(task.agentName) ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
467
- const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job, task) : task.routing?.cwd ?? process.cwd();
466
+ const projectPath = task.dagNode && job.shortcutRunnerContext?.projectPath ? job.shortcutRunnerContext.projectPath : this.options.projectPathForJob ? await this.options.projectPathForJob(job, task) : task.routing?.cwd ?? process.cwd();
468
467
  executionContext = await this.resolvedContext(job, task, role, projectPath);
469
468
  }
470
469
  catch (error) {
@@ -478,7 +477,7 @@ export class Reconciler extends ReconcilerReviewBase {
478
477
  const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
479
478
  let baseWorkerInput;
480
479
  try {
481
- baseWorkerInput = await managedWorkerInput(job, task, executionContext);
480
+ baseWorkerInput = task.adapter === 'script' ? task.input : await managedWorkerInput(job, task, executionContext);
482
481
  }
483
482
  catch (error) {
484
483
  await this.failLaunch(job.id, task.id, task.executionId, `Execution contract unavailable: ${error instanceof Error ? error.message : String(error)}`);
@@ -0,0 +1,118 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { once } from 'node:events';
3
+ import { dirname, isAbsolute } from 'node:path';
4
+ import { mkdir, writeFile } from 'node:fs/promises';
5
+ import { pathToFileURL } from 'node:url';
6
+ import { eventFor } from './events.js';
7
+ import { executionEventSource } from './execution-event-identity.js';
8
+ import { discoverShortcut } from './agent-shortcut.js';
9
+ import { spawnOwnedProcess } from './owned-process.js';
10
+ const valid = (value) => {
11
+ if (!value || typeof value !== 'object' || Array.isArray(value))
12
+ return false;
13
+ const r = value;
14
+ return r.status === 'COMPLETED' && !!r.output && typeof r.output === 'object' && !Array.isArray(r.output)
15
+ && (!!r.artifacts && typeof r.artifacts === 'object');
16
+ };
17
+ async function runCommand(args, cwd, signal) {
18
+ if (!args.length || args.some(a => typeof a !== 'string' || !a))
19
+ throw Error('Script command requires an argv vector');
20
+ const child = spawnOwnedProcess(args[0], args.slice(1), { invocation: 'dag.script-command', signal, spawn: { cwd, stdio: ['ignore', 'pipe', 'pipe'] } });
21
+ let stdout = '', stderr = '';
22
+ child.stdout?.on('data', c => { stdout += String(c); });
23
+ child.stderr?.on('data', c => { stderr += String(c); });
24
+ const [code] = await once(child, 'close');
25
+ return { stdout, stderr, code: code ?? -1 };
26
+ }
27
+ /** Script is just another Task Worker Adapter. It publishes exactly the same
28
+ * execution-scoped Task lifecycle events as a Model Worker. */
29
+ export class ScriptTaskAdapter {
30
+ onEvent;
31
+ roots;
32
+ name = 'script';
33
+ id = 'script';
34
+ capabilities = ['script'];
35
+ constructor(onEvent, roots = {}) {
36
+ this.onEvent = onEvent;
37
+ this.roots = roots;
38
+ }
39
+ launch(task, signal, context = {}) {
40
+ const dag = task.dagNode;
41
+ if ((dag && dag.executor !== 'script') || !task.executionId || !task.jobId || !task.agentName)
42
+ throw Error('Script Adapter requires a leased Agent Task');
43
+ if (task.output?.kind !== 'file' || !isAbsolute(task.output.path))
44
+ throw Error('Script Task requires absolute file output');
45
+ const outputPath = task.output.path;
46
+ const executionId = task.executionId;
47
+ const executionAbort = new AbortController();
48
+ const forwardAbort = () => executionAbort.abort(signal.reason ?? new Error('Script Task cancelled'));
49
+ if (signal.aborted)
50
+ forwardAbort();
51
+ else
52
+ signal.addEventListener('abort', forwardAbort, { once: true });
53
+ const source = { id: executionEventSource(task.jobId, task.id, executionId), agent: task.agentName, component: 'agents-relay' };
54
+ const send = async (type, status, message, data = {}) => {
55
+ await this.onEvent(eventFor(task.jobId, task.id, task.parentTaskId, type, status, message, 'orchestrator', data, source));
56
+ };
57
+ const promise = (async () => {
58
+ let stage = 'running';
59
+ try {
60
+ let input;
61
+ if (dag) {
62
+ input = JSON.parse(task.input);
63
+ if (input.source !== 'relay-dag-task' || input.nodeId !== dag.nodeId || input.taskId && input.taskId !== task.id)
64
+ throw Error('Script Task is not bound to its declared DAG node');
65
+ }
66
+ else {
67
+ let parsed;
68
+ try {
69
+ parsed = JSON.parse(task.input);
70
+ }
71
+ catch { }
72
+ input = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : { taskInput: task.input };
73
+ input = { ...input, source: 'relay-agent-task', taskId: task.id, outputPath };
74
+ }
75
+ const projectPath = context.executionContext?.project.path ?? input.projectPath;
76
+ if (typeof projectPath !== 'string' || !isAbsolute(projectPath))
77
+ throw Error('No trusted Script Project context');
78
+ const script = await discoverShortcut(task.agentName, projectPath, this.roots.sharedRoot ?? undefined, this.roots.workspaceRoot ?? undefined, this.roots.globalRoot ?? undefined);
79
+ if (!script)
80
+ throw Error(`Declared Agent Shortcut is unavailable: ${task.agentName}`);
81
+ await send('task.started', 'running', 'Script Worker started');
82
+ const module = await import(pathToFileURL(script).href);
83
+ if (typeof module.run !== 'function')
84
+ throw Error('Agent Shortcut must export run(context)');
85
+ const invocation = task.interactiveInvocation;
86
+ const review = invocation?.decidedAt && ['approved', 'changes_requested'].includes(invocation.status)
87
+ ? { status: invocation.status, revision: invocation.revision, invocationId: invocation.invocationId, feedback: invocation.feedback, comments: invocation.comments } : undefined;
88
+ if (executionAbort.signal.aborted)
89
+ throw executionAbort.signal.reason;
90
+ const result = await Promise.race([module.run({ input: { ...input, jobId: task.jobId, taskId: task.id, executionId,
91
+ ...(review ? { reviewDecision: review } : {}) }, signal,
92
+ runCommand: (args, cwd) => runCommand(args, cwd, executionAbort.signal) }), new Promise((_resolve, reject) => {
93
+ if (executionAbort.signal.aborted)
94
+ reject(executionAbort.signal.reason);
95
+ else
96
+ executionAbort.signal.addEventListener('abort', () => reject(executionAbort.signal.reason), { once: true });
97
+ })]);
98
+ if (result && typeof result === 'object' && result.status === 'WAITING_REVIEW') {
99
+ stage = 'waiting';
100
+ return { summary: 'Script Task waiting for authorized human review' };
101
+ }
102
+ if (!valid(result))
103
+ throw Error('Script Worker did not return a completed artifact contract');
104
+ await mkdir(dirname(outputPath), { recursive: true, mode: 0o700 });
105
+ await writeFile(outputPath, JSON.stringify(result, null, 2) + '\n');
106
+ await send('task.completed', 'succeeded', 'Script Worker completed', { status: 'COMPLETED', output: result.output, artifacts: result.artifacts });
107
+ stage = 'completed';
108
+ return { summary: 'Script Task completed' };
109
+ }
110
+ catch (error) {
111
+ if (!executionAbort.signal.aborted && stage === 'running')
112
+ await send('task.failed', 'failed', error instanceof Error ? error.message : String(error), { reason: 'script_execution_failed' });
113
+ throw error;
114
+ }
115
+ })().finally(() => signal.removeEventListener('abort', forwardAbort));
116
+ return { id: randomUUID(), promise, cancel: () => executionAbort.abort(new Error('Script Task cancelled')) };
117
+ }
118
+ }
@@ -41,6 +41,7 @@ export const WORKFLOW_EVENT_NAMES = [
41
41
  'task.started',
42
42
  'shortcut.waiting',
43
43
  'shortcut.completed',
44
+ 'content.completed',
44
45
  'shortcut.failed',
45
46
  'shortcut.result',
46
47
  'effect.launchShortcut.failed',
@@ -5,7 +5,7 @@ import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, }
5
5
  const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'AWAITING_DECISION', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
6
6
  const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
7
7
  const conditionRegistry = new ConditionRegistry([
8
- ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady', 'shortcutCompletionAllowed'])
8
+ ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady', 'shortcutCompletionAllowed', 'contentCompletionAllowed'])
9
9
  ].map(booleanCondition));
10
10
  const boolGuard = (name) => conditionRegistry.guard(name);
11
11
  export const lifecycleConditions = conditionRegistry;
@@ -64,6 +64,7 @@ export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
64
64
  && values.reviewHeadCurrent === true && values.mergeAttemptReady === true;
65
65
  },
66
66
  shortcutCompletionAllowed: facts => facts.durableFacts.shortcutCompletionAllowed === true,
67
+ contentCompletionAllowed: facts => facts.durableFacts.contentCompletionAllowed === true,
67
68
  });
68
69
  function topologyTargets(graph, from) {
69
70
  const source = [...graph.nodes.values()].find(node => node.kind === 'state' && node.semanticId === from);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.252",
3
+ "version": "2.0.253",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -16,9 +16,9 @@
16
16
  "test": "npm run test:full",
17
17
  "test:chatgpt-temp-quality": "AGENTS_RELAY_RUN_CHATGPT_TEMP_QUALITY=1 sh -c \"npm run build && node test/quality/run-temporary-chat.mjs\"",
18
18
  "dev": "tsx src/cli.ts",
19
- "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js test/verification/l3-shortcut-review.test.mjs",
20
- "test:l3:shortcut": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/l3-shortcut-review.test.mjs",
21
- "test:shortcut:dags": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/shortcut-dag-matrix.test.mjs test/verification/l3-shortcut-review.test.mjs test/agent-shortcut.test.js",
19
+ "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js test/verification/l3-shortcut-review.test.mjs test/verification/l3-unified-dag.test.mjs",
20
+ "test:l3:shortcut": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/l3-shortcut-review.test.mjs test/verification/l3-unified-dag.test.mjs",
21
+ "test:shortcut:dags": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/shortcut-dag-matrix.test.mjs test/verification/l3-shortcut-review.test.mjs test/verification/l3-unified-dag.test.mjs test/agent-shortcut.test.js",
22
22
  "test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/interactive-request.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js test/verification/shortcut-dag-matrix.test.mjs",
23
23
  "test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js test/verification/shortcut-dag-matrix.test.mjs && npm run test:verification:l3",
24
24
  "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/browser-worker-pool-graph.test.js test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/verification/force-restate-validation.test.mjs test/planner-child-recovery.test.js",
@@ -13,9 +13,9 @@ Explain **JEL** to the user: **Create → Plan → Execute → Final Review →
13
13
 
14
14
  ## 1. Choose and start a Job
15
15
 
16
- Use Relay when the objective requires independent Tasks, durable progress, retries, review, or cross-session handoffs. Capture the full user objective, decisions, constraints, acceptance checks, and delivery expectations in standalone Markdown before creating a Job. A fresh agent must be able to act without the originating conversation. Put a Mermaid diagram before its explanation only when it clarifies a real workflow.
16
+ Use Relay for durable multi-Task work. Record the standalone objective, constraints, acceptance checks, and deliverables before Job creation.
17
17
 
18
- For ordinary CLI use, consult `npx agents-relay --help` and `npx agents-relay <command> --help` rather than memorizing all flags. Examples:
18
+ Consult CLI help; examples:
19
19
 
20
20
  ```sh
21
21
  npx agents-relay job create --repo OWNER/REPO --title "Objective" --objective-file job.md --initial-plan
@@ -23,7 +23,7 @@ npx agents-relay job show --id JOB_ID
23
23
  npx agents-relay task list --repo OWNER/REPO --id JOB_ID
24
24
  ```
25
25
 
26
- Use the **Job ID returned by create**; do not invent an ID, PR number, or Task. Omit `--initial-plan` only for explicitly create-only work. Existing GitHub PRs are not imported as Jobs; GitHub is audit-only and local Git owns merge/delivery. For local-only work, consult the CLI's `--no-github` option.
26
+ Use the returned Job ID; never invent IDs. Omit `--initial-plan` only for create-only work. GitHub is audit-only; local Git owns merge. For local-only operations use `--no-github`.
27
27
 
28
28
  Read `contracts/task-job-contract.md` before authoring or changing Jobs or Tasks and `contracts/orchestrator-workflows.md` when handling initial planning, P0/self Jobs, or merge/delivery boundaries. For content work, load the active Neo Project rules, its Agent Graph if present, and the relevant stage contracts—not a presumed universal production sequence.
29
29
 
@@ -40,39 +40,49 @@ node <matching-absolute-dist/cli.js> task context --id JOB --task-id TASK --exec
40
40
  node <matching-absolute-dist/cli.js> plan context --id JOB --plan-id PLAN --execution-id EXECUTION
41
41
  ```
42
42
 
43
- These are alternative commands for Task and Planner executions. Both fail closed for stale identities. Optional `--repo` further constrains Job identity. Do not reconstruct task content from PR comments or guessed local files. The Planner submits its candidate through the returned `apply_cli`; only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt proves application. Follow the assigned Role and independent Contracts; load optional context only when the work requires it. Authorized delegation creates durable Relay child Tasks, not untracked agent processes.
43
+ Task and Planner context commands reject stale identities. Optional `--repo` constrains the Job. Never infer Task content from GitHub. Planner submits via `apply_cli`; only `PLAN_APPLIED:<plan-id>:<execution-id>` proves application. Authorized delegation creates durable child Tasks.
44
+
45
+ Graph Tasks use Relay's ordinary Task Reconciler: `agentGraph` becomes a
46
+ **Coordinator** with durable Agent-named children created as dependencies become
47
+ ready. Script and Model are Task execution choices; each has the same
48
+ Task-level retry, failure and review semantics. A Shortcut CLI starts an idle
49
+ Job and hands it to that same Reconciler; it is not a separate DAG scheduler.
44
50
 
45
51
  ## 3. Verify, review, and recover
46
52
 
47
- Use the pinned CLI to inspect authoritative status, Task events, comments, and review evidence. For SHA-bound final Job review, use `agents-relay review job --repo OWNER/REPO --id JOB_ID [--thread-id THREAD_ID]`; for independent Agent-owned outcome review, use `agents-relay review run --prompt-file PATH --project-path DIR`.
53
+ Inspect Task status/events with pinned CLI. Final Review: `agents-relay review job --repo OWNER/REPO --id JOB_ID [--thread-id THREAD_ID]`. Agent review: `agents-relay review run --prompt-file PATH --project-path DIR`.
48
54
 
49
- A worker's process exit, browser submission receipt, or emitted event is **not** proof of durable completion. Task agents publish `task.started`, optional `task.progress`, and exactly one correlated terminal `task.completed` or `task.failed` via the canonical `events-bus` capability. Never emit `task.blocked` as a worker terminal outcome. Read `contracts/event-contract.md` for exact identity, event semantics, and reviewer verdict payloads; implementation agents also follow `contracts/worker-self-review.md`.
55
+ Process exit and delivery are not Task completion. Agents publish `task.started`, optional `task.progress`, and one correlated terminal `task.completed` or `task.failed` via `events-bus`; never `task.blocked`. See `contracts/event-contract.md` and `contracts/worker-self-review.md`.
50
56
 
51
57
  A Reviewer finding defects in a known immutable head emits `task.completed` with `data.verdict: changes-required`, `data.head_sha`, and actionable findings—not `task.failed`. If the Reviewer cannot establish the required head or produce a valid review, it reports an execution failure with `task.failed`, not an invented verdict.
52
58
 
53
- For a failed Task, diagnose before retrying. Read `contracts/task-recovery-flows.md` for recovery and human escalation boundaries. For authorized technical prerequisites in another repository, use `contracts/blocker-job-recovery.md` and the pinned `blocker ensure` CLI action; repository boundaries alone do not justify escalation. Troubleshooter inspects the original Task via `task show` and paginated `task events`, verifies the root cause, then uses the pinned CLI `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER` only after proving the repair. Only a genuinely human-required decision justifies the **pinned CLI** `task escalate --task-id TROUBLESHOOTER --required-action ... --resolution-condition ...`; this is a Relay operation, **not** an Events Bus event. Never invent or publish an escalation event, and never escalate a browser-readiness failure as a login request without authentication evidence. Only Relay can block/unblock a Troubleshooter; after a human response, recheck the blocker before recovering the original Task. Do not silently treat missing or stale evidence as success.
59
+ For a failed Task, **diagnose before retrying**. Load
60
+ `contracts/task-recovery-flows.md`; for external repository prerequisites load
61
+ `contracts/blocker-job-recovery.md`. Troubleshooter inspects the exact Task's
62
+ state and paginated event history, proves the technical repair and calls the
63
+ pinned `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER`.
64
+ For verified human-only blockers, use pinned `task escalate --task-id ...`;
65
+ this is a Relay CLI operation, not an Event. Recheck evidence after escalation;
66
+ never treat a stale response or an unverified operation as recovery.
54
67
 
55
68
  ## 4. Configured escalation and host-owned Interactive Review
56
69
 
57
- `agents-relay escalation` executes the canonical Escalation Graph using only
58
- `AGENTS_RELAY_ESCALATION_COMMAND` provided by the operator's environment. The
59
- value is either an **absolute executable path** or a JSON argv array with an
60
- absolute executable first (for example
61
- `'["/opt/homebrew/bin/neo","escalation"]'` on a host explicitly using Neo).
62
- Relay appends `--handoff-file`, optional `--on-needs-user-file` and `--cwd`.
63
- No Shell expansion or default `neo` call is allowed. Missing or broken
64
- configuration returns `technical_failure`; it must never be treated as
65
- `resolved` or `needs_user`. This direct escalation command is distinct from
66
- `task escalate`, which is the durable Troubleshooter/human-blocker transition.
67
-
68
- Human Preview uses `review.interactive.begin/wait/ready/fail/abort` and the
69
- canonical `task.interactive_waiting` contract. The provider owns media and
70
- notifications; a delivery receipt is **not approval**. Never forge event
71
- identity or create a separate Review Provider. For Shortcut Preview, invoke
72
- the tool with the **original Task identity**, return `WAITING_REVIEW` after
73
- Relay durably suspends it, then resume that Task after an authenticated
74
- decision. Neo Preview commits the Run Git revision automatically; no separate
75
- checkpoint CLI. See `contracts/event-contract.md` for details.
70
+ `agents-relay escalation` runs the canonical Escalation Graph only with
71
+ an operator-configured `AGENTS_RELAY_ESCALATION_COMMAND` (absolute executable
72
+ or JSON argv with an absolute executable). Missing/broken configuration
73
+ returns `technical_failure`, never presumed human resolution. This differs
74
+ from the Task Troubleshooter `task escalate` operation.
75
+
76
+ A Worker requests human Review once in its current execution using
77
+ `agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`.
78
+ Relay delegates rendering to the configured host (Neo uses `review.preview` and
79
+ Markcut). The reviewed Task enters `AWAITING_DECISION`. An inbox/compile receipt
80
+ is **not approval**. An accepted Approve resumes the same Agent Task; Request
81
+ Changes resumes the same Task with feedback (a scripted Task can switch to its
82
+ Model executor for semantic revision, then return to Script for validation).
83
+ One execution ID identifies at most one review. Preview does **not** create Git
84
+ commits, snapshots or independent reviewer Tasks. Legacy in-flight Shortcut
85
+ checkpoints remain compatible. See `contracts/event-contract.md`.
76
86
 
77
87
  ## 5. Manage services when needed
78
88
 
@@ -44,21 +44,23 @@ A fix child reports its **own** correlated completion after verified repair. Dow
44
44
 
45
45
  ## Interactive Task suspension
46
46
 
47
- For a **host-wrapped interactive review tool**, the Worker supplies the
48
- reviewable output path and the authoritative `relay: {jobId, taskId,
49
- executionId}` binding as required by that tool's caller-provided contract.
50
- The host owns the Invocation, immutable review material, wait binding and
51
- notification delivery. The Worker never fabricates the Invocation ID or
52
- publishes an additional waiting/terminal event when the host manages handoff.
53
- No particular review product, MCP server or mobile client is required.
54
-
55
- For other host adapters, after binding an Invocation a RUNNING Worker waiting
56
- for human input publishes `task.interactive_waiting` with its exact
57
- Job/Task/Execution source identity.
58
- Relay checks the pending invocation, persists RUNNING -> AWAITING_DECISION,
59
- clears the execution lease, and releases the Worker. This is a non-failure
60
- handoff and is not a Task completion or a Troubleshooter block.
61
- For Shortcut modules, a host-wrapped `markcut.preview` call uses the **original Shortcut Task identity**, not a reviewer child. The module returns `WAITING_REVIEW` only after the host has durably transitioned that Task to `AWAITING_DECISION`. The foreground runner exits with waiting status, keeping the in-flight node as a durable replay fence. After an authenticated accepted decision, the lifecycle requeues that same Task. The interactive decision event listener calls the same trusted Shortcut Runner CLI used for manual execution, immediately after Relay durably accepts the decision and requeues the original Task. It does not schedule Shortcuts through the normal Worker Pool. It never auto-starts draft or unlaunched Shortcut Jobs and does not add a separate Scheduler. On `changes_requested`, a Script node invokes its Agent's normal durable model Worker to revise existing Artifacts, then re-verifies and opens a new human Preview. `approved` continues the Graph. Nonhuman `WAITING_EVENT` receipts are a different mechanism.
47
+ For a managed human Preview the current Agent Task calls
48
+ `agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`.
49
+ The host may expose `review.preview`; it renders and delivers without managing
50
+ Task state. Relay binds one review to that Task Execution ID, persists
51
+ `RUNNING -> AWAITING_DECISION`, releases the execution lease, accepts a
52
+ correlated decision, and requeues **the same Task**. The Agent does not call the
53
+ low-level Review lifecycle commands, invent an invocation ID, or emit another
54
+ waiting/terminal event on behalf of its host. An inbox acknowledgement is not
55
+ approval. No Git commit, content snapshot or SHA is required for human Review.
56
+
57
+ For new DAG executions, the Coordinator creates normal Agent Tasks; a review
58
+ belongs to the corresponding Agent child, not the Coordinator. The ordinary
59
+ Reconciler (not the external Shortcut start CLI) schedules their retries and
60
+ revisions. A Script Task on `changes_requested` may use its own Agent Model
61
+ executor in a **new execution of that same Task**; after a fresh approval,
62
+ Script verifies the revised artifacts. Legacy running Shortcut checkpoints
63
+ retain the earlier foreground-runner resume behavior until completion.
62
64
 
63
65
  The Job stays ACTIVE; the Task does not requeue until a matching
64
66
  `task.interactive_decision` is durably accepted and the Task Graph selects
@@ -14,6 +14,7 @@ cancelActive["action: effect.cancelActiveTasks"]
14
14
  localCompletionGuard["guard: localCompletionAllowed"]
15
15
  localMergeReadyGuard["guard: localMergeReady"]
16
16
  shortcutCompletionGuard["guard: shortcutCompletionAllowed"]
17
+ contentCompletionGuard["guard: contentCompletionAllowed"]
17
18
  localMergeDelivery["action: effect.deliverLocalMerge"]
18
19
 
19
20
  draft -->|on: activate| active
@@ -29,6 +30,9 @@ cancelActive --> cancelled
29
30
  active -->|on: local.completed| localCompletionGuard
30
31
  localCompletionGuard -->|true| completed
31
32
  localCompletionGuard -->|false| active
33
+ active -->|on: content.completed| contentCompletionGuard
34
+ contentCompletionGuard -->|true| completed
35
+ contentCompletionGuard -->|false| active
32
36
  active -->|on: shortcut.completed| shortcutCompletionGuard
33
37
  shortcutCompletionGuard -->|true| completed
34
38
  shortcutCompletionGuard -->|false| active