@openapi-flow/langchain 0.2.0 → 0.3.1

package/dist/schemas/workflow-planning-evidence-schemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { WorkflowPlanningContextDescription } from '@openapi-flow/core';
+import type { ProposedWorkflowPlanningEvidence } from '../types/workflow-clarification.js';
+/** Model candidates are code-owned references, not model-built OAS keys or pointers. */
+export declare function createWorkflowPlanningEvidenceSchemas(context: WorkflowPlanningContextDescription, candidateIds: string[], sourceMessageIds: string[]): {
+    message: z.ZodPipe<z.ZodObject<{
+        kind: z.ZodLiteral<"message">;
+        messageId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+    }, z.core.$strict>, z.ZodTransform<{
+        quote: string;
+        kind: "message";
+        messageId: string;
+    }, {
+        kind: "message";
+        messageId: string;
+    }>>;
+    evidence: z.ZodType<ProposedWorkflowPlanningEvidence, unknown, z.core.$ZodTypeInternals<ProposedWorkflowPlanningEvidence, unknown>>;
+};

package/dist/schemas/workflow-planning-evidence-schemas.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { createWorkflowMessageEvidenceSelectionSchema } from './create-workflow-message-evidence-selection-schema.js';
+/** Model candidates are code-owned references, not model-built OAS keys or pointers. */
+export function createWorkflowPlanningEvidenceSchemas(context, candidateIds, sourceMessageIds) {
+    const message = (ids) => {
+        const selected = ids.map((id) => {
+            const source = context.messages.find((item) => item.id === id);
+            if (!source)
+                throw new Error(`Planning evidence references unavailable message ${id}`);
+            return source;
+        });
+        return createWorkflowMessageEvidenceSelectionSchema(selected);
+    };
+    const evidence = z.union([
+        message(context.messages.map((item) => item.id)),
+        ...(context.entrypoint === undefined
+            ? []
+            : [
+                z.strictObject({
+                    kind: z.literal('entrypoint'),
+                    entrypoint: z.literal(context.entrypoint.kind),
+                }),
+            ]),
+        ...(candidateIds.length
+            ? [
+                z.strictObject({
+                    kind: z.literal('oas'),
+                    candidateId: z
+                        .enum(candidateIds)
+                        .describe('Select a supplied operation; code attaches its original identity and root location.'),
+                }),
+            ]
+            : []),
+        ...(context.capabilities.length
+            ? [
+                z.strictObject({
+                    kind: z.literal('native'),
+                    capability: z.enum(context.capabilities.map((item) => item.name)),
+                }),
+            ]
+            : []),
+    ]);
+    return { message: message(sourceMessageIds), evidence };
+}

package/dist/schemas/workflow-requirements-schema.d.ts

@@ -0,0 +1,3 @@
+import type { ClarificationQuestionLimits, ResolvedWorkflowClarificationOptions, WorkflowPlanningContextDescription } from '@openapi-flow/core';
+import type { WorkflowClarificationOasCandidate } from '../types/workflow-clarification.js';
+export declare function createWorkflowRequirementsSchema(limits: ClarificationQuestionLimits, options: ResolvedWorkflowClarificationOptions, context: WorkflowPlanningContextDescription, candidates: WorkflowClarificationOasCandidate[]): import("zod").ZodType<import("@openapi-flow/core").WorkflowRequirementsProposal<import("../types/workflow-clarification.js").ProposedWorkflowPlanningEvidence>, unknown, import("zod/v4/core").$ZodTypeInternals<import("@openapi-flow/core").WorkflowRequirementsProposal<import("../types/workflow-clarification.js").ProposedWorkflowPlanningEvidence>, unknown>>;

package/dist/schemas/workflow-requirements-schema.js

@@ -0,0 +1,6 @@
+import { createWorkflowRequirementsProposalSchema } from '@openapi-flow/core';
+import { createWorkflowPlanningEvidenceSchemas } from './workflow-planning-evidence-schemas.js';
+export function createWorkflowRequirementsSchema(limits, options, context, candidates) {
+    const { message, evidence } = createWorkflowPlanningEvidenceSchemas(context, candidates.map((candidate) => candidate.candidateId), context.messages.map((item) => item.id));
+    return createWorkflowRequirementsProposalSchema(limits, options, evidence, message);
+}

package/dist/schemas/workflow-review-suggestions-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { WorkflowReviewSuggestionsDescription } from '@openapi-flow/core';
+import type { ProposedWorkflowReviewSuggestionEvidence } from '../types/workflow-review-suggestions.js';
+export declare function createWorkflowReviewSuggestionsSchema(description: WorkflowReviewSuggestionsDescription, candidateIds: string[]): z.ZodType<import("@openapi-flow/core").WorkflowReviewSuggestionsProposal<ProposedWorkflowReviewSuggestionEvidence>, unknown, z.core.$ZodTypeInternals<import("@openapi-flow/core").WorkflowReviewSuggestionsProposal<ProposedWorkflowReviewSuggestionEvidence>, unknown>>;

package/dist/schemas/workflow-review-suggestions-schema.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { createWorkflowReviewSuggestionsProposalSchema } from '@openapi-flow/core';
+import { createWorkflowPlanningEvidenceSchemas } from './workflow-planning-evidence-schemas.js';
+export function createWorkflowReviewSuggestionsSchema(description, candidateIds) {
+    const original = createWorkflowPlanningEvidenceSchemas(description.context, candidateIds, description.context.messages.map((message) => message.id));
+    const evidence = z.union([
+        original.evidence,
+        ...(description.boundary.questions.length
+            ? [
+                z.strictObject({
+                    kind: z.literal('review-question'),
+                    questionId: z.enum(description.boundary.questions.map((question) => question.id)),
+                }),
+            ]
+            : []),
+    ]);
+    return createWorkflowReviewSuggestionsProposalSchema(description, evidence);
+}

package/dist/selection/analyze-api-selection.d.ts

@@ -0,0 +1,4 @@
+import type { ApiSelectionAnalysis } from '@openapi-flow/core';
+import type { SelectApiOperationsInput } from '../types/operation-selection.js';
+/** Additive clarification boundary; the existing selector keeps its output contract. */
+export declare function analyzeApiSelection(input: SelectApiOperationsInput): Promise<ApiSelectionAnalysis>;

package/dist/selection/analyze-api-selection.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { describeApiSelectionContext, createApiSelectionExplanation, } from '@openapi-flow/core';
+import { createApiSelectionAnalysisSchema } from '../schemas/api-selection-analysis-schema.js';
+import { apiSelectionAnalysisPrompt } from '../prompts/api-selection-analysis-prompt.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { selectApiOperations } from './select-api-operations.js';
+import { resolveApiSelectionOptions } from './resolve-api-selection-options.js';
+import { apiSelectionExplanationPrompt } from '../prompts/api-selection-explanation-prompt.js';
+/** Additive clarification boundary; the existing selector keeps its output contract. */
+export async function analyzeApiSelection(input) {
+    assertSelectionInput(input.scenario, input.model);
+    if (!Array.isArray(input.operations))
+        throw new Error('operations must be an array');
+    const includeExplanations = resolveApiSelectionOptions({
+        includeExplanations: input.includeExplanations,
+    });
+    const context = describeApiSelectionContext({
+        scenario: input.scenario,
+        operations: input.operations,
+    });
+    if (!input.operations.length)
+        return { selection: await selectApiOperations(input), questions: [] };
+    const candidates = context.operations.map((operation, index) => ({
+        ...operation,
+        candidateId: `candidate-${index + 1}`,
+    }));
+    const schema = createApiSelectionAnalysisSchema(candidates.map((item) => item.candidateId), includeExplanations);
+    const proposed = await input.model
+        .withStructuredOutput(schema, {
+        name: 'analyze_api_selection',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(`${apiSelectionAnalysisPrompt}\n${apiSelectionExplanationPrompt}`),
+        new HumanMessage(JSON.stringify({ scenario: context.scenario, candidates })),
+    ]);
+    const parsed = parseStructuredOutput(schema, proposed, 'model API selection analysis');
+    const byId = new Map(candidates.map((item) => [item.candidateId, item]));
+    const selected = parsed.operations.map((item) => {
+        const candidate = byId.get(item.candidateId);
+        if (!candidate)
+            throw new Error(`Unknown API candidate ${item.candidateId}`);
+        return {
+            key: structuredClone(candidate.key),
+            purpose: item.purpose,
+            ...('explanation' in item
+                ? {
+                    explanation: createApiSelectionExplanation({
+                        context,
+                        basis: { kind: 'candidates', operations: [candidate.key] },
+                        reason: item.explanation.reason,
+                    }),
+                }
+                : {}),
+        };
+    });
+    const questions = parsed.questions.map((question, index) => {
+        if (new Set(question.candidateIds).size !== question.candidateIds.length)
+            throw new Error('API alternatives must be distinct');
+        const alternatives = question.candidateIds.map((id) => {
+            const candidate = byId.get(id);
+            if (!candidate)
+                throw new Error(`Unknown API alternative ${id}`);
+            return structuredClone(context.operations[candidates.indexOf(candidate)]);
+        });
+        return {
+            kind: 'operation-choice',
+            id: createHash('sha256')
+                .update(JSON.stringify([
+                context.scenario,
+                index,
+                question.purpose,
+                alternatives.map((item) => item.key),
+            ]))
+                .digest('hex'),
+            message: question.message,
+            purpose: question.purpose,
+            candidates: alternatives,
+            ...('explanation' in question
+                ? {
+                    explanation: createApiSelectionExplanation({
+                        context,
+                        basis: {
+                            kind: 'candidates',
+                            operations: alternatives.map((candidate) => candidate.key),
+                        },
+                        reason: question.explanation.reason,
+                    }),
+                }
+                : {}),
+        };
+    });
+    if (!selected.length && !questions.length && !parsed.gaps.length)
+        throw new Error('API analysis must contain operations, questions or gaps');
+    return {
+        selection: {
+            operations: selected,
+            gaps: parsed.gaps.map((gap) => ({
+                kind: 'missing_operation',
+                description: gap.description,
+                ...('explanation' in gap
+                    ? {
+                        explanation: createApiSelectionExplanation({
+                            context,
+                            basis: { kind: 'catalog' },
+                            reason: gap.explanation.reason,
+                        }),
+                    }
+                    : {}),
+            })),
+        },
+        questions,
+    };
+}

package/dist/selection/resolve-api-selection-options.d.ts

@@ -0,0 +1,3 @@
+import type { ApiSelectionModelOptions } from '../types/operation-selection.js';
+/** Optional standalone selector feature; absence preserves the non-explanation API. */
+export declare function resolveApiSelectionOptions(input: ApiSelectionModelOptions): boolean;

package/dist/selection/resolve-api-selection-options.js

@@ -0,0 +1,6 @@
+import { apiSelectionOptionsSchema } from '../schemas/api-selection-options-schema.js';
+/** Optional standalone selector feature; absence preserves the non-explanation API. */
+export function resolveApiSelectionOptions(input) {
+    const options = apiSelectionOptionsSchema.parse(input);
+    return options.includeExplanations === true;
+}

package/dist/selection/select-api-operations.d.ts

@@ -1,3 +1,3 @@
 import type { ApiSelection } from '@openapi-flow/core';
 import type { SelectApiOperationsInput } from '../types/operation-selection.js';
-export declare function selectApiOperations({ operations, scenario, model, }: SelectApiOperationsInput): Promise<ApiSelection>;
+export declare function selectApiOperations(input: SelectApiOperationsInput): Promise<ApiSelection>;

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

@@ -1,12 +1,24 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { describeApiSelectionContext, createApiSelectionExplanation, } from '@openapi-flow/core';
 import { createApiSelectionSchema } from '../schemas/api-selection-schema.js';
 import { operationSelectionPrompt } from '../prompts/operation-selection-prompt.js';
 import { assertSelectionInput } from '../legacy/planning/select-operation.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
-export async function selectApiOperations({ operations, scenario, model, }) {
+import { resolveApiSelectionOptions } from './resolve-api-selection-options.js';
+import { apiSelectionExplanationPrompt } from '../prompts/api-selection-explanation-prompt.js';
+export async function selectApiOperations(input) {
+    const { scenario, model } = input;
     assertSelectionInput(scenario, model);
-    if (!Array.isArray(operations))
+    if (!Array.isArray(input.operations))
         throw new Error('operations must be an array');
+    const includeExplanations = resolveApiSelectionOptions({
+        includeExplanations: input.includeExplanations,
+    });
+    const context = describeApiSelectionContext({
+        scenario,
+        operations: input.operations,
+    });
+    const { operations } = context;
     if (operations.length === 0)
         return {
             operations: [],
@@ -18,10 +30,10 @@ export async function selectApiOperations({ operations, scenario, model, }) {
             ],
         };
     const candidates = operations.map((operation, index) => ({
-        candidateId: `candidate-${index + 1}`,
         ...operation,
+        candidateId: `candidate-${index + 1}`,
     }));
-    const schema = createApiSelectionSchema(candidates.map((candidate) => candidate.candidateId));
+    const schema = createApiSelectionSchema(candidates.map((candidate) => candidate.candidateId), includeExplanations);
     const proposed = await model
         .withStructuredOutput(schema, {
         name: 'select_api_operations',
@@ -29,7 +41,7 @@ export async function selectApiOperations({ operations, scenario, model, }) {
         strict: true,
     })
         .invoke([
-        new SystemMessage(operationSelectionPrompt),
+        new SystemMessage(`${operationSelectionPrompt}\n${apiSelectionExplanationPrompt}`),
         new HumanMessage(JSON.stringify({ scenario, candidates })),
     ]);
     const selection = parseStructuredOutput(schema, proposed, 'model API selection');
@@ -41,11 +53,32 @@ export async function selectApiOperations({ operations, scenario, model, }) {
             const candidate = byId.get(item.candidateId);
             if (!candidate)
                 throw new Error(`model API selection references unknown ${item.candidateId}`);
-            return { key: { ...candidate.key }, purpose: item.purpose };
+            return {
+                key: { ...candidate.key },
+                purpose: item.purpose,
+                ...('explanation' in item
+                    ? {
+                        explanation: createApiSelectionExplanation({
+                            context,
+                            basis: { kind: 'candidates', operations: [candidate.key] },
+                            reason: item.explanation.reason,
+                        }),
+                    }
+                    : {}),
+            };
         }),
         gaps: selection.gaps.map((gap) => ({
             kind: 'missing_operation',
             description: gap.description,
+            ...('explanation' in gap
+                ? {
+                    explanation: createApiSelectionExplanation({
+                        context,
+                        basis: { kind: 'catalog' },
+                        reason: gap.explanation.reason,
+                    }),
+                }
+                : {}),
         })),
     };
 }

package/dist/types/api-input-answers.d.ts

@@ -0,0 +1,16 @@
+import type { ApiInputRequirement } from '@openapi-flow/core';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { z } from 'zod';
+import type { createApiInputAnswerSourceSchema } from '../schemas/api-input-answer-source-schema.js';
+export interface ExtractApiInputAnswersInput {
+    requirements: ApiInputRequirement[];
+    reply: string;
+    model: BaseChatModel;
+}
+export interface AnalyzeApiInputAnswersInput extends Omit<ExtractApiInputAnswersInput, 'model'> {
+    /** Required only when pending questions and a nonempty reply need interpretation. */
+    model?: BaseChatModel;
+    includeExplanations?: boolean;
+}
+export type ApiInputAnswersOutput = z.infer<ReturnType<typeof createApiInputAnswerSourceSchema>>;
+export type ApiInputAnswerProposal = ApiInputAnswersOutput['answers'][number];

package/dist/types/api-input-answers.js

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

package/dist/types/api-selection-analysis.d.ts

@@ -0,0 +1,3 @@
+import type { z } from 'zod';
+import type { createApiSelectionAnalysisSchema } from '../schemas/api-selection-analysis-schema.js';
+export type ApiSelectionAnalysisOutput = z.infer<ReturnType<typeof createApiSelectionAnalysisSchema>>;

package/dist/types/api-selection-analysis.js

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

package/dist/types/argument-generation.d.ts

@@ -1,7 +1,13 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ApiArgumentsSchemaInput } from '@openapi-flow/core';
-export interface GenerateApiArgumentsInput extends ApiArgumentsSchemaInput {
-    callId: string;
-    scenario: string;
-    model: BaseChatModel;
+import type { ApiLiteralGenerationInput, ApiArgumentGenerationContract, ApiArgumentProposalSchemaShape } from '@openapi-flow/core';
+import type { z } from 'zod';
+import type { createApiLiteralGenerationOutputSchema } from '../schemas/api-literal-generation-output-schema.js';
+import type { apiLiteralGenerationReasonSchema } from '../schemas/api-literal-generation-output-schema.js';
+export interface GenerateApiArgumentsInput extends ApiLiteralGenerationInput {
+    model?: BaseChatModel;
+    includeExplanations?: boolean;
 }
+export type ApiLiteralGenerationOutput = z.infer<ReturnType<typeof createApiLiteralGenerationOutputSchema>>;
+export type ApiLiteralGenerationOutputSchema = ApiArgumentGenerationContract['schema'] | z.ZodObject<ApiArgumentProposalSchemaShape & {
+    explanation: typeof apiLiteralGenerationReasonSchema;
+}, z.core.$strict>;

package/dist/types/binding-planning.d.ts

@@ -1,8 +1,10 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ApiBindingMaterial, NativeOutputContract } from '@openapi-flow/core';
-export interface PlanApiBindingsInput {
-    scenario: string;
-    materials: ApiBindingMaterial[];
+import type { ApiBindingPlanningInput, ApiBindingPlanProposal, ExplainedApiBindingCall } from '@openapi-flow/core';
+export interface PlanApiBindingsInput extends ApiBindingPlanningInput {
     model: BaseChatModel;
-    nativeOutputs?: NativeOutputContract[];
+    includeExplanations?: boolean;
 }
+export interface ExplainedApiBindingPlanOutput extends Omit<ApiBindingPlanProposal, 'calls'> {
+    calls: ExplainedApiBindingCall[];
+}
+export type ApiBindingPlanOutput = ApiBindingPlanProposal | ExplainedApiBindingPlanOutput;

package/dist/types/native-node-planning.d.ts

@@ -1,25 +1,76 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ApiBindingMaterial, PlannedNativeNode, WorkflowCapability, WorkflowPlanGap, WorkflowReviewGap } from '@openapi-flow/core';
-export interface PlanNativeNodesInput {
-    planId: string;
-    scenario: string;
-    model: BaseChatModel;
-    capabilities?: WorkflowCapability[];
-    apiMaterials?: ApiBindingMaterial[];
-    preparedNativeNodes?: PlannedNativeNode[];
-}
-export interface NativeNodeProposal {
-    nativeNodes: PlannedNativeNode[];
-    gaps: WorkflowPlanGap[];
-}
-export interface NativeNodePlan {
-    nativeNodes: PlannedNativeNode[];
-    gaps: WorkflowReviewGap[];
+import type { z } from 'zod';
+import type { JsonValueObject, NativeNodePlanningInput, NativePlanningProposal, NativePlanningResult, NativePlanningAssessment, NativePlanningCapabilityMaterial, NativeNodePlanningRecord, NativeInstanceSelectionInput, NativeNodeConfigurationInput, NativeSelectedPlanningInput } from '@openapi-flow/core';
+export interface PlanNativeNodesInput extends NativeNodePlanningInput {
+    model?: BaseChatModel;
+    includeExplanations?: boolean;
+}
+export type NativeNodeProposal = NativePlanningProposal;
+export type { NativePlanningCapabilityMaterial } from '@openapi-flow/core';
+export interface NativeLiteralNodeOutput {
+    id: string;
+    capability: string;
+    parameters: JsonValueObject;
+}
+export interface NativeOwnedLiteralNodeOutput extends NativeLiteralNodeOutput {
+    parameterSource: 'literal';
+}
+export interface NativeRuntimeNodeOutput {
+    id: string;
+    capability: string;
+    parameterSource: 'workflow-input';
+}
+export type NativeNodeModelInstance = NativeLiteralNodeOutput | NativeOwnedLiteralNodeOutput | NativeRuntimeNodeOutput;
+export interface NativeNodeModelProposal {
+    nativeNodes: NativeNodeModelInstance[];
+    gaps: NativePlanningProposal['gaps'];
+}
+export interface ExplainedNativeNodeProposal {
+    node: NativeNodeModelInstance;
+    reason: string;
+}
+export interface ExplainedNativeNodePlanningOutput {
+    decision: {
+        additions: ExplainedNativeNodeProposal[];
+        gaps: NativePlanningProposal['gaps'];
+    } | {
+        noAdditionalNodesReason: string;
+        gaps: NativePlanningProposal['gaps'];
+    };
+}
+export type NativeNodePlanningOutput = NativeNodeModelProposal | ExplainedNativeNodePlanningOutput;
+export interface ResolvedNativeNodePlanningOutput {
+    proposal: NativeNodeProposal;
+    assessment?: NativePlanningAssessment;
+}
+export interface NativeNodeParameterContract {
+    schemas: z.ZodType<NativeNodeModelInstance>[];
+    material: NativePlanningCapabilityMaterial;
+}
+export interface NativeNodePlanningContract {
+    schema: z.ZodType<NativeNodePlanningOutput>;
+    capabilities: NativePlanningCapabilityMaterial[];
+}
+export interface NativeNodePlan extends NativePlanningResult {
+    nativePlanning?: NativeNodePlanningRecord;
 }
 export type NativeNodePlanningFailure = {
+    stage: 'instance-selection' | 'dependency-plan' | 'parameter-schema' | 'parameter-validation';
+    output: unknown;
+} | {
     stage: 'proposal-schema';
     output: unknown;
 } | {
     stage: 'node-validation';
     output: NativeNodeProposal;
+    sourceOutput?: NativeNodePlanningOutput;
 };
+export interface SelectNativeNodeInstancesInput extends NativeInstanceSelectionInput {
+    model?: BaseChatModel;
+}
+export interface GenerateNativeNodeParametersInput extends NativeNodeConfigurationInput {
+    model?: BaseChatModel;
+}
+export interface PlanNativeInstanceDependenciesInput extends NativeSelectedPlanningInput {
+    model?: BaseChatModel;
+}

package/dist/types/operation-selection.d.ts

@@ -2,7 +2,11 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { ApiOperationCandidate } from '@openapi-flow/core';
 import type { z } from 'zod';
 import type { createApiSelectionSchema } from '../schemas/api-selection-schema.js';
-export interface SelectApiOperationsInput {
+export interface ApiSelectionModelOptions {
+    /** Opt in to reasons in the same call and code-owned discovery evidence. */
+    includeExplanations?: boolean;
+}
+export interface SelectApiOperationsInput extends ApiSelectionModelOptions {
     operations: ApiOperationCandidate[];
     scenario: string;
     model: BaseChatModel;

package/dist/types/request-media-selection.d.ts

@@ -1,10 +1,15 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { ApiOperationContract } from '@openapi-flow/core';
+import type { z } from 'zod';
+import type { createApiRequestMediaTypeSchema } from '../schemas/api-request-media-type-schema.js';
 export interface SelectApiRequestMediaTypeInput {
     operation: ApiOperationContract;
     scenario: string;
+    purpose?: string;
     model: BaseChatModel;
 }
-export interface ApiRequestMediaTypeOutput {
-    requestMediaType: string | null;
+export interface AnalyzeApiRequestMediaTypeInput extends SelectApiRequestMediaTypeInput {
+    /** Optional same-call model reason; code attaches unchanged request-body sources. */
+    includeExplanations?: boolean;
 }
+export type ApiRequestMediaTypeOutput = z.infer<ReturnType<typeof createApiRequestMediaTypeSchema>>;

package/dist/types/reviewable-workflow-planning.d.ts

@@ -1,19 +1,28 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ReviewableWorkflowGraphProposal, ReviewableWorkflowPlanningContext, WorkflowReviewGap, PlannedNativeNode } from '@openapi-flow/core';
+import type { ReviewableWorkflowGraphProposal, ReviewableWorkflowPlanningContext, WorkflowReviewGap, PlannedNativeNode, ExplainedWorkflowConnection, ExplainedWorkflowBlockedCall } from '@openapi-flow/core';
+import type { ExplainedGraphNativeNode } from './workflow-planning.js';
 export interface PlanReviewableWorkflowGraphInput extends ReviewableWorkflowPlanningContext {
     scenario: string;
     model: BaseChatModel;
     gaps: WorkflowReviewGap[];
     preparedNativeNodes?: PlannedNativeNode[];
+    includeExplanations?: boolean;
 }
 export type ReviewableWorkflowGraphPlanningFailure = {
     stage: 'proposal-schema';
     output: unknown;
 } | {
     stage: 'graph-validation';
-    output: ReviewableWorkflowGraphOutput;
+    output: ReviewableWorkflowGraphModelOutput;
 };
 export type ReviewableWorkflowGraphOutput = Omit<ReviewableWorkflowGraphProposal, 'nativeNodes' | 'blockedCalls'> & {
     additionalNativeNodes?: ReviewableWorkflowGraphProposal['nativeNodes'];
     blockedCalls?: ReviewableWorkflowGraphProposal['blockedCalls'];
 };
+export interface ExplainedReviewableWorkflowGraphOutput extends ReviewableWorkflowGraphOutput {
+    reason: string;
+    additionalNativeNodes?: ExplainedGraphNativeNode[];
+    edges: ExplainedWorkflowConnection[];
+    blockedCalls?: ExplainedWorkflowBlockedCall[];
+}
+export type ReviewableWorkflowGraphModelOutput = ReviewableWorkflowGraphOutput | ExplainedReviewableWorkflowGraphOutput;

package/dist/types/structured-output-schema.d.ts

@@ -0,0 +1,3 @@
+export type StructuredOutputSchemaDialect = 'draft-7' | 'draft-2020-12';
+export type StructuredOutputSchemaDirection = 'input' | 'output';
+export type StructuredOutputSchemaReuse = 'inline' | 'ref';

package/dist/types/structured-output-schema.js

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

package/dist/types/workflow-clarification.d.ts

@@ -0,0 +1,23 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ApiOperationContract, ClarificationQuestionLimits, WorkflowClarificationOptions, WorkflowDecisionExplanation, WorkflowMessageEvidence, WorkflowNativeEvidence, WorkflowEntryPointEvidence, WorkflowPlanningContext, WorkflowRequirementsProposal, WorkflowSourceMessage } from '@openapi-flow/core';
+export interface ClarifyWorkflowRequirementsInput {
+    context: WorkflowPlanningContext;
+    limits: ClarificationQuestionLimits;
+    options?: WorkflowClarificationOptions;
+    model: BaseChatModel;
+    /** Earlier intent, not authority for a new statement or answer. */
+    backgroundMessages?: WorkflowSourceMessage[];
+}
+export interface WorkflowClarificationOasCandidate {
+    candidateId: string;
+    operation: ApiOperationContract;
+}
+export interface ProposedWorkflowOasEvidence {
+    kind: 'oas';
+    candidateId: string;
+}
+export type ProposedWorkflowPlanningEvidence = WorkflowMessageEvidence | WorkflowNativeEvidence | WorkflowEntryPointEvidence | ProposedWorkflowOasEvidence;
+export type WorkflowRequirementsModelOutput = WorkflowRequirementsProposal<ProposedWorkflowPlanningEvidence>;
+export interface CanonicalWorkflowExplanationFields {
+    explanation?: WorkflowDecisionExplanation;
+}

package/dist/types/workflow-clarification.js

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

package/dist/types/workflow-draft-api-binding-edit.d.ts

@@ -0,0 +1,9 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftApiBindingEditInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftApiBindingEditInput extends WorkflowDraftApiBindingEditInput {
+    model: BaseChatModel;
+}
+export interface WorkflowDraftApiBindingEditPlanningFailure {
+    stage: 'proposal-schema' | 'proposal-validation';
+    output: unknown;
+}

package/dist/types/workflow-draft-api-binding-edit.js

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

package/dist/types/workflow-draft-api-call-planning.d.ts

@@ -0,0 +1,15 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftApiCallPlanningInput, WorkflowDraftApiCallBindingsInput, WorkflowDraftApiCallArgumentsInput } from '@openapi-flow/core';
+export interface SelectWorkflowDraftApiBindingInputsInput extends WorkflowDraftApiCallPlanningInput {
+    model?: BaseChatModel;
+}
+export interface PlanWorkflowDraftApiCallBindingsInput extends WorkflowDraftApiCallBindingsInput {
+    model?: BaseChatModel;
+}
+export interface GenerateWorkflowDraftApiCallArgumentsInput extends WorkflowDraftApiCallArgumentsInput {
+    model?: BaseChatModel;
+}
+export interface WorkflowDraftApiCallPlanningFailure {
+    stage: 'binding-inputs' | 'bindings' | 'arguments';
+    output: unknown;
+}

package/dist/types/workflow-draft-api-call-planning.js

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

package/dist/types/workflow-draft-api-input-edit.d.ts

@@ -0,0 +1,13 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftApiInputEditInput, WorkflowDraftApiInputEditContractInput } from '@openapi-flow/core';
+export interface SelectWorkflowDraftApiInputEditTargetsInput extends WorkflowDraftApiInputEditInput {
+    model: BaseChatModel;
+}
+export interface GenerateWorkflowDraftApiInputEditsInput extends WorkflowDraftApiInputEditContractInput {
+    /** Not needed when the explicit contract contains removals only. */
+    model?: BaseChatModel;
+}
+export interface WorkflowDraftApiInputEditPlanningFailure {
+    stage: 'targets' | 'values';
+    output: unknown;
+}