@kilnai/core 0.1.0

package/dist/engine/loader/app-loader.js

@@ -0,0 +1,947 @@
+// Engine loader: AppLoader -- parses App YAML into typed composites
+// Validates dependency graph: team refs in router must exist in teams
+import { parse } from "yaml";
+import { KilnError } from "../errors.js";
+import { validateApp } from "../composites/app.js";
+import { VALID_MODALITIES } from "../domain/modality.js";
+import { validateVoiceConfig } from "../domain/speech-config.js";
+import { validateKnowledgeConfig } from "../domain/knowledge-config.js";
+import { validateEvalConfig } from "../domain/eval-config.js";
+import { validateMcpConfig } from "../domain/mcp-config.js";
+import { validateToolSelectionConfig } from "../domain/tool-selection-config.js";
+import { validateSafetyConfig } from "../domain/safety-config.js";
+/** Error class for YAML loader failures, aggregating all validation errors */
+export class AppLoaderError extends KilnError {
+    errors;
+    constructor(errors) {
+        const msg = errors.map((e) => `  ${e.field}: ${e.message}`).join("\n");
+        super("APP_YAML_INVALID", `Invalid app YAML:\n${msg}`, {
+            context: { errors },
+            retryable: false,
+        });
+        this.name = "AppLoaderError";
+        this.errors = errors;
+    }
+}
+// ---------------------------------------------------------------------------
+// Mapping helpers
+// ---------------------------------------------------------------------------
+const VALID_TIERS = ["reasoning", "coding", "fast"];
+function mapAgent(identifier, raw, path) {
+    const errors = [];
+    // name: persona name from YAML (required) -- falls back to identifier for safety
+    const name = typeof raw.name === "string" && raw.name.trim() !== ""
+        ? raw.name.trim()
+        : identifier;
+    if (!raw.name || typeof raw.name !== "string" || raw.name.trim() === "") {
+        errors.push({ field: `${path}.name`, message: "must be a non-empty string (persona name)" });
+    }
+    // role: expertise / function (required)
+    const role = typeof raw.role === "string" ? raw.role.trim() : "";
+    if (!raw.role || typeof raw.role !== "string" || raw.role.trim() === "") {
+        errors.push({ field: `${path}.role`, message: "must be a non-empty string (expertise/function)" });
+    }
+    // goal: what agent is trying to achieve (required)
+    const goal = typeof raw.goal === "string" ? raw.goal.trim() : "";
+    if (!raw.goal || typeof raw.goal !== "string" || raw.goal.trim() === "") {
+        errors.push({ field: `${path}.goal`, message: "must be a non-empty string (what agent achieves)" });
+    }
+    // tier: model class (required)
+    const tier = raw.tier;
+    if (!tier || !VALID_TIERS.includes(tier)) {
+        errors.push({ field: `${path}.tier`, message: `must be one of: ${VALID_TIERS.join(", ")}` });
+    }
+    // tools: capability references (can be [])
+    const tools = [];
+    if (raw.tools !== undefined) {
+        if (!Array.isArray(raw.tools)) {
+            errors.push({ field: `${path}.tools`, message: "must be an array" });
+        }
+        else {
+            for (const t of raw.tools) {
+                if (typeof t !== "string") {
+                    errors.push({ field: `${path}.tools`, message: "all entries must be strings" });
+                    break;
+                }
+                tools.push(t);
+            }
+        }
+    }
+    // modalities: optional content type declarations
+    let modalities;
+    if (raw.modalities !== undefined) {
+        if (!Array.isArray(raw.modalities)) {
+            errors.push({ field: `${path}.modalities`, message: "must be an array" });
+        }
+        else {
+            modalities = [];
+            for (const m of raw.modalities) {
+                if (typeof m !== "string") {
+                    errors.push({ field: `${path}.modalities`, message: "all entries must be strings" });
+                    break;
+                }
+                if (!VALID_MODALITIES.includes(m)) {
+                    errors.push({ field: `${path}.modalities`, message: `unknown modality "${m}", must be one of: ${VALID_MODALITIES.join(", ")}` });
+                }
+                else {
+                    modalities.push(m);
+                }
+            }
+        }
+    }
+    const agent = {
+        name,
+        role,
+        goal,
+        tier: tier ?? "coding",
+        tools,
+        ...(typeof raw.backstory === "string" ? { backstory: raw.backstory.trim() } : {}),
+        ...(typeof raw.instructions === "string" ? { instructions: raw.instructions.trim() } : {}),
+        ...(typeof raw.structured === "boolean" ? { structured: raw.structured } : {}),
+        ...(typeof raw.count === "number" ? { count: raw.count } : {}),
+        ...(typeof raw.sandbox === "boolean" ? { sandbox: raw.sandbox } : {}),
+        ...(modalities && modalities.length > 0 ? { modalities } : {}),
+    };
+    return { agent, errors };
+}
+function mapWorkflow(raw, path) {
+    const errors = [];
+    const phases = [];
+    if (!raw.phases || !Array.isArray(raw.phases)) {
+        errors.push({ field: `${path}.phases`, message: "must be a non-empty array" });
+    }
+    else {
+        for (const p of raw.phases) {
+            if (typeof p !== "string") {
+                errors.push({ field: `${path}.phases`, message: "all entries must be strings" });
+                break;
+            }
+            phases.push(p);
+        }
+    }
+    const gates = {};
+    if (raw.gates !== undefined) {
+        if (typeof raw.gates !== "object" || raw.gates === null || Array.isArray(raw.gates)) {
+            errors.push({ field: `${path}.gates`, message: "must be an object" });
+        }
+        else {
+            for (const [phaseName, gateRaw] of Object.entries(raw.gates)) {
+                const requires = [];
+                if (Array.isArray(gateRaw?.requires)) {
+                    for (const r of gateRaw.requires) {
+                        if (typeof r === "string")
+                            requires.push(r);
+                    }
+                }
+                gates[phaseName] = { requires };
+            }
+        }
+    }
+    const workflow = {
+        phases,
+        gates,
+        ...(typeof raw.maxIterations === "number" ? { maxIterations: raw.maxIterations } : {}),
+    };
+    return { workflow, errors };
+}
+function mapCapability(raw, path) {
+    const errors = [];
+    if (!raw.name || typeof raw.name !== "string") {
+        errors.push({ field: `${path}.name`, message: "must be a non-empty string" });
+    }
+    if (!raw.description || typeof raw.description !== "string") {
+        errors.push({ field: `${path}.description`, message: "must be a non-empty string" });
+    }
+    const tags = [];
+    if (raw.tags !== undefined) {
+        if (!Array.isArray(raw.tags)) {
+            errors.push({ field: `${path}.tags`, message: "must be an array" });
+        }
+        else {
+            for (const t of raw.tags) {
+                if (typeof t === "string")
+                    tags.push(t);
+            }
+        }
+    }
+    // Validate guardrailRetries
+    if (raw.guardrailRetries !== undefined) {
+        if (typeof raw.guardrailRetries !== "number" || !Number.isInteger(raw.guardrailRetries) || raw.guardrailRetries < 1) {
+            errors.push({ field: `${path}.guardrailRetries`, message: "must be a positive integer" });
+        }
+    }
+    // Validate outputSchema
+    if (raw.outputSchema !== undefined) {
+        if (typeof raw.outputSchema !== "object" || raw.outputSchema === null || Array.isArray(raw.outputSchema)) {
+            errors.push({ field: `${path}.outputSchema`, message: "must be a valid object" });
+        }
+    }
+    const capability = {
+        name: typeof raw.name === "string" ? raw.name : "",
+        description: typeof raw.description === "string" ? raw.description : "",
+        schema: typeof raw.schema === "object" && raw.schema !== null && !Array.isArray(raw.schema)
+            ? raw.schema
+            : {},
+        tags,
+        ...(raw.annotations ? { annotations: raw.annotations } : {}),
+        ...(typeof raw.type === "string" ? { type: raw.type } : {}),
+        ...(typeof raw.targetApp === "string" ? { targetApp: raw.targetApp } : {}),
+        ...(typeof raw.task === "string" ? { task: raw.task } : {}),
+        ...(typeof raw.timeout === "number" && raw.timeout > 0 ? { timeout: raw.timeout } : {}),
+        ...(typeof raw.guardrail === "string" ? { guardrail: raw.guardrail } : {}),
+        ...(typeof raw.guardrailRetries === "number" && Number.isInteger(raw.guardrailRetries) && raw.guardrailRetries >= 1
+            ? { guardrailRetries: raw.guardrailRetries }
+            : {}),
+        ...(typeof raw.outputSchema === "object" && raw.outputSchema !== null && !Array.isArray(raw.outputSchema)
+            ? { outputSchema: raw.outputSchema }
+            : {}),
+    };
+    if (raw.type === "delegation") {
+        if (typeof raw.targetApp !== "string" || raw.targetApp === "") {
+            errors.push({ field: `${path}.targetApp`, message: "required when type is 'delegation'" });
+        }
+        if (typeof raw.task !== "string" || raw.task === "") {
+            errors.push({ field: `${path}.task`, message: "required when type is 'delegation'" });
+        }
+    }
+    if (raw.type === "a2a") {
+        if (typeof raw.targetApp !== "string" || raw.targetApp === "") {
+            errors.push({ field: `${path}.targetApp`, message: "required when type is 'a2a' (must be agent URL)" });
+        }
+    }
+    return { capability, errors };
+}
+function mapQualityGate(raw, path) {
+    const errors = [];
+    if (!raw.name || typeof raw.name !== "string") {
+        errors.push({ field: `${path}.name`, message: "must be a non-empty string" });
+    }
+    if (!raw.command || typeof raw.command !== "string") {
+        errors.push({ field: `${path}.command`, message: "must be a non-empty string" });
+    }
+    if (!raw.description || typeof raw.description !== "string") {
+        errors.push({ field: `${path}.description`, message: "must be a non-empty string" });
+    }
+    const gate = {
+        name: typeof raw.name === "string" ? raw.name : "",
+        command: typeof raw.command === "string" ? raw.command : "",
+        description: typeof raw.description === "string" ? raw.description : "",
+        required: typeof raw.required === "boolean" ? raw.required : true,
+    };
+    return { gate, errors };
+}
+function mapTeam(name, raw, path) {
+    const errors = [];
+    const agents = {};
+    // Agents
+    if (!raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+        errors.push({ field: `${path}.agents`, message: "must be an object" });
+    }
+    else {
+        for (const [agentName, agentRaw] of Object.entries(raw.agents)) {
+            const { agent, errors: agentErrors } = mapAgent(agentName, agentRaw ?? {}, `${path}.agents.${agentName}`);
+            agents[agentName] = agent;
+            errors.push(...agentErrors);
+        }
+    }
+    // Workflow
+    let workflow = { phases: [], gates: {} };
+    if (!raw.workflow || typeof raw.workflow !== "object" || Array.isArray(raw.workflow)) {
+        errors.push({ field: `${path}.workflow`, message: "must be an object" });
+    }
+    else {
+        const { workflow: wf, errors: wfErrors } = mapWorkflow(raw.workflow, `${path}.workflow`);
+        workflow = wf;
+        errors.push(...wfErrors);
+    }
+    // Capabilities
+    const capabilities = [];
+    if (raw.capabilities !== undefined) {
+        if (!Array.isArray(raw.capabilities)) {
+            errors.push({ field: `${path}.capabilities`, message: "must be an array" });
+        }
+        else {
+            for (let i = 0; i < raw.capabilities.length; i++) {
+                const { capability, errors: capErrors } = mapCapability(raw.capabilities[i], `${path}.capabilities[${i}]`);
+                capabilities.push(capability);
+                errors.push(...capErrors);
+            }
+        }
+    }
+    // Quality gates -- support both `qualityGates` and `quality` keys
+    const qualityGates = [];
+    const rawGates = raw.qualityGates ?? raw.quality;
+    if (rawGates !== undefined) {
+        if (!Array.isArray(rawGates)) {
+            errors.push({ field: `${path}.qualityGates`, message: "must be an array" });
+        }
+        else {
+            for (let i = 0; i < rawGates.length; i++) {
+                const { gate, errors: gateErrors } = mapQualityGate(rawGates[i], `${path}.qualityGates[${i}]`);
+                qualityGates.push(gate);
+                errors.push(...gateErrors);
+            }
+        }
+    }
+    // Mode
+    const validModes = ["sequential", "supervisor", "swarm"];
+    let mode;
+    if (raw.mode !== undefined) {
+        if (typeof raw.mode !== "string" || !validModes.includes(raw.mode)) {
+            errors.push({ field: `${path}.mode`, message: `must be one of: ${validModes.join(", ")}` });
+        }
+        else {
+            mode = raw.mode;
+        }
+    }
+    // Manager
+    let manager;
+    if (raw.manager !== undefined) {
+        if (typeof raw.manager !== "string" || raw.manager === "") {
+            errors.push({ field: `${path}.manager`, message: "must be a non-empty string" });
+        }
+        else {
+            manager = raw.manager;
+        }
+    }
+    const team = {
+        name,
+        agents,
+        workflow,
+        capabilities,
+        qualityGates,
+        ...(mode ? { mode } : {}),
+        ...(manager ? { manager } : {}),
+    };
+    return { team, errors };
+}
+function mapRouter(raw, path) {
+    const errors = [];
+    const rules = [];
+    if (raw.rules !== undefined) {
+        if (!Array.isArray(raw.rules)) {
+            errors.push({ field: `${path}.rules`, message: "must be an array" });
+        }
+        else {
+            for (let i = 0; i < raw.rules.length; i++) {
+                const ruleRaw = raw.rules[i];
+                if (!ruleRaw.match || typeof ruleRaw.match !== "string") {
+                    errors.push({ field: `${path}.rules[${i}].match`, message: "must be a non-empty string" });
+                }
+                if (!ruleRaw.team || typeof ruleRaw.team !== "string") {
+                    errors.push({ field: `${path}.rules[${i}].team`, message: "must be a non-empty string" });
+                }
+                rules.push({
+                    match: typeof ruleRaw.match === "string" ? ruleRaw.match : "",
+                    team: typeof ruleRaw.team === "string" ? ruleRaw.team : "",
+                });
+            }
+        }
+    }
+    if (!raw.fallback || typeof raw.fallback !== "string") {
+        errors.push({ field: `${path}.fallback`, message: "must be a non-empty string" });
+    }
+    let classifier;
+    if (raw.classifier !== undefined) {
+        const classifierRaw = raw.classifier;
+        const { agent, errors: classifierErrors } = mapAgent("classifier", { ...classifierRaw, tier: classifierRaw.tier ?? "fast" }, `${path}.classifier`);
+        classifier = agent;
+        errors.push(...classifierErrors);
+    }
+    const router = {
+        rules,
+        fallback: typeof raw.fallback === "string" ? raw.fallback : "",
+        ...(classifier ? { classifier } : {}),
+    };
+    return { router, errors };
+}
+function mapMemory(raw, path) {
+    const errors = [];
+    const scopes = [];
+    if (!raw.scopes || !Array.isArray(raw.scopes)) {
+        errors.push({ field: `${path}.scopes`, message: "must be a non-empty array" });
+    }
+    else {
+        for (const s of raw.scopes) {
+            if (typeof s === "string")
+                scopes.push(s);
+        }
+    }
+    if (!raw.backend || typeof raw.backend !== "string") {
+        errors.push({ field: `${path}.backend`, message: "must be a non-empty string" });
+    }
+    const memory = {
+        scopes,
+        backend: typeof raw.backend === "string" ? raw.backend : "",
+        ...(typeof raw.sync === "string" ? { sync: raw.sync } : {}),
+    };
+    return { memory, errors };
+}
+const VALID_TRIGGER_TYPES = ["webhook", "event", "schedule"];
+function mapTrigger(raw, path) {
+    const errors = [];
+    if (!raw.name || typeof raw.name !== "string") {
+        errors.push({ field: `${path}.name`, message: "must be a non-empty string" });
+    }
+    if (!raw.type || typeof raw.type !== "string" || !VALID_TRIGGER_TYPES.includes(raw.type)) {
+        errors.push({ field: `${path}.type`, message: `must be one of: ${VALID_TRIGGER_TYPES.join(", ")}` });
+    }
+    if (!raw.team || typeof raw.team !== "string") {
+        errors.push({ field: `${path}.team`, message: "must be a non-empty string" });
+    }
+    const base = {
+        name: typeof raw.name === "string" ? raw.name : "",
+        team: typeof raw.team === "string" ? raw.team : "",
+        ...(typeof raw.task === "string" ? { task: raw.task } : {}),
+        ...(typeof raw.enabled === "boolean" ? { enabled: raw.enabled } : {}),
+    };
+    const type = typeof raw.type === "string" ? raw.type : "";
+    switch (type) {
+        case "webhook": {
+            if (!raw.path || typeof raw.path !== "string") {
+                errors.push({ field: `${path}.path`, message: "must be a non-empty string" });
+            }
+            const trigger = {
+                ...base,
+                type: "webhook",
+                path: typeof raw.path === "string" ? raw.path : "",
+                ...(typeof raw.method === "string" ? { method: raw.method } : {}),
+                ...(typeof raw.secretEnv === "string" ? { secretEnv: raw.secretEnv } : {}),
+            };
+            return { trigger, errors };
+        }
+        case "event": {
+            if (!raw.event || typeof raw.event !== "string") {
+                errors.push({ field: `${path}.event`, message: "must be a non-empty string" });
+            }
+            const trigger = {
+                ...base,
+                type: "event",
+                event: typeof raw.event === "string" ? raw.event : "",
+                ...(raw.filter && typeof raw.filter === "object" && !Array.isArray(raw.filter)
+                    ? { filter: raw.filter }
+                    : {}),
+            };
+            return { trigger, errors };
+        }
+        case "schedule": {
+            if (!raw.cron || typeof raw.cron !== "string") {
+                errors.push({ field: `${path}.cron`, message: "must be a non-empty string" });
+            }
+            const trigger = {
+                ...base,
+                type: "schedule",
+                cron: typeof raw.cron === "string" ? raw.cron : "",
+                ...(typeof raw.timezone === "string" ? { timezone: raw.timezone } : {}),
+            };
+            return { trigger, errors };
+        }
+        default: {
+            // Return a webhook trigger as placeholder to satisfy the type system; the type error was already recorded
+            const trigger = {
+                ...base,
+                type: "webhook",
+                path: "",
+            };
+            return { trigger, errors };
+        }
+    }
+}
+function mapKnowledge(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { knowledge: undefined, errors: [] };
+    }
+    const rawEmbedding = raw.embedding;
+    const rawStore = raw.store;
+    const rawChunking = raw.chunking;
+    const embedding = {
+        provider: (typeof rawEmbedding?.provider === "string" ? rawEmbedding.provider : ""),
+        model: typeof rawEmbedding?.model === "string" ? rawEmbedding.model : undefined,
+        apiKeyEnv: typeof rawEmbedding?.apiKeyEnv === "string" ? rawEmbedding.apiKeyEnv : undefined,
+        baseUrl: typeof rawEmbedding?.baseUrl === "string" ? rawEmbedding.baseUrl : undefined,
+    };
+    const store = {
+        backend: (typeof rawStore?.backend === "string" ? rawStore.backend : ""),
+        connectionString: typeof rawStore?.connectionString === "string" ? rawStore.connectionString : undefined,
+    };
+    const chunking = {
+        strategy: (typeof rawChunking?.strategy === "string" ? rawChunking.strategy : ""),
+        chunkSize: typeof rawChunking?.chunkSize === "number" ? rawChunking.chunkSize : undefined,
+        chunkOverlap: typeof rawChunking?.chunkOverlap === "number" ? rawChunking.chunkOverlap : undefined,
+    };
+    const sources = [];
+    if (Array.isArray(raw.sources)) {
+        for (let i = 0; i < raw.sources.length; i++) {
+            const source = raw.sources[i];
+            if (!source)
+                continue;
+            const rawSourceChunking = source.chunking;
+            const sourceChunking = rawSourceChunking ? {
+                strategy: (typeof rawSourceChunking.strategy === "string" ? rawSourceChunking.strategy : ""),
+                chunkSize: typeof rawSourceChunking.chunkSize === "number" ? rawSourceChunking.chunkSize : undefined,
+                chunkOverlap: typeof rawSourceChunking.chunkOverlap === "number" ? rawSourceChunking.chunkOverlap : undefined,
+            } : undefined;
+            sources.push({
+                name: typeof source.name === "string" ? source.name : "",
+                path: typeof source.path === "string" ? source.path : "",
+                watch: typeof source.watch === "boolean" ? source.watch : undefined,
+                chunking: sourceChunking,
+            });
+        }
+    }
+    const allowedAgents = Array.isArray(raw.allowedAgents)
+        ? raw.allowedAgents.filter((a) => typeof a === "string")
+        : undefined;
+    const knowledge = {
+        embedding,
+        store,
+        chunking,
+        sources,
+        ...(allowedAgents && allowedAgents.length > 0 ? { allowedAgents } : {}),
+    };
+    const validationErrors = validateKnowledgeConfig(knowledge);
+    for (const ve of validationErrors) {
+        errors.push(ve);
+    }
+    return { knowledge: validationErrors.length > 0 ? undefined : knowledge, errors };
+}
+const VALID_SCORER_TYPES = [
+    "exact-match", "contains", "json-validity", "length", "latency", "cost",
+    "faithfulness", "relevance", "coherence", "hallucination", "toxicity",
+    "custom-prompt", "composite",
+];
+function mapEvalScorer(raw) {
+    const errors = [];
+    const subScorers = [];
+    if (raw.scorers !== undefined && Array.isArray(raw.scorers)) {
+        for (let i = 0; i < raw.scorers.length; i++) {
+            const { scorer, errors: subErrors } = mapEvalScorer(raw.scorers[i]);
+            subScorers.push(scorer);
+            errors.push(...subErrors);
+        }
+    }
+    let scorerType = "exact-match";
+    if (typeof raw.type === "string" && VALID_SCORER_TYPES.includes(raw.type)) {
+        scorerType = raw.type;
+    }
+    else if (typeof raw.type === "string") {
+        errors.push({ field: "type", message: `unknown scorer type "${raw.type}", must be one of: ${VALID_SCORER_TYPES.join(", ")}` });
+    }
+    const scorer = {
+        name: typeof raw.name === "string" ? raw.name : "",
+        type: scorerType,
+        ...(subScorers.length > 0 ? { scorers: subScorers } : {}),
+        ...(typeof raw.schema === "object" && raw.schema !== null && !Array.isArray(raw.schema) ? { schema: raw.schema } : {}),
+        ...(typeof raw.prompt === "string" ? { prompt: raw.prompt } : {}),
+        ...(typeof raw.minLength === "number" ? { minLength: raw.minLength } : {}),
+        ...(typeof raw.maxLength === "number" ? { maxLength: raw.maxLength } : {}),
+        ...(typeof raw.maxLatencyMs === "number" ? { maxLatencyMs: raw.maxLatencyMs } : {}),
+        ...(typeof raw.maxCostUsd === "number" ? { maxCostUsd: raw.maxCostUsd } : {}),
+        ...(Array.isArray(raw.substrings) ? { substrings: raw.substrings.filter((s) => typeof s === "string") } : {}),
+    };
+    return { scorer, errors };
+}
+function mapEval(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { eval: undefined, errors: [] };
+    }
+    const datasets = [];
+    if (Array.isArray(raw.datasets)) {
+        for (const ds of raw.datasets) {
+            const rawDs = ds;
+            if (!rawDs)
+                continue;
+            datasets.push({
+                name: typeof rawDs.name === "string" ? rawDs.name : "",
+                path: typeof rawDs.path === "string" ? rawDs.path : "",
+            });
+        }
+    }
+    const scorers = [];
+    if (Array.isArray(raw.scorers)) {
+        for (const s of raw.scorers) {
+            const { scorer, errors: scorerErrors } = mapEvalScorer(s);
+            scorers.push(scorer);
+            errors.push(...scorerErrors);
+        }
+    }
+    const experiments = [];
+    if (Array.isArray(raw.experiments)) {
+        for (const exp of raw.experiments) {
+            const rawExp = exp;
+            if (!rawExp)
+                continue;
+            const expScorers = [];
+            if (Array.isArray(rawExp.scorers)) {
+                for (const s of rawExp.scorers) {
+                    if (typeof s === "string")
+                        expScorers.push(s);
+                }
+            }
+            experiments.push({
+                name: typeof rawExp.name === "string" ? rawExp.name : "",
+                dataset: typeof rawExp.dataset === "string" ? rawExp.dataset : "",
+                team: typeof rawExp.team === "string" ? rawExp.team : "",
+                scorers: expScorers,
+                ...(typeof rawExp.overrides === "object" && rawExp.overrides !== null && !Array.isArray(rawExp.overrides) ? { overrides: rawExp.overrides } : {}),
+                ...(typeof rawExp.compare === "string" ? { compare: rawExp.compare } : {}),
+            });
+        }
+    }
+    const evalConfig = {
+        datasets,
+        scorers,
+        experiments,
+    };
+    const validationErrors = validateEvalConfig(evalConfig);
+    for (const ve of validationErrors) {
+        errors.push({ field: `eval.${ve.field}`, message: ve.message });
+    }
+    return { eval: validationErrors.length > 0 ? undefined : evalConfig, errors };
+}
+function mapMcp(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { mcp: undefined, errors: [] };
+    }
+    const servers = [];
+    if (Array.isArray(raw.servers)) {
+        for (let i = 0; i < raw.servers.length; i++) {
+            const server = raw.servers[i];
+            if (!server)
+                continue;
+            let env;
+            if (server.env && typeof server.env === "object" && !Array.isArray(server.env)) {
+                const envObj = {};
+                for (const [key, value] of Object.entries(server.env)) {
+                    if (typeof value === "string") {
+                        envObj[key] = value;
+                    }
+                }
+                if (Object.keys(envObj).length > 0) {
+                    env = envObj;
+                }
+            }
+            servers.push({
+                name: typeof server.name === "string" ? server.name : "",
+                url: typeof server.url === "string" ? server.url : "",
+                ...(env && Object.keys(env).length > 0 ? { env } : {}),
+                ...(typeof server.reconnect === "boolean" ? { reconnect: server.reconnect } : {}),
+            });
+        }
+    }
+    const mcpConfig = { servers };
+    const validationErrors = validateMcpConfig(mcpConfig);
+    for (const ve of validationErrors) {
+        errors.push({ field: `mcp.${ve.field}`, message: ve.message });
+    }
+    return { mcp: validationErrors.length > 0 ? undefined : mcpConfig, errors };
+}
+function mapToolSelection(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { toolSelection: undefined, errors: [] };
+    }
+    const strategy = typeof raw.strategy === "string" ? raw.strategy : undefined;
+    const config = {
+        strategy: strategy ?? "all",
+        ...(typeof raw.maxTools === "number" ? { maxTools: raw.maxTools } : {}),
+        ...(typeof raw.threshold === "number" ? { threshold: raw.threshold } : {}),
+    };
+    const validationErrors = validateToolSelectionConfig(config);
+    for (const ve of validationErrors) {
+        errors.push({ field: `toolSelection.${ve.field}`, message: ve.message });
+    }
+    return { toolSelection: validationErrors.length > 0 ? undefined : config, errors };
+}
+function mapVoiceConfig(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { voice: undefined, errors: [] };
+    }
+    const rawStt = raw.stt;
+    const rawTts = raw.tts;
+    if (!rawStt || typeof rawStt !== "object") {
+        errors.push({ field: "voice.stt", message: "must be an object" });
+    }
+    if (!rawTts || typeof rawTts !== "object") {
+        errors.push({ field: "voice.tts", message: "must be an object" });
+    }
+    if (errors.length > 0)
+        return { voice: undefined, errors };
+    const stt = {
+        provider: (typeof rawStt.provider === "string" ? rawStt.provider : ""),
+        ...(typeof rawStt.model === "string" ? { model: rawStt.model } : {}),
+        ...(typeof rawStt.apiKeyEnv === "string" ? { apiKeyEnv: rawStt.apiKeyEnv } : {}),
+        ...(typeof rawStt.language === "string" ? { language: rawStt.language } : {}),
+    };
+    const tts = {
+        provider: (typeof rawTts.provider === "string" ? rawTts.provider : ""),
+        ...(typeof rawTts.model === "string" ? { model: rawTts.model } : {}),
+        ...(typeof rawTts.apiKeyEnv === "string" ? { apiKeyEnv: rawTts.apiKeyEnv } : {}),
+        ...(typeof rawTts.voice === "string" ? { voice: rawTts.voice } : {}),
+    };
+    const voice = { stt, tts };
+    const validationErrors = validateVoiceConfig(voice);
+    for (const ve of validationErrors) {
+        errors.push(ve);
+    }
+    return { voice: validationErrors.length > 0 ? undefined : voice, errors };
+}
+function mapSafety(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { safety: undefined, errors: [] };
+    }
+    let pii;
+    if (raw.pii !== undefined) {
+        const rawPii = raw.pii;
+        const detect = [];
+        if (Array.isArray(rawPii.detect)) {
+            for (const d of rawPii.detect) {
+                if (typeof d === "string")
+                    detect.push(d);
+            }
+        }
+        const allowlist = [];
+        if (Array.isArray(rawPii.allowlist)) {
+            for (const a of rawPii.allowlist) {
+                if (typeof a === "string")
+                    allowlist.push(a);
+            }
+        }
+        pii = {
+            detect,
+            action: (typeof rawPii.action === "string" ? rawPii.action : "detect"),
+            ...(typeof rawPii.deepScan === "boolean" ? { deepScan: rawPii.deepScan } : {}),
+            ...(allowlist.length > 0 ? { allowlist } : {}),
+        };
+    }
+    let content;
+    if (raw.content !== undefined) {
+        const rawContent = raw.content;
+        const categories = {};
+        if (rawContent.categories && typeof rawContent.categories === "object" && !Array.isArray(rawContent.categories)) {
+            for (const [cat, catConfig] of Object.entries(rawContent.categories)) {
+                if (!catConfig)
+                    continue;
+                categories[cat] = {
+                    threshold: typeof catConfig.threshold === "number" ? catConfig.threshold : 0.5,
+                    action: (typeof catConfig.action === "string" ? catConfig.action : "block"),
+                };
+            }
+        }
+        content = {
+            enabled: typeof rawContent.enabled === "boolean" ? rawContent.enabled : true,
+            categories,
+            ...(typeof rawContent.deepScan === "boolean" ? { deepScan: rawContent.deepScan } : {}),
+        };
+    }
+    const rails = [];
+    if (raw.rails !== undefined) {
+        if (!Array.isArray(raw.rails)) {
+            errors.push({ field: "safety.rails", message: "must be an array" });
+        }
+        else {
+            for (let i = 0; i < raw.rails.length; i++) {
+                const rawRail = raw.rails[i];
+                if (!rawRail)
+                    continue;
+                const railType = typeof rawRail.type === "string" ? rawRail.type : "";
+                switch (railType) {
+                    case "topic": {
+                        const block = Array.isArray(rawRail.block) ? rawRail.block.filter((b) => typeof b === "string") : [];
+                        const escalate = Array.isArray(rawRail.escalate) ? rawRail.escalate.filter((e) => typeof e === "string") : [];
+                        rails.push({ type: "topic", ...(block.length > 0 ? { block } : {}), ...(escalate.length > 0 ? { escalate } : {}) });
+                        break;
+                    }
+                    case "competitor": {
+                        const competitors = Array.isArray(rawRail.competitors) ? rawRail.competitors.filter((c) => typeof c === "string") : [];
+                        rails.push({
+                            type: "competitor",
+                            competitors,
+                            response: typeof rawRail.response === "string" ? rawRail.response : "",
+                        });
+                        break;
+                    }
+                    case "escalation": {
+                        const triggers = Array.isArray(rawRail.triggers) ? rawRail.triggers.filter((t) => typeof t === "string") : [];
+                        rails.push({ type: "escalation", triggers });
+                        break;
+                    }
+                    case "compliance": {
+                        const required = Array.isArray(rawRail.required) ? rawRail.required.filter((r) => typeof r === "string") : [];
+                        const forbid = Array.isArray(rawRail.forbid) ? rawRail.forbid.filter((f) => typeof f === "string") : [];
+                        rails.push({
+                            type: "compliance",
+                            ...(required.length > 0 ? { required } : {}),
+                            ...(forbid.length > 0 ? { forbid } : {}),
+                        });
+                        break;
+                    }
+                    default:
+                        errors.push({ field: `safety.rails[${i}].type`, message: `unknown rail type "${railType}"` });
+                }
+            }
+        }
+    }
+    const safety = {
+        ...(pii ? { pii } : {}),
+        ...(content ? { content } : {}),
+        ...(rails.length > 0 ? { rails } : {}),
+    };
+    const validationErrors = validateSafetyConfig(safety);
+    for (const ve of validationErrors) {
+        errors.push({ field: `safety.${ve.field}`, message: ve.message });
+    }
+    return { safety: validationErrors.length > 0 ? undefined : safety, errors };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Parse a YAML string into a typed App composite. Throws AppLoaderError if invalid. */
+export function parseAppYaml(content) {
+    let data;
+    try {
+        data = parse(content);
+    }
+    catch (err) {
+        throw new AppLoaderError([{ field: "yaml", message: String(err) }]);
+    }
+    const errors = [];
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new AppLoaderError([{ field: "root", message: "must be a YAML object" }]);
+    }
+    const raw = data;
+    // name
+    if (!raw.name || typeof raw.name !== "string") {
+        errors.push({ field: "name", message: "must be a non-empty string" });
+    }
+    // channels
+    const channels = [];
+    if (raw.channels !== undefined) {
+        if (!Array.isArray(raw.channels)) {
+            errors.push({ field: "channels", message: "must be an array" });
+        }
+        else {
+            for (const c of raw.channels) {
+                if (typeof c === "string")
+                    channels.push(c);
+            }
+        }
+    }
+    // memory
+    let memory = { scopes: [], backend: "" };
+    if (!raw.memory || typeof raw.memory !== "object" || Array.isArray(raw.memory)) {
+        errors.push({ field: "memory", message: "must be an object" });
+    }
+    else {
+        const { memory: mem, errors: memErrors } = mapMemory(raw.memory, "memory");
+        memory = mem;
+        errors.push(...memErrors);
+    }
+    // teams
+    const teams = {};
+    if (!raw.teams || typeof raw.teams !== "object" || Array.isArray(raw.teams)) {
+        errors.push({ field: "teams", message: "must be an object" });
+    }
+    else {
+        for (const [teamName, teamRaw] of Object.entries(raw.teams)) {
+            const { team, errors: teamErrors } = mapTeam(teamName, teamRaw ?? {}, `teams.${teamName}`);
+            teams[teamName] = team;
+            errors.push(...teamErrors);
+        }
+    }
+    // router
+    let router = { rules: [], fallback: "" };
+    if (!raw.router || typeof raw.router !== "object" || Array.isArray(raw.router)) {
+        errors.push({ field: "router", message: "must be an object" });
+    }
+    else {
+        const { router: rt, errors: routerErrors } = mapRouter(raw.router, "router");
+        router = rt;
+        errors.push(...routerErrors);
+    }
+    // triggers (optional)
+    const triggers = [];
+    if (raw.triggers !== undefined) {
+        if (!Array.isArray(raw.triggers)) {
+            errors.push({ field: "triggers", message: "must be an array" });
+        }
+        else {
+            for (let i = 0; i < raw.triggers.length; i++) {
+                const { trigger, errors: triggerErrors } = mapTrigger(raw.triggers[i], `triggers[${i}]`);
+                triggers.push(trigger);
+                errors.push(...triggerErrors);
+            }
+        }
+    }
+    // knowledge (optional)
+    let knowledge;
+    if (raw.knowledge !== undefined) {
+        const { knowledge: knowledgeConfig, errors: knowledgeErrors } = mapKnowledge(raw.knowledge);
+        knowledge = knowledgeConfig;
+        errors.push(...knowledgeErrors);
+    }
+    // eval (optional)
+    let evalConfig;
+    if (raw.eval !== undefined) {
+        const { eval: parsedEval, errors: evalErrors } = mapEval(raw.eval);
+        evalConfig = parsedEval;
+        errors.push(...evalErrors);
+    }
+    // mcp (optional)
+    let mcpConfig;
+    if (raw.mcp !== undefined) {
+        const { mcp, errors: mcpErrors } = mapMcp(raw.mcp);
+        mcpConfig = mcp;
+        errors.push(...mcpErrors);
+    }
+    // toolSelection (optional)
+    let toolSelectionConfig;
+    if (raw.toolSelection !== undefined) {
+        const { toolSelection, errors: tsErrors } = mapToolSelection(raw.toolSelection);
+        toolSelectionConfig = toolSelection;
+        errors.push(...tsErrors);
+    }
+    // voice (optional)
+    let voiceConfig;
+    if (raw.voice !== undefined) {
+        const { voice, errors: voiceErrors } = mapVoiceConfig(raw.voice);
+        voiceConfig = voice;
+        errors.push(...voiceErrors);
+    }
+    // safety (optional)
+    let safetyConfig;
+    if (raw.safety !== undefined) {
+        const { safety, errors: safetyErrors } = mapSafety(raw.safety);
+        safetyConfig = safety;
+        errors.push(...safetyErrors);
+    }
+    if (errors.length > 0)
+        throw new AppLoaderError(errors);
+    return {
+        name: raw.name,
+        teams,
+        router,
+        memory,
+        channels,
+        ...(triggers.length > 0 ? { triggers } : {}),
+        ...(knowledge ? { knowledge } : {}),
+        ...(evalConfig ? { eval: evalConfig } : {}),
+        ...(mcpConfig ? { mcp: mcpConfig } : {}),
+        ...(toolSelectionConfig ? { toolSelection: toolSelectionConfig } : {}),
+        ...(voiceConfig ? { voice: voiceConfig } : {}),
+        ...(safetyConfig ? { safety: safetyConfig } : {}),
+    };
+}
+/** Validate the dependency graph of an App. Returns null if valid, AppLoaderError if not. */
+export function validateAppGraph(app) {
+    const appErrors = validateApp(app);
+    if (appErrors.length === 0)
+        return null;
+    return new AppLoaderError(appErrors);
+}
+//# sourceMappingURL=app-loader.js.map