@openapi-flow/langchain 0.2.0 → 0.3.0

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

@@ -1,83 +1,38 @@
 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 { describeWorkflowGraphPlanning, createWorkflowGraphPlanningResult, createWorkflowGraphPlanningRecord, } from '@openapi-flow/core';
 import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { workflowGraphExplanationOptionsSchema } from '../schemas/workflow-graph-explanation-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { resolveReviewableWorkflowGraphOutput } from './resolve-workflow-graph-output.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,
+    const options = workflowGraphExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
     });
-    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 { input: snapshot, context, sources, planningCapabilities, } = describeWorkflowGraphPlanning({ ...input, mode: 'reviewable' });
+    const readyIds = snapshot.materials.flatMap((material) => material.status === 'ready' ? [material.arguments.callId] : []);
+    const schema = createReviewableWorkflowGraphSchema(planningCapabilities, readyIds, options.includeExplanations === true ? 'graph' : 'none');
     const output = await input.model
-        .withStructuredOutput(schema, {
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         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,
-            })),
-        })),
+        new HumanMessage(JSON.stringify(context)),
     ]);
-    let proposal;
+    let resolved;
     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);
+        resolved = resolveReviewableWorkflowGraphOutput(parsed, snapshot.capabilities.length, readyIds.length);
     }
     catch (error) {
         if (!(error instanceof Error))
@@ -85,13 +40,27 @@ export async function planReviewableWorkflowGraph(input) {
         throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
     }
     try {
-        return createReviewableWorkflowGraphPlan({
-            ...input,
-            proposal: {
-                ...proposal,
-                nativeNodes: assembleNativeNodeMaterials(preparedNativeNodes, proposal.nativeNodes),
-            },
+        const current = describeWorkflowGraphPlanning(snapshot);
+        if (!isDeepStrictEqual(current.context, context) ||
+            !isDeepStrictEqual(current.sources, sources))
+            throw new Error('reviewable workflow graph source contracts changed during the model invocation');
+        const plan = createWorkflowGraphPlanningResult({
+            ...snapshot,
+            proposal: resolved.proposal,
         });
+        if (!('blockedCalls' in plan))
+            throw new Error('reviewable graph result is missing blockedCalls');
+        if (options.includeExplanations === true) {
+            if (!resolved.assessment)
+                throw new Error('model reviewable workflow graph is missing its explanation assessment');
+            plan.graphPlanning = createWorkflowGraphPlanningRecord({
+                ...snapshot,
+                proposal: resolved.proposal,
+                plan,
+                assessment: resolved.assessment,
+            });
+        }
+        return plan;
     }
     catch (error) {
         if (!(error instanceof Error))

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

@@ -1,43 +1,38 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { createReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowConnectionPlanning, createWorkflowConnectionPlan, createWorkflowConnectionPlanningRecord, } from '@openapi-flow/core';
 import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
-import { completeReviewableWorkflowGraphProposal } from './complete-reviewable-workflow-graph-proposal.js';
+import { resolveWorkflowConnectionOutput } from './resolve-workflow-connection-output.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';
+import { workflowConnectionExplanationOptionsSchema } from '../schemas/workflow-connection-explanation-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.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 options = workflowConnectionExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, context, sources, } = describeWorkflowConnectionPlanning(input);
+    const readyIds = context.readyCallIds;
+    const schema = createReviewableWorkflowGraphSchema([], readyIds, options.includeExplanations === true ? 'connections' : 'none');
     const output = await input.model
-        .withStructuredOutput(schema, {
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         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,
-        })),
+        new HumanMessage(JSON.stringify(context)),
     ]);
-    let proposal;
+    let resolved;
     try {
-        proposal = completeReviewableWorkflowGraphProposal(parseStructuredOutput(schema, output, 'model workflow connections'), 0, readyIds.length);
+        const parsed = parseStructuredOutput(schema, output, 'model workflow connections');
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('connection model schema must validate without defaults, coercion or transformation');
+        resolved = resolveWorkflowConnectionOutput(parsed, readyIds.length);
     }
     catch (error) {
         if (!(error instanceof Error))
@@ -45,14 +40,24 @@ export async function planWorkflowConnections(input) {
         throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
     }
     try {
-        return createReviewableWorkflowGraphPlan({
-            ...context,
-            proposal: {
-                ...proposal,
-                nativeNodes,
-                edges: [...edges, ...proposal.edges],
-            },
+        const current = describeWorkflowConnectionPlanning(snapshot);
+        if (!isDeepStrictEqual(current.context, context) ||
+            !isDeepStrictEqual(current.sources, sources))
+            throw new Error('connection planning source contracts changed during the model invocation');
+        const plan = createWorkflowConnectionPlan({
+            ...snapshot,
+            proposal: resolved.proposal,
         });
+        if (options.includeExplanations === true) {
+            if (!resolved.decision)
+                throw new Error('model workflow connections are missing the explanation decision');
+            plan.connectionPlanning = createWorkflowConnectionPlanningRecord({
+                ...snapshot,
+                plan,
+                decision: resolved.decision,
+            });
+        }
+        return plan;
     }
     catch (error) {
         if (!(error instanceof Error))

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

@@ -1,80 +1,50 @@
 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 { describeWorkflowGraphPlanning, createWorkflowGraphPlanningResult, createWorkflowGraphPlanningRecord, } from '@openapi-flow/core';
 import { createWorkflowGraphProposalSchema } from '../schemas/workflow-graph-proposal-schema.js';
+import { workflowGraphExplanationOptionsSchema } from '../schemas/workflow-graph-explanation-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { resolveExecutableWorkflowGraphOutput } from './resolve-workflow-graph-output.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 options = workflowGraphExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
     });
-    const nativeOutputs = createNativeOutputContracts({
-        nativeNodes: preparedNativeNodes,
+    if (!Array.isArray(input.materials))
+        throw new Error('planWorkflowGraph.materials must be an array');
+    const source = {
+        mode: 'executable',
+        scenario: input.scenario,
+        materials: input.materials.map((material) => ({
+            ...material,
+            status: 'ready',
+        })),
         capabilities: input.capabilities,
-    });
+        preparedNativeNodes: input.preparedNativeNodes,
+        gaps: [],
+    };
+    const { input: snapshot, context, sources, planningCapabilities, } = describeWorkflowGraphPlanning(source);
+    const schema = createWorkflowGraphProposalSchema(planningCapabilities, options.includeExplanations === true);
     const output = await input.model
-        .withStructuredOutput(schema, {
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         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,
-            })),
-        })),
+        new HumanMessage(JSON.stringify(context)),
     ]);
-    let proposal;
+    let resolved;
     try {
-        proposal = parseStructuredOutput(schema, output, 'model workflow graph');
-        if (!isDeepStrictEqual(proposal, output))
+        const parsed = parseStructuredOutput(schema, output, 'model workflow graph');
+        if (!isDeepStrictEqual(parsed, output))
             throw new Error('native model schema must validate without defaults, coercion or transformation');
+        resolved = resolveExecutableWorkflowGraphOutput(parsed, snapshot.capabilities.length);
     }
     catch (error) {
         if (!(error instanceof Error))
@@ -82,18 +52,29 @@ export async function planWorkflowGraph(input) {
         throw new WorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
     }
     try {
-        return createWorkflowGraphPlan({
-            ...input,
-            proposal: {
-                edges: proposal.edges,
-                gaps: proposal.gaps,
-                nativeNodes: assembleNativeNodeMaterials(preparedNativeNodes, proposal.additionalNativeNodes),
-            },
+        const current = describeWorkflowGraphPlanning(snapshot);
+        if (!isDeepStrictEqual(current.context, context) ||
+            !isDeepStrictEqual(current.sources, sources))
+            throw new Error('workflow graph source contracts changed during the model invocation');
+        const plan = createWorkflowGraphPlanningResult({
+            ...snapshot,
+            proposal: resolved.proposal,
         });
+        if (options.includeExplanations === true) {
+            if (!resolved.assessment)
+                throw new Error('model workflow graph is missing its explanation assessment');
+            plan.graphPlanning = createWorkflowGraphPlanningRecord({
+                ...snapshot,
+                proposal: resolved.proposal,
+                plan,
+                assessment: resolved.assessment,
+            });
+        }
+        return plan;
     }
     catch (error) {
         if (!(error instanceof Error))
             throw error;
-        throw new WorkflowGraphPlanningError({ stage: 'graph-validation', output: proposal }, error);
+        throw new WorkflowGraphPlanningError({ stage: 'graph-validation', output }, error);
     }
 }

package/dist/workflow/resolve-native-node-parameter-source.d.ts

@@ -0,0 +1,4 @@
+import type { PlannedNativeNode } from '@openapi-flow/core';
+import type { NativeNodeModelInstance } from '../types/native-node-planning.js';
+/** Runtime flags and empty execution parameters are code-owned, never inferred from placeholder text. */
+export declare function resolveNativeNodeParameterSource(node: NativeNodeModelInstance): PlannedNativeNode;

package/dist/workflow/resolve-native-node-parameter-source.js

@@ -0,0 +1,7 @@
+/** Runtime flags and empty execution parameters are code-owned, never inferred from placeholder text. */
+export function resolveNativeNodeParameterSource(node) {
+    const identity = { id: node.id, capability: node.capability };
+    if ('parameterSource' in node && node.parameterSource === 'workflow-input')
+        return { ...identity, parameters: {}, runtimeParameters: true };
+    return { ...identity, parameters: node.parameters };
+}

package/dist/workflow/resolve-native-node-planning-output.d.ts

@@ -0,0 +1,3 @@
+import type { NativeNodePlanningOutput, ResolvedNativeNodePlanningOutput } from '../types/native-node-planning.js';
+/** Structural projection only: no values, identities or unmet requirements are repaired. */
+export declare function resolveNativeNodePlanningOutput(output: NativeNodePlanningOutput): ResolvedNativeNodePlanningOutput;

package/dist/workflow/resolve-native-node-planning-output.js

@@ -0,0 +1,33 @@
+import { resolveNativeNodeParameterSource } from './resolve-native-node-parameter-source.js';
+/** Structural projection only: no values, identities or unmet requirements are repaired. */
+export function resolveNativeNodePlanningOutput(output) {
+    if (!('decision' in output))
+        return {
+            proposal: {
+                nativeNodes: output.nativeNodes.map(resolveNativeNodeParameterSource),
+                gaps: output.gaps,
+            },
+        };
+    const { decision } = output;
+    if ('additions' in decision)
+        return {
+            proposal: {
+                nativeNodes: decision.additions.map((item) => resolveNativeNodeParameterSource(item.node)),
+                gaps: decision.gaps,
+            },
+            assessment: {
+                kind: 'additions',
+                nodes: decision.additions.map(({ node, reason }) => ({
+                    nodeId: node.id,
+                    reason,
+                })),
+            },
+        };
+    return {
+        proposal: { nativeNodes: [], gaps: decision.gaps },
+        assessment: {
+            kind: 'no-additions',
+            reason: decision.noAdditionalNodesReason,
+        },
+    };
+}

package/dist/workflow/resolve-workflow-connection-output.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedWorkflowConnectionOutput, WorkflowConnectionPlanningOutput } from '../types/workflow-orchestration.js';
+/** Fill only context-fixed omissions, then separate reasons from executable edges. */
+export declare function resolveWorkflowConnectionOutput(output: WorkflowConnectionPlanningOutput, readyCallCount: number): ResolvedWorkflowConnectionOutput;

package/dist/workflow/resolve-workflow-connection-output.js

@@ -0,0 +1,22 @@
+import { projectWorkflowConnectionDecision } from '@openapi-flow/core';
+import { completeReviewableWorkflowGraphProposal } from './complete-reviewable-workflow-graph-proposal.js';
+/** Fill only context-fixed omissions, then separate reasons from executable edges. */
+export function resolveWorkflowConnectionOutput(output, readyCallCount) {
+    const completed = completeReviewableWorkflowGraphProposal(output, 0, readyCallCount);
+    if ('reason' in output) {
+        const decision = {
+            reason: output.reason,
+            edges: output.edges,
+            additionalGaps: output.additionalGaps,
+            blockedCalls: output.blockedCalls === undefined ? [] : output.blockedCalls,
+        };
+        return { proposal: projectWorkflowConnectionDecision(decision), decision };
+    }
+    return {
+        proposal: {
+            edges: structuredClone(completed.edges),
+            additionalGaps: structuredClone(completed.additionalGaps),
+            blockedCalls: structuredClone(completed.blockedCalls),
+        },
+    };
+}

package/dist/workflow/resolve-workflow-graph-output.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowGraphModelOutput, ResolvedWorkflowGraphOutput } from '../types/workflow-planning.js';
+import type { ReviewableWorkflowGraphModelOutput } from '../types/reviewable-workflow-planning.js';
+/** Context-fixed empty choices are code-owned, never fallback for a missing required model field. */
+export declare function resolveExecutableWorkflowGraphOutput(output: WorkflowGraphModelOutput, capabilityCount: number): ResolvedWorkflowGraphOutput;
+export declare function resolveReviewableWorkflowGraphOutput(output: ReviewableWorkflowGraphModelOutput, capabilityCount: number, readyCallCount: number): ResolvedWorkflowGraphOutput;

package/dist/workflow/resolve-workflow-graph-output.js

@@ -0,0 +1,69 @@
+function assessment(output) {
+    return {
+        reason: output.reason,
+        nodes: output.additionalNativeNodes === undefined
+            ? []
+            : output.additionalNativeNodes.map((node) => ({
+                nodeId: node.id,
+                reason: node.reason,
+            })),
+        edges: structuredClone(output.edges),
+        blockedCalls: 'blockedCalls' in output && output.blockedCalls !== undefined
+            ? structuredClone(output.blockedCalls)
+            : [],
+    };
+}
+/** Context-fixed empty choices are code-owned, never fallback for a missing required model field. */
+export function resolveExecutableWorkflowGraphOutput(output, capabilityCount) {
+    if (capabilityCount > 0 && output.additionalNativeNodes === undefined)
+        throw new Error('model workflow graph.additionalNativeNodes is required');
+    const nodes = capabilityCount === 0 ? [] : output.additionalNativeNodes;
+    return {
+        proposal: {
+            mode: 'executable',
+            additionalNativeNodes: nodes.map(({ id, capability, parameters }) => ({
+                id,
+                capability,
+                parameters,
+            })),
+            edges: output.edges.map(({ from, output, to, input }) => ({
+                from,
+                output,
+                to,
+                input,
+            })),
+            gaps: structuredClone(output.gaps),
+        },
+        ...('reason' in output ? { assessment: assessment(output) } : {}),
+    };
+}
+export function resolveReviewableWorkflowGraphOutput(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 nodes = capabilityCount === 0 ? [] : output.additionalNativeNodes;
+    const blocked = readyCallCount === 0 ? [] : output.blockedCalls;
+    return {
+        proposal: {
+            mode: 'reviewable',
+            additionalNativeNodes: nodes.map(({ id, capability, parameters }) => ({
+                id,
+                capability,
+                parameters,
+            })),
+            edges: output.edges.map(({ from, output, to, input }) => ({
+                from,
+                output,
+                to,
+                input,
+            })),
+            additionalGaps: structuredClone(output.additionalGaps),
+            blockedCalls: blocked.map(({ callId, gapIds }) => ({
+                callId,
+                gapIds: structuredClone(gapIds),
+            })),
+        },
+        ...('reason' in output ? { assessment: assessment(output) } : {}),
+    };
+}

package/dist/workflow/select-native-node-instances.d.ts

@@ -0,0 +1,4 @@
+import type { NativeInstanceSelection } from '@openapi-flow/core';
+import type { SelectNativeNodeInstancesInput } from '../types/native-node-planning.js';
+/** One checkpointable role/ownership selection; parameter values are a separate public stage. */
+export declare function selectNativeNodeInstances(input: SelectNativeNodeInstancesInput): Promise<NativeInstanceSelection>;

package/dist/workflow/select-native-node-instances.js

@@ -0,0 +1,57 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { createNativeInstanceSelectionSchema, describeNativeInstanceSelection, resolveNativeInstanceSelection, } from '@openapi-flow/core';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { nativeInstanceSelectionPrompt } from '../prompts/native-node-planning-prompt.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+/** One checkpointable role/ownership selection; parameter values are a separate public stage. */
+export async function selectNativeNodeInstances(input) {
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('selectNativeNodeInstances.model must support structured output when supplied');
+    const { context } = describeNativeInstanceSelection(input);
+    const originalOptions = JSON.stringify([
+        input.planId,
+        input.allowRuntimeParameters,
+        input.includeExplanations,
+    ]);
+    const schema = createNativeInstanceSelectionSchema(input);
+    if (!context.capabilities.length)
+        return resolveNativeInstanceSelection({
+            ...input,
+            proposal: {
+                instances: [],
+                gaps: [],
+                ...(input.includeExplanations
+                    ? { reason: 'No native capabilities were supplied.' }
+                    : {}),
+            },
+        });
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('selectNativeNodeInstances.model must support structured output for native choices');
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'select_native_node_instances',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeInstanceSelectionPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    try {
+        if (!isDeepStrictEqual(describeNativeInstanceSelection(input).context, context) ||
+            JSON.stringify([
+                input.planId,
+                input.allowRuntimeParameters,
+                input.includeExplanations,
+            ]) !== originalOptions)
+            throw new Error('Native instance source contracts changed during selection; no automatic rebase');
+        return resolveNativeInstanceSelection({ ...input, proposal: output });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'instance-selection', output }, cause);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/langchain",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Composable LangChain planning for OpenAPI workflows",
@@ -28,11 +28,14 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@openapi-flow/core": "0.2.0",
-    "zod": "4.6.5"
+    "@openapi-flow/core": "0.3.0"
   },
   "peerDependencies": {
-    "@langchain/core": "^1.0.0"
+    "@langchain/core": "^1.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "zod": "4.6.5"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/dist/schemas/native-node-plan-schema.d.ts

@@ -1,4 +0,0 @@
-import { z } from 'zod';
-import type { WorkflowCapability } from '@openapi-flow/core';
-import type { NativeNodeProposal } from '../types/native-node-planning.js';
-export declare function createNativeNodePlanSchema(capabilities: WorkflowCapability[]): z.ZodType<NativeNodeProposal>;