@openapi-flow/langchain 0.4.1 → 0.4.3

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

@@ -1,6 +1,7 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { ReviewableWorkflowGraphProposal, ReviewableWorkflowPlanningContext, WorkflowReviewGap, PlannedNativeNode, ExplainedWorkflowConnection, ExplainedWorkflowBlockedCall } from '@openapi-flow/core';
 import type { ExplainedGraphNativeNode } from './workflow-planning.js';
+import type { WorkflowConnectionSelectionOutput } from './workflow-connection-selection.js';
 export interface PlanReviewableWorkflowGraphInput extends ReviewableWorkflowPlanningContext {
     scenario: string;
     model: BaseChatModel;
@@ -13,7 +14,7 @@ export type ReviewableWorkflowGraphPlanningFailure = {
     output: unknown;
 } | {
     stage: 'graph-validation';
-    output: ReviewableWorkflowGraphModelOutput;
+    output: ReviewableWorkflowGraphModelOutput | WorkflowConnectionSelectionOutput;
 };
 export type ReviewableWorkflowGraphOutput = Omit<ReviewableWorkflowGraphProposal, 'nativeNodes' | 'blockedCalls'> & {
     additionalNativeNodes?: ReviewableWorkflowGraphProposal['nativeNodes'];

package/dist/types/workflow-connection-selection.d.ts

@@ -0,0 +1,19 @@
+import type { z } from 'zod';
+import type { createWorkflowConnectionSelectionSchema } from '../schemas/workflow-connection-selection-schema.js';
+import type { WorkflowConnectionProposal, BlockedWorkflowCall, WorkflowPlanEdge } from '@openapi-flow/core';
+export type WorkflowConnectionSelectionOutput = z.infer<ReturnType<typeof createWorkflowConnectionSelectionSchema>>;
+export type WorkflowConnectionExecutionEdge = Omit<WorkflowConnectionSelectionOutput['edges'][number], 'reason'> & {
+    reason?: unknown;
+};
+export type WorkflowConnectionExecutionBlockedCall = BlockedWorkflowCall & {
+    reason?: unknown;
+};
+export interface WorkflowConnectionExecutionOutput extends Omit<WorkflowConnectionProposal, 'edges' | 'blockedCalls'> {
+    reason?: unknown;
+    edges: WorkflowConnectionExecutionEdge[];
+    blockedCalls?: WorkflowConnectionExecutionBlockedCall[];
+}
+export type ResolvedWorkflowConnectionSelectionEdge = WorkflowPlanEdge & Pick<WorkflowConnectionExecutionEdge, 'reason'>;
+export interface ResolvedWorkflowConnectionSelection extends Omit<WorkflowConnectionExecutionOutput, 'edges'> {
+    edges: ResolvedWorkflowConnectionSelectionEdge[];
+}

package/dist/types/workflow-connection-selection.js

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

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

@@ -0,0 +1,6 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowIntentInput } from '@openapi-flow/core';
+export interface PlanWorkflowIntentInput extends WorkflowIntentInput {
+    model: BaseChatModel;
+    signal?: AbortSignal;
+}

package/dist/types/workflow-intent.js

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

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

@@ -1,5 +1,5 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection } from '@openapi-flow/core';
+import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection, WorkflowConnectionExplanationIssue } from '@openapi-flow/core';
 import type { ReviewableWorkflowGraphOutput } from './reviewable-workflow-planning.js';
 export interface PlanWorkflowConnectionsInput extends WorkflowConnectionPlanningInput {
     model: BaseChatModel;
@@ -18,4 +18,5 @@ export type WorkflowConnectionPlanningOutput = ReviewableWorkflowGraphOutput | W
 export interface ResolvedWorkflowConnectionOutput {
     proposal: WorkflowConnectionProposal;
     decision?: WorkflowConnectionDecision;
+    explanationIssues?: WorkflowConnectionExplanationIssue[];
 }

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

@@ -33,7 +33,10 @@ export async function invokeConnectionPlanningModel(input) {
             ? {}
             : { requestFingerprint: input.requestFingerprint }),
     }, () => {
-        const parsed = input.schema.parse(output);
+        const receiver = input.validationSchema === undefined
+            ? input.schema
+            : input.validationSchema;
+        const parsed = receiver.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/review-workflow-connection-goals.js

@@ -33,6 +33,7 @@ export async function reviewWorkflowConnectionGoals(input) {
         operation,
         name: 'review_workflow_connection_goals',
         schema: createWorkflowConnectionGoalReviewSchema(description),
+        validationSchema: createWorkflowConnectionGoalReviewSchema(description, false),
         sourceFingerprint: description.sourceFingerprint,
         messages: [
             new SystemMessage(workflowConnectionGoalReviewPrompt),

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

@@ -1,5 +1,5 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, } from '@openapi-flow/core';
+import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, resolveNativeProducerParameters, } from '@openapi-flow/core';
 import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 import { nativeNodeParametersPrompt } from '../prompts/native-node-planning-prompt.js';
 import { NativeNodePlanningError } from './native-node-planning-error.js';
@@ -9,6 +9,9 @@ export async function generateNativeNodeParameters(input) {
     if (input.model !== undefined &&
         (!input.model || typeof input.model.withStructuredOutput !== 'function'))
         throw new Error('generateNativeNodeParameters.model must support structured output when supplied');
+    const derived = resolveNativeProducerParameters(input);
+    if (derived !== undefined)
+        return derived;
     const description = describeNativeNodeConfiguration(input);
     if (!description.instance.hasLiteralParameters)
         return resolveNativeNodeParameters({
@@ -29,6 +32,7 @@ export async function generateNativeNodeParameters(input) {
     if (!input.model || typeof input.model.withStructuredOutput !== 'function')
         throw new Error('generateNativeNodeParameters.model must support structured output for remaining values');
     const schema = createNativeNodeParametersSchema(input);
+    const validationSchema = createNativeNodeParametersSchema(input, false);
     const capability = description.context.capabilities.find((entry) => entry.name === description.instance.capability);
     if (!capability)
         throw new Error('Native parameter generation has no selected capability material');
@@ -67,7 +71,7 @@ export async function generateNativeNodeParameters(input) {
     input.signal?.throwIfAborted();
     try {
         // Validate output separately so callers can distinguish a malformed reply from stale source material.
-        schema.parse(output);
+        validationSchema.parse(output);
     }
     catch (cause) {
         if (!(cause instanceof Error))

package/dist/workflow/native-selection/review-native-instance-selection.js

@@ -27,7 +27,7 @@ export async function reviewNativeInstanceSelection(input) {
         requestFingerprint,
         rejectedProposals: input.rejectedProposals,
     });
-    if (!description.gaps.length)
+    if (!description.gaps.length && description.reviewInstances !== true)
         return createNativeInstanceSelectionReview({
             ...input,
             proposal: { assessments: {} },
@@ -40,7 +40,7 @@ export async function reviewNativeInstanceSelection(input) {
     }, () => {
         if (!input.model ||
             typeof input.model.withStructuredOutput !== 'function')
-            throw new Error('reviewNativeInstanceSelection.model must support structured output for reported gaps');
+            throw new Error('reviewNativeInstanceSelection.model must support structured output for the requested review');
         return input.model;
     });
     const checkCurrent = (originalFailure) => {

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

@@ -1,7 +1,9 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { isDeepStrictEqual } from 'node:util';
 import { describeWorkflowConnectionPlanning, createWorkflowConnectionPlan, createWorkflowConnectionPlanningRecord, } from '@openapi-flow/core';
-import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { createWorkflowConnectionSelectionSchema } from '../schemas/workflow-connection-selection-schema.js';
+import { createWorkflowConnectionExecutionSchema } from '../schemas/workflow-connection-execution-schema.js';
+import { resolveWorkflowConnectionSelection } from './resolve-workflow-connection-selection.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';
@@ -15,8 +17,7 @@ export async function planWorkflowConnections(input) {
         includeExplanations: input.includeExplanations,
     });
     const { input: snapshot, context, sources, } = describeWorkflowConnectionPlanning(input);
-    const readyIds = context.readyCallIds;
-    const schema = createReviewableWorkflowGraphSchema([], readyIds, options.includeExplanations === true ? 'connections' : 'none');
+    const schema = createWorkflowConnectionSelectionSchema(context, options.includeExplanations === true);
     const output = await input.model
         .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         name: 'plan_workflow_connections',
@@ -29,10 +30,10 @@ export async function planWorkflowConnections(input) {
     ]);
     let resolved;
     try {
-        const parsed = parseStructuredOutput(schema, output, 'model workflow connections');
+        const parsed = parseStructuredOutput(createWorkflowConnectionExecutionSchema(context, options.includeExplanations === true), 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);
+        resolved = resolveWorkflowConnectionOutput(resolveWorkflowConnectionSelection(parsed, context), options.includeExplanations === true);
     }
     catch (error) {
         if (!(error instanceof Error))
@@ -48,15 +49,15 @@ export async function planWorkflowConnections(input) {
             ...snapshot,
             proposal: resolved.proposal,
         });
-        if (options.includeExplanations === true) {
-            if (!resolved.decision)
-                throw new Error('model workflow connections are missing the explanation decision');
+        if (resolved.decision !== undefined) {
             plan.connectionPlanning = createWorkflowConnectionPlanningRecord({
                 ...snapshot,
                 plan,
                 decision: resolved.decision,
             });
         }
+        if (resolved.explanationIssues !== undefined)
+            plan.connectionExplanationIssues = resolved.explanationIssues;
         return plan;
     }
     catch (error) {

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

@@ -0,0 +1,4 @@
+import type { WorkflowIntentPlan } from '@openapi-flow/core';
+import type { PlanWorkflowIntentInput } from '../types/workflow-intent.js';
+/** One semantic planning call; the host owns invocation order, checkpointing, human review and revision. */
+export declare function planWorkflowIntent(input: PlanWorkflowIntentInput): Promise<WorkflowIntentPlan>;

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

@@ -0,0 +1,49 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { createWorkflowIntentProposalSchema, workflowIntentInputSchema, resolveWorkflowIntent, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { workflowIntentPrompt } from '../prompts/workflow-intent-prompt.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { modelSignalSchema } from '../schemas/model-signal-schema.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
+/** One semantic planning call; the host owns invocation order, checkpointing, human review and revision. */
+export async function planWorkflowIntent(input) {
+    const operation = 'planWorkflowIntent';
+    const source = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        modelSignalSchema.parse(input.signal);
+        return workflowIntentInputSchema.parse({
+            scenario: input.scenario,
+            messages: input.messages,
+        });
+    });
+    const proposal = await invokeStructuredModel({
+        model: input.model,
+        operation,
+        name: 'plan_workflow_intent',
+        schema: serializeStructuredOutputSchema(createWorkflowIntentProposalSchema(source), 'draft-2020-12'),
+        method: 'jsonSchema',
+        strict: true,
+        signal: input.signal,
+        messages: [
+            new SystemMessage(workflowIntentPrompt),
+            new HumanMessage(JSON.stringify(source)),
+        ],
+    });
+    return runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'contract-validation',
+        code: 'WORKFLOW_GRAPH_PLANNING_FAILED',
+    }, () => {
+        if (!isDeepStrictEqual(source, workflowIntentInputSchema.parse({
+            scenario: input.scenario,
+            messages: input.messages,
+        })))
+            throw new Error('Workflow intent source changed during model invocation');
+        return resolveWorkflowIntent({ ...source, proposal });
+    });
+}

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

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

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

@@ -1,22 +1,34 @@
-import { projectWorkflowConnectionDecision } from '@openapi-flow/core';
-import { completeReviewableWorkflowGraphProposal } from './complete-reviewable-workflow-graph-proposal.js';
+import { workflowConnectionDecisionSchema } from '@openapi-flow/core';
 /** 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 };
-    }
+export function resolveWorkflowConnectionOutput(output, includeExplanations) {
+    const proposal = {
+        edges: output.edges.map(({ from, output, to, input }) => ({
+            from,
+            output,
+            to,
+            input,
+        })),
+        additionalGaps: structuredClone(output.additionalGaps),
+        blockedCalls: output.blockedCalls === undefined
+            ? []
+            : output.blockedCalls.map(({ callId, gapIds }) => ({
+                callId,
+                gapIds: structuredClone(gapIds),
+            })),
+    };
+    if (!includeExplanations)
+        return { proposal };
+    const presentation = workflowConnectionDecisionSchema.safeParse({
+        ...output,
+        blockedCalls: output.blockedCalls === undefined ? [] : output.blockedCalls,
+    });
+    if (presentation.success)
+        return { proposal, decision: presentation.data };
     return {
-        proposal: {
-            edges: structuredClone(completed.edges),
-            additionalGaps: structuredClone(completed.additionalGaps),
-            blockedCalls: structuredClone(completed.blockedCalls),
-        },
+        proposal,
+        explanationIssues: presentation.error.issues.map((issue) => ({
+            path: issue.path.map((segment) => typeof segment === 'symbol' ? String(segment) : segment),
+            code: issue.code,
+        })),
     };
 }

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

@@ -0,0 +1,4 @@
+import type { WorkflowConnectionPlanningContext } from '@openapi-flow/core';
+import type { WorkflowConnectionExecutionOutput, ResolvedWorkflowConnectionSelection } from '../types/workflow-connection-selection.js';
+/** Resolve explicit new-gap references. Never repair, alias or approximate a supplied node ID. */
+export declare function resolveWorkflowConnectionSelection(output: WorkflowConnectionExecutionOutput, context: WorkflowConnectionPlanningContext): ResolvedWorkflowConnectionSelection;

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

@@ -0,0 +1,24 @@
+/** Resolve explicit new-gap references. Never repair, alias or approximate a supplied node ID. */
+export function resolveWorkflowConnectionSelection(output, context) {
+    const known = new Set(context.nodes.map((node) => node.id));
+    const gaps = new Set(output.additionalGaps.map((gap) => gap.id));
+    for (const edge of output.edges)
+        for (const endpoint of [edge.from, edge.to]) {
+            if (typeof endpoint === 'string') {
+                if (!known.has(endpoint))
+                    throw new Error('Connection selection references an unknown supplied node');
+            }
+            else if (!gaps.has(endpoint.gapId) || known.has(endpoint.gapId)) {
+                throw new Error('Connection gap reference must name a newly declared gap, not a supplied node');
+            }
+        }
+    const canonical = {
+        ...output,
+        edges: output.edges.map((edge) => ({
+            ...edge,
+            from: typeof edge.from === 'string' ? edge.from : edge.from.gapId,
+            to: typeof edge.to === 'string' ? edge.to : edge.to.gapId,
+        })),
+    };
+    return canonical;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/langchain",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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.4.1"
+    "@openapi-flow/core": "0.4.3"
   },
   "peerDependencies": {
     "@langchain/core": "^1.0.0",