unity-open-mcp 0.1.0 → 0.3.0

package/dist/capabilities/cost-hints.js

@@ -0,0 +1,185 @@
+// M22 Plan 1 / T22.1.5 — Cost hints for the heavy tools' output profiles.
+//
+// Agents that reason about prompt cost before choosing an output profile need
+// a machine-readable signal of *roughly* how expensive each profile is per
+// tool. This module is that signal: a per-tool, per-profile cost band plus a
+// short recommended-tool-chain narrative.
+//
+// The bands are deliberately coarse (`small` | `medium` | `large`) and framed
+// as approximate token ranges. They are not measurements — they are planning
+// hints so an agent can pick `compact` first, expand on demand, and avoid
+// pulling a 100 KB `full` dump into context when it only needed a count.
+//
+// This is a pure data module (no I/O, no cross-file runtime imports) so it
+// loads cleanly under `node --experimental-strip-types` in tests.
+/**
+ * Approximate token range for each cost band.
+ *
+ * The ranges are intentionally wide — they describe the *typical* payload a
+ * profile produces for that tool on a representative asset, not a hard bound.
+ * Real payloads can fall outside the range on very large or very small inputs;
+ * `page_size` is the mechanism that enforces an actual cap.
+ */
+export const COST_BAND_TOKENS = {
+    small: { min: 0, max: 800 },
+    medium: { min: 800, max: 4000 },
+    large: { min: 4000, max: 0 }, // 0 max = unbounded (use page_size)
+};
+/**
+ * Format a cost band into a human-readable approximate-token string.
+ */
+export function describeBand(band) {
+    switch (band) {
+        case "small":
+            return "~0.3–0.8k tokens";
+        case "medium":
+            return "~1–4k tokens";
+        case "large":
+            return "large — unbounded; set page_size to bound it";
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-tool cost hints.
+//
+// The table mirrors the heavy-tool roster in `docs/api/mcp-tools.md`
+// §"Output profiles + uniform paging". Keep the two in sync: when a tool is
+// added to / removed from the profile-aware surface, update both this table
+// and the doc in the same task.
+// ---------------------------------------------------------------------------
+export const TOOL_COST_HINTS = [
+    {
+        tool: "unity_open_mcp_read_asset",
+        profileControls: "TREE folding (compact = CMP codes + omission counts; full = verbose tree).",
+        pageSizePages: "TREE rows.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+    {
+        tool: "unity_open_mcp_search_assets",
+        profileControls: "per-file object cap (compact tight; balanced/full larger).",
+        pageSizePages: "result-file matches.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+    {
+        tool: "unity_open_mcp_scene_get_data",
+        profileControls: "scene overview vs nested children vs transforms (depth / per-node verbosity).",
+        pageSizePages: "flattened node stream.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+    {
+        tool: "unity_open_mcp_find_references",
+        profileControls: "counts/groupings (compact) vs per-asset list (balanced) vs field locations (full).",
+        pageSizePages: "referencing-assets list.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+    {
+        tool: "unity_open_mcp_validate_edit",
+        profileControls: "counts by severity (compact) vs full issues list (balanced/full).",
+        pageSizePages: "issues list.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+    {
+        tool: "unity_open_mcp_scan_paths",
+        profileControls: "counts by severity (compact) vs full issues list (balanced/full).",
+        pageSizePages: "issues list.",
+        profiles: {
+            compact: { band: "small", approxTokens: describeBand("small") },
+            balanced: { band: "medium", approxTokens: describeBand("medium") },
+            full: { band: "large", approxTokens: describeBand("large") },
+        },
+    },
+];
+/**
+ * The default recommended page sizes per tool. These are starting points, not
+ * hard caps — an agent can choose a different `page_size`. Surfaced as part of
+ * the cost-hints block so an agent learns a sensible starting page size
+ * alongside the cost band.
+ */
+export const RECOMMENDED_PAGE_SIZE = {
+    unity_open_mcp_read_asset: 40,
+    unity_open_mcp_search_assets: 25,
+    unity_open_mcp_scene_get_data: 50,
+    unity_open_mcp_find_references: 50,
+    unity_open_mcp_validate_edit: 25,
+    unity_open_mcp_scan_paths: 25,
+};
+export const RECOMMENDED_TOOL_CHAINS = [
+    {
+        name: "discover",
+        task: "Learn the available surface before assuming tool names or schemas.",
+        steps: [
+            "unity_open_mcp_capabilities",
+            "unity_open_mcp_manage_tools(action=\"list_groups\")",
+            "unity_open_mcp_ping",
+        ],
+    },
+    {
+        name: "asset-inspect",
+        task: "Read an asset cheaply, then drill into the part you need.",
+        steps: [
+            "unity_open_mcp_read_asset (default compact) — get the folded overview + omission counts",
+            "unity_open_mcp_read_asset(component=\"...\" or path=\"...\") — drill down without re-fetching",
+            "only escalate to profile=\"full\" when the folded view is insufficient",
+        ],
+    },
+    {
+        name: "find-references",
+        task: "Find what references an asset without flooding context.",
+        steps: [
+            "unity_open_mcp_find_references (default compact) — counts + folder groupings",
+            "if a folder is interesting, page its assets with page_size + cursor",
+            "escalate to profile=\"verbose\" only for the specific field locations you need",
+        ],
+    },
+    {
+        name: "mutate-then-verify",
+        task: "Mutate scoped to paths_hint, then read the gate delta inline.",
+        steps: [
+            "mutate with gate=\"enforce\" + non-empty paths_hint",
+            "read gate.delta + agentNextSteps from the response (no separate read_console needed)",
+            "on gate failure, prefer unity_open_mcp_apply_fix with dry_run: true first",
+        ],
+    },
+    {
+        name: "verify-api-before-coding",
+        task: "Verify Unity API details before writing C# — LLM training data frequently contains incorrect or outdated Unity APIs.",
+        steps: [
+            "unity_open_mcp_search_assets — find actual shaders / materials / scripts in the project",
+            "unity_open_mcp_find_members — reflect the real type + member signatures",
+            "unity_open_mcp_type_schema — drill into fields/properties on a type",
+            "only then unity_open_mcp_execute_csharp / invoke_method with the verified API",
+        ],
+    },
+];
+export function buildCostHints() {
+    return {
+        tools: TOOL_COST_HINTS,
+        recommendedPageSize: RECOMMENDED_PAGE_SIZE,
+        recommendedToolChains: RECOMMENDED_TOOL_CHAINS,
+        guidance: "Start with the default compact profile on every heavy tool, then " +
+            "expand (profile=\"balanced\" / \"full\") or drill down " +
+            "(component / path / id flags) only for the slice you need. Set " +
+            "page_size to bound any profile; follow pagination.next_cursor to " +
+            "resume. compact is the documented default for all heavy tools.",
+    };
+}
+//# sourceMappingURL=cost-hints.js.map

package/dist/capabilities/cost-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-hints.js","sourceRoot":"","sources":["../../src/capabilities/cost-hints.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/lifecycle.d.ts

@@ -0,0 +1,40 @@
+export type LifecycleClass = "none" | "compile-reload" | "modal-dialog" | "scene-dirty" | "process-stale";
+export interface ToolLifecycle {
+    /** Lifecycle class the tool declares. */
+    class: LifecycleClass;
+    /**
+     * Optional short agent-facing constraint or secondary recovery concern.
+     * Examples: `compile_check` notes its batch-only lock; `build_start` notes
+     * the secondary scene-dirty concern; `package_add` notes the rare upgrade
+     * modal. Absent when the class is self-describing.
+     */
+    note?: string;
+}
+export declare const TOOL_LIFECYCLE: Record<string, ToolLifecycle>;
+/**
+ * Resolve the lifecycle declaration for a tool. Unlisted tools (the read-only
+ * majority) default to `{ class: "none" }` — the safe recovery class that
+ * promises no settle wait, no dirty guard, and no stale-heartbeat risk.
+ */
+export declare function lifecycleFor(toolName: string): ToolLifecycle;
+export interface LifecycleTaxonomyEntry {
+    /** Lifecycle class id (matches `ToolLifecycle.class`). */
+    class: LifecycleClass;
+    /** One-line description of what the tool does to the editor. */
+    meaning: string;
+    /** What the bridge does for this class (settle / guard / heartbeat). */
+    bridge: string;
+    /** How an agent should recover when a call of this class fails / stalls. */
+    recovery: string;
+}
+export declare const LIFECYCLE_TAXONOMY: LifecycleTaxonomyEntry[];
+export interface LifecycleBlock {
+    /** The 5-class taxonomy (meaning / bridge behaviour / recovery per class). */
+    classes: LifecycleTaxonomyEntry[];
+    /**
+     * One-line guidance restating how to read the per-tool `lifecycle` field.
+     * Kept here so the block is self-describing without an agent reading the doc.
+     */
+    guidance: string;
+}
+export declare function buildLifecycle(): LifecycleBlock;

package/dist/capabilities/lifecycle.js

@@ -0,0 +1,353 @@
+// Lifecycle policy taxonomy + per-tool declarations.
+//
+// Every tool is classified into one of five lifecycle classes describing the
+// *recovery* concern the agent must reason about when the call fails or the
+// bridge becomes unresponsive: read-only (none), a domain reload
+// (compile-reload), an OS modal (modal-dialog), a scene/prefab mutation that
+// needs the gate + paths_hint (scene-dirty), or a long-running op where the
+// bridge may stall (process-stale). The class is exposed per tool via
+// `capabilities.tools[].lifecycle` so an agent can pick a recovery strategy
+// before it calls, and the full taxonomy is attached as
+// `capabilities.lifecycleBlock`.
+//
+// IMPORTANT — two distinct axes, intentionally not conflated:
+//   - This module is the agent-facing RECOVERY axis (5 classes). It is the
+//     source of truth for what an agent sees in `capabilities`.
+//   - The bridge carries a separate internal SETTLE-TIMING axis
+//     (None / EditorSettle / RestartThenSettle / CustomConfirmation) that
+//     drives how long the dispatcher blocks before returning and whether the
+//     active-scene dirty guard preflights. Agents do not see that enum
+//     directly; it is an internal mechanism. The two axes agree because this
+//     table is derived from the same per-tool knowledge, but they are not
+//     renamed copies of each other — the recovery class is coarser and
+//     oriented toward "what do I do when this goes wrong."
+//
+// This is a pure data module (no I/O, no cross-file runtime imports) so it
+// loads cleanly under `node --experimental-strip-types` in tests.
+// ---------------------------------------------------------------------------
+// Per-tool declarations.
+//
+// Only tools whose class is NOT the safe default (`none`) are listed here —
+// `lifecycleFor()` falls back to `{ class: "none" }` for any unlisted tool, so
+// a read-only tool added without an entry surfaces correctly without an edit.
+// `compile_check` is listed even though it is read-only re: game state because
+// its lifecycle class is `compile-reload` (it spawns a recompiling Unity) and
+// it carries the batch-only lock note agents must see.
+//
+// Keep this table in sync with the bridge's internal settle-timing map
+// (`packages/bridge/Editor/Bridge/ToolLifecycle.cs`) and the lifecycle doc in
+// `docs/api/mcp-tools.md` when a tool is added/removed/reclassified.
+// ---------------------------------------------------------------------------
+export const TOOL_LIFECYCLE = {
+    // ----- compile-reload: triggers or observes a domain reload --------------
+    // The bridge blocks up to 60s for the compile to settle and the dirty guard
+    // preflights these. `compile_check` is the batch-only observer: it spawns a
+    // fresh headless Unity and cannot share the project with a live Editor.
+    "unity_open_mcp_execute_csharp": { class: "compile-reload" },
+    "unity_open_mcp_invoke_method": { class: "compile-reload" },
+    "unity_open_mcp_execute_menu": { class: "compile-reload" },
+    "unity_open_mcp_asmdef_create": { class: "compile-reload" },
+    "unity_open_mcp_asmdef_modify": { class: "compile-reload" },
+    "unity_open_mcp_script_write": { class: "compile-reload" },
+    "unity_open_mcp_script_delete": { class: "compile-reload" },
+    "unity_open_mcp_build_set_target": { class: "compile-reload" },
+    "unity_open_mcp_build_set_defines": { class: "compile-reload" },
+    "unity_open_mcp_settings_set_player": {
+        class: "compile-reload",
+        note: "Flipping scripting backend / input handler knobs can force a recompile " +
+            "in addition to the settings write.",
+    },
+    // scene_open in single mode can lose unsaved changes in currently-open
+    // scenes; the dirty guard preflights it (same recovery class as a reload).
+    "unity_open_mcp_scene_open": { class: "compile-reload" },
+    // compile_check is read-only re: game state but its lifecycle IS a domain
+    // reload: it spawns a recompiling Unity. Batch-only by design — see note.
+    "unity_open_mcp_compile_check": {
+        class: "compile-reload",
+        note: "Batch-only by design — spawns a fresh headless Unity that recompiles " +
+            "from scratch. Cannot run while a live Editor holds the project lock; " +
+            "expect `editor_instance_locked` and do not retry blindly (close the " +
+            "live Editor, or verify compile state via the live bridge instead). " +
+            "Edits under a local `packages/` source live outside Unity's Assets/ " +
+            "watch root, so assets_refresh / RequestScriptCompilation are not " +
+            "reliable for forcing a rebuild in a long-running live session — " +
+            "verify via Library/ScriptAssemblies/*.dll mtime instead.",
+    },
+    // ----- modal-dialog: may raise an OS modal -------------------------------
+    // Plan 1 declares the class; full detect/classify/dismiss/escalate policy
+    // ships separately. The note points at the secondary concern.
+    "unity_open_mcp_build_start": {
+        class: "modal-dialog",
+        note: "BuildPipeline.BuildPlayer may raise an OS modal (build settings, " +
+            "platform mismatch). Also a scene-dirty mutation — the gate + " +
+            "paths_hint cover the mutate side; the modal is the harder recovery.",
+    },
+    "unity_open_mcp_package_add": {
+        class: "compile-reload",
+        note: "Rewrites Packages/manifest.json + triggers UPM resolution which can " +
+            "force a domain reload. A first import of a major package version can " +
+            "additionally raise a project-upgrade modal (rare).",
+    },
+    "unity_open_mcp_package_remove": {
+        class: "compile-reload",
+        note: "Rewrites Packages/manifest.json + triggers UPM resolution which can " +
+            "force a domain reload.",
+    },
+    "unity_open_mcp_reimport_package": {
+        class: "compile-reload",
+        note: "Force-reimports a local file: package's source and nudges a script " +
+            "recompile (RequestScriptCompilation); a domain reload can follow. The " +
+            "package id is the scope (source lives outside Assets/, so the gate has " +
+            "no Assets/ path to validate — paths_hint defaults to " +
+            "Packages/<package_id>). The response reports dllMtimeBefore/After so " +
+            "an agent can detect a no-op recompile and fall back to a standalone " +
+            "Roslyn compile (documented in agentNextSteps on a no-op).",
+    },
+    // ----- process-stale: long-running / async; bridge may stall -------------
+    // The heartbeat may stop advancing during these; an agent should expect a
+    // stale-heartbeat signature and not interpret it as a crash without the
+    // PID-liveness check.
+    "unity_senses_run_tests": {
+        class: "process-stale",
+        note: "Async — returns immediately and the result is delivered via an external " +
+            "completion signal you poll. A long test run can stall the heartbeat; " +
+            "treat stale-heartbeat + live-PID as 'still running', not crashed.",
+    },
+    "unity_open_mcp_reflection_probe_bake": {
+        class: "process-stale",
+        note: "Reflection-probe bake can take seconds to minutes; the bridge blocks " +
+            "until it finishes. A stale heartbeat during a bake is expected.",
+    },
+    "unity_senses_memory_snapshot_capture": {
+        class: "process-stale",
+        note: "Callback-based capture; the bridge blocks until the snapshot file is " +
+            "written. Large captures can take seconds and stall the heartbeat.",
+    },
+    // ----- scene-dirty: mutates scene/prefab/hierarchy; gate + paths_hint -----
+    // The bridge blocks up to 5s for asset refresh / serialization. No domain
+    // reload. These are the bulk of the typed mutators and domain mutators.
+    "unity_open_mcp_apply_fix": { class: "scene-dirty" },
+    "unity_open_mcp_reserialize": { class: "scene-dirty" },
+    // Asset CRUD.
+    "unity_open_mcp_assets_create_folder": { class: "scene-dirty" },
+    "unity_open_mcp_assets_copy": { class: "scene-dirty" },
+    "unity_open_mcp_assets_move": { class: "scene-dirty" },
+    "unity_open_mcp_assets_delete": { class: "scene-dirty" },
+    "unity_open_mcp_assets_refresh": { class: "scene-dirty" },
+    // Material mutators.
+    "unity_open_mcp_material_create": { class: "scene-dirty" },
+    "unity_open_mcp_material_set_property": { class: "scene-dirty" },
+    "unity_open_mcp_material_set_keyword": { class: "scene-dirty" },
+    "unity_open_mcp_material_set_shader": { class: "scene-dirty" },
+    // Prefab mutators (open/close are editor-stage state, still asset-scoped).
+    "unity_open_mcp_prefab_instantiate": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_create": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_open": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_close": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_save": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_apply": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_revert": { class: "scene-dirty" },
+    "unity_open_mcp_prefab_unpack": { class: "scene-dirty" },
+    // GameObject + component mutators.
+    "unity_open_mcp_gameobject_create": { class: "scene-dirty" },
+    "unity_open_mcp_gameobject_destroy": { class: "scene-dirty" },
+    "unity_open_mcp_gameobject_duplicate": { class: "scene-dirty" },
+    "unity_open_mcp_gameobject_modify": { class: "scene-dirty" },
+    "unity_open_mcp_gameobject_set_parent": { class: "scene-dirty" },
+    "unity_open_mcp_component_add": { class: "scene-dirty" },
+    "unity_open_mcp_component_destroy": { class: "scene-dirty" },
+    "unity_open_mcp_component_modify": { class: "scene-dirty" },
+    // Object/script mutators.
+    "unity_open_mcp_object_modify": { class: "scene-dirty" },
+    "unity_open_mcp_scriptableobject_create": { class: "scene-dirty" },
+    // Scene mutators (non-open; open is compile-reload above).
+    "unity_open_mcp_scene_create": { class: "scene-dirty" },
+    "unity_open_mcp_scene_save": { class: "scene-dirty" },
+    "unity_open_mcp_scene_unload": { class: "scene-dirty" },
+    "unity_open_mcp_scene_set_active": { class: "scene-dirty" },
+    "unity_open_mcp_scene_focus": { class: "scene-dirty" },
+    "unity_open_mcp_sceneview_set_camera": { class: "scene-dirty" },
+    // TagManager + console + selection + editor state mutators.
+    "unity_open_mcp_editor_add_tag": { class: "scene-dirty" },
+    "unity_open_mcp_editor_add_layer": { class: "scene-dirty" },
+    "unity_open_mcp_console_clear": { class: "scene-dirty" },
+    "unity_open_mcp_console_log": { class: "scene-dirty" },
+    "unity_open_mcp_editor_set_state": {
+        class: "scene-dirty",
+        note: "Entering play mode can trigger Unity's native save modal; the bridge " +
+            "runs its own inline dirty guard for this tool.",
+    },
+    "unity_open_mcp_selection_set": { class: "scene-dirty" },
+    "unity_open_mcp_editor_undo": { class: "scene-dirty" },
+    "unity_open_mcp_editor_redo": { class: "scene-dirty" },
+    "unity_open_mcp_editor_clear_history": { class: "scene-dirty" },
+    // Profiler snapshot write.
+    "unity_open_mcp_profiler_save_data": { class: "scene-dirty" },
+    // Build/settings mutators (non-reload).
+    "unity_open_mcp_build_set_scenes": { class: "scene-dirty" },
+    "unity_open_mcp_settings_set_quality": { class: "scene-dirty" },
+    "unity_open_mcp_settings_set_physics": { class: "scene-dirty" },
+    "unity_open_mcp_settings_set_lighting": { class: "scene-dirty" },
+    "unity_open_mcp_settings_set_time": { class: "scene-dirty" },
+    "unity_open_mcp_settings_set_quality_level": { class: "scene-dirty" },
+    // KV preferences setters (registry / Library writes, not project assets).
+    "unity_open_mcp_playerprefs_set": { class: "scene-dirty" },
+    "unity_open_mcp_playerprefs_delete": { class: "scene-dirty" },
+    "unity_open_mcp_editorprefs_set": { class: "scene-dirty" },
+    "unity_open_mcp_editorprefs_delete": { class: "scene-dirty" },
+    // ----- Domain mutators (extension packs) — all scene-dirty ---------------
+    // Navigation.
+    "unity_open_mcp_navigation_surface_add": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_set_bake_settings": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_surface_bake": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_modifier_add": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_modifier_volume_add": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_link_add": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_agent_add": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_agent_set_destination": { class: "scene-dirty" },
+    "unity_open_mcp_navigation_modify": { class: "scene-dirty" },
+    // Input System.
+    "unity_open_mcp_inputsystem_asset_create": { class: "scene-dirty" },
+    "unity_open_mcp_inputsystem_actionmap_add": { class: "scene-dirty" },
+    "unity_open_mcp_inputsystem_action_add": { class: "scene-dirty" },
+    "unity_open_mcp_inputsystem_binding_add": { class: "scene-dirty" },
+    "unity_open_mcp_inputsystem_binding_composite_add": { class: "scene-dirty" },
+    "unity_open_mcp_inputsystem_controlscheme_add": { class: "scene-dirty" },
+    // ProBuilder.
+    "unity_open_mcp_probuilder_create_shape": { class: "scene-dirty" },
+    "unity_open_mcp_probuilder_extrude": { class: "scene-dirty" },
+    "unity_open_mcp_probuilder_delete_faces": { class: "scene-dirty" },
+    "unity_open_mcp_probuilder_set_face_material": { class: "scene-dirty" },
+    // Particle System.
+    "unity_open_mcp_particle_system_modify": { class: "scene-dirty" },
+    // Animation (AnimationClip + AnimatorController).
+    "unity_open_mcp_animation_create": { class: "scene-dirty" },
+    "unity_open_mcp_animation_modify": { class: "scene-dirty" },
+    "unity_open_mcp_animator_create": { class: "scene-dirty" },
+    "unity_open_mcp_animator_modify": { class: "scene-dirty" },
+    // Splines.
+    "unity_open_mcp_splines_container_create": { class: "scene-dirty" },
+    "unity_open_mcp_splines_add_knot": { class: "scene-dirty" },
+    "unity_open_mcp_splines_set_knot": { class: "scene-dirty" },
+    "unity_open_mcp_splines_set_tangent_mode": { class: "scene-dirty" },
+    "unity_open_mcp_splines_modify": { class: "scene-dirty" },
+    // Lighting.
+    "unity_open_mcp_light_add": { class: "scene-dirty" },
+    "unity_open_mcp_light_set": { class: "scene-dirty" },
+    "unity_open_mcp_light_modify": { class: "scene-dirty" },
+    "unity_open_mcp_skybox_set": { class: "scene-dirty" },
+    // Audio.
+    "unity_open_mcp_audio_source_add": { class: "scene-dirty" },
+    "unity_open_mcp_audio_source_modify": { class: "scene-dirty" },
+    "unity_open_mcp_audio_mixer_set_parameter": { class: "scene-dirty" },
+    // UI (uGUI).
+    "unity_open_mcp_ui_canvas_add": { class: "scene-dirty" },
+    "unity_open_mcp_ui_element_add": { class: "scene-dirty" },
+    "unity_open_mcp_ui_layout_group_add": { class: "scene-dirty" },
+    "unity_open_mcp_ui_element_modify": { class: "scene-dirty" },
+    // Constraints & LOD.
+    "unity_open_mcp_constraint_add": { class: "scene-dirty" },
+    "unity_open_mcp_lod_group_configure": { class: "scene-dirty" },
+    "unity_open_mcp_lod_add_level": { class: "scene-dirty" },
+    // Terrain.
+    "unity_open_mcp_terrain_create": { class: "scene-dirty" },
+    "unity_open_mcp_terrain_set_heights": { class: "scene-dirty" },
+    "unity_open_mcp_terrain_paint_layer": { class: "scene-dirty" },
+    "unity_open_mcp_terrain_place_trees": { class: "scene-dirty" },
+    "unity_open_mcp_terrain_set_neighbors": { class: "scene-dirty" },
+    // Cinemachine.
+    "unity_open_mcp_cinemachine_create_camera": { class: "scene-dirty" },
+    "unity_open_mcp_cinemachine_set_targets": { class: "scene-dirty" },
+    "unity_open_mcp_cinemachine_set_lens": { class: "scene-dirty" },
+    "unity_open_mcp_cinemachine_set_body": { class: "scene-dirty" },
+    "unity_open_mcp_cinemachine_set_noise": { class: "scene-dirty" },
+    "unity_open_mcp_cinemachine_brain_ensure": { class: "scene-dirty" },
+    // Timeline.
+    "unity_open_mcp_timeline_create": { class: "scene-dirty" },
+    "unity_open_mcp_timeline_track_add": { class: "scene-dirty" },
+    "unity_open_mcp_timeline_clip_add": { class: "scene-dirty" },
+    "unity_open_mcp_timeline_director_bind": { class: "scene-dirty" },
+    "unity_open_mcp_timeline_modify": { class: "scene-dirty" },
+    // Tilemap.
+    "unity_open_mcp_tilemap_create": { class: "scene-dirty" },
+    "unity_open_mcp_tilemap_set_tile": { class: "scene-dirty" },
+    "unity_open_mcp_tilemap_box_fill": { class: "scene-dirty" },
+    "unity_open_mcp_tilemap_create_tile_asset": { class: "scene-dirty" },
+    "unity_open_mcp_tilemap_create_rule_tile": { class: "scene-dirty" },
+    // Shader Graph.
+    "unity_open_mcp_shader_graph_create": { class: "scene-dirty" },
+    "unity_open_mcp_shader_graph_node_add": { class: "scene-dirty" },
+    "unity_open_mcp_shader_graph_node_connect": { class: "scene-dirty" },
+    // VFX Graph.
+    "unity_open_mcp_vfx_block_edit": { class: "scene-dirty" },
+    // 2D art pipeline (SpriteAtlas + Texture).
+    "unity_open_mcp_spriteatlas_create": { class: "scene-dirty" },
+    "unity_open_mcp_spriteatlas_add_packable": { class: "scene-dirty" },
+    "unity_open_mcp_spriteatlas_remove_packable": { class: "scene-dirty" },
+    "unity_open_mcp_spriteatlas_modify": { class: "scene-dirty" },
+    "unity_open_mcp_spriteatlas_delete": { class: "scene-dirty" },
+    "unity_open_mcp_texture_set_import": { class: "scene-dirty" },
+    "unity_open_mcp_texture_reimport": {
+        class: "scene-dirty",
+        note: "Reimport can take seconds and occasionally triggers a platform-switch " +
+            "domain reload; if a reload follows, treat it as compile-reload.",
+    },
+};
+/**
+ * Resolve the lifecycle declaration for a tool. Unlisted tools (the read-only
+ * majority) default to `{ class: "none" }` — the safe recovery class that
+ * promises no settle wait, no dirty guard, and no stale-heartbeat risk.
+ */
+export function lifecycleFor(toolName) {
+    return TOOL_LIFECYCLE[toolName] ?? { class: "none" };
+}
+export const LIFECYCLE_TAXONOMY = [
+    {
+        class: "none",
+        meaning: "Read-only / side-effect-free.",
+        bridge: "Returns immediately; no settle wait, no dirty guard.",
+        recovery: "Retry on the next call. A failure is a real error, not a settle/reload artifact.",
+    },
+    {
+        class: "compile-reload",
+        meaning: "Triggers or observes a domain reload (script / asmdef / package edit).",
+        bridge: "Blocks up to 60s for the compile to settle; the active-scene dirty guard preflights.",
+        recovery: "After the call, poll editor_status / read_compile_errors before assuming success. " +
+            "compile_check is batch-only and returns editor_instance_locked when a live Editor " +
+            "holds the project lock — do not retry blindly.",
+    },
+    {
+        class: "modal-dialog",
+        meaning: "May raise an OS modal (build, project upgrade, version mismatch).",
+        bridge: "No first-class dismiss yet (planned); the call can hang on the modal until dismissed.",
+        recovery: "Have an operator dismiss the dialog, or avoid the call in headless contexts. " +
+            "Detect/classify/dismiss policy is forthcoming.",
+    },
+    {
+        class: "scene-dirty",
+        meaning: "Mutates scene / prefab / hierarchy / asset state.",
+        bridge: "Runs the gate (checkpoint → mutate → validate → delta); blocks up to 5s for asset " +
+            "refresh. Requires non-empty paths_hint (no whole-project fallback).",
+        recovery: "Read gate.delta + agentNextSteps from the response. On scene_dirty refusal, save or " +
+            "discard first, or pass ignore_scene_dirty: true to accept the risk.",
+    },
+    {
+        class: "process-stale",
+        meaning: "Long-running / async op where the bridge may become unresponsive.",
+        bridge: "Blocks until the op finishes; the heartbeat may stop advancing during the wait.",
+        recovery: "Treat stale-heartbeat + live-PID as 'still running', not crashed. Wait, then re-probe " +
+            "with ping / editor_status before concluding the bridge died.",
+    },
+];
+export function buildLifecycle() {
+    return {
+        classes: LIFECYCLE_TAXONOMY,
+        guidance: "Each tool carries a `lifecycle` class describing the recovery concern: " +
+            "none (read-only), compile-reload (domain reload; settle + dirty guard), " +
+            "modal-dialog (OS modal; may hang), scene-dirty (gate + paths_hint), or " +
+            "process-stale (long-running; heartbeat may stall). Read it before the " +
+            "call to pick a recovery strategy; `lifecycleNote` carries tool-specific " +
+            "constraints (e.g. compile_check is batch-only).",
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/capabilities/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/capabilities/lifecycle.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,iEAAiE;AACjE,6EAA6E;AAC7E,4EAA4E;AAC5E,sEAAsE;AACtE,4EAA4E;AAC5E,wDAAwD;AACxD,iCAAiC;AACjC,EAAE;AACF,8DAA8D;AAC9D,2EAA2E;AAC3E,gEAAgE;AAChE,gEAAgE;AAChE,0EAA0E;AAC1E,6EAA6E;AAC7E,uEAAuE;AACvE,6EAA6E;AAC7E,0EAA0E;AAC1E,uEAAuE;AACvE,2DAA2D;AAC3D,EAAE;AACF,2EAA2E;AAC3E,kEAAkE;AAyBlE,8EAA8E;AAC9E,yBAAyB;AACzB,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,uDAAuD;AACvD,EAAE;AACF,uEAAuE;AACvE,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,cAAc,GAAkC;IAC3D,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,wEAAwE;IACxE,+BAA+B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC5D,8BAA8B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC3D,6BAA6B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC1D,8BAA8B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC3D,8BAA8B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC3D,6BAA6B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC1D,8BAA8B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC3D,iCAAiC,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC9D,kCAAkC,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC/D,oCAAoC,EAAE;QACpC,KAAK,EAAE,gBAAgB;QACvB,IAAI,EACF,yEAAyE;YACzE,oCAAoC;KACvC;IACD,uEAAuE;IACvE,2EAA2E;IAC3E,2BAA2B,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE;IACxD,0EAA0E;IAC1E,0EAA0E;IAC1E,8BAA8B,EAAE;QAC9B,KAAK,EAAE,gBAAgB;QACvB,IAAI,EACF,uEAAuE;YACvE,uEAAuE;YACvE,sEAAsE;YACtE,qEAAqE;YACrE,sEAAsE;YACtE,mEAAmE;YACnE,kEAAkE;YAClE,0DAA0D;KAC7D;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,8DAA8D;IAC9D,4BAA4B,EAAE;QAC5B,KAAK,EAAE,cAAc;QACrB,IAAI,EACF,mEAAmE;YACnE,+DAA+D;YAC/D,qEAAqE;KACxE;IACD,4BAA4B,EAAE;QAC5B,KAAK,EAAE,gBAAgB;QACvB,IAAI,EACF,sEAAsE;YACtE,uEAAuE;YACvE,oDAAoD;KACvD;IACD,+BAA+B,EAAE;QAC/B,KAAK,EAAE,gBAAgB;QACvB,IAAI,EACF,sEAAsE;YACtE,wBAAwB;KAC3B;IACD,iCAAiC,EAAE;QACjC,KAAK,EAAE,gBAAgB;QACvB,IAAI,EACF,qEAAqE;YACrE,wEAAwE;YACxE,yEAAyE;YACzE,uDAAuD;YACvD,uEAAuE;YACvE,sEAAsE;YACtE,2DAA2D;KAC9D;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,wEAAwE;IACxE,sBAAsB;IACtB,wBAAwB,EAAE;QACxB,KAAK,EAAE,eAAe;QACtB,IAAI,EACF,0EAA0E;YAC1E,uEAAuE;YACvE,mEAAmE;KACtE;IACD,sCAAsC,EAAE;QACtC,KAAK,EAAE,eAAe;QACtB,IAAI,EACF,uEAAuE;YACvE,iEAAiE;KACpE;IACD,sCAAsC,EAAE;QACtC,KAAK,EAAE,eAAe;QACtB,IAAI,EACF,uEAAuE;YACvE,mEAAmE;KACtE;IAED,6EAA6E;IAC7E,0EAA0E;IAC1E,wEAAwE;IACxE,0BAA0B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,cAAc;IACd,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,qBAAqB;IACrB,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,2EAA2E;IAC3E,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,6BAA6B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,6BAA6B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvD,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,mCAAmC;IACnC,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,0BAA0B;IAC1B,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,2DAA2D;IAC3D,6BAA6B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvD,2BAA2B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACrD,6BAA6B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvD,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,4DAA4D;IAC5D,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,iCAAiC,EAAE;QACjC,KAAK,EAAE,aAAa;QACpB,IAAI,EACF,uEAAuE;YACvE,gDAAgD;KACnD;IACD,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,4BAA4B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtD,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,2BAA2B;IAC3B,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,wCAAwC;IACxC,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,2CAA2C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACrE,0EAA0E;IAC1E,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAE7D,4EAA4E;IAC5E,cAAc;IACd,uCAAuC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACjE,6CAA6C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvE,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,+CAA+C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzE,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,iDAAiD,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3E,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,gBAAgB;IAChB,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,0CAA0C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpE,uCAAuC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACjE,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,kDAAkD,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5E,8CAA8C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxE,cAAc;IACd,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,6CAA6C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvE,mBAAmB;IACnB,uCAAuC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACjE,kDAAkD;IAClD,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,WAAW;IACX,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,YAAY;IACZ,0BAA0B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpD,0BAA0B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpD,6BAA6B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACvD,2BAA2B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACrD,SAAS;IACT,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,0CAA0C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpE,aAAa;IACb,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,qBAAqB;IACrB,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,8BAA8B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACxD,WAAW;IACX,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,eAAe;IACf,0CAA0C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpE,wCAAwC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAClE,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,qCAAqC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC/D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,YAAY;IACZ,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,kCAAkC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC5D,uCAAuC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACjE,gCAAgC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC1D,WAAW;IACX,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,iCAAiC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC3D,0CAA0C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpE,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,gBAAgB;IAChB,oCAAoC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC9D,sCAAsC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAChE,0CAA0C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACpE,aAAa;IACb,+BAA+B,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACzD,2CAA2C;IAC3C,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,yCAAyC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACnE,4CAA4C,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IACtE,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,mCAAmC,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE;IAC7D,iCAAiC,EAAE;QACjC,KAAK,EAAE,aAAa;QACpB,IAAI,EACF,wEAAwE;YACxE,iEAAiE;KACpE;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC;AAiBD,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D;QACE,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,+BAA+B;QACxC,MAAM,EAAE,sDAAsD;QAC9D,QAAQ,EACN,kFAAkF;KACrF;IACD;QACE,KAAK,EAAE,gBAAgB;QACvB,OAAO,EAAE,wEAAwE;QACjF,MAAM,EACJ,sFAAsF;QACxF,QAAQ,EACN,oFAAoF;YACpF,oFAAoF;YACpF,gDAAgD;KACnD;IACD;QACE,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,mEAAmE;QAC5E,MAAM,EACJ,uFAAuF;QACzF,QAAQ,EACN,+EAA+E;YAC/E,gDAAgD;KACnD;IACD;QACE,KAAK,EAAE,aAAa;QACpB,OAAO,EAAE,mDAAmD;QAC5D,MAAM,EACJ,oFAAoF;YACpF,qEAAqE;QACvE,QAAQ,EACN,sFAAsF;YACtF,qEAAqE;KACxE;IACD;QACE,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,mEAAmE;QAC5E,MAAM,EACJ,iFAAiF;QACnF,QAAQ,EACN,wFAAwF;YACxF,8DAA8D;KACjE;CACF,CAAC;AAgBF,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,OAAO,EAAE,kBAAkB;QAC3B,QAAQ,EACN,yEAAyE;YACzE,0EAA0E;YAC1E,yEAAyE;YACzE,wEAAwE;YACxE,0EAA0E;YAC1E,iDAAiD;KACpD,CAAC;AACJ,CAAC"}

package/dist/capabilities/rule-catalog.d.ts

@@ -3,11 +3,23 @@ export interface RuleIssueDescriptor {
     /** Issue code emitted by the rule (e.g. `missing_script`). */
     code: string;
     /** Default severity (`Error` | `Warning`). */
-    severity: "Error" | "Warning";
+    severity: "Error" | `Warning`;
     /** Fix IDs that can resolve this issue code, if any. */
     fixIds: string[];
     /** True when the issue is only emitted during a full project scan. */
     fullScanOnly?: boolean;
+    /**
+     * Machine-readable root-cause code (e.g. `missing_guid_reference`,
+     * `duplicate_guid`). Stable across releases — agents branch on it. Mirrors
+     * the C# `IssueExplainability` taxonomy in
+     * `packages/verify/Editor/Core/IssueExplainability.cs`.
+     */
+    rootCause?: string;
+    /**
+     * Short, user-visible remediation playbook for this issue class. Clean of
+     * internal IDs (no milestone / spec / execution-plan references).
+     */
+    remediation?: string;
 }
 export interface RuleCapability {
     id: string;