ue-mcp 1.3.0 → 1.3.1-beta.2

package/README.md

@@ -5,7 +5,7 @@
 [![stars](https://img.shields.io/github/stars/db-lyon/ue-mcp)](https://github.com/db-lyon/ue-mcp/stargazers)
 [![MIT](https://img.shields.io/npm/l/ue-mcp)](LICENSE)
 
-**Unreal Engine Model Context Protocol Server** - gives AI assistants deep read/write access to the Unreal Editor through <!-- count:tools -->24<!-- /count --> category tools covering <!-- count:actions -->845+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
+**Unreal Engine Model Context Protocol Server** - gives AI assistants deep read/write access to the Unreal Editor through <!-- count:tools -->24<!-- /count --> category tools covering <!-- count:actions -->1090+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
 
 On UE 5.8+ it also wraps Epic's entire native AI Toolset Registry - 830 official Unreal tools, called in-process and surfaced as `epic_*` actions in the matching category: Sequencer in `animation`, PCG in `pcg`, static meshes in `asset`.
 
@@ -137,7 +137,7 @@ flows:
 flow(action="run", flowName="build_and_check")
 ```
 
-Every one of the <!-- count:actions -->845+<!-- /count --> actions is also a flow task. Flows support step references, retries, rollback, custom tasks in your own `.js`/`.ts`, and shell steps. See [Flows](https://ue-mcp.com/docs/flows/).
+Every one of the <!-- count:actions -->1090+<!-- /count --> actions is also a flow task. Flows support step references, retries, rollback, custom tasks in your own `.js`/`.ts`, and shell steps. See [Flows](https://ue-mcp.com/docs/flows/).
 
 ## Plugins
 
@@ -177,7 +177,7 @@ Details: [Guards](https://ue-mcp.com/docs/plugins-guards/) and [Handler Conventi
 
 | | |
 |---|---|
-| **Unreal Engine** | 5.4-5.8 (Windows), 5.6+ (Linux and macOS). `epic` category needs 5.8+. |
+| **Unreal Engine** | 5.4-5.8 (Windows), 5.6+ (Linux and macOS). Compiled and verified on 5.7 and 5.8; 5.4 to 5.6 are version-gated in source but not built here. `epic` category needs 5.8+. |
 | **Node.js** | 18 or newer |
 | **UE plugins** | `PythonScriptPlugin` (ships with the engine); `init` enables the rest for you |
 | **C++ toolchain** | Required - the bridge is a C++ plugin and compiles on first editor launch. On Windows that means Visual Studio with the C++ workload; on macOS, Xcode command line tools. |
@@ -192,6 +192,8 @@ Editor process control (`editor(start_editor)` / `stop_editor` / `restart_editor
 - [Tool Reference](https://ue-mcp.com/docs/tool-reference/) - Every tool, action, and parameter
 - [Architecture](https://ue-mcp.com/docs/architecture/) - How the server, bridge, and editor fit together
 - [Flows](https://ue-mcp.com/docs/flows/) - Multi-step YAML workflows, custom tasks, rollback
+- [Journal](https://ue-mcp.com/docs/journal/) - The per-project record of what a session did, produced, and how it ended
+- [Skill Packs](https://ue-mcp.com/docs/skill-packs/) - Written workflows an agent reads, and checking that the calls they teach still exist
 - [Plugins](https://ue-mcp.com/docs/plugins/) - Extending the surface through npm
 - [Configuration](https://ue-mcp.com/docs/configuration/) - `ue-mcp.yml` and MCP client config
 - [Troubleshooting](https://ue-mcp.com/docs/troubleshooting/) - Connection, build, and asset path issues

package/dist/action-class.js

@@ -61,7 +61,7 @@ const MUTATE_VERBS = new Set([
     "pause", "resume", "teleport", "respond", "stage", "capture", "render", "scrub",
     // Authoring verbs the asset lexicon has no reason to know about.
     "author", "edit", "place", "load", "reload", "force", "regenerate", "recompile",
-    "rebuild", "reparent", "auto", "populate", "bind", "rebind", "fill", "append",
+    "rebuild", "reparent", "auto", "populate", "bind", "rebind", "unbind", "fill", "append",
     "reindex", "migrate", "override", "flush", "cleanup", "configure", "init",
     "initialize", "step", "go", "submit", "remap", "login", "logout", "sync",
     "toggle", "reactivate", "reorder", "wrap", "sculpt", "paint", "snap", "aim",
@@ -113,6 +113,54 @@ const OVERRIDES = {
     // is a mutation by the lexicon, which is correct: a flow is whatever its
     // steps are.
     "flow.plan": "read",
+    // ── Read the engine tree and the project's own sources ──────────────
+    // These answer questions about C++ before any is written. They touch the
+    // engine install and the project's Source/ read-only, and the index they
+    // build is a cache under the user directory, not editor state. `verify` and
+    // `lint` are not in the verb lexicon because nothing else on the surface
+    // uses them.
+    "project.verify_symbols": "read",
+    "project.lint_cpp_header": "read",
+    // The relational half of the same reading: what a class derives from, what
+    // derives from it, and the lines around a declaration. `class` and `symbol`
+    // are nouns rather than verbs, so the lexicon has nothing to go on. The
+    // `find_*` analysis actions resolve through the lexicon already and are not
+    // listed here.
+    "project.class_hierarchy": "read",
+    "project.symbol_context": "read",
+    // ── Viewport, transactions and AI runtime ───────────────────────────
+    // Repaints the viewport. Nothing about the editor, the project on disk or
+    // the process changes; it is the visual equivalent of a read.
+    "editor.redraw_viewport": "read",
+    // Pure reads whose verb is not in the lexicon.
+    "editor.get_undo_state": "read",
+    "asset.read_skeletal_mesh_build_settings": "read",
+    // Rewrites a mesh's UV layout in place, so it changes the asset on disk.
+    "asset.unwrap_uvs": "mutate",
+    // Reports UV faults and writes nothing.
+    "asset.check_uvs": "read",
+    // Records another skeleton as compatible on this one, so it writes the asset.
+    "animation.register_compatible_skeleton": "mutate",
+    // Discards an open transaction, restoring what it touched. That is a change
+    // to editor state, so it is gated like one even though its purpose is undo.
+    "editor.cancel_transaction": "mutate",
+    // Asks whether A perceives B. Reads the perception component and nothing
+    // more; the verb is simply not in the lexicon.
+    "gameplay.check_perception": "read",
+    // Injects a stimulus into the running world, which AI then reacts to.
+    "gameplay.report_noise_event": "mutate",
+    // Creates the config asset when it is absent, so it can create.
+    "gameplay.ensure_mass_entity_config": "mutate",
+    // ── GAS granting and diagnosis ──────────────────────────────────────
+    // grant/revoke change a live actor's AbilitySystemComponent, so they are
+    // mutations even though neither verb is in the lexicon.
+    "gas.grant_ability": "mutate",
+    "gas.revoke_ability": "mutate",
+    // Reads by default. `activate: true` really does activate the ability, and
+    // an action whose effect a parameter decides is exactly what `unknown` is
+    // for: it is gated like a mutation, which is the safe answer, and the label
+    // stays honest.
+    "gas.trace_ability_activation": "unknown",
     // ── Arbitrary payload decides the effect ────────────────────────────
     "epic.call_tool": "unknown",
     "editor.execute_python": "mutate",
@@ -124,6 +172,16 @@ const OVERRIDES = {
     "editor.invoke_function": "unknown",
     "widget.invoke_runtime_function": "unknown",
     "niagara.batch": "mutate",
+    // ── Terrain reads the verb lexicon has no word for ──────────────────
+    // "analyze", "plan" and "project" are not in either list, and adding them as
+    // verbs would classify every future action containing those segments from a
+    // guess. All three of these only measure: they read the height field, or in
+    // the case of plan_real_world read nothing but a file the caller named, and
+    // return arithmetic. Nothing about them reaches an editor that could be the
+    // wrong one.
+    "landscape.analyze_terrain": "read",
+    "landscape.plan_real_world": "read",
+    "landscape.project_geo_coordinates": "read",
     // ── Reads whose verb reads as a write ───────────────────────────────
     // Serializers: they render a graph as text or JSON and return it.
     "blueprint.export_nodes_t3d": "read",
@@ -139,6 +197,12 @@ const OVERRIDES = {
     "level.load_actor_descs": "read",
     // Extracts a widget subtree as a description. `widget.author` writes one.
     "widget.extract_subtree": "read",
+    // Both walk a widget tree and report on it. "focus" is a mutate verb because
+    // the editor focuses a viewport on an actor, and a mutate verb anywhere in the
+    // name wins, which is wrong for a report about focus and for a read of where
+    // focus currently sits. `widget.set_runtime_focus` is the action that moves it.
+    "widget.audit_focus_chain": "read",
+    "widget.get_runtime_focus_path": "read",
     // Cache metadata about the Fab library, not a cache write.
     "fab.cache_info": "read",
     // Computes bounds, area, volume and topology over mesh data already in the
@@ -182,6 +246,10 @@ const OVERRIDES = {
     "gameplay.find_nav_path": "read",
     "editor.hit_test_viewport_pixel": "read",
     "editor.check_for_crashes": "read",
+    // Inspects the project descriptor, the engine tree and the deployed plugin
+    // on disk. It deploys nothing, enables nothing and builds nothing; the
+    // "install" in its name is the subject it reports on, not what it does.
+    "project.check_install": "read",
     "editor.search_log": "read",
     "project.live_coding_status": "read",
     "feedback.route": "read",
@@ -195,7 +263,17 @@ const OVERRIDES = {
     "asset.export": "mutate",
     "asset.export_texture": "mutate",
     "level.export_actor_fbx": "mutate",
-    "audio.extract_pcm": "mutate",
+    // Writes a 16-bit heightmap to a path the caller chose. It changes no
+    // terrain, but a file appearing on disk is an external side effect and the
+    // taxonomy above counts that as a mutation.
+    "landscape.export_heightmap": "mutate",
+    // Not one of the exports above, despite sitting next to them here since it
+    // was written. It decodes a USoundWave's imported audio into memory and
+    // returns the samples base64-encoded in the response: no intermediate file,
+    // no path parameter to write one to, nothing dirtied and nothing saved. It
+    // was classified `mutate` by association with the file-writing exports, and
+    // the handler body settles it the other way.
+    "audio.extract_pcm": "read",
     // Rebuilds the full-text index in the editor's own database.
     "asset.reindex_fts": "mutate",
     // Loads, rewrites and saves the packages that reference a set of
@@ -216,6 +294,53 @@ const OVERRIDES = {
     // The verb says read; what it can do says mutate, and the gate follows what
     // it can do.
     "gas.get_live_attribute_value": "mutate",
+    // Runs an EQS query through FEnvQueryManager::RunInstantQuery against an
+    // already-spawned querier and serialises the scored items. `run` is a mutate
+    // verb and this one does not: no spawn, no Modify, no save, nothing written
+    // back to the query asset or the world. Landing it in the wrong editor
+    // returns the wrong scores and changes nothing.
+    "gameplay.run_eqs_query": "read",
+    // ── Reads whose name leads with a subsystem, not a verb ─────────────
+    // The lexicon only trusts a read verb in the leading segment, so these say
+    // out loud what they read. Each one was confirmed against its handler: they
+    // open an asset, walk a graph or a document, and write nothing back.
+    "audio.metasound_get_graph": "read",
+    "audio.metasound_read_document": "read",
+    "audio.metasound_list_node_classes": "read",
+    "audio.metasound_list_node_pins": "read",
+    "audio.metasound_list_connections": "read",
+    "audio.metasound_list_variables": "read",
+    "audio.metasound_search_nodes": "read",
+    "audio.metasound_inspect_node": "read",
+    // Runs the MetaSound builder's own validation over a document and reports
+    // the errors. It builds nothing and saves nothing.
+    "audio.metasound_validate": "read",
+    "audio.cue_get_graph": "read",
+    // Answers whether a named weightmap layer is present on a landscape. The
+    // `exists` question never creates the layer it asks about.
+    "landscape.layer_exists": "read",
+    // ── The workflow journal and the skill packs ────────────────────────
+    // Neither reaches a bridge, so nothing here can land in the wrong EDITOR.
+    // Both are still per project: the journal file is keyed by absolute project
+    // root and skill packs install under a project's own `.claude/skills/`, so a
+    // write that guessed the wrong session would record one project's history,
+    // or install into one project's checkout, under another project's name.
+    // Spelled out rather than left to the verb lexicon, which has no reason to
+    // know what "note", "attach", "finish" or "cancel" do.
+    "flow.journal_start": "mutate",
+    "flow.journal_note": "mutate",
+    "flow.journal_attach": "mutate",
+    "flow.journal_finish": "mutate",
+    "flow.journal_cancel": "mutate",
+    "flow.journal_delete": "mutate",
+    "flow.journal_list": "read",
+    "flow.journal_get": "read",
+    "flow.journal_status": "read",
+    "flow.skill_install": "mutate",
+    "flow.skill_remove": "mutate",
+    "flow.skill_list": "read",
+    "flow.skill_get": "read",
+    "flow.skill_check": "read",
 };
 /** Split `category.action`, tolerating an action name that contains a dot. */
 export function splitTaskName(taskName) {
@@ -239,7 +364,20 @@ export function classifyActionClass(tool, action) {
     const segments = action.toLowerCase().split(/[._]/).filter(Boolean);
     if (segments.some((s) => MUTATE_VERBS.has(s)))
         return { class: "mutate", source: "lexicon" };
-    if (segments.some((s) => READ_VERBS.has(s)))
+    // A read verb only settles the question from the FRONT of the name. Anywhere
+    // else it is a noun as often as a verb, and the direction of that mistake is
+    // the dangerous one: `wire_rvt_sample` was a mutation that classified as a
+    // read on the strength of `sample`, and untargeted dispatch would have let it
+    // edit whichever editor happened to be active. It reached a human review
+    // rather than a release, and was renamed to `add_rvt_sampler`, which is a fix
+    // to one name and not to the rule that produced it.
+    //
+    // So a trailing read verb now decides nothing and falls through to
+    // `unresolved`, which is gated exactly like a mutation and which the drift
+    // guard fails on. The cost is an override line for every genuine read whose
+    // name leads with a subsystem instead of a verb; those are below, each saying
+    // what it reads. The alternative costs a silent wrong-editor write.
+    if (READ_VERBS.has(segments[0] ?? ""))
         return { class: "read", source: "lexicon" };
     // Epic's wrapped engine tools are injected at runtime from a live catalog, so
     // no build-time guard can enumerate them: enrichment can invent whole

package/dist/action-class.js.map

@@ -1 +1 @@
-{"version":3,"file":"action-class.js","sourceRoot":"","sources":["../src/action-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAY9D;;;;;;;;;;GAUG;AACH,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAS;IACxD,GAAG,eAAe;IAClB,gDAAgD;IAChD,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;IAC1C,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ;IACxF,yEAAyE;IACzE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO;IAC1E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO;IAC/E,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW;IAC/E,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ;IAC7E,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM;IACzE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM;IACxE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IAC3E,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU;IAC7E,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY;IACrE,sEAAsE;IACtE,4EAA4E;IAC5E,SAAS;IACT,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS;IAC5E,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO;IACpF,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;IAChE,8EAA8E;IAC9E,+EAA+E;IAC/E,8EAA8E;IAC9E,cAAc;IACd,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO;IAC7E,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK;IACnE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ;IACvE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM;CAC7E,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAS;IACtD,GAAG,aAAa;IAChB,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;IACxE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO;CAChE,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,SAAS,GAA0C;IACvD,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,sEAAsE;IACtE,sBAAsB,EAAE,MAAM;IAC9B,oBAAoB,EAAE,MAAM;IAC5B,oBAAoB,EAAE,MAAM;IAC5B,qBAAqB,EAAE,MAAM;IAE7B,2EAA2E;IAC3E,yEAAyE;IACzE,aAAa;IACb,WAAW,EAAE,MAAM;IAEnB,uEAAuE;IACvE,gBAAgB,EAAE,SAAS;IAC3B,uBAAuB,EAAE,QAAQ;IACjC,+BAA+B,EAAE,QAAQ;IACzC,wBAAwB,EAAE,QAAQ;IAClC,+BAA+B,EAAE,SAAS;IAC1C,gCAAgC,EAAE,SAAS;IAC3C,+BAA+B,EAAE,SAAS;IAC1C,wBAAwB,EAAE,SAAS;IACnC,gCAAgC,EAAE,SAAS;IAC3C,eAAe,EAAE,QAAQ;IAEzB,uEAAuE;IACvE,kEAAkE;IAClE,4BAA4B,EAAE,MAAM;IACpC,yEAAyE;IACzE,6EAA6E;IAC7E,yEAAyE;IACzE,8DAA8D;IAC9D,6BAA6B,EAAE,MAAM;IACrC,uBAAuB,EAAE,MAAM;IAC/B,kBAAkB,EAAE,MAAM;IAC1B,4EAA4E;IAC5E,mEAAmE;IACnE,wBAAwB,EAAE,MAAM;IAChC,0EAA0E;IAC1E,wBAAwB,EAAE,MAAM;IAChC,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM;IACxB,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,6BAA6B,EAAE,MAAM;IACrC,2EAA2E;IAC3E,8EAA8E;IAC9E,qEAAqE;IACrE,kCAAkC,EAAE,MAAM;IAC1C,uEAAuE;IACvE,kEAAkE;IAClE,iCAAiC,EAAE,MAAM;IACzC,yEAAyE;IACzE,2CAA2C;IAC3C,6BAA6B,EAAE,SAAS;IACxC,wEAAwE;IACxE,4EAA4E;IAC5E,sEAAsE;IACtE,iCAAiC,EAAE,MAAM;IACzC,uEAAuE;IACvE,0EAA0E;IAC1E,uEAAuE;IACvE,0BAA0B,EAAE,QAAQ;IACpC,8BAA8B,EAAE,QAAQ;IACxC,2EAA2E;IAC3E,6CAA6C;IAC7C,8BAA8B,EAAE,MAAM;IACtC,4EAA4E;IAC5E,0EAA0E;IAC1E,mCAAmC;IACnC,4BAA4B,EAAE,MAAM;IACpC,kDAAkD;IAClD,kBAAkB,EAAE,MAAM;IAC1B,4EAA4E;IAC5E,gDAAgD;IAChD,uBAAuB,EAAE,MAAM;IAC/B,yBAAyB,EAAE,MAAM;IACjC,6BAA6B,EAAE,MAAM;IACrC,yBAAyB,EAAE,MAAM;IACjC,wBAAwB,EAAE,MAAM;IAChC,gCAAgC,EAAE,MAAM;IACxC,0BAA0B,EAAE,MAAM;IAClC,mBAAmB,EAAE,MAAM;IAC3B,4BAA4B,EAAE,MAAM;IACpC,gBAAgB,EAAE,MAAM;IACxB,aAAa,EAAE,MAAM;IACrB,YAAY,EAAE,MAAM;IAEpB,uEAAuE;IACvE,oEAAoE;IACpE,6BAA6B,EAAE,QAAQ;IACvC,6BAA6B;IAC7B,yBAAyB,EAAE,QAAQ;IACnC,cAAc,EAAE,QAAQ;IACxB,sBAAsB,EAAE,QAAQ;IAChC,wBAAwB,EAAE,QAAQ;IAClC,mBAAmB,EAAE,QAAQ;IAC7B,6DAA6D;IAC7D,mBAAmB,EAAE,QAAQ;IAC7B,iEAAiE;IACjE,6EAA6E;IAC7E,4EAA4E;IAC5E,uCAAuC;IACvC,yBAAyB,EAAE,QAAQ;IACnC,uEAAuE;IACvE,6EAA6E;IAC7E,4EAA4E;IAC5E,6BAA6B;IAC7B,oBAAoB,EAAE,QAAQ;IAC9B,mCAAmC;IACnC,iBAAiB,EAAE,QAAQ;IAC3B,wEAAwE;IACxE,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,aAAa;IACb,8BAA8B,EAAE,QAAQ;CACzC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,MAAc;IAC9D,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAE7D,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpE,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7F,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAEzF,8EAA8E;IAC9E,sEAAsE;IACtE,wEAAwE;IACxE,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,+DAA+D;IAC/D,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAEjF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;AACpD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAgB;IACrD,OAAO,GAAG,KAAK,MAAM,CAAC;AACxB,CAAC"}
+{"version":3,"file":"action-class.js","sourceRoot":"","sources":["../src/action-class.ts"],"names":[],"mappings":"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"}

package/dist/action-schema.d.ts

@@ -0,0 +1,157 @@
+import type { ActionSpec, ToolDef } from "./types.js";
+import { type ActionClass } from "./action-class.js";
+export interface ParamSchema {
+    name: string;
+    /** Wire type, unwrapped through optional/default/nullable. */
+    type: string;
+    required: boolean;
+    description?: string;
+    /** Allowed values, when the parameter is an enum or a union of literals. */
+    enumValues?: string[];
+    /** Default applied by the schema when the caller omits the parameter. */
+    default?: unknown;
+    /**
+     * Where this name was found. A parameter missing `declared` is stripped
+     * before the handler sees it, whatever the description promises.
+     */
+    sources: Array<"documented" | "forwards" | "declared">;
+    /**
+     * Index into the action's `alternatives` when this parameter is one of a
+     * choice. `required` is false for every member of a choice, because the
+     * handler takes either one; what has to be satisfied is the group.
+     */
+    alternativeGroup?: number;
+}
+export interface ActionSchema {
+    tool: string;
+    action: string;
+    description: string;
+    /** The C++ bridge method this dispatches to, when it dispatches to one. */
+    bridge?: string;
+    /** True when the action runs in the server process with no editor call. */
+    local: boolean;
+    /** Longer wait this action declares for itself, in milliseconds. */
+    timeoutMs?: number;
+    /**
+     * Whether this observes the editor or changes it (#817's taxonomy).
+     *
+     * MCP's own readOnlyHint is per TOOL, and every tool here is a category
+     * holding both reads and mutations, so the manifest cannot carry this. A
+     * harness that wants to auto-approve reads and prompt on writes reads it
+     * from here instead of maintaining its own list.
+     *
+     *   read    observes; landing it in the wrong editor changes nothing
+     *   mutate  may change the editor, its project on disk, or its process
+     *   unknown decided by a parameter (an arbitrary python string, a wrapped
+     *           tool name), and therefore gated exactly like mutate
+     */
+    class: ActionClass;
+    params: ParamSchema[];
+    /**
+     * Choices the action offers, when it offers any.
+     *
+     * `level.delete_actor` takes `actorLabel OR actorPath`, and reporting both
+     * as required would have a caller send two ways of naming one actor, while
+     * reporting both as optional would have it send neither. Neither is
+     * individually required and the group is, so the group is what is published:
+     * each branch is a set of names that go together, and `required` says
+     * whether one of the branches has to be supplied.
+     */
+    alternatives?: AlternativeGroup[];
+    /**
+     * Names promised by the description or read by `mapParams` that the category
+     * does not declare. Passing one of these has no effect.
+     */
+    drift: string[];
+}
+/**
+ * A parameter named by an action's `Params:` clause.
+ *
+ * `group` is set when the clause offered the name as one of a choice
+ * (`actorLabel OR actorPath`). A member of a choice is never individually
+ * required, however the clause marks it, because the handler takes either.
+ */
+export interface DocumentedParam {
+    name: string;
+    optional: boolean;
+    /** Index into the parse's `alternatives`, when this name is one of a choice. */
+    group?: number;
+}
+/**
+ * A choice the clause offered.
+ *
+ * Each branch is the set of names that go together, so `name + packagePath? OR
+ * materialPath` has branches `[["name", "packagePath"], ["materialPath"]]`:
+ * what the caller supplies is one branch, not one name.
+ */
+export interface AlternativeGroup {
+    branches: string[][];
+    /** True when the action needs one of the branches. */
+    required: boolean;
+}
+export interface DocumentedParams {
+    params: DocumentedParam[];
+    alternatives: AlternativeGroup[];
+}
+/**
+ * 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 declare function parseParams(description: string, known?: ReadonlySet<string>): DocumentedParams;
+/** The parameters the `Params:` clause names, without the choice structure. */
+export declare function parseParamsClause(description: string, known?: ReadonlySet<string>): DocumentedParam[];
+/**
+ * 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 declare function forwardedParams(spec: ActionSpec): string[];
+/** Build the full schema for one action of one tool. */
+export declare function actionSchema(tool: ToolDef, action: string): ActionSchema;
+/**
+ * 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 declare function resolveActionRef(ref: string, tools: ToolDef[]): Array<{
+    tool: ToolDef;
+    action: string;
+}>;
+/** Close spellings for an action name that did not resolve. */
+export declare function suggestActions(ref: string, tools: ToolDef[], limit?: number): string[];
+/**
+ * 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 declare function similarity(a: string, b: string): number;
+/**
+ * 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 declare function nearestActions(ref: string, available: string[], limit?: number): string[];
+/**
+ * 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 declare function allActionSchemas(tools: ToolDef[]): ActionSchema[];