@oxygen-agent/cli 1.365.3 → 1.575.19

package/node_modules/@oxygen/workflows/dist/graph/remap.js

@@ -0,0 +1,213 @@
+import { SCOPE_PATH_ROOTS } from "./expression.js";
+/** Rewrite the node ids in one scope path, leaving foreign syntax untouched. */
+export function remapScopePath(path, ids) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return path;
+    // The id segment accepts anything up to the next delimiter, not just
+    // [A-Za-z_][A-Za-z0-9_]*. genNodeId only ever mints `[a-z0-9_]`, but a
+    // CLI-authored manifest can carry `find-person` or a non-ASCII id, and
+    // parseScopePath/resolvePath both read those — so a narrower pattern here
+    // silently skipped exactly the ids the editor did not create.
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\.([^.[]+)([.[].*)?$/.exec(trimmed);
+    if (!match)
+        return path;
+    const [, root, id, rest] = match;
+    if (root === undefined || id === undefined)
+        return path;
+    // `trigger` has no node id in the second position — it is `trigger.input`.
+    if (!SCOPE_PATH_ROOTS.has(root) || root === "trigger")
+        return path;
+    const next = ids.get(id);
+    return next === undefined ? path : `${root}.${next}${rest ?? ""}`;
+}
+/**
+ * Rewrite node ids inside `{{ ... }}` tokens, leaving every foreign token alone.
+ *
+ * Same discriminator the evaluator uses: only a token rooted at one of our scope
+ * roots is ours. `{{column}}` and `{{RANDOM|a|b}}` are Oxygen merge-tag syntax
+ * that travels inside these same strings and must survive untouched.
+ */
+export function remapTokens(value, ids) {
+    return value.replace(/\{\{([^{}]*)\}\}/g, (match, body) => {
+        const path = body.trim();
+        if (!path)
+            return match;
+        const root = path.split(/[.[]/, 1)[0];
+        if (root === undefined || !SCOPE_PATH_ROOTS.has(root))
+            return match;
+        const remapped = remapScopePath(path, ids);
+        return remapped === path ? match : `{{ ${remapped} }}`;
+    });
+}
+export function remapValueRef(ref, ids) {
+    switch (ref.type) {
+        case "ref":
+            return { ...ref, path: remapScopePath(ref.path, ids) };
+        case "template":
+            return { ...ref, value: remapTokens(ref.value, ids) };
+        case "literal":
+            return { ...ref, value: remapLiteral(ref.value, ids) };
+        case "formula":
+            return { ...ref, expression: remapFormulaIdentifiers(ref.expression, ids) };
+        default:
+            // context_profile / context_asset name no node.
+            return ref;
+    }
+}
+function remapLiteral(value, ids, depth = 0) {
+    if (depth > 12)
+        return value;
+    if (typeof value === "string")
+        return remapTokens(value, ids);
+    if (Array.isArray(value))
+        return value.map((entry) => remapLiteral(entry, ids, depth + 1));
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            out[key] = remapLiteral(entry, ids, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Rewrite bare identifiers in a formula that name a mapped node.
+ *
+ * Quoted string literals are skipped, so a formula like `concat(find, "find")`
+ * rewrites the identifier and leaves the text alone. Beyond that this is a
+ * word-boundary substitution rather than a parse: @oxygen/formula owns the
+ * grammar, and re-implementing it here to rename an identifier would be a second
+ * opinion on what a formula means.
+ */
+function remapFormulaIdentifiers(expression, ids) {
+    if (ids.size === 0)
+        return expression;
+    let out = "";
+    let index = 0;
+    while (index < expression.length) {
+        const char = expression[index];
+        if (char === '"' || char === "'") {
+            // Copy the string literal verbatim, including its closing quote.
+            const end = expression.indexOf(char, index + 1);
+            const stop = end === -1 ? expression.length : end + 1;
+            out += expression.slice(index, stop);
+            index = stop;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(char)) {
+            let word = "";
+            while (index < expression.length && /[A-Za-z0-9_]/.test(expression[index])) {
+                word += expression[index];
+                index += 1;
+            }
+            // A DOTTED identifier is a scope path, so hand the whole thing to
+            // remapScopePath rather than substituting word by word. Word-by-word looked
+            // like it worked — `steps.<id>.x` has the node id in a word position — but it
+            // also rewrote FIELDS that happen to share a duplicated node's name:
+            // `steps.a.enrich` would have had its `enrich` field renamed. Only the second
+            // segment of a rooted path is a node id, and only remapScopePath knows that.
+            if (SCOPE_PATH_ROOTS.has(word) && expression[index] === ".") {
+                const pathEnd = readPathEnd(expression, index);
+                const path = word + expression.slice(index, pathEnd);
+                out += remapScopePath(path, ids);
+                index = pathEnd;
+                continue;
+            }
+            out += ids.get(word) ?? word;
+            continue;
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+/** End of a `.field` / `[0]` run, mirroring the tokenizer's own path scan. */
+function readPathEnd(expression, from) {
+    let index = from;
+    for (;;) {
+        const char = expression[index];
+        if (char === "." && /[A-Za-z0-9_]/.test(expression[index + 1] ?? "")) {
+            index += 2;
+            while (/[A-Za-z0-9_]/.test(expression[index] ?? ""))
+                index += 1;
+            continue;
+        }
+        if (char === "[") {
+            const close = expression.indexOf("]", index);
+            if (close === -1)
+                return index;
+            index = close + 1;
+            continue;
+        }
+        return index;
+    }
+}
+export function remapCondition(condition, ids) {
+    if (condition.type === "group") {
+        return { ...condition, children: condition.children.map((child) => remapCondition(child, ids)) };
+    }
+    return {
+        ...condition,
+        left: remapValueRef(condition.left, ids),
+        ...(condition.right === undefined ? {} : { right: remapValueRef(condition.right, ids) }),
+    };
+}
+/**
+ * Every binding in one node, rewritten.
+ *
+ * Switches on kind exhaustively rather than walking unknown keys: a node's shape
+ * is closed, and a generic deep walk would also rewrite things that merely look
+ * like paths (a `code` node's JavaScript, a switch case's label).
+ */
+export function remapNodeRefs(node, ids) {
+    switch (node.kind) {
+        case "tool":
+            return {
+                ...node,
+                params: Object.fromEntries(Object.entries(node.params).map(([key, ref]) => [key, remapValueRef(ref, ids)])),
+            };
+        case "filter":
+            return { ...node, when: remapCondition(node.when, ids) };
+        case "switch":
+            return {
+                ...node,
+                cases: node.cases.map((entry) => ({ ...entry, when: remapCondition(entry.when, ids) })),
+            };
+        case "loop":
+            return { ...node, over: remapValueRef(node.over, ids) };
+        case "set":
+            return {
+                ...node,
+                fields: node.fields.map((field) => ({ ...field, value: remapValueRef(field.value, ids) })),
+            };
+        case "wait":
+            return node.until === undefined
+                ? node
+                : { ...node, until: remapValueRef(node.until, ids) };
+        case "workflow":
+            return {
+                ...node,
+                input: Object.fromEntries(Object.entries(node.input).map(([key, ref]) => [key, remapValueRef(ref, ids)])),
+            };
+        // Missed when this module was first written, because the kind list was typed
+        // from memory instead of read off the WorkflowGraphNode union — so a
+        // duplicated approval node kept pointing at the original, silently, which is
+        // the exact failure this module exists to prevent.
+        case "approval":
+            return {
+                ...node,
+                ...(node.reason === undefined ? {} : { reason: remapValueRef(node.reason, ids) }),
+                ...(node.request === undefined
+                    ? {}
+                    : {
+                        request: Object.fromEntries(Object.entries(node.request).map(([key, ref]) => [key, remapValueRef(ref, ids)])),
+                    }),
+            };
+        default:
+            // trigger, merge, code — no bindings. A `code` node's source is JavaScript
+            // reading `ctx.steps`, deliberately NOT rewritten: it is arbitrary code, and
+            // string-substituting inside it would be a guess.
+            return node;
+    }
+}

package/node_modules/@oxygen/workflows/dist/graph/topology.d.ts

@@ -0,0 +1,46 @@
+import { type WorkflowGraphEdge, type WorkflowGraphManifest } from "./types.js";
+export type GraphAdjacency = {
+    /** node id -> edges leaving it, in manifest declaration order. */
+    outgoing: Map<string, WorkflowGraphEdge[]>;
+    /** node id -> edges arriving at it, in manifest declaration order. */
+    incoming: Map<string, WorkflowGraphEdge[]>;
+};
+/**
+ * Both directions of the edge list, with an entry for every declared node (an
+ * isolated node maps to an empty array rather than being absent).
+ */
+export declare function buildAdjacency(graph: WorkflowGraphManifest): GraphAdjacency;
+/** Edges naming a source or target that no node declares. */
+export declare function danglingEdges(graph: WorkflowGraphManifest): WorkflowGraphEdge[];
+/** Nodes with no inbound edge, in declaration order. */
+export declare function entryNodeIds(graph: WorkflowGraphManifest): string[];
+/** Every node a run can actually reach from its roots (see rootNodeIds). */
+export declare function reachableNodeIds(graph: WorkflowGraphManifest): Set<string>;
+/**
+ * The nodes that make up a loop's body: everything reachable from the loop's
+ * "loop_body" handle without passing back through the loop node itself. The loop
+ * node is not a member of its own body.
+ *
+ * Membership is transitive through a nested loop, so an inner loop's body is also
+ * part of the outer loop's body. That is what lets a genuinely nested pair keep
+ * both of its back-edges legal.
+ */
+export declare function loopBodyNodeIds(graph: WorkflowGraphManifest, loopNodeId: string): Set<string>;
+/**
+ * Kahn's algorithm over the graph minus legal back-edges. Returns null when some
+ * node can never be scheduled — i.e. an illegal cycle exists.
+ *
+ * Ties are broken by manifest declaration order, so the order is stable across
+ * runs and across machines.
+ */
+export declare function topologicalOrder(graph: WorkflowGraphManifest): string[] | null;
+/**
+ * Illegal cycles: one entry per strongly connected component that still contains
+ * a cycle once legal loop back-edges are removed.
+ *
+ * Each entry lists the component's node ids in declaration order; a single-id
+ * entry means a self-edge. A component is the smallest deterministic description
+ * of an illegal cycle — enumerating every simple cycle is exponential and no
+ * caller needs the enumeration.
+ */
+export declare function findIllegalCycles(graph: WorkflowGraphManifest): string[][];

package/node_modules/@oxygen/workflows/dist/graph/topology.js

@@ -0,0 +1,280 @@
+// Pure graph algorithms over an oxygen-workflows-v2 manifest, shared by the
+// linter, the worker scheduler and the visual editor. No I/O, no node builtins:
+// this module ships to the browser.
+//
+// Two conventions hold throughout:
+//   - Dangling edges (an endpoint that names no node) are excluded from every
+//     traversal and reported separately by danglingEdges(). Topology answers stay
+//     meaningful on a half-drawn canvas.
+//   - `disabled` nodes still participate. Disabling is a run-time skip, not a
+//     structural edit, so the editor keeps showing the same shape.
+import { LOOP_BODY_HANDLE, isLoopNode, isTriggerNode, } from "./types.js";
+function nodeIndex(graph) {
+    const index = new Map();
+    for (const node of graph.nodes) {
+        // First declaration wins; duplicate ids are the linter's problem, and
+        // silently preferring the later one would hide the duplicate here.
+        if (!index.has(node.id))
+            index.set(node.id, node);
+    }
+    return index;
+}
+function pushEdge(map, key, edge) {
+    const existing = map.get(key);
+    if (existing)
+        existing.push(edge);
+    else
+        map.set(key, [edge]);
+}
+/**
+ * Both directions of the edge list, with an entry for every declared node (an
+ * isolated node maps to an empty array rather than being absent).
+ */
+export function buildAdjacency(graph) {
+    const nodes = nodeIndex(graph);
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const id of nodes.keys()) {
+        outgoing.set(id, []);
+        incoming.set(id, []);
+    }
+    for (const edge of graph.edges) {
+        if (!nodes.has(edge.source) || !nodes.has(edge.target))
+            continue;
+        pushEdge(outgoing, edge.source, edge);
+        pushEdge(incoming, edge.target, edge);
+    }
+    return { outgoing, incoming };
+}
+/** Edges naming a source or target that no node declares. */
+export function danglingEdges(graph) {
+    const nodes = nodeIndex(graph);
+    return graph.edges.filter((edge) => !nodes.has(edge.source) || !nodes.has(edge.target));
+}
+/** Nodes with no inbound edge, in declaration order. */
+export function entryNodeIds(graph) {
+    const { incoming } = buildAdjacency(graph);
+    const entries = [];
+    for (const id of nodeIndex(graph).keys()) {
+        if ((incoming.get(id) ?? []).length === 0)
+            entries.push(id);
+    }
+    return entries;
+}
+/**
+ * Roots of execution: the declared trigger nodes when the graph has any,
+ * otherwise every node with no inbound edge.
+ *
+ * The preference matters — once a trigger exists it is the only way a run can
+ * start, so a second unconnected entry node is an island, not a second root.
+ */
+function rootNodeIds(graph) {
+    const triggers = graph.nodes.filter(isTriggerNode).map((node) => node.id);
+    return triggers.length > 0 ? triggers : entryNodeIds(graph);
+}
+/** Forward reachability over `outgoing`, optionally refusing to expand one node. */
+function traverse(startIds, outgoing, stopAt) {
+    const visited = new Set();
+    const queue = [];
+    for (const id of startIds) {
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        queue.push(id);
+    }
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (current === undefined)
+            break;
+        for (const edge of outgoing.get(current) ?? []) {
+            if (edge.target === stopAt || visited.has(edge.target))
+                continue;
+            visited.add(edge.target);
+            queue.push(edge.target);
+        }
+    }
+    return visited;
+}
+/** Every node a run can actually reach from its roots (see rootNodeIds). */
+export function reachableNodeIds(graph) {
+    const { outgoing } = buildAdjacency(graph);
+    return traverse(rootNodeIds(graph), outgoing);
+}
+function loopBodyFrom(outgoing, loopNodeId) {
+    const bodyEntries = (outgoing.get(loopNodeId) ?? [])
+        .filter((edge) => edge.source_handle === LOOP_BODY_HANDLE && edge.target !== loopNodeId)
+        .map((edge) => edge.target);
+    const body = traverse(bodyEntries, outgoing, loopNodeId);
+    body.delete(loopNodeId);
+    return body;
+}
+/**
+ * The nodes that make up a loop's body: everything reachable from the loop's
+ * "loop_body" handle without passing back through the loop node itself. The loop
+ * node is not a member of its own body.
+ *
+ * Membership is transitive through a nested loop, so an inner loop's body is also
+ * part of the outer loop's body. That is what lets a genuinely nested pair keep
+ * both of its back-edges legal.
+ */
+export function loopBodyNodeIds(graph, loopNodeId) {
+    const loop = nodeIndex(graph).get(loopNodeId);
+    if (!loop || !isLoopNode(loop))
+        return new Set();
+    return loopBodyFrom(buildAdjacency(graph).outgoing, loopNodeId);
+}
+/**
+ * The one legal back-edge rule: an edge may close a cycle only by returning to
+ * the loop node whose "loop_body" it starts inside. Every other edge that closes
+ * a cycle is illegal.
+ *
+ * Proper nesting is strict containment — the inner loop sits in the outer loop's
+ * body, never the reverse. Two loops that each sit inside the other's body are
+ * interlocked rather than nested (each "back-edge" is also the other's forward
+ * edge), so neither loop grants legality and their tangle is reported as an
+ * illegal cycle.
+ */
+function legalBackEdgeIds(graph) {
+    const { outgoing, incoming } = buildAdjacency(graph);
+    const loopIds = graph.nodes.filter(isLoopNode).map((node) => node.id);
+    const bodies = new Map();
+    for (const loopId of loopIds)
+        bodies.set(loopId, loopBodyFrom(outgoing, loopId));
+    const legal = new Set();
+    for (const loopId of loopIds) {
+        const body = bodies.get(loopId) ?? new Set();
+        const interlocked = loopIds.some((other) => other !== loopId && body.has(other) && (bodies.get(other)?.has(loopId) ?? false));
+        if (interlocked)
+            continue;
+        for (const edge of incoming.get(loopId) ?? []) {
+            if (body.has(edge.source))
+                legal.add(edge.id);
+        }
+    }
+    return legal;
+}
+/** Adjacency minus legal loop back-edges — acyclic if and only if the graph is legal. */
+function forwardOutgoing(graph) {
+    const { outgoing } = buildAdjacency(graph);
+    const backEdges = legalBackEdgeIds(graph);
+    const forward = new Map();
+    for (const [id, edges] of outgoing) {
+        forward.set(id, edges.filter((edge) => !backEdges.has(edge.id)));
+    }
+    return forward;
+}
+/**
+ * Kahn's algorithm over the graph minus legal back-edges. Returns null when some
+ * node can never be scheduled — i.e. an illegal cycle exists.
+ *
+ * Ties are broken by manifest declaration order, so the order is stable across
+ * runs and across machines.
+ */
+export function topologicalOrder(graph) {
+    const nodes = nodeIndex(graph);
+    const forward = forwardOutgoing(graph);
+    const indegree = new Map();
+    for (const id of nodes.keys())
+        indegree.set(id, 0);
+    for (const edges of forward.values()) {
+        for (const edge of edges)
+            indegree.set(edge.target, (indegree.get(edge.target) ?? 0) + 1);
+    }
+    const ready = [...nodes.keys()].filter((id) => (indegree.get(id) ?? 0) === 0);
+    const order = [];
+    while (ready.length > 0) {
+        const current = ready.shift();
+        if (current === undefined)
+            break;
+        order.push(current);
+        for (const edge of forward.get(current) ?? []) {
+            const remaining = (indegree.get(edge.target) ?? 0) - 1;
+            indegree.set(edge.target, remaining);
+            // Enqueue on exactly zero: parallel edges decrement more than once and must
+            // not enqueue the same node twice.
+            if (remaining === 0)
+                ready.push(edge.target);
+        }
+    }
+    return order.length === nodes.size ? order : null;
+}
+/**
+ * Illegal cycles: one entry per strongly connected component that still contains
+ * a cycle once legal loop back-edges are removed.
+ *
+ * Each entry lists the component's node ids in declaration order; a single-id
+ * entry means a self-edge. A component is the smallest deterministic description
+ * of an illegal cycle — enumerating every simple cycle is exponential and no
+ * caller needs the enumeration.
+ */
+export function findIllegalCycles(graph) {
+    const nodes = nodeIndex(graph);
+    const forward = forwardOutgoing(graph);
+    const declarationIndex = new Map();
+    for (const [position, id] of [...nodes.keys()].entries())
+        declarationIndex.set(id, position);
+    const orderOf = (id) => declarationIndex.get(id ?? "") ?? 0;
+    // Iterative Tarjan: recursion depth would otherwise track graph size, and a
+    // generated graph can be far deeper than an author-drawn one.
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    let counter = 0;
+    const open = (id) => {
+        index.set(id, counter);
+        lowlink.set(id, counter);
+        counter += 1;
+        stack.push(id);
+        onStack.add(id);
+    };
+    for (const root of nodes.keys()) {
+        if (index.has(root))
+            continue;
+        open(root);
+        const work = [{ id: root, edgeIndex: 0 }];
+        while (work.length > 0) {
+            const frame = work[work.length - 1];
+            if (!frame)
+                break;
+            const edges = forward.get(frame.id) ?? [];
+            const edge = frame.edgeIndex < edges.length ? edges[frame.edgeIndex] : undefined;
+            if (edge) {
+                frame.edgeIndex += 1;
+                if (!index.has(edge.target)) {
+                    open(edge.target);
+                    work.push({ id: edge.target, edgeIndex: 0 });
+                }
+                else if (onStack.has(edge.target)) {
+                    lowlink.set(frame.id, Math.min(lowlink.get(frame.id) ?? 0, index.get(edge.target) ?? 0));
+                }
+                continue;
+            }
+            work.pop();
+            const parent = work[work.length - 1];
+            if (parent) {
+                lowlink.set(parent.id, Math.min(lowlink.get(parent.id) ?? 0, lowlink.get(frame.id) ?? 0));
+            }
+            if (lowlink.get(frame.id) !== index.get(frame.id))
+                continue;
+            const component = [];
+            for (;;) {
+                const member = stack.pop();
+                if (member === undefined)
+                    break;
+                onStack.delete(member);
+                component.push(member);
+                if (member === frame.id)
+                    break;
+            }
+            const hasSelfEdge = (forward.get(frame.id) ?? []).some((e) => e.target === frame.id);
+            if (component.length > 1 || hasSelfEdge) {
+                component.sort((a, b) => orderOf(a) - orderOf(b));
+                components.push(component);
+            }
+        }
+    }
+    components.sort((a, b) => orderOf(a[0]) - orderOf(b[0]));
+    return components;
+}