@openapi-flow/langchain 0.0.0-stage → 0.3.0

package/dist/types/workflow-draft-native-parameter-edit.js

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

package/dist/types/workflow-draft-native-reference-repair.d.ts

@@ -0,0 +1,9 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowDraftNativeReferenceRepairInput } from '@openapi-flow/core';
+export interface PlanWorkflowDraftNativeReferenceRepairInput extends WorkflowDraftNativeReferenceRepairInput {
+    model: BaseChatModel;
+}
+export interface WorkflowDraftNativeReferenceRepairPlanningFailure {
+    stage: 'proposal-schema' | 'proposal-validation';
+    output: unknown;
+}

package/dist/types/workflow-draft-native-reference-repair.js

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

package/dist/types/workflow-message-evidence-selection.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowMessageEvidence } from '@openapi-flow/core';
+/** Model input contains identities; the parsed result contains code-owned exact source text. */
+export type WorkflowMessageEvidenceSelection = Pick<WorkflowMessageEvidence, 'kind' | 'messageId'>;
+export type WorkflowMessageSelectionOutput<Output> = Output extends WorkflowMessageEvidence ? WorkflowMessageEvidenceSelection : Output extends Array<infer Item> ? WorkflowMessageSelectionOutput<Item>[] : Output extends object ? {
+    [Key in keyof Output]: WorkflowMessageSelectionOutput<Output[Key]>;
+} : Output;

package/dist/types/workflow-message-evidence-selection.js

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

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

@@ -0,0 +1,21 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { PlannedNativeNode, WorkflowConnectionPlanningInput, WorkflowConnectionDecision, WorkflowConnectionProposal, ExplainedWorkflowBlockedCall, ExplainedWorkflowConnection } from '@openapi-flow/core';
+import type { ReviewableWorkflowGraphOutput } from './reviewable-workflow-planning.js';
+export interface PlanWorkflowConnectionsInput extends WorkflowConnectionPlanningInput {
+    model: BaseChatModel;
+    includeExplanations?: boolean;
+}
+export interface OrchestrateWorkflowInput extends Omit<PlanWorkflowConnectionsInput, 'nativeNodes'> {
+    workflowId: string;
+    preparedNativeNodes?: PlannedNativeNode[];
+}
+export interface WorkflowConnectionModelDecision extends ReviewableWorkflowGraphOutput {
+    reason: string;
+    edges: ExplainedWorkflowConnection[];
+    blockedCalls?: ExplainedWorkflowBlockedCall[];
+}
+export type WorkflowConnectionPlanningOutput = ReviewableWorkflowGraphOutput | WorkflowConnectionModelDecision;
+export interface ResolvedWorkflowConnectionOutput {
+    proposal: WorkflowConnectionProposal;
+    decision?: WorkflowConnectionDecision;
+}

package/dist/types/workflow-orchestration.js

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

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

@@ -0,0 +1,35 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowApiMaterial, WorkflowCapability, WorkflowGraphProposal, PlannedNativeNode, ExplainedWorkflowConnection, WorkflowGraphPlanningProposal, WorkflowGraphPlanningAssessment } from '@openapi-flow/core';
+export interface PlanWorkflowGraphInput {
+    scenario: string;
+    model: BaseChatModel;
+    materials: WorkflowApiMaterial[];
+    capabilities: WorkflowCapability[];
+    preparedNativeNodes?: PlannedNativeNode[];
+    includeExplanations?: boolean;
+}
+export type { PreparedNativeNodeMaterial } from '@openapi-flow/core';
+export type WorkflowGraphOutput = Omit<WorkflowGraphProposal, 'nativeNodes'> & {
+    additionalNativeNodes?: PlannedNativeNode[];
+};
+export interface ExplainedGraphNativeNode extends PlannedNativeNode {
+    reason: string;
+}
+export interface ExplainedWorkflowGraphOutput extends WorkflowGraphOutput {
+    reason: string;
+    additionalNativeNodes?: ExplainedGraphNativeNode[];
+    edges: ExplainedWorkflowConnection[];
+}
+export type WorkflowGraphModelOutput = WorkflowGraphOutput | ExplainedWorkflowGraphOutput;
+export interface ResolvedWorkflowGraphOutput {
+    proposal: WorkflowGraphPlanningProposal;
+    assessment?: WorkflowGraphPlanningAssessment;
+}
+export type WorkflowGraphExplanationMode = 'none' | 'connections' | 'graph';
+export type WorkflowGraphPlanningFailure = {
+    stage: 'proposal-schema';
+    output: unknown;
+} | {
+    stage: 'graph-validation';
+    output: WorkflowGraphModelOutput;
+};

package/dist/types/workflow-planning.js

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

package/dist/types/workflow-review-suggestions.d.ts

@@ -0,0 +1,12 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { WorkflowReviewSuggestionsInput, WorkflowReviewSuggestionsProposal, WorkflowReviewQuestionEvidence } from '@openapi-flow/core';
+import type { ProposedWorkflowPlanningEvidence } from './workflow-clarification.js';
+export interface SuggestWorkflowReviewFollowUpsInput extends WorkflowReviewSuggestionsInput {
+    model: BaseChatModel;
+}
+export type ProposedWorkflowReviewSuggestionEvidence = ProposedWorkflowPlanningEvidence | WorkflowReviewQuestionEvidence;
+export type WorkflowReviewSuggestionsModelOutput = WorkflowReviewSuggestionsProposal<ProposedWorkflowReviewSuggestionEvidence>;
+export interface WorkflowReviewSuggestionPlanningFailure {
+    stage: 'proposal-schema' | 'source-validation';
+    output: unknown;
+}

package/dist/types/workflow-review-suggestions.js

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

package/dist/workflow/complete-reviewable-workflow-graph-proposal.d.ts

@@ -0,0 +1,4 @@
+import type { ReviewableWorkflowGraphProposal } from '@openapi-flow/core';
+import type { ReviewableWorkflowGraphOutput } from '../types/reviewable-workflow-planning.js';
+/** Complete only fields fixed by the supplied planning context, not model errors. */
+export declare function completeReviewableWorkflowGraphProposal(output: ReviewableWorkflowGraphOutput, capabilityCount: number, readyCallCount: number): ReviewableWorkflowGraphProposal;

package/dist/workflow/complete-reviewable-workflow-graph-proposal.js

@@ -0,0 +1,13 @@
+/** Complete only fields fixed by the supplied planning context, not model errors. */
+export function completeReviewableWorkflowGraphProposal(output, capabilityCount, readyCallCount) {
+    if (capabilityCount > 0 && output.additionalNativeNodes === undefined)
+        throw new Error('model reviewable workflow graph.additionalNativeNodes is required');
+    if (readyCallCount > 0 && output.blockedCalls === undefined)
+        throw new Error('model reviewable workflow graph.blockedCalls is required');
+    const { additionalNativeNodes, ...proposal } = output;
+    return {
+        ...proposal,
+        nativeNodes: capabilityCount === 0 ? [] : additionalNativeNodes,
+        blockedCalls: readyCallCount === 0 ? [] : output.blockedCalls,
+    };
+}

package/dist/workflow/generate-native-node-parameters.d.ts

@@ -0,0 +1,4 @@
+import type { NativeNodeParameterResult } from '@openapi-flow/core';
+import type { GenerateNativeNodeParametersInput } from '../types/native-node-planning.js';
+/** Zero or one value call for one selected instance; no hidden ownership or connection planning. */
+export declare function generateNativeNodeParameters(input: GenerateNativeNodeParametersInput): Promise<NativeNodeParameterResult>;

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

@@ -0,0 +1,87 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { createNativeNodeParametersSchema, describeNativeNodeConfiguration, resolveNativeNodeParameters, } from '@openapi-flow/core';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { nativeNodeParametersPrompt } from '../prompts/native-node-planning-prompt.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+/** Zero or one value call for one selected instance; no hidden ownership or connection planning. */
+export async function generateNativeNodeParameters(input) {
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('generateNativeNodeParameters.model must support structured output when supplied');
+    const description = describeNativeNodeConfiguration(input);
+    if (!description.instance.hasLiteralParameters)
+        return resolveNativeNodeParameters({
+            ...input,
+            fingerprint: description.fingerprint,
+            proposal: {
+                decision: {
+                    status: 'provided',
+                    parameters: {},
+                    ...(input.includeExplanations
+                        ? {
+                            reason: 'The validated ownership contract leaves no literal parameter choice.',
+                        }
+                        : {}),
+                },
+            },
+        });
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('generateNativeNodeParameters.model must support structured output for remaining values');
+    const schema = createNativeNodeParametersSchema(input);
+    const capability = description.context.capabilities.find((entry) => entry.name === description.instance.capability);
+    if (!capability)
+        throw new Error('Native parameter generation has no selected capability material');
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'generate_native_node_parameters',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeNodeParametersPrompt),
+        new HumanMessage(JSON.stringify({
+            scenario: description.context.scenario,
+            purpose: description.instance.purpose,
+            target: {
+                id: description.instance.id,
+                capability: {
+                    name: capability.name,
+                    description: capability.description,
+                },
+            },
+            parametersSchema: description.instance.literalParametersSchema,
+            runtimeParameters: description.instance.runtimeParameters,
+            apiMaterials: description.context.apiMaterials,
+            preparedNativeNodes: description.context.preparedNativeNodes,
+            configuredNodes: description.configuredNodes,
+            outputs: description.outputs,
+            ...(description.sourceDependencies === undefined
+                ? {}
+                : { sourceDependencies: description.sourceDependencies }),
+            ...(description.replies === undefined
+                ? {}
+                : { replies: description.replies }),
+        })),
+    ]);
+    try {
+        // Validate output separately so callers can distinguish a malformed reply from stale source material.
+        schema.parse(output);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'parameter-schema', output }, cause);
+    }
+    try {
+        return resolveNativeNodeParameters({
+            ...input,
+            fingerprint: description.fingerprint,
+            proposal: output,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'parameter-validation', output }, cause);
+    }
+}

package/dist/workflow/native-node-planning-error.d.ts

@@ -0,0 +1,5 @@
+import type { NativeNodePlanningFailure } from '../types/native-node-planning.js';
+export declare class NativeNodePlanningError extends Error {
+    readonly failure: NativeNodePlanningFailure;
+    constructor(failure: NativeNodePlanningFailure, cause: Error);
+}

package/dist/workflow/native-node-planning-error.js

@@ -0,0 +1,10 @@
+export class NativeNodePlanningError extends Error {
+    failure;
+    constructor(failure, cause) {
+        super(`Native node planning failed at ${failure.stage}: ${cause.message}`, {
+            cause,
+        });
+        this.name = 'NativeNodePlanningError';
+        this.failure = failure;
+    }
+}

package/dist/workflow/orchestrate-workflow.d.ts

@@ -0,0 +1,4 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { OrchestrateWorkflowInput } from '../types/workflow-orchestration.js';
+/** Optional material groups mean absence, never an implicit capability registry. */
+export declare function orchestrateWorkflow(input: OrchestrateWorkflowInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/orchestrate-workflow.js

@@ -0,0 +1,31 @@
+import { planNativeNodes } from './plan-native-nodes.js';
+import { planWorkflowConnections } from './plan-workflow-connections.js';
+import { assembleNativeNodeMaterials } from '@openapi-flow/core';
+import { prepareWorkflowConnectionMaterials } from '@openapi-flow/core';
+/** Optional material groups mean absence, never an implicit capability registry. */
+export async function orchestrateWorkflow(input) {
+    if (!input.workflowId?.trim())
+        throw new Error('orchestrateWorkflow.workflowId is required');
+    prepareWorkflowConnectionMaterials({
+        ...input,
+        nativeNodes: input.preparedNativeNodes,
+    });
+    const nativePlan = await planNativeNodes({
+        planId: `${input.workflowId}-native`,
+        scenario: input.scenario,
+        model: input.model,
+        capabilities: input.capabilities,
+        preparedNativeNodes: input.preparedNativeNodes,
+        apiMaterials: input.materials?.map((material) => ({
+            callId: material.status === 'ready'
+                ? material.arguments.callId
+                : material.callId,
+            operation: material.operation,
+        })),
+    });
+    return planWorkflowConnections({
+        ...input,
+        nativeNodes: assembleNativeNodeMaterials(input.preparedNativeNodes ?? [], nativePlan.nativeNodes),
+        gaps: [...(input.gaps ?? []), ...nativePlan.gaps],
+    });
+}

package/dist/workflow/plan-native-instance-dependencies.d.ts

@@ -0,0 +1,4 @@
+import type { NativeInstanceDependencyPlan } from '@openapi-flow/core';
+import type { PlanNativeInstanceDependenciesInput } from '../types/native-node-planning.js';
+/** Zero or one producer-choice call; no parameters, output contracts or runtime DAG edges. */
+export declare function planNativeInstanceDependencies(input: PlanNativeInstanceDependenciesInput): Promise<NativeInstanceDependencyPlan>;

package/dist/workflow/plan-native-instance-dependencies.js

@@ -0,0 +1,45 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { describeNativeInstanceDependencies, createNativeInstanceDependenciesSchema, resolveNativeInstanceDependencies, } from '@openapi-flow/core';
+import { nativeInstanceDependenciesPrompt } from '../prompts/native-instance-dependencies-prompt.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+/** Zero or one producer-choice call; no parameters, output contracts or runtime DAG edges. */
+export async function planNativeInstanceDependencies(input) {
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('planNativeInstanceDependencies.model must support structured output when supplied');
+    const context = describeNativeInstanceDependencies(input);
+    const explanations = input.includeExplanations;
+    if (Object.values(context.sourceCandidatesByNodeId).every((ids) => ids.length === 0))
+        return resolveNativeInstanceDependencies({
+            ...input,
+            proposal: {
+                sourcesByNodeId: Object.fromEntries(context.instances.map((node) => [node.id, { sourceNodeIds: [] }])),
+            },
+        });
+    if (!input.model || typeof input.model.withStructuredOutput !== 'function')
+        throw new Error('planNativeInstanceDependencies.model must support structured output for producer choices');
+    const schema = createNativeInstanceDependenciesSchema(input);
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'plan_native_instance_dependencies',
+        method: 'jsonSchema',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeInstanceDependenciesPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    try {
+        if (!isDeepStrictEqual(describeNativeInstanceDependencies(input), context) ||
+            explanations !== input.includeExplanations)
+            throw new Error('Native dependency source contracts changed during planning; no automatic rebase');
+        return resolveNativeInstanceDependencies({ ...input, proposal: output });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error))
+            throw cause;
+        throw new NativeNodePlanningError({ stage: 'dependency-plan', output }, cause);
+    }
+}

package/dist/workflow/plan-native-nodes.d.ts

@@ -0,0 +1,2 @@
+import type { NativeNodePlan, PlanNativeNodesInput } from '../types/native-node-planning.js';
+export declare function planNativeNodes(input: PlanNativeNodesInput): Promise<NativeNodePlan>;

package/dist/workflow/plan-native-nodes.js

@@ -0,0 +1,96 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { describeNativeNodePlanning, createNativeNodePlan, createNativeNodePlanningRecord, } from '@openapi-flow/core';
+import { createNativeNodePlanningContract } from '../schemas/native-node-planning-contract.js';
+import { nativeNodeExplanationOptionsSchema } from '../schemas/native-node-explanation-schema.js';
+import { nativeNodePlanningPrompt } from '../prompts/native-node-planning-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { resolveNativeNodePlanningOutput } from './resolve-native-node-planning-output.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { NativeNodePlanningError } from './native-node-planning-error.js';
+export async function planNativeNodes(input) {
+    if (!input.planId?.trim())
+        throw new Error('planNativeNodes.planId is required');
+    if (input.model !== undefined &&
+        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+        throw new Error('planNativeNodes.model must support structured output when supplied');
+    const options = nativeNodeExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, context, planningCapabilities, } = describeNativeNodePlanning(input);
+    // No registered choice means no native-selection model call, not an inferred registry.
+    if (!snapshot.capabilities.length) {
+        const plan = createNativeNodePlan({
+            ...snapshot,
+            proposal: { nativeNodes: [], gaps: [] },
+        });
+        return {
+            ...plan,
+            ...(options.includeExplanations === true
+                ? {
+                    nativePlanning: createNativeNodePlanningRecord({
+                        ...snapshot,
+                        plan,
+                    }),
+                }
+                : {}),
+        };
+    }
+    const model = input.model;
+    if (!model)
+        throw new Error('planNativeNodes.model is required when supplied capabilities need a planning decision');
+    assertSelectionInput(snapshot.scenario, model);
+    const contract = createNativeNodePlanningContract(planningCapabilities, snapshot.allowRuntimeParameters === true, options.includeExplanations === true);
+    if (!isDeepStrictEqual(contract.capabilities, context.capabilities))
+        throw new Error('native planning schema differs from its supplied capability material');
+    const { schema } = contract;
+    const output = await model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'plan_native_nodes',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(nativeNodePlanningPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    let parsed;
+    try {
+        parsed = parseStructuredOutput(schema, output, 'model native node plan');
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('native model schema must validate without defaults, coercion or transformation');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new NativeNodePlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    const { proposal, assessment } = resolveNativeNodePlanningOutput(parsed);
+    try {
+        if (!isDeepStrictEqual(describeNativeNodePlanning(snapshot).context, context))
+            throw new Error('native planning source contracts changed during the model invocation');
+        const plan = createNativeNodePlan({ ...snapshot, proposal });
+        return {
+            ...plan,
+            ...(options.includeExplanations === true
+                ? {
+                    nativePlanning: createNativeNodePlanningRecord({
+                        ...snapshot,
+                        plan,
+                        assessment,
+                    }),
+                }
+                : {}),
+        };
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new NativeNodePlanningError({
+            stage: 'node-validation',
+            output: proposal,
+            sourceOutput: parsed,
+        }, error);
+    }
+}

package/dist/workflow/plan-reviewable-workflow-graph.d.ts

@@ -0,0 +1,3 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanReviewableWorkflowGraphInput } from '../types/reviewable-workflow-planning.js';
+export declare function planReviewableWorkflowGraph(input: PlanReviewableWorkflowGraphInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/plan-reviewable-workflow-graph.js

@@ -0,0 +1,70 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowGraphPlanning, createWorkflowGraphPlanningResult, createWorkflowGraphPlanningRecord, } from '@openapi-flow/core';
+import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { workflowGraphExplanationOptionsSchema } from '../schemas/workflow-graph-explanation-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+import { resolveReviewableWorkflowGraphOutput } from './resolve-workflow-graph-output.js';
+import { reviewableWorkflowGraphPrompt } from '../prompts/reviewable-workflow-graph-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { ReviewableWorkflowGraphPlanningError } from './reviewable-workflow-graph-planning-error.js';
+export async function planReviewableWorkflowGraph(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const options = workflowGraphExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, context, sources, planningCapabilities, } = describeWorkflowGraphPlanning({ ...input, mode: 'reviewable' });
+    const readyIds = snapshot.materials.flatMap((material) => material.status === 'ready' ? [material.arguments.callId] : []);
+    const schema = createReviewableWorkflowGraphSchema(planningCapabilities, readyIds, options.includeExplanations === true ? 'graph' : 'none');
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'plan_reviewable_workflow_graph',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(reviewableWorkflowGraphPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    let resolved;
+    try {
+        const parsed = parseStructuredOutput(schema, output, 'model reviewable workflow graph');
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('native model schema must validate without defaults, coercion or transformation');
+        resolved = resolveReviewableWorkflowGraphOutput(parsed, snapshot.capabilities.length, readyIds.length);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        const current = describeWorkflowGraphPlanning(snapshot);
+        if (!isDeepStrictEqual(current.context, context) ||
+            !isDeepStrictEqual(current.sources, sources))
+            throw new Error('reviewable workflow graph source contracts changed during the model invocation');
+        const plan = createWorkflowGraphPlanningResult({
+            ...snapshot,
+            proposal: resolved.proposal,
+        });
+        if (!('blockedCalls' in plan))
+            throw new Error('reviewable graph result is missing blockedCalls');
+        if (options.includeExplanations === true) {
+            if (!resolved.assessment)
+                throw new Error('model reviewable workflow graph is missing its explanation assessment');
+            plan.graphPlanning = createWorkflowGraphPlanningRecord({
+                ...snapshot,
+                proposal: resolved.proposal,
+                plan,
+                assessment: resolved.assessment,
+            });
+        }
+        return plan;
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'graph-validation', output }, error);
+    }
+}

package/dist/workflow/plan-workflow-connections.d.ts

@@ -0,0 +1,3 @@
+import type { ReviewableWorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanWorkflowConnectionsInput } from '../types/workflow-orchestration.js';
+export declare function planWorkflowConnections(input: PlanWorkflowConnectionsInput): Promise<ReviewableWorkflowGraphPlan>;

package/dist/workflow/plan-workflow-connections.js

@@ -0,0 +1,67 @@
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { isDeepStrictEqual } from 'node:util';
+import { describeWorkflowConnectionPlanning, createWorkflowConnectionPlan, createWorkflowConnectionPlanningRecord, } from '@openapi-flow/core';
+import { createReviewableWorkflowGraphSchema } from '../schemas/reviewable-workflow-graph-schema.js';
+import { resolveWorkflowConnectionOutput } from './resolve-workflow-connection-output.js';
+import { workflowConnectionsPrompt } from '../prompts/workflow-connections-prompt.js';
+import { assertSelectionInput } from '../legacy/planning/select-operation.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { ReviewableWorkflowGraphPlanningError } from './reviewable-workflow-graph-planning-error.js';
+import { workflowConnectionExplanationOptionsSchema } from '../schemas/workflow-connection-explanation-schema.js';
+import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
+export async function planWorkflowConnections(input) {
+    assertSelectionInput(input.scenario, input.model);
+    const options = workflowConnectionExplanationOptionsSchema.parse({
+        includeExplanations: input.includeExplanations,
+    });
+    const { input: snapshot, context, sources, } = describeWorkflowConnectionPlanning(input);
+    const readyIds = context.readyCallIds;
+    const schema = createReviewableWorkflowGraphSchema([], readyIds, options.includeExplanations === true ? 'connections' : 'none');
+    const output = await input.model
+        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+        name: 'plan_workflow_connections',
+        method: 'functionCalling',
+        strict: true,
+    })
+        .invoke([
+        new SystemMessage(workflowConnectionsPrompt),
+        new HumanMessage(JSON.stringify(context)),
+    ]);
+    let resolved;
+    try {
+        const parsed = parseStructuredOutput(schema, output, 'model workflow connections');
+        if (!isDeepStrictEqual(parsed, output))
+            throw new Error('connection model schema must validate without defaults, coercion or transformation');
+        resolved = resolveWorkflowConnectionOutput(parsed, readyIds.length);
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'proposal-schema', output }, error);
+    }
+    try {
+        const current = describeWorkflowConnectionPlanning(snapshot);
+        if (!isDeepStrictEqual(current.context, context) ||
+            !isDeepStrictEqual(current.sources, sources))
+            throw new Error('connection planning source contracts changed during the model invocation');
+        const plan = createWorkflowConnectionPlan({
+            ...snapshot,
+            proposal: resolved.proposal,
+        });
+        if (options.includeExplanations === true) {
+            if (!resolved.decision)
+                throw new Error('model workflow connections are missing the explanation decision');
+            plan.connectionPlanning = createWorkflowConnectionPlanningRecord({
+                ...snapshot,
+                plan,
+                decision: resolved.decision,
+            });
+        }
+        return plan;
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new ReviewableWorkflowGraphPlanningError({ stage: 'graph-validation', output }, error);
+    }
+}

package/dist/workflow/plan-workflow-graph.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowGraphPlan } from '@openapi-flow/core';
+import type { PlanWorkflowGraphInput } from '../types/workflow-planning.js';
+export declare function planWorkflowGraph(input: PlanWorkflowGraphInput): Promise<WorkflowGraphPlan>;