aontu 0.52.0 → 0.53.0

package/dist/mcp.js

@@ -0,0 +1,814 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_PROTOCOL = void 0;
+exports.servedTrust = servedTrust;
+exports.confinedParseFailure = confinedParseFailure;
+exports.toolList = toolList;
+exports.callTool = callTool;
+exports.serverInstructions = serverInstructions;
+exports.handle = handle;
+exports.parseError = parseError;
+// THE MCP TOOL LIBRARY (G7 phase 6,
+// docs/capability-review/g7-machine-access.md; completed to the full
+// CLI verb surface by the use-case review's MCP recommendation,
+// use-cases/SUPPORT.md): the verbs an agent calls, over the Model
+// Context Protocol, as a transport-free library. The split follows
+// the LSP's (docs/lsp.md): this file is the protocol and the tools,
+// ts/src/mcp-server.ts is stdio and nothing else, and the whole thing
+// is testable without a socket.
+//
+// Every tool returns THE SAME JSON CONTRACT THE CLI PRINTS. That is
+// the point of the surface: an agent that has read `aontu vet
+// --format json` output knows what the `vet` tool answers, and a
+// report copied from one to the other is the same object. The tools
+// add no vocabulary of their own.
+//
+// The server evaluates under a CONFINED resolver (G5, docs/trust.md):
+// a caller hands source text, and text that could reach out through
+// `@"..."` is exactly what a server must not run unconfined. By
+// default every include is denied; a server started with
+// `--root <dir>` (ts/src/mcp-server.ts) resolves includes confined
+// below that root instead — the CLI's `--trust root:<dir>` posture —
+// and lets every document argument arrive as a `<name>Path` file
+// under the same root. The package-resolver leg is never enabled
+// here.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const aontu_1 = require("./aontu");
+const vet_1 = require("./vet");
+const query_1 = require("./query");
+const diff_1 = require("./diff");
+const hcanon_1 = require("./hcanon");
+const keyorder_1 = require("./keyorder");
+const subsume_1 = require("./subsume");
+const trim_1 = require("./trim");
+const jsonschema_1 = require("./jsonschema");
+const relation_1 = require("./relation");
+const reach_1 = require("./reach");
+const patch_1 = require("./patch");
+exports.MCP_PROTOCOL = '2024-11-05';
+// JSON-RPC's own codes, the three a server this small can raise.
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+// The trust profile a served evaluation runs under: no includes at
+// all — or, when the server was started with --root, includes
+// realpath-confined below that root (the CLI's `--trust root:<dir>`
+// semantics; docs/trust.md). The package-resolver leg is enabled by
+// neither.
+//
+// The profile is INJECTED into every tool by callTool rather than
+// applied by each tool for itself. That is deliberate: four of the six
+// original tools once called the library with no profile at all, so a
+// served `@"x.js"` was require()d in the server process, while the
+// module header claimed confinement. A tool that must remember to
+// confine itself is a tool that eventually forgets, and the forgetting
+// is silent. With the profile arriving as an argument, a tool cannot
+// run unconfined without visibly discarding it.
+function servedTrust(root) {
+    return null == root
+        ? { include: 'none' }
+        : { include: { root } };
+}
+function served(trust) {
+    return new aontu_1.Aontu({ trust });
+}
+// DOES THIS DOCUMENT STAND UP UNDER THE SERVED PROFILE — or the
+// finding that says why not. This is the confinement gate for the
+// engines that take no trust profile, and parse is the whole include
+// story: `@"..."` resolves at parse time (ts/src/lang.ts), so a
+// document whose confined parse is clean either has no includes at
+// all (capability 'none') or resolves every one below the root — and
+// an engine that then re-resolves the same closure under the default
+// profile reads exactly the files the confined parse proved in
+// bounds. A parse that fails for any reason refuses the call: an
+// engine's own answer for a document this profile cannot read is not
+// an answer this server may compute.
+function confinedParseFailure(src, trust, path) {
+    const aontu = served(trust);
+    const ctx = aontu.ctx({ collect: true });
+    aontu.parse(src, null == path ? undefined : { path }, ctx);
+    return 0 < ctx.err.length ? (0, query_1.evalFailure)(ctx) : undefined;
+}
+// Confinement is realpath-then-prefix-check, mirroring the include
+// resolver's own rule (ts/src/lang.ts, docs/trust.md): the file's
+// real path must sit below the root's real path, so a symlink inside
+// the root pointing outside it is an escape, not a loophole.
+//
+// A path that does not (fully) exist cannot be realpath'd whole, and
+// falling back to the LEXICAL form compares apples to oranges when the
+// root itself sits behind a symlink -- on macOS a root under /var
+// realpaths to /private/var, so a merely-missing file inside it read
+// as an escape instead of "cannot read" (the CI failure that bought
+// this comment). Realpath the deepest EXISTING ancestor and re-attach
+// the rest, so both sides of the prefix check are in real coordinates.
+function realpathOf(p) {
+    try {
+        return (0, node_fs_1.realpathSync)(p);
+    }
+    catch {
+        const parent = (0, node_path_1.dirname)(p);
+        if (parent === p) {
+            return p;
+        }
+        return (0, node_path_1.join)(realpathOf(parent), (0, node_path_1.basename)(p));
+    }
+}
+function outsideRoot(root, full) {
+    const rootReal = realpathOf(root);
+    const fullReal = realpathOf(full);
+    return fullReal !== rootReal && !fullReal.startsWith(rootReal + node_path_1.sep);
+}
+const TOOLS = [
+    {
+        name: 'vet',
+        description: 'Validate a data document against a schema document. Returns the ' +
+            'vet report: verdict (valid | invalid | incomplete | error), and ' +
+            'findings with codes, paths, sites and a repair hint. A site ' +
+            'names the file whose text it excerpts, so its row and column ' +
+            'are safe to edit at even when the schema loads other files.',
+        properties: {
+            schema: { type: 'string', description: 'The schema document' },
+            data: { type: 'string', description: 'The data document' },
+            at: { type: 'string', description: 'Validate at this path ($.a.b)' },
+        },
+        required: ['schema', 'data'],
+        docs: ['schema', 'data'],
+        run: (a, trust, paths) => (0, vet_1.vet)(str(a.schema), str(a.data), {
+            ...(null == a.at ? {} : { at: str(a.at) }),
+            schemaPath: paths.schema,
+            dataPath: paths.data,
+            schemaUrl: paths.schema,
+            dataUrl: paths.data,
+            trust,
+        }),
+    },
+    {
+        name: 'get',
+        description: 'Select one node of an evaluated document by path and render it: ' +
+            'generated JSON by default, or the canon, types, keys or ' +
+            'depth-elided view. A view other than json is a valid Aontu ' +
+            'document that subsumes the truth it summarises.',
+        properties: {
+            src: { type: 'string', description: 'The document' },
+            path: { type: 'string', description: 'The path ($.a.b)' },
+            view: {
+                type: 'string',
+                description: 'json (default), canon, types or keys',
+            },
+            depth: {
+                type: 'number',
+                description: 'Structure to this depth; deeper nodes render as top',
+            },
+        },
+        required: ['src', 'path'],
+        docs: ['src'],
+        run: (a, trust, paths) => (0, query_1.get)(str(a.src), str(a.path), {
+            view: a.view,
+            depth: 'number' === typeof a.depth ? a.depth : undefined,
+            path: paths.src,
+            trust,
+        }),
+    },
+    {
+        name: 'why',
+        description: 'Explain the value at a path: every contribution that met there, ' +
+            'in source order, with its role (literal, spread, ref, pref) and ' +
+            'the site it was written at.',
+        properties: {
+            src: { type: 'string', description: 'The document' },
+            path: { type: 'string', description: 'The path ($.a.b)' },
+        },
+        required: ['src', 'path'],
+        docs: ['src'],
+        run: (a, trust, paths) => (0, query_1.why)(str(a.src), str(a.path), { path: paths.src, trust }),
+    },
+    {
+        name: 'diff',
+        description: 'What changed, at which paths, between two documents. Compares ' +
+            'the hash form, so reformatting is not a change and closing a ' +
+            'map is. Whether a change is BREAKING is the breaking verb\'s ' +
+            'question, not this one.',
+        properties: {
+            left: { type: 'string', description: 'The earlier document' },
+            right: { type: 'string', description: 'The later document' },
+            at: { type: 'string', description: 'Compare at this path ($.a.b)' },
+        },
+        required: ['left', 'right'],
+        docs: ['left', 'right'],
+        run: (a, trust, paths) => (0, diff_1.diff)(str(a.left), str(a.right), {
+            ...(null == a.at ? {} : { at: str(a.at) }),
+            leftPath: paths.left,
+            rightPath: paths.right,
+            trust,
+        }),
+    },
+    {
+        name: 'canon',
+        description: 'Normalise a document to its canonical form: the deterministic ' +
+            'text two documents that mean the same thing share.',
+        properties: {
+            src: { type: 'string', description: 'The document' },
+        },
+        required: ['src'],
+        docs: ['src'],
+        run: (a, trust, paths) => canonOf(str(a.src), trust, paths.src),
+    },
+    {
+        name: 'summary',
+        description: 'A document at a glance: its canon-hash pin, its root keys, and ' +
+            'the shape of its top tier. The first tier of progressive ' +
+            'disclosure — expand by calling get with a path.',
+        properties: {
+            src: { type: 'string', description: 'The document' },
+        },
+        required: ['src'],
+        docs: ['src'],
+        run: (a, trust, paths) => summaryOf(str(a.src), trust, paths.src),
+    },
+    // The evolution and change verbs (the use-case review's "MCP is a
+    // read-only subset" gap, use-cases/09-agent-tools/README.md gap 11).
+    {
+        name: 'subsume',
+        description: 'Does the general document admit every instance the specific ' +
+            'one admits? Returns the subsume report: verdict (subsumes | ' +
+            'does_not_subsume | undecided | error) and compat findings, ' +
+            'each with a witness at the path that narrowed.',
+        properties: {
+            general: { type: 'string', description: 'The general document' },
+            specific: { type: 'string', description: 'The specific document' },
+            profile: {
+                type: 'string',
+                description: 'values, defaults (default) or gen',
+            },
+            at: { type: 'string', description: 'Compare at this path ($.a.b)' },
+        },
+        required: ['general', 'specific'],
+        docs: ['general', 'specific'],
+        check: (a) => null == a.profile || 'values' === a.profile ||
+            'defaults' === a.profile || 'gen' === a.profile
+            ? undefined : 'profile needs values, defaults or gen',
+        refuse: (_a, finding) => ({ verdict: 'error', findings: [finding] }),
+        run: (a, _trust, paths) => (0, subsume_1.subsume)(str(a.general), str(a.specific), {
+            ...(null == a.profile ? {} : { profile: a.profile }),
+            ...(null == a.at ? {} : { at: str(a.at) }),
+            generalUrl: paths.general,
+            specificUrl: paths.specific,
+            generalPath: paths.general,
+            specificPath: paths.specific,
+        }),
+    },
+    {
+        name: 'breaking',
+        description: 'Is the new version of a document a breaking change against the ' +
+            'old one? Wraps subsume in the CLI\'s policy logic: the mode ' +
+            'argument, else the document\'s own $.aontu_policy.compat, else ' +
+            'backward. Returns verdict (compatible | breaking | undecided | ' +
+            'error), the mode checked, and the findings.',
+        properties: {
+            old: { type: 'string', description: 'The old (published) version' },
+            new: { type: 'string', description: 'The new (proposed) version' },
+            mode: {
+                type: 'string',
+                description: 'backward, forward or full; overrides the ' +
+                    'document\'s own $.aontu_policy.compat declaration',
+            },
+        },
+        required: ['old', 'new'],
+        docs: ['old', 'new'],
+        check: (a) => null == a.mode || 'backward' === a.mode ||
+            'forward' === a.mode || 'full' === a.mode
+            ? undefined : 'mode needs backward, forward or full',
+        refuse: (a, finding, trust, paths) => ({
+            verdict: 'error',
+            mode: breakingMode(a, trust, paths),
+            findings: [finding],
+        }),
+        run: (a, trust, paths) => breakingOf(a, trust, paths),
+    },
+    {
+        name: 'set',
+        description: 'Change values by appending to an overlay document (or, with ' +
+            'inPlace, rewriting a pinned literal where that is provably ' +
+            'safe). Returns the vet-class report plus the NEW OVERLAY TEXT: ' +
+            'this server never writes files, so the caller owns the write.',
+        properties: {
+            entry: {
+                type: 'string',
+                description: 'The entry document (the truth the overlay must ' +
+                    'hold against)',
+            },
+            overlay: {
+                type: 'string',
+                description: 'The overlay document as it stands (may be empty)',
+            },
+            assignments: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'The path ($.a.b)' },
+                        value: {
+                            type: 'string',
+                            description: 'The value, as Aontu source text',
+                        },
+                    },
+                    required: ['path', 'value'],
+                },
+                description: 'The assignments to apply, in order',
+            },
+            inPlace: {
+                type: 'boolean',
+                description: 'Rewrite a pinned literal where it was written, ' +
+                    'where provably safe; otherwise append as usual',
+            },
+        },
+        required: ['entry', 'overlay', 'assignments'],
+        docs: ['entry', 'overlay'],
+        check: checkAssignments,
+        refuse: (a, finding) => setError(str(a.overlay), finding),
+        run: (a, trust, paths) => setOf(a, trust, paths),
+    },
+    {
+        name: 'relations',
+        description: 'Check the declared relations of a finished model: acyclicity ' +
+            'and inverse consistency over the entity edge set. Returns ' +
+            'verdict (pass | fail | error) and relation findings.',
+        properties: {
+            source: { type: 'string', description: 'The document' },
+        },
+        required: ['source'],
+        docs: ['source'],
+        // The pre-parse finding rides `errors`, exactly where the engine
+        // puts its own reason for a document that does not stand up
+        // (ts/src/relation.ts, the review's finding F). NOT `findings`:
+        // RelationFinding is its own vocabulary (code, relation, at,
+        // detail) and a document with no graph has no graph findings.
+        refuse: (_a, finding) => ({ verdict: 'error', findings: [], errors: [finding] }),
+        run: (a, _trust, paths) => (0, relation_1.relationCheck)(str(a.source), { path: paths.source }),
+    },
+    {
+        name: 'reaches',
+        description: 'Ask whether one entity reaches another over the entity graph, ' +
+            'at any remove — the closure question `relations` cannot ask one ' +
+            'edge at a time (blast radius, containment). Returns verdict ' +
+            '(reaches | unreachable | error) and, when it reaches, a shortest ' +
+            'path. Transitive, not reflexive: an entity reaches itself only ' +
+            'through a cycle.',
+        properties: {
+            source: { type: 'string', description: 'The document' },
+            from: { type: 'string', description: 'The entity to start at' },
+            to: { type: 'string', description: 'The entity to look for' },
+            relation: {
+                type: 'string',
+                description: 'Follow only edges under this relation (optional)',
+            },
+        },
+        required: ['source', 'from', 'to'],
+        docs: ['source'],
+        refuse: (_a, finding) => ({ verdict: 'error', errors: [finding] }),
+        run: (a, _trust, paths) => (0, reach_1.reachCheck)(str(a.source), str(a.from), str(a.to), {
+            path: paths.source,
+            relation: null == a.relation ? undefined : str(a.relation),
+        }),
+    },
+    {
+        name: 'hash',
+        description: 'The canon-hash pin of a document: "aon1-" + ' +
+            'base64url(SHA-256(hash form)). Survives reformatting; moves on ' +
+            'any change of meaning. Pass form: true for the hash form text ' +
+            'the pin digests.',
+        properties: {
+            source: { type: 'string', description: 'The document' },
+            form: {
+                type: 'boolean',
+                description: 'Include the hash form text as well',
+            },
+        },
+        required: ['source'],
+        docs: ['source'],
+        run: (a, trust, paths) => hashOf(str(a.source), true === a.form, trust, paths.source),
+    },
+    {
+        name: 'trim',
+        description: 'Report redundant map entries — entries whose removal leaves ' +
+            'the evaluated result unchanged, the spread-implied case ' +
+            'included — as paths. Report-only, the CLI\'s trim --check. ' +
+            'Returns verdict (clean | redundant | error).',
+        properties: {
+            source: { type: 'string', description: 'The document' },
+        },
+        required: ['source'],
+        docs: ['source'],
+        // The pre-parse finding rides `errors`, exactly where the engine
+        // puts its own reason for a document that does not stand up
+        // (ts/src/trim.ts, the review's finding F).
+        refuse: (_a, finding) => ({ verdict: 'error', redundant: [], errors: [finding] }),
+        run: (a, _trust, paths) => (0, trim_1.trimCheck)(str(a.source), { path: paths.source }),
+    },
+    {
+        name: 'jsonschema',
+        description: 'Export a document as a JSON Schema (draft 2020-12), and say ' +
+            'what could not be carried. This is the bridge to a ' +
+            'structured-output API, which constrains generation to JSON ' +
+            'Schema and to nothing else -- and to an MCP tool\'s own ' +
+            'inputSchema, which the protocol requires to be one. Returns ' +
+            'verdict (ok | lossy | error), the schema, and a `lossy` list ' +
+            'naming every construct the schema could not say and what it ' +
+            'says instead. A lossy schema admits MORE than the model does, ' +
+            'so vet the result against the model rather than trusting the ' +
+            'schema alone.',
+        properties: {
+            source: { type: 'string', description: 'The document' },
+            at: {
+                type: 'string',
+                description: 'Export this path of the document ($.a.b)',
+            },
+        },
+        required: ['source'],
+        docs: ['source'],
+        refuse: (_a, finding) => ({ verdict: 'error', schema: {}, lossy: [], errors: [finding] }),
+        run: (a, _trust, paths) => (0, jsonschema_1.jsonSchema)(str(a.source), {
+            at: null == a.at ? undefined : str(a.at), path: paths.source,
+        }),
+    },
+];
+function str(v) {
+    return 'string' === typeof v ? v : '';
+}
+function canonOf(src, trust, path) {
+    const aontu = served(trust);
+    const ctx = aontu.ctx({ collect: true });
+    const v = aontu.unify(src, null == path ? undefined : { path }, ctx);
+    if (0 < ctx.err.length) {
+        return { ok: false, canon: '', findings: [(0, query_1.evalFailure)(ctx)] };
+    }
+    return { ok: true, canon: v.canon, findings: [] };
+}
+function summaryOf(src, trust, path) {
+    const aontu = served(trust);
+    const ctx = aontu.ctx({ collect: true });
+    const v = aontu.unify(src, null == path ? undefined : { path }, ctx);
+    if (0 < ctx.err.length) {
+        return {
+            ok: false, hash: '', keys: [], shape: '', findings: [(0, query_1.evalFailure)(ctx)],
+        };
+    }
+    const keys = true === v.isMap ? Object.keys(v.peg).sort(keyorder_1.cmpCodePoint) : [];
+    return {
+        ok: true,
+        hash: (0, hcanon_1.canonHash)(v),
+        keys,
+        // The top tier only: every key, with its subtree elided to `top`.
+        shape: (0, query_1.get)(src, '$', { view: 'types', depth: 2, path, trust }).out,
+        findings: [],
+    };
+}
+// The pin, computed under the served profile — this engine is the
+// evaluation itself, so the profile rides in directly and no pre-parse
+// is needed. The error answer follows canonOf's shape; the CLI prints
+// nothing but a message there (ts/src/cli.ts runHash), so this shape
+// is the served superset of it.
+function hashOf(src, form, trust, path) {
+    const aontu = served(trust);
+    const ctx = aontu.ctx({ collect: true });
+    const v = aontu.unify(src, null == path ? undefined : { path }, ctx);
+    if (0 < ctx.err.length || null == v || true === v.isNil) {
+        return { ok: false, hash: '', findings: [(0, query_1.evalFailure)(ctx)] };
+    }
+    return {
+        ok: true,
+        hash: (0, hcanon_1.canonHash)(v),
+        ...(form ? { form: (0, hcanon_1.hcanon)(v) } : {}),
+        findings: [],
+    };
+}
+// Verdict aggregation: an error anywhere makes the run an error;
+// otherwise a witness anywhere makes it breaking; otherwise an open
+// question anywhere leaves it undecided.
+const BREAKING_RANK = {
+    subsumes: 0,
+    undecided: 1,
+    does_not_subsume: 2,
+    error: 3,
+};
+const BREAKING_VERDICT = {
+    subsumes: 'compatible',
+    does_not_subsume: 'breaking',
+    undecided: 'undecided',
+    error: 'error',
+};
+// The document's own compatibility declaration: `$.aontu_policy.compat`,
+// a disjunction whose default is the declared mode. Undefined when the
+// key is absent or does not spell a mode. The one departure from the
+// cli.ts original: the read runs CONFINED, because here the document
+// came from a caller.
+function policyCompatOf(newSrc, trust, path) {
+    const aontu = served(trust);
+    const ctx = aontu.ctx({ collect: true });
+    const v = aontu.unify(newSrc, null == path ? undefined : { path }, ctx);
+    if (0 < ctx.err.length || true === v?.isNil) {
+        return undefined;
+    }
+    let compat = v?.peg?.aontu_policy?.peg?.compat;
+    if (null == compat) {
+        return undefined;
+    }
+    if (true === compat.isDisjunct && Array.isArray(compat.peg)) {
+        compat = compat.peg.find((m) => true === m?.isPref) ?? compat.peg[0];
+    }
+    if (true === compat.isPref) {
+        compat = compat.peg;
+    }
+    const m = true === compat?.isString ? compat.peg : undefined;
+    return 'backward' === m || 'forward' === m || 'full' === m || 'none' === m
+        ? m : undefined;
+}
+// The declared mode: the mode argument overrides the document's own
+// policy; neither means backward (v1-valid documents stay valid).
+function breakingMode(a, trust, paths) {
+    return a.mode ?? policyCompatOf(str(a.new), trust, paths.new) ?? 'backward';
+}
+function breakingOf(a, trust, paths) {
+    const mode = breakingMode(a, trust, paths);
+    if ('none' === mode) {
+        // The document declares no compatibility promise: nothing to check.
+        return { verdict: 'compatible', mode, findings: [] };
+    }
+    const sides = {
+        old: { src: str(a.old), url: paths.old ?? 'old', path: paths.old },
+        new: { src: str(a.new), url: paths.new ?? 'new', path: paths.new },
+    };
+    // backward: the NEW document is the general side — every old
+    // instance must still be admitted. forward: the old one is.
+    const checks = [];
+    if ('backward' === mode || 'full' === mode) {
+        checks.push({ general: sides.new, specific: sides.old });
+    }
+    if ('forward' === mode || 'full' === mode) {
+        checks.push({ general: sides.old, specific: sides.new });
+    }
+    let worst = 'subsumes';
+    const findings = [];
+    for (const check of checks) {
+        const report = (0, subsume_1.subsume)(check.general.src, check.specific.src, {
+            generalUrl: check.general.url,
+            specificUrl: check.specific.url,
+            generalPath: check.general.path,
+            specificPath: check.specific.path,
+        });
+        if (BREAKING_RANK[worst] < BREAKING_RANK[report.verdict]) {
+            worst = report.verdict;
+        }
+        findings.push(...report.findings);
+    }
+    return { verdict: BREAKING_VERDICT[worst], mode, findings };
+}
+// ---------------------------------------------------------------------
+// The set tool: the CLI's `set` verb minus the filesystem — the patch
+// engine (ts/src/patch.ts) already answers with the new overlay text,
+// and the caller owns the write.
+// The assignments arrive structured ({path, value}) rather than as the
+// CLI's `<path>=<value>` spelling, and are re-joined for the engine's
+// parseAssignment — so the path must not smuggle a `=` that would move
+// the split.
+function checkAssignments(a) {
+    if (0 === a.assignments.length) {
+        return 'assignments needs at least one {path, value}';
+    }
+    for (const x of a.assignments) {
+        if ('string' !== typeof x?.path || '' === x.path.trim() ||
+            'string' !== typeof x?.value || '' === x.value.trim()) {
+            return 'each assignment needs a path and a value, both strings';
+        }
+        if (x.path.includes('=')) {
+            return `assignment path may not contain "=": ${x.path}`;
+        }
+    }
+    return undefined;
+}
+function setError(overlay, finding) {
+    return {
+        overlay,
+        appended: [],
+        replaced: [],
+        verdict: 'error',
+        findings: [finding],
+    };
+}
+function setOf(a, trust, paths) {
+    // THE ASSIGNMENT VALUES ARE DOCUMENTS TOO: each one is appended (or
+    // spliced) into the overlay and evaluated there by the engine's
+    // final vet, so a value that smuggles an include — or a newline and
+    // then an include — gets the same confined pre-parse as the
+    // documents themselves, wrapped exactly as the engine's own
+    // spanValue wraps a fragment (ts/src/patch.ts).
+    for (const x of a.assignments) {
+        const denied = confinedParseFailure('v: ' + x.value, trust, paths.overlay);
+        if (null != denied) {
+            return setError(str(a.overlay), denied);
+        }
+    }
+    return (0, patch_1.patch)(str(a.entry), str(a.overlay), a.assignments.map((x) => x.path + '=' + x.value), {
+        entryPath: paths.entry,
+        overlayPath: paths.overlay,
+        inPlace: true === a.inPlace,
+    });
+}
+// ---------------------------------------------------------------------
+// The tool list as MCP spells it: a name, a description, and a JSON
+// Schema for the arguments. With a served root, every document
+// property gains its `<name>Path` file alternative — and comes OFF the
+// `required` list, because JSON Schema's `required` cannot say "one of
+// the two"; callTool's own argument check still refuses a call that
+// carries neither.
+function toolList(root) {
+    return TOOLS.map((t) => {
+        const properties = { ...t.properties };
+        let required = t.required;
+        if (null != root && null != t.docs) {
+            for (const doc of t.docs) {
+                properties[doc + 'Path'] = {
+                    type: 'string',
+                    description: `File below the server's --root, read as ` +
+                        `\`${doc}\`; an alternative to inline \`${doc}\` text`,
+                };
+            }
+            required = t.required.filter((r) => !t.docs.includes(r));
+        }
+        return {
+            name: t.name,
+            description: t.description,
+            inputSchema: {
+                type: 'object',
+                properties,
+                required,
+            },
+        };
+    });
+}
+function refusal(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+// One tool call. A tool that REFUSES (an invalid document, a path that
+// names nothing, a document the served profile cannot read) is not a
+// protocol error: it answers with its own report and `isError` false,
+// because the report IS the answer the agent asked for. `isError` is
+// reserved for a call that could not be made at all — an unknown tool,
+// a missing or malformed argument, a file argument the server cannot
+// serve.
+// `opts.tools` is injectable for the same reason the watch loop's
+// waiter is: the catch below is defensive code no document reaches --
+// every verb answers with a report rather than throwing -- and code
+// the suite cannot execute is code the ADR-002 floor cannot hold.
+function callTool(name, args, opts) {
+    const root = opts?.root;
+    const tools = opts?.tools ?? TOOLS;
+    const tool = tools.find((t) => t.name === name);
+    if (null == tool) {
+        return refusal(`no such tool: ${name}`);
+    }
+    const a = { ...(args ?? {}) };
+    const paths = {};
+    // THE FILE ALTERNATIVES (--root). A document that did not arrive as
+    // inline text may arrive as a `<name>Path` file — served only when
+    // the operator granted a root at startup, confined below it by the
+    // same realpath rule the include resolver applies, and recorded in
+    // `paths` so the engine resolves the file's own relative includes
+    // from its directory (the CLI's rule for a named file). Inline text
+    // wins when a caller sends both.
+    for (const doc of tool.docs ?? []) {
+        if ('string' === typeof a[doc]) {
+            continue;
+        }
+        const rel = a[doc + 'Path'];
+        if ('string' !== typeof rel) {
+            continue;
+        }
+        if (null == root) {
+            return refusal(`tool ${name}: ${doc}Path needs a server started with ` +
+                `--root <dir>; pass ${doc} as document text instead`);
+        }
+        const full = (0, node_path_1.resolve)(root, rel);
+        if (outsideRoot(root, full)) {
+            return refusal(`tool ${name}: ${doc}Path escapes the server root: ${rel}`);
+        }
+        try {
+            a[doc] = (0, node_fs_1.readFileSync)(full, 'utf8');
+        }
+        catch (e) {
+            return refusal(`tool ${name}: cannot read ${doc}Path ${rel}: ${e?.message ?? e}`);
+        }
+        paths[doc] = full;
+    }
+    for (const req of tool.required) {
+        const kind = tool.properties[req]?.type;
+        const okv = 'array' === kind
+            ? Array.isArray(a[req])
+            : 'string' === typeof a[req];
+        if (!okv) {
+            const alt = null != root && (tool.docs ?? []).includes(req)
+                ? ` (or ${req}Path)` : '';
+            return refusal(`tool ${name} needs ${'array' === kind ? 'an array' : 'a string'}` +
+                ` argument: ${req}${alt}`);
+        }
+    }
+    const bad = null == tool.check ? undefined : tool.check(a);
+    if (null != bad) {
+        return refusal(`tool ${name}: ${bad}`);
+    }
+    // The served profile is supplied HERE, once, for every tool.
+    // A tool never chooses its own confinement.
+    const trust = servedTrust(root);
+    let out;
+    try {
+        // The confined pre-parse, for the engines that cannot take the
+        // profile themselves (see ToolDef.refuse).
+        if (null != tool.refuse) {
+            for (const doc of tool.docs ?? []) {
+                if ('string' !== typeof a[doc]) {
+                    continue;
+                }
+                const denied = confinedParseFailure(a[doc], trust, paths[doc]);
+                if (null != denied) {
+                    out = tool.refuse(a, denied, trust, paths);
+                    break;
+                }
+            }
+        }
+        if (undefined === out) {
+            out = tool.run(a, trust, paths);
+        }
+    }
+    catch (e) {
+        // A tool that throws is a call that could not be made, which is
+        // what isError means -- and it must not take the server process
+        // down with it: a stdio server serves one client for a whole
+        // session, so an unhandled throw on one document loses every
+        // later call too.
+        return refusal(`tool ${name} failed: ${e?.message ?? e}`);
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        isError: false,
+    };
+}
+// What a connecting client is told once, at the handshake: which
+// confinement mode this server is in. The --root capability is a
+// startup grant, not a per-call negotiation, so initialize is where a
+// caller learns whether `<name>Path` arguments are served.
+function serverInstructions(root) {
+    return 'Aontu tools take document TEXT arguments and answer the ' +
+        'same JSON reports the aontu CLI prints with --format json. ' +
+        (null == root
+            ? 'Evaluation is confined: includes (@"...") are denied, and ' +
+                'file-path arguments (schemaPath, srcPath, sourcePath, ...) ' +
+                'are refused. Start the server with --root <dir> to serve ' +
+                'both, confined below that directory.'
+            : `This server was started with --root ${root}: every document ` +
+                'argument also accepts a <name>Path alternative naming a file ' +
+                'below that root, and includes (@"...") resolve confined to it.');
+}
+// Handle one JSON-RPC message. Returns undefined for a NOTIFICATION
+// (no id): MCP sends `notifications/initialized`, and answering a
+// notification is a protocol error in the other direction.
+function handle(msg, version, root) {
+    const id = msg.id ?? null;
+    if (null == msg.id) {
+        return undefined;
+    }
+    switch (msg.method) {
+        case 'initialize':
+            return ok(id, {
+                protocolVersion: exports.MCP_PROTOCOL,
+                capabilities: { tools: {} },
+                serverInfo: { name: 'aontu', version },
+                instructions: serverInstructions(root),
+            });
+        case 'ping':
+            return ok(id, {});
+        case 'tools/list':
+            return ok(id, { tools: toolList(root) });
+        case 'tools/call': {
+            const name = msg.params?.name;
+            if ('string' !== typeof name) {
+                return err(id, INVALID_PARAMS, 'tools/call needs a tool name');
+            }
+            return ok(id, callTool(name, msg.params?.arguments ?? {}, { root }));
+        }
+        default:
+            return err(id, METHOD_NOT_FOUND, `no such method: ${msg.method}`);
+    }
+}
+// A message that did not decode at all.
+function parseError() {
+    return err(null, PARSE_ERROR, 'invalid JSON');
+}
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function err(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+//# sourceMappingURL=mcp.js.map