agents-relay 2.0.83 → 2.0.84

package/dist/host-invocation-store.js

@@ -0,0 +1,83 @@
+export const hostInvocationTablesSql = `
+  CREATE TABLE IF NOT EXISTS host_invocation_event (
+    job_id TEXT NOT NULL,
+    task_id TEXT NOT NULL,
+    event_id TEXT NOT NULL,
+    invocation_id TEXT NOT NULL,
+    execution_id TEXT NOT NULL,
+    revision TEXT NOT NULL,
+    decision TEXT NOT NULL CHECK(decision IN ('approved','changes_requested')),
+    outcome TEXT NOT NULL CHECK(outcome IN ('accepted','duplicate','stale','ignored')),
+    fingerprint TEXT NOT NULL,
+    received_at TEXT NOT NULL,
+    PRIMARY KEY(job_id,task_id,event_id)
+  );
+  CREATE TABLE IF NOT EXISTS host_invocation_decision (
+    job_id TEXT NOT NULL,
+    task_id TEXT NOT NULL,
+    invocation_id TEXT NOT NULL,
+    execution_id TEXT NOT NULL,
+    revision TEXT NOT NULL,
+    decision TEXT NOT NULL CHECK(decision IN ('approved','changes_requested')),
+    feedback TEXT,
+    fingerprint TEXT NOT NULL,
+    event_id TEXT NOT NULL,
+    decided_at TEXT NOT NULL,
+    PRIMARY KEY(job_id,task_id,invocation_id),
+    UNIQUE(job_id,task_id,event_id)
+  );
+`;
+export function recordHostInvocationEvent(db, delivery, outcome, fingerprint) {
+    db.prepare(`INSERT OR IGNORE INTO host_invocation_event
+    (job_id,task_id,event_id,invocation_id,execution_id,revision,decision,outcome,fingerprint,received_at)
+    VALUES(?,?,?,?,?,?,?,?,?,?)`).run(delivery.jobId, delivery.taskId, delivery.eventId, delivery.invocationId, delivery.executionId, delivery.revision, delivery.decision, outcome, fingerprint, delivery.deliveredAt);
+}
+export function hasHostInvocationDecision(db, jobId, taskId, invocationId, fingerprint) {
+    return db.prepare('SELECT 1 FROM host_invocation_decision WHERE job_id=? AND task_id=? AND invocation_id=? AND (? IS NULL OR fingerprint=?)')
+        .get(jobId, taskId, invocationId, fingerprint ?? null, fingerprint ?? null) !== undefined;
+}
+export function recordHostInvocationDecision(db, delivery, fingerprint, writeSnapshot) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const existing = db.prepare('SELECT fingerprint FROM host_invocation_decision WHERE job_id=? AND task_id=? AND invocation_id=?')
+            .get(delivery.jobId, delivery.taskId, delivery.invocationId);
+        if (existing) {
+            const outcome = existing.fingerprint === fingerprint ? 'duplicate' : 'stale';
+            recordHostInvocationEvent(db, delivery, outcome, fingerprint);
+            db.exec('COMMIT');
+            return { outcome, reason: outcome === 'duplicate' ? 'invocation_already_decided' : 'conflicting_invocation_decision' };
+        }
+        const snapshot = db.prepare('SELECT json FROM job_snapshot WHERE job_id=?').get(delivery.jobId);
+        const job = snapshot?.json ? JSON.parse(snapshot.json) : null;
+        const task = job?.tasks.find(item => item.id === delivery.taskId);
+        const invocation = task?.interactiveInvocation;
+        if (!job || !task || !invocation || !(['RUNNING', 'BLOCKED'].includes(task.state)) || invocation.executionId !== delivery.executionId ||
+            (task.executionId !== delivery.executionId && task.state !== 'BLOCKED') ||
+            invocation.status !== 'awaiting_decision' || invocation.invocationId !== delivery.invocationId || invocation.revision !== delivery.revision) {
+            recordHostInvocationEvent(db, delivery, 'stale', fingerprint);
+            db.exec('COMMIT');
+            return { outcome: 'stale', reason: 'invocation_or_revision_mismatch' };
+        }
+        db.prepare(`INSERT INTO host_invocation_decision
+      (job_id,task_id,invocation_id,execution_id,revision,decision,feedback,fingerprint,event_id,decided_at)
+      VALUES(?,?,?,?,?,?,?,?,?,?)`).run(delivery.jobId, delivery.taskId, delivery.invocationId, delivery.executionId, delivery.revision, delivery.decision, delivery.feedback ?? null, fingerprint, delivery.eventId, delivery.deliveredAt);
+        recordHostInvocationEvent(db, delivery, 'accepted', fingerprint);
+        const decidedInvocation = {
+            invocationId: delivery.invocationId, revision: delivery.revision, executionId: delivery.executionId,
+            status: delivery.decision === 'approved' ? 'approved' : 'changes_requested',
+            boundAt: invocation.boundAt, decidedAt: delivery.deliveredAt, feedback: delivery.feedback,
+        };
+        task.interactiveInvocation = decidedInvocation;
+        const candidate = Date.parse(delivery.deliveredAt);
+        const previous = Date.parse(job.updatedAt);
+        job.updatedAt = Number.isFinite(candidate) && candidate > previous
+            ? delivery.deliveredAt : new Date(previous + 1).toISOString();
+        writeSnapshot(job, delivery.deliveredAt);
+        db.exec('COMMIT');
+        return { outcome: 'accepted', reason: 'latest_interactive_decision', invocation: decidedInvocation };
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}

package/dist/interactive-invocation.js

@@ -0,0 +1,233 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './workflow/graph-v2.js';
+import { dispatchWorkflowGraph } from './workflow/dispatcher.js';
+const graphSource = readFileSync(new URL('../workflow/interactive-invocation.mmd', import.meta.url), 'utf8');
+export const interactiveInvocationGraph = new GraphRuntime(graphSource, {
+    states: new Set(['awaiting_decision', 'changes_requested', 'approved']),
+    guards: {
+        currentInvocation: facts => facts.durableFacts.currentInvocation === true,
+        awaitingDecision: facts => facts.durableFacts.awaitingDecision === true,
+        currentRevision: facts => facts.durableFacts.currentRevision === true,
+        duplicateDelivery: facts => facts.durableFacts.duplicateDelivery === true,
+        changesRequested: facts => facts.durableFacts.changesRequested === true,
+    },
+    actions: {
+        'interactive.recordDecision': { id: 'interactive.recordDecision' },
+        'interactive.requestChanges': { id: 'interactive.requestChanges' },
+        'interactive.approve': { id: 'interactive.approve' },
+        'interactive.wakeWorker': { id: 'interactive.wakeWorker' },
+    },
+    events: { 'task.interactive_decision': { id: 'task.interactive_decision' }, 'task.interactive_recover': { id: 'task.interactive_recover' } },
+});
+export function hostInteractiveDecisionEvent(context, feedback, receivedAt = new Date().toISOString()) {
+    if (!feedback.eventId || !feedback.invocationId || !feedback.revision ||
+        !['approved', 'changes_requested'].includes(feedback.decision)) {
+        throw new Error('Incomplete generic interactive decision');
+    }
+    return {
+        version: 1, event_id: feedback.eventId, job_id: context.jobId,
+        task_id: context.taskId, parent_task_id: null, type: 'task.interactive_decision',
+        status: 'running', timestamp: receivedAt, visibility: 'orchestrator', level: 'info',
+        message: `Host interactive decision received for revision ${feedback.revision}`,
+        source: { id: `job/${context.jobId}/task/${context.taskId}/execution/${context.executionId}`, component: 'agents-relay' },
+        data: { interactive: { ...context, ...feedback, eventId: undefined } },
+    };
+}
+export function normalizeInteractiveDecision(event) {
+    if (event.type !== 'task.interactive_decision')
+        return null;
+    const payload = event.data?.interactive;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return null;
+    const value = payload;
+    const string = (key) => typeof value[key] === 'string' && value[key].length > 0 ? value[key] : null;
+    const jobId = string('jobId');
+    const taskId = string('taskId');
+    const executionId = string('executionId');
+    const invocationId = string('invocationId');
+    const revision = string('revision');
+    const decision = value.decision === 'approved' || value.decision === 'changes_requested' ? value.decision : null;
+    if (!jobId || !taskId || !executionId || !invocationId || !revision || !decision)
+        return null;
+    const feedback = string('feedback');
+    return {
+        jobId, taskId, executionId, invocationId, revision, decision,
+        feedback: feedback ?? undefined,
+        eventId: event.event_id,
+        deliveredAt: event.timestamp,
+    };
+}
+export function interactiveDecisionFingerprint(decision) {
+    return createHash('sha256').update(JSON.stringify({
+        jobId: decision.jobId,
+        taskId: decision.taskId,
+        executionId: decision.executionId,
+        invocationId: decision.invocationId,
+        revision: decision.revision,
+        decision: decision.decision,
+        feedback: decision.feedback ?? null,
+    })).digest('hex');
+}
+function invocationState(invocation) {
+    return invocation?.status ?? 'awaiting_decision';
+}
+async function decideInteractiveInvocation(task, delivery, duplicateDelivery) {
+    const invocation = task.interactiveInvocation;
+    const result = await dispatchWorkflowGraph(interactiveInvocationGraph, {
+        initialState: invocationState(invocation),
+        input: { transport: 'event', id: 'task.interactive_decision', payload: {} },
+        durableFacts: {
+            currentInvocation: invocation?.invocationId === delivery.invocationId,
+            awaitingDecision: invocation?.status === 'awaiting_decision',
+            currentRevision: invocation?.revision === delivery.revision,
+            duplicateDelivery,
+            changesRequested: delivery.decision === 'changes_requested',
+        },
+        graphName: 'interactive-invocation',
+        observe: false,
+        executeAction: () => ({}),
+    });
+    return {
+        accepted: result.accepted,
+        actions: result.accepted ? result.actions.map((action) => action.id) : [],
+    };
+}
+/** Explicitly bind prototype-backed Store operations; object spread discards them. */
+export function hostInvocationPorts(store) {
+    return {
+        loadJob: jobId => store.load(jobId),
+        mutateJob: (jobId, mutation) => {
+            if (!store.mutateJob)
+                throw new Error('Store does not support atomic job mutation');
+            return store.mutateJob(jobId, mutation);
+        },
+        recordHostInvocationEvent: (delivery, outcome, fingerprint) => {
+            if (!store.recordHostInvocationEvent)
+                throw new Error('Store does not support invocation events');
+            return store.recordHostInvocationEvent(delivery, outcome, fingerprint);
+        },
+        hasHostInvocationDecision: (jobId, taskId, invocationId, fingerprint) => store.hasHostInvocationDecision?.(jobId, taskId, invocationId, fingerprint) ?? Promise.resolve(false),
+        recordHostInvocationDecision: (delivery, fingerprint) => {
+            if (!store.recordHostInvocationDecision)
+                throw new Error('Store does not support invocation decisions');
+            return store.recordHostInvocationDecision(delivery, fingerprint);
+        },
+    };
+}
+export class HostInteractiveInvocationCoordinator {
+    options;
+    waiters = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async bind(jobId, task, executionId, invocationId, revision) {
+        if (task.state !== 'RUNNING')
+            throw new Error(`Task ${task.id} must be RUNNING to bind an interactive invocation`);
+        if (task.executionId !== executionId)
+            throw new Error(`Task ${task.id} does not own execution ${executionId}`);
+        const now = (this.options.now ?? (() => new Date()))().toISOString();
+        const invocation = { invocationId, revision, executionId, status: 'awaiting_decision', boundAt: now };
+        const boundJobId = task.jobId ?? jobId;
+        if (!boundJobId)
+            throw new Error(`Task ${task.id} cannot bind an interactive invocation without a Job ID`);
+        if (!this.options.store.mutateJob)
+            throw new Error('Store does not support atomic invocation binding');
+        await this.options.store.mutateJob(boundJobId, current => {
+            const next = structuredClone(current);
+            const nextTask = next.tasks.find((item) => item.id === task.id);
+            if (!nextTask || nextTask.executionId !== executionId || nextTask.state !== 'RUNNING')
+                return current;
+            if (nextTask.interactiveInvocation?.invocationId === invocationId) {
+                if (nextTask.interactiveInvocation.revision !== revision)
+                    throw new Error('Invocation identity cannot change revision');
+                return current;
+            }
+            nextTask.interactiveInvocation = invocation;
+            return next;
+        });
+        const key = `${boundJobId}:${task.id}:${executionId}:${invocationId}`;
+        const decision = new Promise((resolve, reject) => {
+            this.waiters.set(key, resolve);
+            const timer = setTimeout(() => {
+                if (this.waiters.get(key) !== resolve)
+                    return;
+                this.waiters.delete(key);
+                reject(new Error(`Interactive decision timeout for task ${task.id}, revision ${revision}`));
+            }, 60_000);
+            timer.unref();
+        });
+        return { decision };
+    }
+    async applyEvent(event) {
+        const delivery = normalizeInteractiveDecision(event);
+        if (!delivery || delivery.jobId !== event.job_id || delivery.taskId !== event.task_id) {
+            return { outcome: 'ignored', reason: 'invalid_interactive_delivery' };
+        }
+        const job = await this.options.store.loadJob(delivery.jobId);
+        const task = job?.tasks.find((item) => item.id === delivery.taskId);
+        if (!job || !task || task.interactiveInvocation?.executionId !== delivery.executionId ||
+            (task.executionId !== delivery.executionId && task.state !== 'BLOCKED')) {
+            await this.options.store.recordHostInvocationEvent?.(delivery, 'stale', interactiveDecisionFingerprint(delivery));
+            return { outcome: 'stale', reason: 'execution_not_bound' };
+        }
+        const duplicate = await this.options.store.hasHostInvocationDecision?.(delivery.jobId, delivery.taskId, delivery.invocationId, interactiveDecisionFingerprint(delivery)) ?? false;
+        const graphDecision = await decideInteractiveInvocation(task, delivery, duplicate);
+        const selected = graphDecision.actions.some(action => action === 'interactive.requestChanges' || action === 'interactive.approve');
+        if (!graphDecision.accepted || !selected || duplicate) {
+            const outcome = duplicate ? 'duplicate' : 'stale';
+            await this.options.store.recordHostInvocationEvent?.(delivery, outcome, interactiveDecisionFingerprint(delivery));
+            return { outcome, reason: `${outcome}_interactive_decision`, decision: delivery, resumeWorker: duplicate && graphDecision.actions.includes('interactive.wakeWorker') };
+        }
+        const recorded = await this.options.store.recordHostInvocationDecision?.(delivery, interactiveDecisionFingerprint(delivery));
+        if (!recorded)
+            throw new Error('Interactive invocation store does not support durable decisions');
+        if (recorded.outcome !== 'accepted')
+            return { outcome: recorded.outcome, reason: recorded.reason };
+        const accepted = {
+            jobId: delivery.jobId, taskId: delivery.taskId, executionId: delivery.executionId,
+            invocationId: delivery.invocationId, revision: delivery.revision, decision: delivery.decision,
+            feedback: delivery.feedback, event,
+        };
+        const key = `${accepted.jobId}:${accepted.taskId}:${accepted.executionId}:${accepted.invocationId}`;
+        const waiter = this.waiters.get(key);
+        if (waiter) {
+            this.waiters.delete(key);
+            waiter(accepted);
+        }
+        await this.options.onAccepted?.(accepted);
+        await this.options.emit?.(acceptedEvent(accepted));
+        return { outcome: 'accepted', reason: 'latest_interactive_decision', invocation: recorded.invocation, decision: delivery,
+            resumeWorker: graphDecision.actions.includes('interactive.wakeWorker') };
+    }
+    close() {
+        this.waiters.clear();
+    }
+}
+function acceptedEvent(decision) {
+    return {
+        version: 1,
+        event_id: randomUUID(),
+        job_id: decision.jobId,
+        task_id: decision.taskId,
+        parent_task_id: null,
+        type: 'task.interactive_decision.accepted',
+        status: 'succeeded',
+        timestamp: new Date().toISOString(),
+        visibility: 'orchestrator',
+        level: 'info',
+        message: `Interactive decision ${decision.decision} accepted for revision ${decision.revision}`,
+        source: { id: `job/${decision.jobId}/task/${decision.taskId}/execution/${decision.executionId}`, component: 'agents-relay' },
+        data: { interactive: { ...decision, decision: decision.decision, outcome: 'accepted' } },
+    };
+}
+/** Recovery uses the canonical decision Graph, not transport delivery history. */
+export async function shouldRecoverInteractiveDecision(status) {
+    const result = await dispatchWorkflowGraph(interactiveInvocationGraph, {
+        initialState: status,
+        input: { transport: 'event', id: 'task.interactive_recover', payload: {} },
+        durableFacts: {}, graphName: 'interactive-invocation', observe: false,
+        executeAction: () => ({}),
+    });
+    return result.accepted && result.actions.some(action => action.id === 'interactive.wakeWorker');
+}

package/dist/interactive-resume.js

@@ -0,0 +1,41 @@
+import { shouldRecoverInteractiveDecision } from './interactive-invocation.js';
+import { tryTransitionTaskEvent } from './scheduler.js';
+import { applyTaskUnblockRetrySnapshot } from './task-actions.js';
+export async function resumeInteractiveTask(store, jobId, taskId, invocationId, revision, decision) {
+    if (!store.mutateJob)
+        throw new Error('Interactive resume requires atomic SQLite Job mutation');
+    let resumed = false;
+    await store.mutateJob(jobId, job => {
+        const task = job.tasks.find(item => item.id === taskId);
+        const invocation = task?.interactiveInvocation;
+        if (!task || task.state !== 'BLOCKED' || !invocation ||
+            invocation.invocationId !== invocationId || invocation.revision !== revision ||
+            invocation.status !== decision || !invocation.decidedAt)
+            return job;
+        // Both state transitions and retry eligibility are owned by task-lifecycle.mmd.
+        if (!tryTransitionTaskEvent(task, 'task.unblocked').accepted) {
+            throw new Error('Interactive Task unblock rejected by canonical lifecycle Graph');
+        }
+        applyTaskUnblockRetrySnapshot(task);
+        task.error = null;
+        task.failureReason = undefined;
+        task.updatedAt = new Date().toISOString();
+        resumed = true;
+        return job;
+    });
+    return resumed;
+}
+/** Reconciliation is recovery-safe even when the accepted event was lost after SQLite commit. */
+export async function recoverInteractiveDecisions(store, jobId) {
+    const job = await store.load(jobId);
+    let recovered = false;
+    for (const task of job.tasks) {
+        if (task.state !== 'BLOCKED' || !task.interactiveInvocation?.decidedAt)
+            continue;
+        const invocation = task.interactiveInvocation;
+        if (invocation.status === 'awaiting_decision' || !await shouldRecoverInteractiveDecision(invocation.status))
+            continue;
+        recovered = await resumeInteractiveTask(store, job.id, task.id, invocation.invocationId, invocation.revision, invocation.status) || recovered;
+    }
+    return recovered;
+}

package/dist/managed-worker-input.js

@@ -23,6 +23,15 @@ export async function managedWorkerInput(job, task, context) {
     const output = task.output.kind === 'file'
         ? `file\nPath: ${task.output.path}`
         : (projectedReview ? `task/PR\nProjected PR: ${prUrl}\nTask: ${task.id}` : isLocalJob ? `task/PR\nTask: ${task.id}` : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`);
+    const interactiveContext = task.interactiveInvocation && task.interactiveInvocation.status !== 'awaiting_decision'
+        ? '[Durable interactive review continuation]\n' +
+            JSON.stringify({
+                invocationId: task.interactiveInvocation.invocationId,
+                revision: task.interactiveInvocation.revision,
+                decision: task.interactiveInvocation.status,
+                feedback: task.interactiveInvocation.feedback ?? null,
+            }) + '\nContinue this same Task. For changes_requested, revise the artifact and request review of a NEW immutable revision; for approved, finalize only that approved revision. Never invent a human approval.\n'
+        : '';
     const taskTag = taskTagWorkerPrompt(job);
     return `[Agents Relay managed task]
 ${projectedReview ? `Job: local ${job.id} (lifecycle authority)\nProjected GitHub PR: ${prUrl}` : isLocalJob ? `Job: local ${job.id}` : `Job URL: ${prUrl}`}
@@ -38,7 +47,7 @@ ${projectedReview
 \n[Authoritative execution context]
 Job objective: ${job.objective ?? '(none recorded)'}
 Plan: ${task.planningDecisionId ? `${task.planningDecisionId} (round ${task.planningRound ?? 'unknown'})` : 'directly created Task'}
-Task attempt/execution: ${task.attempt}/${task.maxAttempts} / ${task.executionId}
+${interactiveContext}Task attempt/execution: ${task.attempt}/${task.maxAttempts} / ${task.executionId}
 Dependencies: ${task.dependencies.length ? task.dependencies.join(', ') : 'none'}
 ${task.attempt > 1 || task.error ? `Retry summary: prior error=${task.error ?? 'none'}; prior generations=${(task.executionHistory ?? []).map(item => `${item.id}@${item.attempt}`).join(', ') || 'none'}` : 'Retry summary: first attempt'}
 SQLite/RelayStore and the canonical Mermaid Graphs own lifecycle, merge, recovery, and completion decisions. Do not perform Relay-owned merge or completion actions from this worker.

package/dist/projected-store.js

@@ -218,6 +218,23 @@ export class ProjectedDurableStore {
     async finishExecutionProcess(jobId, taskId, executionId) {
         await this.relay.finishExecutionProcess(jobId, taskId, executionId);
     }
+    async mutateJob(jobId, mutation) {
+        if (!this.relay.mutateJob)
+            throw new Error("Relay store does not support atomic job mutation");
+        return this.relay.mutateJob(jobId, mutation);
+    }
+    async markEventProcessed(eventId, stream, sequence) {
+        return this.relay.markEventProcessed(eventId, stream ?? null, sequence ?? null);
+    }
+    async recordHostInvocationEvent(delivery, outcome, fingerprint) {
+        await this.relay.recordHostInvocationEvent?.(delivery, outcome, fingerprint);
+    }
+    async hasHostInvocationDecision(jobId, taskId, invocationId, fingerprint) {
+        return await this.relay.hasHostInvocationDecision?.(jobId, taskId, invocationId, fingerprint) ?? false;
+    }
+    async recordHostInvocationDecision(delivery, fingerprint) {
+        return await this.relay.recordHostInvocationDecision?.(delivery, fingerprint) ?? { outcome: 'ignored', reason: 'interactive_invocations_unsupported' };
+    }
     /** Ingest trusted GitHub records without echoing them back through the projection outbox. */
     async hydrate(job) {
         await this.relay.ingestJobSnapshot(structuredClone(job));

package/dist/reconciler-runtime.js

@@ -10,6 +10,8 @@ import { acceptedReportedTag, eventDataWithoutTag } from './task-tag.js';
 import { rearmTerminalEventDeadline } from './terminal-event-watchdog.js';
 import { createWorkerStartAck } from './worker-start-ack.js';
 import { monitorExecutionProcess } from './execution-process-tracker.js';
+import { HostInteractiveInvocationCoordinator, hostInvocationPorts } from './interactive-invocation.js';
+import { resumeInteractiveTask } from './interactive-resume.js';
 export function executionEventSource(jobId, taskId, executionId) { return `job/${jobId}/task/${taskId}/execution/${executionId}`; }
 function eventSourceId(event) { return typeof event.source?.id === 'string' ? event.source.id : undefined; }
 function executionIdFromSource(sourceId, jobId, taskId) {
@@ -40,12 +42,14 @@ export class ReconcilerRuntimeBase {
     startAckCleanups = new Set();
     taskTransitions;
     eventCoordinator;
+    hostInvocations;
     detachedReconciles = new Set();
     workflowEffects = new WorkflowEffectExecutor();
     reconciling = false;
     constructor(store, options) {
         this.store = store;
         this.options = options;
+        this.hostInvocations = new HostInteractiveInvocationCoordinator({ store: hostInvocationPorts(store), emit: event => this.emit(event) });
         this.taskTransitions = new DurableTaskTransitionRuntime(store);
         this.eventCoordinator = new ReconcileCoordinator(async (jobId, signals) => {
             let shouldReconcile = false;
@@ -77,6 +81,8 @@ export class ReconcilerRuntimeBase {
             }
         });
     }
+    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}` }; }
+    bindInteractiveInvocation(jobId, task, executionId, invocationId, revision) { return this.hostInvocations.bind(jobId, task, executionId, invocationId, revision); }
     async applyJobEffectOutcomes(job, outcomes) {
         await applyJobEffectOutcomes(this.store, event => this.emit(event), job, outcomes);
     }
@@ -106,6 +112,8 @@ export class ReconcilerRuntimeBase {
         }
         if (['review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type))
             return this.applyReviewEvent(event);
+        if (event.type === 'task.interactive_decision')
+            return this.applyHostInvocationEvent(event);
         if (event.type === 'github.webhook')
             return { applied: true, reconcile: false, reason: 'github.audit_only' };
         if (event.type === 'job.wake')
@@ -393,6 +401,8 @@ export class ReconcilerRuntimeBase {
                     return false;
                 if (task.agentName === 'reviewer' && event.type === 'task.completed')
                     return false;
+                if (event.type === 'task.completed' && task.interactiveInvocation?.status !== undefined && task.interactiveInvocation.status !== 'approved')
+                    return false; // current interactive revision requires durable approval
                 const modelBacked = task.adapter === 'codex' || task.adapter === 'chatgpt';
                 if (!trustedInternal && modelBacked && !this.isCorrelatedWorkerEvent(task, event)) {
                     const eventExecutionId = executionIdFromSource(eventSourceId(event), _job.id, task.id);

package/dist/reconciler.js

@@ -31,6 +31,7 @@ import { reconcileLocalGitCompletion } from './local-merge-delivery.js';
 import { repairLegacyOrchestrators } from './legacy-orchestrator-repair.js';
 import { launchPlanExecution } from './planner-runtime.js';
 import { classifyFailure, errorMessage, observability, withObservabilityCorrelation } from './observability.js';
+import { recoverInteractiveDecisions } from './interactive-resume.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export class Reconciler extends ReconcilerReviewBase {
@@ -94,6 +95,7 @@ export class Reconciler extends ReconcilerReviewBase {
                 return job;
             await recoverExpiredExecutions(job, now, this.executionRecoveryPorts(job));
             await repairLegacyOrchestrators(jobId, now, { store: this.store, owner: this.options.owner, emit: event => this.emit(event) });
+            await recoverInteractiveDecisions(this.store, jobId);
             await this.recoverPlannerChildren(job);
             await retryPendingPlannerUnblocks({
                 store: this.store,

package/dist/relay-store.js

@@ -5,6 +5,7 @@ import { readdir } from 'node:fs/promises';
 import { recordPublicationInDatabase, loadPublicationFromDatabase, listPublicationEventsFromDatabase } from './publication-store.js';
 import { observability } from './observability.js';
 import { migrateLegacyJobPrNumbers, normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
+import { hostInvocationTablesSql, recordHostInvocationEvent, hasHostInvocationDecision, recordHostInvocationDecision } from './host-invocation-store.js';
 import { ProjectionOutbox, SCHEMA_VERSION, logicalOperationKey, } from './projection-outbox.js';
 function newerRecord(local, remote) {
     if (!local)
@@ -97,6 +98,7 @@ export class SQLiteRelayStore {
         ended_at TEXT,
         PRIMARY KEY(job_id,task_id,execution_id)
       );
+      ${hostInvocationTablesSql}
       ${ProjectionOutbox.createTableSql()}
       ${ProjectionOutbox.createIndexSql()}
     `);
@@ -298,6 +300,15 @@ export class SQLiteRelayStore {
         this.db.prepare('UPDATE execution_process SET ended_at=COALESCE(ended_at,?) WHERE job_id=? AND task_id=? AND execution_id=?')
             .run(at, jobId, taskId, executionId);
     }
+    async recordHostInvocationEvent(delivery, outcome, fingerprint) {
+        recordHostInvocationEvent(this.db, delivery, outcome, fingerprint);
+    }
+    async hasHostInvocationDecision(jobId, taskId, invocationId, fingerprint) {
+        return hasHostInvocationDecision(this.db, jobId, taskId, invocationId, fingerprint);
+    }
+    async recordHostInvocationDecision(delivery, fingerprint) {
+        return recordHostInvocationDecision(this.db, delivery, fingerprint, (job, at) => this.writeJobSnapshot(job, at));
+    }
     async markEventProcessed(eventId, stream = null, sequence = null) {
         const result = this.db.prepare(`
       INSERT OR IGNORE INTO event_receipt(event_id,stream,sequence,received_at) VALUES(?,?,?,?)

package/dist/troubleshooter.js

@@ -54,7 +54,7 @@ export function pendingTroubleshooterTasks(job) {
             failedWork: task.state === 'FAILED',
             ordinaryWork: task.kind !== 'planner' && task.agentName !== 'troubleshooter',
             currentRun: belongsToCurrentRun(job, task),
-            needsRecovery: true,
+            needsRecovery: !(task.state === 'BLOCKED' && (Boolean(task.unblock) || Boolean(task.interactiveInvocation))),
             idUnused: !existing.has(id),
             noRecoveryBarrier: !hasRecoveryBarrier(job, task),
         }, () => { create = true; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.83",
+  "version": "2.0.84",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/workflow/interactive-invocation.mmd

@@ -0,0 +1,37 @@
+flowchart LR
+%% relay: initial awaiting_decision
+awaiting_decision["state: awaiting_decision"]
+changes["state: changes_requested"]
+approved["state: approved"]
+context["guard: currentInvocation"]
+awaiting["guard: awaitingDecision"]
+revision["guard: currentRevision"]
+duplicateChanges["guard: duplicateDelivery"]
+duplicateApproved["guard: duplicateDelivery"]
+decisionKind["guard: changesRequested"]
+requestChanges["action: interactive.requestChanges"]
+approve["action: interactive.approve"]
+wake["action: interactive.wakeWorker"]
+wakeChanges["action: interactive.wakeWorker"]
+
+awaiting_decision -->|on: task.interactive_decision| context
+changes -->|on: task.interactive_decision| duplicateChanges
+approved -->|on: task.interactive_decision| duplicateApproved
+context -->|true| awaiting
+context -->|false| awaiting_decision
+awaiting -->|true| revision
+awaiting -->|false| awaiting_decision
+revision -->|true| decisionKind
+revision -->|false| awaiting_decision
+decisionKind -->|true| requestChanges
+decisionKind -->|false| approve
+requestChanges --> wakeChanges
+wakeChanges -->|to: changes_requested| changes
+approve --> wake
+wake -->|to: approved| approved
+duplicateChanges -->|true| wakeChanges
+duplicateChanges -->|false| changes
+duplicateApproved -->|true| wake
+duplicateApproved -->|false| approved
+changes -->|on: task.interactive_recover| wakeChanges
+approved -->|on: task.interactive_recover| wake