@mseep/clawdcursor 1.5.5

package/dist/tools/playbooks/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Playbook registry.
+ *
+ * Playbooks are app-AGNOSTIC keyboard choreographies for known capability
+ * shapes the vision loop would otherwise re-discover on every run. They
+ * are NOT app-specific shortcuts. Each playbook implements ONE capability
+ * (e.g. "compose+submit a form with To/Subject/Body fields") and works
+ * across every app that follows the same UX convention.
+ *
+ * Dispatch: matchPlaybook routes by CAPABILITY (the user's intent),
+ * never by app name. This is the key rule: if the same user intent
+ * routes to two different playbooks because the active app changed,
+ * the playbooks should be merged.
+ *
+ * Dispatched by the pipeline as a first-class Strategy ('playbook') sitting
+ * between the router and the LLM ladder; NOT exposed on the public MCP
+ * surface. compose-send specifically prefers the OS protocol-handler path
+ * (mailto://, tel://, slack://, vscode://, ...) via
+ * resolveSchemeHandlerExecutable + launchHandlerAndVerify; the in-app
+ * keyboard choreography here is the fallback when no protocol handler is
+ * registered or the dispatched window never appears.
+ *
+ * Each playbook is a pure function over PlatformAdapter + args. No
+ * per-playbook state, no retries (that's the verifier's job).
+ */
+import type { PlatformAdapter } from '../../platform/types';
+import { findReplace } from './find-replace';
+export interface PlaybookResult {
+    success: boolean;
+    /** One-line description for logs + verifier context. */
+    text: string;
+    /** Trace of executed steps for skill-cache recording. */
+    steps: Array<{
+        type: 'click' | 'type' | 'key' | 'scroll' | 'wait';
+        description: string;
+        [k: string]: unknown;
+    }>;
+}
+export interface PlaybookArgs {
+    adapter: PlatformAdapter;
+    /** Free-form args (recipient, subject, body, findText, etc.). */
+    input: Record<string, string | undefined>;
+}
+export type Playbook = (args: PlaybookArgs) => Promise<PlaybookResult>;
+/**
+ * Capability-keyed playbook registry. Keys describe the INTENT, not the
+ * app. New playbooks SHOULD be added if they generalize across apps;
+ * playbooks that name an app are an antipattern and should be merged
+ * into a capability-keyed sibling.
+ */
+export declare const PLAYBOOKS: Record<string, Playbook>;
+/**
+ * Match a task to a playbook name by CAPABILITY ONLY. activeApp is
+ * intentionally not consulted \u2014 if the same intent needs two different
+ * playbooks for two different apps, merge them. The first-class path
+ * for email is open_uri(mailto: ...); we offer compose-send as the
+ * in-UI fallback when the user explicitly wants to compose in-app.
+ *
+ * Returns null when nothing matches \u2014 caller proceeds with the
+ * text-agent's normal a11y-driven flow.
+ */
+export declare function matchPlaybook(task: string, _activeApp: string): string | null;
+export { findReplace };

package/dist/tools/playbooks/index.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Playbook registry.
+ *
+ * Playbooks are app-AGNOSTIC keyboard choreographies for known capability
+ * shapes the vision loop would otherwise re-discover on every run. They
+ * are NOT app-specific shortcuts. Each playbook implements ONE capability
+ * (e.g. "compose+submit a form with To/Subject/Body fields") and works
+ * across every app that follows the same UX convention.
+ *
+ * Dispatch: matchPlaybook routes by CAPABILITY (the user's intent),
+ * never by app name. This is the key rule: if the same user intent
+ * routes to two different playbooks because the active app changed,
+ * the playbooks should be merged.
+ *
+ * Dispatched by the pipeline as a first-class Strategy ('playbook') sitting
+ * between the router and the LLM ladder; NOT exposed on the public MCP
+ * surface. compose-send specifically prefers the OS protocol-handler path
+ * (mailto://, tel://, slack://, vscode://, ...) via
+ * resolveSchemeHandlerExecutable + launchHandlerAndVerify; the in-app
+ * keyboard choreography here is the fallback when no protocol handler is
+ * registered or the dispatched window never appears.
+ *
+ * Each playbook is a pure function over PlatformAdapter + args. No
+ * per-playbook state, no retries (that's the verifier's job).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findReplace = exports.PLAYBOOKS = void 0;
+exports.matchPlaybook = matchPlaybook;
+const find_replace_1 = require("./find-replace");
+Object.defineProperty(exports, "findReplace", { enumerable: true, get: function () { return find_replace_1.findReplace; } });
+/**
+ * Capability-keyed playbook registry. Keys describe the INTENT, not the
+ * app. New playbooks SHOULD be added if they generalize across apps;
+ * playbooks that name an app are an antipattern and should be merged
+ * into a capability-keyed sibling.
+ */
+// NOTE: 'compose-send' is intentionally NOT in this registry. matchPlaybook
+// still routes mail intents to the 'compose-send' KEY, but the pipeline
+// special-cases that key to its OS-`mailto:` path (app-agnostic) and, on miss,
+// defers to the perception agent — there is no in-app keyboard choreography to
+// register here. Registry-dispatched playbooks must be genuinely app-agnostic.
+exports.PLAYBOOKS = {
+    'find-replace': find_replace_1.findReplace,
+};
+/**
+ * Match a task to a playbook name by CAPABILITY ONLY. activeApp is
+ * intentionally not consulted \u2014 if the same intent needs two different
+ * playbooks for two different apps, merge them. The first-class path
+ * for email is open_uri(mailto: ...); we offer compose-send as the
+ * in-UI fallback when the user explicitly wants to compose in-app.
+ *
+ * Returns null when nothing matches \u2014 caller proceeds with the
+ * text-agent's normal a11y-driven flow.
+ */
+function matchPlaybook(task, _activeApp) {
+    const t = task.toLowerCase();
+    // Compose + submit form (mail, message, or any compose-style flow).
+    // Matches any intent that asks to compose AND send/submit AND has a
+    // recipient-like noun. Pure regex \u2014 no app names.
+    if (/\bsend\b.*\b(email|message|mail|note|invite)\b|\bcompose\b.*\b(email|message|mail)\b|\bsend\s+to\s+\S+@/i.test(t)) {
+        return 'compose-send';
+    }
+    // Find & replace \u2014 universal across text editors, IDEs, browsers, docs.
+    if (/\bfind\s+and\s+replace\b|\breplace\s+all\b/i.test(t)) {
+        return 'find-replace';
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/playbooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/playbooks/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;AA8CH,sCAgBC;AA3DD,iDAA6C;AA6DpC,4FA7DA,0BAAW,OA6DA;AA3CpB;;;;;GAKG;AACH,4EAA4E;AAC5E,wEAAwE;AACxE,+EAA+E;AAC/E,+EAA+E;AAC/E,+EAA+E;AAClE,QAAA,SAAS,GAA6B;IACjD,cAAc,EAAE,0BAAW;CAC5B,CAAC;AAEF;;;;;;;;;GASG;AACH,SAAgB,aAAa,CAAC,IAAY,EAAE,UAAkB;IAC5D,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAE7B,oEAAoE;IACpE,oEAAoE;IACpE,uDAAuD;IACvD,IAAI,0GAA0G,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACvH,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,6EAA6E;IAC7E,IAAI,6CAA6C,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/playbooks/keys-blocklist.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Destructive-key blocklist.
+ *
+ * v0.8.0 shipped a 3-entry list (alt+f4, ctrl+alt+delete, ctrl+alt+del).
+ * The audit flagged this as cosmetic. v0.8.1 expands to the full known
+ * destructive set with whitespace-normalized matching so "alt +f4" also
+ * blocks.
+ *
+ * Used by the SafetyLayer. Adding a combo here blocks it across EVERY
+ * path (text-agent, vision-agent, MCP direct, REST /action, playbooks).
+ */
+/** Normalize a user-supplied combo for comparison — lowercase, trim, collapse whitespace, resolve `mod`. */
+export declare function normalizeCombo(combo: string): string;
+export type KeyBlockTier = 'block' | 'confirm' | null;
+/** Classify a combo: 'block' (hard, no path), 'confirm' (allowConfirm-able), or null (free). */
+export declare function keyBlockTier(combo: string): KeyBlockTier;
+/** Truthful reason for the given tier. */
+export declare function keyBlockReason(combo: string, tier: 'block' | 'confirm'): string;
+/** The read-only normalized HARD-block set. */
+export declare const BLOCKED_KEYS: ReadonlySet<string>;
+/** True only for HARD-blocked combos (no confirm path). */
+export declare function isBlockedKey(combo: string): boolean;
+/** Reason string for a HARD block. */
+export declare function blockReason(combo: string): string;

package/dist/tools/playbooks/keys-blocklist.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Destructive-key blocklist.
+ *
+ * v0.8.0 shipped a 3-entry list (alt+f4, ctrl+alt+delete, ctrl+alt+del).
+ * The audit flagged this as cosmetic. v0.8.1 expands to the full known
+ * destructive set with whitespace-normalized matching so "alt +f4" also
+ * blocks.
+ *
+ * Used by the SafetyLayer. Adding a combo here blocks it across EVERY
+ * path (text-agent, vision-agent, MCP direct, REST /action, playbooks).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOCKED_KEYS = void 0;
+exports.normalizeCombo = normalizeCombo;
+exports.keyBlockTier = keyBlockTier;
+exports.keyBlockReason = keyBlockReason;
+exports.isBlockedKey = isBlockedKey;
+exports.blockReason = blockReason;
+/**
+ * Platform-aware substitution for the `mod` modifier — resolves to `cmd` on
+ * macOS and `ctrl` on Windows/Linux. Mirrors the `mod` alias in `src/keys.ts`
+ * so `mod+q` on macOS is treated the same as `cmd+q` for blocklist matching.
+ */
+const PLATFORM_MOD_LOWER = process.platform === 'darwin' ? 'cmd' : 'ctrl';
+/** Normalize a user-supplied combo for comparison — lowercase, trim, collapse whitespace, resolve `mod`. */
+function normalizeCombo(combo) {
+    const flat = combo.toLowerCase().replace(/\s+/g, '').replace(/[+_-]+/g, '+');
+    // Resolve the platform-aware `mod` token in any position so `mod+q` matches
+    // `cmd+q` on macOS and `ctrl+q` (etc.) on Win/Linux.
+    if (!flat.includes('mod'))
+        return flat;
+    return flat.split('+').map(p => p === 'mod' ? PLATFORM_MOD_LOWER : p).join('+');
+}
+// Two tiers (v1.6.0): the old single list HARD-blocked everything with NO
+// confirm path — even though `blockReason` promised "consent via Confirm-tier".
+// That dead-ended legitimate agent actions: win+d (show desktop), ctrl+w
+// (close a tab), win+r. Split by reversibility/intent:
+//   HARD   — locks the machine, force-quits, or fires a secure-attention /
+//            shutdown sequence. Never an agent action; no confirm path.
+//   CONFIRM — consequential but legitimate (close window/tab, show desktop,
+//            open a launcher). Routes through the normal confirm/allowConfirm
+//            gate so an authorized caller can proceed.
+/** Hard-blocked: no confirm path. */
+const HARD_BLOCK = [
+    'ctrl+alt+delete', 'ctrl+alt+del', // secure attention sequence
+    'win+l', 'cmd+ctrl+q', // lock the machine
+    'cmd+shift+q', // macOS log out
+    'cmd+opt+esc', // macOS force-quit picker
+    'ctrl+shift+esc', // task manager / force-quit escalation
+    'fn+alt+f4', // shutdown combo some laptops map to
+];
+/** Confirm-tier: consequential but a legitimate agent action with approval. */
+const CONFIRM_BLOCK = [
+    'alt+f4', 'cmd+q', // close all windows / quit app (may lose unsaved work)
+    'ctrl+w', 'cmd+w', // close tab/window
+    'win+r', 'cmd+space', // Run dialog / Spotlight launcher
+    'win+d', 'cmd+f3', // show desktop / minimize everything
+    'f11', // full-screen — often interferes with UIA
+];
+const HARD_BLOCK_SET = new Set(HARD_BLOCK.map(normalizeCombo));
+const CONFIRM_BLOCK_SET = new Set(CONFIRM_BLOCK.map(normalizeCombo));
+/** Classify a combo: 'block' (hard, no path), 'confirm' (allowConfirm-able), or null (free). */
+function keyBlockTier(combo) {
+    const n = normalizeCombo(combo);
+    if (HARD_BLOCK_SET.has(n))
+        return 'block';
+    if (CONFIRM_BLOCK_SET.has(n))
+        return 'confirm';
+    return null;
+}
+/** Truthful reason for the given tier. */
+function keyBlockReason(combo, tier) {
+    return tier === 'block'
+        ? `Key combo "${combo}" is hard-blocked — it locks the machine, force-quits, or fires a system/shutdown sequence an agent must never send.`
+        : `Key combo "${combo}" needs confirmation — it closes windows/tabs, shows the desktop, or opens a run/search launcher. If the user authorized it, re-issue inside batch({allowConfirm:true}).`;
+}
+// ── Back-compat: the old names now mean HARD blocks only ──
+/** The read-only normalized HARD-block set. */
+exports.BLOCKED_KEYS = HARD_BLOCK_SET;
+/** True only for HARD-blocked combos (no confirm path). */
+function isBlockedKey(combo) {
+    return HARD_BLOCK_SET.has(normalizeCombo(combo));
+}
+/** Reason string for a HARD block. */
+function blockReason(combo) {
+    return keyBlockReason(combo, 'block');
+}
+//# sourceMappingURL=keys-blocklist.js.map

package/dist/tools/playbooks/keys-blocklist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys-blocklist.js","sourceRoot":"","sources":["../../../src/tools/playbooks/keys-blocklist.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAUH,wCAMC;AAqCD,oCAKC;AAGD,wCAIC;AAMD,oCAEC;AAED,kCAEC;AA3ED;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AAE1E,4GAA4G;AAC5G,SAAgB,cAAc,CAAC,KAAa;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7E,4EAA4E;IAC5E,qDAAqD;IACrD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClF,CAAC;AAED,0EAA0E;AAC1E,gFAAgF;AAChF,yEAAyE;AACzE,uDAAuD;AACvD,2EAA2E;AAC3E,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,uDAAuD;AAEvD,qCAAqC;AACrC,MAAM,UAAU,GAAa;IAC3B,iBAAiB,EAAE,cAAc,EAAG,4BAA4B;IAChE,OAAO,EAAE,YAAY,EAAe,mBAAmB;IACvD,aAAa,EAAuB,gBAAgB;IACpD,aAAa,EAAuB,0BAA0B;IAC9D,gBAAgB,EAAoB,uCAAuC;IAC3E,WAAW,EAAyB,qCAAqC;CAC1E,CAAC;AAEF,+EAA+E;AAC/E,MAAM,aAAa,GAAa;IAC9B,QAAQ,EAAE,OAAO,EAAmB,uDAAuD;IAC3F,QAAQ,EAAE,OAAO,EAAmB,mBAAmB;IACvD,OAAO,EAAE,WAAW,EAAgB,kCAAkC;IACtE,OAAO,EAAE,QAAQ,EAAmB,qCAAqC;IACzE,KAAK,EAA+B,0CAA0C;CAC/E,CAAC;AAEF,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AACpF,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AAI1F,gGAAgG;AAChG,SAAgB,YAAY,CAAC,KAAa;IACxC,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0CAA0C;AAC1C,SAAgB,cAAc,CAAC,KAAa,EAAE,IAAyB;IACrE,OAAO,IAAI,KAAK,OAAO;QACrB,CAAC,CAAC,cAAc,KAAK,sHAAsH;QAC3I,CAAC,CAAC,cAAc,KAAK,0KAA0K,CAAC;AACpM,CAAC;AAED,6DAA6D;AAC7D,+CAA+C;AAClC,QAAA,YAAY,GAAwB,cAAc,CAAC;AAChE,2DAA2D;AAC3D,SAAgB,YAAY,CAAC,KAAa;IACxC,OAAO,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC;AACD,sCAAsC;AACtC,SAAgB,WAAW,CAAC,KAAa;IACvC,OAAO,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+import { getCompactTools } from './compact';
+import type { ToolDefinition, ToolContext, ToolResult, CompactGroup } from './types';
+import { toOpenAiFunctions, toJsonSchema } from './types';
+export type { ToolDefinition, ToolContext, ToolResult };
+export { toOpenAiFunctions, toJsonSchema };
+export { getCompactTools };
+/** Options for the unified getTools() accessor. */
+export interface GetToolsOptions {
+    /**
+     * Which surface to return.
+     *   'granular' — the full set of granular primitives (default)
+     *   'compact'  — the 6 compound tools (same as getCompactSurface())
+     */
+    palette?: 'granular' | 'compact';
+    /**
+     * Filter granular tools by their compactGroup.
+     * Only meaningful when palette === 'granular' (or omitted).
+     */
+    compactGroup?: CompactGroup;
+}
+export declare function getTools(options?: GetToolsOptions): ToolDefinition[];
+/** Get all registered GRANULAR tools (the full primitive surface). Back-compat wrapper around getTools(). */
+export declare function getAllTools(): ToolDefinition[];
+/**
+ * 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' }).
+ */
+export declare function getCompactSurface(): ToolDefinition[];
+/** Get tools by category */
+export declare function getToolsByCategory(category: string): ToolDefinition[];
+/** Get a tool by name */
+export declare function getTool(name: string): ToolDefinition | undefined;