ue-mcp 1.3.0 → 1.3.1-beta.2

package/dist/action-schema.js

@@ -0,0 +1,731 @@
+import { classifyActionClass } from "./action-class.js";
+function defOf(schema) {
+    return schema._def ?? {};
+}
+/**
+ * Peel the wrappers that only change optionality, keeping the first
+ * description and default found on the way in. The description belongs to
+ * whichever wrapper `.describe()` was called on, which for the prevailing
+ * `z.string().optional().describe(...)` spelling is the outer one.
+ */
+function unwrap(schema) {
+    let cur = schema;
+    let optional = false;
+    let description = cur.description;
+    let dflt;
+    // Bounded: the wrapper chains in this codebase are two or three deep, and a
+    // cycle would otherwise hang the server rather than fail a call.
+    for (let i = 0; i < 16; i++) {
+        const def = defOf(cur);
+        const name = def.typeName;
+        if (name === "ZodOptional" || name === "ZodNullable") {
+            optional = true;
+        }
+        else if (name === "ZodDefault") {
+            optional = true;
+            if (dflt === undefined && typeof def.defaultValue === "function")
+                dflt = def.defaultValue();
+        }
+        else if (name !== "ZodEffects" && name !== "ZodBranded" && name !== "ZodReadonly") {
+            break;
+        }
+        const next = def.innerType ?? def.schema;
+        if (!next)
+            break;
+        cur = next;
+        description = description ?? cur.description;
+    }
+    return { inner: cur, optional, description, default: dflt };
+}
+/** A short, agent-readable name for a zod type. */
+function typeName(schema) {
+    const def = defOf(schema);
+    switch (def.typeName) {
+        case "ZodString": return "string";
+        case "ZodNumber": return "number";
+        case "ZodBoolean": return "boolean";
+        case "ZodUnknown":
+        case "ZodAny": return "any";
+        case "ZodEnum": return "enum";
+        case "ZodLiteral": return "literal";
+        case "ZodRecord": return "object";
+        case "ZodObject": return "object";
+        case "ZodArray": {
+            const el = def.type;
+            return el ? `${typeName(unwrap(el).inner)}[]` : "array";
+        }
+        case "ZodUnion": {
+            const opts = def.options ?? [];
+            const names = [...new Set(opts.map((o) => typeName(unwrap(o).inner)))];
+            return names.join("|") || "union";
+        }
+        default: return def.typeName ? def.typeName.replace(/^Zod/, "").toLowerCase() : "unknown";
+    }
+}
+/** Allowed values for an enum, or a union made entirely of string literals. */
+function enumValues(schema) {
+    const def = defOf(schema);
+    if (def.typeName === "ZodEnum" && Array.isArray(def.values)) {
+        return def.values.map((v) => String(v));
+    }
+    if (def.typeName === "ZodUnion" && Array.isArray(def.options)) {
+        const literals = [];
+        for (const opt of def.options) {
+            const od = defOf(unwrap(opt).inner);
+            if (od.typeName !== "ZodLiteral")
+                return undefined;
+            literals.push(String(od.value));
+        }
+        return literals.length > 0 ? literals : undefined;
+    }
+    return undefined;
+}
+/**
+ * The grammar of a `Params:` clause, as the descriptions in this repo actually
+ * write it rather than as one might wish they did.
+ *
+ * The clause is a list of ITEMS separated by `,` or `;` at bracket depth zero.
+ * Each item names one parameter and then, optionally, commentary. Inside an
+ * item the names are joined by separators:
+ *
+ *   OR or | either   a choice: supply one side, not both
+ *   and/or           a choice where more than one side is also allowed
+ *   + with plus      a conjunction: the names go together in one branch
+ *   /                two spellings, or two keys, of the same idea
+ *
+ * An item may open with a quantifier (`at least one of`, `exactly one of`),
+ * which makes the names behind it a choice, or with a connective (`plus`,
+ * `then`, `EITHER`) continuing the previous item.
+ *
+ * Everything else at depth zero ends the item, because the prose has resumed:
+ * a bare word that is not a separator (`renames[] where each entry is ...`),
+ * or a character that cannot start a name (`all=true`, `- uses its agent`).
+ *
+ * The rule that matters most is what is NOT here. There is no list of English
+ * words that are refused in parameter position. `value`, `all`, `from`, `to`,
+ * `min`, `max` and `name` are real parameters on this surface, and a filter
+ * that reads them as prose deletes a required field from the schema an agent
+ * is handed. Position decides, not vocabulary: the head of an item, and
+ * whatever follows a separator, is a parameter.
+ */
+/** Joins two names into a choice. */
+const CHOICE_WORD = /^(?:or|either)$/i;
+/** Joins two names into one branch of a choice. */
+const JOIN_WORD = /^(?:and|plus|with)$/i;
+/** Opens an item that continues the previous one rather than naming a parameter. */
+const LEAD_WORD = /^(?:or|either|and|plus|with|then|also)$/i;
+/** `at least one of a/b/c`, `exactly one of x/y`, `any one of ...`. */
+const QUANTIFIER = /^\s*(?:at\s+least\s+|exactly\s+|any\s+)?(?:one|two)\s+of\s+/i;
+/**
+ * `Params: none` says the action takes nothing of its own. It is a sentinel,
+ * not a terminator: `paged()` appends `cursor?, limit?` behind it, and those
+ * are real parameters.
+ */
+const NONE_WORD = /^none$/i;
+/**
+ * Commentary that shares a bracket with real parameters, for the case where
+ * the category's declared keys are not to hand to settle it.
+ */
+const BRACKET_PROSE = /^(?:default|defaults|e|g|i|see|note|optional|required|omit|when|flat|legacy|socket)$/i;
+/** Cut a clause at the first match of `stop` that is not inside brackets. */
+function cutAtDepthZero(text, stop) {
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0) {
+            stop.lastIndex = i;
+            const m = stop.exec(text);
+            if (m && m.index === i)
+                return text.slice(0, i);
+        }
+    }
+    return text;
+}
+/** The bracket group opening at `i`, and the index just past its close. */
+function bracketAt(text, i) {
+    let depth = 0;
+    for (let j = i; j < text.length; j++) {
+        const c = text[j];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            depth--;
+            if (depth === 0)
+                return { inner: text.slice(i + 1, j), end: j + 1 };
+        }
+    }
+    return { inner: text.slice(i + 1), end: text.length };
+}
+/** Split on the given separators, ignoring any that sits inside brackets. */
+function splitDepthZero(text, separators) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    let separator = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && separators.includes(c)) {
+            out.push({ text: text.slice(start, i), separator });
+            separator = c;
+            start = i + 1;
+        }
+    }
+    out.push({ text: text.slice(start), separator });
+    return out;
+}
+/** The atoms of a `(+ x?, y?)` group: further parameters, plus commentary. */
+function scanPlusGroup(inner, known) {
+    const out = [];
+    for (const part of splitDepthZero(inner.replace(/^\s*\+/, ""), ",")) {
+        const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)(\[\])?\s*(\?)?/.exec(part.text);
+        if (!m)
+            continue;
+        const accepted = known ? known.has(m[1]) : !BRACKET_PROSE.test(m[1]);
+        if (accepted)
+            out.push({ name: m[1], optional: m[3] === "?" });
+    }
+    return out;
+}
+/**
+ * Read one item of the clause.
+ *
+ * Scans left to right at depth zero, alternating between "a name may appear
+ * here" and "a separator may appear here". The first thing that is neither
+ * ends the item: the rest of it is prose about the parameter, not more
+ * parameters.
+ */
+function scanItem(text, options) {
+    const { known, strict } = options;
+    const branches = [[]];
+    const extra = [];
+    let choice = false;
+    let quantified = false;
+    let expectName = true;
+    let atHead = true;
+    // A head connective (`plus shortcuts:`) is as often the prose resuming as it
+    // is a continuation, so the name behind one has to be a declared key.
+    let headGuarded = false;
+    let rejected = false;
+    // Set once a `+` (or `and`/`plus`/`with`) has joined something into the
+    // current branch. After that a `/` is reading inside the branch rather than
+    // starting a new one: `systemPath + emitterName?/emitterIndex?` is one way
+    // of addressing the emitter, not two ways of addressing the system.
+    let conjoined = false;
+    const branch = () => branches[branches.length - 1];
+    const openBranch = (markChoice) => {
+        if (markChoice)
+            choice = true;
+        if (branch().length > 0)
+            branches.push([]);
+        conjoined = false;
+    };
+    const addAtom = (atom) => {
+        if (known && (strict || headGuarded) && !known.has(atom.name))
+            return false;
+        branch().push(atom);
+        headGuarded = false;
+        return true;
+    };
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (atHead) {
+            const q = QUANTIFIER.exec(text.slice(i));
+            if (q) {
+                quantified = true;
+                choice = true;
+                i += q[0].length;
+                continue;
+            }
+        }
+        if (c === "(" || c === "[" || c === "{") {
+            const { inner, end } = bracketAt(text, i);
+            i = end;
+            if (expectName) {
+                // `EITHER (nodeId + inputName) OR graphInput`: a bracket where a name
+                // was due groups names, it does not comment on one.
+                const sub = scanItem(inner, { known, strict: true });
+                const atoms = [...sub.branches.flat(), ...sub.extra];
+                if (atoms.length > 0) {
+                    for (const atom of atoms)
+                        branch().push(atom);
+                    conjoined = atoms.length > 1;
+                    headGuarded = false;
+                    expectName = false;
+                }
+                continue;
+            }
+            const trimmed = inner.trim();
+            if (trimmed.startsWith("+")) {
+                extra.push(...scanPlusGroup(trimmed, known));
+            }
+            else if (/^or\b/i.test(trimmed)) {
+                // `(or point, or worldX + worldY)` names further ways to say the same
+                // thing. It is only ever read as parameters when every name in it is
+                // declared, because the same shape carries prose (`(or socket name)`).
+                const alt = [];
+                let ok = true;
+                for (const part of splitDepthZero(trimmed, ",")) {
+                    const sub = scanItem(part.text, { known, strict: true });
+                    if (sub.branches.length === 0 && sub.extra.length === 0) {
+                        ok = false;
+                        break;
+                    }
+                    for (const b of sub.branches)
+                        alt.push(b);
+                    if (sub.extra.length > 0)
+                        alt.push(sub.extra);
+                }
+                if (ok && alt.length > 0) {
+                    choice = true;
+                    for (const b of alt)
+                        branches.push(b);
+                }
+            }
+            continue;
+        }
+        if (c === "|") {
+            openBranch(true);
+            expectName = true;
+            atHead = false;
+            i++;
+            continue;
+        }
+        if (c === "+") {
+            conjoined = true;
+            expectName = true;
+            atHead = false;
+            i++;
+            continue;
+        }
+        if (c === "/") {
+            // A slash separates: `target/targetLabel` are two spellings of one
+            // parameter and `frames?/times?` are two ways of asking. Whether that
+            // separation is a CHOICE is decided by the rest of the item - an item
+            // with no `OR` in it is a plain list, and its branches never surface.
+            if (!conjoined)
+                openBranch(false);
+            expectName = true;
+            atHead = false;
+            i++;
+            continue;
+        }
+        if (c === ":") {
+            i++;
+            continue;
+        }
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)(\[\])?\s*(\?)?/.exec(text.slice(i));
+        if (!m)
+            break;
+        const word = m[1];
+        if (atHead && NONE_WORD.test(word) && !known?.has(word))
+            return { branches: [], extra: [], choice: false, quantified: false };
+        if (CHOICE_WORD.test(word) || JOIN_WORD.test(word) || (atHead && LEAD_WORD.test(word))) {
+            if (CHOICE_WORD.test(word))
+                openBranch(true);
+            else
+                conjoined = true;
+            if (atHead)
+                headGuarded = true;
+            expectName = true;
+            atHead = false;
+            i += m[1].length;
+            continue;
+        }
+        if (!expectName)
+            break;
+        if (!addAtom({ name: word, optional: m[3] === "?" })) {
+            rejected = true;
+            break;
+        }
+        expectName = false;
+        atHead = false;
+        i += m[0].length;
+    }
+    if (rejected && branch().length === 0 && branches.length === 1) {
+        return { branches: [], extra: [], choice: false, quantified: false };
+    }
+    const filled = branches.filter((b) => b.length > 0);
+    // A branch is reached, or not, through its first name. Everything conjoined
+    // behind an optional one is therefore optional too, however the clause spelt
+    // it: `axisHorizontal?/axisVertical? + horizontalMin/horizontalMax/...` is a
+    // back-compat spelling of an optional axis, not six required numbers.
+    for (const b of filled) {
+        if (b[0].optional)
+            for (const atom of b)
+                atom.optional = true;
+    }
+    // A quantifier is a choice even before a second branch turns up: `at least
+    // one of a, b, c` spells its list with commas, so the rest of it arrives as
+    // the items that follow.
+    const isChoice = (choice && filled.length > 1) || (quantified && filled.length > 0);
+    return { branches: filled, extra, choice: isChoice, quantified };
+}
+/**
+ * Pull the parameters out of the `Params:` clause every action carries.
+ *
+ * `known`, when given, is the category's declared keys. It settles the two
+ * places where the clause alone is ambiguous - a name behind a head connective
+ * and a name inside a bracket - by asking whether the wire would accept it.
+ * It only ever admits a name, never refuses one that stands in plain parameter
+ * position, so a name the description invents is still reported and still
+ * shows up as drift.
+ */
+export function parseParams(description, known) {
+    const at = description.search(/\bParams:/);
+    if (at < 0)
+        return { params: [], alternatives: [] };
+    let clause = description.slice(at + "Params:".length);
+    // The clause runs until the prose resumes. Two things end it: a `Returns`
+    // section, whose names are result fields rather than parameters, and a
+    // sentence break, after which the description is explaining rather than
+    // listing. Both are only terminators at depth zero, so `(e.g. 'foot_l')`
+    // and `{op:'set'}` stay attached to the parameter they document.
+    clause = cutAtDepthZero(clause, /\.\s+|\bReturns\b|\bReturn:/g);
+    // A trailing issue reference is not part of the list.
+    clause = clause.replace(/\(#[\d/#\s,]+\)\s*$/, "").trim();
+    const params = [];
+    const byName = new Map();
+    const alternatives = [];
+    const add = (atom, group) => {
+        const existing = byName.get(atom.name);
+        if (existing) {
+            if (group !== undefined && existing.group === undefined)
+                existing.group = group;
+            return existing;
+        }
+        const param = { name: atom.name, optional: atom.optional };
+        if (group !== undefined)
+            param.group = group;
+        byName.set(atom.name, param);
+        params.push(param);
+        return param;
+    };
+    const items = splitDepthZero(clause, ",;");
+    // A quantifier that ran out of item (`at least one of a, b, c`) keeps
+    // collecting the bare names behind it until something else appears.
+    let openGroup;
+    for (const item of items) {
+        const bare = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*$/.exec(item.text);
+        if (openGroup && item.separator === "," && bare) {
+            alternatives[openGroup.index].branches.push([bare[1]]);
+            add({ name: bare[1], optional: false }, openGroup.index);
+            continue;
+        }
+        openGroup = undefined;
+        const scanned = scanItem(item.text, { known });
+        if (scanned.branches.length === 0 && scanned.extra.length === 0)
+            continue;
+        if (scanned.choice) {
+            const index = alternatives.length;
+            const required = scanned.quantified
+                || scanned.branches.every((b) => b.some((a) => !a.optional));
+            alternatives.push({ branches: scanned.branches.map((b) => b.map((a) => a.name)), required });
+            for (const b of scanned.branches)
+                for (const atom of b)
+                    add(atom, index);
+            if (scanned.quantified)
+                openGroup = { index, scanned };
+        }
+        else {
+            for (const b of scanned.branches)
+                for (const atom of b)
+                    add(atom);
+        }
+        for (const atom of scanned.extra)
+            add(atom);
+    }
+    return { params, alternatives };
+}
+/** The parameters the `Params:` clause names, without the choice structure. */
+export function parseParamsClause(description, known) {
+    return parseParams(description, known).params;
+}
+/**
+ * The parameter keys an action's `mapParams` closure reads.
+ *
+ * Reading the compiled source is the only way to see this: `mapParams` is an
+ * opaque function by the time the registry is built. It is a best-effort
+ * signal - a closure that spreads its argument reads everything and shows
+ * nothing here - so it only ever adds names, never removes them.
+ */
+export function forwardedParams(spec) {
+    // A bridge action maps its parameters through `mapParams`; a local one
+    // reads them out of its handler's second argument. Both are the same
+    // question - which keys does this action look at - so both are scanned.
+    const fn = spec.mapParams ?? spec.handler;
+    if (!fn)
+        return [];
+    let src;
+    try {
+        src = fn.toString();
+    }
+    catch {
+        return [];
+    }
+    const names = new Set();
+    // Bind the scan to the closure's own parameter, so `arr.length` and
+    // `Array.isArray` are not mistaken for parameters the action reads.
+    // For a handler that is `(ctx, p) => ...`, the bag is the second argument.
+    const argsMatch = /^\s*(?:async\s*)?\(?\s*([^)=]*?)\s*\)?\s*=>/.exec(src);
+    const argNames = (argsMatch?.[1] ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => /^[A-Za-z_$][\w$]*$/.test(s));
+    const bagName = spec.mapParams ? argNames[0] : argNames[1];
+    if (bagName) {
+        const bag = bagName.replace(/\$/g, "\\$");
+        // The prevailing spelling is `(p) => ({ x: p.x, y: p.y ?? p.path })`.
+        // Match the accessor rather than the key, so an alias like
+        // `p.assetPath ?? p.path` reports both spellings the action accepts.
+        for (const m of src.matchAll(new RegExp(`\\b${bag}\\.([A-Za-z_][A-Za-z0-9_]*)\\b`, "g"))) {
+            names.add(m[1]);
+        }
+        for (const m of src.matchAll(new RegExp(`\\b${bag}\\[\\s*["']([A-Za-z_][A-Za-z0-9_]*)["']\\s*\\]`, "g"))) {
+            names.add(m[1]);
+        }
+    }
+    // Destructuring in the parameter position: `({ assetPath, save })`, or
+    // `(ctx, { assetPath })` for a local handler.
+    const destructured = spec.mapParams
+        ? /^\s*\(?\s*\{([^{}]*)\}/.exec(src)
+        : /^\s*(?:async\s*)?\([^,)]*,\s*\{([^{}]*)\}/.exec(src);
+    if (destructured) {
+        for (const part of destructured[1].split(",")) {
+            const key = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(?::|=|$)/.exec(part);
+            if (key)
+                names.add(key[1]);
+        }
+    }
+    names.delete("action");
+    return [...names];
+}
+/* ── the schema itself ─────────────────────────────────────────────── */
+/** Routing instructions the dispatcher consumes and strips before a handler
+ *  ever sees them. They are real wire parameters, so they are reported, but
+ *  they are never counted as drift against an action's own documentation. */
+const ROUTING_PARAMS = new Set(["action", "timeoutMs", "select", "omit", "editor", "toEditor"]);
+/** Build the full schema for one action of one tool. */
+export function actionSchema(tool, action) {
+    const spec = tool.actions[action];
+    if (!spec) {
+        throw new Error(`Unknown action '${action}' on tool '${tool.name}'. Available: ${Object.keys(tool.actions).join(", ")}`);
+    }
+    const description = spec.description ?? "";
+    // The category's declared keys settle the two spots where the clause alone
+    // is ambiguous, so the parse is done against them rather than in the dark.
+    const declaredNames = new Set(Object.keys(tool.schema));
+    const parsed = parseParams(description, declaredNames);
+    const documented = parsed.params;
+    const forwards = new Set(forwardedParams(spec));
+    const documentedByName = new Map(documented.map((d) => [d.name, d]));
+    // A choice only survives while more than one of its branches is reachable.
+    // `asset.migrate` documents `toEditor OR destinationContentDir`, and with
+    // one editor registered `toEditor` is not in the shape at all, which leaves
+    // an ordinary required parameter rather than a choice.
+    const alternatives = [];
+    const groupIndex = new Map();
+    parsed.alternatives.forEach((group, i) => {
+        const branches = group.branches
+            .map((b) => b.filter((n) => declaredNames.has(n)))
+            .filter((b) => b.length > 0);
+        if (branches.length < 2)
+            return;
+        groupIndex.set(i, alternatives.length);
+        alternatives.push({ branches, required: group.required });
+    });
+    const params = [];
+    const covered = new Set();
+    for (const [name, schema] of Object.entries(tool.schema)) {
+        if (name === "action")
+            continue;
+        const { inner, optional, description: paramDoc, default: dflt } = unwrap(schema);
+        const doc = documentedByName.get(name);
+        const group = doc?.group === undefined ? undefined : groupIndex.get(doc.group);
+        const sources = ["declared"];
+        if (doc)
+            sources.unshift("documented");
+        if (forwards.has(name))
+            sources.splice(sources.length - 1, 0, "forwards");
+        // A category's shape is one flat bag shared by all its actions, so most of
+        // its keys belong to some other action. Report the ones this action uses,
+        // plus the routing parameters, which every action accepts.
+        if (!doc && !forwards.has(name) && !ROUTING_PARAMS.has(name))
+            continue;
+        covered.add(name);
+        params.push({
+            name,
+            type: typeName(inner),
+            // The description's `?` marker wins: it is per-action, whereas the
+            // category shape has to declare nearly everything optional to let its
+            // other actions through.
+            required: doc ? group === undefined && !doc.optional : !optional,
+            description: paramDoc,
+            enumValues: enumValues(inner),
+            default: dflt,
+            sources,
+            alternativeGroup: group,
+        });
+    }
+    const drift = [];
+    const noteDrift = (name) => {
+        // Routing parameters are consumed by the dispatcher, and two of them are
+        // injected into the shape only while this server drives more than one
+        // editor, so their absence from a single-editor graph is not drift.
+        if (ROUTING_PARAMS.has(name))
+            return;
+        if (covered.has(name) || name in tool.schema || drift.includes(name))
+            return;
+        drift.push(name);
+    };
+    for (const { name } of documented)
+        noteDrift(name);
+    for (const name of forwards)
+        noteDrift(name);
+    params.sort((a, b) => {
+        if (a.required !== b.required)
+            return a.required ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    return {
+        tool: tool.name,
+        action,
+        description,
+        bridge: spec.bridge,
+        local: !spec.bridge,
+        timeoutMs: spec.timeoutMs,
+        class: classifyActionClass(tool.name, action).class,
+        params,
+        alternatives: alternatives.length > 0 ? alternatives : undefined,
+        drift,
+    };
+}
+/**
+ * Resolve an action reference to the tools that provide it.
+ *
+ * Accepts `tool.action`, `tool:action`, `tool action`, or a bare action name,
+ * which may be provided by more than one category (`list`, `save`, `create`).
+ * All matches come back so the caller can disambiguate rather than being
+ * handed whichever one sorted first.
+ */
+export function resolveActionRef(ref, tools) {
+    const trimmed = (ref ?? "").trim();
+    if (!trimmed)
+        return [];
+    const split = /^([A-Za-z_][A-Za-z0-9_]*)\s*[.: ]\s*([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+    if (split) {
+        const [, toolName, actionName] = split;
+        const tool = tools.find((t) => t.name === toolName.toLowerCase());
+        if (tool && tool.actions[actionName])
+            return [{ tool, action: actionName }];
+        // A bare action name containing a dot is not a thing, so fall through only
+        // when the qualified form found nothing at all.
+        if (tool)
+            return [];
+    }
+    const out = [];
+    for (const tool of tools) {
+        if (tool.actions[trimmed])
+            out.push({ tool, action: trimmed });
+    }
+    return out;
+}
+/** Close spellings for an action name that did not resolve. */
+export function suggestActions(ref, tools, limit = 8) {
+    const needle = (ref ?? "").trim().toLowerCase().replace(/^[a-z_]+[.:]/, "");
+    if (!needle)
+        return [];
+    const scored = [];
+    for (const tool of tools) {
+        for (const action of Object.keys(tool.actions)) {
+            const score = similarity(needle, action.toLowerCase());
+            if (score > 0)
+                scored.push({ label: `${tool.name}.${action}`, score });
+        }
+    }
+    return scored
+        .sort((a, b) => b.score - a.score || a.label.localeCompare(b.label))
+        .slice(0, limit)
+        .map((s) => s.label);
+}
+/**
+ * How close two action names are, on 0..1.
+ *
+ * Substring containment dominates, because the realistic miss is a caller who
+ * remembers part of the name (`bones` for `list_skeleton_bones`) rather than
+ * one who transposes two letters. Edit distance catches the typo case below
+ * that, and anything under a third of the name matching scores zero so the
+ * suggestion list stays short enough to read.
+ */
+export function similarity(a, b) {
+    if (a === b)
+        return 1;
+    if (b.includes(a))
+        return 0.9 * (a.length / b.length) + 0.05;
+    if (a.includes(b))
+        return 0.85 * (b.length / a.length);
+    const distance = editDistance(a, b);
+    const longest = Math.max(a.length, b.length);
+    const closeness = 1 - distance / longest;
+    return closeness >= 0.6 ? closeness * 0.8 : 0;
+}
+function editDistance(a, b) {
+    // Two rows rather than the full matrix: this runs over every action name on
+    // the surface for every miss.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let cur = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, cur] = [cur, prev];
+    }
+    return prev[b.length];
+}
+/**
+ * The closest spellings to a missed action name, out of a plain name list.
+ *
+ * Separate from `suggestActions` because the dispatcher has only its own
+ * category's keys at the point it fails, and importing the whole graph there
+ * would tie a per-call error path to the session registry.
+ */
+export function nearestActions(ref, available, limit = 5) {
+    const needle = (ref ?? "").trim().toLowerCase();
+    if (!needle)
+        return [];
+    return available
+        .map((a) => ({ a, score: similarity(needle, a.toLowerCase()) }))
+        .filter((x) => x.score > 0)
+        .sort((x, y) => y.score - x.score || x.a.localeCompare(y.a))
+        .slice(0, limit)
+        .map((x) => x.a);
+}
+/**
+ * Every action on the surface, with the drift each one carries. Used by the
+ * schema-drift unit test and by `project(describe_action)` when it is asked
+ * for a whole category rather than one action.
+ */
+export function allActionSchemas(tools) {
+    const out = [];
+    for (const tool of tools) {
+        for (const action of Object.keys(tool.actions)) {
+            out.push(actionSchema(tool, action));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=action-schema.js.map