agents-relay 2.0.194 → 2.0.196
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/dist/adapters.js +10 -6
- package/dist/agent-content-resolver.js +28 -1
- package/dist/agent-prompt-builder.js +73 -3
- package/dist/browser-worker-runtime.js +40 -22
- package/dist/cli-help.js +20 -5
- package/dist/cli-prompt.js +132 -0
- package/dist/cli-shutdown.js +3 -0
- package/dist/cli-support.js +47 -5
- package/dist/cli.js +19 -30
- package/dist/dashboard-html.js +8 -6
- package/dist/dashboard-style.js +16 -1
- package/dist/events-bus-runtime.js +58 -8
- package/dist/local-job-registry.js +9 -5
- package/dist/managed-worker-input.js +48 -74
- package/dist/planner.js +16 -10
- package/dist/reconciler.js +3 -7
- package/dist/troubleshooter.js +2 -2
- package/dist/z-adapter.js +16 -8
- package/package.json +3 -1
- package/skills/agents-relay/SKILL.md +82 -30
- package/skills/agents-relay/agents/implementation.agent.md +1 -2
- package/skills/agents-relay/agents/planner.agent.md +12 -12
- package/skills/agents-relay/agents/reviewer.agent.md +1 -1
- package/skills/agents-relay/agents/troubleshooter.agent.md +6 -6
- package/skills/agents-relay/contracts/event-contract.md +6 -3
- package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -4
- package/skills/agents-relay/contracts/task-job-contract.md +23 -20
- package/skills/agents-relay/contracts/task-recovery-flows.md +15 -35
package/dist/z-adapter.js
CHANGED
|
@@ -4,10 +4,17 @@ import { pooledWebHelmRun } from './browser-worker-runtime.js';
|
|
|
4
4
|
import { issueZWorkerCredential } from './z-oauth.js';
|
|
5
5
|
/** The worker must use the exact server-issued execution source, never invent one. */
|
|
6
6
|
export function zExecutionSource(prompt) {
|
|
7
|
-
const
|
|
8
|
-
if (
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
const explicit = [...prompt.matchAll(/^Execution source: (job\/[^\s/]+\/task\/[^\s/]+\/execution\/[0-9a-f-]{36})$/gm)];
|
|
8
|
+
if (explicit.length === 1)
|
|
9
|
+
return explicit[0][1];
|
|
10
|
+
if (explicit.length > 1)
|
|
11
|
+
throw new Error('Z worker prompt contains multiple execution sources');
|
|
12
|
+
const job = [...prompt.matchAll(/^Job: ([^\s]+)$/gm)];
|
|
13
|
+
const task = [...prompt.matchAll(/^Task: ([^\s]+)$/gm)];
|
|
14
|
+
const execution = [...prompt.matchAll(/^Execution: ([0-9a-f-]{36})$/gm)];
|
|
15
|
+
if (job.length !== 1 || task.length !== 1 || execution.length !== 1)
|
|
16
|
+
throw new Error('Z worker prompt requires exactly one Graph-issued execution source');
|
|
17
|
+
return `job/${job[0][1]}/task/${task[0][1]}/execution/${execution[0][1]}`;
|
|
11
18
|
}
|
|
12
19
|
/** A compact executable prompt avoids Z.ai's silent long-message persistence failures. */
|
|
13
20
|
export function zTaskBrief(prompt) {
|
|
@@ -20,7 +27,7 @@ export function zTaskBrief(prompt) {
|
|
|
20
27
|
if (!output)
|
|
21
28
|
throw new Error('Z worker missing authoritative output contract');
|
|
22
29
|
const objective = prompt.match(/^Job objective: (.+)$/m)?.[1];
|
|
23
|
-
return '[LOCAL SQLite Job — no GitHub lookup]\nThe Task brief is complete and authoritative. Do
|
|
30
|
+
return '[LOCAL SQLite Job — no GitHub lookup]\nThe Task brief is complete and authoritative. Do not query GitHub issues or PRs for Relay state; use the version-matched Relay CLI. Read Neo bootstrap and the pinned contracts, retrieve Task context with Relay CLI, then execute the Task.\n[Durable Job objective]\n' + (objective ?? '(see task)') +
|
|
24
31
|
'\n[Authoritative Task input]\n' + local +
|
|
25
32
|
'\n[Output contract]\n' + output;
|
|
26
33
|
}
|
|
@@ -37,11 +44,11 @@ export function zBootstrap(accessToken, prompt) {
|
|
|
37
44
|
'You run in Z cloud Bash. Neo Master is a SEPARATE Mac accessed only by HTTPS Neo MCP at https://neoy.qili2.com/mcp. A Z local file is NOT a Neo Master output.',
|
|
38
45
|
'One-hour OAuth worker credential: ' + accessToken,
|
|
39
46
|
'NEVER print the credential, put it in output, or store it in a repository. Each Bash tool call has a fresh shell. Set the token inside EVERY Bash invocation.',
|
|
40
|
-
'
|
|
47
|
+
'FIRST ACTION: Before any reasoning/planning/bootstrap, make ONE real Bash tool call to send task.started. Relay will timeout without it. Use the exact shell commands:',
|
|
41
48
|
"NEO_ACCESS_TOKEN='" + accessToken + "'",
|
|
42
49
|
"curl -sS --max-time 20 https://neoy.qili2.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H \"Authorization: Bearer $NEO_ACCESS_TOKEN\" --data-binary '" + makeEvent('task.started', 'Z worker started') + "'",
|
|
43
50
|
'Check JSON-RPC result (not only HTTP status). Retry once on transient error. DO NOT merely explain this call.',
|
|
44
|
-
'
|
|
51
|
+
'Then follow the manual bootstrap at https://neoy.qili2.com/files/z-chat/bootstrap.md. Via Neo MCP shell exec run "neo bootstrap". Read returned Global rules and only the pinned Event/Task contracts from the Graph Action Prompt.',
|
|
45
52
|
...(instructionSnapshot ? ['After task.started, use Neo MCP fs to read the Relay-pinned agent instruction snapshot: ' + instructionSnapshot + '. Follow it in addition to Neo bootstrap, but keep Task intent from the durable Task brief.'] : []),
|
|
46
53
|
'Work on Neo Master using its MCP fs/shell tools; first discover their schemas with tools/list. A call uses JSON-RPC {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"shell","arguments":{"command":"help"}}}. Set NEO_ACCESS_TOKEN again inside the SAME Bash tool call as curl.',
|
|
47
54
|
'Before success, validate EVERY explicit acceptance criterion from the Task brief. If the Task requires an exact marker/text, verify that exact literal with Neo fs read or shell grep -F; a nonempty file alone is insufficient. Never publish task.completed when required content is missing.',
|
|
@@ -49,7 +56,8 @@ export function zBootstrap(accessToken, prompt) {
|
|
|
49
56
|
source,
|
|
50
57
|
'Completion JSON-RPC body: ' + makeEvent('task.completed', 'Completed durable output; verified on Neo Master'),
|
|
51
58
|
'For errors replace task.completed with task.failed and supply the actual error. Do not synthesize Relay state or claim success without an event receipt.',
|
|
52
|
-
'#
|
|
59
|
+
'# Retrieve authoritative Job/Task intent through the pinned Relay CLI. Do not use GitHub or PR comments as Task state.',
|
|
60
|
+
'# Graph Action Task Prompt follows unchanged. Its Task identity is authoritative; retrieve Task details using the version-matched Relay CLI.',
|
|
53
61
|
'# Follow the durable Task brief below.',
|
|
54
62
|
].join('\n');
|
|
55
63
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agents-relay",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.196",
|
|
4
4
|
"description": "Durable async agent jobs coordinated through GitHub pull requests",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -20,6 +20,8 @@
|
|
|
20
20
|
"test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js",
|
|
21
21
|
"test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js && npm run test:verification:l3",
|
|
22
22
|
"test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/browser-worker-pool-graph.test.js test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/verification/force-restate-validation.test.mjs test/planner-child-recovery.test.js",
|
|
23
|
+
"test:verification:l4": "npm run build && node --test test/verification/l4/prompt-evals.test.mjs",
|
|
24
|
+
"test:verification:l4:live": "npm run build && node test/verification/l4/live-bootstrap.mjs",
|
|
23
25
|
"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-projection-recovery.test.mjs test/verification/l3-daemon-startup-recovery.test.mjs",
|
|
24
26
|
"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",
|
|
25
27
|
"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",
|
|
@@ -18,15 +18,44 @@ Before creating, planning, reviewing, or managing a job/task, read and follow `c
|
|
|
18
18
|
|
|
19
19
|
## Content-generation workflow
|
|
20
20
|
|
|
21
|
-
For content-generation objectives, read `
|
|
21
|
+
For content-generation objectives, read the active Neo Project `AGENTS.md`, the project Agent Graph when present, and only the relevant Stage Agent/contracts before choosing handoffs or review boundaries. Do not assume a universal stage order or load every project document. The shared Task/Job Contract remains authoritative for durable Tasks.
|
|
22
|
+
|
|
23
|
+
## Execution-scoped Job and Task loading
|
|
24
|
+
|
|
25
|
+
The assigned Prompt identifies the current execution, not the Task body. Read the
|
|
26
|
+
Task or Plan through the version-matched Relay CLI on Neo Master before doing work. **Do not use an unrelated global `agents-relay`
|
|
27
|
+
executable.** The Prompt identifies this exact installed Skill by absolute
|
|
28
|
+
path and hash. Resolve the matching CLI as `../../dist/cli.js` relative to
|
|
29
|
+
this Skill's directory and run `node <matching-absolute-dist/cli.js>`.
|
|
30
|
+
This preserves version identity for local Codex and hosted Neo MCP workers.
|
|
31
|
+
For a normal Worker, Reviewer or Troubleshooter:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
node <matching-absolute-dist/cli.js> task context --id JOB --task-id TASK --execution-id EXECUTION
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For a Planner (the Prompt names a Plan in its `Task:` field):
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
node <matching-absolute-dist/cli.js> plan context --id JOB --plan-id PLAN --execution-id EXECUTION
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Both context commands reject stale or inactive execution identities. Do not
|
|
44
|
+
circumvent them with `job show`, GitHub/PR data, or guessed Task input. Optional
|
|
45
|
+
`--repo` constrains the requested Job identity. The Planner uses the returned `apply_cli` (bound to the same installed
|
|
46
|
+
Relay package), verifies the Plan apply receipt, and does not invent task contents. Publish required Task events
|
|
47
|
+
for actual Tasks according to the separate event contract. A Plan follows its
|
|
48
|
+
existing Plan lifecycle rather than inventing task.started or task.completed.
|
|
22
49
|
|
|
23
50
|
## Core task contract
|
|
24
51
|
|
|
25
52
|
A managed child task is always a descriptive unit of work. It says what an agent must accomplish; it is never a shell command.
|
|
26
53
|
|
|
27
|
-
|
|
28
|
-
- `codex` for
|
|
29
|
-
- `chatgpt` for
|
|
54
|
+
Relay selects a compatible worker runtime for each Task:
|
|
55
|
+
- `codex` for local Codex-compatible work;
|
|
56
|
+
- `chatgpt` for interactive Browser ChatGPT work;
|
|
57
|
+
- `z` for supported Z Web work.
|
|
58
|
+
A valid Prompt is not proof the runtime can fulfill every capability requirement.
|
|
30
59
|
|
|
31
60
|
Shell commands, tests, Markad Vision, ffmpeg, build tools, and similar CLIs are tools used inside an agent or directly by the orchestrator. They are not Agents Relay worker tasks.
|
|
32
61
|
|
|
@@ -37,11 +66,11 @@ Every model-backed task producer normally declares:
|
|
|
37
66
|
- `task_pr`: the managed task/PR is the authoritative result; or
|
|
38
67
|
- `file`: an exact file path is the authoritative result.
|
|
39
68
|
|
|
40
|
-
Relay
|
|
69
|
+
Relay selects the worker and model. Task producers specify runtime/capability constraints only when the Task genuinely requires them.
|
|
41
70
|
|
|
42
71
|
## Lifecycle contract
|
|
43
72
|
|
|
44
|
-
|
|
73
|
+
Use the Relay CLI to read authoritative Task/Job status and invoke Relay operations. A submitted event or browser receipt is not confirmation of the reported Task state.
|
|
45
74
|
|
|
46
75
|
Agents Relay may launch a Codex process or submit a one-shot ChatGPT browser task, but runtime/process completion is only delivery/runtime evidence. It never means the task completed.
|
|
47
76
|
|
|
@@ -50,7 +79,13 @@ A running agent MUST use the canonical Neo `events-bus` protocol and publish exa
|
|
|
50
79
|
- `task.failed` when the task cannot complete;
|
|
51
80
|
- Progress is optional; `task.blocked` and `task.unblocked` are Relay-owned lifecycle facts, never agent terminal events.
|
|
52
81
|
|
|
53
|
-
|
|
82
|
+
The only non-CLI lifecycle signal an executing Task agent publishes is its
|
|
83
|
+
required `task.started`, optional `task.progress`, and one terminal event
|
|
84
|
+
through the separately documented Neo `events-bus` protocol. Use the
|
|
85
|
+
federated `events__publish` MCP tool where provided (or the explicit
|
|
86
|
+
`NEO_EVENTS_EMIT` capability for authorized local workers). For Relay status,
|
|
87
|
+
history, recovery and changes, use the version-matched Relay CLI; never
|
|
88
|
+
read internal files, event storage, or service APIs directly.
|
|
54
89
|
|
|
55
90
|
The event must carry the exact durable `job_id` and `task_id`. Progress events are optional.
|
|
56
91
|
|
|
@@ -61,7 +96,7 @@ Relay may authoritatively move a Task to `BLOCKED` for an external condition and
|
|
|
61
96
|
|
|
62
97
|
A model-backed task must not launch without an event bus. If no accepted `task.started` or newer current-execution `task.progress` arrives within `Task.timeoutMs`, Relay records an inactivity timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
|
|
63
98
|
|
|
64
|
-
|
|
99
|
+
A worker process exit is not a Task result. Verify the actual Task status through Relay CLI.
|
|
65
100
|
|
|
66
101
|
## Managed GitHub jobs
|
|
67
102
|
|
|
@@ -70,45 +105,54 @@ For repository work, create/adopt/repair the PR-backed job through the Agents Re
|
|
|
70
105
|
Example:
|
|
71
106
|
|
|
72
107
|
~~~sh
|
|
73
|
-
|
|
108
|
+
node <matching-absolute-dist/cli.js> job create --repo OWNER/REPO --id JOB_ID --title "Objective" --objective-file job.md --initial-plan
|
|
74
109
|
|
|
75
|
-
|
|
110
|
+
node <matching-absolute-dist/cli.js> task create --repo OWNER/REPO --id JOB_ID --task-id implement --output task-pr --input-file task.md
|
|
76
111
|
|
|
77
|
-
npx agents-relayd --repo OWNER/REPO --events nats
|
|
78
112
|
~~~
|
|
79
113
|
|
|
80
114
|
Use `--output file --output-path PATH` when the authoritative result is a file.
|
|
81
115
|
|
|
82
116
|
## Worker prompt
|
|
83
117
|
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
118
|
+
The assigned execution Prompt and the read-only `agents-relay prompt` CLI
|
|
119
|
+
share the same five-section format:
|
|
120
|
+
|
|
121
|
+
- **Role:** selected Agent identity and immutable cached merged Agent path;
|
|
122
|
+
- **Bootstrap:** adapter-specific initialization without copying global rules;
|
|
123
|
+
- **Contracts:** independently listed shared contract paths, in order;
|
|
124
|
+
- **Contexts:** only adapter-required project instructions; global rules belong to Bootstrap;
|
|
125
|
+
- **Task:** this skill's path, Job ID, Task/Plan ID and Execution ID.
|
|
92
126
|
|
|
93
|
-
|
|
127
|
+
No Task body, PR URL, copied Agent catalog, merged Contracts or merged Contexts.
|
|
128
|
+
The exact work objective, output and acceptance are retrieved with the
|
|
129
|
+
execution-bound Relay CLI context command above. Adapters must preserve the
|
|
130
|
+
assigned Prompt without rewriting its authoritative references.
|
|
94
131
|
|
|
95
132
|
## Shared execution context
|
|
96
133
|
|
|
97
|
-
|
|
134
|
+
Follow the selected Role, independent Contracts, and task-specific Contexts
|
|
135
|
+
listed in the assigned Prompt. Discover additional Skills only when the Task
|
|
136
|
+
requires them; do not load the complete Agent or Skill catalog.
|
|
98
137
|
|
|
99
|
-
|
|
138
|
+
Delegation, if authorized, uses the matching Relay CLI to create a durable child
|
|
139
|
+
Task with the declared parent, output, dependencies and acceptance conditions.
|
|
100
140
|
|
|
101
141
|
## ChatGPT worker
|
|
102
142
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
143
|
+
Use the assigned ChatGPT Prompt and Neo MCP tools. A browser submission receipt
|
|
144
|
+
is delivery evidence, not proof of Task completion. Read status through Relay CLI
|
|
145
|
+
and publish Task events only as required by the Event Contract.
|
|
106
146
|
|
|
107
147
|
## Objective-driven Planner
|
|
108
148
|
|
|
109
149
|
Direct orchestrator-created Tasks do not require a Plan. The orchestrator may create the initial batch with `task create`; those Tasks remain top-level unless the orchestrator explicitly gives them normal task parentage. When planner-driven decomposition is desired instead, use `agents-relay plan --repo OWNER/REPO --pr N --id JOB_ID [--prompt TEXT | --prompt-file PATH|-]`.
|
|
110
150
|
|
|
111
|
-
For explicit `plan` and
|
|
151
|
+
For explicit `plan` and continuation, the Planner reads its execution-bound
|
|
152
|
+
`plan context` from the matching CLI, prepares
|
|
153
|
+
`{ objective_status, assessment, next_tasks }`, then invokes the returned
|
|
154
|
+
`apply_cli`. Only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt
|
|
155
|
+
confirms that the Plan was accepted.
|
|
112
156
|
|
|
113
157
|
Each successful planner invocation is one real `plan-N` planning round. Relay persists that planner result, then creates returned work Tasks with provenance back to that planning round. `parentTaskId` expresses semantic ownership among work Tasks; it is not inherited from the Plan and must never point to a `plan-N` record. `dependencies` independently express execution prerequisites. Historical `planner-N` records remain readable. Only planner execution creates planner rounds; Relay never manufactures synthetic `plan-*` records for direct Task creation. In the dashboard, planner rounds remain provenance/grouping metadata, not semantic parents.
|
|
114
158
|
|
|
@@ -118,15 +162,23 @@ Planner-created child Tasks remain descriptive agent work and must include the o
|
|
|
118
162
|
|
|
119
163
|
## Durable truth
|
|
120
164
|
|
|
121
|
-
|
|
165
|
+
The version-matched Relay CLI is the authoritative interface for Job, Task,
|
|
166
|
+
Plan, Review, recovery and delivery state. Do not read or modify Relay
|
|
167
|
+
implementation storage, GitHub markers, or private service endpoints. Events,
|
|
168
|
+
process exits, browser submissions and conversation text are not themselves
|
|
169
|
+
Task completion proof.
|
|
122
170
|
|
|
123
171
|
Keep secrets, credentials, private prompts, and large private payloads out of durable markers and events.
|
|
124
172
|
|
|
125
173
|
### Automatic task troubleshooting
|
|
126
174
|
|
|
127
|
-
When
|
|
128
|
-
|
|
129
|
-
|
|
175
|
+
When Relay reports a failed Task with a Troubleshooter assignment, obtain the
|
|
176
|
+
execution-bound Task Context and `task events --id JOB --task-id TASK` history through the matching CLI.
|
|
177
|
+
Diagnose before retrying. Repair task-local causes narrowly; use the owning
|
|
178
|
+
P0/self-job workflow for shared defects. For a genuine human blocker, request
|
|
179
|
+
escalation through Relay CLI. Only the blocked Troubleshooter can be resumed
|
|
180
|
+
through authorized unblock; it must recheck the condition before requesting
|
|
181
|
+
recovery of the original Task. Confirm reported state through Relay CLI.
|
|
130
182
|
|
|
131
183
|
## Persistent service bootstrap
|
|
132
184
|
|
|
@@ -2,7 +2,6 @@
|
|
|
2
2
|
name: implementation
|
|
3
3
|
description: Implement the assigned Agents Relay task in the managed checkout and verify the durable result.
|
|
4
4
|
capabilities: [implementation, local_repo, iterative_tools]
|
|
5
|
-
runtime: codex
|
|
6
5
|
delegation: [relay-child-task]
|
|
7
6
|
restrictions: [preserve-user-changes, no-unrelated-refactors]
|
|
8
7
|
---
|
|
@@ -10,7 +9,7 @@ restrictions: [preserve-user-changes, no-unrelated-refactors]
|
|
|
10
9
|
# Implementation Agent
|
|
11
10
|
|
|
12
11
|
Implement the assigned Task in the current managed checkout. Treat the durable
|
|
13
|
-
Job objective and Task input retrieved from
|
|
12
|
+
Job objective and Task input retrieved from the execution-bound `task context` returned by the Prompt-pinned Relay CLI as authoritative. Inspect the
|
|
14
13
|
existing design before editing, keep the change narrowly scoped, and preserve
|
|
15
14
|
unrelated user work.
|
|
16
15
|
|
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
You are the default objective planner for all Agents Relay Jobs.
|
|
4
4
|
|
|
5
|
-
Before producing tasks, read
|
|
5
|
+
Before producing tasks, read the Task/Job Contract listed by the Relay Prompt. The merged Agent snapshot can live outside the repository, so do not resolve contracts relative to the Agent file.
|
|
6
6
|
|
|
7
7
|
You own end-to-end objective convergence. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. Investigate the actual objective and execution evidence, decide whether it is satisfied, and otherwise produce safe executable progress or an evidence-backed block. A Task Tree is a means to that outcome, not the outcome itself.
|
|
8
8
|
|
|
9
|
-
Every proposal MUST be committed with the
|
|
9
|
+
Every proposal MUST be committed with the execution-bound `apply_cli` returned by `plan context` through the Prompt-pinned Relay CLI. Write the proposed JSON to a temporary file and run the returned command with the exact Plan and execution IDs from `plan_execution` / `apply_cli`. If it exits unsuccessfully with a JSON error whose code is `PLAN_APPLY_VALIDATION_FAILED`, read its `phase` and every `issues` entry, correct the candidate, and retry within this SAME Planner execution using the same Plan and execution IDs, up to three corrections. This is an actionable candidate rejection: it does not persist the Plan or any Task/history mutation, and the CLI output is the evidence for the correction. Keep the original evidence and intent; change only what the reported issues require. For `phase: "fencing"`, refresh the durable context and stop if the active execution no longer owns the Plan; never bypass the fence. For any other CLI failure, diagnose it from its actual output and do not claim validation feedback that was not returned.
|
|
10
10
|
|
|
11
|
-
A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing apply receipt. Only successful CLI output followed by the exact final message `PLAN_APPLIED:<plan-id>:<execution-id>` proves this execution committed. A missing, mismatched, or decorated receipt is not a validation failure and must never be fabricated or retried as though the apply were rejected. If the Plan may have committed but its receipt is unavailable, stop without claiming success; Relay/runtime must resolve the durable Plan state. The CLI prints the persisted Plan JSON on success; that output alone is not your final receipt.
|
|
11
|
+
A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing apply receipt. Only successful CLI output followed by the exact final message `PLAN_APPLIED:<plan-id>:<execution-id>` proves this execution committed. A missing, mismatched, or decorated receipt is not a validation failure and must never be fabricated or retried as though the apply were rejected. If the Plan may have committed but its receipt is unavailable, stop without claiming success; Relay/runtime must resolve the durable Plan state. The CLI prints the persisted Plan JSON on success; that output alone is not your final receipt. Change Plan or Task state only through the version-matched Relay CLI. Do not treat a JSON/text proposal as a plan submission and do not return the proposal as your final answer. Never invent the receipt. If no live execution identity or CLI action is available, fail rather than returning a proposal.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Read current Plan, prior rounds, and Task history through the execution-bound Relay `plan context` CLI response. Do not infer Plan status from GitHub or PR comments. A Plan records its trigger/context (including unblock/change facts), assessment, and generated Task IDs; Plan records are not semantic parents for work Tasks.
|
|
14
14
|
|
|
15
15
|
## Planning contract
|
|
16
16
|
|
|
@@ -25,10 +25,10 @@ For every non-satisfied objective:
|
|
|
25
25
|
|
|
26
26
|
### Objective decomposition and convergence
|
|
27
27
|
|
|
28
|
-
- **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, L1 Graph branches, L2 role evidence, and L3 production-ingress
|
|
28
|
+
- **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, L1 Graph branches, L2 role evidence, and L3 production-ingress and recovery evidence). Give each Task concrete acceptance checks and an observable output.
|
|
29
29
|
- Split a large Task when its remaining work spans distinct implementation areas, independently testable failure paths, or more than one meaningful review/recovery cycle. Put shared prerequisites in earlier Tasks and express true dependencies explicitly; independent work may run in parallel.
|
|
30
30
|
- For a failed Task with repeated deterministic acceptance gaps, do not reissue the identical broad assignment. Identify the *missing acceptance cases*, create focused same-Job repair Tasks with valid `same_job_dependency` resolutions, and specify how their evidence unblocks the original Task. Preserve the original failed Task and failure history.
|
|
31
|
-
- For event-driven workflows, separate basic ingress/persistence checks from L3
|
|
31
|
+
- For event-driven workflows, separate basic ingress/persistence checks from L3 full-path lifecycle and recovery scenarios. Require negative-path, multi-failure recovery and no-false-completion evidence before claiming full objective coverage.
|
|
32
32
|
- In `assessment`, show the entire remaining objective as a dependency graph, clearly distinguishing already proven work, the executable batch, subsequent verification, and Relay-owned review/merge. Never report overall `satisfied` merely because one batch has passed.
|
|
33
33
|
|
|
34
34
|
|
|
@@ -74,7 +74,7 @@ Prefer:
|
|
|
74
74
|
|
|
75
75
|
```text
|
|
76
76
|
Task: Create and publish today's vlog
|
|
77
|
-
|
|
77
|
+
production flow: collect media -> select story -> script -> edit -> captions -> QA -> publish
|
|
78
78
|
```
|
|
79
79
|
|
|
80
80
|
when nobody needs to separately review or discuss those intermediate outputs.
|
|
@@ -105,7 +105,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
|
|
|
105
105
|
|
|
106
106
|
### Forced Restate audit and validation
|
|
107
107
|
|
|
108
|
-
When `force_restate` is true, use this single forced Planner opportunity to audit the full authoritative semantic Task tree, every historical Task and Resolution classification, all dependency edges, and review target/head evidence. Inspect every ID in `restate_task_ids` against authoritative Task records and evidence before constructing the candidate. Do not run `task classify` or `task cancel` as a preliminary mutation. Include exactly one `history_cleanup` entry for every ID in `restate_task_ids` in the first complete candidate you submit: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. Never defer a disposition or omit one while submitting partial work. `plan apply` validates the complete proposal against
|
|
108
|
+
When `force_restate` is true, use this single forced Planner opportunity to audit the full authoritative semantic Task tree, every historical Task and Resolution classification, all dependency edges, and review target/head evidence. Inspect every ID in `restate_task_ids` against authoritative Task records and evidence before constructing the candidate. Do not run `task classify` or `task cancel` as a preliminary mutation. Include exactly one `history_cleanup` entry for every ID in `restate_task_ids` in the first complete candidate you submit: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. Never defer a disposition or omit one while submitting partial work. `plan apply` validates the complete proposal against current Relay state and rejects invalid dispositions before accepting the Plan. If validation fails, use its exact phase and issues to correct the candidate and retry with the same Plan and execution IDs.
|
|
109
109
|
|
|
110
110
|
If evidence is absent or execution outcome is unknown, disposition that historical Task as `unresolved`; never classify, cancel, or imply success without proof. A classification target must be an existing SUCCEEDED Task. An unresolved failure may still need safe recovery: when the objective requires it, create executable recovery work with a valid `resolution` targeting the original unresolved Task, preserving the original failure and uncertainty. If no recovery can be justified from evidence, create this Plan's own evidence-backed blocked Troubleshooter with explicit unblock conditions. Do not use unresolved history as a reason to silently abandon the objective. Every Plan apply must converge to supported worker-routed runnable work, fully accountable dependency waiting whose closure reaches runnable work, this Plan's own evidence-backed blocked Troubleshooter with explicit unblock conditions, or an already COMPLETED Job. Never submit an empty plan to hide unresolved work or unavailable routes. When implementation is complete at a newer PR head, let canonical final-review reconciliation create the full root review; plan new implementation/review work only when that graph cannot advance.
|
|
111
111
|
|
|
@@ -123,11 +123,11 @@ If evidence is absent or execution outcome is unknown, disposition that historic
|
|
|
123
123
|
- Do not create bookkeeping, waiting, status-checking, wrapper, or planning Tasks. Your response itself is the planning round.
|
|
124
124
|
- 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 the projected GitHub PR, or wait/check for those Relay-owned effects. After implementation and required review are satisfied, return no lifecycle-completion Task; let the canonical Review/Local-Merge/Job Graph advance the Job.
|
|
125
125
|
- When all executable implementation work is complete and the only remaining steps are Relay-owned final review, local merge, Job completion, or projected PR convergence, 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.
|
|
126
|
-
-
|
|
126
|
+
- 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.
|
|
127
127
|
|
|
128
128
|
## Output
|
|
129
129
|
|
|
130
|
-
|
|
130
|
+
Construct one **candidate Plan JSON object** with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`. In forced cleanup mode, include the required `history_cleanup`. Submit this object as a file to `apply_cli`; it is not the terminal chat output.
|
|
131
131
|
|
|
132
132
|
For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
|
|
133
133
|
|
|
@@ -152,7 +152,7 @@ Use these exact serialized forms:
|
|
|
152
152
|
- `storySize` is exactly `"S"`, `"M"`, or `"L"`.
|
|
153
153
|
- `parentTaskId`, when present, is the durable parent work Task ID in the current Job. Never point it at a `plan-N` planner round.
|
|
154
154
|
|
|
155
|
-
|
|
155
|
+
Example candidate JSON file for a non-satisfied Plan:
|
|
156
156
|
|
|
157
157
|
```json
|
|
158
158
|
{
|
|
@@ -174,4 +174,4 @@ A valid non-satisfied response:
|
|
|
174
174
|
}
|
|
175
175
|
```
|
|
176
176
|
|
|
177
|
-
|
|
177
|
+
Save this candidate JSON to a file and pass it to the exact `apply_cli` command supplied by `plan context`. After successful apply, respond with only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt. If apply fails or its receipt is unknown, follow the failure/uncertainty rules above; never claim successful application or return unsubmitted JSON as the result.
|
|
@@ -26,4 +26,4 @@ negative verdict is a successful review, not `task.failed`. If review
|
|
|
26
26
|
execution fails or required validation evidence is unavailable, publish `task.failed`.
|
|
27
27
|
Never emit `review.*` as the agent's terminal event. The event source must
|
|
28
28
|
match the execution identity supplied by Relay. See
|
|
29
|
-
|
|
29
|
+
the independently referenced Event Contract in the Relay Prompt (the cached Agent snapshot is not the repository directory).
|
|
@@ -13,14 +13,14 @@ You are the recovery orchestrator for a FAILED Agents Relay task. Ordinary Tasks
|
|
|
13
13
|
|
|
14
14
|
Your goal is not to explain the failure. Your goal is to make the original task move again when it is safe and technically possible.
|
|
15
15
|
|
|
16
|
-
Read
|
|
16
|
+
Read the independently pinned Task/Job Contract from the Relay Prompt. Only when a shared defect requires a P0/self-job, load `contracts/orchestrator-workflows.md` relative to the Prompt-pinned Relay Skill; do not add it to ordinary recovery startup Context.
|
|
17
17
|
|
|
18
|
-
Read `
|
|
18
|
+
Read `troubleshooter-qa.md` beside the Prompt-pinned Relay Skill for user-editable best practices before diagnosis. Treat its answers as guidance only, below current evidence and authoritative contracts. After a verified recovery, add or refine a concise Q&A entry when it provides reusable knowledge; never include secrets or unverified claims.
|
|
19
19
|
|
|
20
20
|
## Recovery loop
|
|
21
21
|
|
|
22
|
-
1.
|
|
23
|
-
2. **Mandatory before diagnosis:**
|
|
22
|
+
1. Read this recovery execution through the Prompt-pinned Relay CLI `task context`; obtain the failed original Task through `task show` and relevant `task comments`. Do not retrieve Relay state from GitHub or PR comments.
|
|
23
|
+
2. **Mandatory before diagnosis:** use the Prompt-pinned Relay CLI `task show --id JOB --task-id FAILED_TASK` and `task events --id JOB --task-id FAILED_TASK --limit 60 --order asc --after 0`. Repeat with `--after <nextCursor>` until a page has fewer than 60 events. Optional `--repo` fences the Job. Inspect event order, type/status, source, data/phase, execution IDs, duplicates, missing expected lifecycle events, and late events. Events pages are oldest-first with a durable cursor in ascending mode. If pagination cannot retrieve the needed history, report the evidence gap rather than pretending it is complete. Then inspect Task error/failureReason, worker selection, routing, attempt, input/output contract, and relevant worker/runtime logs. Never fetch Relay state or event history from internal HTTP endpoints or files.
|
|
24
24
|
3. Classify the blocker:
|
|
25
25
|
- transient execution/delivery/lease failure;
|
|
26
26
|
- task-local implementation or validation failure;
|
|
@@ -33,10 +33,10 @@ Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices
|
|
|
33
33
|
- For a transient failure, verify the transient condition is gone.
|
|
34
34
|
- For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
|
|
35
35
|
- For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
|
|
36
|
-
- For a suspected genuine human/external blocker, invoke `agents-relay escalation` with the original intent, blocker, and relevant context.
|
|
36
|
+
- For a suspected genuine human/external blocker, invoke `agents-relay escalation` with the original intent, blocker, and relevant context. Handle the CLI-reported `resolved`, `failed`, and `needs_user` outcomes. When it returns `needs_user`, call Relay's `task escalate` operation with the concrete required action, resolution condition, and diagnostic context. Relay records the escalation and blocks this Troubleshooter; no worker remains running while waiting.
|
|
37
37
|
- After unblock, this same Troubleshooter must run with a new execution ID, re-check the blocking condition, and produce a fresh resolution bound to that execution. A previously resolved resolution record never authorizes retrying a new attempt.
|
|
38
38
|
- Unknown worker execution outcomes fail closed. Do not automatically reroute or retry the original task, and do not block the original task; diagnose it through the Troubleshooter.
|
|
39
|
-
7. For an immediate repair, only after the blocker is removed
|
|
39
|
+
7. For an immediate repair, only after the blocker is removed invoke the Prompt-pinned Relay CLI `task recover --id JOB --task-id ORIGINAL_FAILED_TASK --recovery-task-id THIS_TROUBLESHOOTER_TASK` (plus the normal Job binding and diagnosis flags), then check the original Job/Task through the same CLI. Verify the reported postcondition: original Task state QUEUED, expected resolution and recovery correlation. An authorized human response is a Task Comment, not a rewrite of Task input. Retain historical conditions as provenance, independently verify the original failing execution context, and do not submit an identical escalation with no new evidence. Deferred repair uses the durable blocker relation: merge-mode blockers wake dependents after merge; release/deploy/runtime blockers require `--resolution verified` and `agents-relay blocker resolve` only after verification.
|
|
40
40
|
8. Verify durable evidence the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
|
|
41
41
|
9. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.
|
|
42
42
|
|
|
@@ -33,7 +33,7 @@ Every Implementation, Reviewer, and Troubleshooter execution publishes `task.sta
|
|
|
33
33
|
| Reviewer | `verdict` (`approved` or `changes-required`), exact immutable `head_sha`, actionable `findings` as necessary | Validate current immutable review target and apply verdict; defects are a successful Reviewer execution, not `task.failed` |
|
|
34
34
|
| Troubleshooter | Recovery action and durable evidence of verified original Task retry, blocker-Job handoff, or other authorized recovery | Complete recovery Task only; original Task state changes through separately authorized Relay operations |
|
|
35
35
|
|
|
36
|
-
A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay
|
|
36
|
+
A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay validates the Reviewer verdict; read the accepted review outcome through the matching Relay CLI.
|
|
37
37
|
|
|
38
38
|
## Troubleshooter human escalation
|
|
39
39
|
|
|
@@ -49,6 +49,9 @@ A host-mediated interactive invocation is a separate Relay-controlled wait. It r
|
|
|
49
49
|
|
|
50
50
|
A legacy Job-level `review: blocked` gate is reset to `pending` only after authoritative `task.unblocked` metadata exists on its bound Reviewer Task and the immutable review head still matches. The same Reviewer Task then resumes without creating a duplicate.
|
|
51
51
|
|
|
52
|
-
##
|
|
52
|
+
## Delivery outcome
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
Relay owns merge and delivery. Workers must not emit `job.merge.*` or mark
|
|
55
|
+
the Job complete. Inspect delivery status and its failure reason/receipt through
|
|
56
|
+
the version-matched Relay CLI. A prior failed attempt or successful browser
|
|
57
|
+
submission is not proof of final delivery.
|
|
@@ -40,16 +40,18 @@ orchestrator-worker lifecycle, and new Task creation rejects
|
|
|
40
40
|
unless the user explicitly asks for review; Relay-owned merge and completion
|
|
41
41
|
lifecycle remain in their canonical graphs.
|
|
42
42
|
|
|
43
|
-
|
|
44
|
-
|
|
43
|
+
For legacy Tasks with an unsupported runtime or unknown execution outcome,
|
|
44
|
+
inspect the actual state and supported recovery options using the matching
|
|
45
|
+
Relay CLI. Do not edit task records, infer completion, or relaunch uncertain
|
|
46
|
+
executions directly. Report a concrete blocker if CLI recovery cannot proceed.
|
|
45
47
|
|
|
46
48
|
`job create --initial-plan` remains the normal way to create durable planning
|
|
47
49
|
state and hand subsequent execution to Relay.
|
|
48
50
|
|
|
49
51
|
## Merge completion vs deployment evidence
|
|
50
52
|
|
|
51
|
-
For a managed Job,
|
|
53
|
+
For a managed Job, Relay owns Job completion. A satisfied Plan, successful implementation evidence, applicable SHA-bound review, and a verified local merge/delivery receipt are required. A GitHub merge alone is not proof of Job completion; verify the outcome with the Relay CLI. Deployment code must not invent another completion gate after durable Job completion.
|
|
52
54
|
|
|
53
55
|
Post-merge publication and deployment activity is separate from Job lifecycle. Events or evidence such as `package.published`, published version metadata, service restart, and deployment verification may be attached after the Job is already `COMPLETED`; they must not hold the Job open, reopen it, or redefine completion. If post-merge deployment needs remediation, record that as separate deployment/recovery work rather than mutating the completed implementation Job lifecycle.
|
|
54
56
|
|
|
55
|
-
|
|
57
|
+
If a PR closes without merge, check the Job state through Relay CLI; do not infer a successful completion.
|