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
|
@@ -6,7 +6,7 @@ This contract is the shared protocol for every component that creates, schedules
|
|
|
6
6
|
|
|
7
7
|
Job objectives and Task inputs are **Markdown** and are durable execution context, not short labels. Use Mermaid where a diagram materially explains a workflow, state model, architecture, dependency graph, relationship, or other visual structure. **Mermaid-first applies to that explanation/section, not to the entire Job objective or Task input.** Put the diagram before the prose that explains that visual model, but keep normal document structure: start with the goal/context when that is what the reader needs first. Do not force a Mermaid block at the top of every objective/input, and do not add decorative or redundant diagrams when Markdown is clearer.
|
|
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
11
|
For long-form content, use files instead of shell-quoted arguments:
|
|
12
12
|
|
|
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
|
|
|
15
15
|
|
|
16
16
|
When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Use `job create` with standalone objective Markdown, or `job adopt` for an existing PR when authorized. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
|
|
19
19
|
|
|
20
20
|
## Task producers
|
|
21
21
|
|
|
@@ -34,12 +34,10 @@ A later Planner round must inspect the existing semantic tree and attach review,
|
|
|
34
34
|
|
|
35
35
|
A Task input records **what is known and what has already been decided before execution**. A Task result records **what execution discovered and what was actually done**.
|
|
36
36
|
|
|
37
|
-
After creation, keep `Task.input` stable as the objective and initial
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
resolution
|
|
41
|
-
the durable idempotent projection outbox. Comments supplement current state and
|
|
42
|
-
never replace `Task.resolution` or `Task.escalation`.
|
|
37
|
+
After creation, keep `Task.input` stable as the objective and initial
|
|
38
|
+
evidence. Use the Relay CLI to read or append Task Comments and to request
|
|
39
|
+
resolution/escalation changes. Comments are history; the current
|
|
40
|
+
`Task.resolution` and `Task.escalation` are obtained through the CLI.
|
|
43
41
|
|
|
44
42
|
Task input should include, as applicable:
|
|
45
43
|
|
|
@@ -62,7 +60,7 @@ Task results should also include, as applicable:
|
|
|
62
60
|
|
|
63
61
|
- **deviations** from any proposed or required solution, with the reason;
|
|
64
62
|
- **validation** showing how the result was verified;
|
|
65
|
-
- relevant changed files, commits,
|
|
63
|
+
- relevant changed files, commits, artifacts, CLI receipts, or remaining issues.
|
|
66
64
|
|
|
67
65
|
This is a worker result-content contract, not a requirement for dedicated `rootCause` / `solution` schema fields. Workers may satisfy it in normal durable result prose unless a Job defines a stricter structured output contract.
|
|
68
66
|
|
|
@@ -76,12 +74,12 @@ Every artifact-changing implementation worker follows the shared [worker self-re
|
|
|
76
74
|
|
|
77
75
|
`Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. `BLOCKED` is exclusive to Tasks whose `agentName` is exactly `troubleshooter`; ordinary Tasks never enter `BLOCKED` or an `UNBLOCKED` lifecycle state. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
|
|
78
76
|
|
|
79
|
-
The Job owns the meaning of the tag. Its
|
|
77
|
+
The Job owns the meaning of the tag. Its Job-defined tag contract declares a human-readable `description` explaining when workers should set it, allowed values, and their display strings:
|
|
80
78
|
|
|
81
79
|
```json
|
|
82
80
|
{
|
|
83
81
|
"tag": {
|
|
84
|
-
"description": "L3 verification outcome. Set pass only after
|
|
82
|
+
"description": "L3 verification outcome. Set pass only after the required recovery checks pass; otherwise set fail.",
|
|
85
83
|
"values": {
|
|
86
84
|
"pass": "✅",
|
|
87
85
|
"fail": "❌"
|
|
@@ -90,7 +88,7 @@ The Job owns the meaning of the tag. Its trusted Job marker declares a human-rea
|
|
|
90
88
|
}
|
|
91
89
|
```
|
|
92
90
|
|
|
93
|
-
A worker does **not** edit
|
|
91
|
+
A worker does **not** edit Relay state or PR markers directly. When the Job defines a tag and the tag applies to the work just performed, the worker reports one allowed durable value in the canonical terminal event as `data.tag`:
|
|
94
92
|
|
|
95
93
|
```json
|
|
96
94
|
{
|
|
@@ -102,7 +100,7 @@ A worker does **not** edit the Task marker directly. When the Job defines a tag
|
|
|
102
100
|
}
|
|
103
101
|
```
|
|
104
102
|
|
|
105
|
-
Relay validates `data.tag` against `Job.tag.values`.
|
|
103
|
+
Relay validates `data.tag` against `Job.tag.values`. Check the accepted tag and Task state through the Relay CLI; lifecycle status and Job-defined tag are independent:
|
|
106
104
|
|
|
107
105
|
```json
|
|
108
106
|
{
|
|
@@ -121,8 +119,7 @@ For a validation Job, for example, the Job defines `pass -> ✅` and `fail ->
|
|
|
121
119
|
### Task resolution classifications
|
|
122
120
|
|
|
123
121
|
`Task.resolutionClassification` is durable diagnostic metadata, separate from
|
|
124
|
-
`Task.state` and the recovery `Task.resolution` path. The
|
|
125
|
-
Resolution Graph and `task classify` CLI action may classify a known FAILED
|
|
122
|
+
`Task.state` and the recovery `Task.resolution` path. The `task classify` CLI action may classify a known FAILED
|
|
126
123
|
work Task as `superseded` or `invalid`; each record requires a different
|
|
127
124
|
durable target Task, evidence, and reason. Classification never changes the
|
|
128
125
|
FAILED lifecycle state, execution history, or result and never proves success.
|
|
@@ -143,7 +140,11 @@ SHA-bound final reviewer. For example, `video-director + market + style ->
|
|
|
143
140
|
review-chair -> unified revision plan` is a project pattern, not a hard-coded
|
|
144
141
|
Relay reviewer list.
|
|
145
142
|
|
|
146
|
-
Every Job is objective-driven. After a
|
|
143
|
+
Every Job is objective-driven. After a Task batch settles, Relay may create
|
|
144
|
+
further Plan rounds until the current Plan reports `objective_status: satisfied`.
|
|
145
|
+
A satisfied Plan alone is not Job completion: accepted implementation
|
|
146
|
+
evidence, immutable review when required, and verified delivery must still
|
|
147
|
+
be confirmed through the Relay CLI.
|
|
147
148
|
|
|
148
149
|
A newly created zero-task DRAFT Job waits for explicit initial planning (`plan` or `--initial-plan`) or direct work creation; this is only a start gate, not a distinct execution mode. Failed or blocked Tasks require durable Troubleshooter/owner recovery and never allow a fabricated completion. Duplicate events and daemon restarts must not create duplicate Plan rounds.
|
|
149
150
|
|
|
@@ -164,7 +165,7 @@ This is a strong execution boundary:
|
|
|
164
165
|
|
|
165
166
|
For example, a `neo-build-log` episode whose output is `runs/2026-10-02/package.md` executes in the canonical `neo/neo-build-log` project directory, and its review/render/publish descendants see the same `runs/2026-10-02/` tree.
|
|
166
167
|
|
|
167
|
-
Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task
|
|
168
|
+
Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task must verify the current target/head at execution time using the Relay CLI and source evidence, unless the objective explicitly requires the earlier immutable target.
|
|
168
169
|
|
|
169
170
|
When success depends on the actual current UI, browser state, store listing, runtime state, or another externally observable surface, the Task contract must require fresh evidence from that real current surface. Reusing an existing screenshot, prepared asset, cached observation, or older evidence is valid only when the Job explicitly permits it.
|
|
170
171
|
|
|
@@ -182,11 +183,13 @@ forbids it.
|
|
|
182
183
|
|
|
183
184
|
`dependencies` describe normal DAG ordering. An unmet dependency keeps ordinary work in `DRAFT`; dispatchable work is `QUEUED`. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay releases dependent work when its prerequisites succeed. Worker, platform, semantic, and unknown-outcome failures are `FAILED`. Unknown worker outcome fails closed and never justifies rerouting. Only a Troubleshooter waiting for an authoritative human response may become `BLOCKED`.
|
|
184
185
|
|
|
185
|
-
A BLOCKED Troubleshooter
|
|
186
|
+
A BLOCKED Troubleshooter resumes only after an authorized Relay CLI unblock with a human response. The CLI must report that same Troubleshooter moving from `BLOCKED` to `QUEUED`. The queued Troubleshooter must execute again, verify the condition from fresh evidence, and issue a fresh resolution before Relay may retry or replan the original FAILED Task. Prior `resolved` metadata never authorizes another attempt. Historical failures must not be silently reclassified as success.
|
|
186
187
|
|
|
187
|
-
|
|
188
|
+
Do not create or infer an `UNBLOCKED` state for ordinary Tasks.
|
|
188
189
|
|
|
189
|
-
|
|
190
|
+
Read Plan rounds, current status, trigger/context, assessment and generated
|
|
191
|
+
Task IDs via the execution-bound `plan context` CLI command. PR comments are
|
|
192
|
+
not a source for Plan execution state.
|
|
190
193
|
|
|
191
194
|
A blocker Job owns reverse `unblocks` references. When it resolves, Relay releases matching dependency-waiting Tasks through their ordinary DRAFT/QUEUED path. It cannot unblock ordinary work or resume a Troubleshooter without the authoritative response flow.
|
|
192
195
|
|
|
@@ -1,36 +1,24 @@
|
|
|
1
|
-
# Task Failure Recovery and Human Escalation —
|
|
1
|
+
# Task Failure Recovery and Human Escalation — Current Contract
|
|
2
2
|
|
|
3
|
-
**Status:** Current recovery contract.
|
|
3
|
+
**Status:** Current recovery contract. Query Task state, recovery status, and comments through the matching Relay CLI.
|
|
4
4
|
|
|
5
5
|
## Principles and ownership
|
|
6
6
|
|
|
7
7
|
- **Events Bus is neutral.** Its generic event envelope consists of event identity, type, time, and opaque client-defined data (plus any transport metadata needed by the bus). It must not understand Relay Jobs, Tasks, roles, or verdicts.
|
|
8
|
-
- **One agent Task event contract** applies to Implementation, Reviewer, and Troubleshooter: optional progress
|
|
8
|
+
- **One agent Task event contract** applies to Implementation, Reviewer, and Troubleshooter: `task.started`, optional `task.progress`, then exactly one agent terminal event, `task.completed` or `task.failed`. Role-specific results belong in `data`. A review with findings is a *completed* review, not a failed agent execution.
|
|
9
9
|
- **`task.blocked` and `task.unblocked` are authoritative Relay lifecycle transitions**, not ordinary agent terminal events. A human may authorize unblocking a Troubleshooter but does not directly unblock the failed original Task.
|
|
10
10
|
- **Troubleshooter owns diagnosis and recovery decisions.** It chooses technical repair/retry, blocker-Job dependency, or human escalation. There is no separate Escalator agent.
|
|
11
|
-
- **Relay owns transitions and dispatch.** Troubleshooter requests authorized operations
|
|
11
|
+
- **Relay owns transitions and dispatch.** Troubleshooter requests authorized operations through Relay CLI, then checks the CLI response and fresh Task Context. Event transport acceptance alone is not confirmation of a Task transition.
|
|
12
12
|
- Preserve the original failure, exact execution correlation, evidence, and idempotency throughout retries and resumes.
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## External recovery interface
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
T["Troubleshooter"] --> U
|
|
23
|
-
U --> B["Neutral Events Bus"]
|
|
24
|
-
B --> C["Relay event consumer"]
|
|
25
|
-
C --> S["Validate execution identity and role-specific data"]
|
|
26
|
-
S --> W["Relay workflow engine / reconciler"]
|
|
27
|
-
W --> D[("Durable Task and Job state")]
|
|
28
|
-
W --> R["Execution / recovery / human-interaction operations"]
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
- Agents publish `task.completed` or `task.failed` as terminal execution outcomes; Reviewer verdicts and Troubleshooter recovery evidence are results inside `data`.
|
|
32
|
-
- `task.blocked` / `task.unblocked` describe Relay-authorized state changes, not a third agent terminal outcome.
|
|
33
|
-
- Transport does not interpret verdicts, execution IDs, blocker relations, or recovery decisions.
|
|
16
|
+
Task agents publish their required Task events via the canonical Neo Events Bus
|
|
17
|
+
protocol. All Relay status reads and authorized changes use the Prompt-pinned
|
|
18
|
+
Relay CLI (`task context`, `task show`, `task events`, `task recover`,
|
|
19
|
+
`task escalate`, or other documented commands as appropriate). Event transport
|
|
20
|
+
acceptance does not confirm a Task transition. Never access Relay backing
|
|
21
|
+
storage, PR markers, or private HTTP endpoints to infer or change state.
|
|
34
22
|
|
|
35
23
|
## Overall flow — Task outcome and recovery branches
|
|
36
24
|
|
|
@@ -78,7 +66,7 @@ flowchart TD
|
|
|
78
66
|
```
|
|
79
67
|
|
|
80
68
|
1. Original agent reports `task.failed` with useful diagnostic `data`; Relay durably records `FAILED`.
|
|
81
|
-
2.
|
|
69
|
+
2. Relay assigns a correlated Troubleshooter Task. Troubleshooter examines durable Task history and technical evidence before choosing a resolution.
|
|
82
70
|
3. For a technical remedy, Troubleshooter repairs/validates, requests authorized retry, confirms the original Task requeued, and completes **its own** Task.
|
|
83
71
|
4. For a blocker Job, Troubleshooter registers a durable dependency, then completes **its own** Task; the dependency mechanism later wakes the original Task after verified resolution.
|
|
84
72
|
5. Only a **real user action** calls for human escalation (Flow 2). Missing credentials that can be found or configured automatically, crashes, and retries are Troubleshooter work, not escalation.
|
|
@@ -127,21 +115,13 @@ flowchart TD
|
|
|
127
115
|
|
|
128
116
|
`BLOCKED` is a durable Task state and `task.blocked` may be published by Relay as a state-change fact; it is **not** an agent-selected terminal outcome. Human unblocking resumes the blocked Troubleshooter Task rather than terminating or re-creating its recovery responsibility.
|
|
129
117
|
|
|
130
|
-
## Required follow-up implementation alignment
|
|
131
|
-
|
|
132
|
-
- Align `skills/agents-relay/SKILL.md` and role instructions with the two agent terminal events; remove agent-directed `task.blocked` emission.
|
|
133
|
-
- Align escalation graph, CLI, reconciler, and unblock commands so human intervention blocks **Troubleshooter**, not the original failed Task; preserve the original failure and correlated recovery context.
|
|
134
|
-
- Ensure the blocked Troubleshooter can resume after an authorized human unblock rather than being treated as a finished terminal execution.
|
|
135
|
-
- Add integrated checks: technical retry, blocker-Job handoff, human request/block, human unblock/resume, failed verification/re-escalation, stale/duplicate responses, and correct original-Task retry.
|
|
136
|
-
|
|
137
118
|
## Durable recovery history
|
|
138
119
|
|
|
139
120
|
`Task.input` remains the stable objective and original evidence. `Task.resolution` and
|
|
140
121
|
`Task.escalation` remain the current authoritative states; comments are append-only
|
|
141
|
-
history, not
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
`resolutionHistory` field.
|
|
122
|
+
history, not current state. Use `task context` through the matching Relay CLI
|
|
123
|
+
to read the current recovery state and history; do not read internal storage
|
|
124
|
+
or invent a second recovery-history source.
|
|
145
125
|
|
|
146
126
|
Human responses are comments. Resuming a Troubleshooter must not rewrite its
|
|
147
127
|
input or append a stale “Required resolution condition” as new objective text.
|