@openapi-flow/langchain 0.0.0-stage → 0.2.0

package/dist/types/reviewable-workflow-planning.d.ts

@@ -0,0 +1,19 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ReviewableWorkflowGraphProposal, ReviewableWorkflowPlanningContext, WorkflowReviewGap, PlannedNativeNode } from '@openapi-flow/core';
+export interface PlanReviewableWorkflowGraphInput extends ReviewableWorkflowPlanningContext {
+    scenario: string;
+    model: BaseChatModel;
+    gaps: WorkflowReviewGap[];
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export type ReviewableWorkflowGraphPlanningFailure = {
+    stage: 'proposal-schema';
+    output: unknown;
+} | {
+    stage: 'graph-validation';
+    output: ReviewableWorkflowGraphOutput;
+};
+export type ReviewableWorkflowGraphOutput = Omit<ReviewableWorkflowGraphProposal, 'nativeNodes' | 'blockedCalls'> & {
+    additionalNativeNodes?: ReviewableWorkflowGraphProposal['nativeNodes'];
+    blockedCalls?: ReviewableWorkflowGraphProposal['blockedCalls'];
+};

package/dist/types/reviewable-workflow-planning.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-orchestration.d.ts

@@ -0,0 +1,23 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ReviewableWorkflowApiMaterial, PlannedNativeNode, WorkflowCapability, WorkflowPlanEdge, WorkflowReviewGap, WorkflowPlanNodeContract } from '@openapi-flow/core';
+export interface PlanWorkflowConnectionsInput {
+    scenario: string;
+    model: BaseChatModel;
+    materials?: ReviewableWorkflowApiMaterial[];
+    capabilities?: WorkflowCapability[];
+    nativeNodes?: PlannedNativeNode[];
+    gaps?: WorkflowReviewGap[];
+    edges?: WorkflowPlanEdge[];
+}
+export interface OrchestrateWorkflowInput extends Omit<PlanWorkflowConnectionsInput, 'nativeNodes'> {
+    workflowId: string;
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export interface WorkflowConnectionMaterials {
+    materials: ReviewableWorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+    nativeNodes: PlannedNativeNode[];
+    gaps: WorkflowReviewGap[];
+    edges: WorkflowPlanEdge[];
+    contracts: WorkflowPlanNodeContract[];
+}

package/dist/types/workflow-orchestration.js

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-planning.d.ts

@@ -0,0 +1,23 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowApiMaterial, WorkflowCapability, WorkflowGraphProposal, PlannedNativeNode } from '@openapi-flow/core';
+export interface PlanWorkflowGraphInput {
+    scenario: string;
+    model: BaseChatModel;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export interface PreparedNativeNodeMaterial extends PlannedNativeNode {
+    inputPorts: string[];
+    outputPorts: string[];
+}
+export type WorkflowGraphOutput = Omit<WorkflowGraphProposal, 'nativeNodes'> & {
+    additionalNativeNodes: PlannedNativeNode[];
+};
+export type WorkflowGraphPlanningFailure = {
+    stage: 'proposal-schema';
+    output: unknown;
+} | {
+    stage: 'graph-validation';
+    output: WorkflowGraphOutput;
+};

package/dist/types/workflow-planning.js

@@ -0,0 +1 @@
+export {};

package/dist/workflow/assemble-native-node-materials.d.ts

@@ -0,0 +1,3 @@
+import type { PlannedNativeNode } from '@openapi-flow/core';
+/** Prepared values belong to the host; model output contains only additions. */
+export declare function assembleNativeNodeMaterials(prepared: PlannedNativeNode[], additional: PlannedNativeNode[]): PlannedNativeNode[];

package/dist/workflow/assemble-native-node-materials.js

@@ -0,0 +1,8 @@
+/** Prepared values belong to the host; model output contains only additions. */
+export function assembleNativeNodeMaterials(prepared, additional) {
+    const preparedIds = new Set(prepared.map((node) => node.id));
+    for (const node of additional)
+        if (preparedIds.has(node.id))
+            throw new Error(`additionalNativeNodes[${node.id}] duplicates preparedNativeNodes; return only new nodes, not existing materials`);
+    return [...prepared, ...additional];
+}

package/dist/workflow/complete-reviewable-workflow-graph-proposal.d.ts

@@ -0,0 +1,4 @@
+import type { ReviewableWorkflowGraphProposal } from '@openapi-flow/core';
+import type { ReviewableWorkflowGraphOutput } from '../types/reviewable-workflow-planning.js';
+/** Complete only fields fixed by the supplied planning context, not model errors. */
+export declare function completeReviewableWorkflowGraphProposal(output: ReviewableWorkflowGraphOutput, capabilityCount: number, readyCallCount: number): ReviewableWorkflowGraphProposal;

package/dist/workflow/complete-reviewable-workflow-graph-proposal.js

@@ -0,0 +1,13 @@
+/** Complete only fields fixed by the supplied planning context, not model errors. */
+export function completeReviewableWorkflowGraphProposal(output, capabilityCount, readyCallCount) {
+    if (capabilityCount > 0 && output.additionalNativeNodes === undefined)
+        throw new Error('model reviewable workflow graph.additionalNativeNodes is required');
+    if (readyCallCount > 0 && output.blockedCalls === undefined)
+        throw new Error('model reviewable workflow graph.blockedCalls is required');
+    const { additionalNativeNodes, ...proposal } = output;
+    return {
+        ...proposal,
+        nativeNodes: capabilityCount === 0 ? [] : additionalNativeNodes,
+        blockedCalls: readyCallCount === 0 ? [] : output.blockedCalls,
+    };
+}

package/dist/workflow/create-prepared-native-node-materials.d.ts

@@ -0,0 +1,4 @@
+import type { PlannedNativeNode, WorkflowCapability } from '@openapi-flow/core';
+import type { PreparedNativeNodeMaterial } from '../types/workflow-planning.js';
+/** Expose existing implementation-owned ports, not descriptions for the model to guess. */
+export declare function createPreparedNativeNodeMaterials(nodes: PlannedNativeNode[], capabilities: WorkflowCapability[]): PreparedNativeNodeMaterial[];

package/dist/workflow/create-prepared-native-node-materials.js

@@ -0,0 +1,15 @@
+import { parseNativeNodeParameters } from '@openapi-flow/core';
+/** Expose existing implementation-owned ports, not descriptions for the model to guess. */
+export function createPreparedNativeNodeMaterials(nodes, capabilities) {
+    return nodes.map((planned) => {
+        const capability = capabilities.find((item) => item.name === planned.capability);
+        if (!capability)
+            throw new Error(`prepared node ${planned.id}: unknown capability ${planned.capability}`);
+        const parameters = parseNativeNodeParameters(planned, capability);
+        return {
+            ...planned,
+            inputPorts: capability.inputPorts(parameters),
+            outputPorts: capability.outputPorts(parameters),
+        };
+    });
+}

package/dist/workflow/native-node-planning-error.d.ts

@@ -0,0 +1,5 @@
+import type { NativeNodePlanningFailure } from '../types/native-node-planning.js';
+export declare class NativeNodePlanningError extends Error {
+    readonly failure: NativeNodePlanningFailure;
+    constructor(failure: NativeNodePlanningFailure, cause: Error);
+}

package/dist/workflow/native-node-planning-error.js

@@ -0,0 +1,10 @@
+export class NativeNodePlanningError extends Error {
+    failure;
+    constructor(failure, cause) {
+        super(`Native node planning failed at ${failure.stage}: ${cause.message}`, {
+            cause,
+        });
+        this.name = 'NativeNodePlanningError';
+        this.failure = failure;
+    }
+}

package/dist/workflow/orchestrate-workflow.d.ts

@@ -0,0 +1,4 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { OrchestrateWorkflowInput } from '../types/workflow-orchestration.js';
+/** Optional material groups mean absence, never an implicit capability registry. */
+export declare function orchestrateWorkflow(input: OrchestrateWorkflowInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/orchestrate-workflow.js

@@ -0,0 +1,31 @@
+import { planNativeNodes } from './plan-native-nodes.js';
+import { planWorkflowConnections } from './plan-workflow-connections.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
+/** Optional material groups mean absence, never an implicit capability registry. */
+export async function orchestrateWorkflow(input) {
+    if (!input.workflowId?.trim())
+        throw new Error('orchestrateWorkflow.workflowId is required');
+    prepareWorkflowConnectionMaterials({
+        ...input,
+        nativeNodes: input.preparedNativeNodes,
+    });
+    const nativePlan = await planNativeNodes({
+        planId: `${input.workflowId}-native`,
+        scenario: input.scenario,
+        model: input.model,
+        capabilities: input.capabilities,
+        preparedNativeNodes: input.preparedNativeNodes,
+        apiMaterials: input.materials?.map((material) => ({
+            callId: material.status === 'ready'
+                ? material.arguments.callId
+                : material.callId,
+            operation: material.operation,
+        })),
+    });
+    return planWorkflowConnections({
+        ...input,
+        nativeNodes: assembleNativeNodeMaterials(input.preparedNativeNodes ?? [], nativePlan.nativeNodes),
+        gaps: [...(input.gaps ?? []), ...nativePlan.gaps],
+    });
+}

package/dist/workflow/plan-native-nodes.d.ts

@@ -0,0 +1,2 @@
+import type { NativeNodePlan, PlanNativeNodesInput } from '../types/native-node-planning.js';
+export declare function planNativeNodes(input: PlanNativeNodesInput): Promise<NativeNodePlan>;

package/dist/workflow/plan-native-nodes.js

@@ -0,0 +1,99 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { createNativeOutputContracts, createWorkflowPlanningCapabilities, validateNativeApiResponseReferences, } from '@openapi-flow/core';
+import { createNativeNodePlanSchema } from '../schemas/native-node-plan-schema.js';
+import { nativeNodePlanningPrompt } from '../prompts/native-node-planning-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+export async function planNativeNodes(input) {
+    assertSelectionInput(input.scenario, input.model);
+    if (!input.planId?.trim())
+        throw new Error('planNativeNodes.planId is required');
+    const capabilities = input.capabilities ?? [];
+    const apiMaterials = input.apiMaterials ?? [];
+    const prepared = input.preparedNativeNodes ?? [];
+    createNativeOutputContracts({ nativeNodes: prepared, capabilities });
+    const apiIds = apiMaterials.map((material) => material.callId);
+    const existingIds = [...apiIds, ...prepared.map((node) => node.id)];
+    if (existingIds.some((id) => !id.trim()) ||
+        new Set(existingIds).size !== existingIds.length)
+        throw new Error('native planning materials require unique non-empty IDs');
+    validateNativeApiResponseReferences({
+        nativeNodes: prepared,
+        capabilities,
+        apiCallIds: apiIds,
+    });
+    // No registered choice means no native-selection model call, not an inferred registry.
+    if (!capabilities.length)
+        return { nativeNodes: [], gaps: [] };
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities,
+        apiCallIds: apiIds,
+    });
+    const schema = createNativeNodePlanSchema(planningCapabilities);
+    const output = await input.model
+        .withStructuredOutput(z.toJSONSchema(schema), {
+        name: 'plan_native_nodes',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeNodePlanningPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: input.scenario,
+            apiMaterials: apiMaterials.map(({ callId, operation }) => ({
+                callId,
+                key: operation.key,
+                method: operation.method,
+                path: operation.path,
+                operation: operation.operation,
+                effective: operation.effective,
+            })),
+            preparedNativeNodes: createPreparedNativeNodeMaterials(prepared, capabilities),
+            capabilities: planningCapabilities.map((capability) => ({
+                name: capability.name,
+                description: capability.description,
+                parametersSchema: z.toJSONSchema(capability.parametersSchema),
+            })),
+        })),
+    ]);
+    let proposal;
+    try {
+        proposal = parseStructuredOutput(schema, output, 'model native node plan');
+        if (!isDeepStrictEqual(proposal, output))
+            throw new Error('native model schema must validate without defaults, coercion or transformation');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new NativeNodePlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        const nodes = assembleNativeNodeMaterials(prepared, proposal.nativeNodes);
+        if (proposal.nativeNodes.some((node) => apiIds.includes(node.id)))
+            throw new Error('native node plan contains an API callId');
+        createNativeOutputContracts({ nativeNodes: nodes, capabilities });
+        validateNativeApiResponseReferences({
+            nativeNodes: nodes,
+            capabilities,
+            apiCallIds: apiIds,
+        });
+        const gaps = proposal.gaps.map((gap, index) => ({
+            id: `${input.planId}-gap-${index + 1}`,
+            stage: 'workflow-graph',
+            description: gap.description,
+        }));
+        if (gaps.some((gap) => [...existingIds, ...nodes.map((node) => node.id)].includes(gap.id)))
+            throw new Error('native planning gap ID collides with a declared node');
+        return { nativeNodes: proposal.nativeNodes, gaps };
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new NativeNodePlanningError({ stage: 'node-validation', output: proposal }, error);
+    }
+}

package/dist/workflow/plan-reviewable-workflow-graph.d.ts

@@ -0,0 +1,3 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanReviewableWorkflowGraphInput } from '../types/reviewable-workflow-planning.js';
+export declare function planReviewableWorkflowGraph(input: PlanReviewableWorkflowGraphInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/plan-reviewable-workflow-graph.js

@@ -0,0 +1,101 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { z } from 'zod';
+import { createReviewableWorkflowGraphPlan, createNativeOutputContracts, createWorkflowPlanningCapabilities, validateNativeApiResponseReferences, } from '@openapi-flow/core';
+import { completeReviewableWorkflowGraphProposal } from './complete-reviewable-workflow-graph-proposal.js';
+import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { reviewableWorkflowGraphPrompt } from '../prompts/reviewable-workflow-graph-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { ReviewableWorkflowGraphPlanningError } from './reviewable-workflow-graph-planning-error.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+export async function planReviewableWorkflowGraph(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const preparedNativeNodes = input.preparedNativeNodes ?? [];
+    const apiCallIds = input.materials.map((material) => material.status === 'ready' ? material.arguments.callId : material.callId);
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities: input.capabilities,
+        apiCallIds,
+    });
+    validateNativeApiResponseReferences({
+        nativeNodes: preparedNativeNodes,
+        capabilities: input.capabilities,
+        apiCallIds,
+    });
+    const nativeOutputs = createNativeOutputContracts({
+        nativeNodes: preparedNativeNodes,
+        capabilities: input.capabilities,
+    });
+    const readyIds = input.materials
+        .filter((item) => item.status === 'ready')
+        .map((item) => item.arguments.callId);
+    const schema = createReviewableWorkflowGraphSchema(planningCapabilities, readyIds);
+    const output = await input.model
+        .withStructuredOutput(schema, {
+        name: 'plan_reviewable_workflow_graph',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(reviewableWorkflowGraphPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: input.scenario,
+            preparedNativeNodes: createPreparedNativeNodeMaterials(preparedNativeNodes, input.capabilities),
+            nativeOutputs,
+            materials: input.materials.map(({ operation, ...material }) => ({
+                ...material,
+                operation: {
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: {
+                        summary: operation.operation.summary,
+                        description: operation.operation.description,
+                        responses: operation.operation.responses,
+                    },
+                },
+                inputPorts: ['main'],
+                outputPorts: ['main'],
+            })),
+            gaps: input.gaps.map((gap) => ({
+                ...gap,
+                inputPorts: ['main'],
+                outputPorts: ['main'],
+            })),
+            capabilities: planningCapabilities.map((capability) => ({
+                name: capability.name,
+                description: capability.description,
+                parametersSchema: z.toJSONSchema(capability.parametersSchema),
+                waitsForAllInputs: capability.waitsForAllInputs,
+                exclusiveOutputPorts: capability.exclusiveOutputPorts,
+            })),
+        })),
+    ]);
+    let proposal;
+    try {
+        const parsed = parseStructuredOutput(schema, output, 'model reviewable workflow graph');
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('native model schema must validate without defaults, coercion or transformation');
+        proposal = completeReviewableWorkflowGraphProposal(parsed, input.capabilities.length, readyIds.length);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        return createReviewableWorkflowGraphPlan({
+            ...input,
+            proposal: {
+                ...proposal,
+                nativeNodes: assembleNativeNodeMaterials(preparedNativeNodes, proposal.nativeNodes),
+            },
+        });
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'graph-validation', output }, error);
+    }
+}

package/dist/workflow/plan-workflow-connections.d.ts

@@ -0,0 +1,3 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanWorkflowConnectionsInput } from '../types/workflow-orchestration.js';
+export declare function planWorkflowConnections(input: PlanWorkflowConnectionsInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/plan-workflow-connections.js

@@ -0,0 +1,62 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { completeReviewableWorkflowGraphProposal } from './complete-reviewable-workflow-graph-proposal.js';
+import { workflowConnectionsPrompt } from '../prompts/workflow-connections-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { ReviewableWorkflowGraphPlanningError } from './reviewable-workflow-graph-planning-error.js';
+import { prepareWorkflowConnectionMaterials } from './prepare-workflow-connection-materials.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+export async function planWorkflowConnections(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const { materials, capabilities, nativeNodes, gaps, edges, contracts } = prepareWorkflowConnectionMaterials(input);
+    const context = { materials, capabilities, gaps };
+    const readyIds = materials.flatMap((material) => material.status === 'ready' ? [material.arguments.callId] : []);
+    const schema = createReviewableWorkflowGraphSchema([], readyIds);
+    const output = await input.model
+        .withStructuredOutput(schema, {
+        name: 'plan_workflow_connections',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowConnectionsPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: input.scenario,
+            nodes: contracts,
+            ...(nativeNodes.length
+                ? {
+                    nativeNodes: createPreparedNativeNodeMaterials(nativeNodes, capabilities),
+                }
+                : {}),
+            edges,
+            gaps,
+            readyCallIds: readyIds,
+        })),
+    ]);
+    let proposal;
+    try {
+        proposal = completeReviewableWorkflowGraphProposal(parseStructuredOutput(schema, output, 'model workflow connections'), 0, readyIds.length);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        return createReviewableWorkflowGraphPlan({
+            ...context,
+            proposal: {
+                ...proposal,
+                nativeNodes,
+                edges: [...edges, ...proposal.edges],
+            },
+        });
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'graph-validation', output }, error);
+    }
+}

package/dist/workflow/plan-workflow-graph.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanWorkflowGraphInput } from '../types/workflow-planning.js';
+export declare function planWorkflowGraph(input: PlanWorkflowGraphInput): Promise<WorkflowGraphPlan>;

package/dist/workflow/plan-workflow-graph.js

@@ -0,0 +1,99 @@
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { createWorkflowGraphPlan, createNativeOutputContracts, createWorkflowPlanningCapabilities, validateNativeApiResponseReferences, } from '@openapi-flow/core';
+import { z } from 'zod';
+import { createWorkflowGraphProposalSchema } from '../schemas/workflow-graph-proposal-schema.js';
+import { WorkflowGraphPlanningError } from './workflow-graph-planning-error.js';
+import { workflowGraphPrompt } from '../prompts/workflow-graph-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { createPreparedNativeNodeMaterials } from './create-prepared-native-node-materials.js';
+import { assembleNativeNodeMaterials } from './assemble-native-node-materials.js';
+export async function planWorkflowGraph(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const preparedNativeNodes = input.preparedNativeNodes ?? [];
+    const apiCallIds = input.materials.map((material) => material.arguments.callId);
+    const planningCapabilities = createWorkflowPlanningCapabilities({
+        capabilities: input.capabilities,
+        apiCallIds,
+    });
+    const schema = createWorkflowGraphProposalSchema(planningCapabilities);
+    validateNativeApiResponseReferences({
+        nativeNodes: preparedNativeNodes,
+        capabilities: input.capabilities,
+        apiCallIds,
+    });
+    const nativeOutputs = createNativeOutputContracts({
+        nativeNodes: preparedNativeNodes,
+        capabilities: input.capabilities,
+    });
+    const output = await input.model
+        .withStructuredOutput(schema, {
+        name: 'plan_workflow_graph',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowGraphPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: input.scenario,
+            preparedNativeNodes: createPreparedNativeNodeMaterials(preparedNativeNodes, input.capabilities),
+            nativeOutputs,
+            // Request values are already generated. Avoid duplicating the resolved
+            // response schemas through both operation and pathItem in this stage.
+            materials: input.materials.map(({ operation, arguments: args }) => ({
+                operation: {
+                    key: operation.key,
+                    method: operation.method,
+                    path: operation.path,
+                    operation: {
+                        summary: operation.operation.summary,
+                        description: operation.operation.description,
+                        tags: operation.operation.tags,
+                        responses: operation.operation.responses,
+                    },
+                },
+                arguments: {
+                    callId: args.callId,
+                    values: args.values,
+                    bindings: args.bindings,
+                },
+                inputPorts: ['main'],
+                outputPorts: ['main'],
+            })),
+            capabilities: planningCapabilities.map((capability) => ({
+                name: capability.name,
+                description: capability.description,
+                parametersSchema: z.toJSONSchema(capability.parametersSchema),
+                waitsForAllInputs: capability.waitsForAllInputs,
+                exclusiveOutputPorts: capability.exclusiveOutputPorts,
+            })),
+        })),
+    ]);
+    let proposal;
+    try {
+        proposal = parseStructuredOutput(schema, output, 'model workflow graph');
+        if (!isDeepStrictEqual(proposal, output))
+            throw new Error('native model schema must validate without defaults, coercion or transformation');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new WorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        return createWorkflowGraphPlan({
+            ...input,
+            proposal: {
+                edges: proposal.edges,
+                gaps: proposal.gaps,
+                nativeNodes: assembleNativeNodeMaterials(preparedNativeNodes, proposal.additionalNativeNodes),
+            },
+        });
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new WorkflowGraphPlanningError({ stage: 'graph-validation', output: proposal }, error);
+    }
+}

package/dist/workflow/prepare-workflow-connection-materials.d.ts

@@ -0,0 +1,3 @@
+import type { PlanWorkflowConnectionsInput, WorkflowConnectionMaterials } from '../types/workflow-orchestration.js';
+/** Validate immutable supplied data before paying for any orchestration model call. */
+export declare function prepareWorkflowConnectionMaterials(input: PlanWorkflowConnectionsInput): WorkflowConnectionMaterials;

package/dist/workflow/prepare-workflow-connection-materials.js

@@ -0,0 +1,66 @@
+import { createReviewableNodeContracts, createNativeOutputContracts, validateWorkflowEdges, validateApiArguments, validateApiBindingAssignments, validateNativeApiResponseReferences, } from '@openapi-flow/core';
+/** Validate immutable supplied data before paying for any orchestration model call. */
+export function prepareWorkflowConnectionMaterials(input) {
+    const materials = input.materials ?? [];
+    const capabilities = input.capabilities ?? [];
+    const nativeNodes = input.nativeNodes ?? [];
+    const gaps = input.gaps ?? [];
+    const edges = input.edges ?? [];
+    validateNativeApiResponseReferences({
+        nativeNodes,
+        capabilities,
+        apiCallIds: materials.map((material) => material.status === 'ready' ? material.arguments.callId : material.callId),
+    });
+    const nativeOutputs = createNativeOutputContracts({
+        nativeNodes,
+        capabilities,
+    });
+    for (const material of materials) {
+        if (material.status !== 'ready')
+            continue;
+        const args = material.arguments;
+        const validation = validateApiArguments({
+            operation: material.operation,
+            ...args,
+        });
+        if (args.unresolvedInputs.length || !validation.valid)
+            throw new Error(`materials[${args.callId}] has unresolved OAS request inputs`);
+    }
+    if (materials.length)
+        validateApiBindingAssignments({
+            nativeOutputs,
+            materials: materials.map((material) => ({
+                operation: material.operation,
+                callId: material.status === 'ready'
+                    ? material.arguments.callId
+                    : material.callId,
+                requestMediaType: material.status === 'ready'
+                    ? material.arguments.requestMediaType
+                    : material.requestMediaType,
+            })),
+            calls: materials.map((material) => ({
+                callId: material.status === 'ready'
+                    ? material.arguments.callId
+                    : material.callId,
+                bindings: material.status === 'ready'
+                    ? material.arguments.bindings
+                    : material.bindings,
+            })),
+        });
+    const plan = {
+        nativeNodes,
+        gaps,
+        edges,
+        starts: [],
+        blockedCalls: materials.flatMap((material) => material.status === 'blocked'
+            ? [{ callId: material.callId, gapIds: material.gapIds }]
+            : []),
+    };
+    const contracts = createReviewableNodeContracts({
+        materials,
+        capabilities,
+        plan,
+    });
+    validateWorkflowEdges({ contracts, edges });
+    return { materials, capabilities, nativeNodes, gaps, edges, contracts };
+}