@oxygen-agent/cli 1.696.2 → 1.717.1

package/node_modules/@oxygen/workflows/dist/portable.js

@@ -0,0 +1,319 @@
+import { createHash } from "node:crypto";
+import { PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION, PORTABLE_WORKFLOW_DEFINITION_VERSION, isPortableWorkflowDefinitionV1, isWorkflowGraphManifest, } from "./graph/types.js";
+import { lintWorkflowGraphManifest } from "./graph/lint.js";
+export class PortableWorkflowDefinitionValidationError extends Error {
+    issues;
+    constructor(issues) {
+        const first = issues[0];
+        super(first ? `${first.code}: ${first.message}` : "Invalid portable workflow definition.");
+        this.name = "PortableWorkflowDefinitionValidationError";
+        this.issues = issues;
+    }
+}
+const TRIGGER_AUTHORITY_FIELDS = new Set([
+    "preapproved_labels",
+    "preApprovedLabels",
+    "preapproved_by_user_id",
+    "standing_authorization",
+    "standing_authorization_policy",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** The graph editor and server use this same material rule. */
+export function hashPortableWorkflowGraphManifest(manifest) {
+    const material = cloneJson(manifest);
+    delete material.source_hash;
+    delete material.created_at;
+    return createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+function stripTriggerAuthority(trigger) {
+    if (!trigger)
+        return undefined;
+    const safe = cloneJson(trigger);
+    safe.status = "disabled";
+    if (safe.type !== "cron" || !isRecord(safe.metadata))
+        return safe;
+    const metadata = {};
+    for (const [key, value] of Object.entries(safe.metadata)) {
+        if (!TRIGGER_AUTHORITY_FIELDS.has(key))
+            metadata[key] = value;
+    }
+    return { ...safe, metadata };
+}
+function portableNodeIssue(node, index) {
+    if (node.kind === "code" && node.recipe) {
+        return {
+            path: `$.graph.nodes.${index}.recipe`,
+            code: "recipe_bundle_not_portable",
+            message: "A durable recipe bundle is one opaque compatibility node, not an editable workflow definition. Rebuild it as explicit graph nodes before exporting.",
+        };
+    }
+    if (node.kind === "tool" && node.payload_source !== undefined) {
+        return {
+            path: `$.graph.nodes.${index}.payload_source`,
+            code: "legacy_tool_payload_not_portable",
+            message: "This tool still computes its payload with legacy JavaScript. Replace it with schema-mapped params in the editor before exporting.",
+        };
+    }
+    if ("legacy_context" in node && node.legacy_context !== undefined) {
+        return {
+            path: `$.graph.nodes.${index}.legacy_context`,
+            code: "legacy_context_not_portable",
+            message: "Legacy execution context cannot be represented as a portable editable graph.",
+        };
+    }
+    if (node.kind === "workflow") {
+        return {
+            path: `$.graph.nodes.${index}`,
+            code: "workflow_node_not_portable",
+            message: "Child-workflow nodes are not executable yet and cannot be exported as a portable definition.",
+        };
+    }
+    return null;
+}
+function valueRefUsesWorkspaceAsset(ref) {
+    return ref.type === "context_asset";
+}
+function conditionUsesWorkspaceAsset(condition) {
+    if (condition.type === "group") {
+        return condition.children.some(conditionUsesWorkspaceAsset);
+    }
+    return valueRefUsesWorkspaceAsset(condition.left)
+        || (condition.right !== undefined && valueRefUsesWorkspaceAsset(condition.right));
+}
+/**
+ * Knowledge asset ids are workspace-local bindings, just like connection UUIDs.
+ * Keep this exhaustive over the graph union so a new binding-bearing node cannot
+ * accidentally become "portable" without an explicit rebinding contract.
+ */
+function nodeUsesWorkspaceAsset(node) {
+    switch (node.kind) {
+        case "tool":
+            return Object.values(node.params).some(valueRefUsesWorkspaceAsset);
+        case "filter":
+            return conditionUsesWorkspaceAsset(node.when);
+        case "switch":
+            return node.cases.some((entry) => conditionUsesWorkspaceAsset(entry.when));
+        case "loop":
+            return valueRefUsesWorkspaceAsset(node.over);
+        case "set":
+            return node.fields.some((field) => valueRefUsesWorkspaceAsset(field.value));
+        case "wait":
+            return node.until !== undefined && valueRefUsesWorkspaceAsset(node.until);
+        case "approval":
+            return (node.reason !== undefined && valueRefUsesWorkspaceAsset(node.reason))
+                || Object.values(node.request ?? {}).some(valueRefUsesWorkspaceAsset);
+        case "code":
+            return Object.values(node.configuration ?? {}).some(valueRefUsesWorkspaceAsset);
+        case "workflow":
+            return Object.values(node.input).some(valueRefUsesWorkspaceAsset);
+        case "trigger":
+        case "merge":
+            return false;
+    }
+}
+export function lintPortableWorkflowGraph(manifest) {
+    const issues = [];
+    if (!isWorkflowGraphManifest(manifest)) {
+        issues.push({
+            path: "$.graph",
+            code: "workflow_graph_required",
+            message: "Portable workflow definitions require an oxygen-workflows-v2 graph. Legacy workflow and recipe revisions remain runnable but must be rebuilt as graph nodes before export.",
+        });
+        return { ok: false, issues };
+    }
+    manifest.nodes.forEach((node, index) => {
+        const issue = portableNodeIssue(node, index);
+        if (issue)
+            issues.push(issue);
+        if (nodeUsesWorkspaceAsset(node)) {
+            issues.push({
+                path: `$.graph.nodes.${index}`,
+                code: "workspace_asset_not_portable",
+                message: "This node references a workspace-local Knowledge asset. Replace it with portable input or profile context before exporting.",
+            });
+        }
+    });
+    return { ok: issues.length === 0, issues };
+}
+export function assertPortableWorkflowGraph(manifest) {
+    const result = lintPortableWorkflowGraph(manifest);
+    if (!result.ok)
+        throw new PortableWorkflowDefinitionValidationError(result.issues);
+}
+export function lintPortableWorkflowDefinition(value) {
+    const issues = [];
+    if (!isPortableWorkflowDefinitionV1(value)) {
+        return {
+            ok: false,
+            issues: [{
+                    path: "$",
+                    code: "invalid_workflow_definition",
+                    message: "Expected an oxygen-workflow-definition envelope with definition_version 1 and an oxygen-workflows-v2 manifest.",
+                }],
+        };
+    }
+    issues.push(...lintWorkflowGraphManifest(value.graph).issues.map((issue) => ({
+        ...issue,
+        path: issue.path === "$" ? "$.graph" : `$.graph${issue.path.slice(1)}`,
+    })));
+    issues.push(...lintPortableWorkflowGraph(value.graph).issues);
+    const toolNodes = new Map(value.graph.nodes
+        .filter((node) => node.kind === "tool")
+        .map((node) => [node.id, node]));
+    const seenBindings = new Set();
+    const seenNodes = new Set();
+    for (const [index, requirement] of value.requirements.connections.entries()) {
+        const path = `$.requirements.connections.${index}`;
+        if (!isRecord(requirement)) {
+            issues.push({ path, code: "invalid_connection_requirement", message: "Connection requirement must be an object." });
+            continue;
+        }
+        if (!isNonEmptyString(requirement.binding_id)
+            || !isNonEmptyString(requirement.integration_id)
+            || !Array.isArray(requirement.node_ids)
+            || requirement.node_ids.length === 0
+            || requirement.node_ids.some((nodeId) => !isNonEmptyString(nodeId))) {
+            issues.push({ path, code: "invalid_connection_requirement", message: "Connection requirement needs binding_id, integration_id, and at least one node_id." });
+            continue;
+        }
+        if (seenBindings.has(requirement.binding_id)) {
+            issues.push({ path: `${path}.binding_id`, code: "duplicate_connection_requirement", message: `Binding '${requirement.binding_id}' is duplicated.` });
+        }
+        seenBindings.add(requirement.binding_id);
+        for (const nodeId of requirement.node_ids) {
+            if (seenNodes.has(nodeId)) {
+                issues.push({ path: `${path}.node_ids`, code: "duplicate_connection_requirement", message: `Node '${nodeId}' belongs to more than one connection requirement.` });
+            }
+            seenNodes.add(nodeId);
+            if (!toolNodes.has(nodeId)) {
+                issues.push({ path: `${path}.node_ids`, code: "connection_requirement_mismatch", message: `Connection requirement points to missing or non-tool node '${nodeId}'.` });
+            }
+        }
+    }
+    for (const node of toolNodes.values()) {
+        if (node.connection_id !== undefined) {
+            issues.push({
+                path: `$.graph.nodes.${value.graph.nodes.indexOf(node)}.connection_id`,
+                code: "source_connection_id_present",
+                message: "Portable definitions must not contain organization-local connection ids.",
+            });
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
+export function assertPortableWorkflowDefinition(value) {
+    const result = lintPortableWorkflowDefinition(value);
+    if (!result.ok)
+        throw new PortableWorkflowDefinitionValidationError(result.issues);
+}
+export function buildPortableWorkflowDefinition(input) {
+    assertPortableWorkflowGraph(input.manifest);
+    const manifest = cloneJson(input.manifest);
+    const grouped = new Map();
+    manifest.nodes = manifest.nodes.map((node) => {
+        if (node.kind !== "tool")
+            return node;
+        if (node.connection_id) {
+            const source = input.sourceConnections?.[node.connection_id];
+            if (!source || !isNonEmptyString(source.integrationId)) {
+                throw new PortableWorkflowDefinitionValidationError([{
+                        path: `$.graph.nodes.${manifest.nodes.indexOf(node)}.connection_id`,
+                        code: "source_connection_metadata_required",
+                        message: `Tool node '${node.id}' is pinned. Export must resolve its source integration account before removing the organization-local connection id.`,
+                    }]);
+            }
+            const current = grouped.get(node.connection_id);
+            if (current)
+                current.nodeIds.push(node.id);
+            else
+                grouped.set(node.connection_id, { source, nodeIds: [node.id] });
+        }
+        const { connection_id: _connectionId, ...portableNode } = node;
+        return portableNode;
+    });
+    const integrationCounts = new Map();
+    const connections = [...grouped.values()].map(({ source, nodeIds }) => {
+        const next = (integrationCounts.get(source.integrationId) ?? 0) + 1;
+        integrationCounts.set(source.integrationId, next);
+        const accountHint = {
+            ...(isNonEmptyString(source.externalAccountId) ? { external_account_id: source.externalAccountId } : {}),
+            ...(isNonEmptyString(source.displayName) ? { display_name: source.displayName } : {}),
+            ...(isNonEmptyString(source.authScheme) ? { auth_scheme: source.authScheme } : {}),
+        };
+        return {
+            binding_id: `connection.${source.integrationId}.${next}`,
+            integration_id: source.integrationId,
+            node_ids: nodeIds,
+            ...(Object.keys(accountHint).length > 0 ? { account_hint: accountHint } : {}),
+        };
+    });
+    manifest.workflow = { ...manifest.workflow, status: "disabled" };
+    manifest.trigger = stripTriggerAuthority(manifest.trigger ?? { type: "api" });
+    manifest.source_hash = hashPortableWorkflowGraphManifest(manifest);
+    return {
+        kind: "oxygen-workflow-definition",
+        definition_version: PORTABLE_WORKFLOW_DEFINITION_VERSION,
+        graph: manifest,
+        requirements: { connections },
+        exported_at: (input.exportedAt ?? new Date()).toISOString(),
+        ...(input.exportedFrom ? { exported_from: cloneJson(input.exportedFrom) } : {}),
+        compiler_version: PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION,
+    };
+}
+export function materializePortableWorkflowDefinition(input) {
+    assertPortableWorkflowDefinition(input.definition);
+    const definition = input.definition;
+    const manifest = cloneJson(definition.graph);
+    const bindings = input.connectionBindings ?? {};
+    const knownBindingIds = new Set(definition.requirements.connections.map((item) => item.binding_id));
+    const unknownBindings = Object.keys(bindings).filter((bindingId) => !knownBindingIds.has(bindingId));
+    if (unknownBindings.length > 0) {
+        throw new PortableWorkflowDefinitionValidationError(unknownBindings.map((bindingId) => ({
+            path: `$.connection_bindings.${bindingId}`,
+            code: "unknown_connection_binding",
+            message: `No connection requirement exists for binding '${bindingId}'.`,
+        })));
+    }
+    const nodeConnections = new Map();
+    const missing = [];
+    for (const requirement of definition.requirements.connections) {
+        const connectionId = bindings[requirement.binding_id]?.trim();
+        if (!connectionId) {
+            missing.push({
+                path: `$.connection_bindings.${requirement.binding_id}`,
+                code: "connection_binding_required",
+                message: `Bind '${requirement.binding_id}' (${requirement.integration_id}) to one active destination connection before import.`,
+            });
+            continue;
+        }
+        for (const nodeId of requirement.node_ids)
+            nodeConnections.set(nodeId, connectionId);
+    }
+    if (missing.length > 0)
+        throw new PortableWorkflowDefinitionValidationError(missing);
+    manifest.nodes = manifest.nodes.map((node) => {
+        if (node.kind !== "tool")
+            return node;
+        const connectionId = nodeConnections.get(node.id);
+        return connectionId ? { ...node, connection_id: connectionId } : node;
+    });
+    const workflowId = input.workflowId?.trim() || manifest.workflow.id;
+    const workflowName = input.workflowName?.trim() || manifest.workflow.name;
+    manifest.workflow = { id: workflowId, name: workflowName, status: "disabled" };
+    manifest.trigger = stripTriggerAuthority(manifest.trigger ?? { type: "api" });
+    if (manifest.trigger?.type === "webhook") {
+        const triggerId = input.webhookTriggerId?.trim() || `${workflowId}-webhook`;
+        manifest.trigger = { ...manifest.trigger, trigger_id: triggerId, status: "disabled" };
+    }
+    manifest.created_at = (input.importedAt ?? new Date()).toISOString();
+    manifest.source_hash = hashPortableWorkflowGraphManifest(manifest);
+    return manifest;
+}

package/node_modules/@oxygen/workflows/dist/usage-estimate.js

@@ -30,6 +30,11 @@ export function estimateWorkflowRunAutomationActionsFloor(manifest) {
     const graph = readWorkflowGraph(manifest);
     if (graph)
         return estimateWorkflowGraphActionsFloor(graph);
+    return estimateRecipeActionsFloor(manifest);
+}
+/** One action for entering the durable recipe plus one per statically visible
+ * checkpoint/tool. Runtime code may emit more, so this remains a floor. */
+function estimateRecipeActionsFloor(manifest) {
     const visualPlan = isRecord(manifest.visual_plan) ? manifest.visual_plan : null;
     const visualSteps = Array.isArray(visualPlan?.steps) ? visualPlan.steps : [];
     const checkpointCount = visualSteps.filter((step) => isRecord(step) && (step.kind !== "branch" || typeof step.checkpoint_id === "string")).length;
@@ -56,7 +61,8 @@ function manifestHasDynamicRuntimeActions(manifest) {
     const graph = readWorkflowGraph(manifest);
     if (!graph)
         return false;
-    return graph.nodes.some((node) => node.kind === "loop" && !node.disabled && declaredLoopIterations(node.maxIterations) === null);
+    return graph.nodes.some((node) => node.hasRecipe
+        || (node.kind === "loop" && !node.disabled && declaredLoopIterations(node.maxIterations) === null));
 }
 function manifestWritesRowsPerRun(manifest) {
     if (!isRecord(manifest))
@@ -67,7 +73,8 @@ function manifestWritesRowsPerRun(manifest) {
     }
     const graph = readWorkflowGraph(manifest);
     if (graph) {
-        return graph.nodes.some((node) => node.kind === "tool" && typeof node.tool === "string" && ROW_FANOUT_TOOL_IDS.has(node.tool));
+        return graph.nodes.some((node) => (node.kind === "tool" && typeof node.tool === "string" && ROW_FANOUT_TOOL_IDS.has(node.tool))
+            || node.recipeTools.some((tool) => ROW_FANOUT_TOOL_IDS.has(tool)));
     }
     const toolsUsed = Array.isArray(manifest.tools_used) ? manifest.tools_used : [];
     return toolsUsed.some((tool) => typeof tool === "string" && ROW_FANOUT_TOOL_IDS.has(tool));
@@ -81,12 +88,18 @@ function readWorkflowGraph(manifest) {
             continue;
         if (typeof raw.id !== "string" || !raw.id || typeof raw.kind !== "string")
             continue;
+        const recipe = isRecord(raw.recipe) ? raw.recipe : null;
         nodes.push({
             id: raw.id,
             kind: raw.kind,
             disabled: raw.disabled === true,
             tool: raw.tool,
             maxIterations: raw.max_iterations,
+            recipeTools: recipe && Array.isArray(recipe.tools_used)
+                ? recipe.tools_used.filter((tool) => typeof tool === "string")
+                : [],
+            hasRecipe: recipe !== null,
+            recipeActionsFloor: recipe ? estimateRecipeActionsFloor(recipe) : 0,
         });
     }
     const edges = manifest.edges.flatMap((raw) => {
@@ -162,9 +175,10 @@ function estimateWorkflowGraphActionsFloor(graph) {
     for (const node of graph.nodes) {
         if (node.disabled || skipped.has(node.id))
             continue;
-        if (!workflowGraphNodeKindBills(node.kind))
+        if (!workflowGraphNodeKindBills(node.kind) && !node.hasRecipe)
             continue;
-        floor += multipliers.get(node.id) ?? 1;
+        const ownFloor = node.hasRecipe ? node.recipeActionsFloor : 1;
+        floor += ownFloor * (multipliers.get(node.id) ?? 1);
     }
     // Nested caps multiply, and two large ones overflow Number's exact range;
     // clamping keeps every downstream product (runs x floor) a finite number.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.696.2",
+  "version": "1.717.1",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",