@openapi-flow/langchain 0.4.1 → 0.4.2

package/dist/schemas/api-selection-analysis-schema.d.ts

@@ -1,10 +1,18 @@
 import { z } from 'zod';
-export declare function createApiSelectionAnalysisSchema(candidateIds: string[], includeExplanations?: boolean): z.ZodObject<{
+export declare function createApiSelectionAnalysisSchema(candidateIds: string[], includeExplanations?: boolean, requireExplanations?: boolean): z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
         candidateId: z.ZodEnum<{
             [x: string]: string;
         }>;
         purpose: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        candidateId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        purpose: z.ZodString;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         candidateId: z.ZodEnum<{
             [x: string]: string;
@@ -16,6 +24,11 @@ export declare function createApiSelectionAnalysisSchema(candidateIds: string[],
     }, z.core.$strict>>;
     gaps: z.ZodArray<z.ZodObject<{
         description: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        description: z.ZodString;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         description: z.ZodString;
         explanation: z.ZodObject<{
@@ -29,6 +42,16 @@ export declare function createApiSelectionAnalysisSchema(candidateIds: string[],
         candidateIds: z.ZodArray<z.ZodEnum<{
             [x: string]: string;
         }>>;
+    }, z.core.$strict> | z.ZodObject<{
+        kind: z.ZodLiteral<"single-choice">;
+        message: z.ZodString;
+        purpose: z.ZodString;
+        candidateIds: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         kind: z.ZodLiteral<"single-choice">;
         message: z.ZodString;
@@ -48,6 +71,18 @@ export declare function createApiSelectionAnalysisSchema(candidateIds: string[],
         }>>;
         minSelections: z.ZodNumber;
         maxSelections: z.ZodNumber;
+    }, z.core.$strict> | z.ZodObject<{
+        message: z.ZodString;
+        purpose: z.ZodString;
+        kind: z.ZodLiteral<"multiple-choice">;
+        candidateIds: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        minSelections: z.ZodNumber;
+        maxSelections: z.ZodNumber;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         message: z.ZodString;
         purpose: z.ZodString;

package/dist/schemas/api-selection-analysis-schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createApiSelectionSchema } from './api-selection-schema.js';
 import { withApiSelectionExplanation } from './with-api-selection-explanation.js';
-export function createApiSelectionAnalysisSchema(candidateIds, includeExplanations = false) {
+export function createApiSelectionAnalysisSchema(candidateIds, includeExplanations = false, requireExplanations = true) {
     const single = z.strictObject({
         kind: z
             .literal('single-choice')
@@ -40,13 +40,13 @@ export function createApiSelectionAnalysisSchema(candidateIds, includeExplanatio
             .safe()
             .describe('Maximum selections allowed by the user and offered candidate count. Must be at least minSelections.'),
     });
-    return createApiSelectionSchema(candidateIds, includeExplanations).extend({
+    return createApiSelectionSchema(candidateIds, includeExplanations, requireExplanations).extend({
         questions: z
             .array(
         // Literal kinds remain disjoint; z.union emits the provider-supported anyOf.
         z.union([
-            withApiSelectionExplanation(single, includeExplanations),
-            withApiSelectionExplanation(multiple, includeExplanations),
+            withApiSelectionExplanation(single, includeExplanations, requireExplanations),
+            withApiSelectionExplanation(multiple, includeExplanations, requireExplanations),
         ]))
             .describe('Empty when the requested API scope is clear. Multiple available APIs alone is not ambiguity. Never expand a short request into unrelated actions.'),
     });

package/dist/schemas/api-selection-schema.d.ts

@@ -1,10 +1,18 @@
 import { z } from 'zod';
-export declare function createApiSelectionSchema(candidateIds: string[], includeExplanations?: boolean): z.ZodObject<{
+export declare function createApiSelectionSchema(candidateIds: string[], includeExplanations?: boolean, requireExplanations?: boolean): z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
         candidateId: z.ZodEnum<{
             [x: string]: string;
         }>;
         purpose: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        candidateId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        purpose: z.ZodString;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         candidateId: z.ZodEnum<{
             [x: string]: string;
@@ -16,6 +24,11 @@ export declare function createApiSelectionSchema(candidateIds: string[], include
     }, z.core.$strict>>;
     gaps: z.ZodArray<z.ZodObject<{
         description: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        description: z.ZodString;
+        explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+            reason: string;
+        } | undefined, unknown>>>;
     }, z.core.$strict> | z.ZodObject<{
         description: z.ZodString;
         explanation: z.ZodObject<{

package/dist/schemas/api-selection-schema.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { withApiSelectionExplanation } from './with-api-selection-explanation.js';
-export function createApiSelectionSchema(candidateIds, includeExplanations = false) {
+export function createApiSelectionSchema(candidateIds, includeExplanations = false, requireExplanations = true) {
     if (candidateIds.length === 0)
         throw new Error('operations must contain candidates for model selection');
     return z
@@ -16,7 +16,7 @@ export function createApiSelectionSchema(candidateIds, includeExplanations = fal
                 .min(1)
                 .describe('The scenario role of this one API call instance. Describe separate required calls separately; this is not an execution order.'),
         })
-            .strict(), includeExplanations))
+            .strict(), includeExplanations, requireExplanations))
             .describe('One entry per required API call instance, not a deduplicated API catalog. Repeat a candidateId only when the scenario requires separate calls to that API.'),
         gaps: z.array(withApiSelectionExplanation(z
             .object({
@@ -25,7 +25,7 @@ export function createApiSelectionSchema(candidateIds, includeExplanations = fal
                 .min(1)
                 .describe('Required API capability that no supplied discovery candidate matches. Do not judge missing parameters, response fields or security without a full contract.'),
         })
-            .strict(), includeExplanations)),
+            .strict(), includeExplanations, requireExplanations)),
     })
         .strict();
 }

package/dist/schemas/reviewable-workflow-graph-schema.d.ts

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 import type { WorkflowCapability } from '@openapi-flow/core';
-import type { WorkflowConnectionPlanningOutput } from '../types/workflow-orchestration.js';
-import type { ReviewableWorkflowGraphModelOutput } from '../types/reviewable-workflow-planning.js';
 import type { WorkflowGraphExplanationMode } from '../types/workflow-planning.js';
-export declare function createReviewableWorkflowGraphSchema(capabilities: WorkflowCapability[], readyCallIds: string[], explanationMode?: WorkflowGraphExplanationMode): z.ZodType<WorkflowConnectionPlanningOutput | ReviewableWorkflowGraphModelOutput>;
+export declare function createReviewableWorkflowGraphSchema(capabilities: WorkflowCapability[], readyCallIds: string[], explanationMode?: WorkflowGraphExplanationMode): z.ZodObject<{
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        output: z.ZodString;
+        to: z.ZodString;
+        input: z.ZodString;
+        reason?: z.ZodString | undefined;
+    }, z.core.$strict>>;
+    additionalGaps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
+    reason?: z.ZodString | undefined;
+}, z.core.$strict>;

package/dist/schemas/with-api-selection-explanation.d.ts

@@ -1,10 +1,18 @@
 import { z } from 'zod';
-export declare function withApiSelectionExplanation<Shape extends z.ZodRawShape>(schema: z.ZodObject<Shape, z.core.$strict>, includeExplanations: boolean): z.ZodObject<Shape, z.core.$strict> | z.ZodObject<(keyof Shape & "explanation" extends never ? Shape & {
+export declare function withApiSelectionExplanation<Shape extends z.ZodRawShape>(schema: z.ZodObject<Shape, z.core.$strict>, includeExplanations: boolean, requireExplanations?: boolean): z.ZodObject<Shape, z.core.$strict> | z.ZodObject<(keyof Shape & "explanation" extends never ? Shape & {
+    explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+        reason: string;
+    } | undefined, unknown>>>;
+} : { [K in keyof Shape as K extends "explanation" ? never : K]: Shape[K]; } & {
+    explanation: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+        reason: string;
+    } | undefined, unknown>>>;
+}) extends infer T ? { [k in keyof T]: T[k]; } : never, z.core.$strict> | z.ZodObject<(keyof Shape & "explanation" extends never ? Shape & {
     explanation: z.ZodObject<{
         reason: z.ZodString;
     }, z.core.$strict>;
-} : { [K in keyof Shape as K extends "explanation" ? never : K]: Shape[K]; } & {
+} : { [K_1 in keyof Shape as K_1 extends "explanation" ? never : K_1]: Shape[K_1]; } & {
     explanation: z.ZodObject<{
         reason: z.ZodString;
     }, z.core.$strict>;
-}) extends infer T ? { [k in keyof T]: T[k]; } : never, z.core.$strict>;
+}) extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never, z.core.$strict>;

package/dist/schemas/with-api-selection-explanation.js

@@ -1,15 +1,28 @@
 import { z } from 'zod';
-export function withApiSelectionExplanation(schema, includeExplanations) {
+const apiSelectionExplanationSchema = z.strictObject({
+    reason: z
+        .string()
+        .min(1)
+        .refine((value) => value.trim().length > 0)
+        .describe('Short user-facing reason in the scenario language for this selection, missing capability or consequential API choice. Use only the supplied scenario and discovery metadata; code attaches those unchanged sources. Do not claim request, response or security contract validation, or expose private chain-of-thought.'),
+});
+export function withApiSelectionExplanation(schema, includeExplanations, requireExplanations = true) {
     z.boolean().parse(includeExplanations);
+    if (!requireExplanations)
+        return schema.extend({
+            explanation: z
+                .unknown()
+                .transform((value) => {
+                const explanation = apiSelectionExplanationSchema.safeParse(value);
+                return includeExplanations && explanation.success
+                    ? explanation.data
+                    : undefined;
+            })
+                .optional(),
+        });
     return includeExplanations
         ? schema.extend({
-            explanation: z.strictObject({
-                reason: z
-                    .string()
-                    .min(1)
-                    .refine((value) => value.trim().length > 0)
-                    .describe('Short user-facing reason in the scenario language for this selection, missing capability or consequential API choice. Use only the supplied scenario and discovery metadata; code attaches those unchanged sources. Do not claim request, response or security contract validation, or expose private chain-of-thought.'),
-            }),
+            explanation: apiSelectionExplanationSchema,
         })
         : schema;
 }

package/dist/schemas/workflow-connection-execution-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { WorkflowConnectionPlanningContext } from '@openapi-flow/core';
+import type { WorkflowConnectionExecutionOutput } from '../types/workflow-connection-selection.js';
+/** Validate executable fields independently of optional model-authored display text. */
+export declare function createWorkflowConnectionExecutionSchema(context: WorkflowConnectionPlanningContext, includeExplanations: boolean): z.ZodType<WorkflowConnectionExecutionOutput>;

package/dist/schemas/workflow-connection-execution-schema.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { workflowConnectionProposalSchema } from '@openapi-flow/core';
+import { createWorkflowConnectionSelectionSchema } from './workflow-connection-selection-schema.js';
+/** Validate executable fields independently of optional model-authored display text. */
+export function createWorkflowConnectionExecutionSchema(context, includeExplanations) {
+    const execution = createWorkflowConnectionSelectionSchema(context, false);
+    if (!includeExplanations)
+        return execution;
+    const display = { reason: z.unknown().optional() };
+    const base = execution.extend({
+        ...display,
+        edges: z.array(execution.shape.edges.element.extend(display)),
+    });
+    if (context.readyCallIds.length)
+        return base.extend({
+            blockedCalls: z.array(workflowConnectionProposalSchema.shape.blockedCalls.element.extend({
+                callId: z.enum(context.readyCallIds),
+                ...display,
+            })),
+        });
+    return base;
+}

package/dist/schemas/workflow-connection-goal-review-schema.d.ts

@@ -1,4 +1,4 @@
 import { z } from 'zod';
 import type { WorkflowConnectionGoalReviewDescription } from '@openapi-flow/core';
 import type { WorkflowConnectionGoalReviewModelOutput } from '../types/workflow-connection-goal-review.js';
-export declare function createWorkflowConnectionGoalReviewSchema(description: WorkflowConnectionGoalReviewDescription): z.ZodType<WorkflowConnectionGoalReviewModelOutput>;
+export declare function createWorkflowConnectionGoalReviewSchema(description: WorkflowConnectionGoalReviewDescription, validatePresentation?: boolean): z.ZodType<WorkflowConnectionGoalReviewModelOutput>;

package/dist/schemas/workflow-connection-goal-review-schema.js

@@ -1,21 +1,19 @@
 import { z } from 'zod';
 import { workflowConnectionGoalAssessmentSchema } from '@openapi-flow/core';
-export function createWorkflowConnectionGoalReviewSchema(description) {
+export function createWorkflowConnectionGoalReviewSchema(description, validatePresentation = true) {
     const assessment = workflowConnectionGoalAssessmentSchema
-        .omit({ factId: true })
+        .omit({ factId: true, sourceQuotes: true, explanationStatus: true })
         .extend({
         policyIds: workflowConnectionGoalAssessmentSchema.shape.policyIds.describe('Select only supplied code-enforced policy IDs for clauses actually covered by that policy. A protected-edge policy does not prove data semantics or implementation of new connections.'),
         goalIds: z
             .array(z.enum(description.goals.map((goal) => goal.id)))
             .describe('Select only actual candidate goals. An omitted requirement may have no matching goal.'),
-        sourceQuotes: z
-            .array(z.string().min(1))
-            .min(1)
-            .describe('Exact unchanged quotes from THIS original requirement, including any missing or contradicted clause.'),
-        reason: z
-            .string()
-            .min(1)
-            .describe('Brief evidence-based explanation comparing the entire original requirement with goals and actual mappings. Not private reasoning.'),
+        reason: validatePresentation
+            ? z
+                .string()
+                .min(1)
+                .describe('Brief evidence-based explanation comparing the entire original requirement with goals and actual mappings. Not private reasoning.')
+            : z.unknown().optional(),
     });
     return z.strictObject({
         assessments: z.strictObject(Object.fromEntries(description.requirements.map((fact) => [

package/dist/schemas/workflow-connection-selection-schema.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { WorkflowConnectionPlanningContext } from '@openapi-flow/core';
+/** Existing identities are supplied choices. Only new gap identities belong to the model. */
+export declare function createWorkflowConnectionSelectionSchema(context: WorkflowConnectionPlanningContext, includeExplanations: boolean): z.ZodObject<{
+    additionalGaps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
+    reason?: z.ZodString | undefined;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodObject<{
+            gapId: z.ZodString;
+        }, z.core.$strict> | z.ZodUnion<readonly [z.ZodEnum<{
+            [x: string]: string;
+        }>, z.ZodObject<{
+            gapId: z.ZodString;
+        }, z.core.$strict>]>;
+        output: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        to: z.ZodObject<{
+            gapId: z.ZodString;
+        }, z.core.$strict> | z.ZodUnion<readonly [z.ZodEnum<{
+            [x: string]: string;
+        }>, z.ZodObject<{
+            gapId: z.ZodString;
+        }, z.core.$strict>]>;
+        input: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        reason?: z.ZodString | undefined;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/schemas/workflow-connection-selection-schema.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { createReviewableWorkflowGraphSchema } from './reviewable-workflow-graph-schema.js';
+import { workflowConnectionReasonSchema } from './workflow-connection-explanation-schema.js';
+/** Existing identities are supplied choices. Only new gap identities belong to the model. */
+export function createWorkflowConnectionSelectionSchema(context, includeExplanations) {
+    const nodeIds = context.nodes.map((node) => node.id);
+    const additionalGap = z.strictObject({
+        gapId: z
+            .string()
+            .min(1)
+            .describe('ID of a NEW gap declared in additionalGaps, not an existing node.'),
+    });
+    const endpoint = nodeIds.length
+        ? z.union([z.enum(nodeIds), additionalGap])
+        : additionalGap;
+    const outputs = [
+        ...new Set(['main', ...context.nodes.flatMap((node) => node.outputs)]),
+    ];
+    const inputs = [
+        ...new Set(['main', ...context.nodes.flatMap((node) => node.inputs)]),
+    ];
+    const base = createReviewableWorkflowGraphSchema([], context.readyCallIds, includeExplanations ? 'connections' : 'none');
+    return base.extend({
+        edges: z.array(z.strictObject({
+            ...(includeExplanations
+                ? { reason: workflowConnectionReasonSchema }
+                : {}),
+            from: endpoint.describe('Choose an exact supplied source ID, or explicitly reference a new gap.'),
+            output: z.enum(outputs),
+            to: endpoint.describe('Choose an exact supplied target ID, or explicitly reference a new gap.'),
+            input: z.enum(inputs),
+        })),
+    });
+}

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

@@ -8,6 +8,7 @@ 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';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 /** Additive clarification boundary; the existing selector keeps its output contract. */
 export async function analyzeApiSelection(input) {
     assertSelectionInput(input.scenario, input.model);
@@ -28,7 +29,7 @@ export async function analyzeApiSelection(input) {
     }));
     const schema = createApiSelectionAnalysisSchema(candidates.map((item) => item.candidateId), includeExplanations);
     const proposed = await input.model
-        .withStructuredOutput(schema, {
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
         name: 'analyze_api_selection',
         method: 'jsonSchema',
         strict: true,
@@ -37,7 +38,7 @@ export async function analyzeApiSelection(input) {
         new SystemMessage(`${apiSelectionAnalysisPrompt}\n${apiSelectionExplanationPrompt}`),
         new HumanMessage(JSON.stringify({ scenario: context.scenario, candidates })),
     ]);
-    const parsed = parseStructuredOutput(schema, proposed, 'model API selection analysis');
+    const parsed = parseStructuredOutput(createApiSelectionAnalysisSchema(candidates.map((candidate) => candidate.candidateId), includeExplanations, false), 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);
@@ -46,7 +47,7 @@ export async function analyzeApiSelection(input) {
         return {
             key: structuredClone(candidate.key),
             purpose: item.purpose,
-            ...('explanation' in item
+            ...('explanation' in item && item.explanation !== undefined
                 ? {
                     explanation: createApiSelectionExplanation({
                         context,
@@ -85,7 +86,7 @@ export async function analyzeApiSelection(input) {
             message: question.message,
             purpose: question.purpose,
             candidates: alternatives,
-            ...('explanation' in question
+            ...('explanation' in question && question.explanation !== undefined
                 ? {
                     explanation: createApiSelectionExplanation({
                         context,
@@ -117,7 +118,7 @@ export async function analyzeApiSelection(input) {
             gaps: parsed.gaps.map((gap) => ({
                 kind: 'missing_operation',
                 description: gap.description,
-                ...('explanation' in gap
+                ...('explanation' in gap && gap.explanation !== undefined
                     ? {
                         explanation: createApiSelectionExplanation({
                             context,

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

@@ -7,6 +7,7 @@ import { parseStructuredOutput } from '../legacy/planning/parse-structured-outpu
 import { resolveApiSelectionOptions } from './resolve-api-selection-options.js';
 import { apiSelectionExplanationPrompt } from '../prompts/api-selection-explanation-prompt.js';
 import { invokeStructuredModel } from '../model/invoke-structured-model.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 export async function selectApiOperations(input) {
     const { scenario, model } = input;
     const { includeExplanations, context } = runOpenApiFlowOperation({
@@ -46,7 +47,7 @@ export async function selectApiOperations(input) {
     const schema = createApiSelectionSchema(candidates.map((candidate) => candidate.candidateId), includeExplanations);
     const proposed = await invokeStructuredModel({
         model,
-        schema,
+        schema: serializeStructuredOutputSchema(schema, 'draft-2020-12'),
         operation: 'selectApiOperations',
         name: 'select_api_operations',
         method: 'jsonSchema',
@@ -62,7 +63,7 @@ export async function selectApiOperations(input) {
         stage: 'contract-validation',
         code: 'API_SELECTION_INVALID',
     }, () => {
-        const selection = parseStructuredOutput(schema, proposed, 'model API selection');
+        const selection = parseStructuredOutput(createApiSelectionSchema(candidates.map((candidate) => candidate.candidateId), includeExplanations, false), proposed, 'model API selection');
         if (selection.operations.length === 0 && selection.gaps.length === 0)
             throw new Error('model API selection must contain operations or gaps');
         const byId = new Map(candidates.map((candidate) => [candidate.candidateId, candidate]));
@@ -74,7 +75,7 @@ export async function selectApiOperations(input) {
                 return {
                     key: { ...candidate.key },
                     purpose: item.purpose,
-                    ...('explanation' in item
+                    ...('explanation' in item && item.explanation !== undefined
                         ? {
                             explanation: createApiSelectionExplanation({
                                 context,
@@ -88,7 +89,7 @@ export async function selectApiOperations(input) {
             gaps: selection.gaps.map((gap) => ({
                 kind: 'missing_operation',
                 description: gap.description,
-                ...('explanation' in gap
+                ...('explanation' in gap && gap.explanation !== undefined
                     ? {
                         explanation: createApiSelectionExplanation({
                             context,

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

@@ -40,7 +40,7 @@ export type ApiLiteralProvidedDecision = z.infer<ReturnType<typeof createApiLite
 export type ApiLiteralAvailabilityDecision = z.infer<typeof apiLiteralNotProvidedSchema> | ApiLiteralProvidedDecision;
 export type ApiTrackedLiteralGenerationOutput = z.infer<ReturnType<typeof createApiTrackedLiteralGenerationSchema>> | z.infer<ReturnType<typeof createApiExplainedTrackedLiteralGenerationSchema>>;
 export interface ApiExplainedLiteralGenerationOutput extends ApiArgumentProposal {
-    explanation: z.infer<typeof apiLiteralGenerationReasonSchema>;
+    explanation?: z.infer<typeof apiLiteralGenerationReasonSchema>;
 }
 export type ApiLiteralGenerationOutput = ApiArgumentProposal | ApiExplainedLiteralGenerationOutput | ApiTrackedLiteralGenerationOutput;
 export type ApiLiteralGenerationOutputSchema = z.ZodType<ApiLiteralGenerationOutput>;

package/dist/types/incremental-connection-planning.d.ts

@@ -61,6 +61,8 @@ export interface InvokeConnectionPlanningModelInput<Output extends object> {
     operation: string;
     name: string;
     schema: ZodType<Output>;
+    /** Optional distinct receiver validation when display-only fields must not gate execution. */
+    validationSchema?: ZodType<Output>;
     messages: BaseMessage[];
     sourceFingerprint?: string;
     requestFingerprint?: string;

package/dist/types/native-instance-selection-review.d.ts

@@ -1,7 +1,7 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { NativeSelectedPlanningInput } from '@openapi-flow/core';
+import type { NativeSelectedPlanningInput, NativeInstanceSelectionReviewOptions } from '@openapi-flow/core';
 import type { NativePlanningRejectedProposal } from './native-planning-rejection.js';
-export interface ReviewNativeInstanceSelectionInput extends NativeSelectedPlanningInput {
+export interface ReviewNativeInstanceSelectionInput extends NativeSelectedPlanningInput, NativeInstanceSelectionReviewOptions {
     model?: BaseChatModel;
     signal?: AbortSignal;
     rejectedProposals?: NativePlanningRejectedProposal[];

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

@@ -1,6 +1,7 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { ReviewableWorkflowGraphProposal, ReviewableWorkflowPlanningContext, WorkflowReviewGap, PlannedNativeNode, ExplainedWorkflowConnection, ExplainedWorkflowBlockedCall } from '@openapi-flow/core';
 import type { ExplainedGraphNativeNode } from './workflow-planning.js';
+import type { WorkflowConnectionSelectionOutput } from './workflow-connection-selection.js';
 export interface PlanReviewableWorkflowGraphInput extends ReviewableWorkflowPlanningContext {
     scenario: string;
     model: BaseChatModel;
@@ -13,7 +14,7 @@ export type ReviewableWorkflowGraphPlanningFailure = {
     output: unknown;
 } | {
     stage: 'graph-validation';
-    output: ReviewableWorkflowGraphModelOutput;
+    output: ReviewableWorkflowGraphModelOutput | WorkflowConnectionSelectionOutput;
 };
 export type ReviewableWorkflowGraphOutput = Omit<ReviewableWorkflowGraphProposal, 'nativeNodes' | 'blockedCalls'> & {
     additionalNativeNodes?: ReviewableWorkflowGraphProposal['nativeNodes'];

package/dist/types/workflow-connection-selection.d.ts

@@ -0,0 +1,19 @@
+import type { z } from 'zod';
+import type { createWorkflowConnectionSelectionSchema } from '../schemas/workflow-connection-selection-schema.js';
+import type { WorkflowConnectionProposal, BlockedWorkflowCall, WorkflowPlanEdge } from '@openapi-flow/core';
+export type WorkflowConnectionSelectionOutput = z.infer<ReturnType<typeof createWorkflowConnectionSelectionSchema>>;
+export type WorkflowConnectionExecutionEdge = Omit<WorkflowConnectionSelectionOutput['edges'][number], 'reason'> & {
+    reason?: unknown;
+};
+export type WorkflowConnectionExecutionBlockedCall = BlockedWorkflowCall & {
+    reason?: unknown;
+};
+export interface WorkflowConnectionExecutionOutput extends Omit<WorkflowConnectionProposal, 'edges' | 'blockedCalls'> {
+    reason?: unknown;
+    edges: WorkflowConnectionExecutionEdge[];
+    blockedCalls?: WorkflowConnectionExecutionBlockedCall[];
+}
+export type ResolvedWorkflowConnectionSelectionEdge = WorkflowPlanEdge & Pick<WorkflowConnectionExecutionEdge, 'reason'>;
+export interface ResolvedWorkflowConnectionSelection extends Omit<WorkflowConnectionExecutionOutput, 'edges'> {
+    edges: ResolvedWorkflowConnectionSelectionEdge[];
+}

package/dist/types/workflow-connection-selection.js

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

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

@@ -0,0 +1,6 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowIntentInput } from '@openapi-flow/core';
+export interface PlanWorkflowIntentInput extends WorkflowIntentInput {
+    model: BaseChatModel;
+    signal?: AbortSignal;
+}

package/dist/types/workflow-intent.js

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

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

@@ -1,5 +1,5 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection } from '@openapi-flow/core';
+import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection, WorkflowConnectionExplanationIssue } from '@openapi-flow/core';
 import type { ReviewableWorkflowGraphOutput } from './reviewable-workflow-planning.js';
 export interface PlanWorkflowConnectionsInput extends WorkflowConnectionPlanningInput {
     model: BaseChatModel;
@@ -18,4 +18,5 @@ export type WorkflowConnectionPlanningOutput = ReviewableWorkflowGraphOutput | W
 export interface ResolvedWorkflowConnectionOutput {
     proposal: WorkflowConnectionProposal;
     decision?: WorkflowConnectionDecision;
+    explanationIssues?: WorkflowConnectionExplanationIssue[];
 }

package/dist/workflow/connections/invoke-connection-planning-model.js

@@ -33,7 +33,10 @@ export async function invokeConnectionPlanningModel(input) {
             ? {}
             : { requestFingerprint: input.requestFingerprint }),
     }, () => {
-        const parsed = input.schema.parse(output);
+        const receiver = input.validationSchema === undefined
+            ? input.schema
+            : input.validationSchema;
+        const parsed = receiver.parse(output);
         if (!isDeepStrictEqual(parsed, output))
             throw new Error('Connection output schema must not default, coerce or transform model data');
         return parsed;

package/dist/workflow/connections/review-workflow-connection-goals.js

@@ -33,6 +33,7 @@ export async function reviewWorkflowConnectionGoals(input) {
         operation,
         name: 'review_workflow_connection_goals',
         schema: createWorkflowConnectionGoalReviewSchema(description),
+        validationSchema: createWorkflowConnectionGoalReviewSchema(description, false),
         sourceFingerprint: description.sourceFingerprint,
         messages: [
             new SystemMessage(workflowConnectionGoalReviewPrompt),

package/dist/workflow/generate-native-node-parameters.js

@@ -1,5 +1,5 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, } from '@openapi-flow/core';
+import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, resolveNativeProducerParameters, } from '@openapi-flow/core';
 import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 import { nativeNodeParametersPrompt } from '../prompts/native-node-planning-prompt.js';
 import { NativeNodePlanningError } from './native-node-planning-error.js';
@@ -9,6 +9,9 @@ export async function generateNativeNodeParameters(input) {
     if (input.model !== undefined &&
         (!input.model || typeof input.model.withStructuredOutput !== 'function'))
         throw new Error('generateNativeNodeParameters.model must support structured output when supplied');
+    const derived = resolveNativeProducerParameters(input);
+    if (derived !== undefined)
+        return derived;
     const description = describeNativeNodeConfiguration(input);
     if (!description.instance.hasLiteralParameters)
         return resolveNativeNodeParameters({
@@ -29,6 +32,7 @@ export async function generateNativeNodeParameters(input) {
     if (!input.model || typeof input.model.withStructuredOutput !== 'function')
         throw new Error('generateNativeNodeParameters.model must support structured output for remaining values');
     const schema = createNativeNodeParametersSchema(input);
+    const validationSchema = createNativeNodeParametersSchema(input, false);
     const capability = description.context.capabilities.find((entry) => entry.name === description.instance.capability);
     if (!capability)
         throw new Error('Native parameter generation has no selected capability material');
@@ -67,7 +71,7 @@ export async function generateNativeNodeParameters(input) {
     input.signal?.throwIfAborted();
     try {
         // Validate output separately so callers can distinguish a malformed reply from stale source material.
-        schema.parse(output);
+        validationSchema.parse(output);
     }
     catch (cause) {
         if (!(cause instanceof Error))