@openapi-flow/langchain 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carefreelife98
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @openapi-flow/langchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.0**, with matching `@openapi-flow/core@0.3.0`. 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.0.md); this release does not rewrite OAS or values to hide it.
+
+`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.0` depends on matching core `0.3.0`.
+
+- `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.
+- `generateApiArguments`: propose one call's OAS-typed request values and report missing inputs.
+- `selectApiRequestMediaType`: choose among the full OAS body's declared formats using scenario-grounded structured output. Zero or one format needs no model call. Unspecified or ambiguous multiple-format requests use core's deterministic `selectDefaultApiRequestMediaType`: JSON, then form-urlencoded, then other concrete keys, then wildcard keys; ties use code-point order. Only declared formats can be chosen, explicit choices remain intact and invalid model output still fails.
+- Requests with no remaining literal inputs return empty values without invoking the model, including fully bound nested closed bodies and whole-body bindings. OAS-permitted additional properties remain potential literal inputs.
+- `planWorkflowGraph`: selected API contracts/values and registered native capabilities → typed native settings, conditions/assertions, explicit DAG edges/starts and gaps.
+- `planReviewableWorkflowGraph`: ready/blocked API materials + identified gaps + native capabilities → a validated internal DAG retaining unresolved steps. Structured output contains `additionalNativeNodes`, `edges`, `additionalGaps` and `blockedCalls`; the returned plan's `nativeNodes` combines fixed prepared materials and new additions. Core derives roots and validates all references. Gap IDs have ports but no fabricated API output. Calls dependent on unavailable scenario work must be explicitly blocked; nonexistent API values/code are never invented. Graph array order does not define execution order.
+
+Argument generation uses core's `createApiArgumentGenerationContract` for both the structured-output schema and `literalInputSchema` in the HumanMessage. It does not send the original parameter/body definitions or the binding plan to that model stage. Forbidden bound paths may appear as negative schema constraints, never as available inputs. Invalid proposals fail schema parsing rather than being repaired or silently trimmed. This literal-ownership contract is separate from the unchanged OAS contract used after runtime values are assembled.
+
+The host supplies a LangChain chat model. No model endpoint, Chomsky adapter, agent loop, LangGraph checkpoint storage or n8n connection is created internally. These functions use named message classes and Zod output schemas with field descriptions. The host can place each invocation in its own LangGraph node and control retries/HITL. Plan bindings before literal arguments so response-supplied fields are not invented as constants. Final graph planning uses these dependencies together with scenario-required order and conditions.
+
+This package depends on core and has a LangChain peer dependency; it does not depend on n8n. The graph schema is built from host-provided capability schemas. The planner validates executable proposals without repairing them; gap proposals remain non-executable and are returned for host review. It does not generate JavaScript, credential data, deployment origins or API-node JSON. Old single/linear planning functions live under `/legacy`; full generation compositions are private workspace examples, not this package's main API.
+
+Binding gap output now requires `{ callId, targetPointer, description }`, not a description alone. Each target must exist in the request OAS. Assignment validation still runs on gap reports, so invalid bindings cannot be disguised as unmet requirements. The host decides whether to fail immediately or prepare a review workflow.
+
+`planApiBindings` owns requested producer-to-request dependencies, not independent literal values. Calls without dependencies return `bindings: []`; absent dependencies are not failures. `gaps: []` means no requested dependency is blocked. Only an unavailable producer, an incompatible source contract or an unsupported explicitly requested transformation belongs in a binding gap. Independent literals (whether supplied or missing) belong to `generateApiArguments`; missing API capabilities belong to selection. These ownership rules are included in both the prompt and the field descriptions sent to the model. Validators check structural and OAS contracts, not the truth of free-text descriptions: genuine gaps remain blocked, and model-reported gaps are never silently discarded by a text heuristic.
+
+Each API material sent by `planApiBindings` also includes core's `responsePointerCatalog`: code-derived body paths, declared types/descriptions and dynamic boundaries, alongside the unchanged full OAS contract. The model still chooses dependencies and source pointers; exact declared paths are supplied instead of requiring it to reconstruct those paths from the large contract alone. Response keys in the context are OAS metadata, not expected statuses to plan. The output remains `ApiBindingPlan`; no output-repair or pointer whitelist is added. This improves the available evidence but does not guarantee model choice or actual field presence.
+
+`planNativeNodes` similarly reports unmet native behavior only. Selected API calls are OAS-backed materials compiled separately, not native HTTP capability choices. Deferred API argument generation, response-to-request binding and connection planning are not native gaps. This boundary is explicit in its prompt and field descriptions; it does not bypass contract validation or infer whether a free-text gap is true.
+
+Native proposal schemas now use capability-owned `createPlanningParametersSchema({ apiCallIds })` hooks when supplied. Built-in n8n IF/assertion schemas constrain response IDs to actual supplied call instances; the model's capability context receives the same specialized schema. The two combined graph planners use this boundary too. With zero API calls, response operands are absent, not an empty enum. Custom capabilities without a hook retain their own schema without field-name rewriting. After proposal parsing, `planNativeNodes` validates declared API response references before returning a native plan; custom references and per-port dependencies receive the same check. Prepared native references also fail before native/connection model invocation. Schema errors remain `proposal-schema` failures with the original proposal; a custom schema-valid but unknown response ID fails `node-validation`. No value correction, defaulting or retry is introduced. ID membership does not replace the later dependency-route or source-response checks.
+
+Discovery selection cannot produce `insufficient_contract` from metadata-only candidates. Model gap output has only `description`; the library assigns `missing_operation`. Detailed input and response limitations belong to stages that read full contracts. Review output omits known empty `blockedCalls`/`additionalNativeNodes` fields; code adds those constants only when the supplied context proves they are empty. Dynamic fields remain required. Real LangChain wire schemas are checked against the JSON Schema meta-schema, including all-blocked and empty-registry contexts.
+
+See the [workspace guide](https://github.com/carefreelife98/openapi-flow#independent-stages). Our code is MIT-licensed; dependency terms remain separate.
+
+Both graph planners accept optional `preparedNativeNodes`. These are fixed materials, not model output: their IDs/parameters and implementation-owned input/output ports are supplied explicitly while the model plans connections. Prepare such producers before binding/argument generation, deriving their schemas with core's `createNativeOutputContracts`. The model's `additionalNativeNodes` contains new nodes only, or `[]` if no addition is needed; the ambiguous old model field `nativeNodes` is not accepted as an alias. Repeating a prepared ID, guessing a producer, changing parameters through a coercing/defaulting schema or bypassing a required producer fails validation. Native output contracts must come from registered capability implementations, never model-generated declarations. Planning errors retain the raw model output, stage and original validation cause; hosts own persistence/privacy and retry policy.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,3 @@
+# Third-party notices
+
+This package depends on `@openapi-flow/core` and Zod and uses `@langchain/core` as a peer dependency. It does not depend on the n8n workflow SDK. Dependencies retain their own licenses; our MIT license applies only to openapi-flow's code.

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.d.ts

@@ -0,0 +1,3 @@
+import type { ApiCallArguments } from '@openapi-flow/core';
+import type { GenerateApiArgumentsInput } from '../types/argument-generation.js';
+export declare function generateApiArguments(input: GenerateApiArgumentsInput): Promise<ApiCallArguments>;

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

@@ -0,0 +1,60 @@
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+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 { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+export async function generateApiArguments(input) {
+    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 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(context)),
+        ]);
+    }
+    const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
+    const values = applyConfirmedApiInputs({
+        ...snapshot,
+        values: parsed.values,
+    });
+    const validation = validateApiArguments({ ...snapshot, values });
+    return {
+        callId: snapshot.callId,
+        values,
+        bindings: structuredClone(snapshot.bindings),
+        unresolvedInputs: validation.missingInputs,
+        ...(snapshot.requestMediaType === undefined
+            ? {}
+            : { 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.d.ts

@@ -0,0 +1,2 @@
+import type { SelectApiRequestMediaTypeInput } from '../types/request-media-selection.js';
+export declare function selectApiRequestMediaType(input: SelectApiRequestMediaTypeInput): Promise<string | undefined>;

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

@@ -0,0 +1,10 @@
+import { analyzeApiRequestMediaType } from './analyze-api-request-media-type.js';
+export async function selectApiRequestMediaType(input) {
+    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.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingPlan } from '@openapi-flow/core';
+import type { PlanApiBindingsInput } from '../types/binding-planning.js';
+export declare function planApiBindings(input: PlanApiBindingsInput): Promise<ApiBindingPlan>;

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

@@ -0,0 +1,50 @@
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+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);
+    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',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(apiBindingsPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    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: snapshot.materials,
+        nativeOutputs: snapshot.nativeOutputs,
+    });
+    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>;