@tomflow/proflow-execution-runtime 0.1.0

package/dist/src/approval-owner.js

@@ -0,0 +1,278 @@
+import { createHash, randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { EXECUTION_CONTRACT_VERSION, parseDecideExecutionApproval, parseExecutionApprovalRecord, parseExecutionArtifactRecord, parseRequestExecutionApproval, parseRevokeExecutionApproval, } from "@tomflow/proflow-execution-contracts";
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]));
+}
+function sha(value) {
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(canonical(value)))
+        .digest("hex")}`;
+}
+export class ExecutionApprovalOwnerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ExecutionApprovalOwnerError";
+        this.code = code;
+    }
+}
+export function createExecutionApprovalOwner(input) {
+    const database = new DatabaseSync(input.databasePath);
+    database.exec("PRAGMA foreign_keys=ON; PRAGMA journal_mode=WAL; PRAGMA busy_timeout=2500;");
+    database.exec(`
+		CREATE TABLE IF NOT EXISTS execution_approvals (
+			approval_ref TEXT PRIMARY KEY,
+			execution_ref TEXT NOT NULL,
+			record_json TEXT NOT NULL,
+			created_at TEXT NOT NULL,
+			FOREIGN KEY(execution_ref) REFERENCES executions(execution_ref)
+		);
+		CREATE INDEX IF NOT EXISTS execution_approvals_execution_idx
+			ON execution_approvals(execution_ref, created_at);
+	`);
+    const now = input.now ?? (() => new Date());
+    const idFactory = input.idFactory ?? randomUUID;
+    const getRow = (approvalRef) => database
+        .prepare("SELECT * FROM execution_approvals WHERE approval_ref=?")
+        .get(approvalRef);
+    const getExecutionRow = (executionRef) => database
+        .prepare("SELECT * FROM executions WHERE execution_ref=?")
+        .get(executionRef);
+    const patchArtifactBinding = (request) => {
+        if (request.capability !== "patch.apply")
+            return undefined;
+        const row = database
+            .prepare("SELECT record_json FROM artifact_registry WHERE artifact_ref=?")
+            .get(request.input.artifactRef);
+        if (!row)
+            throw new ExecutionApprovalOwnerError("ARTIFACT_NOT_FOUND", "patch approval requires the durable patch Artifact");
+        const artifact = parseExecutionArtifactRecord(JSON.parse(String(row.record_json)));
+        if (artifact.kind !== "patch-proposal")
+            throw new ExecutionApprovalOwnerError("ARTIFACT_KIND_INVALID", "patch approval requires a patch-proposal Artifact");
+        return {
+            artifactRef: artifact.artifactRef,
+            hash: artifact.hash,
+            ownerCallerRef: artifact.ownerCallerRef,
+            taskId: artifact.taskId,
+            nodeId: artifact.nodeId,
+            roleRef: artifact.roleRef,
+            workerRef: artifact.workerRef,
+            baseHash: artifact.metadata?.baseHash,
+            baseRef: artifact.metadata?.baseRef,
+        };
+    };
+    const approvalEffectFingerprint = (request, inputFingerprint) => sha({
+        capability: request.capability,
+        inputFingerprint,
+        projectRoot: request.projectRoot,
+        patchArtifact: patchArtifactBinding(request),
+    });
+    const fromRow = (row) => parseExecutionApprovalRecord(JSON.parse(String(row.record_json)));
+    const save = (record) => {
+        database
+            .prepare("UPDATE execution_approvals SET record_json=? WHERE approval_ref=?")
+            .run(JSON.stringify(record), record.approvalRef);
+    };
+    const listApprovals = (filter = {}) => {
+        const rows = filter.executionRef
+            ? database
+                .prepare("SELECT * FROM execution_approvals WHERE execution_ref=? ORDER BY created_at, approval_ref")
+                .all(filter.executionRef)
+            : database
+                .prepare("SELECT * FROM execution_approvals ORDER BY created_at, approval_ref")
+                .all();
+        return rows
+            .map((row) => get(String(row.approval_ref)))
+            .filter((record) => !filter.status || record.status === filter.status);
+    };
+    const get = (approvalRef) => {
+        const row = getRow(approvalRef);
+        if (!row)
+            throw new ExecutionApprovalOwnerError("APPROVAL_NOT_FOUND", "approval was not found");
+        let record = fromRow(row);
+        if (record.status === "APPROVED" &&
+            Date.parse(record.expiresAt) <= now().getTime()) {
+            record = parseExecutionApprovalRecord({
+                ...record,
+                status: "EXPIRED",
+                version: record.version + 1,
+            });
+            save(record);
+        }
+        return record;
+    };
+    const ensurePendingApproval = (value) => {
+        const executionRow = getExecutionRow(value.executionRef);
+        if (!executionRow)
+            throw new ExecutionApprovalOwnerError("EXECUTION_NOT_FOUND", "execution was not found");
+        const inputFingerprint = String(executionRow.input_fingerprint);
+        const existing = database
+            .prepare("SELECT * FROM execution_approvals WHERE execution_ref=? ORDER BY created_at DESC")
+            .all(value.executionRef)
+            .map(fromRow)
+            .find((record) => record.status === "PENDING" &&
+            record.inputFingerprint === inputFingerprint &&
+            Date.parse(record.expiresAt) > now().getTime());
+        if (existing)
+            return existing;
+        return requestApproval({
+            contract: "execution.approval",
+            contractVersion: EXECUTION_CONTRACT_VERSION,
+            executionRef: value.executionRef,
+            actorRef: value.actorRef,
+            expiresAt: value.expiresAt,
+            ...(value.precondition
+                ? { preconditionFingerprint: sha(value.precondition) }
+                : {}),
+        });
+    };
+    const requestApproval = (value) => {
+        const request = parseRequestExecutionApproval(value);
+        if (Date.parse(request.expiresAt) <= now().getTime())
+            throw new ExecutionApprovalOwnerError("APPROVAL_EXPIRY_INVALID", "approval expiry must be in the future");
+        const executionRow = getExecutionRow(request.executionRef);
+        if (!executionRow)
+            throw new ExecutionApprovalOwnerError("EXECUTION_NOT_FOUND", "execution was not found");
+        const executionRequest = JSON.parse(String(executionRow.request_json));
+        const executionRecord = JSON.parse(String(executionRow.record_json));
+        const inputFingerprint = String(executionRow.input_fingerprint);
+        const stamp = now().toISOString();
+        const record = parseExecutionApprovalRecord({
+            contract: "execution.approval",
+            contractVersion: EXECUTION_CONTRACT_VERSION,
+            approvalRef: `approval:${idFactory()}`,
+            executionRef: request.executionRef,
+            callerRef: executionRequest.callerRef,
+            ...(executionRequest.taskId ? { taskId: executionRequest.taskId } : {}),
+            ...(executionRequest.nodeId ? { nodeId: executionRequest.nodeId } : {}),
+            ...(executionRequest.roleRef
+                ? { roleRef: executionRequest.roleRef }
+                : {}),
+            ...(executionRequest.workerRef
+                ? { workerRef: executionRequest.workerRef }
+                : {}),
+            capability: executionRequest.capability,
+            inputFingerprint,
+            effectFingerprint: approvalEffectFingerprint(executionRequest, inputFingerprint),
+            scopeFingerprint: sha({
+                callerRef: executionRequest.callerRef,
+                taskId: executionRequest.taskId,
+                nodeId: executionRequest.nodeId,
+                roleRef: executionRequest.roleRef,
+                workerRef: executionRequest.workerRef,
+                projectRoot: executionRequest.projectRoot,
+            }),
+            ...(request.preconditionFingerprint
+                ? { preconditionFingerprint: request.preconditionFingerprint }
+                : {}),
+            status: "PENDING",
+            requestedByActorRef: request.actorRef,
+            requestedAt: stamp,
+            expiresAt: request.expiresAt,
+            version: 1,
+        });
+        database
+            .prepare("INSERT INTO execution_approvals VALUES (?, ?, ?, ?)")
+            .run(record.approvalRef, record.executionRef, JSON.stringify(record), stamp);
+        void executionRecord;
+        return record;
+    };
+    const decideApproval = (value) => {
+        const request = parseDecideExecutionApproval(value);
+        const current = get(request.approvalRef);
+        if (current.version !== request.expectedVersion)
+            throw new ExecutionApprovalOwnerError("APPROVAL_VERSION_CONFLICT", "approval version changed");
+        if (current.status !== "PENDING")
+            throw new ExecutionApprovalOwnerError("APPROVAL_STATE_INVALID", "only PENDING approval may be decided");
+        const stamp = now().toISOString();
+        const next = parseExecutionApprovalRecord({
+            ...current,
+            status: request.decision === "ALLOW" ? "APPROVED" : "DENIED",
+            decidedByActorRef: request.actorRef,
+            ...(request.reason ? { reason: request.reason } : {}),
+            decidedAt: stamp,
+            version: current.version + 1,
+        });
+        save(next);
+        return next;
+    };
+    const revokeApproval = (value) => {
+        const request = parseRevokeExecutionApproval(value);
+        const current = get(request.approvalRef);
+        if (current.version !== request.expectedVersion)
+            throw new ExecutionApprovalOwnerError("APPROVAL_VERSION_CONFLICT", "approval version changed");
+        if (current.status !== "PENDING" && current.status !== "APPROVED")
+            throw new ExecutionApprovalOwnerError("APPROVAL_STATE_INVALID", "approval cannot be revoked from current state");
+        const next = parseExecutionApprovalRecord({
+            ...current,
+            status: "REVOKED",
+            decidedByActorRef: request.actorRef,
+            reason: request.reason,
+            revokedAt: now().toISOString(),
+            version: current.version + 1,
+        });
+        save(next);
+        return next;
+    };
+    const validate = (value) => {
+        const record = get(value.approvalRef);
+        if (record.status !== "APPROVED")
+            return false;
+        if (record.executionRef !== value.executionRef ||
+            record.callerRef !== value.callerRef ||
+            record.capability !== value.capability ||
+            record.inputFingerprint !== value.inputFingerprint)
+            return false;
+        if ((record.taskId ?? undefined) !== (value.taskId ?? undefined))
+            return false;
+        const effectFingerprint = approvalEffectFingerprint(value.request, value.inputFingerprint);
+        if (record.effectFingerprint !== effectFingerprint)
+            return false;
+        const scopeFingerprint = sha({
+            callerRef: value.request.callerRef,
+            taskId: value.request.taskId,
+            nodeId: value.request.nodeId,
+            roleRef: value.request.roleRef,
+            workerRef: value.request.workerRef,
+            projectRoot: value.request.projectRoot,
+        });
+        if (record.scopeFingerprint !== scopeFingerprint)
+            return false;
+        if (value.precondition && record.preconditionFingerprint) {
+            if (record.preconditionFingerprint !== sha(value.precondition))
+                return false;
+        }
+        return Date.parse(record.expiresAt) > Date.parse(value.now);
+    };
+    const consume = (approvalRef) => {
+        const current = get(approvalRef);
+        if (current.status !== "APPROVED")
+            throw new ExecutionApprovalOwnerError("APPROVAL_STATE_INVALID", "only APPROVED approval may be consumed");
+        const next = parseExecutionApprovalRecord({
+            ...current,
+            status: "CONSUMED",
+            consumedAt: now().toISOString(),
+            version: current.version + 1,
+        });
+        save(next);
+        return next;
+    };
+    return Object.freeze({
+        requestApproval,
+        ensurePendingApproval,
+        decideApproval,
+        revokeApproval,
+        getApproval: get,
+        listApprovals,
+        validate,
+        consume,
+        close: () => database.close(),
+    });
+}

package/dist/src/browser-vision-client.d.ts

@@ -0,0 +1,15 @@
+import { type BrowserVisionPort } from "@tomflow/proflow-execution-browser-extension";
+/**
+ * Typed Browser Vision inference client. It talks to the same Model Runtime
+ * `infer` boundary as the command-risk decision client, but for the
+ * spec-ized `browser.page-vision.v1` REASON-only image observation. A Vision
+ * call returns an OBSERVED interpretation or a typed DEFERRED fail-safe; it
+ * never fabricates page state and never decides Task/Execution/Approval truth.
+ */
+export declare function createExecutionBrowserVisionClient(config: {
+    endpoint: string;
+    timeoutMs?: number;
+    credential?: string;
+}): Readonly<{
+    port: BrowserVisionPort;
+}>;

package/dist/src/browser-vision-client.js

@@ -0,0 +1,79 @@
+import { deferVisionObservation, } from "@tomflow/proflow-execution-browser-extension";
+import { browserPageVisionObservationSchema, inferenceResultSchema, } from "@tomflow/proflow-model-contracts";
+const loopbackHosts = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const browserPageVisionSpecRef = "browser.page-vision.v1";
+/**
+ * Typed Browser Vision inference client. It talks to the same Model Runtime
+ * `infer` boundary as the command-risk decision client, but for the
+ * spec-ized `browser.page-vision.v1` REASON-only image observation. A Vision
+ * call returns an OBSERVED interpretation or a typed DEFERRED fail-safe; it
+ * never fabricates page state and never decides Task/Execution/Approval truth.
+ */
+export function createExecutionBrowserVisionClient(config) {
+    const endpoint = new URL(config.endpoint);
+    if (endpoint.protocol !== "http:" ||
+        !loopbackHosts.has(endpoint.hostname) ||
+        endpoint.pathname !== "/" ||
+        endpoint.search ||
+        endpoint.hash)
+        throw new TypeError("modelDecision.endpoint must be loopback HTTP root");
+    if (config.credential && config.credential.length < 32)
+        throw new TypeError("modelDecision credential must contain at least 32 characters");
+    const timeoutMs = config.timeoutMs ?? 12_000;
+    const authorizationHeaders = config.credential
+        ? { authorization: `Bearer ${config.credential}` }
+        : {};
+    const port = {
+        async inspect({ image, observationContext }) {
+            try {
+                const response = await fetch(`${endpoint.origin}/infer`, {
+                    method: "POST",
+                    headers: {
+                        ...authorizationHeaders,
+                        "content-type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        contractVersion: "1.0.0",
+                        specRef: browserPageVisionSpecRef,
+                        mode: "reason",
+                        priority: "business",
+                        trace: { callerRef: "execution-runtime:browser-vision" },
+                        payload: {
+                            targetRef: observationContext.targetRef,
+                            pageState: observationContext.pageState,
+                            activityKind: observationContext.activityKind,
+                            observedAt: observationContext.observedAt,
+                        },
+                        images: [{ mimeType: image.mimeType, data: image.base64 }],
+                        timeoutMs,
+                    }),
+                    signal: AbortSignal.timeout(timeoutMs + 1_000),
+                });
+                if (!response.ok)
+                    throw new Error(`MODEL_INFER_HTTP_${response.status}`);
+                const result = inferenceResultSchema.parse(await response.json());
+                if (result.specRef !== browserPageVisionSpecRef ||
+                    result.requestedMode !== "reason")
+                    throw new Error("MODEL_INFERENCE_PROTOCOL_MISMATCH");
+                if (result.status !== "SUCCEEDED")
+                    throw new Error(result.error?.code ?? result.status);
+                const data = browserPageVisionObservationSchema.parse(result.data);
+                const observation = {
+                    status: "OBSERVED",
+                    observationRef: result.inferenceRef,
+                    pageState: data.pageState,
+                    activityKind: data.activityKind,
+                    confidence: data.confidence,
+                    recommendedNext: data.recommendedNext,
+                    reasonCode: data.reasonCode,
+                    rationale: data.rationale,
+                };
+                return Object.freeze(observation);
+            }
+            catch (error) {
+                return deferVisionObservation("VISION_INFERENCE_FAILED", error instanceof Error ? error.message : "vision inference failed");
+            }
+        },
+    };
+    return Object.freeze({ port });
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createFormalExecutionRuntimeLifecycle } from "./formal-process.js";
+import { loadExecutionRuntimeProcessConfig } from "./service.js";
+function installSelf() {
+    const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+    const result = spawnSync(executable, [
+        "--yes",
+        "@tomflow/proflow-platform-cli",
+        "install",
+        "@tomflow/proflow-execution-runtime",
+    ], { cwd: process.cwd(), env: process.env, stdio: "inherit" });
+    if (result.error)
+        throw result.error;
+    process.exit(result.status ?? 1);
+}
+async function main() {
+    const [command, configPath] = process.argv.slice(2);
+    if (command === "--help" || command === "-h") {
+        process.stdout.write("Usage: proflow-execution-runtime install | start /absolute/config.json\\n");
+        process.exit(0);
+    }
+    if (command === "install") {
+        if (configPath)
+            throw new Error("Usage: proflow-execution-runtime install");
+        installSelf();
+    }
+    if (command !== "start" || !configPath)
+        throw new Error("Usage: proflow-execution-runtime start /absolute/config.json");
+    const config = await loadExecutionRuntimeProcessConfig(configPath);
+    const service = createFormalExecutionRuntimeLifecycle({
+        config,
+        log: (entry) => process.stderr.write(`${JSON.stringify(entry)}\n`),
+    });
+    const address = await service.start();
+    process.stdout.write(`${JSON.stringify({ status: "RUNNING", ...address })}\n`);
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void service.stop().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await new Promise(() => { });
+}
+if (import.meta.main) {
+    await main();
+}

package/dist/src/executor-port.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility re-export. The structural Executor Port contract is owned by
+ * execution-contracts so concrete executors do not depend back on runtime.
+ */
+export type { ExecutionExecutorPort, ExecutorAdmission, ExecutorApprovalState, ExecutorArtifact, ExecutorArtifactRead, ExecutorDecisionPath, ExecutorInvocation, ExecutorPrecondition, ExecutorReconciliation, ExecutorResult, } from "@tomflow/proflow-execution-contracts";

package/dist/src/executor-port.js

@@ -0,0 +1 @@
+export {};

package/dist/src/executors/local-adapter.d.ts

@@ -0,0 +1,4 @@
+import { createLocalExecutor, type LocalExecutorOptions } from "@tomflow/proflow-execution-local";
+import type { ExecutionExecutorPort } from "../executor-port.ts";
+export declare function adaptLocalExecutor(executor: Awaited<ReturnType<typeof createLocalExecutor>>): ExecutionExecutorPort;
+export declare function createLocalExecutorPort(options: LocalExecutorOptions): Promise<ExecutionExecutorPort>;

package/dist/src/executors/local-adapter.js

@@ -0,0 +1,55 @@
+import { localCapabilityIds, } from "@tomflow/proflow-execution-contracts";
+import { createLocalExecutor, } from "@tomflow/proflow-execution-local";
+const localCapabilitySet = new Set(localCapabilityIds);
+/**
+ * Adapts the concrete `execution-local` executor library to the owner-neutral
+ * Runtime Executor Port. `execution-local` keeps its own concrete public
+ * types; this boundary is the only place that translates them.
+ */
+function toLocalPrecondition(precondition) {
+    switch (precondition.kind) {
+        case "file.write":
+        case "patch.apply":
+        case "git.commit":
+        case "install-dependency":
+        case "process.start":
+        case "process.stop":
+            return precondition;
+        case "opaque": {
+            if (!localCapabilitySet.has(precondition.capability))
+                throw new TypeError("a non-local capability precondition reached the local adapter");
+            return {
+                kind: "opaque",
+                capability: precondition.capability,
+            };
+        }
+        case "browser":
+            throw new TypeError("a browser precondition cannot be routed to the local executor");
+    }
+}
+export function adaptLocalExecutor(executor) {
+    return {
+        bindPatchArtifactResolver(resolver) {
+            executor.bindPatchArtifactResolver(resolver);
+        },
+        async execute(invocation) {
+            const { onEffectStarted, ...rest } = invocation;
+            return executor.execute({
+                ...rest,
+                ...(onEffectStarted
+                    ? {
+                        onEffectStarted: (precondition) => onEffectStarted(precondition),
+                    }
+                    : {}),
+            });
+        },
+        async reconcile(request, precondition) {
+            return executor.reconcile(request, toLocalPrecondition(precondition));
+        },
+        observePrecondition: executor.observePrecondition,
+        readArtifact: executor.readArtifact,
+    };
+}
+export async function createLocalExecutorPort(options) {
+    return adaptLocalExecutor(await createLocalExecutor(options));
+}

package/dist/src/formal-process.d.ts

@@ -0,0 +1,20 @@
+import { type ExecutionRuntimeProcessConfig } from "./service.ts";
+export declare function createFormalExecutionRuntimeLifecycle(input: {
+    config: ExecutionRuntimeProcessConfig;
+    log?: (entry: Record<string, unknown>) => void;
+}): Readonly<{
+    status: () => import("./service.ts").ExecutionRuntimeProcessStatus | {
+        readiness: "NOT_READY";
+    };
+    start(): Promise<{
+        host: string;
+        port: number;
+        browserBridgeEndpoint: string;
+    }>;
+    stop(): Promise<void>;
+    restart(): Promise<{
+        host: string;
+        port: number;
+        browserBridgeEndpoint: string;
+    }>;
+}>;