wotann 0.5.0 → 0.5.39

package/dist/agents/yaml-manifest.js

@@ -0,0 +1,901 @@
+/**
+ * yaml-manifest — Declarative YAML manifest format for managed agents.
+ *
+ * Port of the agent.yaml format from
+ *   anthropics/financial-services/managed-agent-cookbooks
+ *   (https://github.com/anthropics/financial-services/tree/main/managed-agent-cookbooks)
+ *
+ * Each agent.yaml declares a managed agent's identity, model, system
+ * prompt, tool grants, MCP servers, callable sub-agents, skill imports,
+ * and few-shot steering examples. We parse + validate + serialize +
+ * compose these manifests so the runtime can spawn an agent from a
+ * single declarative file.
+ *
+ * Why a hand-rolled YAML subset parser:
+ *   - js-yaml ships YAML 1.2 with anchors/aliases/merge-keys/tags. The
+ *     anchor/alias surface is a known DoS + deserialization-gadget area
+ *     ("YAML billion laughs"). Our subset rejects them by construction.
+ *   - +1 transitive dep + ~70KB is not worth it for the subset we use.
+ *
+ * Quality bars:
+ *   - QB#1 immutable: every public type readonly + Object.freeze on parse
+ *   - QB#3 honest: parse/validate return tagged result; never throws
+ *   - QB#7 stateless: pure functions throughout; no module-level state
+ *   - QB#11 sibling-site: composes Jaccard similarity from
+ *     ../evolution/evaluator (single source of truth across the codebase)
+ *   - QB#19 zombie-free: every export has a test caller in
+ *     tests/agents/yaml-manifest.test.ts
+ */
+import { jaccardScore } from "../evolution/evaluator.js";
+function makeErr(message, line) {
+    return {
+        ok: false,
+        error: line !== undefined ? { message, line } : { message },
+    };
+}
+function isErr(v) {
+    return typeof v === "object" && v !== null && v.ok === false;
+}
+function parseYamlSubset(source) {
+    const rawLines = source.split(/\r?\n/);
+    // Pre-scan for forbidden constructs so errors anchor on the offending line.
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = rawLines[i] ?? "";
+        if (/^\t/.test(raw) || /^[ ]*\t/.test(raw)) {
+            return makeErr("tabs are not permitted in indentation", i + 1);
+        }
+        const stripped = stripLineComment(raw);
+        if (/(?:^|[\s:])&[A-Za-z_][A-Za-z0-9_-]*/.test(stripped)) {
+            return makeErr("YAML anchors (&...) are not supported", i + 1);
+        }
+        if (/(?:^|[\s:])\*[A-Za-z_][A-Za-z0-9_-]*\s*$/.test(stripped)) {
+            return makeErr("YAML aliases (*...) are not supported", i + 1);
+        }
+        if (/^\s*<<\s*:/.test(stripped)) {
+            return makeErr("YAML merge keys (<<:) are not supported", i + 1);
+        }
+        if (/!!?[A-Za-z]/.test(stripped) && !/['"]/.test(stripped)) {
+            return makeErr("YAML tags (!type) are not supported", i + 1);
+        }
+        if (/^---\s*$/.test(stripped) || /^\.\.\.\s*$/.test(stripped)) {
+            return makeErr("multi-document YAML (---) is not supported", i + 1);
+        }
+    }
+    const lines = [];
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = rawLines[i] ?? "";
+        const stripped = stripLineComment(raw);
+        if (!/\S/.test(stripped))
+            continue;
+        const indent = countLeadingSpaces(raw);
+        lines.push({ indent, content: stripped.slice(indent), lineNo: i + 1 });
+    }
+    if (lines.length === 0) {
+        return { ok: true, value: Object.freeze({}) };
+    }
+    let cursor = 0;
+    function peek() {
+        return lines[cursor];
+    }
+    function parseBlock(indent) {
+        const first = peek();
+        if (!first || first.indent < indent)
+            return Object.freeze({});
+        if (first.content.startsWith("- ") || first.content === "-")
+            return parseList(indent);
+        return parseMap(indent);
+    }
+    function parseMap(indent) {
+        const result = {};
+        while (true) {
+            const line = peek();
+            if (!line || line.indent < indent)
+                break;
+            if (line.indent > indent) {
+                return makeErr("unexpected indentation increase", line.lineNo);
+            }
+            const m = /^([^:]+?):(?:\s+(.*))?$/.exec(line.content);
+            if (!m)
+                return makeErr(`expected 'key:' got '${line.content}'`, line.lineNo);
+            const key = unquoteScalarString(m[1]?.trim() ?? "");
+            const inlineRaw = m[2];
+            cursor++;
+            if (inlineRaw === undefined || inlineRaw === "") {
+                const next = peek();
+                if (!next || next.indent <= indent) {
+                    result[key] = null;
+                }
+                else {
+                    const childIndent = next.indent;
+                    const child = parseBlock(childIndent);
+                    if (isErr(child))
+                        return child;
+                    result[key] = child;
+                }
+            }
+            else if (inlineRaw === "|" ||
+                inlineRaw === ">" ||
+                inlineRaw === "|-" ||
+                inlineRaw === ">-") {
+                const next = peek();
+                if (!next || next.indent <= indent) {
+                    result[key] = "";
+                }
+                else {
+                    const childIndent = next.indent;
+                    const collected = [];
+                    while (true) {
+                        const ln = peek();
+                        if (!ln || ln.indent < childIndent)
+                            break;
+                        const raw = (rawLines[ln.lineNo - 1] ?? "").replace(/\r$/, "");
+                        const sliced = raw.startsWith(" ".repeat(childIndent))
+                            ? raw.slice(childIndent)
+                            : raw.replace(/^\s+/, "");
+                        collected.push(sliced);
+                        cursor++;
+                    }
+                    let text;
+                    if (inlineRaw === "|" || inlineRaw === "|-") {
+                        text = collected.join("\n");
+                    }
+                    else {
+                        text = collected
+                            .reduce((acc, l) => {
+                            if (l === "" && acc.length > 0)
+                                acc.push("\n");
+                            else if (acc.length > 0 && acc[acc.length - 1] !== "\n")
+                                acc[acc.length - 1] += " " + l;
+                            else
+                                acc.push(l);
+                            return acc;
+                        }, [])
+                            .join("");
+                    }
+                    if (inlineRaw === "|" || inlineRaw === ">") {
+                        text = text.replace(/\s+$/, "") + "\n";
+                    }
+                    else {
+                        text = text.replace(/\s+$/, "");
+                    }
+                    result[key] = text;
+                }
+            }
+            else {
+                const v = parseInlineValue(inlineRaw, line.lineNo);
+                if (isErr(v))
+                    return v;
+                result[key] = v;
+            }
+        }
+        return Object.freeze(result);
+    }
+    function parseList(indent) {
+        const result = [];
+        while (true) {
+            const line = peek();
+            if (!line || line.indent < indent)
+                break;
+            if (line.indent > indent) {
+                return makeErr("unexpected indentation increase in list", line.lineNo);
+            }
+            if (!(line.content.startsWith("- ") || line.content === "-"))
+                break;
+            const itemBody = line.content === "-" ? "" : line.content.slice(2);
+            cursor++;
+            if (itemBody === "") {
+                const next = peek();
+                if (!next || next.indent <= indent) {
+                    result.push(null);
+                }
+                else {
+                    const child = parseBlock(next.indent);
+                    if (isErr(child))
+                        return child;
+                    result.push(child);
+                }
+            }
+            else if (/^[^:]+:(?:\s|$)/.test(itemBody)) {
+                const synthetic = {
+                    indent: indent + 2,
+                    content: itemBody,
+                    lineNo: line.lineNo,
+                };
+                lines.splice(cursor, 0, synthetic);
+                const child = parseMap(indent + 2);
+                if (isErr(child))
+                    return child;
+                result.push(child);
+            }
+            else {
+                const v = parseInlineValue(itemBody, line.lineNo);
+                if (isErr(v))
+                    return v;
+                result.push(v);
+            }
+        }
+        return Object.freeze(result);
+    }
+    const root = parseBlock(lines[0]?.indent ?? 0);
+    if (isErr(root))
+        return root;
+    if (typeof root !== "object" || root === null || Array.isArray(root)) {
+        return makeErr("top-level YAML must be a map");
+    }
+    return { ok: true, value: root };
+}
+function stripLineComment(raw) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (c === "#" && !inSingle && !inDouble) {
+            if (i === 0 || raw[i - 1] === " " || raw[i - 1] === "\t") {
+                return raw.slice(0, i).replace(/\s+$/, "");
+            }
+        }
+    }
+    return raw;
+}
+function countLeadingSpaces(s) {
+    let i = 0;
+    while (i < s.length && s[i] === " ")
+        i++;
+    return i;
+}
+function parseInlineValue(raw, lineNo) {
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return "";
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) {
+        return unquoteDouble(trimmed.slice(1, -1));
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2) {
+        return trimmed.slice(1, -1).replace(/''/g, "'");
+    }
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        return parseFlowList(trimmed.slice(1, -1), lineNo);
+    }
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        return parseFlowMap(trimmed.slice(1, -1), lineNo);
+    }
+    if (trimmed === "null" || trimmed === "~")
+        return null;
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (/^-?\d+$/.test(trimmed))
+        return Number.parseInt(trimmed, 10);
+    if (/^-?\d+\.\d+$/.test(trimmed))
+        return Number.parseFloat(trimmed);
+    return trimmed;
+}
+function parseFlowList(body, lineNo) {
+    const parts = splitFlow(body);
+    const out = [];
+    for (const p of parts) {
+        const v = parseInlineValue(p, lineNo);
+        if (isErr(v))
+            return v;
+        out.push(v);
+    }
+    return Object.freeze(out);
+}
+function parseFlowMap(body, lineNo) {
+    const parts = splitFlow(body);
+    const out = {};
+    for (const p of parts) {
+        const colonAt = findFlowColon(p);
+        if (colonAt < 0)
+            return makeErr(`flow map entry missing ':' near '${p}'`, lineNo);
+        const k = unquoteScalarString(p.slice(0, colonAt).trim());
+        const v = parseInlineValue(p.slice(colonAt + 1).trim(), lineNo);
+        if (isErr(v))
+            return v;
+        out[k] = v;
+    }
+    return Object.freeze(out);
+}
+function findFlowColon(s) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (c === ":" && !inSingle && !inDouble)
+            return i;
+    }
+    return -1;
+}
+function splitFlow(body) {
+    const parts = [];
+    let depth = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let buf = "";
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i] ?? "";
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (!inSingle && !inDouble) {
+            if (c === "[" || c === "{")
+                depth++;
+            else if (c === "]" || c === "}")
+                depth--;
+            else if (c === "," && depth === 0) {
+                const t = buf.trim();
+                if (t !== "")
+                    parts.push(t);
+                buf = "";
+                continue;
+            }
+        }
+        buf += c;
+    }
+    const t = buf.trim();
+    if (t !== "")
+        parts.push(t);
+    return parts;
+}
+function unquoteScalarString(s) {
+    if (s.startsWith('"') && s.endsWith('"') && s.length >= 2) {
+        return unquoteDouble(s.slice(1, -1));
+    }
+    if (s.startsWith("'") && s.endsWith("'") && s.length >= 2) {
+        return s.slice(1, -1).replace(/''/g, "'");
+    }
+    return s;
+}
+function unquoteDouble(s) {
+    return s.replace(/\\(["\\nrt])/g, (_, ch) => {
+        switch (ch) {
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            case '"':
+                return '"';
+            case "\\":
+                return "\\";
+            default:
+                return ch;
+        }
+    });
+}
+// ── Manifest projection ──────────────────────────────────────────────
+const NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function isYamlMap(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isYamlList(v) {
+    return Array.isArray(v);
+}
+function projectManifest(raw) {
+    const errors = [];
+    const name = raw["name"];
+    if (typeof name !== "string" || name === "") {
+        errors.push("'name' is required and must be a non-empty string");
+    }
+    else if (!NAME_REGEX.test(name)) {
+        errors.push("'name' must match /^[A-Za-z0-9][A-Za-z0-9_-]*$/");
+    }
+    const version = raw["version"];
+    if (version !== 1) {
+        errors.push("'version' is required and must equal 1");
+    }
+    if (errors.length > 0) {
+        return { ok: false, error: errors.join("; ") };
+    }
+    const out = {
+        name: name,
+        version: 1,
+    };
+    if ("model" in raw) {
+        if (typeof raw["model"] !== "string") {
+            return { ok: false, error: "'model' must be a string" };
+        }
+        out["model"] = raw["model"];
+    }
+    if ("system_prompt" in raw) {
+        const v = raw["system_prompt"];
+        if (typeof v !== "string") {
+            return { ok: false, error: "'system_prompt' must be a string" };
+        }
+        out["systemPrompt"] = v;
+    }
+    if ("tools" in raw) {
+        const v = raw["tools"];
+        if (!isYamlList(v) || !v.every((x) => typeof x === "string")) {
+            return { ok: false, error: "'tools' must be a list of strings" };
+        }
+        out["tools"] = Object.freeze([...v]);
+    }
+    if ("mcp_servers" in raw) {
+        const v = raw["mcp_servers"];
+        if (!isYamlList(v))
+            return { ok: false, error: "'mcp_servers' must be a list" };
+        const list = [];
+        for (const entry of v) {
+            if (!isYamlMap(entry)) {
+                return { ok: false, error: "'mcp_servers' entries must be maps" };
+            }
+            const nm = entry["name"];
+            const tp = entry["transport"];
+            if (typeof nm !== "string" || (tp !== "stdio" && tp !== "http")) {
+                return {
+                    ok: false,
+                    error: "mcp_server requires 'name' string and 'transport' stdio|http",
+                };
+            }
+            const ref = { name: nm, transport: tp };
+            if ("command" in entry) {
+                if (typeof entry["command"] !== "string") {
+                    return { ok: false, error: "mcp_server.command must be a string" };
+                }
+                ref["command"] = entry["command"];
+            }
+            if ("url" in entry) {
+                if (typeof entry["url"] !== "string") {
+                    return { ok: false, error: "mcp_server.url must be a string" };
+                }
+                ref["url"] = entry["url"];
+            }
+            if ("args" in entry) {
+                const a = entry["args"];
+                if (!isYamlList(a) || !a.every((x) => typeof x === "string")) {
+                    return { ok: false, error: "mcp_server.args must be a list of strings" };
+                }
+                ref["args"] = Object.freeze([...a]);
+            }
+            list.push(Object.freeze(ref));
+        }
+        out["mcpServers"] = Object.freeze(list);
+    }
+    if ("callable_agents" in raw) {
+        const v = raw["callable_agents"];
+        if (!isYamlList(v) || !v.every((x) => typeof x === "string")) {
+            return { ok: false, error: "'callable_agents' must be a list of strings" };
+        }
+        out["callableAgents"] = Object.freeze([...v]);
+    }
+    if ("skills" in raw) {
+        const v = raw["skills"];
+        if (!isYamlList(v))
+            return { ok: false, error: "'skills' must be a list" };
+        const list = [];
+        for (const entry of v) {
+            if (typeof entry === "string") {
+                list.push(Object.freeze({ inline: entry }));
+            }
+            else if (isYamlMap(entry)) {
+                const ref = {};
+                if ("from_plugin" in entry) {
+                    if (typeof entry["from_plugin"] !== "string") {
+                        return { ok: false, error: "skills[].from_plugin must be a string" };
+                    }
+                    ref["fromPlugin"] = entry["from_plugin"];
+                }
+                if ("inline" in entry) {
+                    if (typeof entry["inline"] !== "string") {
+                        return { ok: false, error: "skills[].inline must be a string" };
+                    }
+                    ref["inline"] = entry["inline"];
+                }
+                if (!("fromPlugin" in ref) && !("inline" in ref)) {
+                    return { ok: false, error: "skills[] entry needs 'from_plugin' or 'inline'" };
+                }
+                list.push(Object.freeze(ref));
+            }
+            else {
+                return { ok: false, error: "skills[] entries must be strings or maps" };
+            }
+        }
+        out["skills"] = Object.freeze(list);
+    }
+    if ("steering_examples" in raw) {
+        const v = raw["steering_examples"];
+        if (!isYamlList(v))
+            return { ok: false, error: "'steering_examples' must be a list" };
+        const list = [];
+        for (const entry of v) {
+            if (!isYamlMap(entry)) {
+                return { ok: false, error: "steering_examples entries must be maps" };
+            }
+            if (typeof entry["input"] !== "string" || typeof entry["output"] !== "string") {
+                return {
+                    ok: false,
+                    error: "steering_examples requires 'input' and 'output' strings",
+                };
+            }
+            const ex = {
+                input: entry["input"],
+                output: entry["output"],
+            };
+            if ("tags" in entry) {
+                const t = entry["tags"];
+                if (!isYamlList(t) || !t.every((x) => typeof x === "string")) {
+                    return { ok: false, error: "steering_examples.tags must be a list of strings" };
+                }
+                ex["tags"] = Object.freeze([...t]);
+            }
+            list.push(Object.freeze(ex));
+        }
+        out["steeringExamples"] = Object.freeze(list);
+    }
+    return { ok: true, manifest: Object.freeze(out) };
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Parse a YAML manifest source string. Returns a tagged result; never
+ * throws on malformed input. The returned manifest is deeply frozen.
+ */
+export function parseAgentYaml(source) {
+    if (typeof source !== "string") {
+        return { ok: false, error: "source must be a string" };
+    }
+    const yaml = parseYamlSubset(source);
+    if (!yaml.ok) {
+        return yaml.error.line !== undefined
+            ? { ok: false, error: yaml.error.message, line: yaml.error.line }
+            : { ok: false, error: yaml.error.message };
+    }
+    return projectManifest(yaml.value);
+}
+/**
+ * Validate a constructed manifest (e.g. one assembled in code rather
+ * than parsed from disk). Catches structural issues plus cross-field
+ * sanity checks (e.g. http MCP needs url, stdio needs command).
+ */
+export function validateManifest(manifest) {
+    const errors = [];
+    if (!manifest || typeof manifest !== "object") {
+        return { ok: false, errors: ["manifest must be an object"] };
+    }
+    if (typeof manifest.name !== "string" || manifest.name === "") {
+        errors.push("'name' is required and must be a non-empty string");
+    }
+    else if (!NAME_REGEX.test(manifest.name)) {
+        errors.push("'name' must match /^[A-Za-z0-9][A-Za-z0-9_-]*$/");
+    }
+    if (manifest.version !== 1) {
+        errors.push("'version' must equal 1");
+    }
+    if (manifest.mcpServers) {
+        for (let i = 0; i < manifest.mcpServers.length; i++) {
+            const s = manifest.mcpServers[i];
+            if (!s)
+                continue;
+            if (s.transport === "stdio" && !s.command) {
+                errors.push(`mcp_servers[${i}] (${s.name}): stdio transport requires 'command'`);
+            }
+            if (s.transport === "http" && !s.url) {
+                errors.push(`mcp_servers[${i}] (${s.name}): http transport requires 'url'`);
+            }
+        }
+    }
+    if (manifest.skills) {
+        for (let i = 0; i < manifest.skills.length; i++) {
+            const sk = manifest.skills[i];
+            if (!sk)
+                continue;
+            if (!sk.fromPlugin && !sk.inline) {
+                errors.push(`skills[${i}]: needs 'fromPlugin' or 'inline'`);
+            }
+        }
+    }
+    if (manifest.callableAgents) {
+        const seen = new Set();
+        for (const a of manifest.callableAgents) {
+            if (a === manifest.name) {
+                errors.push(`callable_agents: cannot include self ('${a}')`);
+            }
+            if (seen.has(a)) {
+                errors.push(`callable_agents: duplicate '${a}'`);
+            }
+            seen.add(a);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors: Object.freeze(errors) };
+    }
+    return { ok: true };
+}
+/**
+ * Serialize a manifest back to canonical YAML. Round-trip stable:
+ * parseAgentYaml(serializeAgentYaml(m)).manifest deep-equals m.
+ */
+export function serializeAgentYaml(manifest) {
+    const out = [];
+    out.push(`name: ${quotePlain(manifest.name)}`);
+    out.push(`version: ${manifest.version}`);
+    if (manifest.model !== undefined) {
+        out.push(`model: ${quotePlain(manifest.model)}`);
+    }
+    if (manifest.systemPrompt !== undefined) {
+        if (manifest.systemPrompt.includes("\n")) {
+            out.push(`system_prompt: |`);
+            for (const ln of manifest.systemPrompt.replace(/\n+$/, "").split("\n")) {
+                out.push(`  ${ln}`);
+            }
+        }
+        else {
+            out.push(`system_prompt: ${quotePlain(manifest.systemPrompt)}`);
+        }
+    }
+    if (manifest.tools && manifest.tools.length > 0) {
+        out.push(`tools:`);
+        for (const t of manifest.tools)
+            out.push(`  - ${quotePlain(t)}`);
+    }
+    if (manifest.mcpServers && manifest.mcpServers.length > 0) {
+        out.push(`mcp_servers:`);
+        for (const s of manifest.mcpServers) {
+            out.push(`  - name: ${quotePlain(s.name)}`);
+            out.push(`    transport: ${s.transport}`);
+            if (s.command !== undefined)
+                out.push(`    command: ${quotePlain(s.command)}`);
+            if (s.url !== undefined)
+                out.push(`    url: ${quotePlain(s.url)}`);
+            if (s.args && s.args.length > 0) {
+                out.push(`    args:`);
+                for (const a of s.args)
+                    out.push(`      - ${quotePlain(a)}`);
+            }
+        }
+    }
+    if (manifest.callableAgents && manifest.callableAgents.length > 0) {
+        out.push(`callable_agents:`);
+        for (const c of manifest.callableAgents)
+            out.push(`  - ${quotePlain(c)}`);
+    }
+    if (manifest.skills && manifest.skills.length > 0) {
+        out.push(`skills:`);
+        for (const sk of manifest.skills) {
+            if (sk.fromPlugin !== undefined && sk.inline === undefined) {
+                out.push(`  - from_plugin: ${quotePlain(sk.fromPlugin)}`);
+            }
+            else if (sk.inline !== undefined && sk.fromPlugin === undefined) {
+                out.push(`  - inline: ${quotePlain(sk.inline)}`);
+            }
+            else {
+                out.push(`  -`);
+                if (sk.fromPlugin !== undefined)
+                    out.push(`    from_plugin: ${quotePlain(sk.fromPlugin)}`);
+                if (sk.inline !== undefined)
+                    out.push(`    inline: ${quotePlain(sk.inline)}`);
+            }
+        }
+    }
+    if (manifest.steeringExamples && manifest.steeringExamples.length > 0) {
+        out.push(`steering_examples:`);
+        for (const ex of manifest.steeringExamples) {
+            out.push(`  - input: ${quotePlain(ex.input)}`);
+            out.push(`    output: ${quotePlain(ex.output)}`);
+            if (ex.tags && ex.tags.length > 0) {
+                out.push(`    tags:`);
+                for (const t of ex.tags)
+                    out.push(`      - ${quotePlain(t)}`);
+            }
+        }
+    }
+    return out.join("\n") + "\n";
+}
+function quotePlain(s) {
+    if (s === "")
+        return '""';
+    if (/[:#\n\r\t"'\\]/.test(s))
+        return JSON.stringify(s);
+    if (/^[\s-]/.test(s) || /\s$/.test(s))
+        return JSON.stringify(s);
+    if (s === "true" || s === "false" || s === "null" || s === "~")
+        return JSON.stringify(s);
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return JSON.stringify(s);
+    return s;
+}
+export function buildSteeringPrompt(manifest, userQuery, opts = {}) {
+    const k = opts.k ?? 3;
+    const minScore = opts.minScore ?? 0;
+    const sysPrompt = manifest.systemPrompt ?? "";
+    const examples = manifest.steeringExamples ?? [];
+    const ranked = rankExamplesByQuery(examples, userQuery);
+    const picked = ranked.filter((r) => r.score >= minScore).slice(0, k);
+    const sections = [];
+    if (sysPrompt !== "")
+        sections.push(sysPrompt);
+    if (picked.length > 0) {
+        const lines = ["Examples:"];
+        for (const { example } of picked) {
+            lines.push(`Input: ${example.input}`);
+            lines.push(`Output: ${example.output}`);
+            lines.push("");
+        }
+        sections.push(lines.join("\n").replace(/\n+$/, ""));
+    }
+    sections.push(`User: ${userQuery}`);
+    return sections.join("\n\n");
+}
+/**
+ * Rank steering examples by Jaccard similarity to the query. Public so
+ * callers (and tests) can inspect ranking decisions.
+ */
+export function rankExamplesByQuery(examples, query) {
+    const indexed = examples.map((example, i) => ({
+        example,
+        score: jaccardScore(query, example.input),
+        i,
+    }));
+    indexed.sort((a, b) => b.score - a.score || a.i - b.i);
+    return Object.freeze(indexed.map(({ example, score }) => ({ example, score })));
+}
+// ── Diff + Merge ─────────────────────────────────────────────────────
+const COMPARABLE_FIELDS = [
+    "name",
+    "version",
+    "model",
+    "systemPrompt",
+    "tools",
+    "mcpServers",
+    "callableAgents",
+    "skills",
+    "steeringExamples",
+];
+/**
+ * Diff two manifests field-by-field. Returns the set of field names
+ * that were added / removed / changed.
+ */
+export function diffManifests(a, b) {
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const f of COMPARABLE_FIELDS) {
+        const av = a[f];
+        const bv = b[f];
+        const aHas = av !== undefined;
+        const bHas = bv !== undefined;
+        if (!aHas && bHas)
+            added.push(f);
+        else if (aHas && !bHas)
+            removed.push(f);
+        else if (aHas && bHas && !deepEqual(av, bv))
+            changed.push(f);
+    }
+    return Object.freeze({
+        added: Object.freeze(added),
+        removed: Object.freeze(removed),
+        changed: Object.freeze(changed),
+    });
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        return true;
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        for (const k of ak) {
+            if (!deepEqual(a[k], b[k])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Merge two manifests with override semantics:
+ *   - Scalars (name, version, model, systemPrompt): override wins when defined.
+ *   - Arrays: concat with de-dup. mcp_servers de-dup by name (override
+ *     replaces), other arrays de-dup by JSON-shape.
+ *
+ * Use this for layering a workspace-local agent.yaml over a
+ * plugin-shipped base. The result is deeply frozen.
+ */
+export function mergeManifests(base, override) {
+    const out = {
+        name: override.name ?? base.name,
+        version: 1,
+    };
+    const scalarKey = (k) => {
+        const ov = override[k];
+        const bv = base[k];
+        if (ov !== undefined)
+            out[k] = ov;
+        else if (bv !== undefined)
+            out[k] = bv;
+    };
+    scalarKey("model");
+    scalarKey("systemPrompt");
+    out["tools"] = mergeStringArrays(base.tools, override.tools);
+    out["callableAgents"] = mergeStringArrays(base.callableAgents, override.callableAgents);
+    out["mcpServers"] = mergeByKey(base.mcpServers, override.mcpServers, (s) => s.name);
+    out["skills"] = mergeByJson(base.skills, override.skills);
+    out["steeringExamples"] = mergeByJson(base.steeringExamples, override.steeringExamples);
+    for (const k of ["tools", "callableAgents", "mcpServers", "skills", "steeringExamples"]) {
+        const v = out[k];
+        if (Array.isArray(v) && v.length === 0)
+            delete out[k];
+    }
+    return Object.freeze(out);
+}
+function mergeStringArrays(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const v of a ?? []) {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    }
+    for (const v of b ?? []) {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    }
+    return Object.freeze(out);
+}
+function mergeByKey(a, b, key) {
+    const out = [];
+    const seen = new Map();
+    for (const v of a ?? []) {
+        seen.set(key(v), out.length);
+        out.push(v);
+    }
+    for (const v of b ?? []) {
+        const k = key(v);
+        if (seen.has(k)) {
+            out[seen.get(k)] = v;
+        }
+        else {
+            seen.set(k, out.length);
+            out.push(v);
+        }
+    }
+    return Object.freeze(out);
+}
+function mergeByJson(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const v of a ?? []) {
+        const j = JSON.stringify(v);
+        if (!seen.has(j)) {
+            seen.add(j);
+            out.push(v);
+        }
+    }
+    for (const v of b ?? []) {
+        const j = JSON.stringify(v);
+        if (!seen.has(j)) {
+            seen.add(j);
+            out.push(v);
+        }
+    }
+    return Object.freeze(out);
+}
+//# sourceMappingURL=yaml-manifest.js.map