@exaudeus/workrail 1.5.0 → 1.5.2

package/dist/mcp/handlers/v2-advance-core.js

@@ -1,433 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeAdvanceCore = executeAdvanceCore;
-const neverthrow_1 = require("neverthrow");
-const index_js_1 = require("../../v2/durable-core/tokens/index.js");
-const workflow_js_1 = require("../../types/workflow.js");
-const snapshot_state_js_1 = require("../../v2/durable-core/projections/snapshot-state.js");
-const run_context_js_1 = require("../../v2/projections/run-context.js");
-const preferences_js_1 = require("../../v2/projections/preferences.js");
-const context_merge_js_1 = require("../../v2/durable-core/domain/context-merge.js");
-const jcs_js_1 = require("../../v2/durable-core/canonical/jcs.js");
-const notes_markdown_js_1 = require("../../v2/durable-core/domain/notes-markdown.js");
-const outputs_js_1 = require("../../v2/durable-core/domain/outputs.js");
-const ack_advance_append_plan_js_1 = require("../../v2/durable-core/domain/ack-advance-append-plan.js");
-const blocking_decision_js_1 = require("../../v2/durable-core/domain/blocking-decision.js");
-const reason_model_js_1 = require("../../v2/durable-core/domain/reason-model.js");
-const risk_policy_guardrails_js_1 = require("../../v2/durable-core/domain/risk-policy-guardrails.js");
-const recommendation_warnings_js_1 = require("../../v2/durable-core/domain/recommendation-warnings.js");
-const validation_criteria_validator_js_1 = require("../../v2/durable-core/domain/validation-criteria-validator.js");
-const validation_event_builder_js_1 = require("../../v2/durable-core/domain/validation-event-builder.js");
-const blocked_node_builder_js_1 = require("../../v2/durable-core/domain/blocked-node-builder.js");
-const decision_trace_builder_js_1 = require("../../v2/durable-core/domain/decision-trace-builder.js");
-const validation_engine_js_1 = require("../../application/services/validation-engine.js");
-const enhanced_loop_validator_js_1 = require("../../application/services/enhanced-loop-validator.js");
-const workflow_compiler_js_1 = require("../../application/services/workflow-compiler.js");
-const workflow_interpreter_js_1 = require("../../application/services/workflow-interpreter.js");
-const v2_state_conversion_js_1 = require("./v2-state-conversion.js");
-const v2_context_budget_js_1 = require("./v2-context-budget.js");
-const with_timeout_js_1 = require("./shared/with-timeout.js");
-function nodeIdOf(mode) {
-    switch (mode.kind) {
-        case 'fresh': return mode.sourceNodeId;
-        case 'retry': return mode.blockedNodeId;
-    }
-}
-function snapshotOf(mode) {
-    switch (mode.kind) {
-        case 'fresh': return mode.snapshot;
-        case 'retry': return mode.blockedSnapshot;
-    }
-}
-function emitValidationOnSuccess(mode) {
-    switch (mode.kind) {
-        case 'fresh': return false;
-        case 'retry': return true;
-    }
-}
-function successNodeKind(mode) {
-    switch (mode.kind) {
-        case 'fresh': return undefined;
-        case 'retry': return 'step';
-    }
-}
-function partialEvent(fields) {
-    return fields;
-}
-function executeAdvanceCore(args) {
-    const { mode, truth, sessionId, runId, attemptId, workflowHash, inputContext, inputOutput, lock, pinnedWorkflow, ports } = args;
-    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
-    const currentNodeId = nodeIdOf(mode);
-    const snap = snapshotOf(mode);
-    const engineState = snap.enginePayload.engineState;
-    const pendingStep = derivePendingStepForMode(mode, engineState);
-    if (!pendingStep) {
-        return errAsync({ kind: 'no_pending_step' });
-    }
-    const validatedRes = validateAdvanceInputs({
-        truth, runId, currentNodeId, inputContext, inputOutput, pinnedWorkflow, pendingStep,
-    });
-    if (validatedRes.isErr())
-        return errAsync(validatedRes.error);
-    const v = validatedRes.value;
-    const validator = v.validationCriteria ? new validation_engine_js_1.ValidationEngine(new enhanced_loop_validator_js_1.EnhancedLoopValidator()) : null;
-    const validationRes = validator && v.notesMarkdown
-        ? neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(validator.validate(v.notesMarkdown, v.validationCriteria, v.mergedContext), 30000, 'ValidationEngine.validate'), (cause) => ({ kind: 'advance_apply_failed', message: String(cause) })).andThen((res) => {
-            if (res.isErr()) {
-                return (0, neverthrow_1.errAsync)({
-                    kind: 'advance_apply_failed',
-                    message: `ValidationEngineError: ${res.error.kind} (${res.error.message})`,
-                });
-            }
-            return (0, neverthrow_1.okAsync)(res.value);
-        })
-        : (0, neverthrow_1.okAsync)(undefined);
-    return validationRes.andThen((validation) => {
-        const outputRequirement = (0, validation_criteria_validator_js_1.getOutputRequirementStatusWithArtifactsV1)({
-            outputContract: v.outputContract,
-            artifacts: v.artifacts,
-            validationCriteria: v.validationCriteria,
-            notesMarkdown: v.notesMarkdown,
-            validation,
-        });
-        const reasonsRes = (0, blocking_decision_js_1.detectBlockingReasonsV1)({ outputRequirement });
-        if (reasonsRes.isErr()) {
-            return errAsync({ kind: 'invariant_violation', message: reasonsRes.error.message });
-        }
-        const reasons = reasonsRes.value;
-        const { blocking: effectiveReasons } = (0, risk_policy_guardrails_js_1.applyGuardrails)(v.riskPolicy, reasons);
-        const shouldBlockNow = effectiveReasons.length > 0 && (0, reason_model_js_1.shouldBlock)(v.autonomy, effectiveReasons);
-        const ctx = { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, inputOutput, pinnedWorkflow, engineState, pendingStep };
-        const computed = { reasons, effectiveReasons, outputRequirement, validation };
-        const ports = { snapshotStore, sessionStore, sha256, idFactory };
-        if (shouldBlockNow) {
-            return buildBlockedOutcome({ mode, snap, ctx, computed, lock, ports });
-        }
-        return buildSuccessOutcome({ mode, ctx, computed, v, lock, ports });
-    });
-}
-function derivePendingStepForMode(mode, engineState) {
-    switch (mode.kind) {
-        case 'fresh': {
-            const currentState = (0, v2_state_conversion_js_1.toV1ExecutionState)(engineState);
-            return (currentState.kind === 'running' && currentState.pendingStep) ? currentState.pendingStep : null;
-        }
-        case 'retry': {
-            if (engineState.kind !== 'blocked')
-                return null;
-            const pending = (0, snapshot_state_js_1.derivePendingStep)(engineState);
-            return pending ? {
-                stepId: String(pending.stepId),
-                loopPath: pending.loopPath.map(f => ({ loopId: String(f.loopId), iteration: f.iteration })),
-            } : null;
-        }
-    }
-}
-function validateAdvanceInputs(args) {
-    const { truth, runId, currentNodeId, inputContext, inputOutput, pinnedWorkflow, pendingStep } = args;
-    const storedContextRes = (0, run_context_js_1.projectRunContextV2)(truth.events);
-    const storedContext = storedContextRes.isOk() ? storedContextRes.value.byRunId[String(runId)]?.context : undefined;
-    const inputContextObj = inputContext && typeof inputContext === 'object' && inputContext !== null && !Array.isArray(inputContext)
-        ? inputContext
-        : undefined;
-    const mergedContextRes = (0, context_merge_js_1.mergeContext)(storedContext, inputContextObj);
-    if (mergedContextRes.isErr()) {
-        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Context merge failed: ${mergedContextRes.error.message}` });
-    }
-    const step = (0, workflow_js_1.getStepById)(pinnedWorkflow, pendingStep.stepId);
-    const validationCriteria = step?.validationCriteria;
-    const outputContract = step?.outputContract;
-    const parentByNodeId = {};
-    for (const e of truth.events) {
-        if (e.kind !== 'node_created')
-            continue;
-        if (e.scope?.runId !== String(runId))
-            continue;
-        parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
-    }
-    const prefs = (0, preferences_js_1.projectPreferencesV2)(truth.events, parentByNodeId);
-    const effectivePrefs = prefs.isOk() ? prefs.value.byNodeId[String(currentNodeId)]?.effective : undefined;
-    const rawAutonomy = effectivePrefs?.autonomy ?? 'guided';
-    const rawRiskPolicy = effectivePrefs?.riskPolicy ?? 'conservative';
-    const VALID_AUTONOMY = ['guided', 'full_auto_stop_on_user_deps', 'full_auto_never_stop'];
-    const VALID_RISK_POLICY = ['conservative', 'balanced', 'aggressive'];
-    if (!VALID_AUTONOMY.includes(rawAutonomy)) {
-        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Unknown autonomy mode: ${rawAutonomy}` });
-    }
-    if (!VALID_RISK_POLICY.includes(rawRiskPolicy)) {
-        return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Unknown risk policy: ${rawRiskPolicy}` });
-    }
-    const autonomy = rawAutonomy;
-    const riskPolicy = rawRiskPolicy;
-    return (0, neverthrow_1.ok)({
-        pendingStep,
-        mergedContext: mergedContextRes.value,
-        inputContextObj,
-        validationCriteria,
-        outputContract,
-        notesMarkdown: inputOutput?.notesMarkdown,
-        artifacts: inputOutput?.artifacts ?? [],
-        autonomy,
-        riskPolicy,
-        effectivePrefs,
-    });
-}
-function buildBlockedOutcome(args) {
-    const { mode, snap, lock, ports } = args;
-    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash } = args.ctx;
-    const { reasons, effectiveReasons, outputRequirement, validation } = args.computed;
-    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
-    const blockersRes = (0, reason_model_js_1.buildBlockerReport)(effectiveReasons);
-    if (blockersRes.isErr()) {
-        return errAsync({ kind: 'invariant_violation', message: blockersRes.error.message });
-    }
-    const validationEventId = idFactory.mintEventId();
-    const validationId = `validation_${String(attemptId)}`;
-    const contractRefForEvent = outputRequirement.kind !== 'not_required' ? outputRequirement.contractRef : 'none';
-    const validationForEvent = validation ??
-        (outputRequirement.kind === 'missing'
-            ? { valid: false, issues: [`Missing required output for contractRef=${contractRefForEvent}`], suggestions: [], warnings: undefined }
-            : { valid: false, issues: ['Validation result missing'], suggestions: [], warnings: undefined });
-    const validationEventRes = (0, validation_event_builder_js_1.buildValidationPerformedEvent)({
-        sessionId: String(sessionId),
-        validationId,
-        attemptId: String(attemptId),
-        contractRef: contractRefForEvent,
-        scope: { runId: String(runId), nodeId: String(currentNodeId) },
-        minted: { eventId: validationEventId },
-        result: validationForEvent,
-    });
-    if (validationEventRes.isErr()) {
-        return errAsync({ kind: 'invariant_violation', message: validationEventRes.error.message });
-    }
-    const extraEventsToAppend = [validationEventRes.value];
-    const primaryReason = reasons[0];
-    if (!primaryReason) {
-        return errAsync({ kind: 'invariant_violation', message: 'shouldBlockNow=true requires at least one reason' });
-    }
-    const blockedSnapshotRes = (0, blocked_node_builder_js_1.buildBlockedNodeSnapshot)({
-        priorSnapshot: snap,
-        primaryReason,
-        attemptId,
-        validationRef: validationId,
-        blockers: blockersRes.value,
-        sha256,
-    });
-    if (blockedSnapshotRes.isErr()) {
-        return errAsync({ kind: 'invariant_violation', message: blockedSnapshotRes.error.message });
-    }
-    return snapshotStore.putExecutionSnapshotV1(blockedSnapshotRes.value).andThen((blockedSnapshotRef) => {
-        return buildAndAppendPlan({
-            truth, sessionId, runId, currentNodeId, attemptId, workflowHash,
-            extraEventsToAppend, toNodeKind: 'blocked_attempt', snapshotRef: blockedSnapshotRef,
-            outputsToAppend: [], sessionStore, idFactory, lock,
-        });
-    });
-}
-function buildSuccessOutcome(args) {
-    const { mode, v, lock, ports } = args;
-    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, inputOutput, pinnedWorkflow, engineState, pendingStep } = args.ctx;
-    const { effectiveReasons, outputRequirement, validation } = args.computed;
-    const { snapshotStore, sessionStore, sha256, idFactory } = ports;
-    const compiler = new workflow_compiler_js_1.WorkflowCompiler();
-    const interpreter = new workflow_interpreter_js_1.WorkflowInterpreter();
-    const compiledWf = compiler.compile(pinnedWorkflow);
-    if (compiledWf.isErr()) {
-        return errAsync({ kind: 'advance_apply_failed', message: compiledWf.error.message });
-    }
-    const currentState = (0, v2_state_conversion_js_1.toV1ExecutionState)(engineState);
-    const event = {
-        kind: 'step_completed',
-        stepInstanceId: {
-            stepId: pendingStep.stepId,
-            loopPath: pendingStep.loopPath.map(f => ({ loopId: f.loopId, iteration: f.iteration })),
-        },
-    };
-    const advanced = interpreter.applyEvent(currentState, event);
-    if (advanced.isErr()) {
-        return errAsync({ kind: 'advance_apply_failed', message: advanced.error.message });
-    }
-    const artifactsForEval = (0, v2_context_budget_js_1.collectArtifactsForEvaluation)({
-        truthEvents: truth.events,
-        inputArtifacts: inputOutput?.artifacts ?? [],
-    });
-    const nextRes = interpreter.next(compiledWf.value, advanced.value, v.mergedContext, artifactsForEval);
-    if (nextRes.isErr()) {
-        return errAsync({ kind: 'advance_next_failed', message: nextRes.error.message });
-    }
-    const out = nextRes.value;
-    const extraEventsToAppend = [];
-    if (v.autonomy === 'full_auto_never_stop' && effectiveReasons.length > 0) {
-        for (const [idx, r] of effectiveReasons.entries()) {
-            const g = (0, reason_model_js_1.reasonToGap)(r);
-            const gapId = `gap_${String(attemptId)}_${idx}`;
-            extraEventsToAppend.push({
-                v: 1,
-                eventId: idFactory.mintEventId(),
-                kind: 'gap_recorded',
-                dedupeKey: `gap_recorded:${String(sessionId)}:${gapId}`,
-                scope: { runId: String(runId), nodeId: String(currentNodeId) },
-                data: { gapId, severity: g.severity, reason: g.reason, summary: g.summary, resolution: { kind: 'unresolved' } },
-            });
-        }
-    }
-    const workflowRecommendations = pinnedWorkflow.definition.recommendedPreferences;
-    if (workflowRecommendations && v.effectivePrefs) {
-        const warnings = (0, recommendation_warnings_js_1.checkRecommendationExceedance)({ autonomy: v.autonomy, riskPolicy: v.riskPolicy }, workflowRecommendations);
-        for (const [idx, w] of warnings.entries()) {
-            const gapId = `rec_warn_${String(currentNodeId)}_${idx}`;
-            extraEventsToAppend.push(partialEvent({
-                v: 1,
-                eventId: idFactory.mintEventId(),
-                kind: 'gap_recorded',
-                dedupeKey: `gap_recorded:${String(sessionId)}:${gapId}`,
-                scope: { runId: String(runId), nodeId: String(currentNodeId) },
-                data: { gapId, severity: 'warning', reason: w.kind, summary: w.summary, resolution: { kind: 'unresolved' } },
-            }));
-        }
-    }
-    if (v.inputContextObj) {
-        extraEventsToAppend.push(partialEvent({
-            v: 1,
-            eventId: idFactory.mintEventId(),
-            kind: 'context_set',
-            dedupeKey: `context_set:${String(sessionId)}:${String(runId)}:${idFactory.mintEventId()}`,
-            scope: { runId: String(runId) },
-            data: {
-                contextId: idFactory.mintEventId(),
-                context: v.mergedContext,
-                source: 'agent_delta',
-            },
-        }));
-    }
-    if (emitValidationOnSuccess(mode)) {
-        const validationId = `validation_${String(attemptId)}`;
-        const contractRefForEvent = outputRequirement.kind !== 'not_required' ? outputRequirement.contractRef : 'none';
-        const validationForEvent = validation ??
-            (outputRequirement.kind === 'missing'
-                ? { valid: false, issues: [`Missing required output for contractRef=${contractRefForEvent}`], suggestions: [], warnings: undefined }
-                : { valid: true, issues: [], suggestions: [], warnings: undefined });
-        const validationEventRes = (0, validation_event_builder_js_1.buildValidationPerformedEvent)({
-            sessionId: String(sessionId),
-            validationId,
-            attemptId: String(attemptId),
-            contractRef: contractRefForEvent,
-            scope: { runId: String(runId), nodeId: String(currentNodeId) },
-            minted: { eventId: idFactory.mintEventId() },
-            result: validationForEvent,
-        });
-        if (validationEventRes.isOk()) {
-            extraEventsToAppend.push(validationEventRes.value);
-        }
-    }
-    if (out.trace.length > 0) {
-        const traceId = idFactory.mintEventId();
-        const traceDataRes = (0, decision_trace_builder_js_1.buildDecisionTraceEventData)(traceId, out.trace);
-        if (traceDataRes.isOk()) {
-            extraEventsToAppend.push(partialEvent({
-                v: 1,
-                eventId: idFactory.mintEventId(),
-                kind: 'decision_trace_appended',
-                dedupeKey: `decision_trace_appended:${String(sessionId)}:${traceId}`,
-                scope: { runId: String(runId), nodeId: String(currentNodeId) },
-                data: traceDataRes.value,
-            }));
-        }
-    }
-    const newEngineState = (0, v2_state_conversion_js_1.fromV1ExecutionState)(out.state);
-    const snapshotFile = {
-        v: 1,
-        kind: 'execution_snapshot',
-        enginePayload: { v: 1, engineState: newEngineState },
-    };
-    return snapshotStore.putExecutionSnapshotV1(snapshotFile).andThen((newSnapshotRef) => {
-        const allowNotesAppend = v.validationCriteria
-            ? Boolean(v.notesMarkdown && validation && validation.valid)
-            : Boolean(v.notesMarkdown);
-        const notesOutputs = buildNotesOutputs(allowNotesAppend, attemptId, inputOutput);
-        const artifactOutputsRes = buildArtifactOutputs(inputOutput?.artifacts ?? [], attemptId, sha256);
-        if (artifactOutputsRes.isErr()) {
-            return errAsync(artifactOutputsRes.error);
-        }
-        const outputsToAppend = [...notesOutputs, ...artifactOutputsRes.value];
-        return buildAndAppendPlan({
-            truth, sessionId, runId, currentNodeId, attemptId, workflowHash,
-            extraEventsToAppend, toNodeKind: successNodeKind(mode),
-            snapshotRef: newSnapshotRef, outputsToAppend,
-            sessionStore, idFactory, lock,
-        });
-    });
-}
-function buildAndAppendPlan(args) {
-    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, extraEventsToAppend, toNodeKind, snapshotRef, outputsToAppend, sessionStore, idFactory, lock } = args;
-    const toNodeId = String(idFactory.mintNodeId());
-    const nextEventIndex = truth.events.length === 0 ? 0 : truth.events[truth.events.length - 1].eventIndex + 1;
-    const evtAdvanceRecorded = idFactory.mintEventId();
-    const evtNodeCreated = idFactory.mintEventId();
-    const evtEdgeCreated = idFactory.mintEventId();
-    const hasChildren = truth.events.some((e) => e.kind === 'edge_created' && e.data.fromNodeId === String(currentNodeId));
-    const causeKind = hasChildren ? 'non_tip_advance' : 'intentional_fork';
-    const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(outputsToAppend);
-    const outputEventIds = normalizedOutputs.map(() => idFactory.mintEventId());
-    const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
-        sessionId: String(sessionId),
-        runId: String(runId),
-        fromNodeId: String(currentNodeId),
-        workflowHash,
-        attemptId: String(attemptId),
-        nextEventIndex,
-        extraEventsToAppend,
-        toNodeId,
-        toNodeKind,
-        snapshotRef,
-        causeKind,
-        minted: {
-            advanceRecordedEventId: evtAdvanceRecorded,
-            nodeCreatedEventId: evtNodeCreated,
-            edgeCreatedEventId: evtEdgeCreated,
-            outputEventIds,
-        },
-        outputsToAppend: [...outputsToAppend],
-    });
-    if (planRes.isErr())
-        return (0, neverthrow_1.errAsync)({ kind: 'invariant_violation', message: planRes.error.message });
-    return sessionStore.append(lock, planRes.value);
-}
-function buildNotesOutputs(allowNotesAppend, attemptId, inputOutput) {
-    if (!allowNotesAppend || !inputOutput?.notesMarkdown)
-        return [];
-    return [{
-            outputId: String((0, index_js_1.asOutputId)(`out_recap_${String(attemptId)}`)),
-            outputChannel: 'recap',
-            payload: {
-                payloadKind: 'notes',
-                notesMarkdown: (0, notes_markdown_js_1.toNotesMarkdownV1)(inputOutput.notesMarkdown),
-            },
-        }];
-}
-function buildArtifactOutputs(inputArtifacts, attemptId, sha256) {
-    const outputs = [];
-    for (let idx = 0; idx < inputArtifacts.length; idx++) {
-        const artifact = inputArtifacts[idx];
-        const canonicalBytesRes = (0, jcs_js_1.toCanonicalBytes)(artifact);
-        if (canonicalBytesRes.isErr()) {
-            return (0, neverthrow_1.err)({ kind: 'invariant_violation', message: `Artifact canonicalization failed at index ${idx}: ${canonicalBytesRes.error.message}` });
-        }
-        const canonicalBytes = canonicalBytesRes.value;
-        outputs.push({
-            outputId: (0, index_js_1.asOutputId)(`out_artifact_${String(attemptId)}_${idx}`),
-            outputChannel: 'artifact',
-            payload: {
-                payloadKind: 'artifact_ref',
-                sha256: sha256.sha256(canonicalBytes),
-                contentType: 'application/json',
-                byteLength: canonicalBytes.length,
-                content: artifact,
-            },
-        });
-    }
-    return (0, neverthrow_1.ok)(outputs);
-}
-function errAsync(e) {
-    return (0, neverthrow_1.errAsync)(e);
-}
+exports.executeAdvanceCore = void 0;
+var index_js_1 = require("./v2-advance-core/index.js");
+Object.defineProperty(exports, "executeAdvanceCore", { enumerable: true, get: function () { return index_js_1.executeAdvanceCore; } });

package/dist/mcp/handlers/v2-advance-events.d.ts

@@ -0,0 +1,61 @@
+import { type Result } from 'neverthrow';
+import type { DomainEventV1 } from '../../v2/durable-core/schemas/session/index.js';
+import type { RunId, NodeId } from '../../v2/durable-core/ids/index.js';
+import type { AttemptId } from '../../v2/durable-core/tokens/index.js';
+import type { JsonObject } from '../../v2/durable-core/canonical/json-types.js';
+import type { ValidationResult } from '../../types/validation.js';
+import type { RecommendationWarning } from '../../v2/durable-core/domain/recommendation-warnings.js';
+import type { ReasonV1 } from '../../v2/durable-core/domain/reason-model.js';
+import type { DecisionTraceEntry } from '../../v2/durable-core/domain/decision-trace-builder.js';
+import type { InternalError } from './v2-error-mapping.js';
+import type { AdvanceCorePorts } from './v2-advance-core.js';
+type PartialEvent = Omit<DomainEventV1, 'eventIndex' | 'sessionId'>;
+import type { OutputRequirementStatus } from '../../v2/durable-core/domain/blocking-decision.js';
+export type AdvanceMode = {
+    readonly kind: 'fresh';
+    readonly sourceNodeId: NodeId;
+    readonly snapshot: unknown;
+} | {
+    readonly kind: 'retry';
+    readonly blockedNodeId: NodeId;
+    readonly blockedSnapshot: unknown;
+};
+export declare function buildGapEvents(args: {
+    readonly gaps: readonly ReasonV1[];
+    readonly sessionId: string;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+}): readonly PartialEvent[];
+export declare function buildRecommendationWarningEvents(args: {
+    readonly recommendations: readonly RecommendationWarning[];
+    readonly sessionId: string;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+}): readonly PartialEvent[];
+export declare function buildContextSetEvent(args: {
+    readonly mergedContext: JsonObject;
+    readonly sessionId: string;
+    readonly runId: RunId;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+}): PartialEvent | null;
+export declare function buildSuccessValidationEvent(args: {
+    readonly mode: AdvanceMode;
+    readonly outputRequirement: OutputRequirementStatus;
+    readonly validation: ValidationResult | undefined;
+    readonly attemptId: AttemptId;
+    readonly sessionId: string;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+}): PartialEvent | null;
+export declare function buildDecisionTraceEvent(args: {
+    readonly decisions: readonly DecisionTraceEntry[];
+    readonly sessionId: string;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+}): Result<PartialEvent | null, InternalError>;
+export {};

package/dist/mcp/handlers/v2-advance-events.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGapEvents = buildGapEvents;
+exports.buildRecommendationWarningEvents = buildRecommendationWarningEvents;
+exports.buildContextSetEvent = buildContextSetEvent;
+exports.buildSuccessValidationEvent = buildSuccessValidationEvent;
+exports.buildDecisionTraceEvent = buildDecisionTraceEvent;
+const neverthrow_1 = require("neverthrow");
+const reason_model_js_1 = require("../../v2/durable-core/domain/reason-model.js");
+const validation_event_builder_js_1 = require("../../v2/durable-core/domain/validation-event-builder.js");
+const decision_trace_builder_js_1 = require("../../v2/durable-core/domain/decision-trace-builder.js");
+const constants_js_1 = require("../../v2/durable-core/constants.js");
+function partialEvent(fields) {
+    return fields;
+}
+function buildGapEvents(args) {
+    const { gaps, sessionId, runId, nodeId, attemptId, idFactory } = args;
+    const events = [];
+    for (const [idx, r] of gaps.entries()) {
+        const g = (0, reason_model_js_1.reasonToGap)(r);
+        const gapId = `gap_${String(attemptId)}_${idx}`;
+        events.push({
+            v: 1,
+            eventId: idFactory.mintEventId(),
+            kind: constants_js_1.EVENT_KIND.GAP_RECORDED,
+            dedupeKey: `gap_recorded:${sessionId}:${gapId}`,
+            scope: { runId: String(runId), nodeId: String(nodeId) },
+            data: {
+                gapId,
+                severity: g.severity,
+                reason: g.reason,
+                summary: g.summary,
+                resolution: { kind: 'unresolved' },
+            },
+        });
+    }
+    return events;
+}
+function buildRecommendationWarningEvents(args) {
+    const { recommendations, sessionId, runId, nodeId, idFactory } = args;
+    const events = [];
+    for (const [idx, w] of recommendations.entries()) {
+        const gapId = `rec_warn_${String(nodeId)}_${idx}`;
+        events.push(partialEvent({
+            v: 1,
+            eventId: idFactory.mintEventId(),
+            kind: constants_js_1.EVENT_KIND.GAP_RECORDED,
+            dedupeKey: `gap_recorded:${sessionId}:${gapId}`,
+            scope: { runId: String(runId), nodeId: String(nodeId) },
+            data: {
+                gapId,
+                severity: 'warning',
+                reason: w.kind,
+                summary: w.summary,
+                resolution: { kind: 'unresolved' },
+            },
+        }));
+    }
+    return events;
+}
+function buildContextSetEvent(args) {
+    const { mergedContext, sessionId, runId, idFactory } = args;
+    return partialEvent({
+        v: 1,
+        eventId: idFactory.mintEventId(),
+        kind: constants_js_1.EVENT_KIND.CONTEXT_SET,
+        dedupeKey: `context_set:${sessionId}:${String(runId)}:${idFactory.mintEventId()}`,
+        scope: { runId: String(runId) },
+        data: {
+            contextId: idFactory.mintEventId(),
+            context: mergedContext,
+            source: 'agent_delta',
+        },
+    });
+}
+function buildSuccessValidationEvent(args) {
+    const { mode, outputRequirement, validation, attemptId, sessionId, runId, nodeId, idFactory } = args;
+    if (mode.kind !== 'retry') {
+        return null;
+    }
+    const validationId = `validation_${String(attemptId)}`;
+    const contractRefForEvent = outputRequirement.kind !== 'not_required' && outputRequirement.kind !== 'satisfied'
+        ? outputRequirement.contractRef
+        : 'none';
+    const validationForEvent = validation ??
+        (outputRequirement.kind === 'missing'
+            ? {
+                valid: false,
+                issues: [`Missing required output for contractRef=${contractRefForEvent}`],
+                suggestions: [],
+                warnings: undefined,
+            }
+            : { valid: true, issues: [], suggestions: [], warnings: undefined });
+    const validationEventRes = (0, validation_event_builder_js_1.buildValidationPerformedEvent)({
+        sessionId,
+        validationId,
+        attemptId: String(attemptId),
+        contractRef: contractRefForEvent,
+        scope: { runId: String(runId), nodeId: String(nodeId) },
+        minted: { eventId: idFactory.mintEventId() },
+        result: validationForEvent,
+    });
+    return validationEventRes.isOk() ? validationEventRes.value : null;
+}
+function buildDecisionTraceEvent(args) {
+    const { decisions, sessionId, runId, nodeId, idFactory } = args;
+    if (decisions.length === 0) {
+        return (0, neverthrow_1.ok)(null);
+    }
+    const traceId = idFactory.mintEventId();
+    const traceDataRes = (0, decision_trace_builder_js_1.buildDecisionTraceEventData)(traceId, decisions);
+    if (traceDataRes.isErr()) {
+        return (0, neverthrow_1.err)({
+            kind: 'invariant_violation',
+            message: `Failed to build decision trace data: ${traceDataRes.error}`,
+        });
+    }
+    return (0, neverthrow_1.ok)(partialEvent({
+        v: 1,
+        eventId: idFactory.mintEventId(),
+        kind: constants_js_1.EVENT_KIND.DECISION_TRACE_APPENDED,
+        dedupeKey: `decision_trace_appended:${sessionId}:${traceId}`,
+        scope: { runId: String(runId), nodeId: String(nodeId) },
+        data: traceDataRes.value,
+    }));
+}