@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/capabilities/tool-definition-validator.js

@@ -1,776 +1,2 @@
-import { isToolCatalogGroupId, TOOL_PAYLOAD_STAGE_LITERAL_OUTPUT_MAX_BYTES, } from "./tool-types.js";
-import { TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH, TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES, } from "./normal-invocation/contracts.js";
-import { projectNormalInvocationDefinition } from "./normal-invocation/definition-projection.js";
-import { parseToolNormalInvocationContract, parseToolNormalInvocationForDefinition, } from "./normal-invocation/validator.js";
-const ROUTING_CAPABILITIES = [
-    "filesystem_inspection",
-    "filesystem_mutation",
-    "semantic_lookup",
-    "semantic_mutation",
-    "web_lookup",
-];
-const DEVELOPMENT_ROLES = [
-    "inspect",
-    "establish",
-    "mutate",
-    "verify",
-    "auxiliary",
-];
-const EXECUTION_EFFECTS = [
-    "read_only",
-    "mutating",
-    "mixed",
-];
-const EVENT_PROJECTION_KINDS = [
-    "string",
-    "number",
-    "string_array",
-    "length",
-];
-const PAYLOAD_STAGE_CONDITION_VALUE_MAX_LENGTH = 256;
-function isObject(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function isRoutingCapability(value) {
-    return (typeof value === "string" &&
-        ROUTING_CAPABILITIES.includes(value));
-}
-function isDevelopmentRole(value) {
-    return (typeof value === "string" &&
-        DEVELOPMENT_ROLES.includes(value));
-}
-function parseToolCatalogGroups(toolName, value) {
-    if (value === undefined)
-        return ["other"];
-    if (!Array.isArray(value) ||
-        value.length === 0 ||
-        value.some((group) => !isToolCatalogGroupId(group)) ||
-        new Set(value).size !== value.length) {
-        throw new Error(`Invalid tool definition for ${toolName} (catalogGroups)`);
-    }
-    return [...value];
-}
-function isExecutionEffect(value) {
-    return (typeof value === "string" &&
-        EXECUTION_EFFECTS.includes(value));
-}
-function parseEventPresentation(toolName, raw) {
-    if (raw === undefined)
-        return undefined;
-    if (!isObject(raw) || !isObject(raw.metadata)) {
-        throw new Error(`Invalid tool definition for ${toolName} (eventPresentation)`);
-    }
-    const metadata = Object.fromEntries(Object.entries(raw.metadata).map(([key, rawProjection]) => {
-        if (!key.trim() || !isObject(rawProjection)) {
-            throw new Error(`Invalid tool definition for ${toolName} (eventPresentation.metadata.${key})`);
-        }
-        const param = rawProjection.param;
-        const kind = rawProjection.kind;
-        const fallback = rawProjection.default;
-        if (typeof param !== "string" ||
-            !param.trim() ||
-            !EVENT_PROJECTION_KINDS.includes(kind) ||
-            (fallback !== undefined &&
-                typeof fallback !== "string" &&
-                typeof fallback !== "number" &&
-                typeof fallback !== "boolean")) {
-            throw new Error(`Invalid tool definition for ${toolName} (eventPresentation.metadata.${key})`);
-        }
-        return [
-            key,
-            {
-                param: param.trim(),
-                kind: kind,
-                ...(fallback !== undefined ? { default: fallback } : {}),
-            },
-        ];
-    }));
-    const lifecycle = raw.lifecycle;
-    if (lifecycle !== undefined && !isObject(lifecycle)) {
-        throw new Error(`Invalid tool definition for ${toolName} (eventPresentation.lifecycle)`);
-    }
-    const parsedLifecycle = isObject(lifecycle)
-        ? Object.fromEntries(["started", "completed", "failed"].flatMap((phase) => {
-            const copy = lifecycle[phase];
-            if (copy === undefined)
-                return [];
-            if (!isObject(copy) ||
-                typeof copy.status !== "string" ||
-                copy.status.trim().length === 0 ||
-                typeof copy.message !== "string" ||
-                copy.message.trim().length === 0) {
-                throw new Error(`Invalid tool definition for ${toolName} (eventPresentation.lifecycle.${phase})`);
-            }
-            return [
-                [
-                    phase,
-                    { status: copy.status.trim(), message: copy.message.trim() },
-                ],
-            ];
-        }))
-        : undefined;
-    return {
-        metadata,
-        ...(parsedLifecycle && Object.keys(parsedLifecycle).length > 0
-            ? { lifecycle: parsedLifecycle }
-            : {}),
-    };
-}
-function parseParamsByCommand(toolName, raw) {
-    if (raw === undefined) {
-        return undefined;
-    }
-    if (!isObject(raw)) {
-        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand)`);
-    }
-    const discriminator = raw.discriminator;
-    const variants = raw.variants;
-    if (typeof discriminator !== "string" || discriminator.trim().length === 0) {
-        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.discriminator)`);
-    }
-    if (!isObject(variants)) {
-        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants)`);
-    }
-    const parsedVariants = {};
-    for (const [variantName, variantParams] of Object.entries(variants)) {
-        if (!isObject(variantParams)) {
-            throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants.${variantName})`);
-        }
-        const parsedVariant = {};
-        for (const [paramName, paramType] of Object.entries(variantParams)) {
-            if (typeof paramType !== "string") {
-                throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants.${variantName}.${paramName})`);
-            }
-            parsedVariant[paramName] = paramType;
-        }
-        parsedVariants[variantName] = parsedVariant;
-    }
-    return { discriminator, variants: parsedVariants };
-}
-function parseRuntimePathBindings(toolName, raw) {
-    if (raw === undefined)
-        return undefined;
-    if (!Array.isArray(raw) || raw.length === 0 || raw.length > 32) {
-        throw new Error(`Invalid tool definition for ${toolName} (runtimePathBindings)`);
-    }
-    const identities = new Set();
-    return raw.map((value, index) => {
-        if (!isObject(value) ||
-            (Object.keys(value).length !== 3 && Object.keys(value).length !== 4) ||
-            !Object.hasOwn(value, "operationId") ||
-            !Object.hasOwn(value, "param") ||
-            !Object.hasOwn(value, "base") ||
-            Object.keys(value).some((key) => !["operationId", "param", "base", "default"].includes(key)) ||
-            typeof value.operationId !== "string" ||
-            value.operationId.trim().length === 0 ||
-            typeof value.param !== "string" ||
-            value.param.trim().length === 0 ||
-            value.base !== "worker_working_directory" ||
-            (value.default !== undefined && value.default !== ".")) {
-            throw new Error(`Invalid tool definition for ${toolName} (runtimePathBindings.${index})`);
-        }
-        const operationId = value.operationId.trim();
-        const param = value.param.trim();
-        const identity = `${operationId}\u0000${param}`;
-        if (identities.has(identity)) {
-            throw new Error(`Invalid tool definition for ${toolName} (runtimePathBindings duplicate ${operationId}.${param})`);
-        }
-        identities.add(identity);
-        return Object.freeze({
-            operationId,
-            param,
-            base: "worker_working_directory",
-            ...(value.default === "." ? { default: "." } : {}),
-        });
-    });
-}
-function parsePayloadChannelSpec(toolName, params, raw) {
-    if (raw === undefined) {
-        return undefined;
-    }
-    if (!isObject(raw)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec)`);
-    }
-    const payloadParams = raw.params;
-    const outputParam = raw.outputParam;
-    const generationMode = raw.generationMode;
-    const targetParam = raw.targetParam;
-    const targetRole = raw.targetRole;
-    const contextScope = raw.contextScope;
-    const targetContext = raw.targetContext;
-    const responseFormat = raw.responseFormat;
-    const promptHint = raw.promptHint;
-    const stages = raw.stages;
-    const groundingWindow = raw.groundingWindow;
-    const requiresCurrentTargetObservation = raw.requiresCurrentTargetObservation;
-    if (!Array.isArray(payloadParams) ||
-        payloadParams.length === 0 ||
-        payloadParams.some((paramName) => typeof paramName !== "string" || paramName.trim().length === 0)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.params)`);
-    }
-    if (typeof outputParam !== "string" || outputParam.trim().length === 0) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.outputParam)`);
-    }
-    if (generationMode !== "raw_text") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.generationMode)`);
-    }
-    if (targetParam !== undefined &&
-        (typeof targetParam !== "string" || targetParam.trim().length === 0)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.targetParam)`);
-    }
-    if (targetRole !== undefined &&
-        targetRole !== "payload_body" &&
-        targetRole !== "operation_target") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.targetRole)`);
-    }
-    if (contextScope !== undefined &&
-        contextScope !== "standard" &&
-        contextScope !== "target_only" &&
-        contextScope !== "target_with_artifacts") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.contextScope)`);
-    }
-    if (targetContext !== undefined &&
-        targetContext !== "bounded" &&
-        targetContext !== "full" &&
-        targetContext !== "full_numbered") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.targetContext)`);
-    }
-    if (responseFormat !== undefined &&
-        responseFormat !== "json" &&
-        !isObject(responseFormat)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.responseFormat)`);
-    }
-    if (promptHint !== undefined && typeof promptHint !== "string") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.promptHint)`);
-    }
-    if (stages !== undefined && (!Array.isArray(stages) || stages.length === 0)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages)`);
-    }
-    if (groundingWindow !== undefined &&
-        (typeof groundingWindow !== "number" ||
-            !Number.isInteger(groundingWindow) ||
-            groundingWindow < 0)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.groundingWindow)`);
-    }
-    if (requiresCurrentTargetObservation !== undefined &&
-        (!isObject(requiresCurrentTargetObservation) ||
-            typeof requiresCurrentTargetObservation.targetParam !== "string" ||
-            requiresCurrentTargetObservation.targetParam.trim().length === 0 ||
-            (requiresCurrentTargetObservation.contentRequirement !== undefined &&
-                requiresCurrentTargetObservation.contentRequirement !== "any" &&
-                requiresCurrentTargetObservation.contentRequirement !== "full"))) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.requiresCurrentTargetObservation)`);
-    }
-    const requiredCurrentTargetParam = isObject(requiresCurrentTargetObservation) &&
-        typeof requiresCurrentTargetObservation.targetParam === "string"
-        ? requiresCurrentTargetObservation.targetParam
-        : undefined;
-    const payloadTargetParam = typeof targetParam === "string" ? targetParam.trim() : undefined;
-    const requiredCurrentTargetContent = isObject(requiresCurrentTargetObservation) &&
-        (requiresCurrentTargetObservation.contentRequirement === "any" ||
-            requiresCurrentTargetObservation.contentRequirement === "full")
-        ? requiresCurrentTargetObservation.contentRequirement
-        : undefined;
-    const parsedStages = Array.isArray(stages)
-        ? stages.map((stage, index) => {
-            if (!isObject(stage)) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index})`);
-            }
-            const stageOutputParam = stage.outputParam;
-            const stageContextScope = stage.contextScope;
-            const stageTargetContext = stage.targetContext;
-            const stageResponseFormat = stage.responseFormat;
-            const stageTargetLineBoundProperties = stage.targetLineBoundProperties;
-            const stagePromptHint = stage.promptHint;
-            const includeMaterializedParams = stage.includeMaterializedParams;
-            const stageMinBytes = stage.minBytes;
-            const stageMinBytesOverride = stage.minBytesOverride;
-            const stageLiteralOutput = stage.literalOutput;
-            if (typeof stageOutputParam !== "string" ||
-                stageOutputParam.trim().length === 0 ||
-                !payloadParams.includes(stageOutputParam) ||
-                params[stageOutputParam] !== "string") {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.outputParam)`);
-            }
-            if (stageContextScope !== undefined &&
-                stageContextScope !== "standard" &&
-                stageContextScope !== "target_only" &&
-                stageContextScope !== "target_with_artifacts") {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.contextScope)`);
-            }
-            if (stageTargetContext !== undefined &&
-                stageTargetContext !== "bounded" &&
-                stageTargetContext !== "full" &&
-                stageTargetContext !== "full_numbered") {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.targetContext)`);
-            }
-            if (stageResponseFormat !== undefined &&
-                stageResponseFormat !== "json" &&
-                !isObject(stageResponseFormat)) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.responseFormat)`);
-            }
-            if (stageTargetLineBoundProperties !== undefined &&
-                (!Array.isArray(stageTargetLineBoundProperties) ||
-                    stageTargetLineBoundProperties.length === 0 ||
-                    new Set(stageTargetLineBoundProperties).size !==
-                        stageTargetLineBoundProperties.length ||
-                    stageTargetLineBoundProperties.some((property) => typeof property !== "string" || property.trim().length === 0))) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.targetLineBoundProperties)`);
-            }
-            if (stagePromptHint !== undefined &&
-                typeof stagePromptHint !== "string") {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.promptHint)`);
-            }
-            if (includeMaterializedParams !== undefined &&
-                (!Array.isArray(includeMaterializedParams) ||
-                    includeMaterializedParams.some((paramName) => typeof paramName !== "string" ||
-                        !payloadParams.includes(paramName)))) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.includeMaterializedParams)`);
-            }
-            if (stageMinBytes !== undefined &&
-                (typeof stageMinBytes !== "number" ||
-                    !Number.isSafeInteger(stageMinBytes) ||
-                    stageMinBytes < 0 ||
-                    stageMinBytes > TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES)) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index}.minBytes)`);
-            }
-            if ((stageMinBytes !== undefined ||
-                stageMinBytesOverride !== undefined) &&
-                stageOutputParam.trim() !== outputParam) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index} byte minimum must belong to the final payload stage)`);
-            }
-            const priorStageOutputs = new Set(stages
-                .slice(0, index)
-                .filter(isObject)
-                .map((priorStage) => priorStage.outputParam)
-                .filter((paramName) => typeof paramName === "string"));
-            if (Array.isArray(includeMaterializedParams) &&
-                includeMaterializedParams.some((paramName) => !priorStageOutputs.has(paramName))) {
-                throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.stages.${index} references unavailable materialized params)`);
-            }
-            const parsedMinBytesOverride = stageMinBytesOverride === undefined
-                ? undefined
-                : parsePayloadStageMinBytesOverride({
-                    toolName,
-                    stageIndex: index,
-                    input: stageMinBytesOverride,
-                    baseMinBytes: stageMinBytes,
-                    includeMaterializedParams,
-                    stages,
-                    inheritedResponseFormat: responseFormat,
-                });
-            const parsedLiteralOutput = parsePayloadStageLiteralOutput({
-                toolName,
-                stageIndex: index,
-                input: stageLiteralOutput,
-                stageOutputParam: stageOutputParam.trim(),
-                finalOutputParam: outputParam,
-                stageResponseFormat,
-                inheritedResponseFormat: responseFormat,
-                stageTargetLineBoundProperties,
-                stageMinBytesOverride,
-                includeMaterializedParams,
-                stages,
-            });
-            return {
-                outputParam: stageOutputParam.trim(),
-                ...(stageContextScope === "standard" ||
-                    stageContextScope === "target_only" ||
-                    stageContextScope === "target_with_artifacts"
-                    ? { contextScope: stageContextScope }
-                    : {}),
-                ...(stageTargetContext === "bounded" ||
-                    stageTargetContext === "full" ||
-                    stageTargetContext === "full_numbered"
-                    ? { targetContext: stageTargetContext }
-                    : {}),
-                ...(stageResponseFormat === "json" || isObject(stageResponseFormat)
-                    ? { responseFormat: stageResponseFormat }
-                    : {}),
-                ...(Array.isArray(stageTargetLineBoundProperties)
-                    ? {
-                        targetLineBoundProperties: [...stageTargetLineBoundProperties],
-                    }
-                    : {}),
-                ...(typeof stagePromptHint === "string"
-                    ? { promptHint: stagePromptHint }
-                    : {}),
-                ...(Array.isArray(includeMaterializedParams)
-                    ? { includeMaterializedParams: [...includeMaterializedParams] }
-                    : {}),
-                ...(typeof stageMinBytes === "number"
-                    ? { minBytes: stageMinBytes }
-                    : {}),
-                ...(parsedMinBytesOverride
-                    ? { minBytesOverride: parsedMinBytesOverride }
-                    : {}),
-                ...(parsedLiteralOutput
-                    ? { literalOutput: parsedLiteralOutput }
-                    : {}),
-            };
-        })
-        : undefined;
-    const unknownParam = payloadParams.find((paramName) => !(paramName in params));
-    if (unknownParam) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec unknown param ${unknownParam})`);
-    }
-    if (!(outputParam in params)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec outputParam ${outputParam})`);
-    }
-    if (params[outputParam] !== "string") {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec outputParam ${outputParam} must be string)`);
-    }
-    if (payloadTargetParam !== undefined && !(payloadTargetParam in params)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec unknown targetParam ${payloadTargetParam})`);
-    }
-    if (payloadTargetParam !== undefined &&
-        payloadParams.includes(payloadTargetParam)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec targetParam ${payloadTargetParam} must be a visible control param)`);
-    }
-    if (targetContext !== undefined && payloadTargetParam === undefined) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec.targetContext requires targetParam)`);
-    }
-    if (parsedStages?.some((stage) => stage.targetContext !== undefined) &&
-        payloadTargetParam === undefined) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec stage targetContext requires targetParam)`);
-    }
-    if (parsedStages &&
-        parsedStages[parsedStages.length - 1]?.outputParam !== outputParam) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec final stage must materialize outputParam ${outputParam})`);
-    }
-    if (requiredCurrentTargetParam !== undefined &&
-        !(requiredCurrentTargetParam in params)) {
-        throw new Error(`Invalid tool definition for ${toolName} (payloadChannelSpec requiresCurrentTargetObservation unknown targetParam ${requiredCurrentTargetParam})`);
-    }
-    return {
-        params: [...payloadParams],
-        outputParam,
-        generationMode,
-        ...(payloadTargetParam ? { targetParam: payloadTargetParam } : {}),
-        ...(targetRole === "payload_body" || targetRole === "operation_target"
-            ? { targetRole }
-            : {}),
-        ...(contextScope === "standard" ||
-            contextScope === "target_only" ||
-            contextScope === "target_with_artifacts"
-            ? { contextScope }
-            : {}),
-        ...(targetContext === "bounded" ||
-            targetContext === "full" ||
-            targetContext === "full_numbered"
-            ? { targetContext }
-            : {}),
-        ...(responseFormat === "json" || isObject(responseFormat)
-            ? { responseFormat }
-            : {}),
-        ...(typeof promptHint === "string" ? { promptHint } : {}),
-        ...(parsedStages ? { stages: parsedStages } : {}),
-        ...(typeof groundingWindow === "number" ? { groundingWindow } : {}),
-        ...(requiredCurrentTargetParam
-            ? {
-                requiresCurrentTargetObservation: {
-                    targetParam: requiredCurrentTargetParam,
-                    ...(requiredCurrentTargetContent
-                        ? { contentRequirement: requiredCurrentTargetContent }
-                        : {}),
-                },
-            }
-            : {}),
-    };
-}
-function parsePayloadStageMinBytesOverride(params) {
-    const path = `payloadChannelSpec.stages.${params.stageIndex}.minBytesOverride`;
-    const input = params.input;
-    if (typeof params.baseMinBytes !== "number" ||
-        !isObject(input) ||
-        Object.keys(input).length !== 4 ||
-        Object.keys(input).some((key) => !["materializedParam", "property", "equals", "minBytes"].includes(key)) ||
-        typeof input.materializedParam !== "string" ||
-        input.materializedParam.length === 0 ||
-        input.materializedParam.length >
-            TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH ||
-        typeof input.property !== "string" ||
-        input.property.length === 0 ||
-        input.property.length > TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH ||
-        typeof input.equals !== "string" ||
-        input.equals.length === 0 ||
-        input.equals.length > PAYLOAD_STAGE_CONDITION_VALUE_MAX_LENGTH ||
-        typeof input.minBytes !== "number" ||
-        !Number.isSafeInteger(input.minBytes) ||
-        input.minBytes < 0 ||
-        input.minBytes > TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES ||
-        !Array.isArray(params.includeMaterializedParams) ||
-        !params.includeMaterializedParams.includes(input.materializedParam)) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path})`);
-    }
-    const materializedParam = input.materializedParam;
-    const property = input.property;
-    const equals = input.equals;
-    const overrideMinBytes = input.minBytes;
-    const sourceStages = [];
-    for (const stage of params.stages.slice(0, params.stageIndex)) {
-        if (isObject(stage) && stage.outputParam === materializedParam) {
-            sourceStages.push(stage);
-        }
-    }
-    if (sourceStages.length !== 1) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path} source)`);
-    }
-    const source = sourceStages[0];
-    const responseFormat = source.responseFormat ?? params.inheritedResponseFormat;
-    if (!validPayloadStageStringConditionSchema(responseFormat, property, equals)) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path} schema)`);
-    }
-    return {
-        materializedParam,
-        property,
-        equals,
-        minBytes: overrideMinBytes,
-    };
-}
-function parsePayloadStageLiteralOutput(params) {
-    if (params.input === undefined)
-        return undefined;
-    const path = `payloadChannelSpec.stages.${params.stageIndex}.literalOutput`;
-    const input = params.input;
-    if (!isObject(input) ||
-        Object.keys(input).length !== 2 ||
-        Object.keys(input).some((key) => !["when", "value"].includes(key)) ||
-        !isObject(input.when) ||
-        Object.keys(input.when).length !== 3 ||
-        Object.keys(input.when).some((key) => !["materializedParam", "property", "equals"].includes(key)) ||
-        typeof input.when.materializedParam !== "string" ||
-        input.when.materializedParam.trim().length === 0 ||
-        input.when.materializedParam.length >
-            TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH ||
-        typeof input.when.property !== "string" ||
-        input.when.property.trim().length === 0 ||
-        input.when.property.length > TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH ||
-        typeof input.when.equals !== "string" ||
-        input.when.equals.length === 0 ||
-        input.when.equals.length > PAYLOAD_STAGE_CONDITION_VALUE_MAX_LENGTH ||
-        typeof input.value !== "string" ||
-        Buffer.byteLength(input.value, "utf8") >
-            TOOL_PAYLOAD_STAGE_LITERAL_OUTPUT_MAX_BYTES ||
-        params.stageOutputParam !== params.finalOutputParam ||
-        params.stageResponseFormat !== undefined ||
-        params.inheritedResponseFormat !== undefined ||
-        params.stageTargetLineBoundProperties !== undefined ||
-        params.stageMinBytesOverride !== undefined ||
-        !Array.isArray(params.includeMaterializedParams) ||
-        !params.includeMaterializedParams.includes(input.when.materializedParam)) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path})`);
-    }
-    const sourceStages = [];
-    for (const stage of params.stages.slice(0, params.stageIndex)) {
-        if (isObject(stage) && stage.outputParam === input.when.materializedParam) {
-            sourceStages.push(stage);
-        }
-    }
-    if (sourceStages.length !== 1) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path} source)`);
-    }
-    const source = sourceStages[0];
-    const sourceResponseFormat = source.responseFormat ?? params.inheritedResponseFormat;
-    if (!validPayloadStageStringConditionSchema(sourceResponseFormat, input.when.property, input.when.equals)) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (${path} schema)`);
-    }
-    return {
-        when: {
-            materializedParam: input.when.materializedParam,
-            property: input.when.property,
-            equals: input.when.equals,
-        },
-        value: input.value,
-    };
-}
-function validPayloadStageStringConditionSchema(input, property, equals) {
-    if (!isObject(input) || input.type !== "object")
-        return false;
-    const properties = input.properties;
-    const required = input.required;
-    if (!isObject(properties) ||
-        !Array.isArray(required) ||
-        !required.includes(property)) {
-        return false;
-    }
-    const propertySchema = properties[property];
-    return (isObject(propertySchema) &&
-        propertySchema.type === "string" &&
-        Array.isArray(propertySchema.enum) &&
-        propertySchema.enum.length > 0 &&
-        propertySchema.enum.every((value) => typeof value === "string") &&
-        propertySchema.enum.includes(equals));
-}
-export function parseToolDefinition(raw) {
-    if (!isObject(raw)) {
-        throw new Error("Invalid tool definition entry (not an object)");
-    }
-    const name = raw.name;
-    const description = raw.description;
-    const routingCapability = raw.routingCapability;
-    const controlsRefinement = raw.controlsRefinement;
-    const catalogGroups = raw.catalogGroups;
-    const executionEffect = raw.executionEffect;
-    const developmentRoles = raw.developmentRoles;
-    const eventPresentation = raw.eventPresentation;
-    const params = raw.params;
-    if (typeof name !== "string" || name.trim().length === 0) {
-        throw new Error("Invalid tool definition entry (name)");
-    }
-    if (description !== undefined && typeof description !== "string") {
-        throw new Error(`Invalid tool definition for ${name} (description)`);
-    }
-    if (!isRoutingCapability(routingCapability)) {
-        throw new Error(`Invalid tool definition for ${name} (routingCapability)`);
-    }
-    if (controlsRefinement !== undefined &&
-        controlsRefinement !== "mechanical_when_complete") {
-        throw new Error(`Invalid tool definition for ${name} (controlsRefinement)`);
-    }
-    if (executionEffect !== undefined && !isExecutionEffect(executionEffect)) {
-        throw new Error(`Invalid tool definition for ${name} (executionEffect)`);
-    }
-    if (!isObject(params)) {
-        throw new Error(`Invalid tool definition for ${name} (params)`);
-    }
-    if (developmentRoles !== undefined &&
-        (!Array.isArray(developmentRoles) ||
-            developmentRoles.some((role) => !isDevelopmentRole(role)))) {
-        throw new Error(`Invalid tool definition for ${name} (developmentRoles)`);
-    }
-    for (const [paramName, paramType] of Object.entries(params)) {
-        if (typeof paramType !== "string") {
-            throw new Error(`Invalid tool definition for ${name} (param type for ${paramName})`);
-        }
-    }
-    const paramsByCommand = parseParamsByCommand(name, raw.paramsByCommand);
-    const runtimePathBindings = parseRuntimePathBindings(name, raw.runtimePathBindings);
-    const payloadChannelSpec = parsePayloadChannelSpec(name, params, raw.payloadChannelSpec);
-    const parsedEventPresentation = parseEventPresentation(name, eventPresentation);
-    return {
-        name,
-        ...(typeof description === "string" ? { description } : {}),
-        routingCapability,
-        ...(controlsRefinement === "mechanical_when_complete"
-            ? { controlsRefinement }
-            : {}),
-        catalogGroups: parseToolCatalogGroups(name, catalogGroups),
-        ...(executionEffect ? { executionEffect } : {}),
-        ...(Array.isArray(developmentRoles)
-            ? { developmentRoles: [...developmentRoles] }
-            : {}),
-        ...(parsedEventPresentation
-            ? { eventPresentation: parsedEventPresentation }
-            : {}),
-        params: params,
-        ...(paramsByCommand ? { paramsByCommand } : {}),
-        ...(payloadChannelSpec ? { payloadChannelSpec } : {}),
-        ...(runtimePathBindings ? { runtimePathBindings } : {}),
-    };
-}
-function parseToolAdapter(toolName, raw) {
-    if (raw === undefined) {
-        return undefined;
-    }
-    if (!isObject(raw)) {
-        throw new Error(`Invalid tool module for ${toolName} (adapter)`);
-    }
-    const normalizeCall = raw.normalizeCall;
-    const validateCall = raw.validateCall;
-    if (normalizeCall !== undefined && typeof normalizeCall !== "function") {
-        throw new Error(`Invalid tool module for ${toolName} (adapter.normalizeCall)`);
-    }
-    if (validateCall !== undefined && typeof validateCall !== "function") {
-        throw new Error(`Invalid tool module for ${toolName} (adapter.validateCall)`);
-    }
-    const adapter = {};
-    if (typeof normalizeCall === "function") {
-        adapter.normalizeCall = normalizeCall;
-    }
-    if (typeof validateCall === "function") {
-        adapter.validateCall = validateCall;
-    }
-    return adapter;
-}
-export function buildToolRegistry(modules) {
-    if (!Array.isArray(modules)) {
-        throw new Error("Tool registry modules must be an array");
-    }
-    const seenNames = new Set();
-    return modules.map((module, index) => {
-        if (!module || typeof module !== "object") {
-            throw new Error(`Invalid tool module entry at index ${index}`);
-        }
-        const rawDefinition = module.definition;
-        const toolName = readToolDefinitionName(rawDefinition);
-        const parsedNormalInvocation = parseToolNormalInvocationContract(toolName, module.normalInvocation);
-        if (!parsedNormalInvocation) {
-            throw new Error(`Invalid tool module for ${toolName} (normalInvocation is required)`);
-        }
-        const definition = parseToolDefinition(projectCanonicalDefinition({
-            toolName,
-            rawDefinition,
-            normalInvocation: parsedNormalInvocation,
-        }));
-        if (seenNames.has(definition.name)) {
-            throw new Error(`Duplicate tool definition: ${definition.name}`);
-        }
-        seenNames.add(definition.name);
-        if (typeof module.implementation !== "function") {
-            throw new Error(`Invalid tool module for ${definition.name} (implementation)`);
-        }
-        const adapter = parseToolAdapter(definition.name, module.adapter);
-        const normalInvocation = parseToolNormalInvocationForDefinition(definition, parsedNormalInvocation);
-        return {
-            definition,
-            implementation: module.implementation,
-            ...(adapter ? { adapter } : {}),
-            normalInvocation: normalInvocation,
-        };
-    });
-}
-export function validateToolModuleDeclarations(modules) {
-    const resolved = buildToolRegistry(modules);
-    return resolved.map((tool, index) => {
-        const source = modules[index];
-        const { params: _projectedParams, executionEffect: _projectedEffect, ...definition } = tool.definition;
-        void _projectedParams;
-        void _projectedEffect;
-        return {
-            definition,
-            implementation: tool.implementation,
-            ...(tool.adapter ? { adapter: tool.adapter } : {}),
-            normalInvocation: tool.normalInvocation,
-        };
-    });
-}
-function readToolDefinitionName(raw) {
-    if (!isObject(raw)) {
-        throw new Error("Invalid tool definition entry (not an object)");
-    }
-    if (typeof raw.name !== "string" || raw.name.trim().length === 0) {
-        throw new Error("Invalid tool definition entry (name)");
-    }
-    return raw.name;
-}
-function projectCanonicalDefinition(params) {
-    if (!isObject(params.rawDefinition)) {
-        throw new Error("Invalid tool definition entry (not an object)");
-    }
-    if (params.rawDefinition.params !== undefined) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (params must be omitted when normalInvocation is canonical)`);
-    }
-    if (params.rawDefinition.executionEffect !== undefined) {
-        throw new Error(`Invalid tool definition for ${params.toolName} (executionEffect must be omitted when normalInvocation is canonical)`);
-    }
-    const projection = projectNormalInvocationDefinition({
-        toolName: params.toolName,
-        contract: params.normalInvocation,
-    });
-    return {
-        ...params.rawDefinition,
-        params: { ...projection.params },
-        executionEffect: projection.executionEffect,
-    };
-}
+export { parseToolDefinition } from "./tool-definition-validator/definition-parser.js";
+export { buildToolRegistry, validateToolModuleDeclarations, } from "./tool-definition-validator/module-registry.js";