@tomflow/proflow-execution-runtime 0.1.0

package/dist/src/formal-process.js

@@ -0,0 +1,161 @@
+import { readFile, stat } from "node:fs/promises";
+import { createBrowserExecutorComposition, loadBrowserExecutorCompositionConfig, } from "@tomflow/proflow-execution-browser-extension/runtime-composition";
+import { createExecutionBrowserVisionClient } from "./browser-vision-client.js";
+import { createExecutionModelDecisionClient } from "./model-decision-client.js";
+import { createExecutionRuntimeProcess, } from "./service.js";
+async function readSecret(path, name) {
+    const info = await stat(path);
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+        throw new TypeError(`${name} permissions must be owner-only`);
+    const value = (await readFile(path, "utf8")).trim();
+    if (value.length < 32)
+        throw new TypeError(`${name} must contain at least 32 characters`);
+    return value;
+}
+async function createIdentityClient(config) {
+    const token = await readSecret(config.tokenFile, "execution identity token");
+    let ready = false;
+    const headers = { authorization: `Bearer ${token}` };
+    try {
+        ready = (await fetch(`${config.endpoint}/internal/execution/identity/ready`, {
+            headers,
+            signal: AbortSignal.timeout(2_000),
+        })).ok;
+    }
+    catch {
+        ready = false;
+    }
+    return {
+        port: {
+            async authorize(request) {
+                try {
+                    const response = await fetch(`${config.endpoint}/internal/execution/authorize`, {
+                        method: "POST",
+                        headers: { ...headers, "content-type": "application/json" },
+                        body: JSON.stringify(request),
+                        signal: AbortSignal.timeout(5_000),
+                    });
+                    ready = response.ok;
+                    if (!response.ok)
+                        return false;
+                    const body = (await response.json());
+                    return body.authorized === true;
+                }
+                catch {
+                    ready = false;
+                    return false;
+                }
+            },
+        },
+        readiness: () => ready,
+    };
+}
+function assertFormalConfig(config) {
+    if (!config.identity)
+        throw new Error("formal execution-runtime requires identity configuration");
+    if (!config.transportCredentialFile)
+        throw new Error("formal execution-runtime requires transportCredentialFile");
+    if (!config.browserExecutorConfigPath)
+        throw new Error("formal execution-runtime requires browserExecutorConfigPath");
+    if (!config.modelDecision)
+        throw new Error("formal execution-runtime requires modelDecision configuration");
+    if (!config.modelDecision.credentialFile)
+        throw new Error("formal execution-runtime requires modelDecision.credentialFile");
+    return {
+        identity: config.identity,
+        transportCredentialFile: config.transportCredentialFile,
+        browserExecutorConfigPath: config.browserExecutorConfigPath,
+        modelDecision: {
+            ...config.modelDecision,
+            credentialFile: config.modelDecision.credentialFile,
+        },
+    };
+}
+export function createFormalExecutionRuntimeLifecycle(input) {
+    const required = assertFormalConfig(input.config);
+    let current;
+    const build = async () => {
+        const identityClient = await createIdentityClient(required.identity);
+        const transportCredential = await readSecret(required.transportCredentialFile, "execution transport credential");
+        const modelDecisionCredential = await readSecret(required.modelDecision.credentialFile, "model decision transport credential");
+        const modelDecisionClient = createExecutionModelDecisionClient({
+            endpoint: required.modelDecision.endpoint,
+            ...(required.modelDecision.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: required.modelDecision.timeoutMs }),
+            credential: modelDecisionCredential,
+        });
+        await modelDecisionClient.probe();
+        const browserVisionClient = createExecutionBrowserVisionClient({
+            endpoint: required.modelDecision.endpoint,
+            ...(required.modelDecision.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: required.modelDecision.timeoutMs }),
+            credential: modelDecisionCredential,
+        });
+        const browserComposition = await createBrowserExecutorComposition({
+            ...(await loadBrowserExecutorCompositionConfig(required.browserExecutorConfigPath)),
+            vision: browserVisionClient.port,
+        });
+        try {
+            const service = await createExecutionRuntimeProcess({
+                config: input.config,
+                identity: identityClient.port,
+                identityReadiness: identityClient.readiness,
+                transportCredential,
+                requireModelDecision: true,
+                modelDecision: modelDecisionClient.port,
+                modelDecisionReadiness: modelDecisionClient.readiness,
+                browserExecutor: browserComposition.browserExecutor,
+                browserReadiness: () => browserComposition.bridgeStatus().online,
+                carrierSummary: () => browserComposition.bridgeStatus(),
+                ...(input.log === undefined ? {} : { log: input.log }),
+            });
+            return {
+                service,
+                closeBrowser: () => browserComposition.close(),
+                browserBridgeEndpoint: browserComposition.bridgeEndpoint,
+            };
+        }
+        catch (error) {
+            await browserComposition.close();
+            throw error;
+        }
+    };
+    return Object.freeze({
+        status: () => current?.service.status() ?? {
+            readiness: "NOT_READY",
+        },
+        async start() {
+            if (current !== undefined)
+                throw new Error("formal execution-runtime lifecycle is already started");
+            current = await build();
+            try {
+                const address = await current.service.start();
+                return {
+                    ...address,
+                    browserBridgeEndpoint: current.browserBridgeEndpoint,
+                };
+            }
+            catch (error) {
+                await current.closeBrowser();
+                current = undefined;
+                throw error;
+            }
+        },
+        async stop() {
+            if (current === undefined)
+                return;
+            const closing = current;
+            current = undefined;
+            await Promise.allSettled([
+                closing.service.stop(),
+                closing.closeBrowser(),
+            ]);
+        },
+        async restart() {
+            await this.stop();
+            return this.start();
+        },
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,122 @@
+import { type ExecuteCapabilityRequest, type ExecutionArtifactRecord, type ExecutionErrorCode, type ExecutionRecord, type ReadExecutionOutputResponse } from "@tomflow/proflow-execution-contracts";
+import type { ExecutionExecutorPort, ExecutorPrecondition } from "./executor-port.ts";
+export declare const moduleRef: "execution-runtime";
+type MaybePromise<Value> = Value | Promise<Value>;
+type AdmissionDecision = {
+    decision: "ALLOW" | "DENY" | "REVIEW";
+    decisionPath: "deterministic" | "fast" | "reason";
+    approvalRequired?: boolean;
+    reason?: string;
+};
+export interface ExecutionPolicyPort {
+    decide(request: ExecuteCapabilityRequest): MaybePromise<AdmissionDecision>;
+}
+export interface ExecutionModelDecisionPort {
+    decide(request: ExecuteCapabilityRequest, context?: {
+        executionRef: string;
+        inputFingerprint: string;
+    }): Promise<{
+        decision: "ALLOW" | "DENY";
+        decisionPath: "fast" | "reason";
+        approvalRequired?: boolean;
+        reason?: string;
+    }>;
+}
+export interface ExecutionApprovalPort {
+    validate(input: {
+        approvalRef: string;
+        executionRef: string;
+        callerRef: string;
+        taskId?: string;
+        capability: string;
+        inputFingerprint: string;
+        request: ExecuteCapabilityRequest;
+        projectRoot?: string;
+        precondition?: ExecutorPrecondition;
+        now: string;
+    }): MaybePromise<boolean>;
+}
+export interface ExecutionIdentityPort {
+    authorize(request: ExecuteCapabilityRequest): MaybePromise<boolean>;
+}
+export type { ExecutionExecutorPort, ExecutorAdmission, ExecutorArtifact, ExecutorArtifactRead, ExecutorDecisionPath, ExecutorInvocation, ExecutorPrecondition, ExecutorReconciliation, ExecutorResult, } from "./executor-port.ts";
+export interface ExecutionRuntimeOptions {
+    databasePath: string;
+    localExecutor: ExecutionExecutorPort;
+    browserExecutor?: ExecutionExecutorPort;
+    policy?: ExecutionPolicyPort;
+    modelDecision?: ExecutionModelDecisionPort;
+    approval?: ExecutionApprovalPort;
+    approvalDraftTtlMs?: number;
+    identity?: ExecutionIdentityPort;
+    maxConcurrent?: number;
+    maxQueued?: number;
+    now?: () => Date;
+    idFactory?: () => string;
+}
+export declare class ExecutionRuntimeError extends Error {
+    readonly code: ExecutionErrorCode;
+    readonly retryable: boolean;
+    constructor(code: ExecutionErrorCode, message: string, retryable?: boolean);
+}
+export declare function executionInputFingerprint(input: unknown): string;
+export declare function createExecutionRuntime(options: ExecutionRuntimeOptions): Promise<Readonly<{
+    executeCapability: (input: unknown) => Promise<ExecutionRecord>;
+    lookupExecutionIntent: (input: unknown) => ExecutionRecord;
+    listExecutionObserverSignals: (limit?: number) => {
+        signalRef: string;
+        kind: "RECOVERY_RESUME" | "UNKNOWN_REALITY";
+        executionRef: string;
+        taskId: string;
+        nodeId: string;
+        runNo?: number;
+        roleRef?: string;
+        workerRef: string;
+        status: ExecutionRecord["status"];
+        sideEffectState: ExecutionRecord["sideEffectState"];
+        errorCode?: string;
+        createdAt: string;
+    }[];
+    acknowledgeExecutionObserverSignal: (signalRef: string) => {
+        acknowledged: boolean;
+    };
+    getExecution: (input: unknown) => ExecutionRecord;
+    getExecutionForCaller: (input: {
+        executionRef: unknown;
+        callerRef: string;
+    }) => ExecutionRecord;
+    readExecutionOutput: (input: unknown) => Promise<ReadExecutionOutputResponse>;
+    readExecutionOutputForCaller: (input: unknown, callerRef: string) => Promise<ReadExecutionOutputResponse>;
+    cancelExecution: (input: unknown) => Promise<ExecutionRecord>;
+    requestExecutionApproval: (value: unknown) => import("@tomflow/proflow-execution-contracts").ExecutionApprovalRecord;
+    decideExecutionApproval: (value: unknown) => import("@tomflow/proflow-execution-contracts").ExecutionApprovalRecord;
+    revokeExecutionApproval: (value: unknown) => import("@tomflow/proflow-execution-contracts").ExecutionApprovalRecord;
+    getExecutionApproval: (approvalRef: string) => import("@tomflow/proflow-execution-contracts").ExecutionApprovalRecord;
+    listExecutionApprovals: (filter?: {
+        executionRef?: string;
+        status?: string;
+    }) => import("@tomflow/proflow-execution-contracts").ExecutionApprovalRecord[];
+    registerArtifact: (input: {
+        record: unknown;
+        path: string;
+    }) => ExecutionArtifactRecord;
+    getArtifactRecord: (input: {
+        artifactRef: string;
+        callerRef: string;
+        taskId?: string;
+        nodeId?: string;
+        roleRef?: string;
+        workerRef?: string;
+    }) => ExecutionArtifactRecord;
+    getArtifactSummary: () => {
+        totalArtifacts: number;
+        byKind: Record<string, number>;
+        latestCreatedAt: string | null;
+        pendingObserverSignals: number;
+    };
+    recoverIncomplete: () => Promise<void>;
+    databasePath: string;
+    logPath: string;
+    close(): void;
+}>>;
+export { createExecutionApprovalOwner, ExecutionApprovalOwnerError, } from "./approval-owner.ts";