jev-devtools 0.1.3 → 0.3.0

package/lib/flow/index.js

@@ -0,0 +1,588 @@
+import { randomUUID } from "node:crypto";
+const owners = new WeakMap();
+function freezeAst(ast, depth = 0) {
+    if (depth > 80)
+        throw new Error("Expression nesting exceeds 80");
+    if (Object.isFrozen(ast))
+        return;
+    if (ast.op === "get")
+        freezeAst(ast.from, depth + 1);
+    if ("args" in ast) {
+        if (ast.args.length > 256)
+            throw new Error("Too many condition operands");
+        for (const child of ast.args)
+            freezeAst(child, depth + 1);
+        Object.freeze(ast.args);
+    }
+    Object.freeze(ast);
+}
+/** Inspectable expression, not an application callback. Use get() for input fields. */
+export class FlowExpression {
+    ast;
+    constructor(ast, owner) {
+        this.ast = ast;
+        if (owner)
+            owners.set(this, owner);
+        freezeAst(ast);
+        Object.freeze(this);
+    }
+    get(key) {
+        return expression({ op: "get", from: this.ast, key: String(key) }, [this]);
+    }
+    eq(value) {
+        return operation("eq", [this, value]);
+    }
+    lt(value) {
+        return operation("lt", [this, value]);
+    }
+    gte(value) {
+        return operation("gte", [this, value]);
+    }
+}
+function expression(ast, values) {
+    const tokens = new Set(values
+        .filter((v) => v instanceof FlowExpression)
+        .map((v) => owners.get(v))
+        .filter(Boolean));
+    if (tokens.size > 1)
+        throw new Error("References belong to different flows");
+    return new FlowExpression(ast, tokens.values().next().value);
+}
+function operation(op, args) {
+    return expression({
+        op,
+        args: args.map((v) => v instanceof FlowExpression ? v.ast : { op: "literal", value: v }),
+    }, args);
+}
+export const all = (...conditions) => operation("all", conditions);
+export const any = (...conditions) => operation("any", conditions);
+export const not = (condition) => operation("not", [condition]);
+const plain = (v) => !!v &&
+    typeof v === "object" &&
+    (Object.getPrototypeOf(v) === Object.prototype ||
+        Object.getPrototypeOf(v) === null);
+function mapValue(value, ref, seen = new Set(), depth = 0) {
+    if (depth > 40)
+        throw new Error("Flow value nesting exceeds 40");
+    if (value instanceof FlowExpression)
+        return ref(value);
+    if (typeof value === "function")
+        throw new Error("Flow values cannot contain callbacks");
+    if (!Array.isArray(value) && !plain(value))
+        return value; // Preserve SDK assets.
+    if (seen.has(value))
+        throw new Error("Cyclic flow value");
+    seen.add(value);
+    const result = Array.isArray(value)
+        ? value.map((v) => mapValue(v, ref, seen, depth + 1))
+        : Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            k,
+            mapValue(v, ref, seen, depth + 1),
+        ]));
+    seen.delete(value);
+    return result;
+}
+const inspectAst = (ast, ref) => {
+    if (ast.op === "ref")
+        ref(ast.id);
+    else if (ast.op === "get")
+        inspectAst(ast.from, ref);
+    else if ("args" in ast)
+        ast.args.forEach((a) => inspectAst(a, ref));
+};
+function describe(ast) {
+    if (ast.op === "input")
+        return "input";
+    if (ast.op === "ref")
+        return ast.id;
+    if (ast.op === "get")
+        return `${describe(ast.from)}.${ast.key}`;
+    if (ast.op === "literal")
+        return "[literal]";
+    return `${ast.op}(${ast.args.map(describe).join(", ")})`;
+}
+function conditionRule(ast, requests) {
+    let remaining = 128;
+    const visit = (node) => {
+        if (--remaining < 0)
+            return { op: "literal", value: "[rule truncated]" };
+        if (node.op === "input" || node.op === "ref" || node.op === "get") {
+            const path = [];
+            let base = node;
+            while (base.op === "get") {
+                path.unshift(base.key);
+                base = base.from;
+            }
+            const answer = base.op === "ref" && requests.has(base.id) && path[0] === "answers";
+            const probability = answer && path.length === 3 && path[2] === "noul";
+            const root = base.op === "input"
+                ? "input"
+                : base.op === "ref"
+                    ? base.id
+                    : describe(base);
+            const fields = probability
+                ? path.slice(1, -1)
+                : answer
+                    ? path.slice(1)
+                    : path;
+            const label = root +
+                fields
+                    .map((key) => /^[a-zA-Z_$][\w$]*$/.test(key)
+                    ? `.${key}`
+                    : `[${JSON.stringify(key)}]`)
+                    .join("");
+            return {
+                op: "reference",
+                label,
+                probability,
+                name: answer
+                    ? path.length === 3 && ["noul", "choice", "score"].includes(path[2])
+                        ? path[1]
+                        : path.slice(1).join(" ")
+                    : (path.at(-1) ?? "Input"),
+                ...(base.op === "ref" && requests.has(base.id)
+                    ? { stepId: base.id, path }
+                    : {}),
+            };
+        }
+        if (node.op === "literal")
+            return {
+                op: "literal",
+                value: node.value === null ||
+                    typeof node.value === "string" ||
+                    typeof node.value === "boolean" ||
+                    (typeof node.value === "number" && Number.isFinite(node.value))
+                    ? node.value
+                    : "[value unavailable]",
+            };
+        const args = [];
+        for (const arg of node.args) {
+            args.push(visit(arg));
+            if (remaining < 0)
+                break;
+        }
+        return { op: node.op, args };
+    };
+    return visit(ast);
+}
+function evaluate(ast, input, values) {
+    if (ast.op === "input")
+        return input;
+    if (ast.op === "literal")
+        return ast.value;
+    if (ast.op === "ref") {
+        if (!values.has(ast.id))
+            throw new Error(`Unavailable result: ${ast.id}`);
+        return values.get(ast.id);
+    }
+    if (ast.op === "get") {
+        const obj = evaluate(ast.from, input, values);
+        if (obj === null ||
+            typeof obj !== "object" ||
+            !Object.hasOwn(obj, ast.key) ||
+            obj[ast.key] === undefined)
+            throw new Error(`Missing value: ${describe(ast)}`);
+        return obj[ast.key];
+    }
+    // Evaluate every operand: a missing value must never hide behind short-circuiting.
+    const args = ast.args.map((a) => evaluate(a, input, values));
+    if (ast.op === "all" || ast.op === "any" || ast.op === "not") {
+        if (args.some((v) => typeof v !== "boolean"))
+            throw new Error("Boolean condition required");
+        return ast.op === "not"
+            ? !args[0]
+            : ast.op === "all"
+                ? args.every(Boolean)
+                : args.some(Boolean);
+    }
+    const [a, b] = args;
+    if (ast.op === "eq") {
+        if (a === undefined ||
+            b === undefined ||
+            (a !== null && !["string", "number", "boolean"].includes(typeof a)) ||
+            (b !== null && !["string", "number", "boolean"].includes(typeof b)) ||
+            typeof a !== typeof b ||
+            (typeof a === "number" && (!Number.isFinite(a) || !Number.isFinite(b))))
+            throw new Error("eq requires matching scalar values");
+        return a === b;
+    }
+    if (typeof a !== "number" ||
+        typeof b !== "number" ||
+        !Number.isFinite(a) ||
+        !Number.isFinite(b))
+        throw new Error("Numeric comparison requires finite numbers");
+    return ast.op === "lt" ? a < b : a >= b;
+}
+export function defineJevFlow(name, build) {
+    const owner = {}, ids = new Set(), nodes = [];
+    const input = new FlowExpression({ op: "input" }, owner);
+    let building = true;
+    let activeBlock;
+    function block(callback, available, path, previous = [], depth = 0, requireOutcome = false) {
+        if (depth > 16)
+            throw new Error("Flow nesting exceeds 16");
+        const token = {};
+        const result = { nodes: [] };
+        let terminal = false;
+        const validate = (value) => mapValue(value, (expr) => {
+            if (owners.get(expr) !== owner)
+                throw new Error("Foreign or unowned flow reference");
+            inspectAst(expr.ast, (id) => {
+                if (!available.has(id))
+                    throw new Error(`Unavailable reference: ${id}`);
+            });
+            return expr;
+        });
+        function add(id, kind, value, display) {
+            if (!building)
+                throw new Error("Flow definition is closed");
+            if (activeBlock !== token)
+                throw new Error("Use the current branch or lane builder for steps");
+            if (terminal)
+                throw new Error("No steps allowed after a terminal output or branch");
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id) || ids.has(id))
+                throw new Error(`Invalid or duplicate step ID: ${id}`);
+            if (ids.size >= 256)
+                throw new Error("Flows support at most 256 steps");
+            const copy = {};
+            if (display !== undefined) {
+                if (!display || typeof display !== "object" || Array.isArray(display))
+                    throw new Error("Step display metadata must be an object");
+                for (const [key, max] of [
+                    ["title", 120],
+                    ["description", 600],
+                ]) {
+                    const text = display[key];
+                    if (text === undefined)
+                        continue;
+                    if (typeof text !== "string" || !text.trim() || text.length > max)
+                        throw new Error(`${key} must be a non-empty string of at most ${max} characters`);
+                    copy[key] = text.trim();
+                }
+            }
+            ids.add(id);
+            validate(value);
+            const dependencies = new Set(previous);
+            mapValue(value, (expr) => {
+                inspectAst(expr.ast, (r) => dependencies.add(r));
+                return expr;
+            });
+            nodes.push({
+                id,
+                kind,
+                dependencies: [...dependencies],
+                path: [...path],
+                ...copy,
+            });
+            previous = [id];
+            available.add(id);
+            const step = { id, kind };
+            result.nodes.push(step);
+            return step;
+        }
+        const builder = {
+            input,
+            jev(id, request, display) {
+                const frozen = mapValue(request, (expr) => expr);
+                const step = add(id, "jev", frozen, display);
+                step.request = frozen;
+                return {
+                    answer(question) {
+                        if (!Object.hasOwn(frozen.questions, question))
+                            throw new Error(`Unknown question: ${question}`);
+                        const type = frozen.questions[question].type;
+                        const fields = type === "noul"
+                            ? ["type", "noul"]
+                            : type === "choice"
+                                ? ["type", "choice", "confidence", "probabilities"]
+                                : type === "score"
+                                    ? ["type", "score", "confidence", "probabilities", "legend"]
+                                    : ["type", "box", "confidence"];
+                        return Object.fromEntries(fields.map((field) => [
+                            field,
+                            new FlowExpression({
+                                op: "get",
+                                from: {
+                                    op: "get",
+                                    from: {
+                                        op: "get",
+                                        from: { op: "ref", id },
+                                        key: "answers",
+                                    },
+                                    key: question,
+                                },
+                                key: field,
+                            }, owner),
+                        ]));
+                    },
+                };
+            },
+            branch(id, paths, display) {
+                const step = add(id, "branch", paths.when, display);
+                step.when = paths.when;
+                if (!(paths.when instanceof FlowExpression))
+                    throw new Error("branch requires a condition expression");
+                const node = nodes.find((n) => n.id === id);
+                node.condition = describe(paths.when.ast);
+                node.conditionRule = conditionRule(paths.when.ast, new Set(nodes.filter((n) => n.kind === "jev").map((n) => n.id)));
+                step.then = block(paths.then, new Set(available), [...path, `${id}:then`], [id], depth + 1, true);
+                step.else = block(paths.else, new Set(available), [...path, `${id}:else`], [id], depth + 1, true);
+                terminal = true;
+                return new FlowExpression({ op: "ref", id }, owner);
+            },
+            parallel(id, lanes, display) {
+                const prior = [...previous], base = new Set(available);
+                const step = add(id, "parallel", undefined, display);
+                step.lanes = {};
+                if (!Object.keys(lanes).length)
+                    throw new Error("parallel requires at least one lane");
+                const refs = {};
+                const tails = [];
+                for (const [key, callback] of Object.entries(lanes)) {
+                    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(key))
+                        throw new Error("Invalid lane name");
+                    const lane = block(callback, new Set(base), [...path, `${id}:${key}`], prior, depth + 1);
+                    step.lanes[key] = lane;
+                    tails.push(lane.nodes.at(-1)?.id ?? prior.at(-1) ?? "");
+                    refs[key] = new FlowExpression({ op: "get", from: { op: "ref", id }, key }, owner);
+                }
+                nodes.find((n) => n.id === id).dependencies = tails.filter(Boolean);
+                nodes.find((n) => n.id === id).lanes = Object.keys(lanes);
+                return refs;
+            },
+            output(outcome, value, display) {
+                const step = add(outcome, "output", value, display);
+                step.outcome = outcome;
+                step.value = mapValue(value, (e) => e);
+                terminal = true;
+                return new FlowExpression({ op: "ref", id: outcome }, owner);
+            },
+        };
+        const parentBlock = activeBlock;
+        activeBlock = token;
+        let returned;
+        try {
+            returned = callback(builder);
+        }
+        finally {
+            activeBlock = parentBlock;
+        }
+        if (!(returned instanceof FlowExpression))
+            throw new Error("Flow callbacks must return an expression, output, or branch");
+        if (requireOutcome && !terminal)
+            throw new Error("Branch paths must end with output or branch");
+        if (terminal &&
+            (returned.ast.op !== "ref" || returned.ast.id !== result.nodes.at(-1).id))
+            throw new Error("Return the terminal output or branch");
+        validate(returned);
+        result.result = returned;
+        return result;
+    }
+    if (!name.trim() || name.length > 100)
+        throw new Error("Invalid flow name");
+    let program;
+    try {
+        program = block(build, new Set(), [], [], 0, true);
+    }
+    finally {
+        building = false;
+    }
+    if (!["branch", "output"].includes(program.nodes.at(-1)?.kind ?? ""))
+        throw new Error("Flow must end with output or branch");
+    const definition = {
+        version: 1,
+        id: randomUUID(),
+        name,
+        nodes,
+    };
+    const definitionView = structuredClone(definition);
+    const freezeRule = (rule) => {
+        if (!rule || typeof rule !== "object")
+            return;
+        for (const value of Object.values(rule))
+            freezeRule(value);
+        Object.freeze(rule);
+    };
+    for (const node of definitionView.nodes) {
+        Object.freeze(node.dependencies);
+        Object.freeze(node.path);
+        if (node.lanes)
+            Object.freeze(node.lanes);
+        freezeRule(node.conditionRule);
+        Object.freeze(node);
+    }
+    Object.freeze(definitionView.nodes);
+    Object.freeze(definitionView);
+    return {
+        definition: definitionView,
+        async run(data, options) {
+            const controller = new AbortController();
+            const cancel = () => controller.abort(options.signal?.reason);
+            if (options.signal?.aborted)
+                cancel();
+            else
+                options.signal?.addEventListener("abort", cancel, { once: true });
+            const run = {
+                version: 1,
+                id: randomUUID(),
+                definitionId: definition.id,
+                name,
+                startedAt: Date.now(),
+                status: "pending",
+                steps: Object.fromEntries(nodes.map((n) => [
+                    n.id,
+                    { id: n.id, executionId: randomUUID(), status: "waiting" },
+                ])),
+            };
+            const started = performance.now(), values = new Map();
+            let observer;
+            try {
+                observer = options.devtools?.startFlow(structuredClone(definition), structuredClone(run));
+            }
+            catch {
+                /* Recording cannot stop execution. */
+            }
+            const emit = () => {
+                try {
+                    if (observer) {
+                        const { value, ...metadata } = run;
+                        observer.update({
+                            ...structuredClone(metadata),
+                            ...(value !== undefined ? { value } : {}),
+                        });
+                    }
+                }
+                catch {
+                    /* Best effort capture. */
+                }
+            };
+            const abortCheck = () => {
+                if (controller.signal.aborted)
+                    throw new DOMException("Flow cancelled", "AbortError");
+            };
+            const mark = (b, status) => {
+                for (const step of b.nodes) {
+                    if (run.steps[step.id].status === "waiting")
+                        run.steps[step.id].status = status;
+                    if (step.then)
+                        mark(step.then, status);
+                    if (step.else)
+                        mark(step.else, status);
+                    for (const lane of Object.values(step.lanes ?? {}))
+                        mark(lane, status);
+                }
+            };
+            async function execute(b) {
+                for (const step of b.nodes) {
+                    abortCheck();
+                    const state = run.steps[step.id], time = performance.now();
+                    state.status = "running";
+                    state.startedAt = Date.now();
+                    emit();
+                    try {
+                        let value;
+                        if (step.kind === "jev") {
+                            const request = mapValue(step.request, (e) => evaluate(e.ast, data, values));
+                            const call = () => options.client.systemOne(request, {
+                                signal: controller.signal,
+                            });
+                            const link = {
+                                runId: run.id,
+                                stepId: step.id,
+                                executionId: state.executionId,
+                            };
+                            value = await (observer
+                                ? observer.request(link, (id) => {
+                                    state.traceId = id;
+                                    emit();
+                                }, call)
+                                : call());
+                            abortCheck();
+                        }
+                        else if (step.kind === "branch") {
+                            const decision = evaluate(step.when.ast, data, values);
+                            if (typeof decision !== "boolean")
+                                throw new Error("Branch condition did not return a boolean");
+                            state.decision = decision;
+                            mark(decision ? step.else : step.then, "untaken");
+                            emit();
+                            value = await execute(decision ? step.then : step.else);
+                        }
+                        else if (step.kind === "parallel") {
+                            const entries = Object.entries(step.lanes);
+                            let firstError;
+                            let failed = false;
+                            const results = await Promise.allSettled(entries.map(async ([, lane]) => {
+                                try {
+                                    return await execute(lane);
+                                }
+                                catch (e) {
+                                    if (!failed) {
+                                        firstError = e;
+                                        failed = true;
+                                    }
+                                    controller.abort(e);
+                                    throw e;
+                                }
+                            }));
+                            if (failed)
+                                throw firstError;
+                            value = Object.fromEntries(results.map((r, i) => [
+                                entries[i][0],
+                                r.value,
+                            ]));
+                        }
+                        else
+                            value = {
+                                outcome: step.outcome,
+                                value: mapValue(step.value, (e) => evaluate(e.ast, data, values)),
+                            };
+                        values.set(step.id, value);
+                        state.status = "completed";
+                    }
+                    catch (error) {
+                        state.status =
+                            error instanceof Error &&
+                                ["AbortError", "APIUserAbortError"].includes(error.name)
+                                ? "cancelled"
+                                : "error";
+                        state.error = error instanceof Error ? error.name : "FlowError";
+                        throw error;
+                    }
+                    finally {
+                        state.durationMs = performance.now() - time;
+                        emit();
+                    }
+                }
+                return evaluate(b.result.ast, data, values);
+            }
+            try {
+                const result = (await execute(program));
+                abortCheck();
+                if (!result || typeof result.outcome !== "string")
+                    throw new Error("Flow must return a named output");
+                run.status = "success";
+                run.outcome = result.outcome;
+                // Only the recorder snapshots output data; runtime keeps the actual typed value.
+                if (result.value !== undefined)
+                    run.value = result.value;
+                return { runId: run.id, ...result };
+            }
+            catch (error) {
+                run.status =
+                    error instanceof Error &&
+                        ["AbortError", "APIUserAbortError"].includes(error.name)
+                        ? "cancelled"
+                        : "error";
+                run.error = error instanceof Error ? error.name : "FlowError";
+                mark(program, run.status === "cancelled" ? "cancelled" : "blocked");
+                throw error;
+            }
+            finally {
+                run.durationMs = performance.now() - started;
+                emit();
+                options.signal?.removeEventListener("abort", cancel);
+            }
+        },
+    };
+}

package/lib/server/flows.d.ts

@@ -0,0 +1,25 @@
+import type { FlowDefinition, FlowRun, FlowUpdate } from "../src/flow-protocol.js";
+import { type CaptureOptions } from "./recorder.js";
+/** Independent bounded run store. Definitions are retained only while referenced. */
+export declare class FlowRecorder {
+    private options;
+    private runs;
+    private definitions;
+    private sessions;
+    private definitionRevisions;
+    private revisions;
+    private revision;
+    private listeners;
+    constructor(options: CaptureOptions);
+    subscribe(fn: (sessions: Set<string>) => void): () => void;
+    private notify;
+    start(definition: FlowDefinition, run: FlowRun, session: string): void;
+    update(run: FlowRun): void;
+    private remove;
+    private prune;
+    clear(session: string): void;
+    changes(session: string, cursor?: number): {
+        revision: number;
+        data: FlowUpdate;
+    };
+}