@openapi-flow/langchain 0.4.1 → 0.4.3

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(),
@@ -32,11 +32,13 @@ function createLiteralSourcesSchema(messages) {
 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.'),
+        .describe('No actual request literal was selected by the user for this call. Examples, unchosen alternatives and values the user will supply later are not selected literals. Code owns the empty values and source list. Do not supply a placeholder body, values, or literalSources in this decision.'),
 });
 export function createApiLiteralProvidedSchema(contract, messages) {
     return z.strictObject({
-        state: z.literal('provided'),
+        state: z
+            .literal('provided')
+            .describe('The user explicitly directs using these actual values for this call. Source occurrence alone does not turn an example, an unchosen alternative or a future input into a selected literal.'),
         values: contract.valuesSchema.refine((values) => Object.entries(values).some(([group, value]) => group === 'body' ||
             (value !== null &&
                 typeof value === 'object' &&
@@ -44,7 +46,13 @@ export function createApiLiteralProvidedSchema(contract, messages) {
         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, messages) {
+export function createApiEnumIntentInputsSchema(requestSchema) {
+    return z
+        .array(createApiRequestInputPointerSchema(requestSchema))
+        .refine((pointers) => new Set(pointers).size === pointers.length)
+        .describe('Only missing input paths whose actual requested value meaning is expressed in natural language and therefore needs OAS enum interpretation. Code includes these paths in requested-input presence; do not duplicate them solely for that purpose. Return [] for unknown values, examples, unchosen alternatives or values to supply later. Requiredness or a requested field name is not a supplied value meaning. Do not include already supplied literals, confirmed inputs or bindings. Code schedules the next semantic call only for this explicit list and validates each path against unanswered OAS enum contracts.');
+}
+export function createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages, selectOasEnums = false) {
     const provided = createApiLiteralProvidedSchema(contract, messages);
     const schema = z.strictObject({
         literalInputs: z.union([apiLiteralNotProvidedSchema, provided]),
@@ -53,21 +61,31 @@ export function createApiTrackedLiteralGenerationSchema(contract, requestSchema,
             .refine((pointers) => new Set(pointers).size === pointers.length)
             .describe('Exact OAS request pointers explicitly requested for this call, even when the value is not given verbatim. Include requested optional inputs. Do not select unrequested filters, OAS defaults or examples. Code validates the original OAS and missing presence. This field contains paths, never values or bindings.'),
     });
-    return schema;
+    return selectOasEnums
+        ? schema.extend({
+            enumIntentInputs: createApiEnumIntentInputsSchema(requestSchema),
+        })
+        : schema;
 }
-export function createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages) {
-    return createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages).extend({
-        explanation: apiLiteralGenerationReasonSchema,
+export function createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages, requireExplanations = true, selectOasEnums = false) {
+    return createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages, selectOasEnums).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, messages) {
+export function createApiLiteralGenerationOutputSchema(contract, includeExplanations, requestSchema, messages, requireExplanations = true, selectOasEnums = false) {
     z.boolean().parse(includeExplanations);
     if (requestSchema !== undefined)
         return includeExplanations && contract.hasLiteralInputs
-            ? createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages)
-            : createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages);
+            ? createApiExplainedTrackedLiteralGenerationSchema(contract, requestSchema, messages, requireExplanations, selectOasEnums)
+            : createApiTrackedLiteralGenerationSchema(contract, requestSchema, messages, selectOasEnums);
     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/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

@@ -1,9 +1,9 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { ApiLiteralGenerationInput, ApiCallArguments, ApiArgumentProposal, ApiLiteralProposalSource, OpenApiFlowError, WorkflowConnectionApiRepairContext, ApiInputLiteralSource } from '@openapi-flow/core';
+import type { ApiLiteralGenerationInput, ApiCallArguments, ApiArgumentProposal, ApiLiteralProposalSource, OpenApiFlowError, WorkflowConnectionApiRepairContext, ApiInputLiteralSource, ApiArgumentEnumContextInput } from '@openapi-flow/core';
 import type { z } from 'zod';
 import type { apiLiteralGenerationReasonSchema } from '../schemas/api-literal-generation-output-schema.js';
 import type { apiLiteralNotProvidedSchema } from '../schemas/api-literal-generation-output-schema.js';
-import type { createApiLiteralProvidedSchema, createApiTrackedLiteralGenerationSchema, createApiExplainedTrackedLiteralGenerationSchema } from '../schemas/api-literal-generation-output-schema.js';
+import type { createApiLiteralProvidedSchema, createApiTrackedLiteralGenerationSchema, createApiExplainedTrackedLiteralGenerationSchema, createApiEnumIntentInputsSchema } from '../schemas/api-literal-generation-output-schema.js';
 import type { apiLiteralGenerationOptionsSchema } from '../schemas/api-literal-generation-output-schema.js';
 import type { apiArgumentRejectionSchema } from '../schemas/api-argument-rejection-schema.js';
 export interface GenerateApiArgumentsInput extends ApiLiteralGenerationInput {
@@ -31,20 +31,20 @@ export interface ApiArgumentPlanningFailure {
     sourceFingerprint: string;
     output: unknown;
 }
-export interface InterpretApiArgumentEnumsInput extends GenerateApiArgumentsInput {
+export interface InterpretApiArgumentEnumsInput extends GenerateApiArgumentsInput, Required<Pick<ApiArgumentEnumContextInput, 'enumIntentInputs'>> {
     arguments: ApiCallArguments;
     proposal: ApiArgumentProposal;
     literalSources: ApiLiteralProposalSource[];
 }
 export type ApiLiteralProvidedDecision = z.infer<ReturnType<typeof createApiLiteralProvidedSchema>>;
 export type ApiLiteralAvailabilityDecision = z.infer<typeof apiLiteralNotProvidedSchema> | ApiLiteralProvidedDecision;
-export type ApiTrackedLiteralGenerationOutput = z.infer<ReturnType<typeof createApiTrackedLiteralGenerationSchema>> | z.infer<ReturnType<typeof createApiExplainedTrackedLiteralGenerationSchema>>;
+export type ApiTrackedLiteralGenerationOutput = (z.infer<ReturnType<typeof createApiTrackedLiteralGenerationSchema>> | z.infer<ReturnType<typeof createApiExplainedTrackedLiteralGenerationSchema>>) & Partial<Record<'enumIntentInputs', z.infer<ReturnType<typeof createApiEnumIntentInputsSchema>>>>;
 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>;
-export interface ResolvedApiLiteralGenerationOutput extends ApiArgumentProposal {
+export interface ResolvedApiLiteralGenerationOutput extends ApiArgumentProposal, Pick<ApiArgumentEnumContextInput, 'enumIntentInputs'> {
     requestedInputs?: string[];
     literalSources?: ApiLiteralGenerationSource[];
     explanation?: z.infer<typeof apiLiteralGenerationReasonSchema>;

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[];