@openapi-flow/langchain 0.3.15 → 0.3.17

package/dist/schemas/connection-planning-field-schemas.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export const connectionDecisionTextSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0);
+export function connectionChoicesSchema(choices) {
+    if (!choices.length)
+        throw new Error('Connection schema requires an available choice');
+    return choices.length === 1 ? choices[0] : z.union(choices);
+}
+export function connectionIdListSchema(ids) {
+    return ids.length ? z.array(z.enum(ids)) : z.array(z.string()).max(0);
+}
+/** A single port is a code-owned fact. Only a genuine port choice is generated. */
+export function connectionPortSelectionListSchema(nodes, direction) {
+    const choices = nodes
+        .filter((node) => node[direction].length)
+        .map((node) => {
+        const identity = z.strictObject({ nodeId: z.literal(node.id) });
+        return node[direction].length === 1
+            ? identity
+            : identity.extend({ port: z.enum(node[direction]) });
+    });
+    return choices.length
+        ? z.array(connectionChoicesSchema(choices))
+        : z.array(z.strictObject({ nodeId: z.string() })).max(0);
+}

package/dist/schemas/workflow-connection-goal-rejection-schema.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const workflowConnectionGoalRejectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    stage: z.ZodLiteral<"model-output">;
+    code: z.ZodLiteral<"MODEL_OUTPUT_INVALID">;
+    sourceFingerprint: z.ZodString;
+    output: z.ZodJSONSchema;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    stage: z.ZodLiteral<"contract-validation">;
+    code: z.ZodLiteral<"WORKFLOW_GRAPH_PLANNING_FAILED">;
+    sourceFingerprint: z.ZodString;
+    output: z.ZodJSONSchema;
+    reason: z.ZodString;
+}, z.core.$strict>], "stage">;

package/dist/schemas/workflow-connection-goal-rejection-schema.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { workflowConnectionStepExpectationSchema } from '@openapi-flow/core';
+/** Private planning feedback; never part of the public error JSON or progress projection. */
+const source = {
+    sourceFingerprint: workflowConnectionStepExpectationSchema.shape.sourceFingerprint,
+    output: z.json(),
+    reason: z.string().min(1),
+};
+export const workflowConnectionGoalRejectionSchema = z.discriminatedUnion('stage', [
+    z.strictObject({
+        ...source,
+        stage: z.literal('model-output'),
+        code: z.literal('MODEL_OUTPUT_INVALID'),
+    }),
+    z.strictObject({
+        ...source,
+        stage: z.literal('contract-validation'),
+        code: z.literal('WORKFLOW_GRAPH_PLANNING_FAILED'),
+    }),
+]);

package/dist/schemas/workflow-connection-goals-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { WorkflowConnectionGoalPlanningDescription } from '@openapi-flow/core';
+import type { WorkflowConnectionGoalsModelOutput } from '../types/incremental-connection-planning.js';
+export declare function createWorkflowConnectionGoalsSchema(description: WorkflowConnectionGoalPlanningDescription): z.ZodType<WorkflowConnectionGoalsModelOutput>;

package/dist/schemas/workflow-connection-goals-schema.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { connectionChoicesSchema, connectionDecisionTextSchema as text, connectionPortSelectionListSchema, } from './connection-planning-field-schemas.js';
+export function createWorkflowConnectionGoalsSchema(description) {
+    const nodes = description.context.nodes;
+    const ids = nodes.map((node) => node.id);
+    if (!ids.length)
+        throw new Error('Connection goals require supplied nodes');
+    const basis = {
+        factIds: z
+            .array(z.enum(description.requirements.map((fact) => fact.id)))
+            .min(1)
+            .describe('Exact confirmed requirement IDs that justify this goal. Cover every supplied fact without changing it.'),
+        reason: text.describe('Brief evidence-based explanation, not private reasoning or new requirements.'),
+    };
+    const choices = [
+        z.strictObject({ kind: z.literal('semantic'), ...basis }),
+    ];
+    if (ids.length > 1) {
+        choices.push(z.strictObject({
+            kind: z.literal('precedence'),
+            before: z.enum(ids),
+            after: z.enum(ids),
+            ...basis,
+        }), z.strictObject({
+            kind: z.literal('independent'),
+            nodeIds: z.array(z.enum(ids)).min(2),
+            ...basis,
+        }));
+        if (nodes.some((node) => node.outputs.length))
+            choices.push(z.strictObject({
+                kind: z.literal('route'),
+                source: connectionPortSelectionListSchema(nodes, 'outputs').element,
+                to: z.enum(ids),
+                ...basis,
+            }));
+        const joinIds = nodes
+            .filter((node) => node.waitsForAllInputs)
+            .map((node) => node.id);
+        if (ids.length > 2 && joinIds.length)
+            choices.push(z.strictObject({
+                kind: z.literal('join'),
+                nodeId: z.enum(joinIds),
+                producerIds: z.array(z.enum(ids)).min(2),
+                ...basis,
+            }));
+    }
+    return z.strictObject({
+        goals: z
+            .array(connectionChoicesSchema(choices))
+            .min(1)
+            .describe('Interpret confirmed requirements as goals, not as a complete edge list. Structural goals are checked by code. Use semantic only where a structural goal cannot express the requirement.'),
+    });
+}

package/dist/schemas/workflow-connection-step-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { WorkflowConnectionStepDescription, WorkflowCapability } from '@openapi-flow/core';
+import type { WorkflowConnectionStepModelOutput } from '../types/incremental-connection-planning.js';
+export declare function createWorkflowConnectionStepSchema(description: WorkflowConnectionStepDescription, capabilities: WorkflowCapability[]): z.ZodType<WorkflowConnectionStepModelOutput>;

package/dist/schemas/workflow-connection-step-schema.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { workflowConnectionAssessmentSchema, workflowConnectionMaterialRequestSchema, workflowConnectionUserDecisionSchema, } from '@openapi-flow/core';
+import { connectionChoicesSchema, connectionDecisionTextSchema as text, connectionIdListSchema, connectionPortSelectionListSchema, } from './connection-planning-field-schemas.js';
+export function createWorkflowConnectionStepSchema(description, capabilities) {
+    const nodes = description.context.nodes;
+    const ids = nodes.map((node) => node.id);
+    if (!ids.length)
+        throw new Error('Connection steps require supplied nodes');
+    const factIds = z
+        .array(z.enum(description.requirements.map((fact) => fact.id)))
+        .min(1);
+    const sources = connectionPortSelectionListSchema(nodes, 'outputs');
+    const targets = connectionPortSelectionListSchema(nodes, 'inputs');
+    const edge = z.strictObject({
+        source: sources.element,
+        target: targets.element,
+    });
+    const canConnect = nodes.some((node) => node.outputs.length) &&
+        nodes.some((node) => node.inputs.length);
+    const roots = nodes
+        .filter((node) => !node.waitsForAllInputs &&
+        node.rejoinsExclusiveOutputs === undefined &&
+        !node.references.length &&
+        !node.dependencyNodeIds.length &&
+        !Object.values(node.inputReferences ?? {}).some((references) => references.length))
+        .map((node) => node.id);
+    const terminalNodes = nodes.map((node) => ({
+        ...node,
+        outputs: node.outputs.filter((output) => description.terminals.some((terminal) => terminal.nodeId === node.id && terminal.output === output)),
+    }));
+    const semanticGoalIds = description.goals
+        .filter((goal) => goal.decision.kind === 'semantic')
+        .map((goal) => goal.id);
+    const assessments = semanticGoalIds.length
+        ? z.array(workflowConnectionAssessmentSchema.extend({
+            goalId: z.enum(semanticGoalIds),
+            nodeIds: z.array(z.enum(ids)),
+        }))
+        : z.array(workflowConnectionAssessmentSchema).max(0);
+    const choices = [
+        z.strictObject({
+            kind: z.literal('patch'),
+            addEdges: (canConnect ? z.array(edge) : z.array(edge).max(0)).describe('One complete connection bundle, including both conditional branches or the intended fan-out/join where needed. Not a full graph replacement.'),
+            removeEdgeIds: connectionIdListSchema(description.edgeCatalog
+                .filter((item) => item.editable)
+                .map((item) => item.id)),
+            addRootNodeIds: connectionIdListSchema(roots).describe('Explicit independent roots. Unconnected nodes are not automatic roots.'),
+            removeRootNodeIds: connectionIdListSchema(description.rootNodeIds),
+            addTerminals: sources,
+            removeTerminals: connectionPortSelectionListSchema(terminalNodes, 'outputs'),
+            factIds,
+            reason: text,
+        }),
+        z.strictObject({
+            kind: z.literal('request-completion'),
+            assessments,
+            reason: text,
+        }),
+        workflowConnectionUserDecisionSchema
+            .extend({ factIds })
+            .describe('Only a genuine unresolved BUSINESS decision. Never ask the user to fix ports, cycles, model output or a missing connection.'),
+    ];
+    if (capabilities.length)
+        choices.push(workflowConnectionMaterialRequestSchema.extend({
+            capability: z.enum(capabilities.map((capability) => capability.name)),
+            factIds,
+        }));
+    return z.strictObject({ decision: connectionChoicesSchema(choices) });
+}

package/dist/selection/select-api-operations.js

@@ -50,6 +50,7 @@ export async function selectApiOperations(input) {
         operation: 'selectApiOperations',
         name: 'select_api_operations',
         method: 'jsonSchema',
+        strict: true,
         messages: [
             new SystemMessage(`${operationSelectionPrompt}\n${apiSelectionExplanationPrompt}`),
             new HumanMessage(JSON.stringify({ scenario, candidates })),

package/dist/types/incremental-connection-planning.d.ts

@@ -0,0 +1,69 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ZodType, z } from 'zod';
+import type { workflowConnectionGoalRejectionSchema } from '../schemas/workflow-connection-goal-rejection-schema.js';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { WorkflowConnectionSessionSource, WorkflowConnectionSessionInput, WorkflowConnectionGoalProposal, WorkflowConnectionStepProposal, WorkflowConnectionPatch, WorkflowConnectionPlanningDecision, WorkflowConnectionMaterialRequest, WorkflowConnectionUserDecision, WorkflowConnectionRejectedProposal, WorkflowConnectionStepExpectation } from '@openapi-flow/core';
+export interface PlanWorkflowConnectionGoalsInput extends WorkflowConnectionSessionSource {
+    model: BaseChatModel;
+    /** Exact rejected output and code-owned validation feedback for this unchanged source. */
+    rejectedProposals?: WorkflowConnectionGoalRejection[];
+    signal?: AbortSignal;
+}
+export type WorkflowConnectionGoalRejection = z.infer<typeof workflowConnectionGoalRejectionSchema>;
+export interface CreateWorkflowConnectionGoalRejectionInput extends WorkflowConnectionSessionSource {
+    error: unknown;
+}
+export interface PlanWorkflowConnectionStepInput extends WorkflowConnectionSessionInput {
+    model: BaseChatModel;
+    rejectedProposals?: WorkflowConnectionRejectedProposal[];
+    signal?: AbortSignal;
+}
+export type WorkflowConnectionRouteGoal = Extract<WorkflowConnectionGoalProposal, {
+    kind: 'route';
+}>;
+export interface WorkflowConnectionRouteSelection extends Omit<WorkflowConnectionRouteGoal, 'from' | 'output'> {
+    source: WorkflowConnectionEndpointSelection;
+}
+export type WorkflowConnectionGoalSelection = Exclude<WorkflowConnectionGoalProposal, WorkflowConnectionRouteGoal> | WorkflowConnectionRouteSelection;
+export interface WorkflowConnectionGoalsModelOutput {
+    goals: WorkflowConnectionGoalSelection[];
+}
+export interface WorkflowConnectionEndpointSelection {
+    nodeId: string;
+    /** Omitted in the model contract exactly when this node has only one such port. */
+    port?: string;
+}
+export interface WorkflowConnectionEdgeSelection {
+    source: WorkflowConnectionEndpointSelection;
+    target: WorkflowConnectionEndpointSelection;
+}
+export interface WorkflowConnectionPatchSelection extends Omit<WorkflowConnectionPatch, 'addEdges' | 'addTerminals' | 'removeTerminals'> {
+    addEdges: WorkflowConnectionEdgeSelection[];
+    addTerminals: WorkflowConnectionEndpointSelection[];
+    removeTerminals: WorkflowConnectionEndpointSelection[];
+}
+export type WorkflowConnectionCompletionRequest = Exclude<WorkflowConnectionStepProposal, WorkflowConnectionPatch>;
+export type WorkflowConnectionStepModelDecision = WorkflowConnectionPatchSelection | WorkflowConnectionCompletionRequest | WorkflowConnectionMaterialRequest | WorkflowConnectionUserDecision;
+export interface WorkflowConnectionStepModelOutput {
+    decision: WorkflowConnectionStepModelDecision;
+}
+export interface PlanWorkflowConnectionStepResult {
+    expected: WorkflowConnectionStepExpectation;
+    decision: WorkflowConnectionPlanningDecision;
+}
+export interface InvokeConnectionPlanningModelInput<Output extends object> {
+    model: BaseChatModel;
+    operation: string;
+    name: string;
+    schema: ZodType<Output>;
+    messages: BaseMessage[];
+    sourceFingerprint?: string;
+    signal?: AbortSignal;
+}
+export interface WorkflowConnectionPlanningFailure {
+    operation: string;
+    stage: 'model-output' | 'contract-validation';
+    code: 'MODEL_OUTPUT_INVALID' | 'WORKFLOW_GRAPH_PLANNING_FAILED';
+    output: unknown;
+    sourceFingerprint?: string;
+}

package/dist/types/incremental-connection-planning.js

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

package/dist/types/native-node-planning.d.ts

@@ -67,10 +67,13 @@ export type NativeNodePlanningFailure = {
 };
 export interface SelectNativeNodeInstancesInput extends NativeInstanceSelectionInput {
     model?: BaseChatModel;
+    signal?: AbortSignal;
 }
 export interface GenerateNativeNodeParametersInput extends NativeNodeConfigurationInput {
     model?: BaseChatModel;
+    signal?: AbortSignal;
 }
 export interface PlanNativeInstanceDependenciesInput extends NativeSelectedPlanningInput {
     model?: BaseChatModel;
+    signal?: AbortSignal;
 }

package/dist/types/structured-model.d.ts

@@ -1,12 +1,14 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ZodType } from 'zod';
+import type { JsonObject } from '@openapi-flow/core';
 export interface InvokeStructuredModelInput<Output extends object> {
     model: BaseChatModel;
-    schema: ZodType<Output>;
+    schema: ZodType<Output> | JsonObject;
     name: string;
     operation: string;
     method: 'functionCalling' | 'jsonSchema';
+    strict: boolean | undefined;
     messages: BaseMessage[];
     signal?: AbortSignal;
 }

package/dist/workflow/connections/create-workflow-connection-goal-rejection.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWorkflowConnectionGoalRejectionInput, WorkflowConnectionGoalRejection } from '../../types/incremental-connection-planning.js';
+/** Classify an unchanged-source proposal rejection. Other failures must remain failures. */
+export declare function createWorkflowConnectionGoalRejection(input: CreateWorkflowConnectionGoalRejectionInput): WorkflowConnectionGoalRejection | undefined;

package/dist/workflow/connections/create-workflow-connection-goal-rejection.js

@@ -0,0 +1,27 @@
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowConnectionGoals } from '@openapi-flow/core';
+import { workflowConnectionGoalRejectionSchema } from '../../schemas/workflow-connection-goal-rejection-schema.js';
+import { WorkflowConnectionPlanningError } from './workflow-connection-planning-error.js';
+/** Classify an unchanged-source proposal rejection. Other failures must remain failures. */
+export function createWorkflowConnectionGoalRejection(input) {
+    const { error } = input;
+    if (!(error instanceof WorkflowConnectionPlanningError) ||
+        error.diagnostic.operation !== 'planWorkflowConnectionGoals' ||
+        !['model-output', 'contract-validation'].includes(error.diagnostic.stage) ||
+        error.sourceFingerprint === undefined)
+        return undefined;
+    const current = describeWorkflowConnectionGoals(input);
+    if (error.sourceFingerprint !== current.sourceFingerprint)
+        return undefined;
+    const parsed = workflowConnectionGoalRejectionSchema.safeParse({
+        sourceFingerprint: error.sourceFingerprint,
+        stage: error.diagnostic.stage,
+        code: error.diagnostic.code,
+        output: error.output,
+        reason: error.message,
+    });
+    // Non-JSON results cannot be checkpointed losslessly; never repair them to enable a retry.
+    if (!parsed.success || !isDeepStrictEqual(parsed.data.output, error.output))
+        return undefined;
+    return structuredClone(parsed.data);
+}

package/dist/workflow/connections/invoke-connection-planning-model.d.ts

@@ -0,0 +1,3 @@
+import type { InvokeConnectionPlanningModelInput } from '../../types/incremental-connection-planning.js';
+/** Exactly one invocation. Loop policy and rejected-proposal handling belong to the host. */
+export declare function invokeConnectionPlanningModel<Output extends object>(input: InvokeConnectionPlanningModelInput<Output>): Promise<Output>;

package/dist/workflow/connections/invoke-connection-planning-model.js

@@ -0,0 +1,38 @@
+import { isDeepStrictEqual } from 'node:util';
+import { runOpenApiFlowOperation } from '@openapi-flow/core';
+import { invokeStructuredModel } from '../../model/invoke-structured-model.js';
+import { serializeStructuredOutputSchema } from '../../schemas/serialize-structured-output-schema.js';
+import { validateConnectionProposal } from './workflow-connection-planning-error.js';
+/** Exactly one invocation. Loop policy and rejected-proposal handling belong to the host. */
+export async function invokeConnectionPlanningModel(input) {
+    const wireSchema = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: input.operation,
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => serializeStructuredOutputSchema(input.schema, 'draft-2020-12'));
+    const output = await invokeStructuredModel({
+        model: input.model,
+        operation: input.operation,
+        name: input.name,
+        schema: wireSchema,
+        method: 'functionCalling',
+        strict: true,
+        messages: input.messages,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    return validateConnectionProposal({
+        operation: input.operation,
+        stage: 'model-output',
+        code: 'MODEL_OUTPUT_INVALID',
+        output,
+        ...(input.sourceFingerprint === undefined
+            ? {}
+            : { sourceFingerprint: input.sourceFingerprint }),
+    }, () => {
+        const parsed = input.schema.parse(output);
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('Connection output schema must not default, coerce or transform model data');
+        return parsed;
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { WorkflowConnectionSession } from '@openapi-flow/core';
+import type { PlanWorkflowConnectionGoalsInput } from '../../types/incremental-connection-planning.js';
+/** One semantic interpretation; code validates coverage/identities and creates the initial session. */
+export declare function planWorkflowConnectionGoals(input: PlanWorkflowConnectionGoalsInput): Promise<WorkflowConnectionSession>;

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

@@ -0,0 +1,72 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { describeWorkflowConnectionGoals, createWorkflowConnectionSession, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { createWorkflowConnectionGoalsSchema } from '../../schemas/workflow-connection-goals-schema.js';
+import { workflowConnectionGoalRejectionSchema } from '../../schemas/workflow-connection-goal-rejection-schema.js';
+import { workflowConnectionGoalsPrompt } 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';
+/** One semantic interpretation; code validates coverage/identities and creates the initial session. */
+export async function planWorkflowConnectionGoals(input) {
+    const operation = 'planWorkflowConnectionGoals';
+    const { description, schema } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        const description = describeWorkflowConnectionGoals(input);
+        if (input.rejectedProposals !== undefined) {
+            if (!Array.isArray(input.rejectedProposals))
+                throw new Error('rejectedProposals must be an array when supplied');
+            for (const rejection of input.rejectedProposals) {
+                workflowConnectionGoalRejectionSchema.parse(rejection);
+                if (rejection.sourceFingerprint !== description.sourceFingerprint)
+                    throw new Error('Rejected goals must belong to the unchanged source and requirements');
+            }
+        }
+        return {
+            description,
+            schema: createWorkflowConnectionGoalsSchema(description),
+        };
+    });
+    const output = await invokeConnectionPlanningModel({
+        model: input.model,
+        operation,
+        name: 'plan_workflow_connection_goals',
+        schema,
+        sourceFingerprint: description.sourceFingerprint,
+        messages: [
+            new SystemMessage(workflowConnectionGoalsPrompt),
+            new HumanMessage(JSON.stringify({
+                ...description,
+                ...(input.rejectedProposals === undefined
+                    ? {}
+                    : { rejectedProposals: input.rejectedProposals }),
+            })),
+        ],
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    return validateConnectionProposal({
+        operation,
+        stage: 'contract-validation',
+        code: 'WORKFLOW_GRAPH_PLANNING_FAILED',
+        output,
+        sourceFingerprint: description.sourceFingerprint,
+    }, () => {
+        if (describeWorkflowConnectionGoals(input).sourceFingerprint !==
+            description.sourceFingerprint)
+            throw new Error('Connection goal source changed during model invocation');
+        const goals = output.goals.map((goal) => goal.kind !== 'route'
+            ? goal
+            : {
+                kind: goal.kind,
+                from: goal.source.nodeId,
+                to: goal.to,
+                factIds: goal.factIds,
+                reason: goal.reason,
+                output: resolveConnectionPortSelection(goal.source, description.context.nodes, 'outputs'),
+            });
+        return createWorkflowConnectionSession({ ...input, goals });
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { PlanWorkflowConnectionStepInput, PlanWorkflowConnectionStepResult } from '../../types/incremental-connection-planning.js';
+export declare function planWorkflowConnectionStep(input: PlanWorkflowConnectionStepInput): Promise<PlanWorkflowConnectionStepResult>;

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,9 @@
+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;
+    readonly sourceFingerprint: string | undefined;
+    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,28 @@
+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;
+    sourceFingerprint;
+    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;
+        this.sourceFingerprint = failure.sourceFingerprint;
+    }
+}
+export function validateConnectionProposal(failure, execute) {
+    try {
+        return execute();
+    }
+    catch (cause) {
+        throw new WorkflowConnectionPlanningError(failure, cause);
+    }
+}