@openapi-flow/langchain 0.3.18 → 0.4.1

package/README.md

@@ -1,5 +1,26 @@
 # @openapi-flow/langchain
 
+0.4.0 adds independent selection/goal review, scoped connection
+outlines and originating-stage recovery planners. Each call is independently
+composable; loops, budget, checkpoints and user review stay in the host. Connection
+steps select explicit start/finish intent, while code resolves a unique actual
+port and validates the whole patch. No missing edge is treated as completion.
+Custom model doubles must follow the supplied structured schema. Publication and
+accepted limitations are tracked in the
+[release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.4.0.md).
+
+0.4.0 source adds `reviewNativeInstanceSelection` and explicit
+`selectNativeNodeInstances({ feedback: { selection, review }, ...source })`.
+Review makes at most one model call (zero with no reported gaps), uses exact supplied
+gap IDs and producer/capability choices, and retains the original selection unchanged.
+Only `needs-reselection` feedback permits a new explicitly requested selection;
+unsupported behavior and business decisions cannot be bypassed this way. Ordinary
+selection and configuration validation still applies to the new candidate. The host
+owns budgets, checkpointing, user questions and whether to invoke either function;
+there is no hidden loop, output repair or execution approval. Classification is model
+evidence, not a proof of scenario correctness. See [native planning](../../docs/native-feature-planning.md).
+This is not part of published 0.3.18.
+
 Version **0.3.18** distinguishes independent inputs, selected response sources,
 missing requested sources and partially missing sources in the model output.
 Code constructs only the fixed fields implied by the validated decision. Invalid

package/dist/arguments/analyze-api-input-answers.js

@@ -1,10 +1,12 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { captureApiInputAnswerContext, createApiInputAnswerExtractionRecord, resolveApiInputAnswerInterpretations, describeApiInputEnumAnswerChoices, describeApiInputSources, resolveApiInputSourceSelections, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { isDeepStrictEqual } from 'node:util';
+import { captureApiInputAnswerContext, createApiInputAnswerExtractionRecord, resolveApiInputAnswerInterpretations, describeApiInputEnumAnswerChoices, describeApiInputSources, describeApiInputMessageSources, hasApiInputAnswerSourceText, resolveApiInputSourceSelections, runOpenApiFlowOperation, } from '@openapi-flow/core';
 import { createApiInputAnswerSourceSchema, apiInputAnswerExplanationOptionsSchema, } from '../schemas/api-input-answer-source-schema.js';
 import { apiInputAnswersPrompt } from '../prompts/api-input-answers-prompt.js';
 import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 import { invokeStructuredModel } from '../model/invoke-structured-model.js';
+import { modelSignalSchema } from '../schemas/model-signal-schema.js';
 export async function analyzeApiInputAnswers(input) {
     const { options, snapshot } = runOpenApiFlowOperation({
         owner: 'langchain',
@@ -12,12 +14,16 @@ export async function analyzeApiInputAnswers(input) {
         stage: 'input-validation',
         code: 'PLANNING_INPUT_INVALID',
     }, () => {
+        modelSignalSchema.parse(input.signal);
         const options = apiInputAnswerExplanationOptionsSchema.parse({
             includeExplanations: input.includeExplanations,
             selectOasEnums: input.selectOasEnums,
         });
         const snapshot = captureApiInputAnswerContext({
             reply: input.reply,
+            ...(input.sourceMessages === undefined
+                ? {}
+                : { sourceMessages: input.sourceMessages }),
             requirements: input.requirements,
             ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
             ...(options.selectOasEnums === undefined
@@ -29,7 +35,7 @@ export async function analyzeApiInputAnswers(input) {
             throw new Error('analyzeApiInputAnswers.model must support structured output when supplied');
         return { options, snapshot };
     });
-    if (!snapshot.requirements.length || snapshot.reply === '')
+    if (!snapshot.requirements.length || !hasApiInputAnswerSourceText(snapshot))
         return {
             status: snapshot.requirements.length
                 ? 'empty-reply'
@@ -38,8 +44,21 @@ export async function analyzeApiInputAnswers(input) {
             sources: [],
             unansweredRequirementIds: snapshot.requirements.map((item) => item.id),
         };
-    const catalog = describeApiInputSources(snapshot.reply);
-    if (!catalog.json.length && !catalog.text.length)
+    const catalog = snapshot.sourceMessages === undefined
+        ? describeApiInputSources(snapshot.reply)
+        : undefined;
+    const messageSources = snapshot.sourceMessages === undefined
+        ? undefined
+        : describeApiInputMessageSources(snapshot.sourceMessages);
+    let hasSources;
+    if (messageSources !== undefined)
+        hasSources = messageSources.some(({ sources }) => sources.json.length > 0 || sources.text.length > 0);
+    else {
+        if (catalog === undefined)
+            throw new Error('API input answer sources are missing');
+        hasSources = catalog.json.length > 0 || catalog.text.length > 0;
+    }
+    if (!hasSources)
         return {
             status: 'extracted',
             answers: [],
@@ -55,7 +74,7 @@ export async function analyzeApiInputAnswers(input) {
         if (!input.model)
             throw new Error('analyzeApiInputAnswers.model is required for a nonempty reply with pending inputs');
         const enumChoices = describeApiInputEnumAnswerChoices(snapshot);
-        const schema = createApiInputAnswerSourceSchema(snapshot.requirements, catalog, options.includeExplanations === true, enumChoices);
+        const schema = createApiInputAnswerSourceSchema(snapshot.requirements, catalog, options.includeExplanations === true, enumChoices, messageSources);
         return {
             model: input.model,
             schema,
@@ -70,6 +89,7 @@ export async function analyzeApiInputAnswers(input) {
         name: 'extract_api_input_answers',
         method: 'functionCalling',
         strict: true,
+        signal: input.signal,
         messages: [
             new SystemMessage(apiInputAnswersPrompt),
             new HumanMessage(JSON.stringify({
@@ -78,7 +98,9 @@ export async function analyzeApiInputAnswers(input) {
                 ...(snapshot.purpose === undefined
                     ? {}
                     : { purpose: snapshot.purpose }),
-                sources: catalog,
+                ...(catalog === undefined
+                    ? { messageSources }
+                    : { sources: catalog }),
                 ...(enumChoices.length ? { enumChoices } : {}),
             })),
         ],
@@ -89,6 +111,9 @@ export async function analyzeApiInputAnswers(input) {
         stage: 'contract-validation',
         code: 'API_ARGUMENT_VALIDATION_FAILED',
     }, () => {
+        if (snapshot.sourceMessages !== undefined &&
+            !isDeepStrictEqual(snapshot.sourceMessages, input.sourceMessages))
+            throw new Error('sourceMessages changed during API input answer analysis');
         const parsed = parseStructuredOutput(schema, output, 'model clarification answer sources');
         const selections = resolveApiInputSourceSelections({
             ...snapshot,
@@ -115,6 +140,9 @@ export async function analyzeApiInputAnswers(input) {
                     intent: {
                         sourceFormat: intent.sourceFormat,
                         sourceText: intent.sourceText,
+                        ...(intent.messageId === undefined
+                            ? {}
+                            : { messageId: intent.messageId }),
                     },
                     reason: answer.reason,
                 },

package/dist/arguments/api-argument-planning-error.d.ts

@@ -0,0 +1,11 @@
+import { OpenApiFlowError } from '@openapi-flow/core';
+import type { ApiArgumentPlanningFailure } from '../types/argument-generation.js';
+/** Preserve the original typed error and cause; inherited toJSON exposes only its safe diagnostic. */
+export declare class ApiArgumentPlanningError extends OpenApiFlowError {
+    readonly originalError: OpenApiFlowError;
+    readonly sourceFingerprint: string;
+    readonly output: unknown;
+    constructor(failure: ApiArgumentPlanningFailure);
+}
+/** Only this literal stage's output/contract rejection is eligible; transport/configuration/enum errors are not. */
+export declare function rethrowApiArgumentPlanningError(error: unknown, sourceFingerprint: string, output: unknown): never;

package/dist/arguments/api-argument-planning-error.js

@@ -0,0 +1,32 @@
+import { OpenApiFlowError, isOpenApiFlowError } from '@openapi-flow/core';
+/** Preserve the original typed error and cause; inherited toJSON exposes only its safe diagnostic. */
+export class ApiArgumentPlanningError extends OpenApiFlowError {
+    originalError;
+    sourceFingerprint;
+    output;
+    constructor(failure) {
+        super({
+            message: failure.error.message,
+            diagnostic: failure.error.diagnostic,
+            cause: failure.error.cause,
+        });
+        this.originalError = failure.error;
+        this.sourceFingerprint = failure.sourceFingerprint;
+        this.output = failure.output;
+    }
+}
+/** Only this literal stage's output/contract rejection is eligible; transport/configuration/enum errors are not. */
+export function rethrowApiArgumentPlanningError(error, sourceFingerprint, output) {
+    if (error instanceof ApiArgumentPlanningError)
+        throw error;
+    if (isOpenApiFlowError(error) &&
+        error.diagnostic.owner === 'langchain' &&
+        ((error.diagnostic.stage === 'model-output' &&
+            error.diagnostic.code === 'MODEL_OUTPUT_INVALID' &&
+            ['generateApiArguments', 'parseStructuredOutput'].includes(error.diagnostic.operation)) ||
+            (error.diagnostic.stage === 'contract-validation' &&
+                error.diagnostic.code === 'API_ARGUMENT_VALIDATION_FAILED' &&
+                error.diagnostic.operation === 'generateApiArguments')))
+        throw new ApiArgumentPlanningError({ error, sourceFingerprint, output });
+    throw error;
+}

package/dist/arguments/assert-api-argument-generation-source.d.ts

@@ -0,0 +1,4 @@
+import type { ApiLiteralGenerationInput, WorkflowConnectionApiRepairDescription } from '@openapi-flow/core';
+import type { GenerateApiArgumentsInput } from '../types/argument-generation.js';
+/** Both asynchronous decisions must finish against the same explicit original source and repair request. */
+export declare function assertApiArgumentGenerationSource(input: GenerateApiArgumentsInput, snapshot: ApiLiteralGenerationInput, materialRepair?: WorkflowConnectionApiRepairDescription): void;

package/dist/arguments/assert-api-argument-generation-source.js

@@ -0,0 +1,16 @@
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowConnectionApiRepair } from '@openapi-flow/core';
+/** Both asynchronous decisions must finish against the same explicit original source and repair request. */
+export function assertApiArgumentGenerationSource(input, snapshot, materialRepair) {
+    if (snapshot.literalSourceMessages !== undefined &&
+        !isDeepStrictEqual(snapshot.literalSourceMessages, input.literalSourceMessages))
+        throw new Error('literalSourceMessages changed during argument generation');
+    if (materialRepair !== undefined &&
+        (input.materialRepair === undefined ||
+            !isDeepStrictEqual(materialRepair, describeWorkflowConnectionApiRepair({
+                stage: 'api-arguments',
+                repair: input.materialRepair,
+                planning: input,
+            }))))
+        throw new Error('API material repair feedback changed during argument generation');
+}

package/dist/arguments/attribute-api-literal-generation-sources.d.ts

@@ -0,0 +1,4 @@
+import type { ApiLiteralGenerationInput, ApiLiteralProposalSource } from '@openapi-flow/core';
+import type { ApiLiteralGenerationSource } from '../types/argument-generation.js';
+/** Single-source identity is code-owned; multi-source identity must be explicitly selected. */
+export declare function attributeApiLiteralGenerationSources(input: ApiLiteralGenerationInput, sources: ApiLiteralGenerationSource[]): ApiLiteralProposalSource[];

package/dist/arguments/attribute-api-literal-generation-sources.js

@@ -0,0 +1,16 @@
+/** Single-source identity is code-owned; multi-source identity must be explicitly selected. */
+export function attributeApiLiteralGenerationSources(input, sources) {
+    const messages = input.literalSourceMessages;
+    if (messages === undefined)
+        return sources.map((source) => ({ ...source, messageId: 'scenario' }));
+    const first = messages[0];
+    if (!first)
+        throw new Error('literalSourceMessages must not be empty');
+    if (messages.length === 1)
+        return sources.map((source) => ({ ...source, messageId: first.id }));
+    return sources.map((source) => {
+        if (source.messageId === undefined)
+            throw new Error('Multiple literalSourceMessages require a source messageId');
+        return { ...source, messageId: source.messageId };
+    });
+}

package/dist/arguments/create-api-argument-rejection.d.ts

@@ -0,0 +1,3 @@
+import type { CreateApiArgumentRejectionInput, ApiArgumentRejection } from '../types/argument-generation.js';
+/** Return feedback only for the original unchanged literal source and lossless JSON output. */
+export declare function createApiArgumentRejection(input: CreateApiArgumentRejectionInput): ApiArgumentRejection | undefined;

package/dist/arguments/create-api-argument-rejection.js

@@ -0,0 +1,38 @@
+import { isDeepStrictEqual } from 'node:util';
+import { describeApiLiteralGeneration, describeWorkflowConnectionApiRepair, } from '@openapi-flow/core';
+import { apiLiteralGenerationOptionsSchema } from '../schemas/api-literal-generation-output-schema.js';
+import { apiArgumentRejectionSchema } from '../schemas/api-argument-rejection-schema.js';
+import { fingerprintApiArgumentSource } from './fingerprint-api-argument-source.js';
+import { ApiArgumentPlanningError } from './api-argument-planning-error.js';
+/** Return feedback only for the original unchanged literal source and lossless JSON output. */
+export function createApiArgumentRejection(input) {
+    const error = input.error;
+    if (!(error instanceof ApiArgumentPlanningError))
+        return undefined;
+    const options = apiLiteralGenerationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+        selectOasEnums: input.selectOasEnums,
+        trackRequestedInputs: input.trackRequestedInputs,
+    });
+    const current = describeApiLiteralGeneration(input);
+    const materialRepair = input.materialRepair === undefined
+        ? undefined
+        : describeWorkflowConnectionApiRepair({
+            stage: 'api-arguments',
+            repair: input.materialRepair,
+            planning: input,
+        });
+    if (error.sourceFingerprint !==
+        fingerprintApiArgumentSource(current.input, options, materialRepair))
+        return undefined;
+    const result = apiArgumentRejectionSchema.safeParse({
+        sourceFingerprint: error.sourceFingerprint,
+        code: error.diagnostic.code,
+        stage: error.diagnostic.stage,
+        reason: error.message,
+        ...(error.output === undefined ? {} : { output: error.output }),
+    });
+    if (!result.success || !isDeepStrictEqual(result.data.output, error.output))
+        return undefined;
+    return structuredClone(result.data);
+}

package/dist/arguments/fingerprint-api-argument-source.d.ts

@@ -0,0 +1,4 @@
+import type { ApiLiteralGenerationInput, WorkflowConnectionApiRepairDescription } from '@openapi-flow/core';
+import type { ApiLiteralGenerationOptions } from '../types/argument-generation.js';
+/** Only the validated Core snapshot and effective options participate, never a model/client or prior outputs. */
+export declare function fingerprintApiArgumentSource(snapshot: ApiLiteralGenerationInput, options: ApiLiteralGenerationOptions, materialRepair?: WorkflowConnectionApiRepairDescription): string;

package/dist/arguments/fingerprint-api-argument-source.js

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto';
+/** Only the validated Core snapshot and effective options participate, never a model/client or prior outputs. */
+export function fingerprintApiArgumentSource(snapshot, options, materialRepair) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        snapshot,
+        includeExplanations: options.includeExplanations === true,
+        selectOasEnums: options.selectOasEnums === true,
+        trackRequestedInputs: options.trackRequestedInputs === true,
+        ...(materialRepair === undefined ? {} : { materialRepair }),
+    }))
+        .digest('hex');
+}

package/dist/arguments/generate-api-arguments.js

@@ -1,20 +1,28 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { describeApiLiteralGeneration, createApiLiteralGenerationRecord, applyConfirmedApiInputs, createApiRequestSchema, inspectApiArgumentRequirements, resolveApiLiteralProposalSources, runOpenApiFlowOperation, runOpenApiFlowAsyncOperation, } from '@openapi-flow/core';
+import { describeApiLiteralGeneration, createApiLiteralGenerationRecord, applyConfirmedApiInputs, createApiRequestSchema, inspectApiArgumentRequirements, resolveApiLiteralProposalSources, runOpenApiFlowOperation, runOpenApiFlowAsyncOperation, isOpenApiFlowError, describeWorkflowConnectionApiRepair, } from '@openapi-flow/core';
 import { apiLiteralGenerationOptionsSchema, createApiLiteralGenerationOutputSchema, } from '../schemas/api-literal-generation-output-schema.js';
-import { apiArgumentsPrompt } from '../prompts/api-arguments-prompt.js';
+import { apiArgumentsPrompt, apiArgumentReplanningPrompt, } from '../prompts/api-arguments-prompt.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 import { interpretApiArgumentEnums } from './interpret-api-argument-enums.js';
 import { invokeStructuredModel } from '../model/invoke-structured-model.js';
+import { resolveApiLiteralGenerationOutput } from './resolve-api-literal-generation-output.js';
+import { apiArgumentRejectionsSchema } from '../schemas/api-argument-rejection-schema.js';
+import { fingerprintApiArgumentSource } from './fingerprint-api-argument-source.js';
+import { rethrowApiArgumentPlanningError } from './api-argument-planning-error.js';
+import { modelSignalSchema } from '../schemas/model-signal-schema.js';
+import { apiMaterialRepairPrompt } from '../prompts/api-material-repair-prompt.js';
+import { attributeApiLiteralGenerationSources } from './attribute-api-literal-generation-sources.js';
+import { assertApiArgumentGenerationSource } from './assert-api-argument-generation-source.js';
 export async function generateApiArguments(input) {
-    const { options, snapshot, contract, context, trackInputs, schema } = runOpenApiFlowOperation({
+    const { options, snapshot, contract, context, trackInputs, schema, sourceFingerprint, rejectedProposals, materialRepair, } = runOpenApiFlowOperation({
         owner: 'langchain',
         operation: 'generateApiArguments',
         stage: 'input-validation',
         code: 'PLANNING_INPUT_INVALID',
     }, () => {
+        modelSignalSchema.parse(input.signal);
         if (input.model !== undefined &&
-            (!input.model ||
-                typeof input.model.withStructuredOutput !== 'function'))
+            (!input.model || typeof input.model.withStructuredOutput !== 'function'))
             throw new Error('generateApiArguments.model must support structured output when supplied');
         if (typeof input.callId !== 'string' || !input.callId.trim())
             throw new Error('callId must be non-empty');
@@ -24,61 +32,113 @@ export async function generateApiArguments(input) {
             trackRequestedInputs: input.trackRequestedInputs,
         });
         const { input: snapshot, contract, context, } = describeApiLiteralGeneration(input);
+        const materialRepair = input.materialRepair === undefined
+            ? undefined
+            : describeWorkflowConnectionApiRepair({
+                stage: 'api-arguments',
+                repair: input.materialRepair,
+                planning: input,
+            });
         const trackInputs = options.trackRequestedInputs === true ||
-            options.selectOasEnums === true;
-        const schema = createApiLiteralGenerationOutputSchema(contract, options.includeExplanations === true, trackInputs ? createApiRequestSchema(snapshot) : undefined);
+            options.selectOasEnums === true ||
+            snapshot.literalSourceMessages !== undefined ||
+            materialRepair !== undefined;
+        const schema = createApiLiteralGenerationOutputSchema(contract, options.includeExplanations === true, trackInputs ? createApiRequestSchema(snapshot) : undefined, snapshot.literalSourceMessages);
+        const sourceFingerprint = fingerprintApiArgumentSource(snapshot, options, materialRepair);
+        const rejectedProposals = input.rejectedProposals === undefined
+            ? undefined
+            : apiArgumentRejectionsSchema.parse(input.rejectedProposals);
+        if (rejectedProposals?.some((item) => item.sourceFingerprint !== sourceFingerprint))
+            throw new Error('API argument rejection feedback belongs to a different source');
+        if (!contract.hasLiteralInputs && rejectedProposals?.length)
+            throw new Error('API argument rejection feedback requires a literal model decision');
         if (contract.hasLiteralInputs && !input.model)
             throw new Error('generateApiArguments.model must support structured output when literal inputs remain');
-        return { options, snapshot, contract, context, trackInputs, schema };
+        return {
+            options,
+            snapshot,
+            contract,
+            context,
+            trackInputs,
+            schema,
+            sourceFingerprint,
+            rejectedProposals,
+            materialRepair,
+        };
     });
-    let proposed = {
-        values: {},
-        ...(trackInputs ? { requestedInputs: [], literalSources: [] } : {}),
-    };
+    let proposed = trackInputs
+        ? { literalInputs: { state: 'not-provided' }, requestedInputs: [] }
+        : { values: {} };
     if (contract.hasLiteralInputs) {
         const model = input.model;
         if (!model || typeof model.withStructuredOutput !== 'function')
             throw new Error('generateApiArguments.model must support structured output when literal inputs remain');
-        proposed = await invokeStructuredModel({
-            model,
-            schema,
-            operation: 'generateApiArguments',
-            name: 'generate_api_arguments',
-            method: 'functionCalling',
-            // Preserve the existing provider-default strictness of literal generation.
-            strict: undefined,
-            messages: [
-                new SystemMessage(apiArgumentsPrompt),
-                new HumanMessage(JSON.stringify({
-                    ...context,
-                    ...(options.selectOasEnums === true
-                        ? { selectOasEnums: true }
-                        : {}),
-                })),
-            ],
-        });
+        try {
+            proposed = await invokeStructuredModel({
+                model,
+                schema,
+                operation: 'generateApiArguments',
+                name: 'generate_api_arguments',
+                method: 'functionCalling',
+                // Preserve the existing provider-default strictness of literal generation.
+                strict: undefined,
+                signal: input.signal,
+                messages: [
+                    new SystemMessage([
+                        apiArgumentsPrompt,
+                        ...(rejectedProposals === undefined
+                            ? []
+                            : [apiArgumentReplanningPrompt]),
+                        ...(materialRepair === undefined
+                            ? []
+                            : [apiMaterialRepairPrompt]),
+                    ].join('\n')),
+                    new HumanMessage(JSON.stringify({
+                        ...context,
+                        ...(rejectedProposals === undefined ? {} : { rejectedProposals }),
+                        ...(materialRepair === undefined ? {} : { materialRepair }),
+                        ...(options.selectOasEnums === true
+                            ? { selectOasEnums: true }
+                            : {}),
+                    })),
+                ],
+            });
+        }
+        catch (error) {
+            const cause = isOpenApiFlowError(error) ? error.cause : undefined;
+            // The parser's documented raw output is retained as-is, never parsed/repaired from its message.
+            const output = typeof cause === 'object' &&
+                cause !== null &&
+                Object.getOwnPropertyDescriptor(cause, 'lc_error_code')?.value ===
+                    'OUTPUT_PARSING_FAILURE'
+                ? Object.getOwnPropertyDescriptor(cause, 'llmOutput')?.value
+                : undefined;
+            rethrowApiArgumentPlanningError(error, sourceFingerprint, output);
+        }
     }
+    let interpretingEnums = false;
     return runOpenApiFlowAsyncOperation({
         owner: 'langchain',
         operation: 'generateApiArguments',
         stage: 'contract-validation',
         code: 'API_ARGUMENT_VALIDATION_FAILED',
     }, async () => {
-        const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
+        assertApiArgumentGenerationSource(input, snapshot, materialRepair);
+        const output = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
+        const parsed = resolveApiLiteralGenerationOutput(output);
         const values = applyConfirmedApiInputs({
             ...snapshot,
             values: parsed.values,
         });
-        const requestedInputs = 'requestedInputs' in parsed ? parsed.requestedInputs : undefined;
-        const literalSources = 'literalSources' in parsed
+        const requestedInputs = parsed.requestedInputs;
+        const literalSources = parsed.literalSources !== undefined
             ? resolveApiLiteralProposalSources({
                 callId: snapshot.callId,
                 values: parsed.values,
-                sources: parsed.literalSources.map((source) => ({
-                    ...source,
-                    messageId: 'scenario',
-                })),
-                messages: [{ id: 'scenario', text: snapshot.scenario }],
+                sources: attributeApiLiteralGenerationSources(snapshot, parsed.literalSources),
+                messages: snapshot.literalSourceMessages === undefined
+                    ? [{ id: 'scenario', text: snapshot.scenario }]
+                    : snapshot.literalSourceMessages,
             })
             : undefined;
         const inspection = inspectApiArgumentRequirements({
@@ -100,7 +160,7 @@ export async function generateApiArguments(input) {
                 ? {
                     literalGeneration: createApiLiteralGenerationRecord({
                         ...snapshot,
-                        ...('explanation' in parsed
+                        ...(parsed.explanation !== undefined
                             ? {
                                 proposal: { values: parsed.values },
                                 reason: parsed.explanation.reason,
@@ -113,15 +173,23 @@ export async function generateApiArguments(input) {
         if (options.selectOasEnums === true) {
             if (literalSources === undefined)
                 throw new Error('generateApiArguments enum interpretation requires source-verified literalSources');
-            return interpretApiArgumentEnums({
+            interpretingEnums = true;
+            const interpreted = await interpretApiArgumentEnums({
                 ...snapshot,
                 ...options,
                 arguments: result,
                 proposal: { values: parsed.values },
                 literalSources,
                 model: input.model,
+                signal: input.signal,
             });
+            assertApiArgumentGenerationSource(input, snapshot, materialRepair);
+            return interpreted;
         }
         return result;
+    }).catch((error) => {
+        if (interpretingEnums || !contract.hasLiteralInputs)
+            throw error;
+        rethrowApiArgumentPlanningError(error, sourceFingerprint, proposed);
     });
 }

package/dist/arguments/interpret-api-argument-enums.js

@@ -13,6 +13,7 @@ export async function interpretApiArgumentEnums(input) {
         ...context,
         model: input.model,
         includeExplanations: input.includeExplanations,
+        signal: input.signal,
     });
     const resolved = resolveApiArgumentEnumInterpretation({
         ...material,

package/dist/arguments/resolve-api-literal-generation-output.d.ts

@@ -0,0 +1,3 @@
+import type { ApiLiteralGenerationOutput, ResolvedApiLiteralGenerationOutput } from '../types/argument-generation.js';
+/** Only an explicit absence decision produces empty values; supplied empty literals are never removed. */
+export declare function resolveApiLiteralGenerationOutput(output: ApiLiteralGenerationOutput): ResolvedApiLiteralGenerationOutput;

package/dist/arguments/resolve-api-literal-generation-output.js

@@ -0,0 +1,14 @@
+/** Only an explicit absence decision produces empty values; supplied empty literals are never removed. */
+export function resolveApiLiteralGenerationOutput(output) {
+    if ('literalInputs' in output) {
+        const literals = output.literalInputs;
+        return {
+            ...(literals.state === 'not-provided'
+                ? { values: {}, literalSources: [] }
+                : { values: literals.values, literalSources: literals.literalSources }),
+            requestedInputs: output.requestedInputs,
+            ...('explanation' in output ? { explanation: output.explanation } : {}),
+        };
+    }
+    return output;
+}

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

@@ -1,4 +1,4 @@
-import { describeApiBindingPlanning, validateApiCallBindingPlan, assembleApiBindingPlan, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { describeApiBindingPlanning, validateApiCallBindingPlan, assembleApiBindingPlan, runOpenApiFlowOperation, isOpenApiFlowError, } from '@openapi-flow/core';
 import { apiBindingCallExecutionSchema } from '../schemas/api-call-binding-plan-schema.js';
 import { selectApiBindingSources } from './select-api-binding-sources.js';
 import { planApiCallBindings } from './plan-api-call-bindings.js';
@@ -59,8 +59,17 @@ export async function planApiBindingsByCall(input) {
                 results.set(result.callId, result);
             }
             catch (error) {
-                if (!failed)
-                    failure = error;
+                if (!failed) {
+                    // This aggregate API historically returns the caller's exact cancellation reason.
+                    // A late structured result must not change that public cancellation contract.
+                    failure =
+                        input.signal?.aborted &&
+                            isOpenApiFlowError(error) &&
+                            error.diagnostic.code === 'MODEL_ABORTED' &&
+                            error.cause === input.signal.reason
+                            ? input.signal.reason
+                            : error;
+                }
                 failed = true;
             }
         }

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

@@ -1,12 +1,13 @@
 import { isDeepStrictEqual } from 'node:util';
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { describeApiCallBindingPlanning, resolveApiBindingSourceSelection, resolveApiCallBindingPlan, listApiResponsePointers, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { describeApiCallBindingPlanning, resolveApiBindingSourceSelection, resolveApiCallBindingPlan, listApiResponsePointers, runOpenApiFlowOperation, describeWorkflowConnectionApiRepair, } from '@openapi-flow/core';
 import { createApiCallBindingPlanSchema } from '../schemas/api-call-binding-plan-schema.js';
 import { apiCallBindingsPrompt } from '../prompts/api-call-bindings-prompt.js';
 import { invokeStructuredModel } from '../model/invoke-structured-model.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { apiMaterialRepairPrompt } from '../prompts/api-material-repair-prompt.js';
 export async function planApiCallBindings(input) {
-    const { description, sources } = runOpenApiFlowOperation({
+    const { description, sources, materialRepair } = runOpenApiFlowOperation({
         owner: 'langchain',
         operation: 'planApiCallBindings',
         stage: 'input-validation',
@@ -24,7 +25,14 @@ export async function planApiCallBindings(input) {
         });
         if (!isDeepStrictEqual(sources, expected))
             throw new Error('binding source selection changed or belongs to another call or source snapshot');
-        return { description, sources };
+        const materialRepair = input.materialRepair === undefined
+            ? undefined
+            : describeWorkflowConnectionApiRepair({
+                stage: 'api-bindings',
+                repair: input.materialRepair,
+                planning: input,
+            });
+        return { description, sources, materialRepair };
     });
     input.signal?.throwIfAborted();
     if (!sources.sourceNodeIds.length)
@@ -48,7 +56,9 @@ export async function planApiCallBindings(input) {
         strict: true,
         signal: input.signal,
         messages: [
-            new SystemMessage(apiCallBindingsPrompt),
+            new SystemMessage(materialRepair === undefined
+                ? apiCallBindingsPrompt
+                : [apiCallBindingsPrompt, apiMaterialRepairPrompt].join('\n')),
             new HumanMessage(JSON.stringify({
                 scenario: description.input.scenario,
                 target: description.target,
@@ -65,6 +75,7 @@ export async function planApiCallBindings(input) {
                     responsePointerCatalog: listApiResponsePointers(material.operation),
                 })),
                 nativeSources: description.input.nativeOutputs?.filter((source) => selected.has(source.nodeId)),
+                ...(materialRepair === undefined ? {} : { materialRepair }),
             })),
         ],
     });
@@ -74,9 +85,19 @@ export async function planApiCallBindings(input) {
         operation: 'planApiCallBindings',
         stage: 'contract-validation',
         code: 'API_BINDING_VALIDATION_FAILED',
-    }, () => resolveApiCallBindingPlan({
-        ...description.input,
-        sources,
-        proposal: parseStructuredOutput(schema, output, 'API call bindings'),
-    }));
+    }, () => {
+        if (materialRepair !== undefined &&
+            (input.materialRepair === undefined ||
+                !isDeepStrictEqual(materialRepair, describeWorkflowConnectionApiRepair({
+                    stage: 'api-bindings',
+                    repair: input.materialRepair,
+                    planning: input,
+                }))))
+            throw new Error('API material repair feedback changed during binding planning');
+        return resolveApiCallBindingPlan({
+            ...description.input,
+            sources,
+            proposal: parseStructuredOutput(schema, output, 'API call bindings'),
+        });
+    });
 }