vgxness 0.1.0

package/dist/runs/run-service.js

@@ -0,0 +1,713 @@
+import { evaluatePermission } from '../permissions/policy-evaluator.js';
+import { planExecutionIsolation } from './execution-planning.js';
+import { evaluateOperationRetry as evaluateOperationRetryPolicy } from './operation-retry.js';
+import { RunRepository } from './repositories/runs.js';
+import { buildRunInsights, buildRunOperatorResumePlan } from './run-insights.js';
+const preflightSafety = {
+    operationExecuted: false,
+    executorInvoked: false,
+    executesProvider: false,
+    writesProviderConfig: false,
+    createsSandbox: false,
+    createsWorktree: false,
+};
+const resumeGateSafety = {
+    readOnly: true,
+    preflightExecuted: false,
+    retryAdmitted: false,
+    executorInvoked: false,
+    operationExecuted: false,
+    writesProviderConfig: false,
+    createsSandbox: false,
+    createsWorktree: false,
+};
+export class RunService {
+    runs;
+    constructor(database) {
+        this.runs = new RunRepository(database);
+    }
+    createRun(input) { return this.runs.create(input); }
+    getRun(id) { return this.runs.getDetails(id); }
+    getRunInsights(id) {
+        const details = this.runs.getDetails(id);
+        return details.ok ? { ok: true, value: buildRunInsights(details.value) } : details;
+    }
+    getRunOperatorResumePlan(id) {
+        const details = this.runs.getDetails(id);
+        return details.ok ? { ok: true, value: buildRunOperatorResumePlan(details.value) } : details;
+    }
+    listRuns(filters = {}) { return this.runs.list(filters); }
+    appendEvent(input) { return this.runs.appendEvent(input); }
+    appendEvidence(input) { return this.runs.appendEvent({ ...input, kind: 'evidence' }); }
+    appendCheckpoint(input) { return this.runs.appendCheckpoint(input); }
+    updateFinalStatus(input) { return this.runs.updateFinalStatus(input); }
+    listApprovals(runId) { return this.runs.listApprovals(runId); }
+    listOperationAttempts(runId) { return this.runs.listOperationAttempts(runId); }
+    getApproval(id) { return this.runs.getApproval(id); }
+    resolveApproval(input) { return this.runs.resolveApproval(input); }
+    abandonReservedOperationAttempt(input) { return this.runs.abandonOperationAttempt(input); }
+    evaluateOperationRetry(input) {
+        const approval = this.runs.getApproval(input.approvalId);
+        if (!approval.ok)
+            return { ok: false, error: approval.error };
+        const details = this.runs.getDetails(approval.value.runId);
+        if (!details.ok)
+            return { ok: false, error: details.error };
+        const attempts = details.value.operationAttempts.filter((attempt) => attempt.approvalId === input.approvalId);
+        return {
+            ok: true,
+            value: evaluateOperationRetryPolicy(input.policy === undefined ? { attempts } : { attempts, policy: input.policy }),
+        };
+    }
+    getRunResumeOrchestrationPlan(input) {
+        const approval = this.runs.getApproval(input.approvalId);
+        if (!approval.ok)
+            return approval;
+        const details = this.runs.getDetails(approval.value.runId);
+        if (!details.ok)
+            return details;
+        const blockers = [];
+        if (approval.value.status !== 'approved') {
+            blockers.push({
+                code: 'approval-not-approved',
+                message: `Approval must be approved before manual continuation guidance is available: ${approval.value.status}`,
+                relatedId: approval.value.id,
+            });
+        }
+        const permissionEvent = details.value.events.find((event) => event.id === approval.value.decisionEventId);
+        if (permissionEvent === undefined || !isAskPermissionEvent(permissionEvent)) {
+            blockers.push({
+                code: 'missing-permission-event',
+                message: 'Approval permission-decision event is missing or is not an ask decision',
+                relatedId: approval.value.decisionEventId,
+            });
+        }
+        const pendingExecutionEvent = details.value.events.find((event) => isPendingExecutionEventForApproval(event, approval.value.id));
+        let operation;
+        if (pendingExecutionEvent === undefined) {
+            blockers.push({
+                code: 'missing-pending-operation',
+                message: 'Approval has no pending operation-execution event to reconstruct',
+                relatedId: approval.value.id,
+            });
+        }
+        else {
+            operation = operationFromPendingExecution(pendingExecutionEvent.payload);
+            if (operation === undefined) {
+                blockers.push({
+                    code: 'operation-metadata-incomplete',
+                    message: 'Pending operation metadata is incomplete and cannot be planned',
+                    relatedId: pendingExecutionEvent.id,
+                });
+            }
+        }
+        const retryDecision = operation === undefined
+            ? null
+            : evaluateOperationRetryPolicy(input.policy === undefined
+                ? { attempts: details.value.operationAttempts.filter((attempt) => attempt.approvalId === approval.value.id) }
+                : { attempts: details.value.operationAttempts.filter((attempt) => attempt.approvalId === approval.value.id), policy: input.policy });
+        if (retryDecision !== null && !retryDecision.allowed) {
+            const relatedId = retryDecision.latestAttempt?.id ?? retryDecision.activeAttempt?.id;
+            blockers.push({
+                code: 'retry-blocked',
+                message: retryDecision.reason,
+                ...(relatedId === undefined ? {} : { relatedId }),
+            });
+        }
+        return {
+            ok: true,
+            value: {
+                kind: 'run-resume-orchestration-plan',
+                version: 1,
+                run: {
+                    id: details.value.id,
+                    project: details.value.project,
+                    status: details.value.status,
+                    workflow: details.value.workflow,
+                    phase: details.value.phase,
+                },
+                approval: {
+                    id: approval.value.id,
+                    runId: approval.value.runId,
+                    status: approval.value.status,
+                    decisionEventId: approval.value.decisionEventId,
+                },
+                operation: operation === undefined ? null : summarizeOperation(operation),
+                retryDecision,
+                blockers,
+                nextAction: resumeGateNextAction(approval.value, details.value, blockers),
+                manualNextCommands: resumeGateManualNextCommands(approval.value, details.value, operation),
+                safety: resumeGateSafety,
+            },
+        };
+    }
+    admitOperationRetryAttempt(input) {
+        const approval = this.runs.getApproval(input.approvalId);
+        if (!approval.ok)
+            return approval;
+        if (approval.value.status !== 'approved')
+            return validationFailure(`Only approved approvals can admit retry attempts: ${approval.value.status}`);
+        const details = this.runs.getDetails(approval.value.runId);
+        if (!details.ok)
+            return details;
+        const permissionEvent = details.value.events.find((event) => event.id === approval.value.decisionEventId);
+        if (permissionEvent === undefined)
+            return validationFailure('Approval permission-decision event is missing');
+        if (!isAskPermissionEvent(permissionEvent))
+            return validationFailure('Approval is not linked to an ask permission decision');
+        const pendingExecutionEvent = details.value.events.find((event) => isPendingExecutionEventForApproval(event, approval.value.id));
+        if (pendingExecutionEvent === undefined)
+            return validationFailure('Approved approval has no retryable pending operation event');
+        const operation = operationFromPendingExecution(pendingExecutionEvent.payload);
+        if (operation === undefined)
+            return validationFailure('Pending operation metadata is incomplete and cannot be retried');
+        const attempts = details.value.operationAttempts.filter((attempt) => attempt.approvalId === approval.value.id);
+        const retryDecision = evaluateOperationRetryPolicy(input.policy === undefined ? { attempts } : { attempts, policy: input.policy });
+        if (!retryDecision.allowed || retryDecision.reasonCode !== 'status_allowed_by_policy')
+            return validationFailure(retryDecision.reason);
+        const reserved = this.runs.reserveOperationAttempt({
+            runId: approval.value.runId,
+            approvalId: approval.value.id,
+            decisionEventId: permissionEvent.id,
+            pendingExecutionEventId: pendingExecutionEvent.id,
+            category: operation.category,
+            operation: operation.operation,
+            operationMetadata: operationMetadata(operation),
+            executorName: input.executorName ?? 'retry-admission',
+        });
+        if (!reserved.ok)
+            return reserved;
+        const admissionEvent = this.runs.appendEvent({
+            runId: approval.value.runId,
+            kind: 'operation-execution',
+            title: `Retry attempt admitted: ${operation.category} ${operation.operation}`,
+            payload: executionPayload(operation, reserved.value.executorName, 'pending-approval', {
+                admissionStatus: 'reserved',
+                retryAdmission: true,
+                attemptId: reserved.value.id,
+                attemptSequence: reserved.value.attemptSequence,
+                approvalId: approval.value.id,
+                decisionEventId: permissionEvent.id,
+                originalPendingExecutionEventId: pendingExecutionEvent.id,
+                retryPolicy: retryDecision.policy,
+                retryReasonCode: retryDecision.reasonCode,
+                retryReason: retryDecision.reason,
+                evaluatedAttemptCount: retryDecision.evaluatedAttemptCount,
+                retryableStatuses: [...retryDecision.retryableStatuses],
+                executorInvoked: false,
+                operationExecuted: false,
+            }),
+            relatedType: 'operation-attempt',
+            relatedId: reserved.value.id,
+        });
+        if (!admissionEvent.ok)
+            return { ok: false, error: admissionEvent.error };
+        return { ok: true, value: { approval: approval.value, retryDecision, permissionEvent, pendingExecutionEvent, attempt: reserved.value, admissionEvent: admissionEvent.value } };
+    }
+    planOperationExecution(input) {
+        const permission = this.evaluatePermissionForRun(input);
+        if (!permission.ok)
+            return permission;
+        const plan = planExecutionIsolation({
+            operation: input,
+            decision: permission.value.decision,
+            ...(input.gitBoundaryInspector === undefined ? {} : { gitBoundaryInspector: input.gitBoundaryInspector }),
+        });
+        const sandboxDecision = sandboxDecisionSummary(plan.sandbox);
+        const planEvent = this.runs.appendEvent({
+            runId: input.runId,
+            kind: 'execution-plan',
+            title: `Execution plan: ${input.category} ${input.operation}`,
+            payload: {
+                runId: input.runId,
+                requestedOperation: operationMetadata(input),
+                decisionEventId: permission.value.event.id,
+                approvalId: permission.value.approval?.id ?? null,
+                plan: plan,
+                ...(sandboxDecision === undefined ? {} : { sandboxDecision: sandboxDecision }),
+                operationExecuted: false,
+                executorInvoked: false,
+                executesProvider: false,
+                writesProviderConfig: false,
+                createsSandbox: false,
+                createsWorktree: false,
+                timestamp: new Date().toISOString(),
+            },
+            relatedType: 'operation',
+            relatedId: input.operation,
+        });
+        if (!planEvent.ok)
+            return { ok: false, error: planEvent.error };
+        return { ok: true, value: { ...permission.value, plan, planEvent: planEvent.value } };
+    }
+    preflightOperation(input) {
+        const planned = this.planOperationExecution(input);
+        if (!planned.ok)
+            return planned;
+        const { decision, event, approval, plan, planEvent } = planned.value;
+        const audit = { permissionEventId: event.id, planEventId: planEvent.id };
+        if (approval !== undefined)
+            audit.approvalId = approval.id;
+        const sandbox = plan.sandbox;
+        const sandboxRejected = sandbox?.decision === 'rejected';
+        const sandboxReason = sandboxRejected
+            ? [{ code: sandbox.reason ?? 'sandbox_boundary', message: sandbox.audit.validationSummary }]
+            : [];
+        return {
+            ok: true,
+            value: {
+                outcome: sandboxRejected ? 'blocked' : preflightOutcome(decision),
+                decision,
+                reasons: [...sandboxReason, { code: decision.reason, message: decision.message }],
+                permissionEvent: event,
+                ...(approval === undefined ? {} : { approval }),
+                plan,
+                planEvent,
+                audit,
+                eligibleForFutureExecution: plan.executable && !sandboxRejected,
+                safety: preflightSafety,
+            },
+        };
+    }
+    resumeApprovedOperation(input) {
+        const approval = this.runs.getApproval(input.approvalId);
+        if (!approval.ok)
+            return approval;
+        if (approval.value.status !== 'approved')
+            return validationFailure(`Only approved approvals can be resumed: ${approval.value.status}`);
+        const details = this.runs.getDetails(approval.value.runId);
+        if (!details.ok)
+            return details;
+        const permissionEvent = details.value.events.find((event) => event.id === approval.value.decisionEventId);
+        if (permissionEvent === undefined)
+            return validationFailure('Approval permission-decision event is missing');
+        if (!isAskPermissionEvent(permissionEvent))
+            return validationFailure('Approval is not linked to an ask permission decision');
+        const pendingExecutionEvent = details.value.events.find((event) => isPendingExecutionEventForApproval(event, approval.value.id));
+        if (pendingExecutionEvent === undefined)
+            return validationFailure('Approved approval has no resumable pending operation event');
+        const operation = operationFromPendingExecution(pendingExecutionEvent.payload);
+        if (operation === undefined)
+            return validationFailure('Pending operation metadata is incomplete and cannot be resumed');
+        const retry = this.evaluateOperationRetry({ approvalId: approval.value.id });
+        if (!retry.ok)
+            return retry;
+        if (!retry.value.allowed)
+            return validationFailure(retry.value.reason);
+        const reserved = this.runs.reserveOperationAttempt({
+            runId: approval.value.runId,
+            approvalId: approval.value.id,
+            decisionEventId: permissionEvent.id,
+            pendingExecutionEventId: pendingExecutionEvent.id,
+            category: operation.category,
+            operation: operation.operation,
+            operationMetadata: operationMetadata(operation),
+            executorName: input.executor.name,
+        });
+        if (!reserved.ok)
+            return reserved;
+        const executed = input.executor.execute({ runId: approval.value.runId, operation });
+        if (!executed.ok) {
+            const error = { code: executed.error.code, message: executed.error.message };
+            const attempt = this.runs.completeOperationAttempt({ attemptId: reserved.value.id, status: 'failed', error });
+            if (!attempt.ok)
+                return attempt;
+            const executionEvent = this.runs.appendEvent({
+                runId: approval.value.runId,
+                kind: 'operation-execution',
+                title: `Approved operation failed: ${operation.category} ${operation.operation}`,
+                payload: executionPayload(operation, input.executor.name, 'failed', {
+                    attemptId: attempt.value.id,
+                    decisionEventId: permissionEvent.id,
+                    approvalId: approval.value.id,
+                    originalPendingExecutionEventId: pendingExecutionEvent.id,
+                    originalDecision: 'ask',
+                    approvalStatus: 'approved',
+                    policyReevaluated: false,
+                    resumedFromApprovalId: approval.value.id,
+                    executorInvoked: true,
+                    error,
+                }),
+                relatedType: 'approval',
+                relatedId: approval.value.id,
+            });
+            if (!executionEvent.ok)
+                return { ok: false, error: executionEvent.error };
+            const linkedAttempt = this.runs.attachAttemptResultEvent(attempt.value.id, executionEvent.value.id);
+            return { ok: true, value: { approval: approval.value, permissionEvent, pendingExecutionEvent, attempt: linkedAttempt.ok ? linkedAttempt.value : attempt.value, executionEvent: executionEvent.value, status: 'failed' } };
+        }
+        const output = executed.value.output;
+        const attempt = this.runs.completeOperationAttempt({ attemptId: reserved.value.id, status: 'succeeded', ...(output === undefined ? {} : { output }) });
+        if (!attempt.ok)
+            return attempt;
+        const executionEvent = this.runs.appendEvent({
+            runId: approval.value.runId,
+            kind: 'operation-execution',
+            title: `Approved operation executed: ${operation.category} ${operation.operation}`,
+            payload: executionPayload(operation, input.executor.name, 'succeeded', {
+                attemptId: attempt.value.id,
+                decisionEventId: permissionEvent.id,
+                approvalId: approval.value.id,
+                originalPendingExecutionEventId: pendingExecutionEvent.id,
+                originalDecision: 'ask',
+                approvalStatus: 'approved',
+                policyReevaluated: false,
+                resumedFromApprovalId: approval.value.id,
+                executorInvoked: true,
+                output: output ?? null,
+            }),
+            relatedType: 'approval',
+            relatedId: approval.value.id,
+        });
+        if (!executionEvent.ok)
+            return { ok: false, error: executionEvent.error };
+        const linkedAttempt = this.runs.attachAttemptResultEvent(attempt.value.id, executionEvent.value.id);
+        return { ok: true, value: { approval: approval.value, permissionEvent, pendingExecutionEvent, attempt: linkedAttempt.ok ? linkedAttempt.value : attempt.value, executionEvent: executionEvent.value, status: 'succeeded', ...(output === undefined ? {} : { output }) } };
+    }
+    executeOperation(input) {
+        const permission = this.evaluatePermissionForRun({ runId: input.runId, ...input.operation });
+        if (!permission.ok)
+            return permission;
+        if (permission.value.decision.decision === 'deny') {
+            const executionEvent = this.runs.appendEvent({
+                runId: input.runId,
+                kind: 'operation-execution',
+                title: `Operation blocked: ${input.operation.category} ${input.operation.operation}`,
+                payload: executionPayload(input.operation, input.executor.name, 'blocked', {
+                    decisionEventId: permission.value.event.id,
+                    decision: 'deny',
+                    reason: permission.value.decision.reason,
+                    message: permission.value.decision.message,
+                    executorInvoked: false,
+                }),
+                relatedType: 'operation',
+                relatedId: input.operation.operation,
+            });
+            return executionEvent.ok
+                ? { ok: true, value: { decision: permission.value.decision, permissionEvent: permission.value.event, executionEvent: executionEvent.value, status: 'blocked' } }
+                : { ok: false, error: executionEvent.error };
+        }
+        if (permission.value.decision.decision === 'ask') {
+            const executionEvent = this.runs.appendEvent({
+                runId: input.runId,
+                kind: 'operation-execution',
+                title: `Operation pending approval: ${input.operation.category} ${input.operation.operation}`,
+                payload: executionPayload(input.operation, input.executor.name, 'pending-approval', {
+                    decisionEventId: permission.value.event.id,
+                    approvalId: permission.value.approval?.id ?? null,
+                    decision: 'ask',
+                    reason: permission.value.decision.reason,
+                    message: permission.value.decision.message,
+                    executorInvoked: false,
+                    operationExecuted: false,
+                }),
+                relatedType: 'operation',
+                relatedId: input.operation.operation,
+            });
+            return executionEvent.ok
+                ? { ok: true, value: { decision: permission.value.decision, permissionEvent: permission.value.event, executionEvent: executionEvent.value, status: 'pending-approval', ...(permission.value.approval === undefined ? {} : { approval: permission.value.approval }) } }
+                : { ok: false, error: executionEvent.error };
+        }
+        const executed = input.executor.execute({ runId: input.runId, operation: input.operation });
+        if (!executed.ok) {
+            const executionEvent = this.runs.appendEvent({
+                runId: input.runId,
+                kind: 'operation-execution',
+                title: `Operation failed: ${input.operation.category} ${input.operation.operation}`,
+                payload: executionPayload(input.operation, input.executor.name, 'failed', {
+                    decisionEventId: permission.value.event.id,
+                    decision: 'allow',
+                    executorInvoked: true,
+                    error: { code: executed.error.code, message: executed.error.message },
+                }),
+                relatedType: 'operation',
+                relatedId: input.operation.operation,
+            });
+            return executionEvent.ok
+                ? { ok: true, value: { decision: permission.value.decision, permissionEvent: permission.value.event, executionEvent: executionEvent.value, status: 'failed' } }
+                : { ok: false, error: executionEvent.error };
+        }
+        const output = executed.value.output;
+        const executionEvent = this.runs.appendEvent({
+            runId: input.runId,
+            kind: 'operation-execution',
+            title: `Operation executed: ${input.operation.category} ${input.operation.operation}`,
+            payload: executionPayload(input.operation, input.executor.name, 'succeeded', {
+                decisionEventId: permission.value.event.id,
+                decision: 'allow',
+                executorInvoked: true,
+                output: output ?? null,
+            }),
+            relatedType: 'operation',
+            relatedId: input.operation.operation,
+        });
+        return executionEvent.ok
+            ? { ok: true, value: { decision: permission.value.decision, permissionEvent: permission.value.event, executionEvent: executionEvent.value, status: 'succeeded', ...(output === undefined ? {} : { output }) } }
+            : { ok: false, error: executionEvent.error };
+    }
+    evaluatePermissionForRun(input) {
+        const run = this.runs.getById(input.runId);
+        if (!run.ok)
+            return { ok: false, error: run.error };
+        const decision = evaluatePermission(input);
+        const timestamp = new Date().toISOString();
+        const agent = input.agent === undefined
+            ? { id: run.value.selectedAgentId }
+            : { id: input.agent.id, name: input.agent.name, mode: input.agent.mode };
+        if (decision.decision === 'ask') {
+            const prior = this.findResolvedMatchingApproval(input, agent);
+            if (!prior.ok)
+                return prior;
+            if (prior.value !== undefined) {
+                const reusedDecision = prior.value.approval.status === 'approved'
+                    ? { ...decision, decision: 'allow', message: `Previously approved approval ${prior.value.approval.id} authorizes this exact operation.` }
+                    : { ...decision, decision: 'deny', reason: 'default_policy', message: `Previously ${prior.value.approval.status} approval ${prior.value.approval.id} denies this exact operation.` };
+                const event = this.runs.appendEvent({
+                    runId: input.runId,
+                    kind: 'permission-decision',
+                    title: `Permission ${reusedDecision.decision}: ${input.category} ${input.operation}`,
+                    payload: {
+                        runId: input.runId,
+                        category: input.category,
+                        operation: input.operation,
+                        requestedOperation: operationMetadata(input),
+                        agent,
+                        decision: reusedDecision.decision,
+                        reasons: [{ code: reusedDecision.reason, message: reusedDecision.message }],
+                        requiresHumanApproval: false,
+                        approvalStatus: prior.value.approval.status,
+                        reusedApprovalId: prior.value.approval.id,
+                        originalDecisionEventId: prior.value.event.id,
+                        approvalMatched: true,
+                        timestamp,
+                    },
+                    relatedType: 'approval',
+                    relatedId: prior.value.approval.id,
+                });
+                return event.ok
+                    ? { ok: true, value: { decision: reusedDecision, event: event.value, approval: prior.value.approval } }
+                    : { ok: false, error: event.error };
+            }
+        }
+        const event = this.runs.appendEvent({
+            runId: input.runId,
+            kind: 'permission-decision',
+            title: `Permission ${decision.decision}: ${input.category} ${input.operation}`,
+            payload: {
+                runId: input.runId,
+                category: input.category,
+                operation: input.operation,
+                requestedOperation: operationMetadata(input),
+                agent,
+                decision: decision.decision,
+                reasons: [{ code: decision.reason, message: decision.message }],
+                requiresHumanApproval: decision.decision === 'ask',
+                approvalStatus: decision.decision === 'ask' ? 'pending' : 'not-required',
+                timestamp,
+            },
+            relatedType: 'permission',
+            relatedId: input.category,
+        });
+        if (!event.ok)
+            return { ok: false, error: event.error };
+        if (decision.decision !== 'ask')
+            return { ok: true, value: { decision, event: event.value } };
+        const approval = this.runs.createApproval({ runId: input.runId, decisionEventId: event.value.id });
+        return approval.ok
+            ? { ok: true, value: { decision, event: event.value, approval: approval.value } }
+            : { ok: false, error: approval.error };
+    }
+    findResolvedMatchingApproval(input, agent) {
+        const details = this.runs.getDetails(input.runId);
+        if (!details.ok)
+            return details;
+        const requestedOperation = operationMetadata(input);
+        const resolved = details.value.approvals
+            .filter((approval) => approval.status === 'approved' || approval.status === 'rejected' || approval.status === 'cancelled')
+            .map((approval) => ({ approval, event: details.value.events.find((event) => event.id === approval.decisionEventId) }))
+            .filter((entry) => entry.event !== undefined && isAskPermissionEvent(entry.event))
+            .filter((entry) => approvalEventMatches(entry.event, input, requestedOperation, agent))
+            .sort((left, right) => (right.approval.resolvedAt ?? right.approval.requestedAt).localeCompare(left.approval.resolvedAt ?? left.approval.requestedAt));
+        return { ok: true, value: resolved[0] };
+    }
+}
+function preflightOutcome(decision) {
+    if (decision.decision === 'allow')
+        return 'allowed';
+    if (decision.decision === 'deny')
+        return 'blocked';
+    return 'approval-needed';
+}
+function executionPayload(operation, executorName, status, extra) {
+    return {
+        status,
+        executorName,
+        requestedOperation: operationMetadata(operation),
+        input: operation.input ?? null,
+        timestamp: new Date().toISOString(),
+        ...extra,
+    };
+}
+function summarizeOperation(operation) {
+    return {
+        category: operation.category,
+        operation: operation.operation,
+        ...(operation.input === undefined ? {} : { input: operation.input }),
+    };
+}
+function resumeGateNextAction(approval, details, blockers) {
+    const approvalBlocker = blockers.find((blocker) => blocker.code === 'approval-not-approved');
+    if (approvalBlocker !== undefined) {
+        return {
+            type: 'resolve-approval',
+            command: `runs approve --approval ${approval.id}`,
+            reason: approvalBlocker.message,
+        };
+    }
+    const missingContext = blockers.find((blocker) => blocker.code === 'missing-permission-event' || blocker.code === 'missing-pending-operation' || blocker.code === 'operation-metadata-incomplete');
+    if (missingContext !== undefined) {
+        return {
+            type: 'inspect-run',
+            command: `runs resume-inspect --id ${details.id}`,
+            reason: missingContext.message,
+        };
+    }
+    const retryBlocker = blockers.find((blocker) => blocker.code === 'retry-blocked');
+    if (retryBlocker !== undefined) {
+        return {
+            type: 'retry-check',
+            command: `runs retry-check --approval ${approval.id}`,
+            reason: retryBlocker.message,
+        };
+    }
+    return {
+        type: 'manual-recovery',
+        command: `runs retry-check --approval ${approval.id}`,
+        reason: 'The operator may manually continue after reviewing retry-check guidance; no execution is performed by this plan.',
+    };
+}
+function resumeGateManualNextCommands(approval, details, operation) {
+    const commands = [`runs resume-inspect --id ${details.id}`, `runs retry-check --approval ${approval.id}`];
+    if (approval.status !== 'approved')
+        commands.unshift(`runs approve --approval ${approval.id}`);
+    if (operation !== undefined)
+        commands.push(`Review operation manually: ${operation.category} ${operation.operation}`);
+    return commands;
+}
+function operationMetadata(input) {
+    const metadata = { category: input.category, name: input.operation };
+    if (input.workspaceRoot !== undefined)
+        metadata.workspaceRoot = input.workspaceRoot;
+    if (input.targetPath !== undefined)
+        metadata.targetPath = input.targetPath;
+    if (input.providerToolName !== undefined)
+        metadata.providerToolName = input.providerToolName;
+    if (input.sandboxStrategy !== undefined)
+        metadata.sandboxStrategy = input.sandboxStrategy;
+    if (input.destructive !== undefined)
+        metadata.destructive = input.destructive;
+    if (input.external !== undefined)
+        metadata.external = input.external;
+    if (input.privileged !== undefined)
+        metadata.privileged = input.privileged;
+    if (input.ambiguous !== undefined)
+        metadata.ambiguous = input.ambiguous;
+    if (input.input !== undefined)
+        metadata.input = input.input;
+    return metadata;
+}
+function approvalEventMatches(event, input, requestedOperation, agent) {
+    if (!isObject(event.payload))
+        return false;
+    if (event.payload.runId !== input.runId)
+        return false;
+    if (event.payload.category !== input.category || event.payload.operation !== input.operation)
+        return false;
+    if (!jsonEqual(event.payload.requestedOperation, requestedOperation))
+        return false;
+    if (!jsonEqual(event.payload.agent, agent))
+        return false;
+    return true;
+}
+function jsonEqual(left, right) {
+    return stableJson(left ?? null) === stableJson(right ?? null);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (isObject(value))
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key] ?? null)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+function sandboxDecisionSummary(sandbox) {
+    if (sandbox === undefined)
+        return undefined;
+    return {
+        strategy: sandbox.strategy,
+        decision: sandbox.decision,
+        workspaceRoot: sandbox.workspaceRoot,
+        targetPath: sandbox.targetPath ?? null,
+        reason: sandbox.reason ?? null,
+        validationSummary: sandbox.audit.validationSummary,
+        gitBoundary: sandbox.gitBoundary,
+        providerConfigMutation: sandbox.providerConfigMutation,
+        createsWorktree: sandbox.createsWorktree,
+        executesProvider: sandbox.executesProvider,
+    };
+}
+function isAskPermissionEvent(event) {
+    return event.kind === 'permission-decision' && isObject(event.payload) && event.payload.decision === 'ask';
+}
+function isPendingExecutionEventForApproval(event, approvalId) {
+    return event.kind === 'operation-execution'
+        && isObject(event.payload)
+        && event.payload.status === 'pending-approval'
+        && event.payload.approvalId === approvalId;
+}
+function operationFromPendingExecution(payload) {
+    if (!isObject(payload))
+        return undefined;
+    const requestedOperation = payload.requestedOperation;
+    if (requestedOperation === undefined || !isObject(requestedOperation))
+        return undefined;
+    const requested = requestedOperation;
+    if (!isPermissionCategory(requested.category) || typeof requested.name !== 'string')
+        return undefined;
+    const operation = { category: requested.category, operation: requested.name };
+    if (typeof requested.workspaceRoot === 'string')
+        operation.workspaceRoot = requested.workspaceRoot;
+    if (typeof requested.targetPath === 'string')
+        operation.targetPath = requested.targetPath;
+    if (typeof requested.providerToolName === 'string')
+        operation.providerToolName = requested.providerToolName;
+    if (typeof requested.destructive === 'boolean')
+        operation.destructive = requested.destructive;
+    if (typeof requested.external === 'boolean')
+        operation.external = requested.external;
+    if (typeof requested.privileged === 'boolean')
+        operation.privileged = requested.privileged;
+    if (typeof requested.ambiguous === 'boolean')
+        operation.ambiguous = requested.ambiguous;
+    if ('input' in requested)
+        operation.input = requested.input;
+    if ('input' in payload)
+        operation.input = payload.input;
+    return operation;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPermissionCategory(value) {
+    return value === 'read'
+        || value === 'edit'
+        || value === 'shell'
+        || value === 'network'
+        || value === 'git'
+        || value === 'memory'
+        || value === 'external-directory'
+        || value === 'provider-tool'
+        || value === 'secrets';
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}