@openapi-flow/langchain 0.3.13 → 0.3.14

package/README.md

@@ -1,6 +1,21 @@
 # @openapi-flow/langchain
 
-Zod `^4.6.5` is a required host peer, alongside `@langchain/core`. The three libraries share the host's Zod for public schema types instead of creating an isolated pinned copy. Modern package managers install compatible missing peers; a host that directly creates Zod schemas should declare its own compatible Zod dependency.
+Version **0.3.14** adds source-owned structured errors and preserves initial
+argument provenance failures across optional enum selection. Existing prompts,
+values, schemas and retry behavior are unchanged; the host still chooses the
+planning inventory. The owner accepted the n8n adapter's unresolved upstream
+Zod 3 advisory for this release on 2026-10-25; this does not clear the audit.
+See the [0.3.14 release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.14.md)
+for actual publication and host status; preparation is not publication.
+
+API selection and binding planning expose Core's shared `OpenApiFlowError`
+diagnostic. Existing native/graph planning error subclasses retain their identity,
+failure payload and cause. A typed outer error can now wrap a previously untyped
+exception; use `cause` for its original identity and serialize only the diagnostic.
+No model-output repair or hidden retry is added, and not every internal model
+call/provider-specific timeout has been migrated.
+
+Zod `^4.6.7` is a required host peer, alongside `@langchain/core`. The three libraries share the host's Zod for public schema types instead of creating an isolated pinned copy. Modern package managers install compatible missing peers; a host that directly creates Zod schemas should declare its own compatible Zod dependency.
 
 Version **0.3.13**, with matching `@openapi-flow/core@0.3.13`. Native edit target selection and value generation share actual code-derived API/native source identities and response contracts. Connection edits also forward the optional supplied entrypoint rather than infer one. Model output remains subject to the existing deterministic validators; no output filtering or hidden retries are added. Optional enum interpretation from 0.3.11/0.3.12 remains available. The host supplies its LangChain model and owns LangGraph, storage and review policies. The Core/n8n Ajv `properties.__proto__` limitation and actual publication/host status are documented in the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.13.md); this release does not rewrite OAS or values to hide it.
 

package/dist/bindings/plan-api-bindings.js

@@ -1,26 +1,36 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { validateApiBindingAssignments, validateApiBindingGaps, describeApiBindingPlanning, createApiBindingPlanningRecord, } from '@openapi-flow/core';
+import { validateApiBindingAssignments, validateApiBindingGaps, describeApiBindingPlanning, createApiBindingPlanningRecord, runOpenApiFlowOperation, } from '@openapi-flow/core';
 import { createApiBindingPlanSchema, apiBindingPlanningOptionsSchema, } from '../schemas/api-binding-plan-schema.js';
 import { apiBindingsPrompt } from '../prompts/api-bindings-prompt.js';
 import { assertSelectionInput } from '../legacy/planning/select-operation.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
 export async function planApiBindings(input) {
-    assertSelectionInput(input.scenario, input.model);
-    const options = apiBindingPlanningOptionsSchema.parse({
-        includeExplanations: input.includeExplanations,
+    const { options, snapshot, context, schema } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'planApiBindings',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        assertSelectionInput(input.scenario, input.model);
+        const options = apiBindingPlanningOptionsSchema.parse({
+            includeExplanations: input.includeExplanations,
+        });
+        const { input: snapshot, context } = describeApiBindingPlanning(input);
+        const schema = createApiBindingPlanSchema(snapshot.materials, snapshot.nativeOutputs, options.includeExplanations === true);
+        return { options, snapshot, context, schema };
     });
-    const { input: snapshot, context } = describeApiBindingPlanning(input);
-    const schema = createApiBindingPlanSchema(snapshot.materials, snapshot.nativeOutputs, options.includeExplanations === true);
-    const proposed = await input.model
-        .withStructuredOutput(schema, {
+    const proposed = await invokeStructuredModel({
+        model: input.model,
+        schema,
+        operation: 'planApiBindings',
         name: 'plan_api_bindings',
         method: 'functionCalling',
-        strict: true,
-    })
-        .invoke([
-        new SystemMessage(apiBindingsPrompt),
-        new HumanMessage(JSON.stringify(context)),
-    ]);
+        messages: [
+            new SystemMessage(apiBindingsPrompt),
+            new HumanMessage(JSON.stringify(context)),
+        ],
+    });
     const parsed = parseStructuredOutput(schema, proposed, 'model API bindings');
     const plan = {
         calls: parsed.calls.map(({ callId, bindings }) => ({
@@ -36,7 +46,12 @@ export async function planApiBindings(input) {
     });
     validateApiBindingGaps({ plan, materials: snapshot.materials });
     if (options.includeExplanations === true) {
-        plan.bindingPlanning = createApiBindingPlanningRecord({
+        plan.bindingPlanning = runOpenApiFlowOperation({
+            owner: 'langchain',
+            operation: 'planApiBindings',
+            stage: 'contract-validation',
+            code: 'API_BINDING_VALIDATION_FAILED',
+        }, () => createApiBindingPlanningRecord({
             ...snapshot,
             plan,
             reasons: parsed.calls.map((call) => {
@@ -44,7 +59,7 @@ export async function planApiBindings(input) {
                     throw new Error(`model API bindings are missing reason for ${call.callId}`);
                 return { callId: call.callId, reason: call.reason };
             }),
-        });
+        }));
     }
     return plan;
 }

package/dist/draft/select-workflow-draft-api-enums.js

@@ -5,11 +5,16 @@ import { serializeStructuredOutputSchema } from '../schemas/serialize-structured
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 import { WorkflowDraftApiCallPlanningError } from './workflow-draft-api-call-planning-error.js';
 /** A second call only when actual missing OAS enum choices remain; never a repair retry. */
-export async function selectWorkflowDraftApiEnums(input) {
+export function selectWorkflowDraftApiEnums(input) {
     const original = resolveWorkflowDraftApiCallArguments(input);
-    const { candidates, targets } = describeWorkflowDraftApiEnumChoices(input);
-    if (!candidates.length)
-        return original;
+    const choices = describeWorkflowDraftApiEnumChoices(input);
+    if (!choices.candidates.length)
+        return Promise.resolve(original);
+    return selectMissingWorkflowDraftApiEnums(input, choices);
+}
+/** Model transport remains outside the enum-output validation boundary. */
+async function selectMissingWorkflowDraftApiEnums(input, choices) {
+    const { candidates, targets } = choices;
     const description = describeWorkflowDraftApiCallArguments(input);
     const schema = createWorkflowDraftApiEnumSelectionSchema(input);
     const output = await input.model

package/dist/legacy/planning/parse-structured-output.js

@@ -1,9 +1,17 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
 export function parseStructuredOutput(schema, value, source) {
     const parsed = schema.safeParse(value);
     if (parsed.success)
         return parsed.data;
     const issues = parsed.error.issues.map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`);
-    throw new Error(`${source} is invalid: ${issues.join('; ')}`, {
+    throw new OpenApiFlowError({
+        message: `${source} is invalid: ${issues.join('; ')}`,
+        diagnostic: {
+            owner: 'langchain',
+            operation: 'parseStructuredOutput',
+            stage: 'model-output',
+            code: 'MODEL_OUTPUT_INVALID',
+        },
         cause: parsed.error,
     });
 }

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

@@ -0,0 +1,3 @@
+import type { InvokeStructuredModelInput } from '../types/structured-model.js';
+/** Provider-neutral: a failed invoke is not proof of a network or timeout failure. */
+export declare function invokeStructuredModel<Output extends object>(input: InvokeStructuredModelInput<Output>): Promise<Output>;

package/dist/model/invoke-structured-model.js

@@ -0,0 +1,50 @@
+import { OutputParserException } from '@langchain/core/output_parsers';
+import { OpenApiFlowError, runOpenApiFlowOperation } from '@openapi-flow/core';
+/** Provider-neutral: a failed invoke is not proof of a network or timeout failure. */
+export async function invokeStructuredModel(input) {
+    const runnable = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: input.operation,
+        stage: 'model-configuration',
+        code: 'MODEL_CONFIGURATION_FAILED',
+    }, () => input.model.withStructuredOutput(input.schema, {
+        name: input.name,
+        method: input.method,
+        strict: true,
+    }));
+    try {
+        return await runnable.invoke(input.messages);
+    }
+    catch (cause) {
+        if (cause instanceof OpenApiFlowError)
+            throw cause;
+        const diagnostic = {
+            owner: 'langchain',
+            operation: input.operation,
+            stage: cause instanceof OutputParserException
+                ? 'model-output'
+                : 'model-invocation',
+            code: cause instanceof OutputParserException
+                ? 'MODEL_OUTPUT_INVALID'
+                : cause instanceof DOMException && cause.name === 'TimeoutError'
+                    ? 'MODEL_TIMEOUT'
+                    : cause instanceof DOMException && cause.name === 'AbortError'
+                        ? 'MODEL_ABORTED'
+                        : 'MODEL_INVOCATION_FAILED',
+        };
+        // Record only this error's explicit HTTP status. No message/name/cause heuristics.
+        const status = typeof cause === 'object' && cause !== null
+            ? Object.getOwnPropertyDescriptor(cause, 'status')?.value
+            : undefined;
+        if (typeof status === 'number' &&
+            Number.isInteger(status) &&
+            status >= 100 &&
+            status <= 599)
+            diagnostic.httpStatus = status;
+        throw new OpenApiFlowError({
+            message: cause instanceof Error ? cause.message : input.operation,
+            diagnostic,
+            cause,
+        });
+    }
+}

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

@@ -1,22 +1,32 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { describeApiSelectionContext, createApiSelectionExplanation, } from '@openapi-flow/core';
+import { describeApiSelectionContext, createApiSelectionExplanation, runOpenApiFlowOperation, } from '@openapi-flow/core';
 import { createApiSelectionSchema } from '../schemas/api-selection-schema.js';
 import { operationSelectionPrompt } from '../prompts/operation-selection-prompt.js';
 import { assertSelectionInput } from '../legacy/planning/select-operation.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 import { resolveApiSelectionOptions } from './resolve-api-selection-options.js';
 import { apiSelectionExplanationPrompt } from '../prompts/api-selection-explanation-prompt.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
 export async function selectApiOperations(input) {
     const { scenario, model } = input;
-    assertSelectionInput(scenario, model);
-    if (!Array.isArray(input.operations))
-        throw new Error('operations must be an array');
-    const includeExplanations = resolveApiSelectionOptions({
-        includeExplanations: input.includeExplanations,
-    });
-    const context = describeApiSelectionContext({
-        scenario,
-        operations: input.operations,
+    const { includeExplanations, context } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'selectApiOperations',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        assertSelectionInput(scenario, model);
+        if (!Array.isArray(input.operations))
+            throw new Error('operations must be an array');
+        return {
+            includeExplanations: resolveApiSelectionOptions({
+                includeExplanations: input.includeExplanations,
+            }),
+            context: describeApiSelectionContext({
+                scenario,
+                operations: input.operations,
+            }),
+        };
     });
     const { operations } = context;
     if (operations.length === 0)
@@ -34,51 +44,59 @@ export async function selectApiOperations(input) {
         candidateId: `candidate-${index + 1}`,
     }));
     const schema = createApiSelectionSchema(candidates.map((candidate) => candidate.candidateId), includeExplanations);
-    const proposed = await model
-        .withStructuredOutput(schema, {
+    const proposed = await invokeStructuredModel({
+        model,
+        schema,
+        operation: 'selectApiOperations',
         name: 'select_api_operations',
         method: 'jsonSchema',
-        strict: true,
-    })
-        .invoke([
-        new SystemMessage(`${operationSelectionPrompt}\n${apiSelectionExplanationPrompt}`),
-        new HumanMessage(JSON.stringify({ scenario, candidates })),
-    ]);
-    const selection = parseStructuredOutput(schema, proposed, 'model API selection');
-    if (selection.operations.length === 0 && selection.gaps.length === 0)
-        throw new Error('model API selection must contain operations or gaps');
-    const byId = new Map(candidates.map((candidate) => [candidate.candidateId, candidate]));
-    return {
-        operations: selection.operations.map((item) => {
-            const candidate = byId.get(item.candidateId);
-            if (!candidate)
-                throw new Error(`model API selection references unknown ${item.candidateId}`);
-            return {
-                key: { ...candidate.key },
-                purpose: item.purpose,
-                ...('explanation' in item
+        messages: [
+            new SystemMessage(`${operationSelectionPrompt}\n${apiSelectionExplanationPrompt}`),
+            new HumanMessage(JSON.stringify({ scenario, candidates })),
+        ],
+    });
+    return runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'selectApiOperations',
+        stage: 'contract-validation',
+        code: 'API_SELECTION_INVALID',
+    }, () => {
+        const selection = parseStructuredOutput(schema, proposed, 'model API selection');
+        if (selection.operations.length === 0 && selection.gaps.length === 0)
+            throw new Error('model API selection must contain operations or gaps');
+        const byId = new Map(candidates.map((candidate) => [candidate.candidateId, candidate]));
+        return {
+            operations: selection.operations.map((item) => {
+                const candidate = byId.get(item.candidateId);
+                if (!candidate)
+                    throw new Error(`model API selection references unknown ${item.candidateId}`);
+                return {
+                    key: { ...candidate.key },
+                    purpose: item.purpose,
+                    ...('explanation' in item
+                        ? {
+                            explanation: createApiSelectionExplanation({
+                                context,
+                                basis: { kind: 'candidates', operations: [candidate.key] },
+                                reason: item.explanation.reason,
+                            }),
+                        }
+                        : {}),
+                };
+            }),
+            gaps: selection.gaps.map((gap) => ({
+                kind: 'missing_operation',
+                description: gap.description,
+                ...('explanation' in gap
                     ? {
                         explanation: createApiSelectionExplanation({
                             context,
-                            basis: { kind: 'candidates', operations: [candidate.key] },
-                            reason: item.explanation.reason,
+                            basis: { kind: 'catalog' },
+                            reason: gap.explanation.reason,
                         }),
                     }
                     : {}),
-            };
-        }),
-        gaps: selection.gaps.map((gap) => ({
-            kind: 'missing_operation',
-            description: gap.description,
-            ...('explanation' in gap
-                ? {
-                    explanation: createApiSelectionExplanation({
-                        context,
-                        basis: { kind: 'catalog' },
-                        reason: gap.explanation.reason,
-                    }),
-                }
-                : {}),
-        })),
-    };
+            })),
+        };
+    });
 }

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

@@ -0,0 +1,11 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ZodType } from 'zod';
+export interface InvokeStructuredModelInput<Output extends object> {
+    model: BaseChatModel;
+    schema: ZodType<Output>;
+    name: string;
+    operation: string;
+    method: 'functionCalling' | 'jsonSchema';
+    messages: BaseMessage[];
+}

package/dist/types/structured-model.js

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

package/dist/workflow/native-node-planning-error.d.ts

@@ -1,5 +1,6 @@
 import type { NativeNodePlanningFailure } from '../types/native-node-planning.js';
-export declare class NativeNodePlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export declare class NativeNodePlanningError extends OpenApiFlowError {
     readonly failure: NativeNodePlanningFailure;
     constructor(failure: NativeNodePlanningFailure, cause: Error);
 }

package/dist/workflow/native-node-planning-error.js

@@ -1,7 +1,15 @@
-export class NativeNodePlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export class NativeNodePlanningError extends OpenApiFlowError {
     failure;
     constructor(failure, cause) {
-        super(`Native node planning failed at ${failure.stage}: ${cause.message}`, {
+        super({
+            message: `Native node planning failed at ${failure.stage}: ${cause.message}`,
+            diagnostic: {
+                owner: 'langchain',
+                operation: 'planNativeNodes',
+                stage: 'planning',
+                code: 'NATIVE_NODE_PLANNING_FAILED',
+            },
             cause,
         });
         this.name = 'NativeNodePlanningError';

package/dist/workflow/reviewable-workflow-graph-planning-error.d.ts

@@ -1,5 +1,6 @@
 import type { ReviewableWorkflowGraphPlanningFailure } from '../types/reviewable-workflow-planning.js';
-export declare class ReviewableWorkflowGraphPlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export declare class ReviewableWorkflowGraphPlanningError extends OpenApiFlowError {
     readonly failure: ReviewableWorkflowGraphPlanningFailure;
     constructor(failure: ReviewableWorkflowGraphPlanningFailure, cause: Error);
 }

package/dist/workflow/reviewable-workflow-graph-planning-error.js

@@ -1,7 +1,17 @@
-export class ReviewableWorkflowGraphPlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export class ReviewableWorkflowGraphPlanningError extends OpenApiFlowError {
     failure;
     constructor(failure, cause) {
-        super(`model reviewable workflow graph ${failure.stage} failed: ${cause.message}`, { cause });
+        super({
+            message: `model reviewable workflow graph ${failure.stage} failed: ${cause.message}`,
+            diagnostic: {
+                owner: 'langchain',
+                operation: 'planReviewableWorkflowGraph',
+                stage: 'planning',
+                code: 'REVIEWABLE_WORKFLOW_GRAPH_PLANNING_FAILED',
+            },
+            cause,
+        });
         this.name = 'ReviewableWorkflowGraphPlanningError';
         this.failure = failure;
     }

package/dist/workflow/workflow-graph-planning-error.d.ts

@@ -1,5 +1,6 @@
 import type { WorkflowGraphPlanningFailure } from '../types/workflow-planning.js';
-export declare class WorkflowGraphPlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export declare class WorkflowGraphPlanningError extends OpenApiFlowError {
     readonly failure: WorkflowGraphPlanningFailure;
     constructor(failure: WorkflowGraphPlanningFailure, cause: Error);
 }

package/dist/workflow/workflow-graph-planning-error.js

@@ -1,7 +1,15 @@
-export class WorkflowGraphPlanningError extends Error {
+import { OpenApiFlowError } from '@openapi-flow/core';
+export class WorkflowGraphPlanningError extends OpenApiFlowError {
     failure;
     constructor(failure, cause) {
-        super(`model workflow graph ${failure.stage} failed: ${cause.message}`, {
+        super({
+            message: `model workflow graph ${failure.stage} failed: ${cause.message}`,
+            diagnostic: {
+                owner: 'langchain',
+                operation: 'planWorkflowGraph',
+                stage: 'planning',
+                code: 'WORKFLOW_GRAPH_PLANNING_FAILED',
+            },
             cause,
         });
         this.name = 'WorkflowGraphPlanningError';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-flow/langchain",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "license": "MIT",
   "type": "module",
   "description": "Composable LangChain planning for OpenAPI workflows",
@@ -28,14 +28,14 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@openapi-flow/core": "0.3.13"
+    "@openapi-flow/core": "0.3.14"
   },
   "peerDependencies": {
     "@langchain/core": "^1.0.0",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",