agents-relay 2.0.263 → 2.0.264
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 +57 -52
- package/bin/migrate-task-ids.mjs +12 -0
- package/dist/blocker-recovery.js +9 -16
- package/dist/cli-blocker.js +2 -1
- package/dist/cli-coordinator.js +19 -7
- package/dist/cli-foreground.js +82 -0
- package/dist/cli-help.js +61 -72
- package/dist/cli-job-create.js +15 -9
- package/dist/cli-prompt.js +9 -5
- package/dist/cli-support.js +21 -8
- package/dist/cli-worker-task.js +9 -3
- package/dist/cli.js +50 -36
- package/dist/dag-task-runtime.js +16 -12
- package/dist/dashboard-html.js +28 -14
- package/dist/dashboard-jel.js +87 -31
- package/dist/dashboard-style.js +2 -8
- package/dist/dependency-revision-execution.js +15 -6
- package/dist/final-review-role.js +0 -12
- package/dist/job-local-repository-migration.js +137 -0
- package/dist/job-pr-number-migration.js +0 -4
- package/dist/job-task-id-sequence.js +18 -9
- package/dist/job-worktree-cleanup.js +3 -3
- package/dist/local-job-registry.js +2 -2
- package/dist/local-managed-store.js +2 -2
- package/dist/local-merge-delivery.js +16 -3
- package/dist/local-merge-projection.js +192 -49
- package/dist/no-github.js +2 -1
- package/dist/planner-recovery.js +8 -3
- package/dist/planner.js +5 -5
- package/dist/pool.js +3 -3
- package/dist/projection-failure-recovery.js +6 -46
- package/dist/reconciler-context.js +5 -5
- package/dist/reconciler-review.js +12 -37
- package/dist/reconciler-runtime.js +1 -4
- package/dist/reconciler.js +5 -5
- package/dist/relay-job-merge.js +33 -0
- package/dist/relay-store.js +8 -30
- package/dist/relay-workflow-operations.js +2 -0
- package/dist/relayd-control.js +22 -25
- package/dist/relayd-dashboard-actions.js +4 -5
- package/dist/relayd-utilities.js +15 -20
- package/dist/relayd.js +59 -299
- package/dist/review-generation-fence.js +1 -1
- package/dist/review-replan.js +6 -1
- package/dist/review-revision-model.js +11 -6
- package/dist/task-context.js +1 -1
- package/dist/task-id-migration.js +229 -0
- package/dist/task-transitions.js +1 -1
- package/dist/troubleshooter.js +13 -16
- package/dist/unified-job-registry.js +9 -0
- package/dist/workflow/projection-conflict-v2.js +30 -26
- package/dist/workflow/task-related-action-v2.js +1 -2
- package/dist/workspace.js +52 -56
- package/package.json +4 -2
- package/skills/agents-relay/SKILL.md +35 -60
- package/skills/agents-relay/agents/planner.agent.md +5 -5
- package/skills/agents-relay/bin/services.mjs +21 -3
- package/skills/agents-relay/contracts/task-job-contract.md +11 -2
- package/skills/agents-relay/evals/capabilities.json +6 -1
- package/workflow/projection-conflict.mmd +59 -56
- package/workflow/projection-outbox-conflict.mmd +20 -0
- package/dist/cli-projection.js +0 -29
- package/dist/projection-recovery-runtime.js +0 -121
- package/dist/projection-recovery.js +0 -101
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agents-relay",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.264",
|
|
4
4
|
"description": "Durable async agent jobs coordinated through GitHub pull requests",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"type": "module",
|
|
10
10
|
"bin": {
|
|
11
11
|
"agents-relay": "dist/cli.js",
|
|
12
|
+
"agents-relay-migrate-task-ids": "bin/migrate-task-ids.mjs",
|
|
12
13
|
"agents-relayd": "dist/relayd-main.js"
|
|
13
14
|
},
|
|
14
15
|
"scripts": {
|
|
@@ -26,7 +27,7 @@
|
|
|
26
27
|
"test:verification:l4": "node test/verification/l4/run-all.mjs",
|
|
27
28
|
"test:skill:luna": "node skills/agents-relay/evals/run-codex.mjs --model gpt-6-luna",
|
|
28
29
|
"test:verification:l4:live": "npm run build && node test/verification/l4/live-bootstrap.mjs",
|
|
29
|
-
"test:verification:l3": "npm run build && node --test --test-concurrency=1 test/verification/harness.test.mjs test/local-sqlite-jobid.test.js test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/l3-planner-cli.test.mjs test/verification/l3-task-resolution.test.mjs test/verification/l3-plan-apply-convergence.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-
|
|
30
|
+
"test:verification:l3": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/harness.test.mjs test/local-sqlite-jobid.test.js test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/l3-planner-cli.test.mjs test/verification/l3-task-resolution.test.mjs test/verification/l3-plan-apply-convergence.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-daemon-startup-recovery.test.mjs test/verification/l3-coordinator-review.test.mjs test/verification/l3-optional-remote-delivery.test.mjs test/verification/l3-local-git-cli-contract.test.mjs test/local-merge-projection.test.js",
|
|
30
31
|
"test:verification": "npm run test:verification:l1 && npm run test:verification:l2 && npm run test:verification:l3 && npm run test:verification:cross-a && node --test test/workflow-production-outbox.test.js && npm run test:verification:matrix",
|
|
31
32
|
"test:verification:cross-a": "npm run build && RELAY_A_DIST=$PWD/dist node --test test/verification/action-ledger-cross-branch.test.mjs test/verification/outbox-cross-a.test.mjs",
|
|
32
33
|
"test:verification:matrix": "node test/verification/recovery-report.mjs /tmp/agents-relay-job481-evidence",
|
|
@@ -47,6 +48,7 @@
|
|
|
47
48
|
},
|
|
48
49
|
"files": [
|
|
49
50
|
"dist",
|
|
51
|
+
"bin",
|
|
50
52
|
"agents",
|
|
51
53
|
"skills",
|
|
52
54
|
"workflow",
|
|
@@ -5,11 +5,19 @@ description: Use Agents Relay for durable multi-step or multi-agent work that ne
|
|
|
5
5
|
|
|
6
6
|
# Agents Relay
|
|
7
7
|
|
|
8
|
-
Relay owns durable Jobs and Tasks.
|
|
8
|
+
Relay owns durable Jobs and Tasks; do one-shot work directly. On Neo Master, **use the published npm package**, not the local developer checkout. The default CLI is `npx --yes --package agents-relay@latest agents-relay`; the daemon is `npx --yes --package agents-relay@latest agents-relayd`. Never use a stale globally installed `agents-relay` binary or local `dist/cli.js` for live Jobs.
|
|
9
|
+
|
|
10
|
+
## Capability tree
|
|
11
|
+
|
|
12
|
+
- Create/inspect: Job ID, SQLite state, and immutable `job.projectRoot` (canonical independent Git root); `repository` is its basename, never `owner/repo`.
|
|
13
|
+
- Execute: normal Planner or plan-free Coordinator DAG; use the same published CLI version as daemon.
|
|
14
|
+
- Review/merge: local Git head and normal Job gate; `COMPLETED` requires no network or PR.
|
|
15
|
+
- Deliver: optional verified non-force origin/main push after completion; never changes Job state.
|
|
16
|
+
- Daemon: no Workspace scan and no `--workspace` requirement. Neo's `package.published` watcher restarts package-backed PM2 services after npm `latest` is confirmed.
|
|
9
17
|
|
|
10
18
|
## Job Execution Lifecycle (JEL)
|
|
11
19
|
|
|
12
|
-
|
|
20
|
+
**JEL:** Create → [Plan] → Execute → Final Review → local Merge → Completed. Plan-free Coordinator uses the same lifecycle. PASS merges; CHANGES_REQUIRED records findings and starts Planner N+1 for minimal fixes, then re-reviews. No post-success Plan. Planner/Workers use **ponytail** (YAGNI, reuse, minimal Tasks) without bypassing safety gates.
|
|
13
21
|
|
|
14
22
|
## 1. Choose and start a Job
|
|
15
23
|
|
|
@@ -18,46 +26,39 @@ Use Relay for durable multi-Task work with explicit objectives and acceptance cr
|
|
|
18
26
|
Consult CLI help; examples:
|
|
19
27
|
|
|
20
28
|
```sh
|
|
21
|
-
npx
|
|
22
|
-
npx agents-relay job
|
|
23
|
-
npx agents-relay
|
|
29
|
+
npx --yes --package agents-relay@latest agents-relay --help
|
|
30
|
+
npx --yes --package agents-relay@latest agents-relay job create --repo LOCAL_ROOT_NAME --project-root /absolute/path/to/git-root --title "Objective" --objective-file job.md --initial-plan
|
|
31
|
+
npx --yes --package agents-relay@latest agents-relay job show --id JOB_ID
|
|
32
|
+
npx --yes --package agents-relay@latest agents-relay task list --repo LOCAL_ROOT_NAME --id JOB_ID
|
|
24
33
|
```
|
|
25
34
|
|
|
26
|
-
Use returned Job IDs. Omit `--initial-plan` for DRAFT-only or Coordinator Graph work.
|
|
35
|
+
`job.repository` is the local Git root directory name and `job.projectRoot` is its immutable canonical path. Every Neo Project (`vlog`, `toyalive-3d`, etc.) has an independent Git root; no `job.projectPath` field exists. Remote owner/repository metadata is not part of Job identity. Use returned Job IDs. Omit `--initial-plan` for DRAFT-only or Coordinator Graph work. Local Git is the source of truth for review and merge; GitHub authentication and PRs are not part of Job execution.
|
|
27
36
|
|
|
28
37
|
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
38
|
|
|
30
39
|
## 2. Plan and execute
|
|
31
40
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
Agent `skills` suggests Worker skills; `model`/`reasoning` suggest Router preferences. Neither is mandatory (see `contracts/agent-contract.md`).
|
|
41
|
+
`job create --initial-plan` starts Planner; `plan` advances an existing DRAFT Job. Direct `task create` is for orchestrator-authored Tasks. Describe outcomes/dependencies, not shell commands. Public outputs: `--output local-git` or `--output file --output-path PATH`; historical SQLite `task_pr` means local Git work. Include `storySize`; `skills`, `model`, and `reasoning` are advisory. See `contracts/agent-contract.md`.
|
|
35
42
|
|
|
36
|
-
An
|
|
43
|
+
An execution Prompt pins a Skill/package version, Role, contracts, Task/Plan ID and execution ID. Use **that exact published npm version** when it differs from current `latest`; never substitute a local checkout or a different major/minor version. Before acting, load execution-bound context:
|
|
37
44
|
|
|
38
45
|
```sh
|
|
39
|
-
|
|
40
|
-
|
|
46
|
+
# RELAY_VERSION comes from the execution Prompt's pinned published package.
|
|
47
|
+
npx --yes --package "agents-relay@${RELAY_VERSION}" agents-relay task context --id JOB --task-id TASK --execution-id EXECUTION
|
|
48
|
+
npx --yes --package "agents-relay@${RELAY_VERSION}" agents-relay plan context --id JOB --plan-id PLAN --execution-id EXECUTION
|
|
41
49
|
```
|
|
42
50
|
|
|
43
|
-
Task
|
|
51
|
+
Task/Planner context rejects stale identities. Planner submits via `apply_cli`; only `PLAN_APPLIED:<plan-id>:<execution-id>` proves application. Delegated Tasks remain durable.
|
|
44
52
|
|
|
45
53
|
### Plan-free Coordinator / DAG execution
|
|
46
54
|
|
|
47
|
-
`agentGraph` is a
|
|
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
|
+
`agentGraph` is a dependency DAG: one durable Coordinator Task plus one durable Agent Task per ready node. Coordinator owns the Graph without a Worker lease. Script/Model Tasks share retry, review and terminal semantics; terminal events immediately release successors, respecting capacity and dependencies.
|
|
55
56
|
|
|
56
57
|
To create a plan-free Coordinator Job, include its Graph and execution paths
|
|
57
58
|
**in the original Job creation**, atomically with the durable Job. For example:
|
|
58
59
|
|
|
59
60
|
```sh
|
|
60
|
-
npx agents-relay job create --repo
|
|
61
|
+
npx --yes --package agents-relay@latest agents-relay job create --repo LOCAL_ROOT_NAME --project-root /absolute/project/root --title "Episode" \
|
|
61
62
|
--objective-file job.md \
|
|
62
63
|
--coordinator-graph-file /absolute/project/graph.mmd \
|
|
63
64
|
--coordinator-input-file /absolute/run/neo-project-run.input.md \
|
|
@@ -65,54 +66,28 @@ npx agents-relay job create --repo OWNER/REPO --title "Episode" \
|
|
|
65
66
|
--coordinator-project-root /absolute/project \
|
|
66
67
|
--coordinator-workspace-root /absolute/workspace \
|
|
67
68
|
--coordinator-shared-root /absolute/shared
|
|
68
|
-
npx agents-relay job run --id JOB_ID --task-id
|
|
69
|
-
--
|
|
70
|
-
|
|
69
|
+
npx --yes --package agents-relay@latest agents-relay job run --repo LOCAL_ROOT_NAME --id JOB_ID --task-id NUMERIC_TASK_ID \
|
|
70
|
+
--workspace-root /absolute/workspace --shared-root /absolute/shared
|
|
71
|
+
# Immediate CLI execution and live events (no background scheduling wait):
|
|
72
|
+
# append --foreground to the `job run` invocation.
|
|
71
73
|
```
|
|
72
74
|
|
|
73
|
-
Creation atomically persists
|
|
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.
|
|
75
|
+
Creation atomically persists a DRAFT Job and numeric Coordinator Task ID; reuse returned `taskId` for activation and caller Run bindings. DAG identity is `parentTaskId`/`nodeId`/`graphHash`. Normal activation queues; `--foreground` runs immediately and prints events, retaining durable state on interruption. `neo project run` binds and resumes the same Job. Reject legacy shortcut flags/modes. Final Review (`--review`/`--no-review`) and local merge (`--auto-merge`/`--no-auto-merge`) remain independent Job policies.
|
|
81
76
|
|
|
82
77
|
## 3. Verify, review, and recover
|
|
83
78
|
|
|
84
|
-
Inspect
|
|
79
|
+
Inspect Tasks with the version-matched published CLI. Final Review: `npx --yes --package agents-relay@latest agents-relay review job --repo LOCAL_ROOT_NAME --id JOB_ID [--thread-id THREAD_ID]`. Agent review: `npx --yes --package agents-relay@latest agents-relay review run --prompt-file PATH --project-path DIR` (standalone context only; never `job.projectPath`).
|
|
85
80
|
|
|
86
|
-
Process exit
|
|
81
|
+
Process exit or Preview receipt is not completion. Emit `task.started`, optional `task.progress`, and one correlated `task.completed` or `task.failed` through `events-bus`; never `task.blocked`. Verified reviewer findings use `task.completed` with `data.verdict: changes-required`, `data.head_sha` and actionable findings; unverifiable reviews fail. See `contracts/event-contract.md` and `contracts/worker-self-review.md`.
|
|
87
82
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
For a failed Task, **diagnose before retrying**. Load
|
|
91
|
-
`contracts/task-recovery-flows.md`; for external repository prerequisites load
|
|
92
|
-
`contracts/blocker-job-recovery.md`. Troubleshooter inspects the exact Task's
|
|
93
|
-
state and paginated event history, proves the technical repair and calls the
|
|
94
|
-
pinned `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER`.
|
|
95
|
-
For verified human-only blockers, use pinned `task escalate --task-id ...`;
|
|
96
|
-
this is a Relay CLI operation, not an Event. Recheck evidence after escalation;
|
|
97
|
-
never treat a stale response or an unverified operation as recovery.
|
|
83
|
+
**Diagnose before retrying** failed Tasks; inspect events and `contracts/task-recovery-flows.md` (external prerequisites: `contracts/blocker-job-recovery.md`). Use the version-matched published CLI for `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER` or verified human-only `task escalate`; a stale receipt is not resolution.
|
|
98
84
|
|
|
99
85
|
## 4. Configured escalation and host-owned Interactive Review
|
|
100
86
|
|
|
101
|
-
`agents-relay escalation`
|
|
102
|
-
|
|
103
|
-
or
|
|
104
|
-
returns `technical_failure`, never presumed human resolution. This differs
|
|
105
|
-
from the Task Troubleshooter `task escalate` operation.
|
|
106
|
-
|
|
107
|
-
A Worker requests human Review once in its current execution using
|
|
108
|
-
`agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`.
|
|
109
|
-
Relay delegates rendering to the configured host (Neo uses `review.preview` and
|
|
110
|
-
Markcut). The reviewed Task enters `AWAITING_DECISION`. An inbox/compile receipt
|
|
111
|
-
is **not approval**. An accepted Approve resumes the same Agent Task; Request
|
|
112
|
-
Changes resumes the same Task with feedback (a scripted Task can switch to its
|
|
113
|
-
Model executor for semantic revision, then return to Script for validation).
|
|
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`.
|
|
87
|
+
`npx --yes --package agents-relay@latest agents-relay escalation` requires configured `AGENTS_RELAY_ESCALATION_COMMAND`; missing/broken configuration is a technical failure. `task escalate` instead escalates a Task.
|
|
88
|
+
|
|
89
|
+
For host-owned Review use `npx --yes --package agents-relay@latest agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`. Neo `review.preview` or Markcut owns Preview; receipt is not approval. Approve or Request Changes resumes the same Task; each execution owns at most one Review. Durable feedback is not a Git commit.
|
|
115
90
|
|
|
116
91
|
## 5. Manage services when needed
|
|
117
92
|
|
|
118
|
-
For
|
|
93
|
+
For service operations load `daemon-service-manage`. Use `node <skill-dir>/bin/services.mjs setup|status|doctor`. Never restart Relay for ordinary Job commands or create legacy PM2 names.
|
|
@@ -142,14 +142,14 @@ If evidence is absent or execution outcome is unknown, disposition that historic
|
|
|
142
142
|
- A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
|
|
143
143
|
- Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
|
|
144
144
|
- Do not label authorized technical work in another repository as an owner action or request human escalation just because it crosses a repository boundary. Assign executable work that uses the pinned `blocker ensure` action under `contracts/blocker-job-recovery.md`; preserve escalation for a real owner-only decision.
|
|
145
|
-
- When the current Job is a prerequisite for another durable Job/Task, emit that dependent in top-level `unblocks`. The current blocker Job owns this authoritative reverse relation. Dependent-side `blockedBy` is optional observability metadata and is not the source of truth. Use `resolutionMode: "merge"` when blocker
|
|
145
|
+
- When the current Job is a prerequisite for another durable Job/Task, emit that dependent in top-level `unblocks`. The current blocker Job owns this authoritative reverse relation. Dependent-side `blockedBy` is optional observability metadata and is not the source of truth. Use `resolutionMode: "merge"` when the blocker Job’s verified local Git merge is sufficient; use `"verified"` when publication, deployment, runtime health, human approval, or another post-merge fact must be verified.
|
|
146
146
|
- Describe each child Task precisely enough for worker-router to decide from the Task itself. Do not invent Codex/ChatGPT capability labels. workerRequirements is optional and should normally be omitted; use an explicit runtime only when the objective already requires that runtime.
|
|
147
147
|
- Do not choose codex/chatgpt, provider/model, or usage probes.
|
|
148
|
-
- Every child Task must declare exactly one output: `task_pr` or `file`.
|
|
148
|
+
- Every child Task must declare exactly one output: `task_pr` (historical serialized enum for local Git code work; **not** a GitHub pull request) or `file`. The equivalent public CLI spelling is `--output local-git`.
|
|
149
149
|
- Every child Task must include `storySize` (`S`, `M`, or `L`); use `M` when uncertain.
|
|
150
150
|
- Do not create bookkeeping, waiting, status-checking, wrapper, or planning Tasks. Your response itself is the planning round.
|
|
151
|
-
- Relay owns lifecycle delivery for local-first Jobs. Never create a worker Task whose job is to perform the local Git merge, mark the Job `COMPLETED`, merge
|
|
152
|
-
- When all executable implementation work is complete and the only remaining steps are Relay-owned final review, local merge, Job completion, or
|
|
151
|
+
- Relay owns lifecycle delivery for local-first Jobs. Never create a worker Task whose job is to perform the local Git merge, mark the Job `COMPLETED`, push or merge a remote GitHub PR, or wait/check for any Relay-owned effect. After implementation and required review are satisfied, return no lifecycle-completion Task; let the canonical Review/Local-Merge/Job Graph advance the Job.
|
|
152
|
+
- When all executable implementation work is complete and the only remaining steps are Relay-owned final review, local merge, Job completion, or optional post-completion origin delivery, return `objective_status: "satisfied"` with `next_tasks: []`. Do not return `in_progress` with an empty task list before final review; that would leave the Job with no executable progress path.
|
|
153
153
|
- Do not print the candidate JSON as the final reply. Write it to a temporary file, invoke the execution-bound `apply_cli` with that file, and only return the exact successful `PLAN_APPLIED:<plan-id>:<execution-id>` receipt.
|
|
154
154
|
|
|
155
155
|
## Output
|
|
@@ -172,7 +172,7 @@ Each item in `next_tasks` contains **required `title`**, id, input, output, and
|
|
|
172
172
|
Use these exact serialized forms:
|
|
173
173
|
|
|
174
174
|
- `output` is always an object, never a string:
|
|
175
|
-
-
|
|
175
|
+
- Local Git code work (legacy serialized kind, no GitHub PR): `{"kind":"task_pr"}`
|
|
176
176
|
- File artifact: `{"kind":"file","path":"runs/2026-09-26/example/output.md"}`
|
|
177
177
|
- `agentGraph`, when present, is one executable Mermaid Agent Graph **string** using `flowchart TD|TB|LR|RL`, for example `"flowchart LR\n build-log-editor --> build-log-producer"`. Do not emit `graph LR`, and do not emit an object with `nodes` or `edges`.
|
|
178
178
|
- `priority`, when present, is exactly `"P0"`, `"P1"`, `"P2"`, or `"P3"`; otherwise omit it.
|
|
@@ -1,12 +1,26 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {spawnSync} from 'node:child_process';
|
|
3
|
+
import {basename} from 'node:path';
|
|
3
4
|
const skill="agents-relay";
|
|
4
|
-
const definitions=[["daemon", "npx", ["
|
|
5
|
+
const definitions=[["daemon", "npx", ["--yes", "--package", "agents-relay@latest", "agents-relayd", "--port", "8787", "--concurrency", "4", "--interval", "300000", "--refresh-ms", "300000"]], ["dashboard-tunnel", "cloudflared", ["tunnel", "--protocol", "http2", "--no-autoupdate", "run", "--url", "http://127.0.0.1:8787", "agents-relay-dashboard"]]];
|
|
5
6
|
const home=process.env.HOME||'';
|
|
6
7
|
const expand=s=>s.replaceAll('__HOME__',home);
|
|
7
8
|
const action=process.argv[2]||'status';
|
|
8
9
|
if(!['setup','status','doctor'].includes(action)){console.error('usage: node skills/'+skill+'/bin/services.mjs setup|status|doctor');process.exit(2)}
|
|
9
10
|
const run=(cmd,args)=>{const p=spawnSync(cmd,args,{encoding:'utf8'});if(p.error)throw p.error;if(p.status!==0)throw new Error(cmd+' failed: '+String(p.stderr||p.stdout).slice(0,300));return p.stdout};
|
|
11
|
+
// PM2 keeps its original argv across source-file edits and ordinary restarts.
|
|
12
|
+
// Report drift rather than claiming an outdated live service matches this Skill.
|
|
13
|
+
const configured=(binary,args,live)=>{
|
|
14
|
+
const env=live?.pm2_env;
|
|
15
|
+
if(!env)return false;
|
|
16
|
+
const expected=args.map(expand);
|
|
17
|
+
const actual=Array.isArray(env.args)?env.args.map(String):[];
|
|
18
|
+
const launch=String(env.pm_exec_path||'');
|
|
19
|
+
const isNode=binary==='node';
|
|
20
|
+
const binaryMatches=isNode?launch===expected[0]:basename(launch)===binary;
|
|
21
|
+
const expectedArgs=isNode?expected.slice(1):expected;
|
|
22
|
+
return binaryMatches&&JSON.stringify(actual)===JSON.stringify(expectedArgs);
|
|
23
|
+
};
|
|
10
24
|
try {
|
|
11
25
|
const pm2=JSON.parse(run('npx',['--yes','pm2','jlist']));
|
|
12
26
|
const report=[];
|
|
@@ -20,8 +34,12 @@ try {
|
|
|
20
34
|
if(result.status!==0)throw new Error('failed to define '+id);
|
|
21
35
|
}
|
|
22
36
|
const live=action==='setup'?JSON.parse(run('npx',['--yes','pm2','jlist'])).find(x=>x.name===id):current;
|
|
23
|
-
report.push({service:id,state:live?.pm2_env?.status||'missing',registered:Boolean(live)
|
|
37
|
+
report.push({service:id,state:live?.pm2_env?.status||'missing',registered:Boolean(live),
|
|
38
|
+
configuration:!live?'missing':configured(binary,args,live)?'match':'drift'});
|
|
24
39
|
}
|
|
25
40
|
console.log(JSON.stringify({skill,services:report},null,2));
|
|
26
|
-
if(report.some(x=>x.state!=='online'))
|
|
41
|
+
if(report.some(x=>x.state!=='online'||x.configuration!=='match')) {
|
|
42
|
+
console.error('Service missing, unhealthy, or PM2 argv drift: inspect and explicitly re-register the affected service; setup does not overwrite a live PM2 definition.');
|
|
43
|
+
process.exitCode=2;
|
|
44
|
+
}
|
|
27
45
|
} catch(e){console.error(e.message);process.exitCode=2}
|
|
@@ -8,6 +8,8 @@ Job objectives and Task inputs are **Markdown** and are durable execution contex
|
|
|
8
8
|
|
|
9
9
|
Create, update, and read Job objectives and Task inputs only through the version-matched Relay CLI. Do not parse or edit PR bodies, comments, hidden markers, or private files to obtain or alter Relay state.
|
|
10
10
|
|
|
11
|
+
Every Job has one immutable local repository identity: `repository` is the canonical Git root directory name and `projectRoot` is the validated absolute canonical Git root. Each Neo Project must have its own Git repository; there is no `job.projectPath` subdirectory. A Git remote is not part of Job identity: optional post-completion delivery inspects the existing local `origin` and verified `origin/main` without CLI GitHub/PR options. Never use a GitHub owner/repository string or a `local/...` alias as `repository`, and never infer project ownership from `graphStartContext.projectRoot`. Jobs for separate Git worktrees must bind to the canonical root, not a worktree. Local Git remains authoritative for final review and merge.
|
|
12
|
+
|
|
11
13
|
For long-form content, use files instead of shell-quoted arguments:
|
|
12
14
|
|
|
13
15
|
- Job create/update: `--objective-file PATH` (or `--objective-file -` for stdin) is preferred. `--objective` is for short/simple content only. They are mutually exclusive.
|
|
@@ -23,6 +25,12 @@ Agent frontmatter `skills`, `model`, and `reasoning` are optional **hints**, not
|
|
|
23
25
|
|
|
24
26
|
## Task producers
|
|
25
27
|
|
|
28
|
+
Every persisted Task ID is a store-global, monotonically allocated positive
|
|
29
|
+
decimal string. Producers must use Relay's canonical allocator; a caller may
|
|
30
|
+
provide a durable idempotency key but never an ID. Business identity belongs
|
|
31
|
+
in structured fields and idempotency keys, not in Task IDs. Do not derive
|
|
32
|
+
identity from ID prefixes or retain string-ID compatibility paths.
|
|
33
|
+
|
|
26
34
|
Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
|
|
27
35
|
Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
|
|
28
36
|
|
|
@@ -47,7 +55,8 @@ A later Planner round must inspect the existing semantic tree and attach review,
|
|
|
47
55
|
For an executable `agentGraph`, create the Job and its Coordinator Task
|
|
48
56
|
atomically through `job create --coordinator-graph-file ...` (with input,
|
|
49
57
|
output, project/workspace paths); activate it with
|
|
50
|
-
`job run --id JOB --task-id
|
|
58
|
+
`job run --id JOB --task-id NUMERIC_TASK_ID` using the Task ID returned by Job
|
|
59
|
+
creation. This is an alternative to an
|
|
51
60
|
initial Planner, **not** a separate Job mode or nested runner.
|
|
52
61
|
|
|
53
62
|
The Coordinator stays durable and does not consume a Worker lease. Each graph
|
|
@@ -207,7 +216,7 @@ review delivery itself to create commits or tags.
|
|
|
207
216
|
|
|
208
217
|
This is a strong execution boundary:
|
|
209
218
|
|
|
210
|
-
- tracked source/code work may use a managed
|
|
219
|
+
- tracked source/code work may use a managed local Git worktree;
|
|
211
220
|
- Neo Project runtime work under `runs/` uses the canonical project directory;
|
|
212
221
|
- continuations, reviews, QA, render, and publication Tasks beneath a `runs/` owner reuse that same canonical runtime directory;
|
|
213
222
|
- `runs/` remains ignored/private and must not be committed merely to move evidence between Tasks;
|
|
@@ -75,10 +75,15 @@
|
|
|
75
75
|
"decision": "create",
|
|
76
76
|
"command": "job create",
|
|
77
77
|
"flags": [
|
|
78
|
-
"--
|
|
78
|
+
"--repo",
|
|
79
|
+
"--project-root",
|
|
80
|
+
"--objective-file"
|
|
79
81
|
]
|
|
80
82
|
},
|
|
81
83
|
"forbidden": [
|
|
84
|
+
"--no-github",
|
|
85
|
+
"--github-repo",
|
|
86
|
+
"--pr",
|
|
82
87
|
"GitHub authentication required"
|
|
83
88
|
]
|
|
84
89
|
},
|
|
@@ -1,66 +1,69 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
description:
|
|
2
|
+
title: Completed Local Git Delivery
|
|
3
|
+
description: Optionally deliver completed local main to a usable origin with independent bounded retries.
|
|
4
4
|
name: projection-conflict
|
|
5
|
-
authority: SQLite
|
|
6
|
-
trigger:
|
|
7
|
-
idempotency: job-id plus
|
|
5
|
+
authority: SQLite delivery state and completed Job snapshot
|
|
6
|
+
trigger: job.completed or delivery.retry_due
|
|
7
|
+
idempotency: job-id plus local main SHA
|
|
8
8
|
actions:
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
-
|
|
9
|
+
- delivery.claimInspection
|
|
10
|
+
- delivery.skip
|
|
11
|
+
- delivery.pushMain
|
|
12
|
+
- delivery.recordDelivered
|
|
13
|
+
- delivery.scheduleRetry
|
|
14
|
+
- delivery.recordExhausted
|
|
13
15
|
guards:
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
- projection.repairFailed
|
|
16
|
+
- delivery.claimAvailable
|
|
17
|
+
- delivery.originUsable
|
|
18
|
+
- delivery.remoteMainPresent
|
|
19
|
+
- delivery.remoteContainsMain
|
|
20
|
+
- delivery.retryAvailable
|
|
21
|
+
- delivery.retryDue
|
|
21
22
|
---
|
|
22
23
|
flowchart LR
|
|
23
24
|
%% relay: initial classify
|
|
24
25
|
classify["state: classify"]
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
inspect["state: inspect"]
|
|
27
|
+
push["state: push"]
|
|
28
|
+
waiting["state: waiting"]
|
|
29
|
+
delivered["state: delivered"]
|
|
30
|
+
skipped["state: skipped"]
|
|
31
|
+
exhausted["state: exhausted"]
|
|
30
32
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
33
|
+
originUsable["guard: delivery.originUsable"]
|
|
34
|
+
claimAvailable["guard: delivery.claimAvailable"]
|
|
35
|
+
claimInspection["action: delivery.claimInspection"]
|
|
36
|
+
remoteMainPresent["guard: delivery.remoteMainPresent"]
|
|
37
|
+
remoteContains["guard: delivery.remoteContainsMain"]
|
|
38
|
+
retryAvailable["guard: delivery.retryAvailable"]
|
|
39
|
+
retryDue["guard: delivery.retryDue"]
|
|
40
|
+
skip["action: delivery.skip"]
|
|
41
|
+
pushMain["action: delivery.pushMain"]
|
|
42
|
+
recordDelivered["action: delivery.recordDelivered"]
|
|
43
|
+
scheduleRetry["action: delivery.scheduleRetry"]
|
|
44
|
+
recordExhausted["action: delivery.recordExhausted"]
|
|
41
45
|
|
|
42
|
-
classify -->|on:
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
retryAvailable -->|true|
|
|
58
|
-
retryAvailable -->|false|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
retry -->|on: projection.delivery_failed| eligible
|
|
46
|
+
classify -->|on: job.completed| claimAvailable
|
|
47
|
+
claimAvailable -->|true| claimInspection
|
|
48
|
+
claimAvailable -->|false| recordExhausted
|
|
49
|
+
claimInspection --> inspect
|
|
50
|
+
inspect -->|on: inspect.completed| originUsable
|
|
51
|
+
originUsable -->|false| skip
|
|
52
|
+
originUsable -->|true| remoteMainPresent
|
|
53
|
+
remoteMainPresent -->|false| skip
|
|
54
|
+
remoteMainPresent -->|true| remoteContains
|
|
55
|
+
inspect -->|on: delivery.failed| retryAvailable
|
|
56
|
+
remoteContains -->|true| recordDelivered
|
|
57
|
+
remoteContains -->|false| pushMain
|
|
58
|
+
pushMain --> push
|
|
59
|
+
push -->|on: delivery.pushed| recordDelivered
|
|
60
|
+
push -->|on: delivery.failed| retryAvailable
|
|
61
|
+
retryAvailable -->|true| scheduleRetry
|
|
62
|
+
retryAvailable -->|false| recordExhausted
|
|
63
|
+
scheduleRetry --> waiting
|
|
64
|
+
waiting -->|on: delivery.retry_due| retryDue
|
|
65
|
+
retryDue -->|true| claimAvailable
|
|
66
|
+
retryDue -->|false| waiting
|
|
67
|
+
recordDelivered --> delivered
|
|
68
|
+
skip --> skipped
|
|
69
|
+
recordExhausted --> exhausted
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Historical Projection Outbox Conflict
|
|
3
|
+
description: Classify a legacy SQLite outbox delivery failure without creating Job Tasks or changing the completed Job lifecycle.
|
|
4
|
+
name: projection-outbox-conflict
|
|
5
|
+
authority: SQLite projection outbox row
|
|
6
|
+
trigger: projection.failed
|
|
7
|
+
guards:
|
|
8
|
+
- deterministicDefinitionConflict
|
|
9
|
+
---
|
|
10
|
+
flowchart LR
|
|
11
|
+
%% relay: initial classify
|
|
12
|
+
%% Only historical external outbox receipts use this graph. It never mutates a Job.
|
|
13
|
+
classify["state: classify"]
|
|
14
|
+
conflict["state: conflict"]
|
|
15
|
+
retry["state: retry"]
|
|
16
|
+
deterministic["guard: deterministicDefinitionConflict"]
|
|
17
|
+
|
|
18
|
+
classify -->|on: projection.failed| deterministic
|
|
19
|
+
deterministic -->|true| conflict
|
|
20
|
+
deterministic -->|false| retry
|
package/dist/cli-projection.js
DELETED
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
import { arg, integerArg, relayControlCommand } from './cli-support.js';
|
|
2
|
-
export async function runProjectionCommand(action, args) {
|
|
3
|
-
const jobId = arg(args, '--id');
|
|
4
|
-
if (!jobId)
|
|
5
|
-
throw new Error('projection commands require --id JOB_ID');
|
|
6
|
-
if (action === 'conflicts' || action === 'list') {
|
|
7
|
-
console.log(JSON.stringify(await relayControlCommand(args, { command: 'projection.conflicts', jobId }), null, 2));
|
|
8
|
-
return;
|
|
9
|
-
}
|
|
10
|
-
if (action === 'resolve') {
|
|
11
|
-
const id = integerArg(args, '--projection-id', 0);
|
|
12
|
-
if (id <= 0)
|
|
13
|
-
throw new Error('projection resolve requires --projection-id ID');
|
|
14
|
-
const raw = arg(args, '--action', 'requeue');
|
|
15
|
-
if (!['requeue', 'discard-local', 'discard_local'].includes(raw))
|
|
16
|
-
throw new Error('--action must be requeue or discard-local');
|
|
17
|
-
const resolution = raw === 'requeue' ? 'requeue' : 'discard_local';
|
|
18
|
-
const note = arg(args, '--note') || undefined;
|
|
19
|
-
const result = await relayControlCommand(args, { command: 'projection.resolve', jobId, projectionId: id, action: resolution, ...(note ? { note } : {}) });
|
|
20
|
-
console.log(JSON.stringify(result, null, 2));
|
|
21
|
-
return;
|
|
22
|
-
}
|
|
23
|
-
throw new Error(`projection ${action || '<action>'} is not supported; use conflicts or resolve`);
|
|
24
|
-
}
|
|
25
|
-
export function projectionHelp(action) {
|
|
26
|
-
if (action === 'resolve')
|
|
27
|
-
return `Explicitly repair one classified projection conflict.\n\nRequired: --repo OWNER/REPO --id JOB_ID --projection-id ID --action requeue|discard-local.`;
|
|
28
|
-
return `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.\n\nUsage:\n npx agents-relay projection conflicts --repo OWNER/REPO --id JOB_ID\n npx agents-relay projection resolve --repo OWNER/REPO --id JOB_ID --projection-id ID --action requeue|discard-local`;
|
|
29
|
-
}
|