@openapi-flow/langchain 0.3.18 → 0.4.1

package/dist/workflow/native-selection/create-native-planning-rejection.js

@@ -0,0 +1,45 @@
+import { isDeepStrictEqual } from 'node:util';
+import { nativePlanningRejectionSchema } from '../../schemas/native-planning-rejection-schema.js';
+import { NativeNodePlanningError } from '../native-node-planning-error.js';
+import { NativeInstanceSelectionReviewError } from './native-instance-selection-review-error.js';
+import { describeNativeSelectionRequest, fingerprintNativeSelectionReviewRequest, } from './describe-native-planning-request.js';
+/** Only unchanged, source-bound output failures are eligible; transport/configuration failures are not proposals. */
+export function createNativeSelectionRejection(input) {
+    const error = input.error;
+    if (!(error instanceof NativeNodePlanningError) ||
+        error.failure.stage !== 'instance-selection' ||
+        error.failure.requestFingerprint === undefined)
+        return undefined;
+    const current = describeNativeSelectionRequest(input);
+    if (current.requestFingerprint !== error.failure.requestFingerprint)
+        return undefined;
+    const parsed = nativePlanningRejectionSchema.safeParse({
+        stage: 'instance-selection',
+        requestFingerprint: current.requestFingerprint,
+        output: error.failure.output,
+        reason: error.message,
+    });
+    if (!parsed.success ||
+        !isDeepStrictEqual(parsed.data.output, error.failure.output))
+        return undefined;
+    return structuredClone(parsed.data);
+}
+export function createNativeSelectionReviewRejection(input) {
+    const error = input.error;
+    if (!(error instanceof NativeInstanceSelectionReviewError) ||
+        error.failure.requestFingerprint === undefined)
+        return undefined;
+    const requestFingerprint = fingerprintNativeSelectionReviewRequest(input);
+    if (requestFingerprint !== error.failure.requestFingerprint)
+        return undefined;
+    const parsed = nativePlanningRejectionSchema.safeParse({
+        stage: 'selection-review',
+        requestFingerprint,
+        output: error.failure.output,
+        reason: error.message,
+    });
+    if (!parsed.success ||
+        !isDeepStrictEqual(parsed.data.output, error.failure.output))
+        return undefined;
+    return structuredClone(parsed.data);
+}

package/dist/workflow/native-selection/describe-native-planning-request.d.ts

@@ -0,0 +1,5 @@
+import type { SelectNativeNodeInstancesInput } from '../../types/native-node-planning.js';
+import type { ReviewNativeInstanceSelectionInput } from '../../types/native-instance-selection-review.js';
+import type { NativeSelectionRequestDescription } from '../../types/native-planning-rejection.js';
+export declare function describeNativeSelectionRequest(input: SelectNativeNodeInstancesInput): NativeSelectionRequestDescription;
+export declare function fingerprintNativeSelectionReviewRequest(input: ReviewNativeInstanceSelectionInput): string;

package/dist/workflow/native-selection/describe-native-planning-request.js

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+import { describeNativeInstanceSelection, describeNativeInstanceSelectionFeedback, describeNativeInstanceSelectionReview, } from '@openapi-flow/core';
+export function describeNativeSelectionRequest(input) {
+    const { context } = describeNativeInstanceSelection(input);
+    const feedback = input.feedback === undefined
+        ? undefined
+        : describeNativeInstanceSelectionFeedback(input, input.feedback);
+    return {
+        context,
+        ...(feedback === undefined ? {} : { feedback }),
+        requestFingerprint: createHash('sha256')
+            .update(JSON.stringify([
+            input.planId,
+            input.allowRuntimeParameters,
+            input.includeExplanations,
+            context,
+            feedback,
+        ]))
+            .digest('hex'),
+    };
+}
+export function fingerprintNativeSelectionReviewRequest(input) {
+    return createHash('sha256')
+        .update(JSON.stringify(describeNativeInstanceSelectionReview(input)))
+        .digest('hex');
+}

package/dist/workflow/native-selection/native-instance-selection-review-error.d.ts

@@ -0,0 +1,6 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
+import type { NativeInstanceSelectionReviewFailure } from '../../types/native-instance-selection-review.js';
+export declare class NativeInstanceSelectionReviewError extends OpenApiFlowError {
+    readonly failure: NativeInstanceSelectionReviewFailure;
+    constructor(failure: NativeInstanceSelectionReviewFailure, cause: Error);
+}

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

@@ -0,0 +1,18 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
+export class NativeInstanceSelectionReviewError extends OpenApiFlowError {
+    failure;
+    constructor(failure, cause) {
+        super({
+            message: `Native selection review failed: ${cause.message}`,
+            diagnostic: {
+                owner: 'langchain',
+                operation: 'reviewNativeInstanceSelection',
+                stage: 'model-output',
+                code: 'MODEL_OUTPUT_INVALID',
+            },
+            cause,
+        });
+        this.name = 'NativeInstanceSelectionReviewError';
+        this.failure = failure;
+    }
+}

package/dist/workflow/native-selection/review-native-instance-selection.d.ts

@@ -0,0 +1,4 @@
+import type { NativeInstanceSelectionReview } from '@openapi-flow/core';
+import type { ReviewNativeInstanceSelectionInput } from '../../types/native-instance-selection-review.js';
+/** One review call only. The host owns replanning, user questions, budgets and persistence. */
+export declare function reviewNativeInstanceSelection(input: ReviewNativeInstanceSelectionInput): Promise<NativeInstanceSelectionReview>;

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

@@ -0,0 +1,97 @@
+import { isDeepStrictEqual } from 'node:util';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { describeNativeInstanceSelectionReview, createNativeInstanceSelectionReview, createNativeInstanceSelectionReviewSchema, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { invokeStructuredModel } from '../../model/invoke-structured-model.js';
+import { serializeStructuredOutputSchema } from '../../schemas/serialize-structured-output-schema.js';
+import { modelSignalSchema } from '../../schemas/model-signal-schema.js';
+import { nativeInstanceSelectionReviewPrompt } from '../../prompts/native-instance-selection-review-prompt.js';
+import { NativeInstanceSelectionReviewError } from './native-instance-selection-review-error.js';
+import { fingerprintNativeSelectionReviewRequest } from './describe-native-planning-request.js';
+import { validateNativePlanningRejections } from './validate-native-planning-rejections.js';
+/** One review call only. The host owns replanning, user questions, budgets and persistence. */
+export async function reviewNativeInstanceSelection(input) {
+    const operation = 'reviewNativeInstanceSelection';
+    const description = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        modelSignalSchema.parse(input.signal);
+        return describeNativeInstanceSelectionReview(input);
+    });
+    input.signal?.throwIfAborted();
+    const requestFingerprint = fingerprintNativeSelectionReviewRequest(input);
+    const rejectedProposals = validateNativePlanningRejections({
+        stage: 'selection-review',
+        requestFingerprint,
+        rejectedProposals: input.rejectedProposals,
+    });
+    if (!description.gaps.length)
+        return createNativeInstanceSelectionReview({
+            ...input,
+            proposal: { assessments: {} },
+        });
+    const model = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation,
+        stage: 'model-configuration',
+        code: 'MODEL_CONFIGURATION_FAILED',
+    }, () => {
+        if (!input.model ||
+            typeof input.model.withStructuredOutput !== 'function')
+            throw new Error('reviewNativeInstanceSelection.model must support structured output for reported gaps');
+        return input.model;
+    });
+    const checkCurrent = (originalFailure) => {
+        runOpenApiFlowOperation({
+            owner: 'langchain',
+            operation,
+            stage: 'input-validation',
+            code: 'PLANNING_INPUT_INVALID',
+        }, () => {
+            try {
+                if (!isDeepStrictEqual(description, describeNativeInstanceSelectionReview(input)) ||
+                    !isDeepStrictEqual(rejectedProposals, validateNativePlanningRejections({
+                        stage: 'selection-review',
+                        requestFingerprint,
+                        rejectedProposals: input.rejectedProposals,
+                    })))
+                    throw new Error('Native selection review source changed during model invocation');
+            }
+            catch (error) {
+                if (originalFailure !== undefined)
+                    throw new AggregateError([originalFailure, error], 'Native review input changed while a failed model call was received', { cause: error });
+                throw error;
+            }
+        });
+    };
+    const output = await invokeStructuredModel({
+        operation,
+        model,
+        schema: serializeStructuredOutputSchema(createNativeInstanceSelectionReviewSchema(description), 'draft-2020-12'),
+        name: 'review_native_instance_selection',
+        method: 'jsonSchema',
+        strict: true,
+        messages: [
+            new SystemMessage(nativeInstanceSelectionReviewPrompt),
+            new HumanMessage(JSON.stringify({
+                ...description,
+                ...(rejectedProposals.length === 0 ? {} : { rejectedProposals }),
+            })),
+        ],
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    }).catch((error) => {
+        checkCurrent(error);
+        throw error;
+    });
+    checkCurrent();
+    try {
+        return createNativeInstanceSelectionReview({ ...input, proposal: output });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeInstanceSelectionReviewError({ output, requestFingerprint }, cause);
+    }
+}

package/dist/workflow/native-selection/validate-native-planning-rejections.d.ts

@@ -0,0 +1,2 @@
+import type { NativePlanningRejectedProposal, NativePlanningRejectionValidationInput } from '../../types/native-planning-rejection.js';
+export declare function validateNativePlanningRejections(input: NativePlanningRejectionValidationInput): NativePlanningRejectedProposal[];

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/resolve-native-node-planning-output.js

@@ -1,13 +1,15 @@
 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))
+    if ('nativeNodes' in output)
         return {
             proposal: {
                 nativeNodes: output.nativeNodes.map(resolveNativeNodeParameterSource),
                 gaps: output.gaps,
             },
         };
+    if ('gaps' in output)
+        return { proposal: { nativeNodes: [], gaps: output.gaps } };
     const { decision } = output;
     if ('additions' in decision)
         return {

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

@@ -1,21 +1,40 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { isDeepStrictEqual } from 'node:util';
-import { createNativeInstanceSelectionSchema, describeNativeInstanceSelection, resolveNativeInstanceSelection, } 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 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({
@@ -38,22 +57,30 @@ export async function selectNativeNodeInstances(input) {
     })
         .invoke([
         new SystemMessage(nativeInstanceSelectionPrompt),
-        new HumanMessage(JSON.stringify(context)),
-    ], input.signal === undefined ? undefined : { signal: input.signal });
+        new HumanMessage(JSON.stringify({
+            ...context,
+            ...(feedback === undefined ? {} : { selectionFeedback: feedback }),
+            ...(rejectedProposals.length === 0 ? {} : { rejectedProposals }),
+        })),
+    ], 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) ||
-            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.3.18",
+  "version": "0.4.1",
   "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.18"
+    "@openapi-flow/core": "0.4.1"
   },
   "peerDependencies": {
     "@langchain/core": "^1.0.0",