@openapi-flow/langchain 0.3.14 → 0.3.16

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

@@ -0,0 +1,98 @@
+import { isDeepStrictEqual } from 'node:util';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { describeWorkflowConnectionStep, workflowConnectionPlanningDecisionSchema, workflowConnectionRejectedProposalSchema, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { createWorkflowConnectionStepSchema } from '../../schemas/workflow-connection-step-schema.js';
+import { workflowConnectionStepPrompt } from '../../prompts/incremental-workflow-connections-prompt.js';
+import { invokeConnectionPlanningModel } from './invoke-connection-planning-model.js';
+import { resolveConnectionPortSelection } from './resolve-connection-port-selection.js';
+import { validateConnectionProposal } from './workflow-connection-planning-error.js';
+export async function planWorkflowConnectionStep(input) {
+    const operation = 'planWorkflowConnectionStep';
+    const { description, capabilities, capabilityIndex, schema } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        const description = describeWorkflowConnectionStep(input);
+        if (input.rejectedProposals !== undefined) {
+            if (!Array.isArray(input.rejectedProposals))
+                throw new Error('rejectedProposals must be an array when supplied');
+            for (const proposal of input.rejectedProposals) {
+                workflowConnectionRejectedProposalSchema.parse(proposal);
+                if (proposal.expected.sessionId !== description.expected.sessionId ||
+                    proposal.expected.sourceFingerprint !==
+                        description.expected.sourceFingerprint ||
+                    proposal.expected.revision > description.expected.revision)
+                    throw new Error('Rejected proposal must belong to this session/source and not a future revision');
+            }
+        }
+        // An omitted optional registry has no augmentation choices; never infer an engine registry.
+        const capabilities = input.capabilities === undefined ? [] : input.capabilities;
+        return {
+            description,
+            capabilities,
+            capabilityIndex: capabilities.map(({ name, description }) => ({
+                name,
+                description,
+            })),
+            schema: createWorkflowConnectionStepSchema(description, capabilities),
+        };
+    });
+    const output = await invokeConnectionPlanningModel({
+        model: input.model,
+        operation,
+        name: 'plan_workflow_connection_step',
+        schema,
+        messages: [
+            new SystemMessage(workflowConnectionStepPrompt),
+            new HumanMessage(JSON.stringify({
+                ...description,
+                availableNativeCapabilities: capabilityIndex,
+                ...(input.rejectedProposals === undefined
+                    ? {}
+                    : { rejectedProposals: input.rejectedProposals }),
+            })),
+        ],
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    return validateConnectionProposal({
+        operation,
+        stage: 'contract-validation',
+        code: 'WORKFLOW_GRAPH_PLANNING_FAILED',
+        output,
+    }, () => {
+        if (!isDeepStrictEqual(describeWorkflowConnectionStep(input), description))
+            throw new Error('Connection session or source changed during model invocation');
+        if (!isDeepStrictEqual(capabilities.map(({ name, description }) => ({ name, description })), capabilityIndex))
+            throw new Error('Available native capabilities changed during model invocation');
+        const raw = output.decision;
+        const decision = raw.kind !== 'patch'
+            ? raw
+            : {
+                ...raw,
+                addEdges: raw.addEdges.map((edge) => ({
+                    from: edge.source.nodeId,
+                    output: resolveConnectionPortSelection(edge.source, description.context.nodes, 'outputs'),
+                    to: edge.target.nodeId,
+                    input: resolveConnectionPortSelection(edge.target, description.context.nodes, 'inputs'),
+                })),
+                addTerminals: raw.addTerminals.map((selection) => ({
+                    nodeId: selection.nodeId,
+                    output: resolveConnectionPortSelection(selection, description.context.nodes, 'outputs'),
+                })),
+                removeTerminals: raw.removeTerminals.map((selection) => ({
+                    nodeId: selection.nodeId,
+                    output: resolveConnectionPortSelection(selection, description.context.nodes.map((node) => ({
+                        ...node,
+                        outputs: node.outputs.filter((port) => description.terminals.some((terminal) => terminal.nodeId === node.id &&
+                            terminal.output === port)),
+                    })), 'outputs'),
+                })),
+            };
+        return {
+            expected: structuredClone(description.expected),
+            decision: workflowConnectionPlanningDecisionSchema.parse(decision),
+        };
+    });
+}

package/dist/workflow/connections/resolve-connection-port-selection.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowPlanNodeContract } from '@openapi-flow/core';
+import type { WorkflowConnectionEndpointSelection } from '../../types/incremental-connection-planning.js';
+/** The schema deliberately excludes a unique port from the model's decision. This is not a fallback. */
+export declare function resolveConnectionPortSelection(selection: WorkflowConnectionEndpointSelection, contracts: WorkflowPlanNodeContract[], direction: 'inputs' | 'outputs'): string;

package/dist/workflow/connections/resolve-connection-port-selection.js

@@ -0,0 +1,15 @@
+/** The schema deliberately excludes a unique port from the model's decision. This is not a fallback. */
+export function resolveConnectionPortSelection(selection, contracts, direction) {
+    const node = contracts.find((contract) => contract.id === selection.nodeId);
+    if (!node)
+        throw new Error(`Connection selection has no node ${selection.nodeId}`);
+    const ports = node[direction];
+    if (ports.length === 1) {
+        if (selection.port !== undefined)
+            throw new Error(`Connection selection ${node.id} must not regenerate its unique port`);
+        return ports[0];
+    }
+    if (selection.port === undefined || !ports.includes(selection.port))
+        throw new Error(`Connection selection ${node.id} requires an actual ${direction} port`);
+    return selection.port;
+}

package/dist/workflow/connections/workflow-connection-planning-error.d.ts

@@ -0,0 +1,8 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
+import type { WorkflowConnectionPlanningFailure } from '../../types/incremental-connection-planning.js';
+/** Raw output is retained for a private host diagnostic, not in the public error projection. */
+export declare class WorkflowConnectionPlanningError extends OpenApiFlowError {
+    readonly output: unknown;
+    constructor(failure: WorkflowConnectionPlanningFailure, cause: unknown);
+}
+export declare function validateConnectionProposal<Result>(failure: WorkflowConnectionPlanningFailure, execute: () => Result): Result;

package/dist/workflow/connections/workflow-connection-planning-error.js

@@ -0,0 +1,26 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
+/** Raw output is retained for a private host diagnostic, not in the public error projection. */
+export class WorkflowConnectionPlanningError extends OpenApiFlowError {
+    output;
+    constructor(failure, cause) {
+        super({
+            message: cause instanceof Error ? cause.message : failure.operation,
+            diagnostic: {
+                owner: 'langchain',
+                operation: failure.operation,
+                stage: failure.stage,
+                code: failure.code,
+            },
+            cause,
+        });
+        this.output = failure.output;
+    }
+}
+export function validateConnectionProposal(failure, execute) {
+    try {
+        return execute();
+    }
+    catch (cause) {
+        throw new WorkflowConnectionPlanningError(failure, cause);
+    }
+}

package/dist/workflow/generate-native-node-parameters.js

@@ -5,6 +5,7 @@ import { nativeNodeParametersPrompt } from '../prompts/native-node-planning-prom
 import { NativeNodePlanningError } from './native-node-planning-error.js';
 /** Zero or one value call for one selected instance; no hidden ownership or connection planning. */
 export async function generateNativeNodeParameters(input) {
+    input.signal?.throwIfAborted();
     if (input.model !== undefined &&
         (!input.model || typeof input.model.withStructuredOutput !== 'function'))
         throw new Error('generateNativeNodeParameters.model must support structured output when supplied');
@@ -62,7 +63,8 @@ export async function generateNativeNodeParameters(input) {
                 ? {}
                 : { replies: description.replies }),
         })),
-    ]);
+    ], input.signal === undefined ? undefined : { signal: input.signal });
+    input.signal?.throwIfAborted();
     try {
         // Validate output separately so callers can distinguish a malformed reply from stale source material.
         schema.parse(output);

package/dist/workflow/plan-native-instance-dependencies.js

@@ -6,6 +6,7 @@ import { serializeStructuredOutputSchema } from '../schemas/serialize-structured
 import { NativeNodePlanningError } from './native-node-planning-error.js';
 /** Zero or one producer-choice call; no parameters, output contracts or runtime DAG edges. */
 export async function planNativeInstanceDependencies(input) {
+    input.signal?.throwIfAborted();
     if (input.model !== undefined &&
         (!input.model || typeof input.model.withStructuredOutput !== 'function'))
         throw new Error('planNativeInstanceDependencies.model must support structured output when supplied');
@@ -30,7 +31,8 @@ export async function planNativeInstanceDependencies(input) {
         .invoke([
         new SystemMessage(nativeInstanceDependenciesPrompt),
         new HumanMessage(JSON.stringify(context)),
-    ]);
+    ], input.signal === undefined ? undefined : { signal: input.signal });
+    input.signal?.throwIfAborted();
     try {
         if (!isDeepStrictEqual(describeNativeInstanceDependencies(input), context) ||
             explanations !== input.includeExplanations)

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

@@ -6,6 +6,7 @@ import { nativeInstanceSelectionPrompt } from '../prompts/native-node-planning-p
 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) {
+    input.signal?.throwIfAborted();
     if (input.model !== undefined &&
         (!input.model || typeof input.model.withStructuredOutput !== 'function'))
         throw new Error('selectNativeNodeInstances.model must support structured output when supplied');
@@ -38,7 +39,8 @@ export async function selectNativeNodeInstances(input) {
         .invoke([
         new SystemMessage(nativeInstanceSelectionPrompt),
         new HumanMessage(JSON.stringify(context)),
-    ]);
+    ], input.signal === undefined ? undefined : { signal: input.signal });
+    input.signal?.throwIfAborted();
     try {
         if (!isDeepStrictEqual(describeNativeInstanceSelection(input).context, context) ||
             JSON.stringify([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/langchain",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "license": "MIT",
   "type": "module",
   "description": "Composable LangChain planning for OpenAPI workflows",
@@ -28,7 +28,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@openapi-flow/core": "0.3.14"
+    "@openapi-flow/core": "0.3.16"
   },
   "peerDependencies": {
     "@langchain/core": "^1.0.0",