agents-relay 2.0.252 → 2.0.254

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
 
@@ -377,3 +380,16 @@ The caller must report only a release it has actually verified. For local-first
377
380
  ### Project-scoped agent Markdown inheritance
378
381
 
379
382
  Agent lookup has exactly two layers: Relay built-in `skills/agents-relay/agents/` and `<job-context-root>/agents/`. `job.projectPath` selects the context root within the repository (including monorepo content projects); no workspace/global agent fallback is searched. Project agent frontmatter can specify `extends: relay/planner`, `mode: extend`, and `sections: { replace: [Heading/Subheading], extend: [Other Heading] }` using heading paths, or `mode: replace` for a full behavioral replacement. Relay-owned lifecycle, Job/Task and events contracts are injected separately and cannot be replaced by a project agent. An unextended local agent is a standalone definition. The resolver emits a deterministic SHA-256 of composed Markdown; a missing section or unsupported parent fails instead of silently dropping instructions.
383
+
384
+ ### Plan-free Graph Jobs (unified start)
385
+
386
+ Create a Job without `--initial-plan`, materialize one queued Agent Graph Task,
387
+ then activate it with `agents-relay job run --id JOB --task-id TASK`. No
388
+ `executionMode` is stored; `job run` only activates and publishes a wake-up.
389
+ The ordinary Reconciler creates the Coordinator and durable Agent-named Tasks,
390
+ with the same Script/Model execution, Task Review, Retry and recovery used by
391
+ all other Jobs. `--content-only` is an **independent Job policy** that disables
392
+ Final Job Review and merge; omit it to keep the ordinary Job completion gates.
393
+ The old `--shortcut-execution` input aliases this policy for existing callers,
394
+ but creates no special execution mode. Historical completed/cancelled Shortcut
395
+ records retain their old fields for read-only compatibility.
@@ -84,5 +84,5 @@ export async function agentGraphPrompt(context, source) {
84
84
  validateAgentSelection(context, undefined, source);
85
85
  const contracts = await Promise.all(graph.nodes.map(async (node) => ({ node, prompt: await agentContractPrompt(context, node.agent) })));
86
86
  const incoming = new Map(graph.nodes.map(node => [node.id, graph.edges.filter(edge => edge.to === node.id).map(edge => edge.from)]));
87
- return `[Task Agent Graph]\n${source.trim()}\n\nExecution waves: ${graph.waves.map((wave, index) => `${index + 1}:${wave.join(',')}`).join(' | ')}\n\nExecute this graph inside the current durable Task. Nodes are reasoning roles, NOT durable child Tasks. Preserve the original Job/Task context for every node. Nodes in the same wave are independent: evaluate each from the same original context without using sibling prose. For each later node, provide the original context plus structured outputs only from its declared predecessors. Do not emit outer task.started or task terminal events per node; the current durable Task owns exactly one start and one terminal event.\n\n${contracts.map(({ node, prompt }) => `[Node ${node.id}; predecessors=${(incoming.get(node.id) ?? []).join(',') || 'none'}]\n${prompt}`).join('\n\n')}`;
87
+ return `[Task Agent Graph]\n${source.trim()}\n\nExecution waves: ${graph.waves.map((wave, index) => `${index + 1}:${wave.join(',')}`).join(' | ')}\n\nThe Coordinator materializes each graph node as its own durable Agent Task when its predecessors succeed. All Agent Tasks use the ordinary Reconciler and Task Lifecycle. Each child receives only the original Job/Task context and structured outputs of its declared predecessors. Independent nodes may run concurrently. Never execute the entire graph inside one Model Worker, invent additional Tasks, or publish another Task's lifecycle events.\n\n${contracts.map(({ node, prompt }) => `[Node ${node.id}; predecessors=${(incoming.get(node.id) ?? []).join(',') || 'none'}]\n${prompt}`).join('\n\n')}`;
88
88
  }
@@ -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') })));
package/dist/cli-help.js CHANGED
@@ -40,7 +40,7 @@ Actions:
40
40
  create Create a durable SQLite-authoritative Job
41
41
  update Partially update mutable metadata on a healthy existing Job
42
42
  show Show one durable Job
43
- run Opt in to direct Agent Graph shortcuts for one existing Task
43
+ run Activate a create-only Job with a durable Agent Graph Task
44
44
  shortcut-receipt Atomically record a validated nonhuman result for a persisted wait
45
45
  list List managed Jobs in a repository
46
46
  merge Legacy entry point; local Git merge is Graph-owned (no CLI PR merge)
@@ -53,17 +53,15 @@ Common options:
53
53
  --repo OWNER/REPO Required for create; optional Job identity check otherwise
54
54
  --id JOB_ID Durable job identifier
55
55
 
56
- Shortcut execution:
57
- agents-relay job run --mode shortcut --id JOB --task-id TASK
58
- [--store-dir DIR] [--project-path DIR] [--shared-root DIR] [--concurrency 4]
56
+ Graph Job activation:
57
+ agents-relay job run --id JOB --task-id TASK
58
+ [--project-path DIR] [--workspace-root DIR]
59
59
 
60
- The selected Task must have an Agent Graph. Project shortcuts at
61
- agents/.shortcut/<agent>.agent.mjs override configured shared shortcuts. A Graph
62
- with any missing shortcut falls back to the normal durable Worker before
63
- executing any module; mixing shortcut and Worker nodes in one Graph is unsupported.
64
- Shortcuts that fail before effects also return to the Worker queue. Nonhuman waits resume only from a matching SQLite Task receipt; EventBus
65
- events are wake signals. Human approval remains hostInvocation-only.
66
- Shortcut Job completion requires durable contentOnly=true and no PR, merge, or review gates.
60
+ The Job is created DRAFT without a Planner. This command activates its Graph
61
+ Task, then the same Relay Reconciler schedules all durable Agent child Tasks.
62
+ Use --content-only on job create only when no Final Review or Merge is wanted.
63
+ The --mode shortcut flag is accepted only as a deprecated CLI input alias.
64
+ Historical direct Shortcut checkpoints are read for compatibility.
67
65
 
68
66
  Record an asynchronous result with:
69
67
  agents-relay job shortcut-receipt --id JOB --task-id TASK
@@ -118,11 +116,20 @@ Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job r
118
116
  'job create': `Create a SQLite-authoritative Job (objective-only).
119
117
 
120
118
  Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing store-global number; --id may only reference an existing numeric Job.
121
- Common: --id JOB_ID (optional), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --initial-plan, --no-review, --shortcut-execution, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive.
122
- Job creation enables auto-merge by default. By default it is create-only; --initial-plan validates the first real Planner round before atomically creating the durable Job and Plan, then publishes the normal wake. --shortcut-execution creates a create-only content-only Job with durable direct Graph execution policy, no auto-merge, and no review; select it before Tasks are materialized and do not combine it with --initial-plan. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
119
+ Common: --id JOB_ID (optional), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --initial-plan, --no-review, --content-only, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive.
120
+ Job creation enables auto-merge by default. By default it is create-only; --initial-plan validates the first real Planner round before atomically creating the durable Job and Plan, then publishes the normal wake. --content-only disables Final Review and Merge independent of how the Job starts; do not combine it with --initial-plan. The deprecated --shortcut-execution input is an alias for --content-only and is never persisted as an execution mode. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
123
121
 
124
122
  Example:
125
123
  npx agents-relay job create --repo OWNER/REPO --project-path vlog --title "Episode" --objective-file episode.md --initial-plan`,
124
+ 'job run': `Activate a create-only Job with a durable Agent Graph Task. No Planner or execution mode is required.
125
+
126
+ Usage: agents-relay job run --id JOB --task-id TASK [--project-path DIR] [--no-github]
127
+
128
+ The command activates the normal Job lifecycle and emits a wake-up. The ordinary
129
+ Relay Scheduler creates runtime Agent Tasks, runs Script or Model executors,
130
+ waits for human review, retries failures and handles completion. A Job may use
131
+ --content-only independent of how it starts. --mode shortcut is a deprecated
132
+ input alias; it does not choose an execution engine.`,
126
133
  'job update': `Partially update mutable metadata on a healthy existing Job.
127
134
 
128
135
  Required: --id JOB_ID. Optional: --repo OWNER/REPO verifies the stored Job identity.
@@ -53,10 +53,10 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
53
53
  description: pr.body || undefined,
54
54
  priority: options.priority ?? 'P2',
55
55
  tag: options.tag,
56
- autoMerge: options.executionMode === 'shortcut' ? false : true,
56
+ autoMerge: options.contentOnly || options.executionMode === 'shortcut' ? false : true,
57
57
  ...(localMergeSource ? { localMerge: { sourceRef: localMergeSource, targetRef: 'refs/heads/main', status: 'pending' } } : {}),
58
- reviewEnabled: options.executionMode === 'shortcut' ? false : options.reviewEnabled ?? true,
59
- ...(options.executionMode === 'shortcut' ? { executionMode: 'shortcut', contentOnly: true } : {}),
58
+ reviewEnabled: options.contentOnly || options.executionMode === 'shortcut' ? false : options.reviewEnabled ?? true,
59
+ ...(options.contentOnly || options.executionMode === 'shortcut' ? { contentOnly: true } : {}),
60
60
  ...(options.reviewerThreadId
61
61
  ? { reviewerThreadId: normalizeThreadId(options.reviewerThreadId, 'reviewer thread ID') }
62
62
  : {}),
@@ -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';
@@ -32,20 +33,78 @@ export async function activateShortcutJobForDirectRun(store, jobId) {
32
33
  }
33
34
  export async function runShortcutJobCommand(args, id, makeRunner) {
34
35
  assertSqliteShortcutArgs(args);
35
- if (arg(args, '--mode') !== 'shortcut')
36
- throw new Error('job run requires --mode shortcut');
36
+ if (arg(args, '--mode') && arg(args, '--mode') !== 'shortcut')
37
+ throw new Error('job run no longer selects an execution mode');
37
38
  const loaded = await storeFor(args, false, true);
38
39
  if (loaded.localFile !== null || !loaded.store.mutateJob || !loaded.store.reserveWorkflowLaunch)
39
40
  throw new Error('Shortcut execution requires the authoritative SQLite Relay store');
40
41
  const job = loaded.job;
41
- if (job.executionMode !== 'shortcut' || job.contentOnly !== true)
42
- throw new Error('job run shortcut mode must be durably selected at Job creation with --shortcut-execution before Tasks are materialized');
42
+ // An explicit graph start is an ordinary Job activation. Historical in-flight
43
+ // direct Shortcut checkpoints alone continue through the archived runner below.
43
44
  const taskId = arg(args, '--task-id');
44
45
  if (!taskId)
45
46
  throw new Error('job run requires --task-id');
46
47
  let task = job.tasks.find(item => item.id === taskId);
47
48
  if (!task)
48
49
  throw new Error(`Task ${taskId} not found`);
50
+ const legacy = hasArg(args, '--legacy-shortcut-runtime') || Boolean(task.result?.data?.shortcut);
51
+ if (!legacy) {
52
+ if (hasArg(args, '--event-json'))
53
+ throw new Error('Normal Job activation does not accept a Shortcut runner event');
54
+ const graphOverride = hasArg(args, '--agent-graph-file') ? await textOption(args, '--agent-graph', '--agent-graph-file') : undefined;
55
+ if (graphOverride)
56
+ parseAgentGraph(graphOverride);
57
+ const effectiveGraph = task.agentGraph ?? graphOverride;
58
+ if (!effectiveGraph)
59
+ throw new Error('job run requires a Task with an Agent Graph');
60
+ const workspaceRoot = await resolveWorkspaceRoot(arg(args, '--workspace-root') || undefined);
61
+ const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : job.repository, arg(args, '--project-path') || job.projectPath || '', workspaceRoot);
62
+ const projectPath = resolveRepositoryProjectPath(projectRoot, job.projectPath);
63
+ const globalRoot = arg(args, '--global-root') || process.env.AGENTS_HOME || undefined;
64
+ const sharedRoot = arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined;
65
+ await loaded.store.mutateJob(id, current => {
66
+ const root = current.tasks.find(t => t.id === taskId);
67
+ if (!root)
68
+ throw Error('Graph Task disappeared');
69
+ if (root.agentGraph && root.agentGraph !== effectiveGraph)
70
+ throw Error('Graph Task changed since activation');
71
+ if (root.state !== 'QUEUED' && root.state !== 'RUNNING' && root.state !== 'DRAFT')
72
+ throw Error('Graph Task is not startable: ' + root.state);
73
+ if (!root.agentGraph) {
74
+ if (root.state !== 'QUEUED' && root.state !== 'DRAFT')
75
+ throw Error('Graph cannot be replaced after Task started');
76
+ root.agentGraph = effectiveGraph;
77
+ }
78
+ if (root.state === 'DRAFT') {
79
+ if (root.dependencies.length)
80
+ throw Error('Graph root has unmet dependencies');
81
+ const queued = tryTransitionTaskEvent(root, 'queue', { dependenciesSatisfied: true });
82
+ if (!queued.accepted || queued.target !== 'QUEUED')
83
+ throw Error('Task Lifecycle rejected Graph root queue');
84
+ }
85
+ const ctx = { projectPath, workspaceRoot, ...(sharedRoot ? { sharedRoot } : {}), ...(globalRoot ? { globalRoot } : {}), noGitHub: noGitHubMode(args) };
86
+ const existing = current.graphStartContext;
87
+ if (existing && ['projectPath', 'workspaceRoot', 'sharedRoot', 'globalRoot', 'noGitHub'].some(k => existing[k] !== ctx[k]))
88
+ throw Error('Graph start context changed from first authorized invocation');
89
+ if (!existing)
90
+ current.graphStartContext = ctx;
91
+ if (current.state === 'DRAFT') {
92
+ const decision = dispatchJobLifecycleSync(current, 'activate');
93
+ if (!decision.accepted || decision.target !== 'ACTIVE')
94
+ throw Error('Job Lifecycle rejected activation');
95
+ }
96
+ else if (current.state !== 'ACTIVE')
97
+ throw Error('Job is not runnable: ' + current.state);
98
+ return current;
99
+ });
100
+ const scheduled = await loaded.store.load(id);
101
+ await withEventBus(args, bus => publishWake(bus, scheduled, taskId, 'Graph Job activated; ordinary Scheduler owns execution'));
102
+ console.log(JSON.stringify({ jobId: id, taskId, scheduled: true, state: scheduled.state, graphRuntime: 'tasks',
103
+ message: 'Job activated; Relay Scheduler owns DAG Tasks, Reviews and recovery' }, null, 2));
104
+ return;
105
+ }
106
+ if (job.executionMode !== 'shortcut' || job.contentOnly !== true)
107
+ throw new Error('Legacy Shortcut runner requires its original archived Job policy');
49
108
  if (hasArg(args, '--event-json'))
50
109
  shortcutResumeEvent(arg(args, '--event-json'));
51
110
  if (!task.agentGraph && !hasArg(args, '--agent-graph-file'))
@@ -105,6 +164,37 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
105
164
  current.shortcutRunnerContext = ctx;
106
165
  return current;
107
166
  });
167
+ // Shortcut is an explicit activation point, not a separate Task engine.
168
+ // Previously launched, in-flight Shortcut checkpoints retain their legacy
169
+ // foreground owner; new Jobs use the ordinary Reconciler/DAG Task path.
170
+ const oldCheckpoint = task.result?.data?.shortcut;
171
+ const dagCheckpoint = task.result?.data?.dag;
172
+ const unified = dagCheckpoint?.version === 1 || (!hasArg(args, '--legacy-shortcut-runtime') && !oldCheckpoint && !job.shortcutExecutionStartedAt);
173
+ if (unified) {
174
+ if (!loaded.store.mutateJob)
175
+ throw Error('Unified DAG activation requires SQLite');
176
+ const hash = createHash('sha256').update(task.agentGraph).digest('hex');
177
+ await loaded.store.mutateJob(id, current => {
178
+ const root = current.tasks.find(t => t.id === taskId);
179
+ if (current.state !== 'ACTIVE' || !root || !root.agentGraph || root.agentGraph !== task.agentGraph)
180
+ throw Error('DAG activation Task identity changed');
181
+ if (root.state !== 'QUEUED' && root.state !== 'RUNNING')
182
+ throw Error('DAG Task cannot start from ' + root.state);
183
+ const prior = root.result?.data?.dag;
184
+ if (prior && (prior.version !== 1 || prior.graphHash !== hash))
185
+ throw Error('DAG runtime identity changed');
186
+ if (!prior)
187
+ root.result = { summary: 'DAG ready', data: { ...(root.result?.data ?? {}), dag: { version: 1, graphHash: hash } } };
188
+ if (!current.shortcutExecutionStartedAt)
189
+ current.shortcutExecutionStartedAt = new Date().toISOString();
190
+ return current;
191
+ });
192
+ const scheduled = await loaded.store.load(id);
193
+ await withEventBus(args, bus => publishWake(bus, scheduled, taskId, 'Shortcut DAG activation (normal Task scheduler)'));
194
+ console.log(JSON.stringify({ jobId: id, taskId, mode: 'shortcut', scheduled: true, state: scheduled.state,
195
+ graphRuntime: 'tasks', message: 'Task scheduling and Review are owned by the ordinary Relay Reconciler' }, null, 2));
196
+ return;
197
+ }
108
198
  const missing = await missingShortcutNodes(task.agentGraph, projectPath, sharedRoot, workspaceRoot, globalRoot);
109
199
  const previous = task.result?.data?.shortcut;
110
200
  if (previous?.workerFallback === true)
package/dist/cli.js CHANGED
@@ -62,7 +62,7 @@ async function runManagedTaskCommand(action, args) {
62
62
  throw new Error(`task ${action} requires --task-id`);
63
63
  let result;
64
64
  if (action === 'create') {
65
- if (hasArg(args, '--shortcut-execution') && hasArg(args, '--initial-plan'))
65
+ if ((hasArg(args, '--shortcut-execution') || hasArg(args, '--content-only')) && hasArg(args, '--initial-plan'))
66
66
  throw new Error('--shortcut-execution currently requires create-only job creation; materialize Graph Tasks after the durable shortcut policy is stored');
67
67
  const job = await relayControlJob(args, jobId);
68
68
  if (['COMPLETED', 'CANCELLED'].includes(job.state))
@@ -402,8 +402,8 @@ async function runJobCommand(action, args) {
402
402
  optionalLegacyPr(args);
403
403
  let createObjective;
404
404
  if (action === 'create') {
405
- if (hasArg(args, '--no-auto-merge'))
406
- throw new Error('job create does not accept --no-auto-merge; new Jobs always enable auto-merge');
405
+ if (hasArg(args, '--no-auto-merge') && !hasArg(args, '--content-only'))
406
+ throw new Error('Use --content-only for an explicit no-merge content Job');
407
407
  const taskOnlyFlags = ['--start', '--task-id', '--input', '--input-file', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path', '--draft', '--queue'];
408
408
  const invalid = taskOnlyFlags.find(flag => hasArg(args, flag));
409
409
  if (invalid)
@@ -433,7 +433,7 @@ async function runJobCommand(action, args) {
433
433
  return;
434
434
  }
435
435
  if (action === 'create') {
436
- if (hasArg(args, '--shortcut-execution') && hasArg(args, '--initial-plan'))
436
+ if ((hasArg(args, '--shortcut-execution') || hasArg(args, '--content-only')) && hasArg(args, '--initial-plan'))
437
437
  throw new Error('--shortcut-execution requires create-only Job creation; materialize Agent Graph Tasks only after durable shortcut policy is stored');
438
438
  rejectRemovedJobOptions(args);
439
439
  const objective = createObjective ?? '';
@@ -442,7 +442,7 @@ async function runJobCommand(action, args) {
442
442
  const result = await relayControlCommand(args, { command: 'job.create', repository: repo, initialPlan: hasArg(args, '--initial-plan'), options: {
443
443
  id: id || undefined, idempotencyKey: arg(args, '--idempotency-key') || undefined, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
444
444
  priority: priority(args), tag: jobTagFromArgs(args), reviewEnabled: !hasArg(args, '--no-review'), continuation: continuation(args),
445
- executionMode: hasArg(args, '--shortcut-execution') ? 'shortcut' : undefined,
445
+ contentOnly: hasArg(args, '--content-only') || hasArg(args, '--shortcut-execution'),
446
446
  reviewerThreadId: hasArg(args, '--reviewer-thread-id') ? arg(args, '--reviewer-thread-id') : undefined, creatorThreadId: hasArg(args, '--creator-thread-id') ? arg(args, '--creator-thread-id') : undefined, implementationThreadId: hasArg(args, '--implementation-thread-id') ? arg(args, '--implementation-thread-id') : undefined,
447
447
  } });
448
448
  console.log(JSON.stringify(result, null, 2));
@@ -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
+ }