agents-relay 2.0.255 → 2.0.257

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.
Files changed (39) hide show
  1. package/README.md +26 -13
  2. package/dist/agent-script-discovery.js +56 -0
  3. package/dist/cli-coordinator.js +71 -0
  4. package/dist/cli-help.js +36 -30
  5. package/dist/cli-job-create.js +37 -4
  6. package/dist/cli.js +21 -12
  7. package/dist/dag-result-contract.js +2 -2
  8. package/dist/{shortcut-stage-contract.js → dag-stage-contract.js} +1 -1
  9. package/dist/dag-task-runtime.js +4 -33
  10. package/dist/dashboard-jel.js +8 -12
  11. package/dist/job-execution-slot.js +3 -11
  12. package/dist/pool.js +28 -15
  13. package/dist/reconciler.js +5 -28
  14. package/dist/relay-job-snapshot-reads.js +2 -5
  15. package/dist/relay-workflow-operations.js +2 -3
  16. package/dist/relayd-control.js +5 -0
  17. package/dist/relayd.js +1 -3
  18. package/dist/runtime-status.js +0 -33
  19. package/dist/script-task-adapter.js +2 -2
  20. package/dist/task-inactivity-watchdog.js +3 -6
  21. package/dist/worker-failure-recovery.js +1 -1
  22. package/dist/workflow/action-ledger.js +1 -1
  23. package/dist/workflow/contracts.js +0 -28
  24. package/dist/workflow/definitions-v2.js +1 -8
  25. package/dist/workflow/runtime.js +0 -9
  26. package/package.json +6 -6
  27. package/skills/agents-relay/SKILL.md +41 -14
  28. package/skills/agents-relay/contracts/event-contract.md +4 -5
  29. package/skills/agents-relay/contracts/task-job-contract.md +35 -1
  30. package/workflow/job-lifecycle.mmd +0 -8
  31. package/workflow/task-lifecycle.mmd +1 -26
  32. package/dist/agent-shortcut.js +0 -587
  33. package/dist/cli-shortcut-local.js +0 -50
  34. package/dist/cli-shortcut.js +0 -267
  35. package/dist/reconciler-shortcut.js +0 -74
  36. package/dist/shortcut-node-revision.js +0 -21
  37. package/dist/shortcut-node-worker.js +0 -144
  38. package/dist/shortcut-review-wake.js +0 -64
  39. 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
- Agents Relay manages durable Jobs and Tasks. Use its CLI for Job/Task state and actions; do not read its private storage, GitHub projections, or internal service APIs. Prefer completing simple, non-delegated work directly without Relay.
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. Record the standalone objective, constraints, acceptance checks, and deliverables before Job creation.
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 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`.
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,13 +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
- 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. `job run --id JOB --task-id TASK` activates any create-only Graph Job and
49
- hands it to that same Reconciler; it is not a separate DAG scheduler or Job
50
- execution mode. Final Review is independently controlled by `--review`/`--no-review`;
51
- normal Git Merge is independently controlled by `--auto-merge`/`--no-auto-merge`. A Graph needs no Planner unless one is requested.
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.
52
81
 
53
82
  ## 3. Verify, review, and recover
54
83
 
@@ -82,9 +111,7 @@ Markcut). The reviewed Task enters `AWAITING_DECISION`. An inbox/compile receipt
82
111
  is **not approval**. An accepted Approve resumes the same Agent Task; Request
83
112
  Changes resumes the same Task with feedback (a scripted Task can switch to its
84
113
  Model executor for semantic revision, then return to Script for validation).
85
- One execution ID identifies at most one review. Preview does **not** create Git
86
- commits, snapshots or independent reviewer Tasks. Legacy in-flight Shortcut
87
- 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`.
88
115
 
89
116
  ## 5. Manage services when needed
90
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
- 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
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. Legacy running Shortcut checkpoints
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 Git-versioned Neo Project Interactive Previews, bind a verified full 40-character Git Commit SHA as the sole review revision (`data.interactive.commitSha`, and `data.interactive.revision` must equal it). Compiled media cache hashes, legacy Markcut `revisionId` and `contentHash` must not be used as the Event Review identity. The Producer creates the Stage Commit before requesting Preview; Relay continues to own the decision and Task lifecycle. Generic non-video interactions are not made into Git commits by this contract.
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| shortcutExecution
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