@exaudeus/workrail 2.1.0 → 3.1.0

package/dist/engine/engine-factory.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkRailEngine = createWorkRailEngine;
+require("reflect-metadata");
+const container_js_1 = require("../di/container.js");
+const tokens_js_1 = require("../di/tokens.js");
+const token_codec_ports_js_1 = require("../v2/durable-core/tokens/token-codec-ports.js");
+const validation_js_1 = require("../application/validation.js");
+const v1_to_v2_shim_js_1 = require("../v2/read-only/v1-to-v2-shim.js");
+const feature_flags_js_1 = require("../config/feature-flags.js");
+const index_js_1 = require("../v2/infra/local/data-dir/index.js");
+const start_js_1 = require("../mcp/handlers/v2-execution/start.js");
+const index_js_2 = require("../mcp/handlers/v2-execution/index.js");
+const v2_checkpoint_js_1 = require("../mcp/handlers/v2-checkpoint.js");
+const types_js_1 = require("./types.js");
+async function safeAsync(fn) {
+    try {
+        return (0, types_js_1.engineOk)(await fn());
+    }
+    catch (e) {
+        return (0, types_js_1.engineErr)({
+            kind: 'storage_error',
+            message: e instanceof Error ? e.message : String(e),
+        });
+    }
+}
+function mapStartError(e) {
+    switch (e.kind) {
+        case 'workflow_not_found':
+            return { kind: 'workflow_not_found', workflowId: e.workflowId };
+        case 'workflow_has_no_steps':
+            return { kind: 'workflow_has_no_steps', workflowId: e.workflowId };
+        case 'workflow_compile_failed':
+            return { kind: 'workflow_compile_failed', message: e.message };
+        case 'token_signing_failed':
+            return { kind: 'token_signing_failed', message: String(e.cause) };
+        case 'prompt_render_failed':
+            return { kind: 'prompt_render_failed', message: e.message };
+        case 'precondition_failed':
+            return { kind: 'precondition_failed', message: e.message };
+        case 'invariant_violation':
+            return { kind: 'internal_error', message: e.message };
+        case 'validation_failed':
+            return { kind: 'validation_failed', message: e.failure.message };
+        case 'keyring_load_failed':
+            return { kind: 'internal_error', message: e.cause.message, code: e.cause.code };
+        case 'hash_computation_failed':
+            return { kind: 'internal_error', message: e.message };
+        case 'pinned_workflow_store_failed':
+            return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
+        case 'snapshot_creation_failed':
+            return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
+        case 'session_append_failed':
+            return { kind: 'session_error', message: e.cause.message, code: e.cause.code };
+    }
+}
+function mapContinueError(e) {
+    switch (e.kind) {
+        case 'precondition_failed':
+            return { kind: 'precondition_failed', message: e.message };
+        case 'token_unknown_node':
+            return { kind: 'token_invalid', message: e.message };
+        case 'invariant_violation':
+            return { kind: 'internal_error', message: e.message };
+        case 'validation_failed':
+            return { kind: 'validation_failed', message: e.failure.message };
+        case 'token_decode_failed':
+            return { kind: 'token_invalid', message: e.cause.message, code: e.cause.code };
+        case 'token_verify_failed':
+            return { kind: 'token_invalid', message: e.cause.message, code: e.cause.code };
+        case 'keyring_load_failed':
+            return { kind: 'internal_error', message: e.cause.message, code: e.cause.code };
+        case 'session_load_failed':
+            return { kind: 'session_error', message: e.cause.message, code: e.cause.code };
+        case 'snapshot_load_failed':
+            return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
+        case 'pinned_workflow_store_failed':
+            return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
+        case 'pinned_workflow_missing':
+            return { kind: 'storage_error', message: `Pinned workflow missing: ${e.workflowHash}` };
+        case 'token_signing_failed':
+            return { kind: 'token_signing_failed', message: String(e.cause) };
+        case 'advance_execution_failed':
+            return { kind: 'session_error', message: e.cause.message, code: e.cause.code };
+        case 'prompt_render_failed':
+            return { kind: 'prompt_render_failed', message: e.message };
+    }
+}
+function mapCheckpointError(e) {
+    switch (e.kind) {
+        case 'precondition_failed':
+            return { kind: 'precondition_failed', message: e.message };
+        case 'token_signing_failed':
+            return { kind: 'token_signing_failed', message: String(e.cause) };
+        case 'validation_failed':
+            return { kind: 'validation_failed', message: e.failure.message };
+        case 'missing_node_or_run':
+            return { kind: 'session_error', message: 'Node or run not found in session events' };
+        case 'event_schema_invalid':
+            return { kind: 'internal_error', message: `Event schema invalid: ${e.issues}` };
+        case 'gate_failed':
+            return { kind: 'session_error', message: e.cause.message, code: e.cause.code };
+        case 'store_failed':
+            return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
+    }
+}
+function mapPending(raw) {
+    if (!raw)
+        return null;
+    return {
+        stepId: raw.stepId,
+        title: raw.title,
+        prompt: raw.prompt,
+        ...(raw.agentRole ? { agentRole: raw.agentRole } : {}),
+    };
+}
+function mapStartOutput(out) {
+    const ct = out.continueToken ?? '';
+    return {
+        kind: 'ok',
+        stateToken: (0, types_js_1.asStateToken)(ct),
+        ackToken: (0, types_js_1.asAckToken)(ct),
+        checkpointToken: out.checkpointToken ? (0, types_js_1.asCheckpointToken)(out.checkpointToken) : null,
+        isComplete: out.isComplete,
+        pending: mapPending(out.pending),
+        preferences: out.preferences,
+        nextIntent: out.nextIntent,
+    };
+}
+function mapContinueOutput(out) {
+    const ct = out.continueToken ?? '';
+    const base = {
+        stateToken: (0, types_js_1.asStateToken)(ct),
+        ackToken: (0, types_js_1.asAckToken)(ct),
+        checkpointToken: out.checkpointToken ? (0, types_js_1.asCheckpointToken)(out.checkpointToken) : null,
+        isComplete: out.isComplete,
+        pending: mapPending(out.pending),
+        preferences: out.preferences,
+        nextIntent: out.nextIntent,
+    };
+    if (out.kind === 'blocked') {
+        const blocked = {
+            kind: 'blocked',
+            ...base,
+            blockers: out.blockers.blockers.map(b => ({
+                code: b.code,
+                message: b.message,
+                ...(b.suggestedFix ? { suggestedFix: b.suggestedFix } : {}),
+            })),
+            retryable: out.retryable ?? false,
+            retryAckToken: out.retryContinueToken ? (0, types_js_1.asAckToken)(out.retryContinueToken) : null,
+        };
+        return blocked;
+    }
+    return { kind: 'ok', ...base };
+}
+let engineActive = false;
+async function createWorkRailEngine(config = {}) {
+    if (engineActive) {
+        return (0, types_js_1.engineErr)({
+            kind: 'precondition_failed',
+            message: 'An engine is already active. Call engine.close() before creating another instance.',
+        });
+    }
+    await (0, container_js_1.initializeContainer)({ runtimeMode: { kind: 'library' } });
+    if (config.dataDir) {
+        const customEnv = { ...process.env, WORKRAIL_DATA_DIR: config.dataDir };
+        container_js_1.container.register(tokens_js_1.DI.V2.DataDir, { useValue: new index_js_1.LocalDataDirV2(customEnv) });
+    }
+    const workflowService = container_js_1.container.resolve(tokens_js_1.DI.Services.Workflow);
+    const gate = container_js_1.container.resolve(tokens_js_1.DI.V2.ExecutionGate);
+    const sessionStore = container_js_1.container.resolve(tokens_js_1.DI.V2.SessionStore);
+    const snapshotStore = container_js_1.container.resolve(tokens_js_1.DI.V2.SnapshotStore);
+    const pinnedStore = container_js_1.container.resolve(tokens_js_1.DI.V2.PinnedWorkflowStore);
+    const keyringPort = container_js_1.container.resolve(tokens_js_1.DI.V2.Keyring);
+    const keyringResult = await keyringPort.loadOrCreate();
+    if (keyringResult.isErr()) {
+        (0, container_js_1.resetContainer)();
+        return (0, types_js_1.engineErr)({
+            kind: 'internal_error',
+            message: keyringResult.error.message,
+            code: keyringResult.error.code,
+        });
+    }
+    const sha256 = container_js_1.container.resolve(tokens_js_1.DI.V2.Sha256);
+    const crypto = container_js_1.container.resolve(tokens_js_1.DI.V2.Crypto);
+    const entropy = container_js_1.container.resolve(tokens_js_1.DI.V2.RandomEntropy);
+    const hmac = container_js_1.container.resolve(tokens_js_1.DI.V2.HmacSha256);
+    const base64url = container_js_1.container.resolve(tokens_js_1.DI.V2.Base64Url);
+    const base32 = container_js_1.container.resolve(tokens_js_1.DI.V2.Base32);
+    const bech32m = container_js_1.container.resolve(tokens_js_1.DI.V2.Bech32m);
+    const idFactory = container_js_1.container.resolve(tokens_js_1.DI.V2.IdFactory);
+    const tokenCodecPorts = (0, token_codec_ports_js_1.unsafeTokenCodecPorts)({
+        keyring: keyringResult.value,
+        hmac,
+        base64url,
+        base32,
+        bech32m,
+    });
+    const validationEngine = container_js_1.container.resolve(tokens_js_1.DI.Infra.ValidationEngine);
+    const compiler = container_js_1.container.resolve(tokens_js_1.DI.Services.WorkflowCompiler);
+    const validationPipelineDeps = {
+        schemaValidate: validation_js_1.validateWorkflowSchema,
+        structuralValidate: validationEngine.validateWorkflowStructureOnly.bind(validationEngine),
+        compiler,
+        normalizeToExecutable: v1_to_v2_shim_js_1.normalizeV1WorkflowToPinnedSnapshot,
+    };
+    const dataDir = container_js_1.container.resolve(tokens_js_1.DI.V2.DataDir);
+    const tokenAliasStore = container_js_1.container.resolve(tokens_js_1.DI.V2.TokenAliasStore);
+    const aliasLoadResult = await tokenAliasStore.loadIndex();
+    if (aliasLoadResult.isErr()) {
+        console.error(`[engine-factory] Token alias index load warning: ${aliasLoadResult.error.message}`);
+    }
+    const v2 = {
+        gate,
+        sessionStore,
+        snapshotStore,
+        pinnedStore,
+        sha256,
+        crypto,
+        entropy,
+        idFactory,
+        tokenCodecPorts,
+        tokenAliasStore,
+        validationPipelineDeps,
+        resolvedRootUris: [],
+        dataDir,
+    };
+    const featureFlags = new feature_flags_js_1.StaticFeatureFlagProvider({ v2Tools: true });
+    const ctx = {
+        workflowService,
+        featureFlags,
+        sessionManager: null,
+        httpServer: null,
+        v2,
+    };
+    const v2Ctx = ctx;
+    engineActive = true;
+    const engine = {
+        async startWorkflow(workflowId) {
+            const result = await (0, start_js_1.executeStartWorkflow)({ workflowId }, v2Ctx);
+            if (result.isErr()) {
+                return (0, types_js_1.engineErr)(mapStartError(result.error));
+            }
+            return (0, types_js_1.engineOk)(mapStartOutput(result.value));
+        },
+        async continueWorkflow(stateToken, ackToken, output, context) {
+            const intent = ackToken ? 'advance' : 'rehydrate';
+            const input = {
+                continueToken: (0, types_js_1.unwrapToken)(stateToken),
+                intent: intent,
+                ...(output ? {
+                    output: {
+                        notesMarkdown: output.notesMarkdown,
+                        ...(output.artifacts?.length ? { artifacts: [...output.artifacts] } : {}),
+                    },
+                } : {}),
+                ...(context ? { context } : {}),
+            };
+            const result = await (0, index_js_2.executeContinueWorkflow)(input, v2Ctx);
+            if (result.isErr()) {
+                return (0, types_js_1.engineErr)(mapContinueError(result.error));
+            }
+            return (0, types_js_1.engineOk)(mapContinueOutput(result.value));
+        },
+        async checkpointWorkflow(checkpointToken) {
+            const result = await (0, v2_checkpoint_js_1.executeCheckpoint)({ checkpointToken: (0, types_js_1.unwrapToken)(checkpointToken) }, v2Ctx);
+            if (result.isErr()) {
+                return (0, types_js_1.engineErr)(mapCheckpointError(result.error));
+            }
+            return (0, types_js_1.engineOk)({
+                checkpointNodeId: result.value.checkpointNodeId,
+                stateToken: (0, types_js_1.asStateToken)(result.value.stateToken),
+            });
+        },
+        async listWorkflows() {
+            const result = await safeAsync(() => workflowService.listWorkflowSummaries());
+            if (!result.ok)
+                return result;
+            return (0, types_js_1.engineOk)({
+                workflows: result.value.map((s) => ({
+                    workflowId: s.id,
+                    name: s.name,
+                    description: s.description,
+                    version: s.version,
+                })),
+            });
+        },
+        async close() {
+            (0, container_js_1.resetContainer)();
+            engineActive = false;
+        },
+    };
+    return (0, types_js_1.engineOk)(engine);
+}

package/dist/engine/index.d.ts

@@ -0,0 +1,3 @@
+export { createWorkRailEngine } from './engine-factory.js';
+export type { WorkRailEngine, EngineConfig, EngineResult, EngineError, InfraErrorCode, StepResponse, StepResponseOk, StepResponseBlocked, CheckpointResponse, WorkflowListResponse, WorkflowListItem, PendingStep, StepPreferences, Autonomy, RiskPolicy, NextIntent, Blocker, BlockerCode, StateToken, AckToken, CheckpointToken, } from './types.js';
+export { engineOk, engineErr, asStateToken, asAckToken, asCheckpointToken, unwrapToken } from './types.js';

package/dist/engine/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapToken = exports.asCheckpointToken = exports.asAckToken = exports.asStateToken = exports.engineErr = exports.engineOk = exports.createWorkRailEngine = void 0;
+var engine_factory_js_1 = require("./engine-factory.js");
+Object.defineProperty(exports, "createWorkRailEngine", { enumerable: true, get: function () { return engine_factory_js_1.createWorkRailEngine; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "engineOk", { enumerable: true, get: function () { return types_js_1.engineOk; } });
+Object.defineProperty(exports, "engineErr", { enumerable: true, get: function () { return types_js_1.engineErr; } });
+Object.defineProperty(exports, "asStateToken", { enumerable: true, get: function () { return types_js_1.asStateToken; } });
+Object.defineProperty(exports, "asAckToken", { enumerable: true, get: function () { return types_js_1.asAckToken; } });
+Object.defineProperty(exports, "asCheckpointToken", { enumerable: true, get: function () { return types_js_1.asCheckpointToken; } });
+Object.defineProperty(exports, "unwrapToken", { enumerable: true, get: function () { return types_js_1.unwrapToken; } });

package/dist/engine/types.d.ts

@@ -0,0 +1,130 @@
+declare const StateTokenBrand: unique symbol;
+declare const AckTokenBrand: unique symbol;
+declare const CheckpointTokenBrand: unique symbol;
+export type StateToken = string & {
+    readonly [StateTokenBrand]: never;
+};
+export type AckToken = string & {
+    readonly [AckTokenBrand]: never;
+};
+export type CheckpointToken = string & {
+    readonly [CheckpointTokenBrand]: never;
+};
+export declare function asStateToken(s: string): StateToken;
+export declare function asAckToken(s: string): AckToken;
+export declare function asCheckpointToken(s: string): CheckpointToken;
+export declare function unwrapToken(t: StateToken | AckToken | CheckpointToken): string;
+export interface PendingStep {
+    readonly stepId: string;
+    readonly title: string;
+    readonly prompt: string;
+    readonly agentRole?: string;
+}
+export type Autonomy = 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
+export type RiskPolicy = 'conservative' | 'balanced' | 'aggressive';
+export interface StepPreferences {
+    readonly autonomy: Autonomy;
+    readonly riskPolicy: RiskPolicy;
+}
+export type NextIntent = 'perform_pending_then_continue' | 'await_user_confirmation' | 'rehydrate_only' | 'complete';
+export type BlockerCode = 'USER_ONLY_DEPENDENCY' | 'MISSING_REQUIRED_OUTPUT' | 'INVALID_REQUIRED_OUTPUT' | 'MISSING_REQUIRED_NOTES' | 'MISSING_CONTEXT_KEY' | 'CONTEXT_BUDGET_EXCEEDED' | 'REQUIRED_CAPABILITY_UNKNOWN' | 'REQUIRED_CAPABILITY_UNAVAILABLE' | 'INVARIANT_VIOLATION' | 'STORAGE_CORRUPTION_DETECTED';
+export interface Blocker {
+    readonly code: BlockerCode;
+    readonly message: string;
+    readonly suggestedFix?: string;
+}
+interface StepResponseBase {
+    readonly stateToken: StateToken;
+    readonly ackToken: AckToken | null;
+    readonly checkpointToken: CheckpointToken | null;
+    readonly isComplete: boolean;
+    readonly preferences: StepPreferences;
+    readonly nextIntent: NextIntent;
+}
+export interface StepResponseOk extends StepResponseBase {
+    readonly kind: 'ok';
+    readonly pending: PendingStep | null;
+}
+export interface StepResponseBlocked extends StepResponseBase {
+    readonly kind: 'blocked';
+    readonly pending: PendingStep | null;
+    readonly blockers: readonly Blocker[];
+    readonly retryable: boolean;
+    readonly retryAckToken: AckToken | null;
+}
+export type StepResponse = StepResponseOk | StepResponseBlocked;
+export interface CheckpointResponse {
+    readonly checkpointNodeId: string;
+    readonly stateToken: StateToken;
+}
+export interface WorkflowListItem {
+    readonly workflowId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+}
+export interface WorkflowListResponse {
+    readonly workflows: readonly WorkflowListItem[];
+}
+export type InfraErrorCode = string;
+export type EngineError = {
+    readonly kind: 'workflow_not_found';
+    readonly workflowId: string;
+} | {
+    readonly kind: 'workflow_has_no_steps';
+    readonly workflowId: string;
+} | {
+    readonly kind: 'workflow_compile_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'validation_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'token_invalid';
+    readonly message: string;
+    readonly code?: InfraErrorCode;
+} | {
+    readonly kind: 'token_signing_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'session_error';
+    readonly message: string;
+    readonly code?: InfraErrorCode;
+} | {
+    readonly kind: 'storage_error';
+    readonly message: string;
+    readonly code?: InfraErrorCode;
+} | {
+    readonly kind: 'prompt_render_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'precondition_failed';
+    readonly message: string;
+} | {
+    readonly kind: 'internal_error';
+    readonly message: string;
+    readonly code?: InfraErrorCode;
+};
+export type EngineResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: EngineError;
+};
+export declare function engineOk<T>(value: T): EngineResult<T>;
+export declare function engineErr<T>(error: EngineError): EngineResult<T>;
+export interface EngineConfig {
+    readonly dataDir?: string;
+}
+export interface WorkRailEngine {
+    readonly startWorkflow: (workflowId: string) => Promise<EngineResult<StepResponse>>;
+    readonly continueWorkflow: (stateToken: StateToken, ackToken: AckToken | null, output?: {
+        readonly notesMarkdown?: string;
+        readonly artifacts?: readonly unknown[];
+    }, context?: Readonly<Record<string, unknown>>) => Promise<EngineResult<StepResponse>>;
+    readonly checkpointWorkflow: (checkpointToken: CheckpointToken) => Promise<EngineResult<CheckpointResponse>>;
+    readonly listWorkflows: () => Promise<EngineResult<WorkflowListResponse>>;
+    readonly close: () => Promise<void>;
+}
+export {};

package/dist/engine/types.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asStateToken = asStateToken;
+exports.asAckToken = asAckToken;
+exports.asCheckpointToken = asCheckpointToken;
+exports.unwrapToken = unwrapToken;
+exports.engineOk = engineOk;
+exports.engineErr = engineErr;
+function asStateToken(s) { return s; }
+function asAckToken(s) { return s; }
+function asCheckpointToken(s) { return s; }
+function unwrapToken(t) { return t; }
+function engineOk(value) {
+    return { ok: true, value };
+}
+function engineErr(error) {
+    return { ok: false, error };
+}