@openapi-flow/langchain 0.4.0 → 0.4.2

package/dist/workflow/native-selection/validate-native-planning-rejections.js

@@ -0,0 +1,14 @@
+import { isDeepStrictEqual } from 'node:util';
+import { nativePlanningRejectionSchema } from '../../schemas/native-planning-rejection-schema.js';
+export function validateNativePlanningRejections(input) {
+    if (input.rejectedProposals === undefined)
+        return [];
+    const parsed = nativePlanningRejectionSchema
+        .array()
+        .parse(input.rejectedProposals);
+    if (!isDeepStrictEqual(parsed, input.rejectedProposals) ||
+        parsed.some((entry) => entry.stage !== input.stage ||
+            entry.requestFingerprint !== input.requestFingerprint))
+        throw new Error('Native rejectedProposals belong to a changed source or different planning stage');
+    return structuredClone(parsed);
+}

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/dist/workflow/select-native-node-instances.js

@@ -1,24 +1,40 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { isDeepStrictEqual } from 'node:util';
-import { createNativeInstanceSelectionSchema, describeNativeInstanceSelection, resolveNativeInstanceSelection, describeNativeInstanceSelectionFeedback, } from '@openapi-flow/core';
+import { createNativeInstanceSelectionSchema, 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';
+import { describeNativeSelectionRequest } from './native-selection/describe-native-planning-request.js';
+import { validateNativePlanningRejections } from './native-selection/validate-native-planning-rejections.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');
-    const { context } = describeNativeInstanceSelection(input);
-    const feedback = input.feedback === undefined
-        ? undefined
-        : describeNativeInstanceSelectionFeedback(input, input.feedback);
-    const originalOptions = JSON.stringify([
-        input.planId,
-        input.allowRuntimeParameters,
-        input.includeExplanations,
-    ]);
+    const request = describeNativeSelectionRequest(input);
+    const { context, feedback, requestFingerprint } = request;
+    const rejectedProposals = validateNativePlanningRejections({
+        stage: 'instance-selection',
+        requestFingerprint,
+        rejectedProposals: input.rejectedProposals,
+    });
+    const checkCurrent = (failure) => {
+        try {
+            if (!isDeepStrictEqual(request, describeNativeSelectionRequest(input)) ||
+                !isDeepStrictEqual(rejectedProposals, validateNativePlanningRejections({
+                    stage: 'instance-selection',
+                    requestFingerprint,
+                    rejectedProposals: input.rejectedProposals,
+                })))
+                throw new Error('Native instance source contracts changed during selection; no automatic rebase');
+        }
+        catch (cause) {
+            if (failure !== undefined)
+                throw new AggregateError([failure, cause], 'Native selection input changed while a failed model call was received', { cause });
+            throw cause;
+        }
+    };
     const schema = createNativeInstanceSelectionSchema(input);
     if (!context.capabilities.length)
         return resolveNativeInstanceSelection({
@@ -44,25 +60,27 @@ export async function selectNativeNodeInstances(input) {
         new HumanMessage(JSON.stringify({
             ...context,
             ...(feedback === undefined ? {} : { selectionFeedback: feedback }),
+            ...(rejectedProposals.length === 0 ? {} : { rejectedProposals }),
         })),
-    ], input.signal === undefined ? undefined : { signal: input.signal });
+    ], input.signal === undefined ? undefined : { signal: input.signal })
+        .catch((error) => {
+        checkCurrent(error);
+        throw error;
+    });
     input.signal?.throwIfAborted();
+    let unchanged = false;
     try {
-        if (!isDeepStrictEqual(describeNativeInstanceSelection(input).context, context) ||
-            !isDeepStrictEqual(feedback, input.feedback === undefined
-                ? undefined
-                : describeNativeInstanceSelectionFeedback(input, input.feedback)) ||
-            JSON.stringify([
-                input.planId,
-                input.allowRuntimeParameters,
-                input.includeExplanations,
-            ]) !== originalOptions)
-            throw new Error('Native instance source contracts changed during selection; no automatic rebase');
+        checkCurrent();
+        unchanged = true;
         return resolveNativeInstanceSelection({ ...input, proposal: output });
     }
     catch (cause) {
         if (!(cause instanceof Error))
             throw cause;
-        throw new NativeNodePlanningError({ stage: 'instance-selection', output }, cause);
+        throw new NativeNodePlanningError({
+            stage: 'instance-selection',
+            output,
+            ...(unchanged ? { requestFingerprint } : {}),
+        }, cause);
     }
 }

package/package.json

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