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.
@@ -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
- The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside marker JSON. The Job marker lives in the PR body immediately before the human-readable Job objective; Task markers live in their Task comments immediately before the human-readable Task input/result. Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded long-form content or stored the Job marker in a separate comment.
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
- Ordinary `job create` requires standalone objective Markdown. An external display PR is projected after the first meaningful code commit; existing PRs are adopted with `job adopt`. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
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 evidence.
38
- Responses, resolution changes, and escalation history belong in append-only
39
- Task Comments. SQLite atomically records typed comments with authoritative
40
- resolution/escalation mutations; PR-bound Jobs project those comments through
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, PR comments, artifacts, or remaining issues.
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 trusted Job marker declares a human-readable `description` explaining what the tag means and when workers should set it, plus the allowed durable values and their dashboard display strings:
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 authoritative SQLite replay checks pass; set fail when a required check fails.",
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 the Task marker 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`:
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`. If the value is allowed, Relay persists it into the trusted Task marker as the Task's `tag`; undeclared or invalid values are ignored. The transport `data.tag` is not duplicated into `result.data`. The resulting Task metadata may therefore contain both independent concepts at once:
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 canonical Task
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 direct initial Task batch or a Planner-produced batch settles, reconciliation evaluates the canonical Planner Graph and creates the next durable `plan-N` round until the latest successful Plan returns `objective_status: satisfied`. There is no fixed/autonomous mode, no Job schedule, no cron slot, and no Scheduler entity. The daemon performs startup recovery and wake-driven reconciliation from SQLite. A satisfied Plan alone does not complete a Job: successful implementation evidence, SHA-bound review when enabled, and verified local merge/delivery remain mandatory.
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 that runs after dependencies complete must resolve the current durable Job/PR head at execution time unless the Job objective explicitly requires the earlier immutable target.
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 cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or Troubleshooter inference. The authoritative entry point records the response and transitions that same Troubleshooter `BLOCKED -> QUEUED` through `task.unblocked`. 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 ordinary BLOCKED snapshots migrate to FAILED while their append-only event history remains unchanged; they are never silently converted to success.
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
- The old `UNBLOCKED` state is compatibility-only input. It normalizes to QUEUED only for Troubleshooter Tasks and to FAILED for ordinary Tasks, pending diagnosis.
188
+ Do not create or infer an `UNBLOCKED` state for ordinary Tasks.
188
189
 
189
- Each Planner round is also a first-class durable Plan entity stored in its own `agents-relay:plan:v1` PR comment. Relay creates the Plan comment before the internal planner execution record and before any generated Task comments, then updates that same Plan comment with the final assessment and generated Task IDs. Unblock/change facts belong to the Plan trigger/context, not to new Job-level Change Cycle state. Historical `kind=planner` Task records and legacy Job `changeCycle` fields remain readable for compatibility only.
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 — Agreed Target Design
1
+ # Task Failure Recovery and Human Escalation — Current Contract
2
2
 
3
- **Status:** Current recovery contract. SQLite Task snapshots retain append-only typed comments alongside authoritative state.
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, 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.
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; the reconciler/engine validates and durably applies them. An event arriving over the bus is not proof its transition was applied.
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
- ## Unified architecture
14
+ ## External recovery interface
15
15
 
16
- All three agent roles publish through the **same Task event contract**. Events Bus treats `data` as opaque; Relay interprets role-specific results and alone changes durable Task/Job state.
17
-
18
- ```mermaid
19
- flowchart TD
20
- I["Implementation"] --> U["Unified Task events"]
21
- V["Reviewer"] --> U
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. Reconciler starts a correlated Troubleshooter Task. Troubleshooter examines durable Task history and technical evidence before choosing a resolution.
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 a second state authority. SQLite mutation transactions compare the
142
- before/after authoritative values and append typed comments with Job, Task,
143
- execution, transition, and idempotency identity in the same commit. Do not add a
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.