@oxygen-agent/cli 1.696.2 → 1.717.1

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

@@ -10,7 +10,7 @@
 // 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";
+import { MAX_WORKFLOW_NODE_RETRY_ATTEMPTS, MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS, PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION, PORTABLE_WORKFLOW_DEFINITION_VERSION, 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'.",
@@ -122,6 +122,15 @@ const nodeSchema = {
             description: "tool nodes: parameter name -> value ref.",
             additionalProperties: valueRefSchema,
         },
+        payload_source: {
+            type: "string",
+            description: "Imported v1 tool nodes only: sandboxed payload function preserved until converted to mapped params.",
+        },
+        legacy_context: {
+            type: "string",
+            enum: ["v1"],
+            description: "Imported v1 source receives the original raw-step-output context shape.",
+        },
         when: conditionSchema,
         cases: {
             type: "array",
@@ -155,6 +164,16 @@ const nodeSchema = {
         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." },
+        recipe: {
+            type: "object",
+            description: "Imported durable-recipe code nodes: the complete executable recipe manifest. Exactly one of run_source or recipe is required.",
+            additionalProperties: true,
+        },
+        configuration: {
+            type: "object",
+            description: "Imported durable-recipe code nodes: configuration field -> value ref.",
+            additionalProperties: valueRefSchema,
+        },
         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 },
     },
@@ -203,3 +222,63 @@ export const workflowGraphManifestSchema = {
     },
     required: ["manifest_version", "workflow", "nodes", "edges", "source_hash", "compiler_version"],
 };
+export const portableWorkflowDefinitionSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "OXYGEN Portable Workflow Definition",
+    description: "A portable, editable oxygen-workflows-v2 graph. It never contains source-workspace connection UUIDs or standing trigger authority.",
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        kind: { const: "oxygen-workflow-definition" },
+        definition_version: { const: PORTABLE_WORKFLOW_DEFINITION_VERSION },
+        graph: workflowGraphManifestSchema,
+        requirements: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                connections: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            binding_id: { type: "string", minLength: 1 },
+                            integration_id: { type: "string", minLength: 1 },
+                            node_ids: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+                            account_hint: {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    external_account_id: { type: "string" },
+                                    display_name: { type: "string" },
+                                    auth_scheme: { type: "string" },
+                                },
+                            },
+                        },
+                        required: ["binding_id", "integration_id", "node_ids"],
+                    },
+                },
+            },
+            required: ["connections"],
+        },
+        exported_at: { type: "string", format: "date-time" },
+        exported_from: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                workflow_slug: { type: "string" },
+                revision_version: { type: "integer", minimum: 1 },
+                oxygen_version: { type: "string" },
+            },
+        },
+        compiler_version: { const: PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION },
+    },
+    required: [
+        "kind",
+        "definition_version",
+        "graph",
+        "requirements",
+        "exported_at",
+        "compiler_version",
+    ],
+};

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

@@ -204,8 +204,15 @@ export function remapNodeRefs(node, ids) {
                         request: Object.fromEntries(Object.entries(node.request).map(([key, ref]) => [key, remapValueRef(ref, ids)])),
                     }),
             };
+        case "code":
+            return node.configuration === undefined
+                ? node
+                : {
+                    ...node,
+                    configuration: Object.fromEntries(Object.entries(node.configuration).map(([key, ref]) => [key, remapValueRef(ref, ids)])),
+                };
         default:
-            // trigger, merge, code — no bindings. A `code` node's source is JavaScript
+            // trigger, merge — no bindings. A source code node's 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/types.d.ts

@@ -1,6 +1,8 @@
-import type { JsonSchema, WorkflowMode, WorkflowStatus, WorkflowStepEffect, WorkflowTriggerManifest } from "../index.js";
+import type { JsonSchema, RecipeManifest, WorkflowMode, WorkflowStatus, WorkflowStepEffect, WorkflowTriggerManifest } from "../index.js";
 export declare const WORKFLOW_GRAPH_MANIFEST_VERSION = 2;
 export declare const WORKFLOW_GRAPH_COMPILER_VERSION = "oxygen-workflows-v2";
+export declare const PORTABLE_WORKFLOW_DEFINITION_VERSION = 1;
+export declare const PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION = "oxygen-workflow-definition-v1";
 export declare const RESERVED_NODE_IDS: ReadonlySet<string>;
 export declare const LOOP_BODY_HANDLE = "loop_body";
 export declare const LOOP_DONE_HANDLE = "loop_done";
@@ -144,6 +146,15 @@ export type WorkflowGraphNode =
     /** Per-node managed-credit ceiling, same semantics as v1 tool steps. */
     max_credits?: number;
     params: Record<string, WorkflowValueRef>;
+    /**
+     * Lossless bridge for a v1 code-authored tool step. The canvas cannot infer
+     * declarative field bindings from arbitrary JavaScript, so imported steps
+     * keep their sandboxed payload function until the author explicitly replaces
+     * it with schema-mapped `params` in the inspector.
+     */
+    payload_source?: string;
+    /** Imported payload functions receive the original v1 `{ input, steps, mode }` shape. */
+    legacy_context?: "v1";
 })
 /** Passes execution on only when `when` holds. */
  | (WorkflowGraphNodeBase & {
@@ -212,10 +223,21 @@ export type WorkflowGraphNode =
     reason?: WorkflowValueRef;
     request?: Record<string, WorkflowValueRef>;
 })
-/** Sandboxed transform source, the v2 spelling of a v1 transform step. */
+/**
+ * Sandboxed transform source, or an imported durable recipe bundle.
+ *
+ * A recipe is deliberately ONE executable node: its bundle is the runtime
+ * authority, while visual_plan remains inspectable metadata. Turning those
+ * descriptive checkpoints into editable graph nodes would make the canvas lie
+ * about what deletion or rewiring actually changes.
+ */
  | (WorkflowGraphNodeBase & {
     kind: "code";
-    run_source: string;
+    run_source?: string;
+    recipe?: RecipeManifest;
+    configuration?: Record<string, WorkflowValueRef>;
+    /** Imported v1 source reads raw step outputs rather than v2 output envelopes. */
+    legacy_context?: "v1";
 })
 /** Calls another workflow as a child run. */
  | (WorkflowGraphNodeBase & {
@@ -259,11 +281,58 @@ export type WorkflowGraphManifest = {
     compiler_version: typeof WORKFLOW_GRAPH_COMPILER_VERSION;
     created_at: string;
 };
+/**
+ * A connection requirement in a portable workflow definition.
+ *
+ * Connection UUIDs are organization-local credentials and never travel in the
+ * artifact. Only exact source-account pins appear here. Unpinned provider nodes
+ * and Oxygen-managed nodes remain absent and keep ordinary workspace-default or
+ * managed resolution in the destination.
+ */
+export type PortableWorkflowConnectionRequirement = {
+    /** Artifact-local key used by import flags and UI controls. */
+    binding_id: string;
+    integration_id: string;
+    /** Tool nodes that shared this exact source account pin. */
+    node_ids: string[];
+    /** Display/matching hints only; never a source connection UUID or secret. */
+    account_hint?: {
+        external_account_id?: string;
+        display_name?: string;
+        auth_scheme?: string;
+    };
+};
+/**
+ * Portable, editable representation of one deterministic workflow graph.
+ *
+ * This is deliberately narrower than a Blueprint (which may also carry tables,
+ * prompts, and column grafts) and narrower than AnyWorkflowManifest (which also
+ * includes legacy source-authored generations). A portable definition always
+ * opens as the same v2 graph the worker executes.
+ */
+export type PortableWorkflowDefinitionV1 = {
+    kind: "oxygen-workflow-definition";
+    definition_version: typeof PORTABLE_WORKFLOW_DEFINITION_VERSION;
+    /** Named `graph`, not `manifest`: old CLIs treat `{manifest}` as directly applyable. */
+    graph: WorkflowGraphManifest;
+    requirements: {
+        connections: PortableWorkflowConnectionRequirement[];
+    };
+    exported_at: string;
+    exported_from?: {
+        workflow_slug?: string;
+        revision_version?: number;
+        oxygen_version?: string;
+    };
+    compiler_version: typeof PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION;
+};
 /**
  * Shape gate only — enough to route a manifest to the v2 code path. Full
  * structural validation is the linter's job, not this guard's.
  */
 export declare function isWorkflowGraphManifest(value: unknown): value is WorkflowGraphManifest;
+/** Shape gate only; use the portable-definition linter before importing. */
+export declare function isPortableWorkflowDefinitionV1(value: unknown): value is PortableWorkflowDefinitionV1;
 export declare function isTriggerNode(node: WorkflowGraphNode): node is WorkflowGraphNodeOfKind<"trigger">;
 export declare function isToolNode(node: WorkflowGraphNode): node is WorkflowGraphNodeOfKind<"tool">;
 export declare function isSwitchNode(node: WorkflowGraphNode): node is WorkflowGraphNodeOfKind<"switch">;

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

@@ -1,5 +1,7 @@
 export const WORKFLOW_GRAPH_MANIFEST_VERSION = 2;
 export const WORKFLOW_GRAPH_COMPILER_VERSION = "oxygen-workflows-v2";
+export const PORTABLE_WORKFLOW_DEFINITION_VERSION = 1;
+export const PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION = "oxygen-workflow-definition-v1";
 // Node ids become keys on the runtime scope object (`steps.<id>.output`), exactly
 // as v1 step ids become keys on ctx.steps. The same JavaScript-internals collision
 // applies: a node named `__proto__` would silently lose its output.
@@ -73,6 +75,16 @@ export function isWorkflowGraphManifest(value) {
         && Array.isArray(value.nodes)
         && Array.isArray(value.edges);
 }
+/** Shape gate only; use the portable-definition linter before importing. */
+export function isPortableWorkflowDefinitionV1(value) {
+    return isRecord(value)
+        && value.kind === "oxygen-workflow-definition"
+        && value.definition_version === PORTABLE_WORKFLOW_DEFINITION_VERSION
+        && value.compiler_version === PORTABLE_WORKFLOW_DEFINITION_COMPILER_VERSION
+        && isWorkflowGraphManifest(value.graph)
+        && isRecord(value.requirements)
+        && Array.isArray(value.requirements.connections);
+}
 function isNodeOfKind(node, kind) {
     return node.kind === kind;
 }

package/node_modules/@oxygen/workflows/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./event-dispatch.js";
 export type { CanonicalWorkflowToolEffect } from "./tool-effects.js";
 export * from "./graph/index.js";
 export * from "./graph/lint.js";
+export * from "./portable.js";
 export declare const WORKFLOW_MANIFEST_VERSION = 1;
 export declare const WORKFLOW_COMPILER_VERSION = "oxygen-workflows-v1";
 export declare const DURABLE_RECIPE_COMPILER_VERSION = "oxygen-recipes-v2";
@@ -146,6 +147,13 @@ export type RecipeManifest = {
     };
     trigger?: WorkflowTriggerManifest;
     input_schema?: JsonSchema;
+    /**
+     * Operator-editable recipe settings, distinct from the per-delivery trigger
+     * payload. When present, the canvas renders this schema with the same mapped
+     * field controls used by tool/action configuration.
+     */
+    configuration_schema?: JsonSchema;
+    configuration?: Record<string, unknown>;
     runtime: RecipeRuntime;
     bundle: string;
     bundle_format: "esm";
@@ -392,6 +400,8 @@ export declare function buildRecipeManifest(input: {
     status?: WorkflowStatus;
     trigger?: WorkflowTriggerManifest;
     inputSchema?: JsonSchema;
+    configurationSchema?: JsonSchema;
+    configuration?: Record<string, unknown>;
     bundle: string;
     toolsUsed: string[];
     visualPlan?: RecipeVisualPlanManifest;
@@ -399,6 +409,12 @@ export declare function buildRecipeManifest(input: {
     sourceHash?: string;
     createdAt?: Date;
 }): RecipeManifest;
+/** Canonical executable identity shared by recipe compilers and repair paths. */
+export declare function hashRecipeSource(input: {
+    bundle: string;
+    configurationSchema?: JsonSchema;
+    configuration?: Record<string, unknown>;
+}): string;
 export declare function validateOptionalMaxCredits(value: unknown, path: string, add: (path: string, code: string, message: string) => void): void;
 export declare function lintWorkflowManifest(// skipcq: JS-R1005
 value: unknown, options?: WorkflowManifestValidationOptions): WorkflowLintResult;

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as vm from "node:vm"; // skipcq: JS-C1003
 import { isWorkflowGraphManifest } from "./graph/types.js";
+import { lintWorkflowGraphManifest } from "./graph/lint.js";
 export * from "./usage-estimate.js";
 // Pure event-dispatch semantics, shared by the apps/web and apps/worker event
 // dispatchers so the filter gate, idempotency rule, and delivery verdict cannot
@@ -11,6 +12,7 @@ export * from "./event-dispatch.js";
 // scanner below — so it is re-exported here, from the node entry point only.
 export * from "./graph/index.js";
 export * from "./graph/lint.js";
+export * from "./portable.js";
 export const WORKFLOW_MANIFEST_VERSION = 1;
 export const WORKFLOW_COMPILER_VERSION = "oxygen-workflows-v1";
 export const DURABLE_RECIPE_COMPILER_VERSION = "oxygen-recipes-v2";
@@ -278,7 +280,13 @@ export function buildRecipeManifest(input) {
     if (typeof bundle !== "string" || bundle.length === 0) {
         throw new Error("Recipe bundle source is required.");
     }
-    const sourceHash = input.sourceHash ?? hashWorkflowSource(bundle);
+    const sourceHash = input.sourceHash ?? hashRecipeSource({
+        bundle,
+        ...(input.configurationSchema !== undefined
+            ? { configurationSchema: input.configurationSchema }
+            : {}),
+        ...(input.configuration !== undefined ? { configuration: input.configuration } : {}),
+    });
     const manifest = {
         manifest_version: WORKFLOW_MANIFEST_VERSION,
         workflow: {
@@ -288,6 +296,8 @@ export function buildRecipeManifest(input) {
         },
         ...(input.trigger ? { trigger: input.trigger } : {}),
         ...(input.inputSchema ? { input_schema: input.inputSchema } : {}),
+        ...(input.configurationSchema ? { configuration_schema: input.configurationSchema } : {}),
+        ...(input.configuration ? { configuration: input.configuration } : {}),
         runtime: "durable",
         bundle,
         bundle_format: "esm",
@@ -300,6 +310,20 @@ export function buildRecipeManifest(input) {
     };
     return manifest;
 }
+/** Canonical executable identity shared by recipe compilers and repair paths. */
+export function hashRecipeSource(input) {
+    // Preserve the historical bundle-only identity for recipes that have no
+    // editable configuration. Configuration-bearing revisions include schema +
+    // values because either can change the behavior of the same bundle source.
+    if (input.configurationSchema === undefined && input.configuration === undefined) {
+        return hashWorkflowSource(input.bundle);
+    }
+    return hashWorkflowSource(JSON.stringify({
+        bundle: input.bundle,
+        configuration_schema: input.configurationSchema ?? null,
+        configuration: input.configuration ?? null,
+    }, workflowJsonReplacer));
+}
 // Shared positive-finite validator for the optional per-run / per-step
 // max_credits caps (Gap 2). `undefined` is valid (no cap); anything else must be
 // a positive finite number, or lint rejects the manifest.
@@ -314,6 +338,9 @@ export function validateOptionalMaxCredits(value, path, add) {
 }
 export function lintWorkflowManifest(// skipcq: JS-R1005
 value, options = {}) {
+    if (isWorkflowGraphManifest(value)) {
+        return lintWorkflowGraphManifest(value, options);
+    }
     if (isRecord(value)
         && typeof value.compiler_version === "string"
         && value.compiler_version.startsWith("oxygen-recipes-")) {
@@ -432,7 +459,7 @@ value, options = {}) {
                     if (resolveEffect) {
                         const canonicalEffect = resolveEffect(step.tool);
                         if (canonicalEffect !== null && step.effect !== canonicalEffect) {
-                            add(`${path}.effect`, "tool_effect_mismatch", `Tool '${step.tool}' has canonical effect '${canonicalEffect}', not '${String(step.effect)}'.`);
+                            add(`${path}.effect`, "tool_effect_mismatch", `Tool '${step.tool}' has canonical effect '${canonicalEffect}', not '${String(step.effect)}'. Set step.effect to '${canonicalEffect}'.`);
                         }
                     }
                 }
@@ -504,6 +531,17 @@ value, options = {}) {
     }
     if (value.trigger !== undefined)
         validateTrigger(value.trigger, "$.trigger", add);
+    if (value.configuration_schema !== undefined && !isRecord(value.configuration_schema)) {
+        add("$.configuration_schema", "invalid_configuration_schema", "Recipe configuration_schema must be a JSON Schema object.");
+    }
+    if (value.configuration !== undefined && !isRecord(value.configuration)) {
+        add("$.configuration", "invalid_configuration", "Recipe configuration must be an object.");
+    }
+    else if (isRecord(value.configuration_schema)) {
+        for (const issue of validateJsonSchemaValue(isRecord(value.configuration) ? value.configuration : {}, value.configuration_schema, "$.configuration")) {
+            add(issue.path, issue.code, issue.message);
+        }
+    }
     if (!isNonEmptyString(value.bundle)) {
         add("$.bundle", "missing_bundle", "Recipe bundle is required.");
     }
@@ -1756,7 +1794,11 @@ export function workflowManifestCanInvokeTool(manifest) {
     const viaRecipe = Array.isArray(manifest.tools_used)
         && manifest.tools_used.some((toolId) => isNonEmptyString(toolId));
     const viaGraph = Array.isArray(manifest.nodes)
-        && manifest.nodes.some((node) => isRecord(node) && (node.kind === "tool" || node.kind === "workflow"));
+        && manifest.nodes.some((node) => isRecord(node) && (node.kind === "tool"
+            || node.kind === "workflow"
+            || (isRecord(node.recipe)
+                && Array.isArray(node.recipe.tools_used)
+                && node.recipe.tools_used.some((toolId) => isNonEmptyString(toolId)))));
     const viaSteps = Array.isArray(manifest.steps)
         && manifest.steps.some((step) => isRecord(step) && step.kind === "tool");
     return viaRecipe || viaGraph || viaSteps;

package/node_modules/@oxygen/workflows/dist/portable.d.ts

@@ -0,0 +1,43 @@
+import { type PortableWorkflowDefinitionV1, type WorkflowGraphManifest } from "./graph/types.js";
+export type PortableWorkflowDefinitionIssue = {
+    path: string;
+    code: string;
+    message: string;
+};
+export type PortableWorkflowDefinitionLintResult = {
+    ok: boolean;
+    issues: PortableWorkflowDefinitionIssue[];
+};
+export declare class PortableWorkflowDefinitionValidationError extends Error {
+    readonly issues: PortableWorkflowDefinitionIssue[];
+    constructor(issues: PortableWorkflowDefinitionIssue[]);
+}
+type ExportedFrom = NonNullable<PortableWorkflowDefinitionV1["exported_from"]>;
+export type PortableWorkflowSourceConnection = {
+    integrationId: string;
+    externalAccountId?: string | null;
+    displayName?: string | null;
+    authScheme?: string | null;
+};
+/** The graph editor and server use this same material rule. */
+export declare function hashPortableWorkflowGraphManifest(manifest: WorkflowGraphManifest): string;
+export declare function lintPortableWorkflowGraph(manifest: unknown): PortableWorkflowDefinitionLintResult;
+export declare function assertPortableWorkflowGraph(manifest: unknown): asserts manifest is WorkflowGraphManifest;
+export declare function lintPortableWorkflowDefinition(value: unknown): PortableWorkflowDefinitionLintResult;
+export declare function assertPortableWorkflowDefinition(value: unknown): asserts value is PortableWorkflowDefinitionV1;
+export declare function buildPortableWorkflowDefinition(input: {
+    manifest: unknown;
+    exportedAt?: Date;
+    exportedFrom?: ExportedFrom;
+    /** Source connection metadata keyed by source-only UUID; UUIDs are never serialized. */
+    sourceConnections?: Record<string, PortableWorkflowSourceConnection>;
+}): PortableWorkflowDefinitionV1;
+export declare function materializePortableWorkflowDefinition(input: {
+    definition: unknown;
+    connectionBindings?: Record<string, string>;
+    workflowId?: string;
+    workflowName?: string;
+    webhookTriggerId?: string;
+    importedAt?: Date;
+}): WorkflowGraphManifest;
+export {};