@openapi-flow/langchain 0.2.0 → 0.3.0

package/dist/schemas/api-input-answer-source-schema.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { createApiInputSourceSelectionSchema } from '@openapi-flow/core';
+export const apiInputAnswerExplanationOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+/** Values and unanswered IDs are deliberately not model-owned output fields. */
+export function createApiInputAnswerSourceSchema(requirements, catalog, includeExplanations = false) {
+    const ids = requirements.map((item) => item.id);
+    if (!ids.length || new Set(ids).size !== ids.length)
+        throw new Error('Answer source schema requires distinct pending requirements');
+    const reason = z
+        .string()
+        .min(1)
+        .describe("A brief user-facing reason in the user's language, grounded only in this reply and the supplied pending questions. Instruction/schema language does not set the user's language. Never translate input values, identifiers or original source spans. Not a hidden reasoning trace or a claim that code validation passed.");
+    const answer = z.strictObject({
+        requirementId: z
+            .enum(ids)
+            .describe('The offered pending question answered by this exact source span.'),
+        source: createApiInputSourceSelectionSchema(catalog),
+        ...(includeExplanations ? { reason } : {}),
+    });
+    return z.strictObject({
+        answers: z
+            .array(answer)
+            .describe('Select each answered pending question at most once. Return [] when the reply gives no complete requested value. Do not return a value field or fabricate missing inputs.'),
+        ...(includeExplanations ? { reason } : {}),
+    });
+}

package/dist/schemas/api-literal-generation-output-schema.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { ApiArgumentGenerationContract } from '@openapi-flow/core';
+import type { ApiLiteralGenerationOutputSchema } from '../types/argument-generation.js';
+export declare const apiLiteralGenerationOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const apiLiteralGenerationReasonSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strict>;
+/** The core values schema is unchanged; only optional human-readable attribution is added. */
+export declare function createApiLiteralGenerationOutputSchema(contract: ApiArgumentGenerationContract, includeExplanations: boolean): ApiLiteralGenerationOutputSchema;

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

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export const apiLiteralGenerationOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+export const apiLiteralGenerationReasonSchema = z.strictObject({
+    reason: z
+        .string()
+        .min(1)
+        .refine((value) => value.trim().length > 0)
+        .describe('Brief user-facing reason in the scenario language for these proposed literals or their deliberate omission. It applies only to values in this proposal, not confirmed inputs or preceding-node bindings. Code attaches the original scenario, optional call role and the actual projected literal input contract. Do not generate evidence, source quotes, OAS schemas, metadata, missing-input reports or private chain-of-thought.'),
+});
+/** The core values schema is unchanged; only optional human-readable attribution is added. */
+export function createApiLiteralGenerationOutputSchema(contract, includeExplanations) {
+    z.boolean().parse(includeExplanations);
+    return includeExplanations && contract.hasLiteralInputs
+        ? contract.schema.extend({
+            explanation: apiLiteralGenerationReasonSchema,
+        })
+        : contract.schema;
+}

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

@@ -1,3 +1,6 @@
 import { z } from 'zod';
-import type { ApiRequestMediaTypeOutput } from '../types/request-media-selection.js';
-export declare function createApiRequestMediaTypeSchema(mediaTypes: string[]): z.ZodType<ApiRequestMediaTypeOutput>;
+export declare function createApiRequestMediaTypeSchema(mediaTypes: string[], includeExplanations?: boolean): z.ZodObject<{
+    requestMediaType: z.ZodNullable<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+}, z.core.$strict>;

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

@@ -1,11 +1,23 @@
 import { z } from 'zod';
-export function createApiRequestMediaTypeSchema(mediaTypes) {
+export function createApiRequestMediaTypeSchema(mediaTypes, includeExplanations = false) {
+    z.boolean().parse(includeExplanations);
     if (mediaTypes.length < 2)
         throw new Error('request media selection requires multiple declared media types');
-    return z.strictObject({
+    const schema = z.strictObject({
         requestMediaType: z
             .enum(mediaTypes)
             .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.'),
     });
+    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 the explicit format match, or for returning null because the format is unspecified/ambiguous. Explain the assessment only; code chooses any documented default and attaches the exact scenario and OAS requestBody. Do not generate quotations, source identities, expected responses or private chain-of-thought.'),
+            }),
+        })
+        : schema;
 }

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

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export declare function createApiSelectionAnalysisSchema(candidateIds: string[], includeExplanations?: 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.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    gaps: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        description: z.ZodString;
+        explanation: z.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    questions: z.ZodArray<z.ZodObject<{
+        message: z.ZodString;
+        purpose: z.ZodString;
+        candidateIds: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+    }, z.core.$strict> | z.ZodObject<{
+        message: z.ZodString;
+        purpose: z.ZodString;
+        candidateIds: z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        explanation: z.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

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

@@ -0,0 +1,23 @@
+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) {
+    return createApiSelectionSchema(candidateIds, includeExplanations).extend({
+        questions: z
+            .array(withApiSelectionExplanation(z.strictObject({
+            message: z
+                .string()
+                .min(1)
+                .describe('Ask only a consequential unresolved API-role choice. Do not ask for request values before reading full contracts.'),
+            purpose: z
+                .string()
+                .min(1)
+                .describe('The one user-requested role that will be fulfilled by exactly one offered candidate.'),
+            candidateIds: z
+                .array(z.enum(candidateIds))
+                .min(2)
+                .describe('Distinct supplied alternatives for this role, not API calls that should all run.'),
+        }), includeExplanations))
+            .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-options-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export declare const apiSelectionOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;

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

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export const apiSelectionOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});

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

@@ -1,12 +1,25 @@
 import { z } from 'zod';
-export declare function createApiSelectionSchema(candidateIds: string[]): z.ZodObject<{
+export declare function createApiSelectionSchema(candidateIds: string[], includeExplanations?: 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.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strict>;
     }, z.core.$strict>>;
     gaps: z.ZodArray<z.ZodObject<{
         description: z.ZodString;
+    }, z.core.$strict> | z.ZodObject<{
+        description: z.ZodString;
+        explanation: z.ZodObject<{
+            reason: z.ZodString;
+        }, z.core.$strict>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

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

@@ -1,11 +1,12 @@
 import { z } from 'zod';
-export function createApiSelectionSchema(candidateIds) {
+import { withApiSelectionExplanation } from './with-api-selection-explanation.js';
+export function createApiSelectionSchema(candidateIds, includeExplanations = false) {
     if (candidateIds.length === 0)
         throw new Error('operations must contain candidates for model selection');
     return z
         .object({
         operations: z
-            .array(z
+            .array(withApiSelectionExplanation(z
             .object({
             candidateId: z
                 .enum(candidateIds)
@@ -15,16 +16,16 @@ export function createApiSelectionSchema(candidateIds) {
                 .min(1)
                 .describe('The scenario role of this one API call instance. Describe separate required calls separately; this is not an execution order.'),
         })
-            .strict())
+            .strict(), includeExplanations))
             .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(z
+        gaps: z.array(withApiSelectionExplanation(z
             .object({
             description: z
                 .string()
                 .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()),
+            .strict(), includeExplanations)),
     })
         .strict();
 }

package/dist/schemas/create-workflow-message-evidence-selection-schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { WorkflowSourceMessage } from '@openapi-flow/core';
+/** Resolve only an explicitly selected current source ID, from a captured immutable snapshot. */
+export declare function createWorkflowMessageEvidenceSelectionSchema(supplied: WorkflowSourceMessage[]): z.ZodPipe<z.ZodObject<{
+    kind: z.ZodLiteral<"message">;
+    messageId: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+}, z.core.$strict>, z.ZodTransform<{
+    quote: string;
+    kind: "message";
+    messageId: string;
+}, {
+    kind: "message";
+    messageId: string;
+}>>;

package/dist/schemas/create-workflow-message-evidence-selection-schema.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/** Resolve only an explicitly selected current source ID, from a captured immutable snapshot. */
+export function createWorkflowMessageEvidenceSelectionSchema(supplied) {
+    const messages = z
+        .array(z.strictObject({ id: z.string().min(1), text: z.string().min(1) }))
+        .min(1)
+        .refine((items) => new Set(items.map((item) => item.id)).size === items.length)
+        .parse(supplied);
+    return z
+        .strictObject({
+        kind: z.literal('message'),
+        messageId: z
+            .enum(messages.map((message) => message.id))
+            .describe('Select a supplied message ID only. Code attaches its unchanged original text; never generate a quote.'),
+    })
+        .transform((selection) => {
+        const message = messages.find((item) => item.id === selection.messageId);
+        if (!message)
+            throw new Error(`Message evidence selection references unavailable source ${selection.messageId}`);
+        return { ...selection, quote: message.text };
+    });
+}

package/dist/schemas/native-node-explanation-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare const nativeNodeExplanationOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const nativeNodePlanningReasonSchema: z.ZodString;

package/dist/schemas/native-node-explanation-schema.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const nativeNodeExplanationOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+export const nativeNodePlanningReasonSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0)
+    .describe('Brief user-facing reason in the scenario language for this proposed native instance and its requested parameter values, or for adding no new instance. Explain the proposal, not private chain-of-thought. Code attaches the actual supplied scenario, API roles, prepared nodes and capability schemas. Never generate evidence, ports, output schemas, source quotes, slot IDs or n8n JSON.');

package/dist/schemas/native-node-parameter-contract.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowCapability } from '@openapi-flow/core';
+import type { NativeNodeParameterContract } from '../types/native-node-planning.js';
+export declare function createNativeNodeParameterContract(capability: WorkflowCapability, allowRuntimeParameters: boolean): NativeNodeParameterContract;

package/dist/schemas/native-node-parameter-contract.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { createNativePlanningCapabilityMaterial } from '@openapi-flow/core';
+export function createNativeNodeParameterContract(capability, allowRuntimeParameters) {
+    const identity = {
+        id: z
+            .string()
+            .min(1)
+            .describe('Unique native instance ID, distinct from every supplied API, prepared native and gap ID.'),
+        capability: z.literal(capability.name).describe(capability.description),
+    };
+    const schemas = [];
+    const material = createNativePlanningCapabilityMaterial(capability, allowRuntimeParameters);
+    if (allowRuntimeParameters && capability.supportsRuntimeParameters === true) {
+        schemas.push(z.strictObject({
+            ...identity,
+            parameterSource: z
+                .literal('literal')
+                .describe('Choose only actual values supplied in the scenario, never placeholders or invented defaults.'),
+            parameters: capability.parametersSchema,
+        }), z.strictObject({
+            ...identity,
+            parameterSource: z
+                .literal('workflow-input')
+                .describe('Choose when actual complete parameter values must be supplied at execution and this capability has runtime-independent ports, references and output schema. Never generate any parameters, placeholders or runtime flags here. Code derives the empty parameter object, runtime flag, slot ID and original schema.'),
+        }));
+    }
+    else
+        schemas.push(z.strictObject({ ...identity, parameters: capability.parametersSchema }));
+    return { schemas, material };
+}

package/dist/schemas/native-node-planning-contract.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowCapability } from '@openapi-flow/core';
+import type { NativeNodePlanningContract } from '../types/native-node-planning.js';
+export declare function createNativeNodePlanningContract(capabilities: WorkflowCapability[], allowRuntimeParameters?: boolean, includeExplanations?: boolean): NativeNodePlanningContract;

package/dist/schemas/native-node-planning-contract.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { createNativeNodeParameterContract } from './native-node-parameter-contract.js';
+import { nativeNodePlanningReasonSchema } from './native-node-explanation-schema.js';
+export function createNativeNodePlanningContract(capabilities, allowRuntimeParameters = false, includeExplanations = false) {
+    if (!capabilities.length)
+        throw new Error('native planning schema requires supplied capabilities');
+    const contracts = capabilities.map((capability) => createNativeNodeParameterContract(capability, allowRuntimeParameters));
+    const nodes = contracts.flatMap((contract) => contract.schemas);
+    const nodeSchema = z.union([nodes[0], ...nodes.slice(1)]);
+    const gaps = z
+        .array(z.strictObject({
+        description: nativeNodePlanningReasonSchema.describe('Describe a requested native behavior that cannot be represented and the missing capability or contract. Never a reminder to generate API requests, bindings or connections later.'),
+    }))
+        .describe('Blocking unmet native behavior only. Return [] when requested native behavior is representable. Selected OAS API calls are implemented separately; their bindings, request arguments and connections belong to later stages, not these gaps. Never invent missing data or substitute a capability.');
+    const schema = includeExplanations
+        ? z.strictObject({
+            decision: z.union([
+                z.strictObject({
+                    additions: z
+                        .array(z.strictObject({
+                        node: nodeSchema,
+                        reason: nativeNodePlanningReasonSchema,
+                    }))
+                        .min(1)
+                        .describe('Only NEW native instances required by the scenario. Code extracts node data and keeps the reason outside executable parameters.'),
+                    gaps,
+                }),
+                z.strictObject({
+                    noAdditionalNodesReason: nativeNodePlanningReasonSchema.describe('Why no NEW native instance is proposed, including when prepared nodes suffice or only unmet native requirements remain. Do not repeat supplied nodes or generate a fixed empty node array.'),
+                    gaps,
+                }),
+            ]),
+        })
+        : z.strictObject({
+            nativeNodes: z
+                .array(nodeSchema)
+                .describe('Only new instances required by the scenario, with values following the supplied implementation schema. No ports, output schemas, code or n8n JSON.'),
+            gaps,
+        });
+    return {
+        schema,
+        capabilities: contracts.map((contract) => contract.material),
+    };
+}

package/dist/schemas/request-media-selection-options-schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export declare const requestMediaSelectionOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;

package/dist/schemas/request-media-selection-options-schema.js

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export const requestMediaSelectionOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});

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

@@ -1,4 +1,6 @@
 import { z } from 'zod';
 import type { WorkflowCapability } from '@openapi-flow/core';
-import type { ReviewableWorkflowGraphOutput } from '../types/reviewable-workflow-planning.js';
-export declare function createReviewableWorkflowGraphSchema(capabilities: WorkflowCapability[], readyCallIds: string[]): z.ZodType<ReviewableWorkflowGraphOutput>;
+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>;

package/dist/schemas/reviewable-workflow-graph-schema.js

@@ -1,6 +1,15 @@
 import { z } from 'zod';
-export function createReviewableWorkflowGraphSchema(capabilities, readyCallIds) {
+import { workflowConnectionReasonSchema } from './workflow-connection-explanation-schema.js';
+import { workflowGraphReasonSchema } from './workflow-graph-explanation-schema.js';
+export function createReviewableWorkflowGraphSchema(capabilities, readyCallIds, explanationMode = 'none') {
+    const includeExplanations = explanationMode !== 'none';
+    const reasonSchema = explanationMode === 'graph'
+        ? workflowGraphReasonSchema
+        : workflowConnectionReasonSchema;
     const natives = capabilities.map((capability) => z.strictObject({
+        ...(explanationMode === 'graph'
+            ? { reason: workflowGraphReasonSchema }
+            : {}),
         id: z
             .string()
             .min(1)
@@ -16,6 +25,7 @@ export function createReviewableWorkflowGraphSchema(capabilities, readyCallIds)
     const blockedCalls = readyCallIds.length === 0
         ? undefined
         : z.array(z.strictObject({
+            ...(includeExplanations ? { reason: reasonSchema } : {}),
             callId: z
                 .enum(readyCallIds)
                 .describe('A supplied ready call that must instead be a failing placeholder because a scenario dependency remains unresolved. Do not repeat already blocked calls.'),
@@ -25,8 +35,10 @@ export function createReviewableWorkflowGraphSchema(capabilities, readyCallIds)
                 .describe('IDs of supplied or additional gaps that prevent this API call. Never fabricate a response binding.'),
         }));
     const base = z.strictObject({
+        ...(includeExplanations ? { reason: reasonSchema } : {}),
         edges: z
             .array(z.strictObject({
+            ...(includeExplanations ? { reason: reasonSchema } : {}),
             from: z
                 .string()
                 .min(1)

package/dist/schemas/serialize-structured-output-schema.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { JsonObject } from '@openapi-flow/core';
+import type { StructuredOutputSchemaDialect, StructuredOutputSchemaDirection, StructuredOutputSchemaReuse } from '../types/structured-output-schema.js';
+/** Send JSON data, not Zod's non-enumerable Standard Schema re-serialization hook. */
+export declare function serializeStructuredOutputSchema(schema: z.ZodType, target: StructuredOutputSchemaDialect, io?: StructuredOutputSchemaDirection, reused?: StructuredOutputSchemaReuse): JsonObject;

package/dist/schemas/serialize-structured-output-schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/** Send JSON data, not Zod's non-enumerable Standard Schema re-serialization hook. */
+export function serializeStructuredOutputSchema(schema, target, io = 'output', reused = 'inline') {
+    return JSON.parse(JSON.stringify(z.toJSONSchema(schema, {
+        target,
+        io,
+        reused,
+        cycles: 'ref',
+    })));
+}

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

@@ -0,0 +1,4 @@
+import type { z } from 'zod';
+import type { WorkflowRequirementsModelOutput } from '../types/workflow-clarification.js';
+/** Own wire serialization; retain descriptions and avoid framework ref/title rewrites. */
+export declare function serializeWorkflowRequirementsSchema(schema: z.ZodType<WorkflowRequirementsModelOutput>): import("@openapi-flow/core").JsonObject;

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

@@ -0,0 +1,5 @@
+import { serializeStructuredOutputSchema } from './serialize-structured-output-schema.js';
+/** Own wire serialization; retain descriptions and avoid framework ref/title rewrites. */
+export function serializeWorkflowRequirementsSchema(schema) {
+    return serializeStructuredOutputSchema(schema, 'draft-7', 'input', 'ref');
+}

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

@@ -0,0 +1,10 @@
+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 & {
+    explanation: z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strict>;
+} : { [K in keyof Shape as K extends "explanation" ? never : K]: Shape[K]; } & {
+    explanation: z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strict>;
+}) extends infer T ? { [k in keyof T]: T[k]; } : never, z.core.$strict>;

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

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export function withApiSelectionExplanation(schema, includeExplanations) {
+    z.boolean().parse(includeExplanations);
+    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.'),
+            }),
+        })
+        : schema;
+}

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

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare const workflowConnectionExplanationOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const workflowConnectionReasonSchema: z.ZodString;

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

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const workflowConnectionExplanationOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+export const workflowConnectionReasonSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0)
+    .describe('Brief user-facing reason in the scenario language for this graph strategy, new edge or newly blocked call. Use only supplied roles, immutable node parameters, actual ports, declared dependencies and gaps. Explain no-new-edge/independent-root decisions in the top-level reason. Code retains original source contracts and derives starts and verification. Never generate evidence, quoted source copies or private chain-of-thought.');

package/dist/schemas/workflow-draft-edit-schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import type { ResolvedWorkflowDraftEditOptions, WorkflowDraftEditContextDescription } from '@openapi-flow/core';
+export declare function createWorkflowDraftEditSchema(context: WorkflowDraftEditContextDescription, options: ResolvedWorkflowDraftEditOptions, candidateIds: string[]): z.ZodType<import("@openapi-flow/core").WorkflowDraftEditProposal<string, import("../types/workflow-clarification.js").ProposedWorkflowPlanningEvidence>, unknown, z.core.$ZodTypeInternals<import("@openapi-flow/core").WorkflowDraftEditProposal<string, import("../types/workflow-clarification.js").ProposedWorkflowPlanningEvidence>, unknown>>;

package/dist/schemas/workflow-draft-edit-schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { createWorkflowDraftEditProposalSchema } from '@openapi-flow/core';
+import { createWorkflowPlanningEvidenceSchemas } from './workflow-planning-evidence-schemas.js';
+export function createWorkflowDraftEditSchema(context, options, candidateIds) {
+    const evidence = createWorkflowPlanningEvidenceSchemas(context.planning, candidateIds, context.requestMessageIds);
+    return createWorkflowDraftEditProposalSchema(options, {
+        ...(candidateIds.length ? { operationSchema: z.enum(candidateIds) } : {}),
+        apiNodeIds: context.draft.apiCalls.map((call) => call.id),
+        nativeNodeIds: context.draft.nativeNodes.map((node) => node.id),
+        gapNodeIds: context.draft.gapNodes?.map((node) => node.id),
+        capabilityNames: context.planning.capabilities.map((capability) => capability.name),
+        requirementIds: context.draft.requirements.map((requirement) => requirement.id),
+        removedRequirementIds: context.removedRequirements.map((requirement) => requirement.id),
+        messageSchema: evidence.message,
+        evidenceSchema: evidence.evidence,
+    });
+}

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

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export declare const workflowGraphExplanationOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const workflowGraphReasonSchema: z.ZodString;

package/dist/schemas/workflow-graph-explanation-schema.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const workflowGraphExplanationOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+export const workflowGraphReasonSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0)
+    .describe('Brief user-facing reason in the scenario language for this graph strategy, NEW native instance, edge or newly blocked call. Use only the scenario, supplied API roles/contracts, prepared instances and offered native schemas. Explain no new native nodes or independent roots in the overall reason. Code preserves source evidence and derives ports, starts and validation. Do not generate source copies, evidence, quotes or private chain-of-thought.');

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

@@ -1,4 +1,4 @@
 import { z } from 'zod';
 import type { WorkflowCapability } from '@openapi-flow/core';
-import type { WorkflowGraphOutput } from '../types/workflow-planning.js';
-export declare function createWorkflowGraphProposalSchema(capabilities: WorkflowCapability[]): z.ZodType<WorkflowGraphOutput>;
+import type { WorkflowGraphModelOutput } from '../types/workflow-planning.js';
+export declare function createWorkflowGraphProposalSchema(capabilities: WorkflowCapability[], includeExplanations?: boolean): z.ZodType<WorkflowGraphModelOutput>;

package/dist/schemas/workflow-graph-proposal-schema.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-export function createWorkflowGraphProposalSchema(capabilities) {
-    if (!capabilities.length)
-        throw new Error('capabilities must contain a native node definition');
+import { workflowGraphReasonSchema } from './workflow-graph-explanation-schema.js';
+export function createWorkflowGraphProposalSchema(capabilities, includeExplanations = false) {
     const nativeSchemas = capabilities.map((capability) => z.strictObject({
+        ...(includeExplanations ? { reason: workflowGraphReasonSchema } : {}),
         id: z
             .string()
             .min(1)
@@ -10,12 +10,11 @@ export function createWorkflowGraphProposalSchema(capabilities) {
         capability: z.literal(capability.name).describe(capability.description),
         parameters: capability.parametersSchema,
     }));
-    return z.strictObject({
-        additionalNativeNodes: z
-            .array(z.union([nativeSchemas[0], ...nativeSchemas.slice(1)]))
-            .describe('NEW native nodes only. Existing preparedNativeNodes and API materials are already present. Never repeat their IDs or parameters. Return [] when no new native node is needed.'),
+    const base = z.strictObject({
+        ...(includeExplanations ? { reason: workflowGraphReasonSchema } : {}),
         edges: z
             .array(z.strictObject({
+            ...(includeExplanations ? { reason: workflowGraphReasonSchema } : {}),
             from: z
                 .string()
                 .min(1)
@@ -35,4 +34,12 @@ export function createWorkflowGraphProposalSchema(capabilities) {
             .array(z.strictObject({ description: z.string().min(1) }))
             .describe('Only explicitly requested requirements that cannot be met. Do not invent a success/end/display requirement; a terminal node completes normally. Never invent a capability, API, or executable code.'),
     });
+    if (!nativeSchemas.length)
+        return base;
+    return z.strictObject({
+        additionalNativeNodes: z
+            .array(z.union([nativeSchemas[0], ...nativeSchemas.slice(1)]))
+            .describe('NEW native nodes only. Existing preparedNativeNodes and API materials are already present. Never repeat their IDs or parameters. Return [] when no new native node is needed.'),
+        ...base.shape,
+    });
 }