@exaudeus/workrail 1.4.0 → 1.5.1

package/dist/mcp/handlers/v2-execution/start.js

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAndPinWorkflow = loadAndPinWorkflow;
+exports.buildInitialEvents = buildInitialEvents;
+exports.mintStartTokens = mintStartTokens;
+exports.executeStartWorkflow = executeStartWorkflow;
+const output_schemas_js_1 = require("../../output-schemas.js");
+const step_instance_key_js_1 = require("../../../v2/durable-core/schemas/execution-snapshot/step-instance-key.js");
+const workflow_js_1 = require("../../../types/workflow.js");
+const index_js_1 = require("../../../v2/durable-core/ids/index.js");
+const workflow_hash_ref_js_1 = require("../../../v2/durable-core/ids/workflow-hash-ref.js");
+const neverthrow_1 = require("neverthrow");
+const v1_to_v2_shim_js_1 = require("../../../v2/read-only/v1-to-v2-shim.js");
+const hashing_js_1 = require("../../../v2/durable-core/canonical/hashing.js");
+const observation_builder_js_1 = require("../../../v2/durable-core/domain/observation-builder.js");
+const workflow_source_js_1 = require("../../../types/workflow-source.js");
+const workflow_definition_js_1 = require("../../../types/workflow-definition.js");
+const v2_execution_helpers_js_1 = require("../v2-execution-helpers.js");
+const v2_token_ops_js_1 = require("../v2-token-ops.js");
+const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
+const v2_execution_helpers_js_2 = require("../v2-execution-helpers.js");
+const v2_context_budget_js_1 = require("../v2-context-budget.js");
+const constants_js_1 = require("../../../v2/durable-core/constants.js");
+const index_js_2 = require("./index.js");
+function loadAndPinWorkflow(args) {
+    const { workflowId, workflowService, crypto, pinnedStore } = args;
+    return neverthrow_1.ResultAsync.fromPromise(workflowService.getWorkflowById(workflowId), (e) => ({
+        kind: 'precondition_failed',
+        message: e instanceof Error ? e.message : String(e),
+    }))
+        .andThen((workflow) => {
+        if (!workflow) {
+            return (0, neverthrow_1.errAsync)({ kind: 'workflow_not_found', workflowId: (0, index_js_1.asWorkflowId)(workflowId) });
+        }
+        const firstStep = workflow.definition.steps[0];
+        if (!firstStep) {
+            return (0, neverthrow_1.errAsync)({ kind: 'workflow_has_no_steps', workflowId: (0, index_js_1.asWorkflowId)(workflowId) });
+        }
+        return (0, neverthrow_1.okAsync)({ workflow, firstStep });
+    })
+        .andThen(({ workflow, firstStep }) => {
+        const compiled = (0, v1_to_v2_shim_js_1.compileV1WorkflowToPinnedSnapshot)(workflow);
+        const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(compiled, crypto);
+        if (workflowHashRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
+        }
+        const workflowHash = workflowHashRes.value;
+        return pinnedStore.get(workflowHash)
+            .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+            .andThen((existingPinned) => {
+            if (!existingPinned) {
+                return pinnedStore.put(workflowHash, compiled)
+                    .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }));
+            }
+            return (0, neverthrow_1.okAsync)(undefined);
+        })
+            .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })))
+            .andThen((pinned) => {
+            if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
+                return (0, neverthrow_1.errAsync)({
+                    kind: 'invariant_violation',
+                    message: 'Failed to pin executable workflow snapshot (missing or invalid pinned workflow).',
+                    suggestion: 'Retry start_workflow; if this persists, treat as invariant violation.',
+                });
+            }
+            const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+            return (0, neverthrow_1.okAsync)({ workflow, firstStep, workflowHash, pinnedWorkflow });
+        });
+    });
+}
+function buildInitialEvents(args) {
+    const { sessionId, runId, nodeId, workflowId, workflowHash, workflowSourceKind, workflowSourceRef, snapshotRef, context, observations, idFactory, } = args;
+    const evtSessionCreated = idFactory.mintEventId();
+    const evtRunStarted = idFactory.mintEventId();
+    const evtNodeCreated = idFactory.mintEventId();
+    const evtPreferencesChanged = idFactory.mintEventId();
+    const changeId = idFactory.mintEventId();
+    const baseEvents = [
+        {
+            v: 1,
+            eventId: evtSessionCreated,
+            eventIndex: 0,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.SESSION_CREATED,
+            dedupeKey: `session_created:${sessionId}`,
+            data: {},
+        },
+        {
+            v: 1,
+            eventId: evtRunStarted,
+            eventIndex: 1,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.RUN_STARTED,
+            dedupeKey: `run_started:${sessionId}:${runId}`,
+            scope: { runId },
+            data: {
+                workflowId,
+                workflowHash,
+                workflowSourceKind,
+                workflowSourceRef,
+            },
+        },
+        {
+            v: 1,
+            eventId: evtNodeCreated,
+            eventIndex: 2,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.NODE_CREATED,
+            dedupeKey: `node_created:${sessionId}:${runId}:${nodeId}`,
+            scope: { runId, nodeId },
+            data: {
+                nodeKind: 'step',
+                parentNodeId: null,
+                workflowHash,
+                snapshotRef,
+            },
+        },
+        {
+            v: 1,
+            eventId: evtPreferencesChanged,
+            eventIndex: 3,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.PREFERENCES_CHANGED,
+            dedupeKey: `preferences_changed:${sessionId}:${runId}:${nodeId}:${changeId}`,
+            scope: { runId, nodeId },
+            data: {
+                changeId,
+                source: 'system',
+                delta: [
+                    { key: 'autonomy', value: v2_execution_helpers_js_2.defaultPreferences.autonomy },
+                    { key: 'riskPolicy', value: v2_execution_helpers_js_2.defaultPreferences.riskPolicy },
+                ],
+                effective: {
+                    autonomy: v2_execution_helpers_js_2.defaultPreferences.autonomy,
+                    riskPolicy: v2_execution_helpers_js_2.defaultPreferences.riskPolicy,
+                },
+            },
+        },
+    ];
+    const mutableEvents = [...baseEvents];
+    if (context) {
+        const evtContextSet = idFactory.mintEventId();
+        const contextId = idFactory.mintEventId();
+        mutableEvents.push({
+            v: 1,
+            eventId: evtContextSet,
+            eventIndex: mutableEvents.length,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.CONTEXT_SET,
+            dedupeKey: `context_set:${sessionId}:${runId}:${contextId}`,
+            scope: { runId },
+            data: {
+                contextId,
+                context: context,
+                source: 'initial',
+            },
+        });
+    }
+    for (const obs of observations) {
+        const obsEventId = idFactory.mintEventId();
+        mutableEvents.push({
+            v: 1,
+            eventId: obsEventId,
+            eventIndex: mutableEvents.length,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.OBSERVATION_RECORDED,
+            dedupeKey: `observation_recorded:${sessionId}:${obs.key}`,
+            scope: undefined,
+            data: {
+                key: obs.key,
+                value: obs.value,
+                confidence: obs.confidence,
+            },
+        });
+    }
+    return mutableEvents;
+}
+function mintStartTokens(args) {
+    const { sessionId, runId, nodeId, attemptId, workflowHashRef, ports } = args;
+    const statePayload = {
+        tokenVersion: 1,
+        tokenKind: 'state',
+        sessionId,
+        runId,
+        nodeId,
+        workflowHashRef,
+    };
+    const ackPayload = {
+        tokenVersion: 1,
+        tokenKind: 'ack',
+        sessionId,
+        runId,
+        nodeId,
+        attemptId,
+    };
+    const checkpointPayload = {
+        tokenVersion: 1,
+        tokenKind: 'checkpoint',
+        sessionId,
+        runId,
+        nodeId,
+        attemptId,
+    };
+    const stateTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({ payload: statePayload, ports });
+    if (stateTokenRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: stateTokenRes.error });
+    }
+    const ackTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({ payload: ackPayload, ports });
+    if (ackTokenRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: ackTokenRes.error });
+    }
+    const checkpointTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({ payload: checkpointPayload, ports });
+    if (checkpointTokenRes.isErr()) {
+        return (0, neverthrow_1.errAsync)({ kind: 'token_signing_failed', cause: checkpointTokenRes.error });
+    }
+    return (0, neverthrow_1.okAsync)({
+        stateToken: stateTokenRes.value,
+        ackToken: ackTokenRes.value,
+        checkpointToken: checkpointTokenRes.value,
+    });
+}
+function executeStartWorkflow(input, ctx) {
+    if (!ctx.v2) {
+        return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
+    }
+    const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory } = ctx.v2;
+    if (!idFactory) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing idFactory',
+            suggestion: 'Reinitialize v2 tool context (idFactory must be provided when v2Tools are enabled).',
+        });
+    }
+    if (!tokenCodecPorts) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing tokenCodecPorts dependency',
+            suggestion: 'Reinitialize v2 tool context (tokenCodecPorts must be provided when v2Tools are enabled).',
+        });
+    }
+    const ctxCheck = (0, v2_context_budget_js_1.checkContextBudget)({ tool: 'start_workflow', context: input.context });
+    if (!ctxCheck.ok)
+        return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
+    return loadAndPinWorkflow({
+        workflowId: input.workflowId,
+        workflowService: ctx.workflowService,
+        crypto,
+        pinnedStore,
+    })
+        .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
+        const workspaceAnchor = ctx.v2?.workspaceAnchor;
+        const anchorsRA = workspaceAnchor
+            ? workspaceAnchor.resolveAnchors()
+                .map((anchors) => (0, observation_builder_js_1.anchorsToObservations)(anchors))
+                .orElse(() => (0, neverthrow_1.okAsync)([]))
+            : (0, neverthrow_1.okAsync)([]);
+        return anchorsRA.andThen((observations) => {
+            const sessionId = idFactory.mintSessionId();
+            const runId = idFactory.mintRunId();
+            const nodeId = idFactory.mintNodeId();
+            const snapshot = {
+                v: 1,
+                kind: 'execution_snapshot',
+                enginePayload: {
+                    v: 1,
+                    engineState: {
+                        kind: 'running',
+                        completed: { kind: 'set', values: [] },
+                        loopStack: [],
+                        pending: { kind: 'some', step: { stepId: (0, step_instance_key_js_1.asDelimiterSafeIdV1)(firstStep.id), loopPath: [] } },
+                    },
+                },
+            };
+            return snapshotStore.putExecutionSnapshotV1(snapshot)
+                .mapErr((cause) => ({ kind: 'snapshot_creation_failed', cause }))
+                .andThen((snapshotRef) => {
+                const workflowSourceRef = workflow.source.kind === 'user' || workflow.source.kind === 'project' || workflow.source.kind === 'custom'
+                    ? workflow.source.directoryPath
+                    : workflow.source.kind === 'git'
+                        ? `${workflow.source.repositoryUrl}#${workflow.source.branch}`
+                        : workflow.source.kind === 'remote'
+                            ? workflow.source.registryUrl
+                            : workflow.source.kind === 'plugin'
+                                ? `${workflow.source.pluginName}@${workflow.source.pluginVersion}`
+                                : '(bundled)';
+                const events = buildInitialEvents({
+                    sessionId,
+                    runId,
+                    nodeId,
+                    workflowId: workflow.definition.id,
+                    workflowHash,
+                    workflowSourceKind: (0, v2_state_conversion_js_1.mapWorkflowSourceKind)(workflow.source.kind),
+                    workflowSourceRef,
+                    snapshotRef,
+                    context: input.context,
+                    observations,
+                    idFactory,
+                });
+                return gate.withHealthySessionLock(sessionId, (lock) => sessionStore.append(lock, {
+                    events,
+                    snapshotPins: [{ snapshotRef, eventIndex: 2, createdByEventId: events[2].eventId }],
+                }))
+                    .mapErr((cause) => ({ kind: 'session_append_failed', cause }))
+                    .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, sessionId, runId, nodeId }));
+            });
+        });
+    })
+        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId }) => {
+        const wfRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
+        if (wfRefRes.isErr()) {
+            return (0, neverthrow_1.errAsync)({
+                kind: 'precondition_failed',
+                message: wfRefRes.error.message,
+                suggestion: 'Ensure the pinned workflowHash is a valid sha256 digest.',
+            });
+        }
+        const attemptId = (0, v2_token_ops_js_1.newAttemptId)(idFactory);
+        return mintStartTokens({
+            sessionId,
+            runId,
+            nodeId,
+            attemptId,
+            workflowHashRef: wfRefRes.value,
+            ports: tokenCodecPorts,
+        }).andThen((tokens) => {
+            const meta = (0, v2_execution_helpers_js_1.renderPendingPromptOrDefault)({
+                workflow: pinnedWorkflow,
+                stepId: firstStep.id,
+                loopPath: [],
+                truth: { events: [], manifest: [] },
+                runId: (0, index_js_1.asRunId)(String(runId)),
+                nodeId: (0, index_js_1.asNodeId)(String(nodeId)),
+                rehydrateOnly: false,
+            });
+            const pending = { stepId: meta.stepId, title: meta.title, prompt: meta.prompt };
+            const preferences = v2_execution_helpers_js_2.defaultPreferences;
+            const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: false, isComplete: false, pending: meta });
+            return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
+                stateToken: tokens.stateToken,
+                ackToken: tokens.ackToken,
+                checkpointToken: tokens.checkpointToken,
+                isComplete: false,
+                pending,
+                preferences,
+                nextIntent,
+                nextCall: (0, index_js_2.buildNextCall)({ stateToken: tokens.stateToken, ackToken: tokens.ackToken, isComplete: false, pending }),
+            }));
+        });
+    });
+}

package/dist/mcp/handlers/v2-execution-helpers.d.ts

@@ -97,3 +97,26 @@ export declare function mapExecutionSessionGateErrorToToolError(e: ExecutionSess
 export declare function mapSnapshotStoreErrorToToolError(e: SnapshotStoreError, suggestion?: string): ToolFailure;
 export declare function mapPinnedWorkflowStoreErrorToToolError(e: PinnedWorkflowStoreError, suggestion?: string): ToolFailure;
 export declare function mapSessionOrGateErrorToToolError(e: SessionEventLogStoreError | ExecutionSessionGateErrorV2): ToolFailure;
+import type { LoopPathFrameV1 } from '../../v2/durable-core/schemas/execution-snapshot/index.js';
+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 StepMetadata } from '../../v2/durable-core/domain/prompt-renderer.js';
+export declare function renderPendingPromptOrDefault(args: {
+    readonly workflow: ReturnType<typeof import('../../types/workflow.js').createWorkflow>;
+    readonly stepId: string;
+    readonly loopPath: readonly LoopPathFrameV1[];
+    readonly truth: LoadedSessionTruthV2;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+    readonly rehydrateOnly: boolean;
+}): StepMetadata;
+export type PreferencesV2 = {
+    readonly autonomy: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
+    readonly riskPolicy: 'conservative' | 'balanced' | 'aggressive';
+};
+export declare const defaultPreferences: PreferencesV2;
+export declare function derivePreferencesOrDefault(args: {
+    readonly truth: LoadedSessionTruthV2;
+    readonly runId: RunId;
+    readonly nodeId: NodeId;
+}): PreferencesV2;

package/dist/mcp/handlers/v2-execution-helpers.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultPreferences = void 0;
 exports.mapStartWorkflowErrorToToolError = mapStartWorkflowErrorToToolError;
 exports.mapContinueWorkflowErrorToToolError = mapContinueWorkflowErrorToToolError;
 exports.mapTokenDecodeErrorToToolError = mapTokenDecodeErrorToToolError;
@@ -11,6 +12,8 @@ exports.mapExecutionSessionGateErrorToToolError = mapExecutionSessionGateErrorTo
 exports.mapSnapshotStoreErrorToToolError = mapSnapshotStoreErrorToToolError;
 exports.mapPinnedWorkflowStoreErrorToToolError = mapPinnedWorkflowStoreErrorToToolError;
 exports.mapSessionOrGateErrorToToolError = mapSessionOrGateErrorToToolError;
+exports.renderPendingPromptOrDefault = renderPendingPromptOrDefault;
+exports.derivePreferencesOrDefault = derivePreferencesOrDefault;
 const types_js_1 = require("../types.js");
 const types_js_2 = require("../types.js");
 function mapStartWorkflowErrorToToolError(e) {
@@ -91,7 +94,7 @@ function mapTokenDecodeErrorToToolError(e) {
                 suggestion: 'Copy the entire token string exactly as returned. Use triple-click to select the complete line.',
                 details: {
                     errorType: 'corruption_detected',
-                    estimatedPosition: bech32mErr.position,
+                    estimatedPosition: bech32mErr.position ?? null,
                     tokenFormat: 'binary+bech32m',
                 },
             });
@@ -279,3 +282,41 @@ function mapSessionOrGateErrorToToolError(e) {
     const _exhaustive = e;
     return _exhaustive;
 }
+const prompt_renderer_js_1 = require("../../v2/durable-core/domain/prompt-renderer.js");
+function renderPendingPromptOrDefault(args) {
+    return (0, prompt_renderer_js_1.renderPendingPrompt)({
+        workflow: args.workflow,
+        stepId: args.stepId,
+        loopPath: args.loopPath,
+        truth: args.truth,
+        runId: args.runId,
+        nodeId: args.nodeId,
+        rehydrateOnly: args.rehydrateOnly,
+    }).unwrapOr({
+        stepId: args.stepId,
+        title: args.stepId,
+        prompt: `Pending step: ${args.stepId}`,
+        requireConfirmation: false,
+    });
+}
+const constants_js_1 = require("../../v2/durable-core/constants.js");
+const preferences_js_1 = require("../../v2/projections/preferences.js");
+exports.defaultPreferences = {
+    autonomy: 'guided',
+    riskPolicy: 'conservative'
+};
+function derivePreferencesOrDefault(args) {
+    const parentByNodeId = {};
+    for (const e of args.truth.events) {
+        if (e.kind !== constants_js_1.EVENT_KIND.NODE_CREATED)
+            continue;
+        if (e.scope?.runId !== String(args.runId))
+            continue;
+        parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
+    }
+    const prefs = (0, preferences_js_1.projectPreferencesV2)(args.truth.events, parentByNodeId);
+    if (prefs.isErr())
+        return exports.defaultPreferences;
+    const p = prefs.value.byNodeId[String(args.nodeId)]?.effective;
+    return p ? { autonomy: p.autonomy, riskPolicy: p.riskPolicy } : exports.defaultPreferences;
+}

package/dist/mcp/handlers/v2-execution.d.ts

@@ -1,23 +1 @@
-import type { ToolContext, ToolResult } from '../types.js';
-import type { V2ContinueWorkflowInput, V2StartWorkflowInput } from '../v2/tools.js';
-type NextCallTemplate = {
-    readonly tool: 'continue_workflow';
-    readonly params: {
-        readonly intent: 'advance';
-        readonly stateToken: string;
-        readonly ackToken: string;
-    };
-};
-export declare function buildNextCall(args: {
-    readonly stateToken: string;
-    readonly ackToken: string | undefined;
-    readonly isComplete: boolean;
-    readonly pending: {
-        readonly stepId: string;
-    } | null;
-    readonly retryable?: boolean;
-    readonly retryAckToken?: string;
-}): NextCallTemplate | null;
-export declare function handleV2StartWorkflow(input: V2StartWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
-export declare function handleV2ContinueWorkflow(input: V2ContinueWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
-export {};
+export { handleV2StartWorkflow, handleV2ContinueWorkflow, buildNextCall } from './v2-execution/index.js';