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.
- 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/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
|
@@ -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.
|