@openapi-flow/langchain 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,128 @@
 # @openapi-flow/langchain
 
-Independent model calls for OpenAPI workflows. Unreleased `0.2.0` source; this package is not yet published.
+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.1**, with matching `@openapi-flow/core@0.3.1`. The host supplies its LangChain model and owns LangGraph, storage and review policies. The Core/n8n Ajv `properties.__proto__` validation limitation is documented in the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.1.md); this release does not rewrite OAS or values to hide it.
+
+`planWorkflowConnections` forwards explicit current `deferredApiInputIds`. Code derives their original slot contracts, validates existing request values and checks the complete graph; the model chooses connections, not replacement values. See [input deferral](https://github.com/carefreelife98/openapi-flow/blob/main/docs/deferred-connection-planning.md).
+
+`analyzeWorkflowDraftEdit` offers `report-capability-gap` in its existing
+bounded semantic call. The model selects a role, scoped finding and mandatory
+reason; Core owns IDs, original messages and inventory capture. No separate gap
+agent, parameter-generation call, retry or synthesized contract is introduced.
+See the [gap contract](../../docs/workflow-draft-conversation-host.md#explicit-capability-gaps).
+
+`generateWorkflowDraftApiCallArguments({ trackRequestedInputs: true })`
+asks for requested input pointers in the existing OAS-typed value call, including
+optional literals whose actual value is not known. Core checks declaration and
+presence; no extra model call, invented value or changed OAS required list is used.
+See [requested inputs](../../docs/workflow-draft-api-binding-questions.md#값이-미정인-선택-입력의-요청-추적).
+
+`selectWorkflowDraftApiBindingInputs` selects only requested
+response-to-request target pointers before producer mapping. Passing its
+`inputIntent` to `planWorkflowDraftApiCallBindings` narrows both the model-visible
+target contracts and the output schema. An empty selection makes no binding-model
+call; required literals remain the argument stage responsibility. These primitives
+remain independently callable. See [input intent](../../docs/workflow-draft-api-binding-questions.md#요청-의도를-먼저-고정하는-선택-단계).
+
+`analyzeApiInputAnswers` always returns code-checked `sources` for
+revalidation; model reasons remain optional. The canonical example supports
+[natural input replies](../../docs/canonical-natural-input-replies.md).
+
+`analyzeWorkflowDraftEdit` offers `restore-requirement` only for
+code-derived removed IDs. See
+[requirement restoration](../../docs/workflow-draft-requirement-restoration.md).
+
+`analyzeApiInputAnswers` selects code-owned JSON candidate IDs or
+unquoted text-boundary IDs. The model writes neither values nor `sourceText`;
+Core resolves original spans and validates them without coercion. See the
+[answer extraction guide](../../docs/api-input-answer-extraction.md).
+
+`planWorkflowGraph` and `planReviewableWorkflowGraph` accept
+`includeExplanations: true` for same-call strategy, native-instance and edge reasons,
+with separate code-owned source/verification records. Explicitly empty native
+registries support API-only plans without requesting impossible node fields.
+See the [combined graph guide](../../docs/graph-planning-records.md).
+
+`planWorkflowConnections({ includeExplanations: true })` returns the
+original execution plan plus separate per-new-edge/blocked-call reasons and
+code-owned source receipts. No explanation-only call is added. The two combined
+node-and-graph planners have their own explanation contract. See the
+[connection planning guide](../../docs/connection-planning-records.md).
+
+`planNativeNodes({ includeExplanations: true })` records same-call reasons
+for each new instance or an explicit no-additions decision. Code attaches the source
+context and implementation receipts. Runtime-enabled model contracts choose an
+explicit `parameterSource`; code derives empty runtime parameters/flags, never from
+placeholder text. See [native planning records](../../docs/native-planning-records.md).
+
+`planApiBindings({ includeExplanations: true })` asks for a short reason
+per call in the existing strict function call. Original gap descriptions remain
+their reasons; code owns the supplied-contract evidence in `bindingPlanning`.
+Executable `calls[].bindings` contain no audit metadata. See
+[binding planning records](../../docs/binding-planning-records.md).
+
+`generateApiArguments({ includeExplanations: true })` adds a same-call
+short reason and a code-owned `literalGeneration` record for the original proposal,
+not the final values after confirmed-input merge. Optional `purpose` scopes repeated
+API roles. No remaining literals means zero calls and no required model; otherwise
+a supplied structured-output model is required. See
+[literal records and source boundaries](../../docs/literal-generation-records.md).
+
+`analyzeApiRequestMediaType` returns the typed origin/resolution record,
+with optional same-call reasons and code-attached original scenario/requestBody
+evidence. Zero/one format needs no model; explicit null alone uses the existing
+documented default. `selectApiRequestMediaType` remains the string-only projection
+of the same implementation. Choose one API, not both in sequence. See
+[request format decisions](../../docs/request-media-decisions.md).
+
+`selectApiOperations` and `analyzeApiSelection` accept optional
+`includeExplanations: true`. The same call returns only a short reason per decision;
+core attaches the exact scenario and chosen/alternative/full discovery inventory.
+Omission preserves the standalone selector's existing non-explanation output.
+This is discovery provenance, not full OAS contract or semantic correctness proof.
+See [API selection explanations](../../docs/api-selection-explanations.md).
+
+selected-API binding questions now emit typed current-input pointers and
+actual source alternatives, not free-form questions or claims about missing OAS.
+Core renders/validates the question and resolves explicit human choices without
+another model call. See [scoped binding questions](../../docs/workflow-draft-api-binding-questions.md).
+
+`suggestWorkflowReviewFollowUps` makes one bounded structured-output call
+for the actual current HITL boundary. The model proposes optional messages and source
+references; core owns identities, evidence text and explicit adoption. No suggestion
+becomes intent or a graph patch without a human action. See [the contract](../../docs/workflow-review-suggestions.md).
+
+`planWorkflowDraftApiCallBindings` and `generateWorkflowDraftApiCallArguments`
+separate one selected API instance's source choices from OAS-typed literal extraction.
+Code-known mappings and fully owned inputs require no model-generated constants.
+Optional literal extraction uses function calling with unchanged local validation,
+not strict output that would force absent OAS values. See the
+[API addition/replacement guide](../../docs/workflow-draft-api-call-planning.md).
+
+`generateWorkflowDraftNativeNodeAddition` configures one code-identified `add-native-node` step with the actual registered schema. Optional `selectWorkflowDraftNativeNodeParameterOwnership` separates explicit field ownership from typed remaining values, so hosts can checkpoint/review between calls. Entirely deferred or fixed strict-empty settings need no value model. Evidence selects actual IDs instead of generated quotations. Connection planning and host review remain separate. See [native additions](../../docs/workflow-draft-native-node-addition.md).
+
+`planWorkflowDraftNativeReferenceRepair` uses one bounded call for an actual native consumer task. Model output contains only code-keyed source decisions or questions; core owns reference locations, patches and validation. See the [native repair contract](../../docs/workflow-draft-native-reference-repairs.md). Material-dependent registry refresh and complete conversational composition remain unfinished.
+
+`selectWorkflowDraftNativeParameterEditTargets` and `generateWorkflowDraftNativeParameterEdits` split an existing native revision into target choice and typed parameter values. Core owns schemas, identity and deterministic patches; removal/explicit field-deferral work needs no value call. Opted-in field deferral preserves unrelated literals/owners, and set transfers only the selected owner back to a literal. See the [native parameter-edit contract](../../docs/workflow-draft-native-parameter-edits.md). New draft-native instances use their separate ownership/value stages. Independent hosts can use `selectNativeNodeInstances` followed by `generateNativeNodeParameters` for mixed-field planning without constructing a fake draft. Each invocation is separately checkpointable; no nested planning calls are hidden in the compact planner.
+
+`planWorkflowDraftConnectionEdit` makes one bounded connection-delta call only after actual material results and consumer repairs resolve. Its schema constrains real endpoint/port pairs and editable existing edges; code validates the full candidate DAG. Retained edges and parameter values are not regenerated. See the [connection-edit contract](../../docs/workflow-draft-connection-edits.md); material-dependent native repairs, new-instance models and full conversational host integration remain unfinished.
+
+`planWorkflowDraftApiBindingEdit` makes one bounded source/ownership decision call for a pending reference-edit step or a code-derived consumer repair. Core re-derives staged authority, preserves unrelated mappings and values, and rejects stale/unknown sources or incompatible declarations without transforming data. Unknown producer choices return scoped questions, not a partial applied edit. Literal displacement is an explicit `replace-literal-with-binding` decision. See the [binding edit/staging contract](../../docs/workflow-draft-api-binding-edits.md); connection/native edits use separate stages. Material-dependent native repair, new-instance composition and host review/resume remain unfinished.
+
+`selectWorkflowDraftApiInputEditTargets` and `generateWorkflowDraftApiInputEdits` split an existing literal edit into target selection and OAS-typed actual-value extraction. Core owns field schemas/IDs, exact source checks and deterministic patches; unchanged values are preserved. Missing actual values return `needs-input` without a partial resolution; removals need no value call. Hosts can review between the two calls or supply structured targets/values directly through core. See the [scoped input-edit contract](../../docs/workflow-draft-api-input-edits.md). Binding, connection and native edits use separate stages; registry refresh, new-instance models and complete LangGraph composition remain unfinished.
+
+`analyzeWorkflowDraftEdit` makes one bounded call for semantic change decisions, supplied candidates and existing targets. Core resolves original OAS identities and validates exact current-request provenance, stale state and code-owned IDs. Values, settings, bindings, connections and atomic application remain separate stages. No whole-workflow regeneration or automatic retry is added. See the [edit analysis boundary and remaining composition](../../docs/workflow-draft-edit-analysis.md).
+
+`planNativeNodes({ ..., allowRuntimeParameters: true })` offers explicit runtime parameter ownership only for implementing capabilities. One schema/material factory supplies both the output alternatives and HumanMessage `parameterSources`, so the model receives the same contract it may return. Omission stays literal-only; the model never supplies runtime slot IDs or schemas. Older combined planning compositions do not automatically forward this option. See the [native runtime input contract](../../docs/native-runtime-inputs.md).
+
+`generateNativeNodeParameters` can resume a `needs-clarification` result with `replies: [{ question, text }]`, retaining the same selected role, original scenario and source snapshot. Append another pair for each actual follow-up; stale or out-of-order questions fail before invocation. The model receives validated question/reply data separately and still returns only the same typed setting decision. It does not repeat capability selection or acquire graph/ownership authority. The [native setting reply guide](../../docs/native-runtime-inputs.md#answering-a-selected-instances-questions) shows the host boundary.
+
+`clarifyWorkflowRequirements({ model, context, limits, options? })` makes one described structured-output call for user-grounded requirements and necessary categorized questions. Optional explanations/suggestions are removed from the output schema when disabled. Core validates exact source references and allocates identities; the output has no runtime argument values and does not automatically adopt suggestions. Official Zod inline serialization owns the wire schema while the original Zod schema validates the response. See the [clarification contract](https://github.com/carefreelife98/openapi-flow/blob/main/docs/workflow-requirements-clarification.md). This does not add a host graph or guarantee model semantic accuracy.
+
+source additions provide `analyzeApiSelection` and `extractApiInputAnswers`. The former separates consequential API-role choices from absent capabilities; the latter extracts only pending, OAS-typed answers and checks their complete value spans against the user's actual reply. Existing selectors remain available. These additions are not included in npm 0.2.0; see the [conversation guide](https://github.com/carefreelife98/openapi-flow/blob/main/docs/conversational-generation.md).
+
+Independent model calls for OpenAPI workflows. Version `0.3.1` depends on matching core `0.3.1`.
 
 - `selectApiOperations`: choose catalog candidates and describe capability gaps with structured output.
 - `planApiBindings`: selected OAS contracts and optional declared `nativeOutputs` → output-to-request pointer bindings and request-data gaps, independently of native control-flow planning. API pointers read response bodies; native pointers read the declared JSON output. Neither changes value types or semantics.

package/dist/arguments/analyze-api-input-answers.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputAnswerAnalysis } from '@openapi-flow/core';
+import type { AnalyzeApiInputAnswersInput } from '../types/api-input-answers.js';
+export declare function analyzeApiInputAnswers(input: AnalyzeApiInputAnswersInput): Promise<ApiInputAnswerAnalysis>;

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

@@ -0,0 +1,87 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { captureApiInputAnswerContext, createApiInputAnswerExtractionRecord, resolveApiInputAnswerSources, describeApiInputSources, resolveApiInputSourceSelections, } 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';
+export async function analyzeApiInputAnswers(input) {
+    const options = apiInputAnswerExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const snapshot = captureApiInputAnswerContext({
+        reply: input.reply,
+        requirements: input.requirements,
+    });
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('analyzeApiInputAnswers.model must support structured output when supplied');
+    if (!snapshot.requirements.length || snapshot.reply === '')
+        return {
+            status: snapshot.requirements.length
+                ? 'empty-reply'
+                : 'no-pending-inputs',
+            answers: [],
+            sources: [],
+            unansweredRequirementIds: snapshot.requirements.map((item) => item.id),
+        };
+    const catalog = describeApiInputSources(snapshot.reply);
+    if (!catalog.json.length && !catalog.text.length)
+        return {
+            status: 'extracted',
+            answers: [],
+            sources: [],
+            unansweredRequirementIds: snapshot.requirements.map((item) => item.id),
+        };
+    if (!input.model)
+        throw new Error('analyzeApiInputAnswers.model is required for a nonempty reply with pending inputs');
+    const schema = createApiInputAnswerSourceSchema(snapshot.requirements, catalog, options.includeExplanations === true);
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'extract_api_input_answers',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(apiInputAnswersPrompt),
+        new HumanMessage(JSON.stringify({
+            reply: snapshot.reply,
+            questions: snapshot.requirements,
+            sources: catalog,
+        })),
+    ]);
+    const parsed = parseStructuredOutput(schema, output, 'model clarification answer sources');
+    const selections = resolveApiInputSourceSelections({
+        ...snapshot,
+        selections: parsed.answers.map(({ requirementId, source }) => ({
+            requirementId,
+            source,
+        })),
+    });
+    const resolved = resolveApiInputAnswerSources({
+        ...snapshot,
+        selections,
+    });
+    let extraction;
+    if (options.includeExplanations === true) {
+        if (typeof parsed.reason !== 'string')
+            throw new Error('model clarification answer sources require an explanation');
+        extraction = createApiInputAnswerExtractionRecord({
+            ...snapshot,
+            decision: {
+                reason: parsed.reason,
+                answers: parsed.answers.map((source, index) => {
+                    if (typeof source.reason !== 'string')
+                        throw new Error(`model answer ${source.requirementId} requires an explanation`);
+                    return { ...selections[index], reason: source.reason };
+                }),
+            },
+        });
+    }
+    return {
+        status: 'extracted',
+        answers: resolved.answers,
+        sources: resolved.sources,
+        unansweredRequirementIds: resolved.unansweredRequirementIds,
+        ...(extraction === undefined ? {} : { extraction }),
+    };
+}

package/dist/arguments/analyze-api-request-media-type.d.ts

@@ -0,0 +1,4 @@
+import type { ApiRequestMediaTypeDecision } from '@openapi-flow/core';
+import type { AnalyzeApiRequestMediaTypeInput } from '../types/request-media-selection.js';
+/** One assessment call only for multiple formats; code owns resolution and sources. */
+export declare function analyzeApiRequestMediaType(input: AnalyzeApiRequestMediaTypeInput): Promise<ApiRequestMediaTypeDecision>;

package/dist/arguments/analyze-api-request-media-type.js

@@ -0,0 +1,50 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createApiRequestMediaTypeDecision, describeApiRequestMediaTypeContext, } from '@openapi-flow/core';
+import { createApiRequestMediaTypeSchema } from '../schemas/api-request-media-type-schema.js';
+import { requestMediaSelectionOptionsSchema } from '../schemas/request-media-selection-options-schema.js';
+import { apiRequestMediaTypePrompt } from '../prompts/api-request-media-type-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+/** One assessment call only for multiple formats; code owns resolution and sources. */
+export async function analyzeApiRequestMediaType(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const options = requestMediaSelectionOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const operation = structuredClone(input.operation);
+    const context = describeApiRequestMediaTypeContext({
+        operation,
+        scenario: input.scenario,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+    });
+    if (context.mediaTypes.length < 2)
+        return createApiRequestMediaTypeDecision({
+            operation,
+            scenario: context.scenario,
+            ...(context.purpose === undefined ? {} : { purpose: context.purpose }),
+        });
+    const schema = createApiRequestMediaTypeSchema(context.mediaTypes, options.includeExplanations === true);
+    const proposed = await input.model
+        .withStructuredOutput(schema, {
+        name: 'select_api_request_media_type',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(apiRequestMediaTypePrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: context.scenario,
+            ...(context.purpose === undefined
+                ? {}
+                : { purpose: context.purpose }),
+            operation: context.operation,
+        })),
+    ]);
+    const assessment = parseStructuredOutput(schema, proposed, 'model API request media type');
+    return createApiRequestMediaTypeDecision({
+        operation,
+        scenario: context.scenario,
+        ...(context.purpose === undefined ? {} : { purpose: context.purpose }),
+        assessment,
+    });
+}

package/dist/arguments/extract-api-input-answers.d.ts

@@ -0,0 +1,3 @@
+import type { ApiInputAnswer } from '@openapi-flow/core';
+import type { ExtractApiInputAnswersInput } from '../types/api-input-answers.js';
+export declare function extractApiInputAnswers(input: ExtractApiInputAnswersInput): Promise<ApiInputAnswer[]>;

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

@@ -0,0 +1,4 @@
+import { analyzeApiInputAnswers } from './analyze-api-input-answers.js';
+export async function extractApiInputAnswers(input) {
+    return (await analyzeApiInputAnswers(input)).answers;
+}

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

@@ -1,45 +1,60 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { createApiArgumentGenerationContract, validateApiArguments, } from '@openapi-flow/core';
+import { describeApiLiteralGeneration, createApiLiteralGenerationRecord, validateApiArguments, applyConfirmedApiInputs, } from '@openapi-flow/core';
+import { apiLiteralGenerationOptionsSchema, createApiLiteralGenerationOutputSchema, } from '../schemas/api-literal-generation-output-schema.js';
 import { apiArgumentsPrompt } from '../prompts/api-arguments-prompt.js';
-import { assertSelectionInput } from '../legacy/planning/select-operation.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 export async function generateApiArguments(input) {
-    assertSelectionInput(input.scenario, input.model);
+    if (input.model !== undefined &&
+        (!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');
-    const contract = createApiArgumentGenerationContract(input);
-    const schema = contract.schema;
-    const proposed = contract.hasLiteralInputs
-        ? await input.model
+    const options = apiLiteralGenerationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, contract, context, } = describeApiLiteralGeneration(input);
+    const schema = createApiLiteralGenerationOutputSchema(contract, options.includeExplanations === true);
+    let proposed = { 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 model
             .withStructuredOutput(schema, {
             name: 'generate_api_arguments',
             method: 'functionCalling',
         })
             .invoke([
             new SystemMessage(apiArgumentsPrompt),
-            new HumanMessage(JSON.stringify({
-                scenario: input.scenario,
-                operation: {
-                    key: input.operation.key,
-                    method: input.operation.method,
-                    path: input.operation.path,
-                    summary: input.operation.operation.summary,
-                    description: input.operation.operation.description,
-                },
-                literalInputSchema: contract.literalInputSchema,
-                requestMediaType: input.requestMediaType,
-            })),
-        ])
-        : { values: {} };
-    const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${input.callId}`);
-    const validation = validateApiArguments({ ...input, values: parsed.values });
-    return {
-        callId: input.callId,
+            new HumanMessage(JSON.stringify(context)),
+        ]);
+    }
+    const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
+    const values = applyConfirmedApiInputs({
+        ...snapshot,
         values: parsed.values,
-        bindings: structuredClone(input.bindings),
+    });
+    const validation = validateApiArguments({ ...snapshot, values });
+    return {
+        callId: snapshot.callId,
+        values,
+        bindings: structuredClone(snapshot.bindings),
         unresolvedInputs: validation.missingInputs,
-        ...(input.requestMediaType === undefined
+        ...(snapshot.requestMediaType === undefined
             ? {}
-            : { requestMediaType: input.requestMediaType }),
+            : { requestMediaType: snapshot.requestMediaType }),
+        ...(options.includeExplanations === true
+            ? {
+                literalGeneration: createApiLiteralGenerationRecord({
+                    ...snapshot,
+                    ...('explanation' in parsed
+                        ? {
+                            proposal: { values: parsed.values },
+                            reason: parsed.explanation.reason,
+                        }
+                        : {}),
+                }),
+            }
+            : {}),
     };
 }

package/dist/arguments/select-api-request-media-type.js

@@ -1,39 +1,10 @@
-import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { listApiRequestMediaTypes, selectDefaultApiRequestMediaType, } from '@openapi-flow/core';
-import { createApiRequestMediaTypeSchema } from '../schemas/api-request-media-type-schema.js';
-import { apiRequestMediaTypePrompt } from '../prompts/api-request-media-type-prompt.js';
-import { assertSelectionInput } from '../legacy/planning/select-operation.js';
-import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { analyzeApiRequestMediaType } from './analyze-api-request-media-type.js';
 export async function selectApiRequestMediaType(input) {
-    assertSelectionInput(input.scenario, input.model);
-    const mediaTypes = listApiRequestMediaTypes(input.operation);
-    if (input.operation.operation.requestBody === undefined)
-        return undefined;
-    if (mediaTypes.length === 0)
-        throw new Error(`${input.operation.key.operationRef}.requestBody.content has no request media type`);
-    if (mediaTypes.length === 1)
-        return mediaTypes[0];
-    const schema = createApiRequestMediaTypeSchema(mediaTypes);
-    const output = await input.model
-        .withStructuredOutput(schema, {
-        name: 'select_api_request_media_type',
-        method: 'functionCalling',
-        strict: true,
-    })
-        .invoke([
-        new SystemMessage(apiRequestMediaTypePrompt),
-        new HumanMessage(JSON.stringify({
-            scenario: input.scenario,
-            operation: {
-                key: input.operation.key,
-                method: input.operation.method,
-                path: input.operation.path,
-                requestBody: input.operation.operation.requestBody,
-            },
-        })),
-    ]);
-    const selected = parseStructuredOutput(schema, output, 'model API request media type');
-    if (selected.requestMediaType === null)
-        return selectDefaultApiRequestMediaType(input.operation);
-    return selected.requestMediaType;
+    const decision = await analyzeApiRequestMediaType({
+        operation: input.operation,
+        scenario: input.scenario,
+        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+        model: input.model,
+    });
+    return decision.requestMediaType;
 }

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

@@ -1,13 +1,16 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { validateApiBindingAssignments, validateApiBindingGaps, validateNativeOutputContracts, listApiResponsePointers, } from '@openapi-flow/core';
-import { createApiBindingPlanSchema } from '../schemas/api-binding-plan-schema.js';
+import { validateApiBindingAssignments, validateApiBindingGaps, describeApiBindingPlanning, createApiBindingPlanningRecord, } 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';
 export async function planApiBindings(input) {
     assertSelectionInput(input.scenario, input.model);
-    validateNativeOutputContracts(input.nativeOutputs ?? []);
-    const schema = createApiBindingPlanSchema(input.materials, input.nativeOutputs);
+    const options = apiBindingPlanningOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, context } = describeApiBindingPlanning(input);
+    const schema = createApiBindingPlanSchema(snapshot.materials, snapshot.nativeOutputs, options.includeExplanations === true);
     const proposed = await input.model
         .withStructuredOutput(schema, {
         name: 'plan_api_bindings',
@@ -16,28 +19,32 @@ export async function planApiBindings(input) {
     })
         .invoke([
         new SystemMessage(apiBindingsPrompt),
-        new HumanMessage(JSON.stringify({
-            scenario: input.scenario,
-            nativeOutputs: input.nativeOutputs,
-            materials: input.materials.map(({ operation, ...material }) => ({
-                ...material,
-                operation: {
-                    key: operation.key,
-                    method: operation.method,
-                    path: operation.path,
-                    operation: operation.operation,
-                    effective: operation.effective,
-                },
-                responsePointerCatalog: listApiResponsePointers(operation),
-            })),
-        })),
+        new HumanMessage(JSON.stringify(context)),
     ]);
-    const plan = parseStructuredOutput(schema, proposed, 'model API bindings');
+    const parsed = parseStructuredOutput(schema, proposed, 'model API bindings');
+    const plan = {
+        calls: parsed.calls.map(({ callId, bindings }) => ({
+            callId,
+            bindings: structuredClone(bindings),
+        })),
+        gaps: structuredClone(parsed.gaps),
+    };
     validateApiBindingAssignments({
         calls: plan.calls,
-        materials: input.materials,
-        nativeOutputs: input.nativeOutputs,
+        materials: snapshot.materials,
+        nativeOutputs: snapshot.nativeOutputs,
     });
-    validateApiBindingGaps({ plan, materials: input.materials });
+    validateApiBindingGaps({ plan, materials: snapshot.materials });
+    if (options.includeExplanations === true) {
+        plan.bindingPlanning = createApiBindingPlanningRecord({
+            ...snapshot,
+            plan,
+            reasons: parsed.calls.map((call) => {
+                if (!('reason' in call))
+                    throw new Error(`model API bindings are missing reason for ${call.callId}`);
+                return { callId: call.callId, reason: call.reason };
+            }),
+        });
+    }
     return plan;
 }

package/dist/draft/analyze-workflow-draft-edit.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowDraftEditPlan } from '@openapi-flow/core';
+import type { AnalyzeWorkflowDraftEditInput } from '../types/workflow-draft-edit.js';
+/** One semantic call. Resolution/values/bindings/edges and canonical mutation stay separate. */
+export declare function analyzeWorkflowDraftEdit(input: AnalyzeWorkflowDraftEditInput): Promise<WorkflowDraftEditPlan>;

package/dist/draft/analyze-workflow-draft-edit.js

@@ -0,0 +1,84 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createWorkflowDraftEditPlan, describeWorkflowDraftEditContext, resolveWorkflowDraftEditOptions, describeWorkflowDraftCapabilityGap, } from '@openapi-flow/core';
+import { createWorkflowDraftEditSchema } from '../schemas/workflow-draft-edit-schema.js';
+import { workflowDraftEditPrompt } from '../prompts/workflow-draft-edit-prompt.js';
+import { workflowUserActionEvidencePrompt } from '../prompts/workflow-user-action-evidence-prompt.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { WorkflowDraftEditPlanningError } from './workflow-draft-edit-planning-error.js';
+import { resolveWorkflowDraftEditProposal } from './resolve-workflow-draft-edit-proposal.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+/** One semantic call. Resolution/values/bindings/edges and canonical mutation stay separate. */
+export async function analyzeWorkflowDraftEdit(input) {
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('analyzeWorkflowDraftEdit.model must support structured output');
+    const context = describeWorkflowDraftEditContext(input);
+    const options = resolveWorkflowDraftEditOptions(input.options);
+    const candidates = context.planning.operations.map((operation, index) => ({
+        candidateId: `candidate-${index + 1}`,
+        operation,
+    }));
+    const schema = createWorkflowDraftEditSchema(context, options, candidates.map((candidate) => candidate.candidateId));
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-7', 'input', 'ref'), {
+        name: 'analyze_workflow_draft_edit',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowDraftEditPrompt + '\n' + workflowUserActionEvidencePrompt),
+        new HumanMessage(JSON.stringify({
+            requestMessageIds: context.requestMessageIds,
+            draft: {
+                requirements: context.draft.requirements,
+                removedRequirements: context.removedRequirements,
+                apiCalls: context.draft.apiCalls,
+                nativeNodes: context.draft.nativeNodes,
+                nodeContracts: context.nodeContracts,
+                ...(context.draft.gapNodes === undefined
+                    ? {}
+                    : {
+                        gapNodes: context.draft.gapNodes.map((gap) => describeWorkflowDraftCapabilityGap({
+                            gap,
+                            context: input.context,
+                        })),
+                    }),
+                edges: context.draft.edges,
+            },
+            messages: context.planning.messages,
+            candidates,
+            capabilities: context.planning.capabilities,
+            options,
+            ...(context.planning.clarification === undefined
+                ? {}
+                : { clarification: context.planning.clarification }),
+        })),
+    ]);
+    let proposed;
+    try {
+        proposed = parseStructuredOutput(schema, output, 'model draft edit');
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new WorkflowDraftEditPlanningError({ stage: 'proposal-schema', proposal: output }, cause);
+    }
+    try {
+        const plan = createWorkflowDraftEditPlan({
+            ...input,
+            options,
+            proposal: resolveWorkflowDraftEditProposal(proposed, candidates),
+        });
+        if (plan.draftFingerprint !== context.draftFingerprint ||
+            plan.contextFingerprint !== context.contextFingerprint ||
+            plan.nodeContractsFingerprint !== context.nodeContractsFingerprint ||
+            JSON.stringify(plan.requestMessageIds) !==
+                JSON.stringify(context.requestMessageIds))
+            throw new Error('Draft edit input changed during model invocation; no automatic rebase is permitted');
+        return plan;
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new WorkflowDraftEditPlanningError({ stage: 'proposal-validation', proposal: output }, cause);
+    }
+}

package/dist/draft/generate-workflow-draft-api-call-arguments.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowDraftApiCallArgumentsResult } from '@openapi-flow/core';
+import type { GenerateWorkflowDraftApiCallArgumentsInput } from '../types/workflow-draft-api-call-planning.js';
+export declare function generateWorkflowDraftApiCallArguments(input: GenerateWorkflowDraftApiCallArgumentsInput): Promise<WorkflowDraftApiCallArgumentsResult>;