@openapi-flow/langchain 0.4.0 → 0.4.2

package/dist/schemas/api-literal-generation-output-schema.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createApiRequestInputPointerSchema, apiInputLiteralSourceSchema, } from '@openapi-flow/core';
+import { createApiRequestInputPointerSchema, apiInputLiteralSourceSchema, optionalPlanningExplanationObjectSchema, } from '@openapi-flow/core';
 export const apiLiteralGenerationOptionsSchema = z.strictObject({
     includeExplanations: z.boolean().optional(),
     selectOasEnums: z.boolean().optional(),
@@ -15,27 +15,37 @@ export const apiLiteralGenerationReasonSchema = z.strictObject({
 export const apiLiteralGenerationSourcesSchema = z.array(apiInputLiteralSourceSchema.extend({
     targetPointer: z
         .string()
-        .describe('RFC 6901 pointer relative to values, e.g. /query/id, never /values/query/id. Cover each proposed literal leaf or an explicitly quoted whole object/array. Code verifies exact occurrence, JSON type equality and complete coverage. The original scenario is the only source; purpose and OAS values are not literal quotations.'),
+        .describe('RFC 6901 pointer relative to values, e.g. /query/id, never /values/query/id. Cover each proposed literal leaf or an explicitly quoted whole object/array. Code verifies exact occurrence, JSON type equality and complete coverage. Use literalSourceMessages when supplied; otherwise use the original scenario. Purpose, OAS and feedback are not literal quotations.'),
 }));
+function createLiteralSourcesSchema(messages) {
+    if (messages === undefined || messages.length === 1)
+        return apiLiteralGenerationSourcesSchema.min(1);
+    const ids = messages.map((message) => message.id);
+    return z
+        .array(apiLiteralGenerationSourcesSchema.element.extend({
+        messageId: z
+            .enum(ids)
+            .describe('Select the supplied original message containing this exact quotation. Never cite scenario context or feedback instead.'),
+    }))
+        .min(1);
+}
 export const apiLiteralNotProvidedSchema = z.strictObject({
     state: z
         .literal('not-provided')
         .describe('No request literal was supplied by the scenario for this call. Code owns the empty values and source list. Do not supply a placeholder body, values, or literalSources in this decision.'),
 });
-export function createApiLiteralProvidedSchema(contract) {
+export function createApiLiteralProvidedSchema(contract, messages) {
     return z.strictObject({
         state: z.literal('provided'),
         values: contract.valuesSchema.refine((values) => Object.entries(values).some(([group, value]) => group === 'body' ||
             (value !== null &&
                 typeof value === 'object' &&
                 Object.keys(value).length > 0)), 'Provided literals require an actual request value, not empty parameter-location containers.'),
-        literalSources: apiLiteralGenerationSourcesSchema
-            .min(1)
-            .describe('Every provided literal, including an empty object, empty array, empty string or null, needs its original exact user source. Never use a source-free placeholder.'),
+        literalSources: createLiteralSourcesSchema(messages).describe('Every provided literal, including an empty object, empty array, empty string or null, needs its original exact user source. Never use a source-free placeholder.'),
     });
 }
-export function createApiTrackedLiteralGenerationSchema(contract, requestSchema) {
-    const provided = createApiLiteralProvidedSchema(contract);
+export function createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages) {
+    const provided = createApiLiteralProvidedSchema(contract, messages);
     const schema = z.strictObject({
         literalInputs: z.union([apiLiteralNotProvidedSchema, provided]),
         requestedInputs: z
@@ -45,19 +55,25 @@ export function createApiTrackedLiteralGenerationSchema(contract, requestSchema)
     });
     return schema;
 }
-export function createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema) {
-    return createApiTrackedLiteralGenerationSchema(contract, requestSchema).extend({
-        explanation: apiLiteralGenerationReasonSchema,
+export function createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages, requireExplanations = true) {
+    return createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages).extend({
+        explanation: requireExplanations
+            ? apiLiteralGenerationReasonSchema
+            : optionalPlanningExplanationObjectSchema,
     });
 }
 /** Tracked generation separates absence from literal empty values; the OAS value contract stays unchanged. */
-export function createApiLiteralGenerationOutputSchema(contract, includeExplanations, requestSchema) {
+export function createApiLiteralGenerationOutputSchema(contract, includeExplanations, requestSchema, messages, requireExplanations = true) {
     z.boolean().parse(includeExplanations);
     if (requestSchema !== undefined)
         return includeExplanations && contract.hasLiteralInputs
-            ? createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema)
-            : createApiTrackedLiteralGenerationSchema(contract, requestSchema);
+            ? createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages, requireExplanations)
+            : createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages);
     return includeExplanations && contract.hasLiteralInputs
-        ? contract.schema.extend({ explanation: apiLiteralGenerationReasonSchema })
+        ? contract.schema.extend({
+            explanation: requireExplanations
+                ? apiLiteralGenerationReasonSchema
+                : optionalPlanningExplanationObjectSchema,
+        })
         : contract.schema;
 }

package/dist/schemas/api-request-media-type-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare function createApiRequestMediaTypeSchema(mediaTypes: string[], includeExplanations?: boolean): z.ZodObject<{
+export declare function createApiRequestMediaTypeSchema(mediaTypes: string[], includeExplanations?: boolean, requireExplanations?: boolean): z.ZodObject<{
     requestMediaType: z.ZodNullable<z.ZodEnum<{
         [x: string]: string;
     }>>;

package/dist/schemas/api-request-media-type-schema.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-export function createApiRequestMediaTypeSchema(mediaTypes, includeExplanations = false) {
+import { optionalPlanningExplanationObjectSchema } from '@openapi-flow/core';
+export function createApiRequestMediaTypeSchema(mediaTypes, includeExplanations = false, requireExplanations = true) {
     z.boolean().parse(includeExplanations);
     if (mediaTypes.length < 2)
         throw new Error('request media selection requires multiple declared media types');
@@ -9,6 +10,10 @@ export function createApiRequestMediaTypeSchema(mediaTypes, includeExplanations
             .nullable()
             .describe('Exact OAS requestBody.content key matching an explicitly requested format, or null when the scenario leaves the format unspecified or ambiguous so code can apply the documented default. This is the request Content-Type, not the response format.'),
     });
+    if (!requireExplanations)
+        return schema.extend({
+            explanation: optionalPlanningExplanationObjectSchema,
+        });
     return includeExplanations
         ? schema.extend({
             explanation: z.strictObject({

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/create-connection-material-repair-choice-schema.js

@@ -8,7 +8,9 @@ export function createConnectionMaterialRepairChoiceSchema(stages, factIds) {
         if (!stage.nodeIds.length)
             continue;
         targets.push(workflowConnectionMaterialRepairTargetSchema.extend({
-            stage: z.literal(stage.stage),
+            stage: z
+                .literal(stage.stage)
+                .describe('Origin-stage ownership: api-bindings changes API producer references; api-arguments changes only API literals/requested inputs and retains bindings; native-dependencies changes native producer IDs and then regenerates its settings; native-parameters changes settings or pointers while retaining the existing producer IDs. Request native-dependencies for a producer substitution, not native-parameters alone.'),
             nodeId: z.enum(stage.nodeIds),
         }));
     }

package/dist/schemas/native-planning-rejection-schema.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+/** Private, lossless model-output feedback; not a public progress/error payload. */
+export declare const nativePlanningRejectionSchema: z.ZodObject<{
+    stage: z.ZodEnum<{
+        "instance-selection": "instance-selection";
+        "selection-review": "selection-review";
+    }>;
+    requestFingerprint: z.ZodString;
+    output: z.ZodJSONSchema;
+    reason: z.ZodString;
+}, z.core.$strict>;

package/dist/schemas/native-planning-rejection-schema.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** Private, lossless model-output feedback; not a public progress/error payload. */
+export const nativePlanningRejectionSchema = z.strictObject({
+    stage: z.enum(['instance-selection', 'selection-review']),
+    requestFingerprint: z.string().regex(/^[a-f0-9]{64}$/u),
+    output: z.json(),
+    reason: z.string().min(1),
+});

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/api-call-binding-planning.d.ts

@@ -1,12 +1,13 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { z } from 'zod';
 import type { createApiBindingSourceDecisionSchema } from '../schemas/api-call-binding-plan-schema.js';
-import type { ApiCallBindingPlanningInput, ApiBindingSourceSelection, ApiCallBindingPlan, ApiBindingSourceProposal } from '@openapi-flow/core';
+import type { ApiCallBindingPlanningInput, ApiBindingSourceSelection, ApiCallBindingPlan, ApiBindingSourceProposal, WorkflowConnectionApiRepairContext } from '@openapi-flow/core';
 import type { PlanApiBindingsInput } from './binding-planning.js';
 export type ApiBindingSourceDecisionOutput = z.infer<ReturnType<typeof createApiBindingSourceDecisionSchema>> & Pick<ApiBindingSourceProposal, 'reason'>;
 export interface SelectApiBindingSourcesInput extends ApiCallBindingPlanningInput {
     model: BaseChatModel;
     signal?: AbortSignal;
+    materialRepair?: WorkflowConnectionApiRepairContext;
 }
 export interface PlanApiCallBindingsInput extends SelectApiBindingSourcesInput {
     sources: ApiBindingSourceSelection;