@mseep/clawdcursor 1.5.5

package/dist/tools/registry.js

@@ -0,0 +1,560 @@
+"use strict";
+/**
+ * Tool Registry — central registry of all clawdcursor tools.
+ *
+ * Import this to get all 40 tools in a transport-agnostic format.
+ * Adapters (HTTP, MCP) consume this registry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCompactTools = exports.toJsonSchema = exports.toOpenAiFunctions = void 0;
+exports.getTools = getTools;
+exports.getAllTools = getAllTools;
+exports.getCompactSurface = getCompactSurface;
+exports.getToolsByCategory = getToolsByCategory;
+exports.getTool = getTool;
+const desktop_1 = require("./desktop");
+const a11y_1 = require("./a11y");
+const cdp_1 = require("./cdp");
+const orchestration_1 = require("./orchestration");
+const batch_1 = require("./batch");
+const shortcuts_1 = require("./shortcuts");
+const ocr_1 = require("./ocr");
+const smart_1 = require("./smart");
+const extras_1 = require("./extras");
+const a11y_depth_1 = require("./a11y_depth");
+const electron_bridge_1 = require("./electron_bridge");
+const compact_1 = require("./compact");
+Object.defineProperty(exports, "getCompactTools", { enumerable: true, get: function () { return compact_1.getCompactTools; } });
+const agent_1 = require("./agent");
+const favorites_1 = require("./favorites");
+const scheduler_1 = require("./scheduler");
+const introspection_1 = require("./introspection");
+const types_1 = require("./types");
+Object.defineProperty(exports, "toOpenAiFunctions", { enumerable: true, get: function () { return types_1.toOpenAiFunctions; } });
+Object.defineProperty(exports, "toJsonSchema", { enumerable: true, get: function () { return types_1.toJsonSchema; } });
+const cost_class_1 = require("./cost-class");
+const tools_1 = require("../core/agent-loop/tools");
+const project_mcp_1 = require("../core/agent-loop/project-mcp");
+// ─── Step 3: Window-management re-projection ─────────────────────────────────
+//
+// These System A MCP names are now backed by System B (buildUnifiedTools)
+// implementations. The System A handler functions in a11y.ts / extras.ts are
+// intentionally NOT deleted yet (Step 8 handles that); only the registry
+// routing changes here.
+//
+// Tools WITHOUT a System B equivalent are left on the System A path:
+//   • get_active_window  — no System B counterpart in buildUnifiedTools()
+//   • get_screen_size    — no System B counterpart in buildUnifiedTools()
+//
+// System B tool name → projected MCP name (via TOOL_META.mcpName):
+//   list_windows       → get_windows
+//   focus_window       → focus_window
+//   maximize_window    → maximize_window
+//   minimize_window    → minimize_window_to_taskbar  (mcpName in TOOL_META)
+//   restore_window     → restore_window
+//   close_window       → close_window
+//   resize_window      → resize_window
+//   list_displays      → list_displays
+/** System B names of the window tools to re-project onto the MCP surface. */
+const WINDOW_SYSB_NAMES = new Set([
+    'list_windows',
+    'focus_window',
+    'maximize_window',
+    'minimize_window',
+    'restore_window',
+    'close_window',
+    'resize_window',
+    'list_displays',
+]);
+/** MCP names that the projected window tools will carry (after mcpName rename). */
+const WINDOW_MCP_NAMES = new Set([
+    'get_windows',
+    'focus_window',
+    'maximize_window',
+    'minimize_window_to_taskbar',
+    'restore_window',
+    'close_window',
+    'resize_window',
+    'list_displays',
+]);
+/** Build projected window ToolDefinitions from System B (cached). */
+let _projectedWindowCache = null;
+function projectedWindowTools() {
+    if (_projectedWindowCache === null) {
+        const sysBTools = (0, tools_1.buildUnifiedTools)();
+        _projectedWindowCache = sysBTools
+            .filter(t => WINDOW_SYSB_NAMES.has(t.name))
+            .map(t => (0, project_mcp_1.projectToToolDefinition)(t));
+    }
+    return _projectedWindowCache;
+}
+// ─── Step 5: Mouse group re-projection ───────────────────────────────────────
+//
+// MCP tools mouse_click, mouse_drag, mouse_scroll, mouse_move_relative,
+// mouse_down, mouse_up are re-projected from System B equivalents:
+//   click, drag, scroll, mouse_move_relative, mouse_down, mouse_up.
+//
+// COORDINATE-SPACE BACKWARD COMPATIBILITY
+// ----------------------------------------
+// The CURRENT System A mouse tools (desktop.ts) treat x/y as IMAGE-space
+// (screenshot pixels) and always scale to physical via getMouseScaleFactor().
+// External agents send image-space coords derived from the most-recent
+// screenshot, so omitting `space` must still produce image-space scaling.
+//
+// System B granular tools default to `space:'screen'` when the arg is absent
+// (accessibility-snapshot coords, no scaling). That default is WRONG for the
+// MCP surface where callers never pass `space` — it would silently break all
+// existing external agents on HiDPI/multi-monitor setups.
+//
+// FIX: for the coord-sensitive tools (click, drag, scroll) the projected
+// handler injects `space:'image'` when the caller omits it, preserving the
+// exact image→physical scaling that System A always applied.
+//
+// INTENDED BEHAVIOR CHANGE (bug fix)
+// ------------------------------------
+// Callers that now pass `space:'screen'` (e.g. a11y-snapshot coords) will
+// NOT be double-scaled. Previously, System A always scaled regardless of
+// origin — so a caller using a11y coords had to compensate. This is the one
+// intentional change; see CHANGELOG.md under Unreleased/v2.
+//
+// Tools WITHOUT a System B equivalent are left on System A:
+//   • mouse_hover          — no System B hover tool
+//   • mouse_double_click   — System B click counts differ in schema shape
+//   • mouse_right_click    — System B click button param differs in schema shape
+//   • mouse_middle_click   — no System B equivalent
+//   • mouse_triple_click   — no System B equivalent
+//   • mouse_scroll_horizontal — no System B equivalent
+//   • mouse_drag_stepped   — no System B equivalent
+//
+// System B tool name → projected MCP name (via TOOL_META mcpName):
+//   click             → mouse_click
+//   drag              → mouse_drag
+//   scroll            → mouse_scroll
+//   mouse_move_relative → mouse_move_relative  (name unchanged)
+//   mouse_down        → mouse_down            (name unchanged)
+//   mouse_up          → mouse_up              (name unchanged)
+/** System B names of the mouse tools to re-project onto the MCP surface. */
+const MOUSE_SYSB_NAMES = new Set([
+    'click',
+    'drag',
+    'scroll',
+    'mouse_move_relative',
+    'mouse_down',
+    'mouse_up',
+]);
+/** MCP names that the projected mouse tools will carry (after mcpName rename). */
+const MOUSE_MCP_NAMES = new Set([
+    'mouse_click',
+    'mouse_drag',
+    'mouse_scroll',
+    'mouse_move_relative',
+    'mouse_down',
+    'mouse_up',
+]);
+/**
+ * Names of the coord-sensitive System B mouse tools (click/drag/scroll) that
+ * need an image-space default injected for MCP backward compatibility.
+ */
+const COORD_SENSITIVE_SYSB_NAMES = new Set(['click', 'drag', 'scroll']);
+/** Build projected mouse ToolDefinitions from System B (cached). */
+let _projectedMouseCache = null;
+function projectedMouseTools() {
+    if (_projectedMouseCache !== null)
+        return _projectedMouseCache;
+    const sysBTools = (0, tools_1.buildUnifiedTools)();
+    _projectedMouseCache = sysBTools
+        .filter(t => MOUSE_SYSB_NAMES.has(t.name))
+        .map(t => {
+        const base = (0, project_mcp_1.projectToToolDefinition)(t);
+        // mouse_move_relative: System A scaled dx/dy by the DPI factor; System B
+        // passes them raw. Restore the scaling on the MCP surface so relative
+        // moves don't undershoot 2-3x on HiDPI/retina screens. MCP-only — the
+        // internal agent keeps System B's raw behavior.
+        if (t.name === 'mouse_move_relative') {
+            const sysBHandler = base.handler;
+            return {
+                ...base,
+                handler: (params, ctx) => {
+                    const sf = ctx.getMouseScaleFactor();
+                    const dx = Number(params.dx);
+                    const dy = Number(params.dy);
+                    const scaled = { ...params };
+                    if (Number.isFinite(dx))
+                        scaled.dx = Math.round(dx * sf);
+                    if (Number.isFinite(dy))
+                        scaled.dy = Math.round(dy * sf);
+                    return sysBHandler(scaled, ctx);
+                },
+            };
+        }
+        if (!COORD_SENSITIVE_SYSB_NAMES.has(t.name)) {
+            // mouse_down, mouse_up — button-only, no coords to scale.
+            return base;
+        }
+        // click / drag / scroll: wrap the handler so omitting `space` defaults
+        // to 'image' (image-space scaling) rather than System B's 'screen' default.
+        // This keeps every existing external MCP caller unaffected — they never
+        // pass `space` and expect their screenshot coords to be scaled.
+        // When a caller explicitly passes `space:'screen'` (a11y-sourced coords),
+        // they get pass-through — the intended double-scale bug fix.
+        //
+        // Correct the published `space` description too: System B's own schema
+        // text says "screen (default)", which is the INTERNAL default and the
+        // opposite of the MCP projection's default (image). An agent reading the
+        // MCP schema must see the accurate contract or it double-scales a11y coords.
+        if (base.parameters.space) {
+            base.parameters.space.description =
+                'Coordinate space. Omit (default) → image-space coords from the latest screenshot (scaled to physical pixels). Pass "screen" → a11y-snapshot coords (already physical, not scaled).';
+        }
+        const sysBHandler = base.handler;
+        return {
+            ...base,
+            handler: (params, ctx) => {
+                const withDefault = params.space === undefined
+                    ? { ...params, space: 'image' }
+                    : params;
+                return sysBHandler(withDefault, ctx);
+            },
+        };
+    });
+    return _projectedMouseCache;
+}
+// ─── Step 6: Accessibility / Perception group re-projection ─────────────────
+//
+// The following MCP tools are now backed by System B (buildUnifiedTools)
+// implementations, routed through the uniform projectToToolDefinition path:
+//
+//   System B name    → MCP name          (via TOOL_META mcpName / identity)
+//   read_screen      → read_screen       (name unchanged)
+//   invoke_element   → invoke_element    (name unchanged)
+//   set_field_value  → set_field_value   (name unchanged)
+//   focus_element    → focus_element     (name unchanged)
+//   a11y_get_value   → a11y_get_value    (name unchanged)
+//   a11y_expand      → a11y_expand       (name unchanged)
+//   a11y_collapse    → a11y_collapse     (name unchanged)
+//   a11y_toggle      → a11y_toggle       (name unchanged)
+//   a11y_select      → a11y_select       (name unchanged)
+//   get_element_state → get_element_state (name unchanged)
+//   wait_for_element → wait_for_element  (name unchanged)
+//   (ocr_read_screen stays on System A — structured OCR output for external agents)
+//
+// BEHAVIOR UPGRADE (desirable)
+// ─────────────────────────────
+// System B's a11y tools (a11y_expand, a11y_collapse, a11y_toggle, a11y_select,
+// a11y_get_value, get_element_state) call resolveAgentPid() which auto-scopes
+// to the active window pid when processId is omitted. This is strictly better
+// than the System A behavior (which walked the full system tree).
+//
+// PARAM RECONCILIATION
+// ─────────────────────
+// invoke_element: System A had automationId + action params absent in System B.
+//   → Both have been added to the System B tool (tools.ts) so the MCP schema
+//     is backward-compatible. No behavior is silently dropped.
+//   → automationId note: PlatformAdapter.invokeElement does not expose
+//     automationId in its query type. When only automationId is supplied,
+//     it is used as the name for the search (functional fallback). Document
+//     in CHANGELOG that automationId-only matching is name-based in v2.
+//
+// set_field_value: System A (a11y_depth.ts) had controlType param absent in
+//   the System B version.
+//   → controlType added to the System B tool (tools.ts) for backward-compat.
+//
+// ocr_read_screen: KEPT ON SYSTEM A. System A returns structured JSON
+//   (elements[] + bounds + fullText + dpiRatio + coordinateSystem) which
+//   external agents rely on to locate-and-click OCR'd text. System B's
+//   read_text returns lean plain text built for the in-context LLM — a
+//   downgrade for the MCP surface — so it is not projected. No format change.
+//
+// TOOLS LEFT ON SYSTEM A (no System B buildUnifiedTools() equivalent, or
+// compact-surface invariant test requires no compactGroup):
+//   • find_element        — not in buildUnifiedTools()
+//   • get_focused_element — not in buildUnifiedTools()
+//   • a11y_get_element    — not in buildUnifiedTools()
+//   • a11y_list_children  — not in buildUnifiedTools()
+//   • smart_type          — not in buildUnifiedTools()
+//   • smart_read          — not in buildUnifiedTools()
+//   • smart_click         — System B has a smart_click but TOOL_META assigns
+//                           compactGroup:'computer', which breaks the compact-
+//                           surface invariant test (test section 10 requires
+//                           smart_click to have NO compactGroup). Left on
+//                           System A to preserve the invariant.
+/** System B names of the a11y / perception tools to re-project onto the MCP surface. */
+const A11Y_SYSB_NAMES = new Set([
+    'read_screen',
+    'invoke_element',
+    'set_field_value',
+    'focus_element',
+    'a11y_get_value',
+    'a11y_expand',
+    'a11y_collapse',
+    'a11y_toggle',
+    'a11y_select',
+    'get_element_state',
+    'wait_for_element',
+    'verify',
+    'compile_ui',
+    'find_action_button',
+    'find_input_field',
+    // NOTE: `read_text` (System B) is intentionally NOT projected. Its lean
+    // `@x,y "text"` output is built for the in-context LLM. The MCP surface keeps
+    // System A's `ocr_read_screen`, whose structured JSON (elements[] + bounds +
+    // coordinateSystem) is what external agents need to locate-and-click OCR text.
+]);
+/** MCP names that the projected a11y tools will carry (after mcpName rename). */
+const A11Y_MCP_NAMES = new Set([
+    'read_screen',
+    'invoke_element',
+    'set_field_value',
+    'focus_element',
+    'a11y_get_value',
+    'a11y_expand',
+    'a11y_collapse',
+    'a11y_toggle',
+    'a11y_select',
+    'get_element_state',
+    'wait_for_element',
+    'verify',
+    'compile_ui',
+    'find_action_button',
+    'find_input_field',
+    // `ocr_read_screen` stays on System A (structured OCR output) — see above.
+]);
+/** Build projected a11y/perception ToolDefinitions from System B (cached). */
+let _projectedA11yCache = null;
+function projectedA11yTools() {
+    if (_projectedA11yCache !== null)
+        return _projectedA11yCache;
+    const sysBTools = (0, tools_1.buildUnifiedTools)();
+    _projectedA11yCache = sysBTools
+        .filter(t => A11Y_SYSB_NAMES.has(t.name))
+        .map(t => (0, project_mcp_1.projectToToolDefinition)(t));
+    return _projectedA11yCache;
+}
+// ─── Step 7: CDP / Browser group re-projection ───────────────────────────────
+//
+// 5 of the 12 current browser-category MCP tools map to System B browser_*
+// equivalents via TOOL_META. Per-tool comparison:
+//
+//   cdp_connect (System A):
+//     • Calls ctx.cdp.connect() — attaches to existing CDP session, no auto-launch.
+//     • Output: { text: "Connected to: … at …" } (no usage hint).
+//   browser_connect (System B) → cdp_connect:
+//     • Calls ctx.cdp.ensureConnected({launch, exePaths}) — auto-launches Edge/Chrome
+//       via getEdgePaths()/getChromePaths() if not already connected.
+//     • Output: includes "Use browser_navigate…" guidance.
+//     VERDICT: MIGRATE — System B is strictly BETTER (auto-launch + guidance).
+//
+//   cdp_page_context (System A):
+//     • No params; always calls ctx.cdp.getPageContext() → structured interactive-
+//       element list (links/buttons/inputs with selectors).
+//   browser_read (System B) → cdp_page_context:
+//     • Optional `selector` param; no selector → getPageContext() (SAME output);
+//       with selector → ctx.cdp.readText(selector, 3000) (additive).
+//     VERDICT: MIGRATE — System B is EQUAL-OR-BETTER (adds selector param; no-param
+//     path returns identical structured list).
+//
+//   cdp_click (System A):
+//     • selector OR text; same click logic.
+//   browser_click (System B) → cdp_click:
+//     • Same params (text preferred, selector alternative). Same click logic.
+//     • Error message adds "Call browser_read to see the actual elements" guidance.
+//     VERDICT: MIGRATE — System B is EQUAL (same params, marginally better errors).
+//
+//   cdp_type (System A):
+//     • selector OR label, text required.
+//   browser_type (System B) → cdp_type:
+//     • Same params (text required, selector OR label). Same type logic.
+//     VERDICT: MIGRATE — System B is EQUAL.
+//
+//   navigate_browser (System A):
+//     • safetyTier 2, category 'orchestration'. LAUNCHES the browser with
+//       --remote-debugging-port and then optionally navigates. This is the
+//       dedicated browser-launcher tool; external agents call it to start CDP.
+//   browser_navigate (System B) → navigate_browser:
+//     • safetyTier 1, category 'browser'. Navigates within an ALREADY-CONNECTED
+//       browser; requires a prior browser_connect call.
+//     VERDICT: DO NOT MIGRATE. The System B version would silently strip the
+//       browser-launch capability from navigate_browser — an external agent calling
+//       navigate_browser to start the browser would get "not connected" instead of
+//       a running browser. The launch semantics must not change.
+//
+// TOOLS LEFT ON SYSTEM A (no System B equivalent):
+//   • navigate_browser  — dedicated browser launcher (see above)
+//   • cdp_read_text     — has maxLength param; browser_read lacks it; also maps
+//                         to a different MCP name (cdp_page_context)
+//   • cdp_select_option — no System B equivalent in buildUnifiedTools()
+//   • cdp_evaluate      — no System B equivalent
+//   • cdp_wait_for_selector — no System B equivalent
+//   • cdp_list_tabs     — no System B equivalent
+//   • cdp_switch_tab    — no System B equivalent
+//   • cdp_scroll        — no System B equivalent
+//
+// DOCUMENTED BEHAVIOR CHANGES (see CHANGELOG.md [Unreleased] — v2):
+//   • cdp_connect now auto-launches Edge/Chrome when not connected (was attach-only).
+//   • cdp_page_context gains an optional `selector` param; callers that pass a CSS
+//     selector now get plain text for that element instead of the full interactive-
+//     element list. Callers that pass no params are unaffected.
+/** System B names of the CDP/browser tools to re-project onto the MCP surface. */
+const BROWSER_SYSB_NAMES = new Set([
+    'browser_connect',
+    'browser_read',
+    'browser_click',
+    'browser_type',
+    // NOTE: 'browser_navigate' is intentionally NOT included.
+    // TOOL_META maps it to 'navigate_browser' but the System A navigate_browser is
+    // the browser LAUNCHER (safetyTier 2, category 'orchestration'). Projecting
+    // browser_navigate would silently strip the launch capability. Keep on System A.
+]);
+/** MCP names that the projected browser tools will carry (after mcpName rename). */
+const BROWSER_MCP_NAMES = new Set([
+    'cdp_connect',
+    'cdp_page_context',
+    'cdp_click',
+    'cdp_type',
+    // 'navigate_browser' is NOT in this set — it stays on System A.
+]);
+/** Build projected CDP/browser ToolDefinitions from System B (cached). */
+let _projectedBrowserCache = null;
+function projectedBrowserTools() {
+    if (_projectedBrowserCache !== null)
+        return _projectedBrowserCache;
+    const sysBTools = (0, tools_1.buildUnifiedTools)();
+    _projectedBrowserCache = sysBTools
+        .filter(t => BROWSER_SYSB_NAMES.has(t.name))
+        .map(t => (0, project_mcp_1.projectToToolDefinition)(t));
+    return _projectedBrowserCache;
+}
+// ─── Step 4: Keyboard group re-projection ────────────────────────────────────
+//
+// MCP tools type_text, key_press, key_down, key_up, undo_last are re-projected
+// from System B equivalents: type, key, key_down, key_up, undo_last.
+//
+// ALL five tools use the generic projectToToolDefinition() bridge so every
+// handler runs through toolContextToAgent(ctx) → ctx.platform.* — the real
+// runtime path. System B's `key` tool already carries all necessary fixes:
+//   (a) missing-arg guard
+//   (b) space-separated key sequences
+//   (c) BLOCKED_KEYS guard
+//   (d) `key` alias for `combo` (backward-compat)
+// System B's `type` tool already uses the clipboard fast-path.
+//
+// System B tool name → projected MCP name (via TOOL_META mcpName):
+//   type       → type_text
+//   key        → key_press
+//   key_down   → key_down   (name unchanged)
+//   key_up     → key_up     (name unchanged)
+//   undo_last  → undo_last  (name unchanged)
+/** System B names of the keyboard tools to re-project onto the MCP surface. */
+const KEYBOARD_SYSB_NAMES = new Set(['type', 'key', 'key_down', 'key_up', 'undo_last']);
+/** MCP names that the projected keyboard tools will carry. */
+const KEYBOARD_MCP_NAMES = new Set([
+    'type_text',
+    'key_press',
+    'key_down',
+    'key_up',
+    'undo_last',
+]);
+/** Build projected keyboard ToolDefinitions from System B (cached). */
+let _projectedKeyboardCache = null;
+function projectedKeyboardTools() {
+    if (_projectedKeyboardCache !== null)
+        return _projectedKeyboardCache;
+    const sysBTools = (0, tools_1.buildUnifiedTools)();
+    _projectedKeyboardCache = sysBTools
+        .filter(t => KEYBOARD_SYSB_NAMES.has(t.name))
+        .map(t => (0, project_mcp_1.projectToToolDefinition)(t));
+    return _projectedKeyboardCache;
+}
+/**
+ * Unified tool accessor. Replaces the ad-hoc getAllTools() /
+ * getCompactSurface() pair — those remain as thin back-compat wrappers.
+ *
+ * Examples:
+ *   getTools()                                  → all granular tools
+ *   getTools({ palette: 'compact' })            → 6 compact compound tools
+ *   getTools({ compactGroup: 'computer' })      → granular tools owned by computer
+ *   getTools({ palette: 'granular', compactGroup: 'accessibility' })
+ */
+// The granular tool definitions are static (built from module-level
+// get*Tools() functions, no runtime registration), so assemble the array
+// once and reuse it. Before this, every getTool()/getTools() call rebuilt
+// the whole 14-source array — and getTool() is on the hot dispatch path.
+let _granularCache = null;
+function granularTools() {
+    if (_granularCache === null) {
+        // Assemble all System A tools, then substitute the window group (Step 3),
+        // the keyboard group (Step 4), the mouse group (Step 5), the a11y /
+        // perception group (Step 6), and the CDP / browser group (Step 7) with
+        // projected System B tools. System A tools whose MCP names appear in any
+        // of the five exclusion sets are filtered out before projected tools are
+        // appended to avoid duplicates.
+        const systemATools = [
+            ...(0, desktop_1.getDesktopTools)(),
+            ...(0, a11y_1.getA11yTools)(),
+            ...(0, cdp_1.getCdpTools)(),
+            ...(0, orchestration_1.getOrchestrationTools)(),
+            ...(0, batch_1.getBatchTools)(),
+            ...(0, shortcuts_1.getShortcutTools)(),
+            ...(0, ocr_1.getOcrTools)(),
+            ...(0, smart_1.getSmartTools)(),
+            ...(0, extras_1.getExtraTools)(),
+            ...(0, a11y_depth_1.getA11yDepthTools)(),
+            ...(0, electron_bridge_1.getElectronBridgeTools)(),
+            ...(0, agent_1.getAgentTools)(),
+            ...(0, favorites_1.getFavoritesTools)(),
+            ...(0, scheduler_1.getSchedulerTools)(),
+            ...(0, introspection_1.getIntrospectionTools)(),
+        ].filter(t => !WINDOW_MCP_NAMES.has(t.name) &&
+            !KEYBOARD_MCP_NAMES.has(t.name) &&
+            !MOUSE_MCP_NAMES.has(t.name) &&
+            !A11Y_MCP_NAMES.has(t.name) &&
+            !BROWSER_MCP_NAMES.has(t.name));
+        _granularCache = [
+            ...systemATools,
+            ...projectedWindowTools(),
+            ...projectedKeyboardTools(),
+            ...projectedMouseTools(),
+            ...projectedA11yTools(),
+            ...projectedBrowserTools(),
+        ];
+    }
+    return _granularCache;
+}
+function getTools(options) {
+    const palette = options?.palette ?? 'granular';
+    if (palette === 'compact') {
+        return (0, compact_1.getCompactTools)();
+    }
+    const all = granularTools();
+    // Phase A: stamp token-cost metadata from the central table so every
+    // consumer (tools/list, coverage test, runtime hints) sees `costClass`.
+    (0, cost_class_1.stampCostClasses)(all);
+    if (options?.compactGroup) {
+        return all.filter(t => t.compactGroup === options.compactGroup);
+    }
+    // Return a shallow copy so callers can't mutate the cached array.
+    return all.slice();
+}
+/** Get all registered GRANULAR tools (the full primitive surface). Back-compat wrapper around getTools(). */
+function getAllTools() {
+    return getTools();
+}
+/**
+ * Get the COMPACT surface — 6 compound tools covering every granular
+ * primitive. Equivalent semantics; ~1/12th the catalog tokens. Use via
+ * `clawdcursor mcp --compact` or `GET /tools?mode=compact`.
+ * Back-compat wrapper around getTools({ palette: 'compact' }).
+ */
+function getCompactSurface() {
+    return getTools({ palette: 'compact' });
+}
+/** Get tools by category */
+function getToolsByCategory(category) {
+    return getAllTools().filter(t => t.category === category);
+}
+/** Get a tool by name */
+function getTool(name) {
+    // Search the cached array directly — no copy, no rebuild (hot path).
+    return granularTools().find(t => t.name === name);
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/dist/tools/safety-gate.d.ts

@@ -0,0 +1,16 @@
+import type { ToolDefinition, ToolResult } from './types';
+import type { UIMapHolder } from '../core/sense/ui-map-holder';
+/**
+ * Enforce the canonical safety gate before direct MCP/REST tool handlers run.
+ *
+ * Uses `evaluateInput` from `pipeline/safety/layer` — the single source of
+ * truth for allow/block decisions.  Passes `tool.safetyTier` when present so
+ * the gate consults the tool's own declared tier rather than guessing from
+ * the name string.
+ *
+ * Returns null when the tool is allowed; returns an error ToolResult when
+ * blocked or requiring confirmation.
+ */
+export declare function evaluateToolCall(tool: ToolDefinition, args: Record<string, unknown>, opts?: {
+    uiMaps?: UIMapHolder;
+}): ToolResult | null;

package/dist/tools/safety-gate.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateToolCall = evaluateToolCall;
+const safety_1 = require("../core/safety");
+function labelFromArgs(args, uiMaps) {
+    const candidates = [
+        args.target,
+        args.name,
+        args.text,
+        args.label,
+        args.title,
+        args.selector,
+    ];
+    const value = candidates.find(v => typeof v === 'string' && v.trim().length > 0);
+    if (typeof value === 'string')
+        return value;
+    // el_NN refs carry no name/target — resolve the element's label from the
+    // holder so the destructive-label rule (Send/Delete/Pay…) still fires on
+    // the MCP route's ref path. Stale/unknown snapshot → no label → the blunt
+    // no-label rule stays in effect (safe default). Audit 2026-06-10, finding E.
+    if (uiMaps && typeof args.element_id === 'string' && typeof args.snapshot_id === 'string') {
+        const r = uiMaps.resolve(args.snapshot_id, Date.now());
+        if (r.ok) {
+            const el = r.map.elements.find(e => e.id === args.element_id);
+            const label = el?.text ?? el?.normalized_text;
+            if (typeof label === 'string' && label.trim().length > 0)
+                return label;
+        }
+    }
+    return undefined;
+}
+/**
+ * Enforce the canonical safety gate before direct MCP/REST tool handlers run.
+ *
+ * Uses `evaluateInput` from `pipeline/safety/layer` — the single source of
+ * truth for allow/block decisions.  Passes `tool.safetyTier` when present so
+ * the gate consults the tool's own declared tier rather than guessing from
+ * the name string.
+ *
+ * Returns null when the tool is allowed; returns an error ToolResult when
+ * blocked or requiring confirmation.
+ */
+function evaluateToolCall(tool, args, opts) {
+    const decision = (0, safety_1.evaluateInput)({
+        toolName: tool.name,
+        args,
+        safetyTier: tool.safetyTier,
+        ctx: {
+            targetLabel: labelFromArgs(args, opts?.uiMaps),
+        },
+    });
+    if (decision.allow)
+        return null;
+    const suggestedAction = decision.suggestedAction ?? 'block';
+    const reason = decision.reason ?? `${tool.name} requires user approval`;
+    if (suggestedAction === 'block') {
+        return {
+            text: `${tool.name}: safety block - ${reason}`,
+            isError: true,
+        };
+    }
+    // confirm / warn path
+    return {
+        text: `${tool.name}: safety confirm - ${reason} (requires user confirmation). ` +
+            `Next step: surface this to the user and wait for approval — re-issuing the same call will just block again. ` +
+            `If the user already authorized this intent, run the step inside \`batch({allowConfirm:true})\`.`,
+        isError: true,
+    };
+}
+//# sourceMappingURL=safety-gate.js.map