agents-relay 2.0.210 → 2.0.211
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,3 +1,4 @@
|
|
|
1
|
+
import { eventOnlyReviewEligible } from './interactive-invocation.js';
|
|
1
2
|
export const hostInvocationTablesSql = `
|
|
2
3
|
CREATE TABLE IF NOT EXISTS host_invocation_event (
|
|
3
4
|
job_id TEXT NOT NULL,
|
|
@@ -51,9 +52,21 @@ export function recordHostInvocationDecision(db, delivery, fingerprint, writeSna
|
|
|
51
52
|
const job = snapshot?.json ? JSON.parse(snapshot.json) : null;
|
|
52
53
|
const task = job?.tasks.find(item => item.id === delivery.taskId);
|
|
53
54
|
const invocation = task?.interactiveInvocation;
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
55
|
+
const bound = invocation && ['RUNNING', 'DRAFT'].includes(task?.state ?? '') &&
|
|
56
|
+
invocation.executionId === delivery.executionId &&
|
|
57
|
+
(task?.executionId === delivery.executionId || task?.state === 'DRAFT') &&
|
|
58
|
+
invocation.status === 'awaiting_decision' && invocation.invocationId === delivery.invocationId &&
|
|
59
|
+
invocation.revision === delivery.revision;
|
|
60
|
+
// Event-only reviews are claims against an ACTIVE execution, not permission to
|
|
61
|
+
// release an arbitrary DRAFT/failed/cancelled Task or replay an older revision.
|
|
62
|
+
const active = job?.state === 'ACTIVE' && task?.state === 'RUNNING' &&
|
|
63
|
+
task.executionId === delivery.executionId && eventOnlyReviewEligible(delivery);
|
|
64
|
+
const seen = db.prepare('SELECT 1 FROM host_invocation_decision WHERE job_id=? AND task_id=? AND execution_id=? AND revision=?')
|
|
65
|
+
.get(delivery.jobId, delivery.taskId, delivery.executionId, delivery.revision);
|
|
66
|
+
const eventOnly = active && !seen && (!invocation ||
|
|
67
|
+
(invocation.status === 'changes_requested' && invocation.executionId === delivery.executionId &&
|
|
68
|
+
invocation.revision !== delivery.revision));
|
|
69
|
+
if (!job || !task || job.state !== 'ACTIVE' || (!bound && !eventOnly)) {
|
|
57
70
|
recordHostInvocationEvent(db, delivery, 'stale', fingerprint);
|
|
58
71
|
db.exec('COMMIT');
|
|
59
72
|
return { outcome: 'stale', reason: 'invocation_or_revision_mismatch' };
|
|
@@ -65,7 +78,8 @@ export function recordHostInvocationDecision(db, delivery, fingerprint, writeSna
|
|
|
65
78
|
const decidedInvocation = {
|
|
66
79
|
invocationId: delivery.invocationId, revision: delivery.revision, executionId: delivery.executionId,
|
|
67
80
|
status: delivery.decision === 'approved' ? 'approved' : 'changes_requested',
|
|
68
|
-
boundAt: invocation.boundAt
|
|
81
|
+
boundAt: bound ? invocation.boundAt : delivery.deliveredAt, decidedAt: delivery.deliveredAt,
|
|
82
|
+
feedback: delivery.feedback, comments: delivery.comments, idempotencyKey: delivery.idempotencyKey,
|
|
69
83
|
};
|
|
70
84
|
task.interactiveInvocation = decidedInvocation;
|
|
71
85
|
const candidate = Date.parse(delivery.deliveredAt);
|
|
@@ -9,6 +9,8 @@ export const interactiveInvocationGraph = new GraphRuntime(graphSource, {
|
|
|
9
9
|
currentInvocation: facts => facts.durableFacts.currentInvocation === true,
|
|
10
10
|
awaitingDecision: facts => facts.durableFacts.awaitingDecision === true,
|
|
11
11
|
currentRevision: facts => facts.durableFacts.currentRevision === true,
|
|
12
|
+
eventOnlyCurrentExecution: facts => facts.durableFacts.eventOnlyCurrentExecution === true,
|
|
13
|
+
eventOnlyNextRevision: facts => facts.durableFacts.eventOnlyNextRevision === true,
|
|
12
14
|
duplicateDelivery: facts => facts.durableFacts.duplicateDelivery === true,
|
|
13
15
|
changesRequested: facts => facts.durableFacts.changesRequested === true,
|
|
14
16
|
},
|
|
@@ -50,10 +52,26 @@ export function normalizeInteractiveDecision(event) {
|
|
|
50
52
|
const decision = value.decision === 'approved' || value.decision === 'changes_requested' ? value.decision : null;
|
|
51
53
|
if (!jobId || !taskId || !executionId || !invocationId || !revision || !decision)
|
|
52
54
|
return null;
|
|
53
|
-
|
|
55
|
+
if (event.source?.id !== `job/${jobId}/task/${taskId}/execution/${executionId}`)
|
|
56
|
+
return null;
|
|
57
|
+
if (value.contentHash !== undefined && typeof value.feedback !== 'string')
|
|
58
|
+
return null;
|
|
59
|
+
const feedback = typeof value.feedback === 'string' ? value.feedback : null;
|
|
60
|
+
const contentHash = string('contentHash');
|
|
61
|
+
if (contentHash && contentHash !== revision)
|
|
62
|
+
return null;
|
|
63
|
+
const comments = value.comments;
|
|
64
|
+
if (comments !== undefined && (!Array.isArray(comments) || comments.length > 100 ||
|
|
65
|
+
comments.some(comment => !comment || typeof comment !== 'object' || Array.isArray(comment) ||
|
|
66
|
+
typeof comment.text !== 'string')))
|
|
67
|
+
return null;
|
|
54
68
|
return {
|
|
55
69
|
jobId, taskId, executionId, invocationId, revision, decision,
|
|
56
70
|
feedback: feedback ?? undefined,
|
|
71
|
+
contentHash: contentHash ?? undefined, revisionId: string('revisionId') ?? undefined,
|
|
72
|
+
previewId: string('previewId') ?? undefined, requestId: string('requestId') ?? undefined,
|
|
73
|
+
idempotencyKey: string('idempotencyKey') ?? undefined,
|
|
74
|
+
comments: comments,
|
|
57
75
|
eventId: event.event_id,
|
|
58
76
|
deliveredAt: event.timestamp,
|
|
59
77
|
};
|
|
@@ -67,12 +85,20 @@ export function interactiveDecisionFingerprint(decision) {
|
|
|
67
85
|
revision: decision.revision,
|
|
68
86
|
decision: decision.decision,
|
|
69
87
|
feedback: decision.feedback ?? null,
|
|
88
|
+
comments: decision.comments ?? null,
|
|
70
89
|
})).digest('hex');
|
|
71
90
|
}
|
|
91
|
+
/** First event for an unbound interaction must carry immutable video identity. */
|
|
92
|
+
export function eventOnlyReviewEligible(delivery) {
|
|
93
|
+
return Boolean(delivery.contentHash && /^[a-f0-9]{64}$/.test(delivery.contentHash) &&
|
|
94
|
+
delivery.revision === delivery.contentHash && delivery.feedback !== undefined &&
|
|
95
|
+
[delivery.revisionId, delivery.requestId, delivery.idempotencyKey, delivery.invocationId]
|
|
96
|
+
.every(value => typeof value === 'string' && value.length > 0 && value.length <= 128));
|
|
97
|
+
}
|
|
72
98
|
function invocationState(invocation) {
|
|
73
99
|
return invocation?.status ?? 'awaiting_decision';
|
|
74
100
|
}
|
|
75
|
-
async function decideInteractiveInvocation(task, delivery, duplicateDelivery) {
|
|
101
|
+
async function decideInteractiveInvocation(task, delivery, duplicateDelivery, jobActive) {
|
|
76
102
|
const invocation = task.interactiveInvocation;
|
|
77
103
|
const result = await dispatchWorkflowGraph(interactiveInvocationGraph, {
|
|
78
104
|
initialState: invocationState(invocation),
|
|
@@ -81,6 +107,12 @@ async function decideInteractiveInvocation(task, delivery, duplicateDelivery) {
|
|
|
81
107
|
currentInvocation: invocation?.invocationId === delivery.invocationId,
|
|
82
108
|
awaitingDecision: invocation?.status === 'awaiting_decision',
|
|
83
109
|
currentRevision: invocation?.revision === delivery.revision,
|
|
110
|
+
eventOnlyCurrentExecution: jobActive && !invocation && task.state === 'RUNNING' &&
|
|
111
|
+
task.executionId === delivery.executionId && eventOnlyReviewEligible(delivery),
|
|
112
|
+
eventOnlyNextRevision: jobActive && invocation?.status === 'changes_requested' &&
|
|
113
|
+
invocation.executionId === delivery.executionId && task.state === 'RUNNING' &&
|
|
114
|
+
task.executionId === delivery.executionId && invocation.revision !== delivery.revision &&
|
|
115
|
+
eventOnlyReviewEligible(delivery),
|
|
84
116
|
duplicateDelivery,
|
|
85
117
|
changesRequested: delivery.decision === 'changes_requested',
|
|
86
118
|
},
|
|
@@ -166,13 +198,13 @@ export class HostInteractiveInvocationCoordinator {
|
|
|
166
198
|
}
|
|
167
199
|
const job = await this.options.store.loadJob(delivery.jobId);
|
|
168
200
|
const task = job?.tasks.find((item) => item.id === delivery.taskId);
|
|
169
|
-
if (!job || !task ||
|
|
201
|
+
if (!job || !task ||
|
|
170
202
|
(task.executionId !== delivery.executionId && task.state !== 'DRAFT')) {
|
|
171
203
|
await this.options.store.recordHostInvocationEvent?.(delivery, 'stale', interactiveDecisionFingerprint(delivery));
|
|
172
204
|
return { outcome: 'stale', reason: 'execution_not_bound' };
|
|
173
205
|
}
|
|
174
206
|
const duplicate = await this.options.store.hasHostInvocationDecision?.(delivery.jobId, delivery.taskId, delivery.invocationId, interactiveDecisionFingerprint(delivery)) ?? false;
|
|
175
|
-
const graphDecision = await decideInteractiveInvocation(task, delivery, duplicate);
|
|
207
|
+
const graphDecision = await decideInteractiveInvocation(task, delivery, duplicate, job.state === 'ACTIVE');
|
|
176
208
|
const selected = graphDecision.actions.some(action => action === 'interactive.requestChanges' || action === 'interactive.approve');
|
|
177
209
|
if (!graphDecision.accepted || !selected || duplicate) {
|
|
178
210
|
const outcome = duplicate ? 'duplicate' : 'stale';
|
|
@@ -187,7 +219,7 @@ export class HostInteractiveInvocationCoordinator {
|
|
|
187
219
|
const accepted = {
|
|
188
220
|
jobId: delivery.jobId, taskId: delivery.taskId, executionId: delivery.executionId,
|
|
189
221
|
invocationId: delivery.invocationId, revision: delivery.revision, decision: delivery.decision,
|
|
190
|
-
feedback: delivery.feedback, event,
|
|
222
|
+
feedback: delivery.feedback, comments: delivery.comments, idempotencyKey: delivery.idempotencyKey, event,
|
|
191
223
|
};
|
|
192
224
|
const key = `${accepted.jobId}:${accepted.taskId}:${accepted.executionId}:${accepted.invocationId}`;
|
|
193
225
|
const waiter = this.waiters.get(key);
|
|
@@ -72,7 +72,7 @@ export class ReconcilerRuntimeBase {
|
|
|
72
72
|
}
|
|
73
73
|
});
|
|
74
74
|
}
|
|
75
|
-
async applyHostInvocationEvent(event) { const result = await this.hostInvocations.applyEvent(event); const resumed = result.resumeWorker && result.decision ? await resumeInteractiveTask(this.store, result.decision.jobId, result.decision.taskId, result.decision.invocationId, result.decision.revision, result.decision.decision) : false; return { applied: result.outcome !== 'ignored', reconcile: resumed, reason: `task.interactive_decision.${result.outcome}` }; }
|
|
75
|
+
async applyHostInvocationEvent(event) { const result = await this.hostInvocations.applyEvent(event); const resumed = result.resumeWorker && result.decision ? await resumeInteractiveTask(this.store, result.decision.jobId, result.decision.taskId, result.decision.invocationId, result.decision.revision, result.decision.decision) : false; return { applied: result.outcome !== 'ignored', reconcile: resumed || result.outcome === 'accepted', reason: `task.interactive_decision.${result.outcome}` }; }
|
|
76
76
|
bindInteractiveInvocation(jobId, task, executionId, invocationId, revision) { return this.hostInvocations.bind(jobId, task, executionId, invocationId, revision); }
|
|
77
77
|
async applyJobEffectOutcomes(job, outcomes) {
|
|
78
78
|
await applyJobEffectOutcomes(this.store, event => this.emit(event), job, outcomes);
|
package/package.json
CHANGED
|
@@ -42,6 +42,53 @@ The automatically created `job-acceptance-reviewer` (historical `reviewer` recor
|
|
|
42
42
|
A fix child reports its **own** correlated completion after verified repair. Downstream `dependencyValidity` policy is `order-only` by default, or explicitly `revalidate`/`rerun` per declared input. All changed upstream generations must settle before a fan-in consumer can verify or rerun. Relay derives successful revision lineage from durable Task results, then creates another fresh immutable-head Job Acceptance Review. A partially submitted message, unverified terminal, historical result or stale source SHA does not count as a fix or approval.
|
|
43
43
|
|
|
44
44
|
|
|
45
|
+
## Generic interactive decision event (human review)
|
|
46
|
+
|
|
47
|
+
**Canonical type:** `task.interactive_decision`. This is a human decision for an in-progress Task (video preview, document review, image approval, etc.), **not** an Implementation terminal event or a Job Final Reviewer verdict. A UI such as Markcut is a generic publisher: it receives a caller-supplied template and fills only the declared review-result fields. It must not invent Task/Execution/source identity or a new Relay-specific event type.
|
|
48
|
+
|
|
49
|
+
**Producer event template**, based on the exact managed Task execution context (illustrative identities only):
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"type": "task.interactive_decision",
|
|
54
|
+
"source": "job/556/task/producer/execution/exec-abc",
|
|
55
|
+
"data": {
|
|
56
|
+
"interactive": {
|
|
57
|
+
"jobId": "556",
|
|
58
|
+
"taskId": "producer",
|
|
59
|
+
"executionId": "exec-abc",
|
|
60
|
+
"invocationId": "review-request-123"
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The caller provides this as `markcut.preview({path, review:{delivery:"event", eventTemplate}})` or the same metadata in a Neo Mobile review request. `source` and the four template identity fields are immutable. They must match the current Job/Task/Execution. An invocation ID is a stable unique identifier for the human review request; it is not a video revision, a new Task, or a generated execution ID.
|
|
67
|
+
|
|
68
|
+
**On human Submit**, the Preview UI fills the following fields under `data.interactive`, preserving every caller-owned field:
|
|
69
|
+
|
|
70
|
+
| Field | Rule |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `decision` | **Required**: `approved` or `changes_requested`; only the human sets it. |
|
|
73
|
+
| `feedback` | **Required** string: plain-language feedback, or `""` on approval. |
|
|
74
|
+
| `comments` | Optional structured scene/timestamp comments; do not flatten or discard when available. |
|
|
75
|
+
| `revision` | **Required**: immutable content SHA-256 for the reviewed video in event-only mode. |
|
|
76
|
+
| `contentHash` | **Required** in event-only mode; equals `revision`, exact 64 lowercase hex. |
|
|
77
|
+
| `revisionId` | **Required** in event-only mode: human-visible immutable preview revision identifier. |
|
|
78
|
+
| `previewId`, `requestId` | Optional/required respectively in event-only mode; bind the original review request. |
|
|
79
|
+
| `idempotencyKey` | **Required** in event-only mode, stable across delivery retries. |
|
|
80
|
+
|
|
81
|
+
For a human clicking Approve or Request Changes, **one submitted decision generates one event**. Editing individual comments does not publish events. The Preview and Neo Mobile use the same field paths. Events Bus still accepts `{type,source,data}`; via Neo MCP `events`, call `{command:"publish",args:{type,source,data}}`. A successful publish is only a transport receipt, **not** an accepted Relay decision or a completed revision.
|
|
82
|
+
|
|
83
|
+
**Relay admission and Graph semantics:**
|
|
84
|
+
|
|
85
|
+
1. Normalize the event, validate the source identity against the data and current Task, then consult the canonical `workflow/interactive-invocation.mmd` Graph. Reject stale executions, invalid decisions/versions, wrong identities, cancelled Jobs and duplicated/conflicting decisions; record the decision atomically in Relay-owned durable state.
|
|
86
|
+
2. Legacy host-bound invocations remain supported. An event-only decision may arrive **without a preceding `bindInteractiveInvocation()`** when the Job is ACTIVE, the Task is RUNNING in the exact matching Execution, and the event carries complete immutable content identity. A later video revision may be submitted for the same execution only after `changes_requested`; already decided revisions may not be replayed as new ones.
|
|
87
|
+
3. `changes_requested` records actionable feedback for the owning Task. `approved` passes only the human interaction gate for **that exact content**; it does not mark a Task or Job complete. Graph-selected continuation/recovery is separate from the Event Bus receipt. A RUNNING Worker that did not register a waiting Promise must consume the accepted decision via its event-driven workflow; accepting the event alone does not create a new Agent Turn.
|
|
88
|
+
4. **Limitation of an entirely unbound event**: Relay cannot independently prove that a never-before-seen content hash is the *latest* Markcut preview solely from the Event payload. The Preview provider and mobile client must reject superseded revisions before publishing; a future trusted, durable preview-generation fact is necessary if Relay must independently reject every previously unreviewed stale version. Do not present client-declared revision fields as cryptographic authorization.
|
|
89
|
+
|
|
90
|
+
`review.approved` and `review.changes_required` belong to immutable-head Job Acceptance Review; do **not** emit those or `task.completed` from a Preview UI. Consumers outside Relay may use their own event type, but managed Relay review templates must use `task.interactive_decision`.
|
|
91
|
+
|
|
45
92
|
## Troubleshooter human escalation
|
|
46
93
|
|
|
47
94
|
Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
|
|
@@ -52,7 +99,7 @@ See [task-recovery-flows.md](task-recovery-flows.md) for unified architecture, o
|
|
|
52
99
|
|
|
53
100
|
Reviewer unavailable evidence is an execution failure (`task.failed`), not a blocked Task. Legacy Reviewer verdict `blocked` is normalized to failure and must dispatch Troubleshooter. Only Relay blocks a Troubleshooter during human escalation.
|
|
54
101
|
|
|
55
|
-
A host-mediated interactive invocation
|
|
102
|
+
A host-mediated interactive invocation remains a Relay-controlled wait when explicitly bound. The event-only path above accepts complete decisions from current active executions without requiring prior binding; neither route authorizes a Worker or Reviewer to choose a blocked terminal outcome.
|
|
56
103
|
|
|
57
104
|
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.
|
|
58
105
|
|
|
@@ -10,6 +10,8 @@ approved["state: approved"]
|
|
|
10
10
|
context["guard: currentInvocation"]
|
|
11
11
|
awaiting["guard: awaitingDecision"]
|
|
12
12
|
revision["guard: currentRevision"]
|
|
13
|
+
unbound["guard: eventOnlyCurrentExecution"]
|
|
14
|
+
newRevision["guard: eventOnlyNextRevision"]
|
|
13
15
|
duplicateChanges["guard: duplicateDelivery"]
|
|
14
16
|
duplicateApproved["guard: duplicateDelivery"]
|
|
15
17
|
decisionKind["guard: changesRequested"]
|
|
@@ -22,11 +24,16 @@ awaiting_decision -->|on: task.interactive_decision| context
|
|
|
22
24
|
changes -->|on: task.interactive_decision| duplicateChanges
|
|
23
25
|
approved -->|on: task.interactive_decision| duplicateApproved
|
|
24
26
|
context -->|true| awaiting
|
|
25
|
-
context -->|false|
|
|
27
|
+
context -->|false| unbound
|
|
28
|
+
unbound -->|true| decisionKind
|
|
29
|
+
unbound -->|false| awaiting_decision
|
|
26
30
|
awaiting -->|true| revision
|
|
27
31
|
awaiting -->|false| awaiting_decision
|
|
28
32
|
revision -->|true| decisionKind
|
|
29
33
|
revision -->|false| awaiting_decision
|
|
34
|
+
duplicateChanges -->|false| newRevision
|
|
35
|
+
newRevision -->|true| decisionKind
|
|
36
|
+
newRevision -->|false| changes
|
|
30
37
|
decisionKind -->|true| requestChanges
|
|
31
38
|
decisionKind -->|false| approve
|
|
32
39
|
requestChanges --> wakeChanges
|
|
@@ -34,7 +41,6 @@ wakeChanges -->|to: changes_requested| changes
|
|
|
34
41
|
approve --> wake
|
|
35
42
|
wake -->|to: approved| approved
|
|
36
43
|
duplicateChanges -->|true| wakeChanges
|
|
37
|
-
duplicateChanges -->|false| changes
|
|
38
44
|
duplicateApproved -->|true| wake
|
|
39
45
|
duplicateApproved -->|false| approved
|
|
40
46
|
changes -->|on: task.interactive_recover| wakeChanges
|