agents-relay 2.0.234 → 2.0.235
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 +25 -19
- package/dist/cli-help.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -91,21 +91,23 @@ EOF
|
|
|
91
91
|
npx agents-relay job create --repo OWNER/REPO \
|
|
92
92
|
--title "Objective" --objective-file job.md
|
|
93
93
|
|
|
94
|
-
#
|
|
94
|
+
# Create-only example: the orchestrator explicitly adds these Tasks.
|
|
95
|
+
# For normal autonomous execution, instead pass --initial-plan at creation
|
|
96
|
+
# and let the Planner choose the minimal Tasks; do not also create these manually.
|
|
95
97
|
cat > task.md <<'EOF'
|
|
96
98
|
# Work
|
|
97
99
|
|
|
98
100
|
Implement this phase using the Job objective as context.
|
|
99
101
|
EOF
|
|
100
|
-
npx agents-relay task create --repo OWNER/REPO --id
|
|
102
|
+
npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
|
|
101
103
|
--task-id initial --output task-pr --input-file task.md
|
|
102
104
|
|
|
103
|
-
npx agents-relay task create --repo OWNER/REPO --id
|
|
105
|
+
npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
|
|
104
106
|
--task-id child --output task-pr \
|
|
105
107
|
--input "Implement the described child task and publish a terminal event."
|
|
106
108
|
|
|
107
|
-
npx agents-relay reconcile --repo OWNER/REPO --
|
|
108
|
-
npx agents-relay job show --
|
|
109
|
+
npx agents-relay reconcile --repo OWNER/REPO --id JOB_ID
|
|
110
|
+
npx agents-relay job show --id JOB_ID
|
|
109
111
|
~~~
|
|
110
112
|
|
|
111
113
|
Task readiness is explicit: `DRAFT` means the durable task exists but is not executable yet; `QUEUED` means Relay may execute it now; `RUNNING` means worker execution has started. Tasks created with dependencies start `DRAFT` and become `QUEUED` when those dependencies succeed. A dependency-free task created with `--draft` stays held until `task update --queue`. After binding an interactive request, a running Task may enter `AWAITING_DECISION` and release its Worker. Approved or changes-requested decisions requeue the same Task; `BLOCKED` is reserved for Troubleshooter escalation. Ordinary `DRAFT` Tasks remain unstarted/dependency-held.
|
|
@@ -113,37 +115,41 @@ Task readiness is explicit: `DRAFT` means the durable task exists but is not exe
|
|
|
113
115
|
Mutable draft/queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
|
|
114
116
|
|
|
115
117
|
~~~sh
|
|
116
|
-
npx agents-relay task update --repo OWNER/REPO --
|
|
118
|
+
npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child \
|
|
117
119
|
--adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
|
|
118
120
|
--capabilities model,chatgpt,browser-harness
|
|
119
121
|
|
|
120
122
|
# Explicitly release a held DRAFT task
|
|
121
|
-
npx agents-relay task update --repo OWNER/REPO --
|
|
123
|
+
npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child --queue
|
|
122
124
|
~~~
|
|
123
125
|
|
|
124
126
|
Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created Job is DRAFT, and creating executable work or starting the Planner activates it. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, and locally confirmed merge facts and is never persisted as lifecycle truth.
|
|
125
127
|
|
|
128
|
+
The **Job Execution Lifecycle (JEL)** is Create → Plan → Execute → Final Review → Merge → Completed. All work/recovery Tasks must reach a terminal state (SUCCEEDED, FAILED, or CANCELLED) before Final Review is eligible; terminal failure is evidence for the reviewer, not automatic acceptance. The independent Final Reviewer records findings. A PASS goes to the merge gate; CHANGES_REQUIRED persists findings and starts a minimal Planner N+1 repair round, then another Final Review. No automatic Plan N+1 is created after successful work. Planner and Workers use the discovered `ponytail` Skill to avoid unnecessary tasks without omitting required verification. For operator discussion, call this lifecycle **JEL**.
|
|
129
|
+
|
|
126
130
|
Lifecycle transition authority lives in the directly renderable canonical flowchart sources linked in [Workflow graph navigation](#workflow-graph-navigation). Git history owns prior graph versions; the working tree contains only the current graph set.
|
|
127
131
|
|
|
128
132
|
The canonical Mermaid Graph Engine is the authoritative durable workflow decision path. Job/Task lifecycle transitions plus Review, Planner, Blocker/Unblock, and Troubleshooter orchestration branches are defined by the canonical workflow graphs and executed through the shared graph runtime. TypeScript supplies facts and primitive action/effect implementations; it must not duplicate those workflow branches as a second procedural state machine.
|
|
129
133
|
|
|
130
|
-
Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat.
|
|
134
|
+
Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. SQLite owns Job metadata and objectives. Any display PR or historical PR marker is a compatibility/audit projection, not the source of lifecycle truth.
|
|
131
135
|
|
|
132
|
-
Every Job is objective-driven. `job create` persists only
|
|
133
|
-
|
|
136
|
+
Every Job is objective-driven. By default, `job create` persists only a DRAFT
|
|
137
|
+
Job; `--initial-plan` also initializes the first real Planner round and its
|
|
138
|
+
validated work. For a create-only Job, the caller can add Tasks directly with
|
|
134
139
|
`task create` or invoke the Planner explicitly with `plan`. Direct
|
|
135
140
|
orchestrator-created tasks are persisted directly and are not wrapped in a
|
|
136
141
|
synthetic Plan. `agents-relay plan` works immediately on a zero-task DRAFT Job,
|
|
137
142
|
activates it, persists a real `plan-N` planning round, and materializes validated
|
|
138
143
|
`next_tasks`. Reconciliation does not invent the first round for an untouched
|
|
139
|
-
zero-task DRAFT Job
|
|
140
|
-
|
|
144
|
+
zero-task DRAFT Job. Once work starts, Relay waits for all work/recovery Tasks
|
|
145
|
+
to terminate and triggers Final Review. Only a CHANGES_REQUIRED review verdict
|
|
146
|
+
can start the next Planner round; PASS proceeds to the local merge gate.
|
|
141
147
|
|
|
142
148
|
Manual planning syntax:
|
|
143
149
|
|
|
144
150
|
~~~sh
|
|
145
|
-
npx agents-relay plan --repo OWNER/REPO --
|
|
146
|
-
npx agents-relay plan --repo OWNER/REPO --
|
|
151
|
+
npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt "Plan the implementation from the durable objective"
|
|
152
|
+
npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt-file guidance.md
|
|
147
153
|
~~~
|
|
148
154
|
|
|
149
155
|
The optional prompt is additional round guidance; it does not replace the durable Job objective. New planning rounds use `plan-N`; historical `planner-N` records remain readable.
|
|
@@ -167,7 +173,7 @@ Use `job update` for partial mutable metadata changes on an already healthy Job
|
|
|
167
173
|
npx agents-relay job update --id JOB_ID --priority P0 --no-auto-merge
|
|
168
174
|
~~~
|
|
169
175
|
|
|
170
|
-
Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --
|
|
176
|
+
Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --id JOB_ID`.
|
|
171
177
|
Pass optional `--thread-id THREAD_ID` to persist a reviewer-thread override for subsequent
|
|
172
178
|
review routing. Without it, Relay uses the stored reviewer thread, then creator thread,
|
|
173
179
|
or the legacy review path when neither exists. This request wakes graph-owned
|
|
@@ -190,7 +196,7 @@ Managed GitHub task create/update/show/list/retry/cancel and reconcile/serve com
|
|
|
190
196
|
The original init command remains supported for backward compatibility:
|
|
191
197
|
|
|
192
198
|
~~~sh
|
|
193
|
-
npx agents-relay init --repo OWNER/REPO --pr 1 --id
|
|
199
|
+
npx agents-relay init --repo OWNER/REPO --pr 1 --id JOB_ID --title "Objective"
|
|
194
200
|
~~~
|
|
195
201
|
|
|
196
202
|
## npm publishing
|
|
@@ -275,7 +281,7 @@ Relay does not discover Skill directories or invoke a separate runtime.
|
|
|
275
281
|
The ChatGPT adapter uses Relay's `agents/chatgpt-worker.agent.md` lifecycle contract. A new worker uses `webhelm platform run chatgpt new-thread --session-id SESSION_ID --config <file>` in a caller-owned Session. This is a regular persistent ChatGPT thread, which supports the connected Neo MCP in the verified account. Relay closes the Session after submission, but the ChatGPT thread remains in history. Existing-thread review and handoff continue through `new-turn`. File paths are included in the worker message for Neo MCP reading; they are not uploaded as browser attachments. Submission receipts retain `status: submitted`; the event bus owns task completion.
|
|
276
282
|
|
|
277
283
|
~~~sh
|
|
278
|
-
npx agents-relay task create --repo OWNER/REPO --pr 5 --id
|
|
284
|
+
npx agents-relay task create --repo OWNER/REPO --pr 5 --id JOB_ID \
|
|
279
285
|
--task-id research-ui --adapter chatgpt \
|
|
280
286
|
--capabilities model,chatgpt,browser-harness \
|
|
281
287
|
--provider openai --model MODEL \
|
|
@@ -283,13 +289,13 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
|
|
|
283
289
|
--input "Research the dashboard UX and write the final report to the declared output file."
|
|
284
290
|
~~~
|
|
285
291
|
|
|
286
|
-
|
|
292
|
+
SQLite and the canonical Graphs are authoritative for terminal lifecycle. A remote PR merge/close is an audit observation, not a state transition. Final Review PASS authorizes local Git merge; confirmed local-merge evidence gates `COMPLETED`. The dashboard exposes `/api/jobs` and distinguishes durable Job lifecycle from derived runtime status.
|
|
287
293
|
|
|
288
294
|
Relay has no orchestrator worker adapter for new work. Orchestrators are external clients that create/plan durable Tasks; Execution Router selects a real worker route (`codex` or `chatgpt`). The CLI and dashboard do not expose manual orchestrator-only `task start`, `task complete`, or synthetic `record` paths.
|
|
289
295
|
|
|
290
296
|
Historical stores may still contain `adapter: orchestrator`. Reconciliation treats that value only as legacy migration evidence: QUEUED work that never started can be converted in place to normal worker requirements; RUNNING work with an unknown outcome is quarantined as BLOCKED instead of replayed; only explicit durable `externalCompletionVerified` evidence can complete legacy work without execution. New Task creation and Task update reject that adapter.
|
|
291
297
|
|
|
292
|
-
For managed
|
|
298
|
+
For managed Jobs, SQLite is the canonical collaboration and lifecycle record; an optional GitHub display PR carries audit information only.
|
|
293
299
|
|
|
294
300
|
### Automatic task troubleshooting
|
|
295
301
|
|
package/dist/cli-help.js
CHANGED
|
@@ -43,9 +43,9 @@ Actions:
|
|
|
43
43
|
run Opt in to direct Agent Graph shortcuts for one existing 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
|
-
merge
|
|
46
|
+
merge Legacy entry point; local Git merge is Graph-owned (no CLI PR merge)
|
|
47
47
|
unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
|
|
48
|
-
cancel
|
|
48
|
+
cancel Cancel the Job through the SQLite/Graph lifecycle (no PR required)
|
|
49
49
|
pause Persistently stop dispatch and interrupt active generations; lifecycle state remains unchanged
|
|
50
50
|
resume Clear pause metadata and requeue interrupted work
|
|
51
51
|
|