@openapi-flow/langchain 0.0.0-stage → 0.3.0

package/dist/public-api.d.ts

@@ -0,0 +1,67 @@
+export { selectApiOperations } from './selection/select-api-operations.js';
+export { analyzeApiSelection } from './selection/analyze-api-selection.js';
+export { clarifyWorkflowRequirements } from './requirements/clarify-workflow-requirements.js';
+export { analyzeWorkflowDraftEdit } from './draft/analyze-workflow-draft-edit.js';
+export { WorkflowDraftEditPlanningError } from './draft/workflow-draft-edit-planning-error.js';
+export type * from './types/workflow-draft-edit.js';
+export { selectWorkflowDraftApiInputEditTargets } from './draft/select-workflow-draft-api-input-edit-targets.js';
+export { generateWorkflowDraftApiInputEdits } from './draft/generate-workflow-draft-api-input-edits.js';
+export { WorkflowDraftApiInputEditPlanningError } from './draft/workflow-draft-api-input-edit-planning-error.js';
+export type * from './types/workflow-draft-api-input-edit.js';
+export { planWorkflowDraftApiBindingEdit } from './draft/plan-workflow-draft-api-binding-edit.js';
+export { WorkflowDraftApiBindingEditPlanningError } from './draft/workflow-draft-api-binding-edit-planning-error.js';
+export type * from './types/workflow-draft-api-binding-edit.js';
+export { planWorkflowDraftConnectionEdit } from './draft/plan-workflow-draft-connection-edit.js';
+export { WorkflowDraftConnectionEditPlanningError } from './draft/workflow-draft-connection-edit-planning-error.js';
+export type * from './types/workflow-draft-connection-edit.js';
+export { selectWorkflowDraftNativeParameterEditTargets } from './draft/select-workflow-draft-native-parameter-edit-targets.js';
+export { generateWorkflowDraftNativeParameterEdits } from './draft/generate-workflow-draft-native-parameter-edits.js';
+export { WorkflowDraftNativeParameterEditPlanningError } from './draft/workflow-draft-native-parameter-edit-planning-error.js';
+export type * from './types/workflow-draft-native-parameter-edit.js';
+export { planWorkflowDraftNativeReferenceRepair } from './draft/plan-workflow-draft-native-reference-repair.js';
+export { WorkflowDraftNativeReferenceRepairPlanningError } from './draft/workflow-draft-native-reference-repair-planning-error.js';
+export type * from './types/workflow-draft-native-reference-repair.js';
+export { generateWorkflowDraftNativeNodeAddition } from './draft/generate-workflow-draft-native-node-addition.js';
+export { planWorkflowDraftNativeDependencies } from './draft/plan-workflow-draft-native-dependencies.js';
+export { selectWorkflowDraftNativeNodeParameterOwnership } from './draft/select-workflow-draft-native-node-parameter-ownership.js';
+export { WorkflowDraftNativeNodeAdditionPlanningError } from './draft/workflow-draft-native-node-addition-planning-error.js';
+export type * from './types/workflow-draft-native-node-addition.js';
+export type * from './types/workflow-draft-api-call-planning.js';
+export { selectWorkflowDraftApiBindingInputs } from './draft/select-workflow-draft-api-binding-inputs.js';
+export { planWorkflowDraftApiCallBindings } from './draft/plan-workflow-draft-api-call-bindings.js';
+export { generateWorkflowDraftApiCallArguments } from './draft/generate-workflow-draft-api-call-arguments.js';
+export { WorkflowDraftApiCallPlanningError } from './draft/workflow-draft-api-call-planning-error.js';
+export type { ClarifyWorkflowRequirementsInput } from './types/workflow-clarification.js';
+export { generateApiArguments } from './arguments/generate-api-arguments.js';
+export { extractApiInputAnswers } from './arguments/extract-api-input-answers.js';
+export { analyzeApiInputAnswers } from './arguments/analyze-api-input-answers.js';
+export type * from './types/api-input-answers.js';
+export { selectApiRequestMediaType } from './arguments/select-api-request-media-type.js';
+export { analyzeApiRequestMediaType } from './arguments/analyze-api-request-media-type.js';
+export type * from './types/request-media-selection.js';
+export type * from './types/operation-selection.js';
+export type * from './types/argument-generation.js';
+export { planWorkflowGraph } from './workflow/plan-workflow-graph.js';
+export { WorkflowGraphPlanningError } from './workflow/workflow-graph-planning-error.js';
+export type * from './types/workflow-planning.js';
+export { planApiBindings } from './bindings/plan-api-bindings.js';
+export type * from './types/binding-planning.js';
+export { planReviewableWorkflowGraph } from './workflow/plan-reviewable-workflow-graph.js';
+export { ReviewableWorkflowGraphPlanningError } from './workflow/reviewable-workflow-graph-planning-error.js';
+export type * from './types/reviewable-workflow-planning.js';
+export { planNativeNodes } from './workflow/plan-native-nodes.js';
+export { selectNativeNodeInstances } from './workflow/select-native-node-instances.js';
+export { generateNativeNodeParameters } from './workflow/generate-native-node-parameters.js';
+export { NativeNodePlanningError } from './workflow/native-node-planning-error.js';
+export { planWorkflowConnections } from './workflow/plan-workflow-connections.js';
+export { orchestrateWorkflow } from './workflow/orchestrate-workflow.js';
+export type * from './types/native-node-planning.js';
+export type * from './types/workflow-orchestration.js';
+export type * from './types/workflow-draft-clarification.js';
+export { planWorkflowDraftClarificationScopes } from './draft/plan-workflow-draft-clarification-scopes.js';
+export { WorkflowDraftClarificationScopePlanningError } from './draft/workflow-draft-clarification-scope-planning-error.js';
+export type * from './types/workflow-review-suggestions.js';
+export { suggestWorkflowReviewFollowUps } from './review/suggest-workflow-review-follow-ups.js';
+export { WorkflowReviewSuggestionPlanningError } from './review/workflow-review-suggestion-planning-error.js';
+export { planNativeInstanceDependencies } from './workflow/plan-native-instance-dependencies.js';
+export type { PlanNativeInstanceDependenciesInput } from './types/native-node-planning.js';

package/dist/public-api.js

@@ -0,0 +1,46 @@
+export { selectApiOperations } from './selection/select-api-operations.js';
+export { analyzeApiSelection } from './selection/analyze-api-selection.js';
+export { clarifyWorkflowRequirements } from './requirements/clarify-workflow-requirements.js';
+export { analyzeWorkflowDraftEdit } from './draft/analyze-workflow-draft-edit.js';
+export { WorkflowDraftEditPlanningError } from './draft/workflow-draft-edit-planning-error.js';
+export { selectWorkflowDraftApiInputEditTargets } from './draft/select-workflow-draft-api-input-edit-targets.js';
+export { generateWorkflowDraftApiInputEdits } from './draft/generate-workflow-draft-api-input-edits.js';
+export { WorkflowDraftApiInputEditPlanningError } from './draft/workflow-draft-api-input-edit-planning-error.js';
+export { planWorkflowDraftApiBindingEdit } from './draft/plan-workflow-draft-api-binding-edit.js';
+export { WorkflowDraftApiBindingEditPlanningError } from './draft/workflow-draft-api-binding-edit-planning-error.js';
+export { planWorkflowDraftConnectionEdit } from './draft/plan-workflow-draft-connection-edit.js';
+export { WorkflowDraftConnectionEditPlanningError } from './draft/workflow-draft-connection-edit-planning-error.js';
+export { selectWorkflowDraftNativeParameterEditTargets } from './draft/select-workflow-draft-native-parameter-edit-targets.js';
+export { generateWorkflowDraftNativeParameterEdits } from './draft/generate-workflow-draft-native-parameter-edits.js';
+export { WorkflowDraftNativeParameterEditPlanningError } from './draft/workflow-draft-native-parameter-edit-planning-error.js';
+export { planWorkflowDraftNativeReferenceRepair } from './draft/plan-workflow-draft-native-reference-repair.js';
+export { WorkflowDraftNativeReferenceRepairPlanningError } from './draft/workflow-draft-native-reference-repair-planning-error.js';
+export { generateWorkflowDraftNativeNodeAddition } from './draft/generate-workflow-draft-native-node-addition.js';
+export { planWorkflowDraftNativeDependencies } from './draft/plan-workflow-draft-native-dependencies.js';
+export { selectWorkflowDraftNativeNodeParameterOwnership } from './draft/select-workflow-draft-native-node-parameter-ownership.js';
+export { WorkflowDraftNativeNodeAdditionPlanningError } from './draft/workflow-draft-native-node-addition-planning-error.js';
+export { selectWorkflowDraftApiBindingInputs } from './draft/select-workflow-draft-api-binding-inputs.js';
+export { planWorkflowDraftApiCallBindings } from './draft/plan-workflow-draft-api-call-bindings.js';
+export { generateWorkflowDraftApiCallArguments } from './draft/generate-workflow-draft-api-call-arguments.js';
+export { WorkflowDraftApiCallPlanningError } from './draft/workflow-draft-api-call-planning-error.js';
+export { generateApiArguments } from './arguments/generate-api-arguments.js';
+export { extractApiInputAnswers } from './arguments/extract-api-input-answers.js';
+export { analyzeApiInputAnswers } from './arguments/analyze-api-input-answers.js';
+export { selectApiRequestMediaType } from './arguments/select-api-request-media-type.js';
+export { analyzeApiRequestMediaType } from './arguments/analyze-api-request-media-type.js';
+export { planWorkflowGraph } from './workflow/plan-workflow-graph.js';
+export { WorkflowGraphPlanningError } from './workflow/workflow-graph-planning-error.js';
+export { planApiBindings } from './bindings/plan-api-bindings.js';
+export { planReviewableWorkflowGraph } from './workflow/plan-reviewable-workflow-graph.js';
+export { ReviewableWorkflowGraphPlanningError } from './workflow/reviewable-workflow-graph-planning-error.js';
+export { planNativeNodes } from './workflow/plan-native-nodes.js';
+export { selectNativeNodeInstances } from './workflow/select-native-node-instances.js';
+export { generateNativeNodeParameters } from './workflow/generate-native-node-parameters.js';
+export { NativeNodePlanningError } from './workflow/native-node-planning-error.js';
+export { planWorkflowConnections } from './workflow/plan-workflow-connections.js';
+export { orchestrateWorkflow } from './workflow/orchestrate-workflow.js';
+export { planWorkflowDraftClarificationScopes } from './draft/plan-workflow-draft-clarification-scopes.js';
+export { WorkflowDraftClarificationScopePlanningError } from './draft/workflow-draft-clarification-scope-planning-error.js';
+export { suggestWorkflowReviewFollowUps } from './review/suggest-workflow-review-follow-ups.js';
+export { WorkflowReviewSuggestionPlanningError } from './review/workflow-review-suggestion-planning-error.js';
+export { planNativeInstanceDependencies } from './workflow/plan-native-instance-dependencies.js';

package/dist/requirements/clarify-workflow-requirements.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowClarificationRound } from '@openapi-flow/core';
+import type { ClarifyWorkflowRequirementsInput } from '../types/workflow-clarification.js';
+/** One bounded proposal call. Question IDs, sources and reply handling belong to core. */
+export declare function clarifyWorkflowRequirements(input: ClarifyWorkflowRequirementsInput): Promise<WorkflowClarificationRound>;

package/dist/requirements/clarify-workflow-requirements.js

@@ -0,0 +1,53 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createWorkflowClarificationRound, describeWorkflowPlanningContext, resolveWorkflowClarificationOptions, } from '@openapi-flow/core';
+import { createWorkflowRequirementsSchema } from '../schemas/workflow-requirements-schema.js';
+import { serializeWorkflowRequirementsSchema } from '../schemas/serialize-workflow-requirements-schema.js';
+import { workflowRequirementsPrompt } from '../prompts/workflow-requirements-prompt.js';
+import { workflowUserActionEvidencePrompt } from '../prompts/workflow-user-action-evidence-prompt.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { resolveWorkflowRequirementsEvidence } from './resolve-workflow-requirements-evidence.js';
+/** One bounded proposal call. Question IDs, sources and reply handling belong to core. */
+export async function clarifyWorkflowRequirements(input) {
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('clarifyWorkflowRequirements.model must support structured output');
+    const context = describeWorkflowPlanningContext(input.context);
+    if (input.backgroundMessages !== undefined) {
+        if (!Array.isArray(input.backgroundMessages))
+            throw new Error('clarifyWorkflowRequirements.backgroundMessages must be an array');
+        if (input.backgroundMessages.length)
+            describeWorkflowPlanningContext({ messages: input.backgroundMessages });
+    }
+    const options = resolveWorkflowClarificationOptions(input.options);
+    const candidates = context.operations.map((operation, index) => ({
+        candidateId: `candidate-${index + 1}`,
+        operation,
+    }));
+    const schema = createWorkflowRequirementsSchema(input.limits, options, context, candidates);
+    const output = await input.model
+        .withStructuredOutput(serializeWorkflowRequirementsSchema(schema), {
+        name: 'clarify_workflow_requirements',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowRequirementsPrompt + '\n' + workflowUserActionEvidencePrompt),
+        new HumanMessage(JSON.stringify({
+            messages: context.messages,
+            ...(input.backgroundMessages === undefined
+                ? {}
+                : { backgroundMessages: input.backgroundMessages }),
+            entrypoint: context.entrypoint,
+            candidates,
+            capabilities: context.capabilities,
+            limits: input.limits,
+            options,
+        })),
+    ]);
+    const proposed = parseStructuredOutput(schema, output, 'model workflow requirements');
+    return createWorkflowClarificationRound({
+        context: input.context,
+        limits: input.limits,
+        options,
+        proposal: resolveWorkflowRequirementsEvidence(proposed, candidates),
+    });
+}

package/dist/requirements/resolve-workflow-requirements-evidence.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowRequirementsProposal } from '@openapi-flow/core';
+import type { WorkflowClarificationOasCandidate, WorkflowRequirementsModelOutput } from '../types/workflow-clarification.js';
+/** Candidate identity is code-owned, never copied from model-supplied OAS keys. */
+export declare function resolveWorkflowRequirementsEvidence(proposal: WorkflowRequirementsModelOutput, candidates: WorkflowClarificationOasCandidate[]): WorkflowRequirementsProposal;

package/dist/requirements/resolve-workflow-requirements-evidence.js

@@ -0,0 +1,58 @@
+/** Candidate identity is code-owned, never copied from model-supplied OAS keys. */
+export function resolveWorkflowRequirementsEvidence(proposal, candidates) {
+    function evidence(item) {
+        if (item.kind !== 'oas')
+            return structuredClone(item);
+        const candidate = candidates.find((candidate) => candidate.candidateId === item.candidateId);
+        if (!candidate)
+            throw new Error(`Unknown clarification OAS candidate ${item.candidateId}`);
+        return {
+            kind: 'oas',
+            operation: structuredClone(candidate.operation.key),
+            // This stage cites a complete supplied operation, not a model-built path.
+            pointer: '',
+        };
+    }
+    function explanation(value) {
+        return value === undefined
+            ? {}
+            : {
+                explanation: {
+                    reason: value.reason,
+                    evidence: value.evidence.map(evidence),
+                },
+            };
+    }
+    return {
+        statements: proposal.statements.map((statement) => ({
+            text: statement.text,
+            sources: structuredClone(statement.sources),
+            ...explanation(statement.explanation),
+        })),
+        categories: proposal.categories.map((category) => ({
+            title: category.title,
+            ...explanation(category.explanation),
+            questions: category.questions.map((question) => ({
+                message: question.message,
+                ...explanation(question.explanation),
+                answer: question.answer.kind === 'text'
+                    ? question.answer
+                    : {
+                        kind: question.answer.kind,
+                        choices: question.answer.choices.map((choice) => ({
+                            label: choice.label,
+                            ...explanation(choice.explanation),
+                        })),
+                    },
+            })),
+        })),
+        ...(proposal.suggestions === undefined
+            ? {}
+            : {
+                suggestions: proposal.suggestions.map((suggestion) => ({
+                    text: suggestion.text,
+                    ...explanation(suggestion.explanation),
+                })),
+            }),
+    };
+}

package/dist/review/suggest-workflow-review-follow-ups.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowReviewSuggestions } from '@openapi-flow/core';
+import type { SuggestWorkflowReviewFollowUpsInput } from '../types/workflow-review-suggestions.js';
+/** One fresh bounded call. An unselected suggestion never becomes intent or an executable edit. */
+export declare function suggestWorkflowReviewFollowUps(input: SuggestWorkflowReviewFollowUpsInput): Promise<WorkflowReviewSuggestions>;

package/dist/review/suggest-workflow-review-follow-ups.js

@@ -0,0 +1,87 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createWorkflowReviewSuggestions, describeWorkflowReviewSuggestions, } from '@openapi-flow/core';
+import { workflowReviewSuggestionsPrompt } from '../prompts/workflow-review-suggestions-prompt.js';
+import { createWorkflowReviewSuggestionsSchema } from '../schemas/workflow-review-suggestions-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { WorkflowReviewSuggestionPlanningError } from './workflow-review-suggestion-planning-error.js';
+/** One fresh bounded call. An unselected suggestion never becomes intent or an executable edit. */
+export async function suggestWorkflowReviewFollowUps(input) {
+    const description = describeWorkflowReviewSuggestions(input);
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('suggestWorkflowReviewFollowUps.model must support structured output');
+    const candidates = description.context.operations.map((operation, index) => ({
+        candidateId: `candidate-${index + 1}`,
+        operation,
+    }));
+    const schema = createWorkflowReviewSuggestionsSchema(description, candidates.map((candidate) => candidate.candidateId));
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-7', 'input'), {
+        name: 'suggest_workflow_review_follow_ups',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowReviewSuggestionsPrompt),
+        new HumanMessage(JSON.stringify({
+            boundary: {
+                kind: description.boundary.kind,
+                questions: description.boundary.questions,
+                data: description.boundary.data,
+            },
+            messages: description.context.messages,
+            candidates: candidates.map((candidate) => ({
+                candidateId: candidate.candidateId,
+                method: candidate.operation.method,
+                path: candidate.operation.path,
+                summary: candidate.operation.operation.summary,
+                description: candidate.operation.operation.description,
+                tags: candidate.operation.operation.tags,
+            })),
+            capabilities: description.context.capabilities,
+            entrypoint: description.context.entrypoint,
+            limits: description.limits,
+            options: description.options,
+        })),
+    ]);
+    let proposal;
+    try {
+        proposal = parseStructuredOutput(schema, output, 'workflow review follow-ups');
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new WorkflowReviewSuggestionPlanningError({ stage: 'proposal-schema', output }, cause);
+    }
+    try {
+        if (description.fingerprint !==
+            describeWorkflowReviewSuggestions(input).fingerprint)
+            throw new Error('Review sources changed during model invocation; no automatic rebase');
+        const resolve = (source) => {
+            if (source.kind !== 'oas')
+                return structuredClone(source);
+            const candidate = candidates.find((item) => item.candidateId === source.candidateId);
+            if (!candidate)
+                throw new Error(`Unknown review OAS candidate ${source.candidateId}`);
+            return {
+                kind: 'oas',
+                operation: structuredClone(candidate.operation.key),
+                pointer: '',
+            };
+        };
+        return createWorkflowReviewSuggestions({
+            ...input,
+            proposal: {
+                suggestions: proposal.suggestions.map((suggestion) => ({
+                    ...suggestion,
+                    sources: suggestion.sources.map(resolve),
+                })),
+            },
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new WorkflowReviewSuggestionPlanningError({ stage: 'source-validation', output }, cause);
+    }
+}

package/dist/review/workflow-review-suggestion-planning-error.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowReviewSuggestionPlanningFailure } from '../types/workflow-review-suggestions.js';
+export declare class WorkflowReviewSuggestionPlanningError extends Error {
+    readonly failure: WorkflowReviewSuggestionPlanningFailure;
+    constructor(failure: WorkflowReviewSuggestionPlanningFailure, cause: Error);
+}

package/dist/review/workflow-review-suggestion-planning-error.js

@@ -0,0 +1,8 @@
+export class WorkflowReviewSuggestionPlanningError extends Error {
+    failure;
+    constructor(failure, cause) {
+        super(`Workflow review suggestions failed at ${failure.stage}: ${cause.message}`, { cause });
+        this.name = 'WorkflowReviewSuggestionPlanningError';
+        this.failure = failure;
+    }
+}

package/dist/schemas/api-binding-plan-schema.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { ApiBindingMaterial, NativeOutputContract } from '@openapi-flow/core';
+import type { ApiBindingPlanOutput } from '../types/binding-planning.js';
+export declare const apiBindingPlanningOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const apiBindingCallReasonSchema: z.ZodString;
+export declare function createApiBindingPlanSchema(materials: ApiBindingMaterial[], nativeOutputs?: NativeOutputContract[], includeExplanations?: boolean): z.ZodType<ApiBindingPlanOutput>;

package/dist/schemas/api-binding-plan-schema.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export const apiBindingPlanningOptionsSchema = z.strictObject({
+    includeExplanations: z.boolean().optional(),
+});
+export const apiBindingCallReasonSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim().length > 0)
+    .describe("Brief user-facing reason in the scenario language for this call's selected data bindings or decision that no binding is requested. Acknowledge any declared binding gaps for this call. This is not a value-generation, status-expectation or control-flow decision. Code attaches the exact supplied scenario, roles, OAS and native source contracts. Do not generate evidence, quotes, schemas or private chain-of-thought.");
+export function createApiBindingPlanSchema(materials, nativeOutputs = [], includeExplanations = false) {
+    z.boolean().parse(includeExplanations);
+    if (!materials.length)
+        throw new Error('binding materials must not be empty');
+    const ids = materials.map((item) => item.callId);
+    const sourceIds = [...ids, ...nativeOutputs.map((item) => item.nodeId)];
+    if (new Set(sourceIds).size !== sourceIds.length ||
+        sourceIds.some((id) => !id.trim()))
+        throw new Error('binding sources require unique non-empty node IDs');
+    if (new Set(ids).size !== ids.length || ids.some((id) => !id.trim()))
+        throw new Error('binding materials require unique non-empty callIds');
+    return z.strictObject({
+        calls: z.array(z.strictObject({
+            ...(includeExplanations ? { reason: apiBindingCallReasonSchema } : {}),
+            callId: z
+                .enum(ids)
+                .describe('Exact API call identity. Include each call once, including calls without bindings.'),
+            bindings: z
+                .array(z.strictObject({
+                kind: z.literal('node-output'),
+                targetPointer: z
+                    .string()
+                    .min(1)
+                    .describe('RFC 6901 request pointer: /path/id, /query/name, /body or a nested body field. Never a JavaScript expression.'),
+                sourceNodeId: z
+                    .enum(sourceIds)
+                    .describe('Declared API or native node producing the actual value, not merely the previous array element.'),
+                sourcePointer: z
+                    .string()
+                    .describe('RFC 6901 pointer into an API response BODY or a declared native JSON output. Empty string means the entire value. Use exact schema-declared responsePointerCatalog paths where applicable, without transport-envelope prefixes. Dynamic paths require scenario and contract evidence; the catalog is not a whitelist or a runtime existence guarantee.'),
+            }))
+                .describe('Only scenario-requested response-to-request dependencies. Return [] when no dependency is requested. Independent literals, supplied or missing, are handled by the later argument-generation stage and are not binding gaps.'),
+        })),
+        gaps: z
+            .array(z.strictObject({
+            callId: z
+                .enum(ids)
+                .describe('Exact selected API whose explicitly requested data dependency cannot be represented. An independent literal input does not make this call blocked.'),
+            targetPointer: z
+                .string()
+                .min(1)
+                .describe('RFC 6901 pointer to the affected request input declared by this API OAS.'),
+            description: z
+                .string()
+                .min(1)
+                .describe('Explain the requested dependency and why its producer, source contract or required transformation prevents a binding. Never describe a successful no-binding decision or a missing independent literal here.'),
+        }))
+            .describe('Blocking failures of explicitly requested response-to-request dependencies only. Return [] if there are no such failures, including when all inputs are independent literals. Not informational notes, missing independent literals, missing API capabilities, control flow or response assertions. Those belong to other planning stages. Do not invent values or APIs.'),
+    });
+}

package/dist/schemas/api-input-answer-source-schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { ApiInputRequirement, ApiInputSourceCatalog } from '@openapi-flow/core';
+export declare const apiInputAnswerExplanationOptionsSchema: z.ZodObject<{
+    includeExplanations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Values and unanswered IDs are deliberately not model-owned output fields. */
+export declare function createApiInputAnswerSourceSchema(requirements: ApiInputRequirement[], catalog: ApiInputSourceCatalog, includeExplanations?: boolean): z.ZodObject<{
+    reason?: z.ZodString | undefined;
+    answers: z.ZodArray<z.ZodObject<{
+        reason?: z.ZodString | undefined;
+        requirementId: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        source: z.ZodUnion<z.ZodType<import("@openapi-flow/core").ApiInputJsonSourceSelection | import("@openapi-flow/core").ApiInputTextSourceSelection, unknown, z.core.$ZodTypeInternals<import("@openapi-flow/core").ApiInputJsonSourceSelection | import("@openapi-flow/core").ApiInputTextSourceSelection, unknown>>[]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

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

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+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

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+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');
+    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(),
+});