agents-relay 2.0.251 → 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 +12 -9
- package/dist/agent-shortcut.js +2 -2
- package/dist/cli-help.js +4 -7
- package/dist/cli-review.js +29 -12
- package/dist/cli-shortcut.js +32 -0
- package/dist/dag-result-contract.js +48 -0
- package/dist/dag-task-runtime.js +214 -0
- package/dist/interactive-invocation.js +15 -24
- package/dist/interactive-request.js +11 -34
- package/dist/job-execution-slot.js +27 -21
- package/dist/pool.js +6 -3
- package/dist/reconciler-runtime.js +13 -5
- package/dist/reconciler.js +20 -21
- package/dist/relayd-control.js +5 -10
- package/dist/script-task-adapter.js +118 -0
- package/dist/shortcut-node-worker.js +1 -1
- package/dist/shortcut-review-wake.js +1 -1
- package/dist/workflow/contracts.js +1 -0
- package/dist/workflow/definitions-v2.js +2 -1
- package/package.json +4 -4
- package/skills/agents-relay/SKILL.md +36 -26
- package/skills/agents-relay/contracts/event-contract.md +17 -15
- package/workflow/job-lifecycle.mmd +4 -0
|
@@ -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
|
|
16
|
+
Use Relay for durable multi-Task work. Record the standalone objective, constraints, acceptance checks, and deliverables before Job creation.
|
|
17
17
|
|
|
18
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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`
|
|
58
|
-
`AGENTS_RELAY_ESCALATION_COMMAND`
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|