@dogpile/sdk 0.1.0

package/dist/runtime/validation.js

@@ -0,0 +1,656 @@
+import { DogpileError } from "../types.js";
+const protocolNames = ["coordinator", "sequential", "broadcast", "shared"];
+const budgetTiers = ["fast", "balanced", "quality"];
+/**
+ * Validate high-level caller options before any protocol execution starts.
+ */
+export function validateDogpileOptions(options) {
+    requireRecord(options, "options");
+    validateMissionIntent(options.intent);
+    if (options.protocol !== undefined) {
+        validateProtocolSelection(options.protocol, "protocol");
+    }
+    if (options.tier !== undefined) {
+        validateBudgetTier(options.tier, "tier");
+    }
+    validateModelProviderRegistration(options.model, "model");
+    validateOptionalAgents(options.agents, "agents");
+    validateOptionalRuntimeTools(options.tools, "tools");
+    validateOptionalTemperature(options.temperature, "temperature");
+    validateOptionalBudgetCaps(options.budget, "budget");
+    validateOptionalTerminationCondition(options.terminate, "terminate");
+    validateOptionalFunction(options.evaluate, "evaluate");
+    validateOptionalSeed(options.seed, "seed");
+    validateOptionalAbortSignal(options.signal, "signal");
+}
+export function validateMissionIntent(intent, path = "intent") {
+    validateNonEmptyString(intent, path, "intent is required.");
+}
+/**
+ * Validate low-level engine configuration before normalizing reusable controls.
+ */
+export function validateEngineOptions(options) {
+    requireRecord(options, "options");
+    validateProtocolSelection(options.protocol, "protocol");
+    validateBudgetTier(options.tier, "tier");
+    validateModelProviderRegistration(options.model, "model");
+    validateOptionalAgents(options.agents, "agents");
+    validateOptionalRuntimeTools(options.tools, "tools");
+    validateOptionalTemperature(options.temperature, "temperature");
+    validateOptionalBudgetCaps(options.budget, "budget");
+    validateOptionalTerminationCondition(options.terminate, "terminate");
+    validateOptionalFunction(options.evaluate, "evaluate");
+    validateOptionalSeed(options.seed, "seed");
+    validateOptionalAbortSignal(options.signal, "signal");
+}
+/**
+ * Validate Vercel AI adapter factory options at construction time.
+ */
+export function validateVercelAIProviderOptions(options) {
+    const record = requireRecord(options, "options");
+    if (record.model === undefined) {
+        invalidConfiguration({
+            path: "model",
+            rule: "required",
+            message: "model is required.",
+            expected: "a Vercel AI language model",
+            actual: record.model
+        });
+    }
+    if (typeof record.model === "string") {
+        validateNonEmptyString(record.model, "model", "model must not be empty.");
+    }
+    else {
+        validateVercelAILanguageModel(record.model, "model");
+    }
+    validateOptionalNonEmptyString(record.id, "id");
+    validateOptionalBoolean(record.streaming, "streaming");
+    validateOptionalFunction(record.generateText, "generateText");
+    validateOptionalFunction(record.streamText, "streamText");
+    validateOptionalFunction(record.costEstimator, "costEstimator");
+    validateOptionalPositiveInteger(record.maxOutputTokens, "maxOutputTokens");
+    validateOptionalNumberInRange(record.topP, "topP", 0, 1);
+    validateOptionalPositiveInteger(record.topK, "topK");
+    validateOptionalNumberInRange(record.presencePenalty, "presencePenalty", -2, 2);
+    validateOptionalNumberInRange(record.frequencyPenalty, "frequencyPenalty", -2, 2);
+    validateOptionalStringArray(record.stopSequences, "stopSequences");
+    validateOptionalInteger(record.seed, "seed");
+    validateOptionalNonNegativeInteger(record.maxRetries, "maxRetries");
+    validateOptionalAbortSignal(record.abortSignal, "abortSignal");
+    validateOptionalHeaders(record.headers, "headers");
+    validateOptionalProviderOptions(record.providerOptions, "providerOptions");
+    validateOptionalArray(record.activeTools, "activeTools");
+    validateOptionalFunction(record.runtimeToolIdForName, "runtimeToolIdForName");
+}
+function validateProtocolSelection(value, path) {
+    if (typeof value === "string") {
+        if (!isProtocolName(value)) {
+            invalidConfiguration({
+                path,
+                rule: "enum",
+                message: "protocol must be one of coordinator, sequential, broadcast, or shared.",
+                expected: protocolNames.join(" | "),
+                actual: value
+            });
+        }
+        return;
+    }
+    validateProtocolConfig(value, path);
+}
+function validateProtocolConfig(value, path) {
+    const record = requireRecord(value, path);
+    const kind = record.kind;
+    if (!isProtocolName(kind)) {
+        invalidConfiguration({
+            path: `${path}.kind`,
+            rule: "enum",
+            message: "protocol config kind must be one of coordinator, sequential, broadcast, or shared.",
+            expected: protocolNames.join(" | "),
+            actual: kind
+        });
+    }
+    switch (kind) {
+        case "coordinator":
+        case "sequential":
+        case "shared":
+            validateOptionalPositiveInteger(record.maxTurns, `${path}.maxTurns`);
+            if (kind === "shared") {
+                validateOptionalString(record.organizationalMemory, `${path}.organizationalMemory`);
+            }
+            return;
+        case "broadcast":
+            validateOptionalPositiveInteger(record.maxRounds, `${path}.maxRounds`);
+            return;
+    }
+}
+function validateBudgetTier(value, path) {
+    if (!isBudgetTier(value)) {
+        invalidConfiguration({
+            path,
+            rule: "enum",
+            message: "tier must be one of fast, balanced, or quality.",
+            expected: budgetTiers.join(" | "),
+            actual: value
+        });
+    }
+}
+/**
+ * Validate configured model provider definitions at registration boundaries.
+ */
+export function validateModelProviderRegistration(value, path = "model") {
+    const record = requireRecord(value, path);
+    validateNonEmptyString(record.id, `${path}.id`, "model.id is required.");
+    validateFunction(record.generate, `${path}.generate`);
+    validateOptionalFunction(record.stream, `${path}.stream`);
+}
+function validateVercelAILanguageModel(value, path) {
+    const record = requireRecord(value, path);
+    if (record.specificationVersion !== "v2" && record.specificationVersion !== "v3") {
+        invalidConfiguration({
+            path: `${path}.specificationVersion`,
+            rule: "model-provider",
+            message: "model.specificationVersion must be v2 or v3.",
+            expected: "v2 | v3",
+            actual: record.specificationVersion
+        });
+    }
+    validateNonEmptyString(record.provider, `${path}.provider`, "model.provider is required.");
+    validateNonEmptyString(record.modelId, `${path}.modelId`, "model.modelId is required.");
+    validateFunction(record.doGenerate, `${path}.doGenerate`);
+    validateFunction(record.doStream, `${path}.doStream`);
+}
+function validateOptionalAgents(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "agents must be an array when provided.",
+            expected: "readonly AgentSpec[]",
+            actual: value
+        });
+    }
+    if (value.length === 0) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "agents must contain at least one participant when provided.",
+            expected: "non-empty readonly AgentSpec[]",
+            actual: value
+        });
+    }
+    value.forEach((agent, index) => {
+        const agentPath = `${path}[${index}]`;
+        const record = requireRecord(agent, agentPath);
+        validateNonEmptyString(record.id, `${agentPath}.id`, "agent.id is required.");
+        validateNonEmptyString(record.role, `${agentPath}.role`, "agent.role is required.");
+        validateOptionalString(record.instructions, `${agentPath}.instructions`);
+    });
+}
+function validateOptionalRuntimeTools(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateRuntimeToolRegistrations(value, path);
+}
+/**
+ * Validate runtime tool definitions at registration boundaries.
+ */
+export function validateRuntimeToolRegistrations(value, path = "tools") {
+    if (!Array.isArray(value)) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "tools must be an array when provided.",
+            expected: "readonly RuntimeTool[]",
+            actual: value
+        });
+    }
+    value.forEach((tool, index) => validateRuntimeTool(tool, `${path}[${index}]`));
+}
+function validateRuntimeTool(value, path) {
+    const record = requireRecord(value, path);
+    const identity = requireRecord(record.identity, `${path}.identity`);
+    validateNonEmptyString(identity.id, `${path}.identity.id`, "tool identity id is required.");
+    validateNonEmptyString(identity.name, `${path}.identity.name`, "tool identity name is required.");
+    validateOptionalString(identity.namespace, `${path}.identity.namespace`);
+    validateOptionalString(identity.version, `${path}.identity.version`);
+    validateOptionalString(identity.description, `${path}.identity.description`);
+    const inputSchema = requireRecord(record.inputSchema, `${path}.inputSchema`);
+    if (inputSchema.kind !== "json-schema") {
+        invalidConfiguration({
+            path: `${path}.inputSchema.kind`,
+            rule: "runtime-tool",
+            message: "tool inputSchema.kind must be json-schema.",
+            expected: "json-schema",
+            actual: inputSchema.kind
+        });
+    }
+    validateJsonObject(inputSchema.schema, `${path}.inputSchema.schema`);
+    validateOptionalString(inputSchema.description, `${path}.inputSchema.description`);
+    validateOptionalArray(record.permissions, `${path}.permissions`);
+    validateOptionalFunction(record.validateInput, `${path}.validateInput`);
+    validateFunction(record.execute, `${path}.execute`);
+}
+function validateOptionalBudgetCaps(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateBudgetCaps(value, path);
+}
+function validateBudgetCaps(value, path) {
+    const record = requireRecord(value, path);
+    validateOptionalNonNegativeNumber(record.maxUsd, `${path}.maxUsd`);
+    validateOptionalNonNegativeInteger(record.maxTokens, `${path}.maxTokens`);
+    validateOptionalNonNegativeInteger(record.maxIterations, `${path}.maxIterations`);
+    validateOptionalNonNegativeInteger(record.timeoutMs, `${path}.timeoutMs`);
+    validateOptionalNumberInRange(record.qualityWeight, `${path}.qualityWeight`, 0, 1);
+}
+function validateOptionalTerminationCondition(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateTerminationCondition(value, path, new Set());
+}
+function validateTerminationCondition(value, path, stack) {
+    const record = requireRecord(value, path);
+    if (stack.has(record)) {
+        invalidConfiguration({
+            path,
+            rule: "termination-condition",
+            message: "termination conditions must not contain cycles.",
+            expected: "acyclic termination condition",
+            actual: value
+        });
+    }
+    stack.add(record);
+    try {
+        switch (record.kind) {
+            case "budget":
+                validateBudgetCaps(record, path);
+                return;
+            case "convergence":
+                validatePositiveInteger(record.stableTurns, `${path}.stableTurns`);
+                validateNumberInRange(record.minSimilarity, `${path}.minSimilarity`, 0, 1);
+                return;
+            case "judge":
+                validateJudgeRubric(record.rubric, `${path}.rubric`);
+                validateOptionalNumberInRange(record.minScore, `${path}.minScore`, 0, 1);
+                return;
+            case "firstOf":
+                validateFirstOfConditions(record.conditions, `${path}.conditions`, stack);
+                return;
+            default:
+                invalidConfiguration({
+                    path: `${path}.kind`,
+                    rule: "termination-condition",
+                    message: "termination condition kind must be budget, convergence, judge, or firstOf.",
+                    expected: "budget | convergence | judge | firstOf",
+                    actual: record.kind
+                });
+        }
+    }
+    finally {
+        stack.delete(record);
+    }
+}
+function validateFirstOfConditions(value, path, stack) {
+    if (!Array.isArray(value)) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "firstOf conditions must be a non-empty array.",
+            expected: "non-empty termination condition array",
+            actual: value
+        });
+    }
+    if (value.length === 0) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "firstOf conditions must contain at least one condition.",
+            expected: "non-empty termination condition array",
+            actual: value
+        });
+    }
+    value.forEach((condition, index) => {
+        validateTerminationCondition(condition, `${path}[${index}]`, stack);
+    });
+}
+function validateJudgeRubric(value, path) {
+    if (typeof value === "string") {
+        validateNonEmptyString(value, path, "judge rubric must not be empty.");
+        return;
+    }
+    validateJsonObject(value, path);
+}
+function validateOptionalTemperature(value, path) {
+    validateOptionalNumberInRange(value, path, 0, 2);
+}
+function validateOptionalSeed(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value === "string") {
+        return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return;
+    }
+    invalidConfiguration({
+        path,
+        rule: "finite-number",
+        message: "seed must be a string or finite number when provided.",
+        expected: "string or finite number",
+        actual: value
+    });
+}
+function validateOptionalHeaders(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    const record = requireRecord(value, path);
+    for (const [key, headerValue] of Object.entries(record)) {
+        if (headerValue !== undefined && typeof headerValue !== "string") {
+            invalidConfiguration({
+                path: `${path}.${key}`,
+                rule: "non-empty-string",
+                message: "headers values must be strings or undefined.",
+                expected: "string | undefined",
+                actual: headerValue
+            });
+        }
+    }
+}
+function validateOptionalProviderOptions(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    const record = requireRecord(value, path);
+    for (const [key, providerOptions] of Object.entries(record)) {
+        validateJsonObject(providerOptions, `${path}.${key}`);
+    }
+}
+function validateJsonObject(value, path) {
+    if (!isJsonValue(value, new Set()) || !isRecord(value)) {
+        invalidConfiguration({
+            path,
+            rule: "json-object",
+            message: "value must be a JSON-compatible object.",
+            expected: "JSON-compatible object",
+            actual: value
+        });
+    }
+}
+function isJsonValue(value, stack) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (Array.isArray(value)) {
+        if (stack.has(value)) {
+            return false;
+        }
+        stack.add(value);
+        const valid = value.every((child) => isJsonValue(child, stack));
+        stack.delete(value);
+        return valid;
+    }
+    if (isRecord(value)) {
+        if (stack.has(value)) {
+            return false;
+        }
+        stack.add(value);
+        const valid = Object.values(value).every((child) => isJsonValue(child, stack));
+        stack.delete(value);
+        return valid;
+    }
+    return false;
+}
+function validateOptionalString(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "string") {
+        invalidConfiguration({
+            path,
+            rule: "non-empty-string",
+            message: "value must be a string when provided.",
+            expected: "string",
+            actual: value
+        });
+    }
+}
+function validateOptionalNonEmptyString(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateNonEmptyString(value, path, `${path} must not be empty.`);
+}
+function validateNonEmptyString(value, path, message) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        invalidConfiguration({
+            path,
+            rule: "non-empty-string",
+            message,
+            expected: "non-empty string",
+            actual: value
+        });
+    }
+}
+function validateOptionalBoolean(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "boolean") {
+        invalidConfiguration({
+            path,
+            rule: "boolean",
+            message: "value must be a boolean when provided.",
+            expected: "boolean",
+            actual: value
+        });
+    }
+}
+function validateOptionalFunction(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateFunction(value, path);
+}
+function validateFunction(value, path) {
+    if (typeof value !== "function") {
+        invalidConfiguration({
+            path,
+            rule: "function",
+            message: "value must be a function.",
+            expected: "function",
+            actual: value
+        });
+    }
+}
+function validateOptionalArray(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "value must be an array when provided.",
+            expected: "array",
+            actual: value
+        });
+    }
+}
+function validateOptionalStringArray(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        invalidConfiguration({
+            path,
+            rule: "array",
+            message: "value must be an array of strings when provided.",
+            expected: "string[]",
+            actual: value
+        });
+    }
+    value.forEach((item, index) => validateNonEmptyString(item, `${path}[${index}]`, "array item must be a string."));
+}
+function validateOptionalAbortSignal(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isAbortSignalLike(value)) {
+        invalidConfiguration({
+            path,
+            rule: "abort-signal",
+            message: "value must be an AbortSignal when provided.",
+            expected: "AbortSignal",
+            actual: value
+        });
+    }
+}
+function isAbortSignalLike(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.aborted === "boolean" &&
+        typeof value.addEventListener === "function" &&
+        typeof value.removeEventListener === "function");
+}
+function validateOptionalInteger(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validateInteger(value, path);
+}
+function validateInteger(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+        invalidConfiguration({
+            path,
+            rule: "finite-number",
+            message: "value must be a finite integer.",
+            expected: "finite integer",
+            actual: value
+        });
+    }
+}
+function validateOptionalPositiveInteger(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    validatePositiveInteger(value, path);
+}
+function validatePositiveInteger(value, path) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        invalidConfiguration({
+            path,
+            rule: "positive-integer",
+            message: "value must be a positive integer.",
+            expected: "integer >= 1",
+            actual: value
+        });
+    }
+}
+function validateOptionalNonNegativeInteger(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        invalidConfiguration({
+            path,
+            rule: "non-negative-integer",
+            message: "value must be a non-negative integer.",
+            expected: "integer >= 0",
+            actual: value
+        });
+    }
+}
+function validateOptionalNonNegativeNumber(value, path) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        invalidConfiguration({
+            path,
+            rule: "non-negative-number",
+            message: "value must be a non-negative finite number.",
+            expected: "finite number >= 0",
+            actual: value
+        });
+    }
+}
+function validateOptionalNumberInRange(value, path, min, max) {
+    if (value === undefined) {
+        return;
+    }
+    validateNumberInRange(value, path, min, max);
+}
+function validateNumberInRange(value, path, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+        invalidConfiguration({
+            path,
+            rule: "range",
+            message: `value must be a finite number in the inclusive range ${min}..${max}.`,
+            expected: `finite number in ${min}..${max}`,
+            actual: value
+        });
+    }
+}
+function requireRecord(value, path) {
+    if (!isRecord(value)) {
+        invalidConfiguration({
+            path,
+            rule: "object",
+            message: "value must be an object.",
+            expected: "object",
+            actual: value
+        });
+    }
+    return value;
+}
+function invalidConfiguration(options) {
+    throw new DogpileError({
+        code: "invalid-configuration",
+        message: `Invalid Dogpile configuration at ${options.path}: ${options.message}`,
+        retryable: false,
+        detail: {
+            kind: "configuration-validation",
+            path: options.path,
+            rule: options.rule,
+            expected: options.expected,
+            received: describeValue(options.actual)
+        }
+    });
+}
+function isProtocolName(value) {
+    return typeof value === "string" && protocolNames.includes(value);
+}
+function isBudgetTier(value) {
+    return typeof value === "string" && budgetTiers.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeValue(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "undefined";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        return String(value);
+    }
+    return typeof value;
+}
+//# sourceMappingURL=validation.js.map