agents-relay 2.0.195 → 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.
@@ -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.