@exaudeus/workrail 1.5.0 → 1.5.2

package/dist/mcp/error-mapper.d.ts

@@ -1,4 +1,4 @@
 import type { DomainError } from '../domain/execution/error.js';
 import type { ToolError } from './types.js';
 export declare function mapDomainErrorToToolError(err: DomainError): ToolError;
-export declare function mapUnknownErrorToToolError(err: unknown): ToolError;
+export declare function mapUnknownErrorToToolError(_err: unknown): ToolError;

package/dist/mcp/error-mapper.js

@@ -3,13 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapDomainErrorToToolError = mapDomainErrorToToolError;
 exports.mapUnknownErrorToToolError = mapUnknownErrorToToolError;
 const bounded_json_js_1 = require("./validation/bounded-json.js");
-function assertNever(x) {
+const v2_execution_helpers_js_1 = require("./handlers/v2-execution-helpers.js");
+function assertNever(_x) {
     return {
         type: 'error',
         code: 'INTERNAL_ERROR',
-        message: `Unhandled DomainError variant: ${JSON.stringify(x)}`,
+        message: 'WorkRail encountered an unexpected error. This is not caused by your input.',
         retry: { kind: 'not_retryable' },
-        details: { invariantViolation: 'exhaustiveness_check_failed' },
+        details: { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('', 'WorkRail has an internal error.') },
     };
 }
 function mapDomainErrorToToolError(err) {
@@ -80,9 +81,12 @@ function mapDomainErrorToToolError(err) {
             return assertNever(err);
     }
 }
-function mapUnknownErrorToToolError(err) {
-    if (err instanceof Error) {
-        return { type: 'error', code: 'INTERNAL_ERROR', message: err.message, retry: { kind: 'not_retryable' } };
-    }
-    return { type: 'error', code: 'INTERNAL_ERROR', message: String(err), retry: { kind: 'not_retryable' } };
+function mapUnknownErrorToToolError(_err) {
+    return {
+        type: 'error',
+        code: 'INTERNAL_ERROR',
+        message: 'WorkRail encountered an unexpected error. This is not caused by your input.',
+        retry: { kind: 'not_retryable' },
+        details: { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.') },
+    };
 }

package/dist/mcp/handler-factory.js

@@ -6,6 +6,7 @@ exports.createValidatingHandler = createValidatingHandler;
 const types_js_1 = require("./types.js");
 const index_js_1 = require("./validation/index.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
+const v2_execution_helpers_js_1 = require("./handlers/v2-execution-helpers.js");
 function toMcpResult(result) {
     switch (result.type) {
         case 'success':
@@ -41,7 +42,13 @@ function createHandler(schema, handler) {
                 ...suggestionDetails,
             }));
         }
-        return toMcpResult(await handler(parseResult.data, ctx));
+        try {
+            return toMcpResult(await handler(parseResult.data, ctx));
+        }
+        catch (err) {
+            console.error('[WorkRail] Unhandled exception in tool handler:', err);
+            return toMcpResult((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail encountered an unexpected error. This is not caused by your input.', { suggestion: (0, v2_execution_helpers_js_1.internalSuggestion)('Retry the call.', 'WorkRail has an internal error.') }));
+        }
     };
 }
 function createValidatingHandler(schema, preValidate, handler) {

package/dist/mcp/handlers/session.js

@@ -6,7 +6,6 @@ exports.handleReadSession = handleReadSession;
 exports.handleOpenDashboard = handleOpenDashboard;
 const types_js_1 = require("../types.js");
 const output_schemas_js_1 = require("../output-schemas.js");
-const error_mapper_js_1 = require("../error-mapper.js");
 const SESSION_SCHEMA_OVERVIEW = {
     description: 'Bug Investigation Session Data Structure',
     mainSections: {
@@ -52,49 +51,38 @@ async function handleCreateSession(input, ctx) {
         return guardError;
     const sessionManager = ctx.sessionManager;
     const httpServer = ctx.httpServer;
-    try {
-        const session = await sessionManager.createSession(input.workflowId, input.sessionId, input.initialData);
-        const baseUrl = httpServer.getBaseUrl();
-        const dashboardUrl = baseUrl ? `${baseUrl}?session=${input.sessionId}` : null;
-        const payload = output_schemas_js_1.CreateSessionOutputSchema.parse({
-            sessionId: session.id,
-            workflowId: session.workflowId,
-            path: sessionManager.getSessionPath(input.workflowId, input.sessionId),
-            dashboardUrl,
-            createdAt: session.createdAt,
-        });
-        return (0, types_js_1.success)(payload);
-    }
-    catch (err) {
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
+    const res = await sessionManager.createSession(input.workflowId, input.sessionId, input.initialData);
+    if (res.isErr()) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', res.error.message);
     }
+    const session = res.value;
+    const baseUrl = httpServer.getBaseUrl();
+    const dashboardUrl = baseUrl ? `${baseUrl}?session=${input.sessionId}` : null;
+    const payload = output_schemas_js_1.CreateSessionOutputSchema.parse({
+        sessionId: session.id,
+        workflowId: session.workflowId,
+        path: sessionManager.getSessionPath(input.workflowId, input.sessionId),
+        dashboardUrl,
+        createdAt: session.createdAt,
+    });
+    return (0, types_js_1.success)(payload);
 }
 async function handleUpdateSession(input, ctx) {
     const guardError = requireSessionTools(ctx);
     if (guardError)
         return guardError;
     const sessionManager = ctx.sessionManager;
-    try {
-        await sessionManager.updateSession(input.workflowId, input.sessionId, input.updates);
-        const payload = output_schemas_js_1.UpdateSessionOutputSchema.parse({ updatedAt: new Date().toISOString() });
-        return (0, types_js_1.success)(payload);
-    }
-    catch (err) {
-        if (err instanceof Error && (err.name === 'SessionNotFoundError' ||
-            err.message.toLowerCase().includes('not found') ||
-            err.message.toLowerCase().includes('does not exist'))) {
-            return {
-                type: 'error',
-                code: 'NOT_FOUND',
-                message: err.message,
-                retry: { kind: 'not_retryable' },
-                details: { suggestion: 'Make sure the session exists. Use workrail_create_session() first.' },
-            };
+    const res = await sessionManager.updateSession(input.workflowId, input.sessionId, input.updates);
+    if (res.isErr()) {
+        if (res.error.code === 'SESSION_NOT_FOUND') {
+            return (0, types_js_1.errNotRetryable)('NOT_FOUND', res.error.message, {
+                suggestion: 'Make sure the session exists. Use workrail_create_session() first.',
+            });
         }
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', res.error.message);
     }
+    const payload = output_schemas_js_1.UpdateSessionOutputSchema.parse({ updatedAt: new Date().toISOString() });
+    return (0, types_js_1.success)(payload);
 }
 async function handleReadSession(input, ctx) {
     const guardError = requireSessionTools(ctx);
@@ -108,29 +96,20 @@ async function handleReadSession(input, ctx) {
         });
         return (0, types_js_1.success)(payload);
     }
-    try {
-        const data = await sessionManager.readSession(input.workflowId, input.sessionId, input.path);
-        const payload = output_schemas_js_1.ReadSessionOutputSchema.parse({
-            query: input.path ?? '(full session)',
-            data,
-        });
-        return (0, types_js_1.success)(payload);
-    }
-    catch (err) {
-        if (err instanceof Error && (err.name === 'SessionNotFoundError' ||
-            err.message.toLowerCase().includes('not found') ||
-            err.message.toLowerCase().includes('does not exist'))) {
-            return {
-                type: 'error',
-                code: 'NOT_FOUND',
-                message: err.message,
-                retry: { kind: 'not_retryable' },
-                details: { suggestion: 'Make sure the session exists. Use workrail_create_session() first.' },
-            };
+    const res = await sessionManager.readSession(input.workflowId, input.sessionId, input.path);
+    if (res.isErr()) {
+        if (res.error.code === 'SESSION_NOT_FOUND') {
+            return (0, types_js_1.errNotRetryable)('NOT_FOUND', res.error.message, {
+                suggestion: 'Make sure the session exists. Use workrail_create_session() first.',
+            });
         }
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', res.error.message);
     }
+    const payload = output_schemas_js_1.ReadSessionOutputSchema.parse({
+        query: input.path ?? '(full session)',
+        data: res.value,
+    });
+    return (0, types_js_1.success)(payload);
 }
 async function handleOpenDashboard(input, ctx) {
     const guardError = requireSessionTools(ctx);
@@ -143,7 +122,6 @@ async function handleOpenDashboard(input, ctx) {
         return (0, types_js_1.success)(payload);
     }
     catch (err) {
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', err instanceof Error ? err.message : 'Failed to open dashboard');
     }
 }

package/dist/mcp/handlers/v2-advance-core/event-builders.d.ts

@@ -0,0 +1,37 @@
+import { ResultAsync as RA, type Result } from 'neverthrow';
+import type { DomainEventV1 } from '../../../v2/durable-core/schemas/session/index.js';
+import type { SessionId, RunId, NodeId, WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+import type { AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import { type OutputToAppend } from '../../../v2/durable-core/domain/outputs.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import type { AdvanceCorePorts } from './index.js';
+type BuildAppendPlanArgs = {
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly extraEventsToAppend: readonly Omit<DomainEventV1, 'eventIndex' | 'sessionId'>[];
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2;
+    readonly idFactory: AdvanceCorePorts['idFactory'];
+    readonly lock: WithHealthySessionLock;
+} & ({
+    readonly kind: 'blocked';
+    readonly blockers: import('../../../v2/durable-core/domain/reason-model.js').BlockerReportV1;
+    readonly snapshotRef: import('../../../v2/durable-core/ids/index.js').SnapshotRef;
+} | {
+    readonly kind: 'advanced';
+    readonly toNodeKind: 'step' | 'blocked_attempt' | undefined;
+    readonly snapshotRef: import('../../../v2/durable-core/ids/index.js').SnapshotRef;
+    readonly outputsToAppend: readonly OutputToAppend[];
+});
+export declare function buildAndAppendPlan(args: BuildAppendPlanArgs): RA<void, InternalError | SessionEventLogStoreError>;
+export declare function buildNotesOutputs(allowNotesAppend: boolean, attemptId: AttemptId, inputOutput: V2ContinueWorkflowInput['output']): readonly OutputToAppend[];
+export declare function buildArtifactOutputs(inputArtifacts: readonly unknown[], attemptId: AttemptId, sha256: Sha256PortV2): Result<readonly OutputToAppend[], InternalError>;
+export {};

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAndAppendPlan = buildAndAppendPlan;
+exports.buildNotesOutputs = buildNotesOutputs;
+exports.buildArtifactOutputs = buildArtifactOutputs;
+const neverthrow_1 = require("neverthrow");
+const index_js_1 = require("../../../v2/durable-core/tokens/index.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 constants_js_1 = require("../../../v2/durable-core/constants.js");
+function buildAndAppendPlan(args) {
+    const { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, extraEventsToAppend, sessionStore, idFactory, lock } = args;
+    const nextEventIndex = truth.events.length === 0 ? 0 : truth.events[truth.events.length - 1].eventIndex + 1;
+    const evtAdvanceRecorded = idFactory.mintEventId();
+    if (args.kind === 'blocked') {
+        const toNodeId = String(idFactory.mintNodeId());
+        const evtNodeCreated = idFactory.mintEventId();
+        const evtEdgeCreated = idFactory.mintEventId();
+        const hasChildren = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.EDGE_CREATED && e.data.fromNodeId === String(currentNodeId));
+        const causeKind = hasChildren ? constants_js_1.EDGE_CAUSE.NON_TIP_ADVANCE : constants_js_1.EDGE_CAUSE.INTENTIONAL_FORK;
+        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,
+            outcome: { kind: 'advanced', toNodeId },
+            toNodeKind: 'blocked_attempt',
+            toNodeId,
+            snapshotRef: args.snapshotRef,
+            causeKind,
+            minted: {
+                advanceRecordedEventId: evtAdvanceRecorded,
+                nodeCreatedEventId: evtNodeCreated,
+                edgeCreatedEventId: evtEdgeCreated,
+                outputEventIds: [],
+            },
+            outputsToAppend: [],
+        });
+        if (planRes.isErr())
+            return (0, neverthrow_1.errAsync)({ kind: 'invariant_violation', message: planRes.error.message });
+        return sessionStore.append(lock, planRes.value);
+    }
+    const toNodeId = String(idFactory.mintNodeId());
+    const evtNodeCreated = idFactory.mintEventId();
+    const evtEdgeCreated = idFactory.mintEventId();
+    const hasChildren = truth.events.some((e) => e.kind === constants_js_1.EVENT_KIND.EDGE_CREATED && e.data.fromNodeId === String(currentNodeId));
+    const causeKind = hasChildren ? constants_js_1.EDGE_CAUSE.NON_TIP_ADVANCE : constants_js_1.EDGE_CAUSE.INTENTIONAL_FORK;
+    const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(args.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,
+        outcome: { kind: 'advanced', toNodeId },
+        toNodeKind: args.toNodeKind ?? 'step',
+        toNodeId,
+        snapshotRef: args.snapshotRef,
+        causeKind,
+        minted: {
+            advanceRecordedEventId: evtAdvanceRecorded,
+            nodeCreatedEventId: evtNodeCreated,
+            edgeCreatedEventId: evtEdgeCreated,
+            outputEventIds,
+        },
+        outputsToAppend: [...args.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: constants_js_1.OUTPUT_CHANNEL.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: constants_js_1.OUTPUT_CHANNEL.ARTIFACT,
+            payload: {
+                payloadKind: 'artifact_ref',
+                sha256: sha256.sha256(canonicalBytes),
+                contentType: 'application/json',
+                byteLength: canonicalBytes.length,
+                content: artifact,
+            },
+        });
+    }
+    return (0, neverthrow_1.ok)(outputs);
+}

package/dist/mcp/handlers/v2-advance-core/index.d.ts

@@ -0,0 +1,67 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { ExecutionSnapshotFileV1, EngineStateV1 } from '../../../v2/durable-core/schemas/execution-snapshot/index.js';
+import type { SessionId, RunId, NodeId, WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+import type { AttemptId } from '../../../v2/durable-core/tokens/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SessionEventLogStoreError } from '../../../v2/ports/session-event-log-store.port.js';
+import type { SnapshotStoreError } from '../../../v2/ports/snapshot-store.port.js';
+import type { WithHealthySessionLock } from '../../../v2/durable-core/ids/with-healthy-session-lock.js';
+import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
+import type { JsonValue } from '../../../v2/durable-core/canonical/json-types.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import type { ValidationResult } from '../../../types/validation.js';
+import { createWorkflow } from '../../../types/workflow.js';
+import { type ReasonV1 } from '../../../v2/durable-core/domain/reason-model.js';
+import { getOutputRequirementStatusWithArtifactsV1 } from '../../../v2/durable-core/domain/validation-criteria-validator.js';
+import type { InternalError } from '../v2-error-mapping.js';
+import { type ValidatedAdvanceInputs } from './input-validation.js';
+export type AdvanceMode = {
+    readonly kind: 'fresh';
+    readonly sourceNodeId: NodeId;
+    readonly snapshot: ExecutionSnapshotFileV1;
+} | {
+    readonly kind: 'retry';
+    readonly blockedNodeId: NodeId;
+    readonly blockedSnapshot: ExecutionSnapshotFileV1;
+};
+export interface AdvanceCorePorts {
+    readonly snapshotStore: import('../../../v2/ports/snapshot-store.port.js').SnapshotStorePortV2;
+    readonly sessionStore: import('../../../v2/ports/session-event-log-store.port.js').SessionEventLogAppendStorePortV2;
+    readonly sha256: Sha256PortV2;
+    readonly idFactory: {
+        readonly mintNodeId: () => NodeId;
+        readonly mintEventId: () => string;
+    };
+}
+export interface AdvanceContext {
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly pinnedWorkflow: ReturnType<typeof createWorkflow>;
+    readonly engineState: EngineStateV1;
+    readonly pendingStep: ValidatedAdvanceInputs['pendingStep'];
+}
+export interface ComputedAdvanceResults {
+    readonly reasons: readonly ReasonV1[];
+    readonly effectiveReasons: readonly ReasonV1[];
+    readonly outputRequirement: ReturnType<typeof getOutputRequirementStatusWithArtifactsV1>;
+    readonly validation: ValidationResult | undefined;
+}
+export declare function executeAdvanceCore(args: {
+    readonly mode: AdvanceMode;
+    readonly truth: LoadedSessionTruthV2;
+    readonly sessionId: SessionId;
+    readonly runId: RunId;
+    readonly attemptId: AttemptId;
+    readonly workflowHash: WorkflowHash;
+    readonly dedupeKey: string;
+    readonly inputContext: JsonValue | undefined;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly lock: WithHealthySessionLock;
+    readonly pinnedWorkflow: ReturnType<typeof createWorkflow>;
+    readonly ports: AdvanceCorePorts;
+}): RA<void, InternalError | SessionEventLogStoreError | SnapshotStoreError>;

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

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeAdvanceCore = executeAdvanceCore;
+const neverthrow_1 = require("neverthrow");
+const snapshot_state_js_1 = require("../../../v2/durable-core/projections/snapshot-state.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 blocking_decision_js_1 = require("../../../v2/durable-core/domain/blocking-decision.js");
+const validation_criteria_validator_js_1 = require("../../../v2/durable-core/domain/validation-criteria-validator.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 v2_state_conversion_js_1 = require("../v2-state-conversion.js");
+const v2_execution_helpers_js_1 = require("../v2-execution-helpers.js");
+const with_timeout_js_1 = require("../shared/with-timeout.js");
+const input_validation_js_1 = require("./input-validation.js");
+const outcome_blocked_js_1 = require("./outcome-blocked.js");
+const outcome_success_js_1 = require("./outcome-success.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 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 = (0, input_validation_js_1.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 validationPhase = 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.okAsync)({ kind: 'evaluation_error', message: `${res.error.kind}: ${res.error.message}` });
+            }
+            return (0, neverthrow_1.okAsync)({ kind: 'completed', validation: res.value });
+        }).orElse((e) => {
+            if (e.kind === 'advance_apply_failed') {
+                return (0, neverthrow_1.okAsync)({ kind: 'evaluation_error', message: e.message });
+            }
+            return (0, neverthrow_1.errAsync)(e);
+        })
+        : (0, neverthrow_1.okAsync)({ kind: 'completed', validation: undefined });
+    return validationPhase.andThen((phase) => {
+        if (phase.kind === 'evaluation_error') {
+            const evalReason = { kind: 'evaluation_error' };
+            const reasons = [evalReason];
+            const effectiveReasons = [evalReason];
+            const outputRequirement = { kind: 'not_required' };
+            const evalValidation = {
+                valid: false,
+                issues: ['WorkRail could not evaluate the validation criteria for this step. This is not caused by your output.'],
+                suggestions: [(0, v2_execution_helpers_js_1.internalSuggestion)('Retry your submission with the same output.', 'The validation criteria for this step may be misconfigured.')],
+            };
+            const ctx = { truth, sessionId, runId, currentNodeId, attemptId, workflowHash, inputOutput, pinnedWorkflow, engineState, pendingStep };
+            const computed = { reasons, effectiveReasons, outputRequirement, validation: evalValidation };
+            const portsLocal = { snapshotStore, sessionStore, sha256, idFactory };
+            return (0, outcome_blocked_js_1.buildBlockedOutcome)({ mode, snap, ctx, computed, lock, ports: portsLocal });
+        }
+        const validation = phase.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 (0, outcome_blocked_js_1.buildBlockedOutcome)({ mode, snap, ctx, computed, lock, ports });
+        }
+        return (0, outcome_success_js_1.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 errAsync(e) {
+    return (0, neverthrow_1.errAsync)(e);
+}

package/dist/mcp/handlers/v2-advance-core/input-validation.d.ts

@@ -0,0 +1,44 @@
+import { type Result } from 'neverthrow';
+import type { RunId, NodeId } from '../../../v2/durable-core/ids/index.js';
+import type { LoadedSessionTruthV2 } from '../../../v2/ports/session-event-log-store.port.js';
+import type { JsonValue, JsonObject } from '../../../v2/durable-core/canonical/json-types.js';
+import type { V2ContinueWorkflowInput } from '../../v2/tools.js';
+import type { OutputContract } from '../../../types/workflow-definition.js';
+import type { ValidationCriteria } from '../../../types/validation.js';
+import type { InternalError } from '../v2-error-mapping.js';
+export interface ValidatedAdvanceInputs {
+    readonly pendingStep: {
+        readonly stepId: string;
+        readonly loopPath: readonly {
+            readonly loopId: string;
+            readonly iteration: number;
+        }[];
+    };
+    readonly mergedContext: Record<string, unknown>;
+    readonly inputContextObj: JsonObject | undefined;
+    readonly validationCriteria: ValidationCriteria | undefined;
+    readonly outputContract: OutputContract | undefined;
+    readonly notesMarkdown: string | undefined;
+    readonly artifacts: readonly unknown[];
+    readonly autonomy: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
+    readonly riskPolicy: 'conservative' | 'balanced' | 'aggressive';
+    readonly effectivePrefs: {
+        readonly autonomy: string;
+        readonly riskPolicy: string;
+    } | undefined;
+}
+export declare function validateAdvanceInputs(args: {
+    readonly truth: LoadedSessionTruthV2;
+    readonly runId: RunId;
+    readonly currentNodeId: NodeId;
+    readonly inputContext: JsonValue | undefined;
+    readonly inputOutput: V2ContinueWorkflowInput['output'];
+    readonly pinnedWorkflow: ReturnType<typeof import('../../../types/workflow.js').createWorkflow>;
+    readonly pendingStep: {
+        readonly stepId: string;
+        readonly loopPath: readonly {
+            readonly loopId: string;
+            readonly iteration: number;
+        }[];
+    };
+}): Result<ValidatedAdvanceInputs, InternalError>;

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAdvanceInputs = validateAdvanceInputs;
+const neverthrow_1 = require("neverthrow");
+const workflow_js_1 = require("../../../types/workflow.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 constants_js_1 = require("../../../v2/durable-core/constants.js");
+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 !== constants_js_1.EVENT_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,
+    });
+}