@oxygen-agent/cli 1.365.3 → 1.575.19

package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.js

@@ -0,0 +1,200 @@
+// The published JSON Schema for an oxygen-workflows-v2 manifest, served by
+// `GET /api/cli/workflows/schema` (subject "graph") and by `oxygen workflows
+// schema`. It is the authoring contract an agent reads before writing a graph.
+//
+// Scope: shape, not semantics. It pins the envelope, the node kinds, the edge
+// shape, and the value-ref vocabulary — enough to author a manifest that will be
+// recognized — and deliberately stops there. ./lint.ts stays the authority on
+// per-kind required fields, topology (one trigger, reachability, the one legal
+// back-edge), tool allowlists, formula syntax, and code-source purity; a second
+// full copy of those rules here would drift from the linter that actually runs.
+//
+// Pure data: this module ships to the browser with the rest of the graph barrel.
+import { MAX_WORKFLOW_NODE_RETRY_ATTEMPTS, MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, } from "./types.js";
+const valueRefSchema = {
+    type: "object",
+    description: "How a node input is bound at run time. Scope paths are 'trigger.input.x', 'steps.<node_id>.output.y', or 'loop.<loop_node_id>.item.z'.",
+    properties: {
+        type: {
+            enum: ["literal", "template", "ref", "formula", "context_profile", "context_asset"],
+        },
+        value: { description: "literal: used verbatim. template: interpolated string, e.g. 'Hi {{ steps.find.output.first_name }}'." },
+        path: { type: "string", description: "ref: a scope path. context_*: an optional path inside the context value." },
+        expression: { type: "string", description: "formula: an OXYGEN formula-language expression." },
+        assetId: { type: "string", description: "context_asset: the Knowledge-layer asset id." },
+    },
+    required: ["type"],
+};
+const conditionSchema = {
+    type: "object",
+    description: "A structured predicate: { type: 'group', op: 'all' | 'any', not?: boolean, children: [...] } or { type: 'compare', left, op, right? }. 'is_empty' / 'is_not_empty' take no right operand.",
+    properties: {
+        type: { enum: ["group", "compare"] },
+        op: {
+            enum: [
+                "all",
+                "any",
+                "eq",
+                "neq",
+                "gt",
+                "gte",
+                "lt",
+                "lte",
+                "contains",
+                "not_contains",
+                "starts_with",
+                "ends_with",
+                "is_empty",
+                "is_not_empty",
+                "in",
+                "not_in",
+                "matches",
+            ],
+        },
+        not: { type: "boolean" },
+        children: { type: "array", items: { type: "object", additionalProperties: true } },
+        left: valueRefSchema,
+        right: valueRefSchema,
+    },
+    required: ["type"],
+};
+const nodeSchema = {
+    type: "object",
+    additionalProperties: true,
+    properties: {
+        id: {
+            type: "string",
+            description: "Unique node id. Becomes a key on the run scope ('steps.<id>.output'), so '__proto__', 'constructor' and 'prototype' are rejected.",
+        },
+        name: { type: "string" },
+        description: { type: "string" },
+        kind: {
+            enum: ["trigger", "tool", "filter", "switch", "loop", "merge", "set", "wait", "approval", "code", "workflow"],
+        },
+        ui: {
+            type: "object",
+            description: "Canvas position. Presentation only — it never affects execution order.",
+            properties: { x: { type: "number" }, y: { type: "number" } },
+            required: ["x", "y"],
+        },
+        disabled: { type: "boolean", description: "Kept in the graph but skipped at run time." },
+        continue_on_error: {
+            type: "boolean",
+            description: "Route failures to the 'error' handle instead of failing the run.",
+        },
+        retry: {
+            type: "object",
+            description: "Retry this node after a transient failure. It only ever narrows what the "
+                + "run would already do: a node whose effect is 'external_write' is never "
+                + "auto-retried in a live run whatever this says, because an ambiguous "
+                + "network error may have landed and repeating the call could write twice. "
+                + "The run's own attempt budget still caps the total.",
+            properties: {
+                max_attempts: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: MAX_WORKFLOW_NODE_RETRY_ATTEMPTS,
+                    description: "Attempts for this node, counting the first.",
+                },
+                wait_seconds: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS,
+                    description: "Fixed pause between attempts. Omit to use the run's own backoff.",
+                },
+            },
+            required: ["max_attempts"],
+        },
+        tool: { type: "string", description: "tool nodes: the tool id to call." },
+        effect: {
+            enum: ["none", "external_read", "external_write"],
+            description: "tool nodes: must equal the tool's canonical effect.",
+        },
+        mode: { enum: ["dry_run", "live", "smoke_test"] },
+        max_credits: { type: "number", exclusiveMinimum: 0, description: "Per-node managed-credit ceiling." },
+        params: {
+            type: "object",
+            description: "tool nodes: parameter name -> value ref.",
+            additionalProperties: valueRefSchema,
+        },
+        when: conditionSchema,
+        cases: {
+            type: "array",
+            description: "switch nodes: each case id names the outgoing edge handle it owns.",
+            items: {
+                type: "object",
+                properties: { id: { type: "string" }, label: { type: "string" }, when: conditionSchema },
+                required: ["id", "label", "when"],
+            },
+        },
+        fallthrough: { type: "boolean", description: "switch nodes: fire every matching case, not only the first." },
+        over: valueRefSchema,
+        item_name: { type: "string" },
+        max_iterations: {
+            type: "integer",
+            exclusiveMinimum: 0,
+            description: "loop nodes: declared iteration cap. Without it the workflow's automation-action estimate can only assume a single pass, and cron cadence checks treat the run cost as unbounded.",
+        },
+        concurrency: { type: "integer", exclusiveMinimum: 0 },
+        strategy: { enum: ["append", "first", "wait_all"], description: "merge nodes: how inbound branches are joined." },
+        fields: {
+            type: "array",
+            description: "set nodes: the object built from bound fields.",
+            items: {
+                type: "object",
+                properties: { key: { type: "string" }, value: valueRefSchema },
+                required: ["key", "value"],
+            },
+        },
+        keep_input: { type: "boolean" },
+        duration_seconds: { type: "number", exclusiveMinimum: 0, description: "wait nodes: exactly one of duration_seconds or until." },
+        until: valueRefSchema,
+        run_source: { type: "string", description: "code nodes: sandboxed pure-function source." },
+        workflow_id: { type: "string", description: "workflow nodes: the child workflow to run." },
+        input: { type: "object", description: "workflow nodes: child input name -> value ref.", additionalProperties: valueRefSchema },
+    },
+    required: ["id", "name", "kind", "ui"],
+};
+const edgeSchema = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        id: { type: "string" },
+        source: { type: "string" },
+        source_handle: {
+            type: "string",
+            description: "Which output of the source node this edge leaves from: a switch case id, 'loop_body', 'loop_done', 'error', or omitted for the default output.",
+        },
+        target: { type: "string" },
+    },
+    required: ["id", "source", "target"],
+};
+export const workflowGraphManifestSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "OXYGEN Workflow Graph Manifest (oxygen-workflows-v2)",
+    description: "A node + edge workflow graph. Exactly one trigger node; every node reachable from it; cycles are illegal except a single back-edge from inside a loop's body to that loop node.",
+    type: "object",
+    additionalProperties: true,
+    properties: {
+        manifest_version: { const: WORKFLOW_GRAPH_MANIFEST_VERSION },
+        compiler_version: { const: WORKFLOW_GRAPH_COMPILER_VERSION },
+        workflow: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                name: { type: "string" },
+                status: { enum: ["active", "disabled"] },
+            },
+            required: ["id", "name"],
+        },
+        specification: { type: "string" },
+        trigger: { type: "object", additionalProperties: true, description: "See the 'trigger' schema subject." },
+        input_schema: { type: "object", additionalProperties: true },
+        nodes: { type: "array", items: nodeSchema, minItems: 1 },
+        edges: { type: "array", items: edgeSchema },
+        max_credits: { type: "number", exclusiveMinimum: 0, description: "Per-RUN managed-credit ceiling." },
+        source_hash: { type: "string" },
+        created_at: { type: "string" },
+    },
+    required: ["manifest_version", "workflow", "nodes", "edges", "source_hash", "compiler_version"],
+};

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

@@ -0,0 +1,86 @@
+/**
+ * Whether a tool node's inputs are actually filled in — the ONE implementation.
+ *
+ * This lived only in the editor, which produced the exact divergence the repo
+ * spends real effort avoiding elsewhere: the canvas refused a node while
+ * `/api/cli/workflows/apply` accepted the same manifest, and a CLI-authored
+ * workflow got no check at all. Doctrine is that the CLI does and the web sees;
+ * a guarantee the GUI enforces alone is not a guarantee.
+ *
+ * Kept browser-safe and dependency-free so both sides can call it: the editor
+ * over a loaded descriptor, the server linter over the tool registry.
+ */
+/**
+ * A tool's fields plus whether its schema is CLOSED.
+ *
+ * The closed flag is separate from the field list because it is a property of the
+ * schema, not of any field, and it is optional so a caller that cannot determine it
+ * stays on the old permissive behaviour rather than inventing blockers.
+ */
+export type ToolParamFields = {
+    fields: readonly ToolParamSpec[];
+    /** True only when the schema explicitly declares `additionalProperties: false`. */
+    closed?: boolean;
+};
+/** The subset of a tool's input schema these rules need. */
+export type ToolParamSpec = {
+    name: string;
+    required: boolean;
+    /** The schema's human title, preferred when naming what is missing. */
+    title?: string;
+};
+/**
+ * Capabilities needing exactly one of a set of inputs, keyed by tool id.
+ *
+ * A deliberate table rather than inference. The relationship lives in prose in
+ * the field descriptions ("Mutually exclusive with…", "Omit when passing…"), and
+ * parsing prose to decide whether a node may save would be fragile and invisible.
+ * A short list is reviewable, and every group is checked against the tool's real
+ * fields first, so a renamed input degrades to no check rather than a blocker the
+ * author cannot clear.
+ */
+export declare const ONE_OF_REQUIREMENTS: Record<string, readonly string[][]>;
+/**
+ * What is still missing before this node can run, in words an author can act on.
+ * Empty means ready.
+ */
+export declare function missingToolParams(input: {
+    toolId: string;
+    fields: readonly ToolParamSpec[];
+    params: Record<string, unknown>;
+    /**
+     * Whether the tool's schema declares `additionalProperties: false`. Only then is
+     * an unrecognised key reported — a tool that genuinely accepts extras (a custom
+     * HTTP tool) must not be given a blocker its author cannot clear.
+     */
+    closed?: boolean;
+}): string[];
+/**
+ * Bound keys the tool's schema does not define. Empty unless the schema is CLOSED.
+ *
+ * A key the schema does not define goes nowhere: every one of the 494
+ * workflow-callable `oxygen_*` schemas is `additionalProperties: false`, so the
+ * route either rejects the call or drops the value — and the canvas meanwhile shows
+ * it as configured. Same failure class as a bound-but-empty ref, and the reason a
+ * misspelled param name is worth its own message rather than being folded into
+ * "still needs X", which reads as the opposite of what happened.
+ *
+ * Keyed on an EXPLICIT `additionalProperties: false`. JSON Schema's default is open,
+ * and a provider or custom HTTP tool that omits the keyword must keep accepting
+ * extras rather than acquiring a blocker its author cannot clear.
+ */
+export declare function unknownToolParams(input: {
+    fields: readonly ToolParamSpec[];
+    params: Record<string, unknown>;
+    closed?: boolean;
+}): string[];
+/**
+ * Whether a binding carries no value the provider will actually receive.
+ *
+ * Testing presence — `params[name] !== undefined` — was the mistake behind two
+ * one-click escapes: choosing "A fixed value" writes `{literal:""}` and blurring
+ * an empty JSON box commits `[]`. Both are present, so both cleared the warning,
+ * which is worse than an untouched field because the author reads a cleared
+ * warning as configured. A bound-but-empty ref is unset.
+ */
+export declare function isValueRefEmpty(ref: unknown): boolean;

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

@@ -0,0 +1,173 @@
+/**
+ * Capabilities needing exactly one of a set of inputs, keyed by tool id.
+ *
+ * A deliberate table rather than inference. The relationship lives in prose in
+ * the field descriptions ("Mutually exclusive with…", "Omit when passing…"), and
+ * parsing prose to decide whether a node may save would be fragile and invisible.
+ * A short list is reviewable, and every group is checked against the tool's real
+ * fields first, so a renamed input degrades to no check rather than a blocker the
+ * author cannot clear.
+ */
+export const ONE_OF_REQUIREMENTS = {
+    // `leads` is "Omit when passing from_table: true"; `from_table` is mutually
+    // exclusive with it. Neither is in `required`, so both were optional and a node
+    // with neither saved, armed a cron, and enrolled nobody.
+    oxygen_sequences_enroll: [["leads", "from_table"]],
+    // Declares no `required` array at all and needs one of the two payload forms.
+    oxygen_tables_import_csv: [["csv_text", "csv_base64"]],
+};
+/**
+ * What is still missing before this node can run, in words an author can act on.
+ * Empty means ready.
+ */
+export function missingToolParams(input) {
+    const { toolId, fields, params, closed } = input;
+    const label = (name) => fields.find((field) => field.name === name)?.title ?? name;
+    // An unknown key suppresses the missing-required report, because a misspelled
+    // name is simultaneously an unknown key AND the reason a required field looks
+    // unset — telling the author "still needs Domain" when they typed `domian` sends
+    // them to re-enter a value that is already there. The unknown key is reported
+    // separately by unknownToolParams, under its own message.
+    if (unknownToolParams(input).length > 0)
+        return [];
+    const missing = fields
+        .filter((field) => field.required && isValueRefEmpty(params[field.name]))
+        .map((field) => label(field.name));
+    if (missing.length > 0)
+        return missing;
+    // A capability declaring NOTHING required is the dangerous case, not the safe
+    // one: `oxygen_find_email` publishes no `required` array, so a node with every
+    // field blank cleared the check, saved, armed a cron and then previewed forever
+    // — finding nothing, spending nothing, reporting no error. Silence is the worst
+    // failure mode a scheduled workflow has.
+    if (fields.length > 0 && fields.every((field) => isValueRefEmpty(params[field.name]))) {
+        // ONE composed phrase, not the first three field names. Returning names made
+        // the caller render "oxygen_tables_list still needs project." plus two more —
+        // three issues naming three OPTIONAL filters, which reads as "fill in all of
+        // these" when any one will do. Caught by applying a real graph through the CLI:
+        // the rule was right and its wording sent the author the wrong way.
+        const examples = fields.slice(0, 3).map((field) => label(field.name));
+        return [`at least one input — try ${joinOr(examples)}`];
+    }
+    // A spend ceiling is required the moment the run goes live, and the schema says
+    // so only in prose: max_credits is "Required when mode=live". `mode` defaults to
+    // dry_run so a Test passes, and because the workflow's mode overrides whatever
+    // the author bound, a live run ALWAYS forces mode=live. Keyed on the field
+    // existing: a capability exposes a ceiling because it can spend.
+    const cap = fields.find((field) => field.name === "max_credits");
+    if (cap && !isPositiveNumberRef(params.max_credits))
+        return [label("max_credits")];
+    for (const group of ONE_OF_REQUIREMENTS[toolId] ?? []) {
+        const known = group.filter((name) => fields.some((field) => field.name === name));
+        if (known.length !== group.length)
+            continue;
+        const selected = group.filter((name) => isOneOfOptionSelected(params[name]));
+        if (selected.length === 0)
+            return [group.map(label).join(" or ")];
+        // The schemas call these mutually exclusive and the routes refuse both
+        // ("Pass either from_table: true or leads[] — not both"), so binding both is
+        // as unrunnable as binding neither.
+        if (selected.length > 1)
+            return [`only one of ${group.map(label).join(" or ")}`];
+    }
+    return [];
+}
+/**
+ * Bound keys the tool's schema does not define. Empty unless the schema is CLOSED.
+ *
+ * A key the schema does not define goes nowhere: every one of the 494
+ * workflow-callable `oxygen_*` schemas is `additionalProperties: false`, so the
+ * route either rejects the call or drops the value — and the canvas meanwhile shows
+ * it as configured. Same failure class as a bound-but-empty ref, and the reason a
+ * misspelled param name is worth its own message rather than being folded into
+ * "still needs X", which reads as the opposite of what happened.
+ *
+ * Keyed on an EXPLICIT `additionalProperties: false`. JSON Schema's default is open,
+ * and a provider or custom HTTP tool that omits the keyword must keep accepting
+ * extras rather than acquiring a blocker its author cannot clear.
+ */
+export function unknownToolParams(input) {
+    if (input.closed !== true || input.fields.length === 0)
+        return [];
+    const known = new Set(input.fields.map((field) => field.name));
+    return Object.keys(input.params).filter((name) => !known.has(name));
+}
+/**
+ * Whether a binding carries no value the provider will actually receive.
+ *
+ * Testing presence — `params[name] !== undefined` — was the mistake behind two
+ * one-click escapes: choosing "A fixed value" writes `{literal:""}` and blurring
+ * an empty JSON box commits `[]`. Both are present, so both cleared the warning,
+ * which is worse than an untouched field because the author reads a cleared
+ * warning as configured. A bound-but-empty ref is unset.
+ */
+export function isValueRefEmpty(ref) {
+    if (ref === undefined || ref === null)
+        return true;
+    if (typeof ref !== "object")
+        return false;
+    const value = ref;
+    switch (value.type) {
+        case "literal":
+            return isEmptyLiteral(value.value);
+        case "template":
+            return typeof value.value !== "string" || value.value.trim() === "";
+        case "formula":
+            return typeof value.expression !== "string" || value.expression.trim() === "";
+        case "ref":
+            return typeof value.path !== "string" || value.path.trim() === "";
+        default:
+            // context_profile / context_asset always resolve to something.
+            return false;
+    }
+}
+/** "a, b or c" — an English list, so the phrase reads as prose in the caller. */
+function joinOr(values) {
+    if (values.length <= 1)
+        return values[0] ?? "";
+    return `${values.slice(0, -1).join(", ")} or ${values[values.length - 1]}`;
+}
+function isEmptyLiteral(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === "object")
+        return Object.keys(value).length === 0;
+    return false;
+}
+/**
+ * Whether a one-of option is actually TURNED ON.
+ *
+ * Stricter than "not empty" in exactly one way: a literal `false` does not select
+ * an option. `from_table` is a boolean switch, and toggling it on then off writes
+ * `{literal:false}` — present, non-empty, and meaning "do not enroll from the
+ * table". Scoped to one-of groups on purpose: a literal `false` elsewhere
+ * (`exclude_contacted`) is a real value and must stay one.
+ */
+function isOneOfOptionSelected(ref) {
+    if (isValueRefEmpty(ref))
+        return false;
+    const value = ref;
+    return !(value.type === "literal" && value.value === false);
+}
+/**
+ * A spend ceiling has to be a POSITIVE number, not merely bound.
+ *
+ * `enforceLiveSpendCap` requires greater than zero and `readNumber` silently
+ * drops a non-number, so a cap of "" or 0 reaches the route as no cap at all and
+ * the live delivery fails with spend_cap_required — the failure the check exists
+ * to prevent. A ref, formula or template is accepted: only a literal can be
+ * judged before the run.
+ */
+function isPositiveNumberRef(ref) {
+    if (isValueRefEmpty(ref))
+        return false;
+    const value = ref;
+    if (value.type !== "literal")
+        return true;
+    const numeric = typeof value.value === "string" ? Number(value.value) : value.value;
+    return typeof numeric === "number" && Number.isFinite(numeric) && numeric > 0;
+}

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

@@ -0,0 +1,48 @@
+import type { WorkflowCondition, WorkflowGraphNode, WorkflowValueRef } from "./types.js";
+/**
+ * Rewriting the node ids a binding points at.
+ *
+ * Needed by anything that copies part of a graph: a duplicated selection gets
+ * fresh node ids, and every binding INSIDE the selection that referenced a member
+ * of it must follow. Miss one and the copy silently reads from the original —
+ * which is not a crash, not a lint error, and not visible on the canvas. It is a
+ * workflow that quietly does the wrong thing, so the mapping surface is exhausted
+ * here, in one tested place, rather than inline at the call site.
+ *
+ * A node id can hide in four shapes:
+ *   ref       `steps.<id>.output.x`, `loop.<id>.item.y`
+ *   template  `"Hi {{ steps.<id>.first_name }}"`
+ *   literal   a structured value carrying `{{ }}` tokens, which resolve
+ *   condition either side of a compare, at any nesting depth
+ *
+ *   formula   a BARE identifier — `score * 2` reads the node named `score`
+ *
+ * The formula case was originally omitted here on the reasoning that "the formula
+ * tokenizer has no dotted paths, so a formula cannot name a node". That was wrong,
+ * and an audit disproved it by execution: a workflow formula's identifiers resolve
+ * through a scope whose keys ARE node ids, so `referencedNodeIds` reports `score`
+ * and the expression evaluates against `steps.score.output`. A duplicated formula
+ * therefore read the ORIGINAL node until this case existed.
+ */
+/** Old node id → new node id. Ids absent from the map are left alone. */
+export type NodeIdMap = ReadonlyMap<string, string>;
+/** Rewrite the node ids in one scope path, leaving foreign syntax untouched. */
+export declare function remapScopePath(path: string, ids: NodeIdMap): string;
+/**
+ * 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 declare function remapTokens(value: string, ids: NodeIdMap): string;
+export declare function remapValueRef(ref: WorkflowValueRef, ids: NodeIdMap): WorkflowValueRef;
+export declare function remapCondition(condition: WorkflowCondition, ids: NodeIdMap): WorkflowCondition;
+/**
+ * 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 declare function remapNodeRefs(node: WorkflowGraphNode, ids: NodeIdMap): WorkflowGraphNode;