agents-relay 2.0.256 → 2.0.258
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 +26 -13
- package/dist/agent-script-discovery.js +56 -0
- package/dist/cli-coordinator.js +71 -0
- package/dist/cli-help.js +36 -30
- package/dist/cli-job-create.js +37 -4
- package/dist/cli.js +21 -12
- package/dist/dag-result-contract.js +2 -2
- package/dist/{shortcut-stage-contract.js → dag-stage-contract.js} +1 -1
- package/dist/dag-task-runtime.js +4 -33
- package/dist/dashboard-jel.js +8 -12
- package/dist/job-execution-slot.js +3 -11
- package/dist/pool.js +2 -13
- package/dist/reconciler-runtime.js +4 -1
- package/dist/reconciler.js +12 -29
- package/dist/relay-job-snapshot-reads.js +2 -5
- package/dist/relay-workflow-operations.js +2 -3
- package/dist/relayd-control.js +5 -0
- package/dist/relayd.js +1 -3
- package/dist/runtime-status.js +0 -33
- package/dist/script-task-adapter.js +2 -2
- package/dist/task-inactivity-watchdog.js +3 -6
- package/dist/worker-failure-recovery.js +1 -1
- package/dist/workflow/action-ledger.js +1 -1
- package/dist/workflow/contracts.js +0 -28
- package/dist/workflow/definitions-v2.js +1 -8
- package/dist/workflow/runtime.js +0 -9
- package/package.json +6 -6
- package/skills/agents-relay/SKILL.md +41 -20
- package/skills/agents-relay/contracts/event-contract.md +4 -5
- package/skills/agents-relay/contracts/task-job-contract.md +35 -1
- package/workflow/job-lifecycle.mmd +0 -8
- package/workflow/task-lifecycle.mmd +1 -26
- package/dist/agent-shortcut.js +0 -587
- package/dist/cli-shortcut-local.js +0 -50
- package/dist/cli-shortcut.js +0 -267
- package/dist/reconciler-shortcut.js +0 -74
- package/dist/shortcut-node-revision.js +0 -21
- package/dist/shortcut-node-worker.js +0 -144
- package/dist/shortcut-review-wake.js +0 -64
- package/dist/shortcut-worker-runner.js +0 -64
|
@@ -5,15 +5,15 @@ description: Use Agents Relay for durable multi-step or multi-agent work that ne
|
|
|
5
5
|
|
|
6
6
|
# Agents Relay
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Relay owns durable Jobs and Tasks. Use its CLI—not private storage or GitHub projections. Handle one-shot work directly.
|
|
9
9
|
|
|
10
10
|
## Job Execution Lifecycle (JEL)
|
|
11
11
|
|
|
12
|
-
Explain **JEL** to the user: **Create → Plan → Execute → Final Review → Merge → Completed**. After work/recovery Tasks terminate (SUCCEEDED/FAILED/CANCELLED), Final Review judges completion: PASS merges; CHANGES_REQUIRED persists findings, starts Planner N+1 for minimal fixes, then re-reviews. No automatic post-success Plan. Planner/Workers use discovered **ponytail** Skill (YAGNI, reuse, minimal Tasks); preserve mandatory safeguards.
|
|
12
|
+
Explain **JEL** to the user: **Create → [optional Plan] → Execute → Final Review → Merge → Completed**. A Coordinator Agent Graph does not need an initial Planner; otherwise the same Task/Review/Merge lifecycle applies. After work/recovery Tasks terminate (SUCCEEDED/FAILED/CANCELLED), Final Review judges completion: PASS merges; CHANGES_REQUIRED persists findings, starts Planner N+1 for minimal fixes, then re-reviews. No automatic post-success Plan. Planner/Workers use discovered **ponytail** Skill (YAGNI, reuse, minimal Tasks); preserve mandatory safeguards.
|
|
13
13
|
|
|
14
14
|
## 1. Choose and start a Job
|
|
15
15
|
|
|
16
|
-
Use Relay for durable multi-Task work
|
|
16
|
+
Use Relay for durable multi-Task work with explicit objectives and acceptance criteria.
|
|
17
17
|
|
|
18
18
|
Consult CLI help; examples:
|
|
19
19
|
|
|
@@ -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
|
|
26
|
+
Use returned Job IDs. Omit `--initial-plan` for DRAFT-only or Coordinator Graph 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
|
|
|
@@ -42,19 +42,42 @@ node <matching-absolute-dist/cli.js> plan context --id JOB --plan-id PLAN --exec
|
|
|
42
42
|
|
|
43
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
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
Task
|
|
49
|
-
|
|
50
|
-
execution
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
45
|
+
### Plan-free Coordinator / DAG execution
|
|
46
|
+
|
|
47
|
+
`agentGraph` is a declarative dependency DAG. Relay persists one Coordinator
|
|
48
|
+
Task and one independent **Agent Task for each node as its dependencies become
|
|
49
|
+
ready**. The Coordinator owns the Graph but does not lease a Worker or use a
|
|
50
|
+
second execution state machine. Script and Model nodes have identical durable
|
|
51
|
+
Task lifecycle, retry, recovery, human review and terminal event semantics.
|
|
52
|
+
An Agent terminal event **immediately** reconciles and dispatches ready
|
|
53
|
+
successors when capacity allows. Otherwise QUEUED retains recovery and fair
|
|
54
|
+
admission. Branches can run concurrently; fan-ins await dependencies.
|
|
55
|
+
|
|
56
|
+
To create a plan-free Coordinator Job, include its Graph and execution paths
|
|
57
|
+
**in the original Job creation**, atomically with the durable Job. For example:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
npx agents-relay job create --repo OWNER/REPO --title "Episode" \
|
|
61
|
+
--objective-file job.md \
|
|
62
|
+
--coordinator-graph-file /absolute/project/graph.mmd \
|
|
63
|
+
--coordinator-input-file /absolute/run/neo-project-run.input.md \
|
|
64
|
+
--coordinator-output-path /absolute/run/neo-project-run.result.json \
|
|
65
|
+
--coordinator-project-root /absolute/project \
|
|
66
|
+
--coordinator-workspace-root /absolute/workspace \
|
|
67
|
+
--coordinator-shared-root /absolute/shared
|
|
68
|
+
npx agents-relay job run --id JOB_ID --task-id coordinator \
|
|
69
|
+
--project-path /absolute/project --workspace-root /absolute/workspace \
|
|
70
|
+
--shared-root /absolute/shared
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Creation atomically persists **DRAFT Job + Coordinator Task**. Activation
|
|
74
|
+
returns a scheduled receipt, not completion. Neo's `neo project run` wraps this
|
|
75
|
+
creation/binding/activation sequence and resumes an existing Run without
|
|
76
|
+
creating a second Job. Do not use legacy `--shortcut-execution`, `--mode
|
|
77
|
+
shortcut`, `--shortcut-local`, `--legacy-shortcut-runtime` or receipts.
|
|
78
|
+
Final Review (`--review`/`--no-review`) and local Git Merge
|
|
79
|
+
(`--auto-merge`/`--no-auto-merge`) are independent ordinary Job policies;
|
|
80
|
+
there is no automatic Plan or special content-only completion mode.
|
|
58
81
|
|
|
59
82
|
## 3. Verify, review, and recover
|
|
60
83
|
|
|
@@ -88,9 +111,7 @@ Markcut). The reviewed Task enters `AWAITING_DECISION`. An inbox/compile receipt
|
|
|
88
111
|
is **not approval**. An accepted Approve resumes the same Agent Task; Request
|
|
89
112
|
Changes resumes the same Task with feedback (a scripted Task can switch to its
|
|
90
113
|
Model executor for semantic revision, then return to Script for validation).
|
|
91
|
-
One execution ID identifies at most one review. Preview does **not** create Git
|
|
92
|
-
commits, snapshots or independent reviewer Tasks. Legacy in-flight Shortcut
|
|
93
|
-
checkpoints remain compatible. See `contracts/event-contract.md`.
|
|
114
|
+
One execution ID identifies at most one review. Preview does **not** create Git commits, snapshots or independent reviewer Tasks. Review feedback and decisions live in Relay's durable Task history, not a synthetic Git revision. See `contracts/event-contract.md`.
|
|
94
115
|
|
|
95
116
|
## 5. Manage services when needed
|
|
96
117
|
|
|
@@ -55,12 +55,11 @@ waiting/terminal event on behalf of its host. An inbox acknowledgement is not
|
|
|
55
55
|
approval. No Git commit, content snapshot or SHA is required for human Review.
|
|
56
56
|
|
|
57
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
|
-
|
|
60
|
-
|
|
58
|
+
belongs to the corresponding Agent child, not the Coordinator. The ordinary Reconciler schedules their retries and revisions and
|
|
59
|
+
immediately dispatches dependency-ready successors after terminal events
|
|
60
|
+
when capacity is available. A Script Task on `changes_requested` may use its own Agent Model
|
|
61
61
|
executor in a **new execution of that same Task**; after a fresh approval,
|
|
62
|
-
Script verifies the revised artifacts.
|
|
63
|
-
retain the earlier foreground-runner resume behavior until completion.
|
|
62
|
+
Script verifies the revised artifacts. No direct Shortcut Runner or special execution-mode receipt path remains.
|
|
64
63
|
|
|
65
64
|
The Job stays ACTIVE; the Task does not requeue until a matching
|
|
66
65
|
`task.interactive_decision` is durably accepted and the Task Graph selects
|
|
@@ -42,6 +42,30 @@ Each dependency edge may also declare `dependencyValidity`: `order-only` (the de
|
|
|
42
42
|
|
|
43
43
|
A later Planner round must inspect the existing semantic tree and attach review, revision, re-review, validation rerun, release correction, or recovery work to the existing artifact subtree. Independent milestones remain roots. `plan-N` records are provenance/history and must never be semantic parents. Existing terminal Tasks remain immutable historical evidence and may continue to own later work.
|
|
44
44
|
|
|
45
|
+
### Declarative Agent DAG and Coordinator ownership
|
|
46
|
+
|
|
47
|
+
For an executable `agentGraph`, create the Job and its Coordinator Task
|
|
48
|
+
atomically through `job create --coordinator-graph-file ...` (with input,
|
|
49
|
+
output, project/workspace paths); activate it with
|
|
50
|
+
`job run --id JOB --task-id coordinator`. This is an alternative to an
|
|
51
|
+
initial Planner, **not** a separate Job mode or nested runner.
|
|
52
|
+
|
|
53
|
+
The Coordinator stays durable and does not consume a Worker lease. Each graph
|
|
54
|
+
node materializes as an independently durable Agent Task, with its own
|
|
55
|
+
`parentTaskId`, dependency edges, execution identity, standard retry and
|
|
56
|
+
human review. Its Script or Model executor follows the same Task lifecycle.
|
|
57
|
+
On accepted terminal completion the local Job Reconciler immediately
|
|
58
|
+
considers newly ready dependent nodes, launching independent branches in
|
|
59
|
+
parallel when global capacity permits. `QUEUED` is a persisted recovery and
|
|
60
|
+
capacity boundary, not a reason to wait for the next global scan.
|
|
61
|
+
|
|
62
|
+
`Request Changes` on an Agent's human Preview requeues the **same Agent Task**
|
|
63
|
+
with feedback, not a fresh revision Task. The Task's new execution can use a
|
|
64
|
+
Model executor for edits and return to Script for validation. A Task cannot
|
|
65
|
+
claim success from a preview-delivery acknowledgement or a process exit.
|
|
66
|
+
The normal Job Final Review and Git Merge are unchanged by Coordinator
|
|
67
|
+
creation and run independently of whether a Planner was needed initially.
|
|
68
|
+
|
|
45
69
|
### Task input vs result
|
|
46
70
|
|
|
47
71
|
A Task input records **what is known and what has already been decided before execution**. A Task result records **what execution discovered and what was actually done**.
|
|
@@ -165,7 +189,17 @@ A newly created zero-task DRAFT Job waits for explicit initial planning (`plan`
|
|
|
165
189
|
|
|
166
190
|
## Task evidence and head identity
|
|
167
191
|
|
|
168
|
-
For
|
|
192
|
+
For a **Job Final Review of committed source**, the existing immutable
|
|
193
|
+
`head_sha` identifies the code target. Do **not** apply that requirement to
|
|
194
|
+
**Agent Task interactive Preview**: `review.preview` uses the current
|
|
195
|
+
`jobId`/`taskId`/`executionId` and the durable Relay decision associated
|
|
196
|
+
with that Task. The task stops awaiting its human decision; a new revision
|
|
197
|
+
may be requested by resuming the same Task with feedback. No Git SHA,
|
|
198
|
+
content snapshot, additional revision Task or automatic Git commit is a
|
|
199
|
+
prerequisite. Git source/version history and the Task's human review event
|
|
200
|
+
history answer different questions. If an Agent chooses to commit a verified
|
|
201
|
+
artifact separately, use a meaningful descriptive Git message; do not use
|
|
202
|
+
review delivery itself to create commits or tags.
|
|
169
203
|
|
|
170
204
|
### Canonical Neo Project runs boundary
|
|
171
205
|
|
|
@@ -13,8 +13,6 @@ cancelDraft["action: effect.cancelActiveTasks"]
|
|
|
13
13
|
cancelActive["action: effect.cancelActiveTasks"]
|
|
14
14
|
localCompletionGuard["guard: localCompletionAllowed"]
|
|
15
15
|
localMergeReadyGuard["guard: localMergeReady"]
|
|
16
|
-
shortcutCompletionGuard["guard: shortcutCompletionAllowed"]
|
|
17
|
-
contentCompletionGuard["guard: contentCompletionAllowed"]
|
|
18
16
|
localMergeDelivery["action: effect.deliverLocalMerge"]
|
|
19
17
|
|
|
20
18
|
draft -->|on: activate| active
|
|
@@ -30,12 +28,6 @@ cancelActive --> cancelled
|
|
|
30
28
|
active -->|on: local.completed| localCompletionGuard
|
|
31
29
|
localCompletionGuard -->|true| completed
|
|
32
30
|
localCompletionGuard -->|false| active
|
|
33
|
-
active -->|on: content.completed| contentCompletionGuard
|
|
34
|
-
contentCompletionGuard -->|true| completed
|
|
35
|
-
contentCompletionGuard -->|false| active
|
|
36
|
-
active -->|on: shortcut.completed| shortcutCompletionGuard
|
|
37
|
-
shortcutCompletionGuard -->|true| completed
|
|
38
|
-
shortcutCompletionGuard -->|false| active
|
|
39
31
|
|
|
40
32
|
active -->|on: local.merge.requested| localMergeReadyGuard
|
|
41
33
|
localMergeReadyGuard -->|true| localMergeDelivery
|
|
@@ -24,9 +24,6 @@ depSat["guard: dependenciesSatisfied"]
|
|
|
24
24
|
depUnsat["guard: dependenciesUnsatisfied"]
|
|
25
25
|
runnable["guard: runnable"]
|
|
26
26
|
dispatchable["guard: dispatchable"]
|
|
27
|
-
shortcutExecution["guard: shortcutExecution"]
|
|
28
|
-
shortcutHasGraph["guard: shortcutHasGraph"]
|
|
29
|
-
shortcutDirectInvocation["guard: shortcutDirectInvocation"]
|
|
30
27
|
recoverStart["guard: recoverableExecution"]
|
|
31
28
|
recoverComplete["guard: recoverableExecution"]
|
|
32
29
|
recoverBlocked["guard: recoverableExecution"]
|
|
@@ -37,7 +34,6 @@ recoveryReopenClearError["action: mutation.clearError"]
|
|
|
37
34
|
recoveryReopenClearReason["action: mutation.clearFailureReason"]
|
|
38
35
|
recoveryReopenClearLease["action: mutation.clearLease"]
|
|
39
36
|
recoveryReopenClearExecution["action: mutation.clearExecution"]
|
|
40
|
-
shortcutRecoveryRequired["action: mutation.markShortcutRecoveryRequired"]
|
|
41
37
|
|
|
42
38
|
plannerRetryAvailable["guard: retryAvailable"]
|
|
43
39
|
platformFallbackSafe["guard: platformFallbackSafe"]
|
|
@@ -67,9 +63,6 @@ reconcileDraftClearReason["action: mutation.clearFailureReason"]
|
|
|
67
63
|
reconcileQueuedClearError["action: mutation.clearError"]
|
|
68
64
|
reconcileQueuedClearReason["action: mutation.clearFailureReason"]
|
|
69
65
|
dispatchLaunch["action: effect.launchTask"]
|
|
70
|
-
shortcutLaunch["action: effect.launchShortcut"]
|
|
71
|
-
shortcutResultCorrelated["guard: shortcutResultCorrelated"]
|
|
72
|
-
shortcutResume["action: effect.resumeShortcut"]
|
|
73
66
|
startClearError["action: mutation.clearError"]
|
|
74
67
|
startClearReason["action: mutation.clearFailureReason"]
|
|
75
68
|
reviewStartClearError["action: mutation.clearError"]
|
|
@@ -113,16 +106,9 @@ queued -->|on: reconcile| runnable
|
|
|
113
106
|
runnable -->|true| reconcileQueuedClearError
|
|
114
107
|
reconcileQueuedClearError --> reconcileQueuedClearReason
|
|
115
108
|
reconcileQueuedClearReason --> queued
|
|
116
|
-
queued -->|on: dispatch|
|
|
117
|
-
shortcutExecution -->|true| shortcutHasGraph
|
|
118
|
-
shortcutExecution -->|false| dispatchable
|
|
119
|
-
shortcutHasGraph -->|true| shortcutDirectInvocation
|
|
120
|
-
shortcutDirectInvocation -->|true| shortcutLaunch
|
|
121
|
-
shortcutDirectInvocation -->|false| queued
|
|
122
|
-
shortcutHasGraph -->|false| queued
|
|
109
|
+
queued -->|on: dispatch| dispatchable
|
|
123
110
|
dispatchable -->|true| dispatchLaunch
|
|
124
111
|
dispatchLaunch --> queued
|
|
125
|
-
shortcutLaunch --> queued
|
|
126
112
|
queued -->|on: task.started| startClearError
|
|
127
113
|
startClearError --> startClearReason
|
|
128
114
|
startClearReason --> running
|
|
@@ -143,7 +129,6 @@ queuedBlockAllowed -->|true| blocked
|
|
|
143
129
|
queuedBlockAllowed -->|false| failed
|
|
144
130
|
queued -->|on: fail| failed
|
|
145
131
|
queued -->|on: effect.launchTask.failed| failed
|
|
146
|
-
queued -->|on: effect.launchShortcut.failed| failed
|
|
147
132
|
queued -->|on: watchdog.failed| failed
|
|
148
133
|
queued -->|on: worker.delivery_failed| failed
|
|
149
134
|
queued -->|on: worker.start_ack_failed| failed
|
|
@@ -181,14 +166,6 @@ running -->|on: task.blocked| runningBlockAllowed
|
|
|
181
166
|
runningBlockAllowed -->|true| blocked
|
|
182
167
|
runningBlockAllowed -->|false| failed
|
|
183
168
|
running -->|on: task.progress| running
|
|
184
|
-
running -->|on: shortcut.waiting| shortcutWaitReleaseLease
|
|
185
|
-
shortcutWaitReleaseLease["action: mutation.clearLease"]
|
|
186
|
-
shortcutWaitReleaseLease --> running
|
|
187
|
-
running -->|on: shortcut.result| shortcutResultCorrelated
|
|
188
|
-
shortcutResultCorrelated -->|true| shortcutResume
|
|
189
|
-
shortcutResultCorrelated -->|false| running
|
|
190
|
-
shortcutResume --> running
|
|
191
|
-
running -->|on: effect.resumeShortcut.failed| failed
|
|
192
169
|
running -->|on: review.approved| reviewApproveRunningClearError
|
|
193
170
|
reviewApproveRunningClearError --> reviewApproveRunningClearReason
|
|
194
171
|
reviewApproveRunningClearReason --> succeeded
|
|
@@ -200,8 +177,6 @@ running -->|on: task.completed| completeClearError
|
|
|
200
177
|
completeClearError --> completeClearReason
|
|
201
178
|
completeClearReason --> succeeded
|
|
202
179
|
running -->|on: task.failed| failed
|
|
203
|
-
running -->|on: shortcut.failed| shortcutRecoveryRequired
|
|
204
|
-
shortcutRecoveryRequired --> failed
|
|
205
180
|
running -->|on: worker.platform_failure| runningPlatformFailureQuarantine
|
|
206
181
|
runningPlatformFailureQuarantine["action: mutation.quarantinePlatformFailure"]
|
|
207
182
|
runningPlatformFailureQuarantine --> failed
|