@mseep/clawdcursor 1.5.5

package/dist/core/banner.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Control banner — the on-screen "desktop control in progress" indicators:
+ *   - scripts/banner.ps1: topmost, no-activate pill with a blinking red dot;
+ *     carries the double-click → stop affordance.
+ *   - scripts/edge-glow.ps1: a full-screen, click-through amber glow that pulses
+ *     on all four screen edges. Pure ambient signal; spawned/killed in lockstep
+ *     with the pill so the two are always in sync. Opt out via CLAWD_NO_GLOW=1.
+ *
+ * Transparency contract: whenever an agent is actively driving this desktop,
+ * a human at the machine sees it — and can kill it (double-click → the parent
+ * runs the `clawdcursor stop` flow). Two lifecycles feed it:
+ *
+ *   - pin()/unpin(): the autonomous task loop pins the banner for the whole
+ *     task (agent.executeTask). A pinned banner ignores idle timers.
+ *   - touch(): every consequential (safetyTier ≥ 1) MCP tool call pokes the
+ *     banner; it shows on the first poke and auto-hides after IDLE_HIDE_MS of
+ *     inactivity. This covers EXTERNAL agents (editor-hosted over stdio or
+ *     HTTP /mcp) where there is no task boundary to hook.
+ *
+ * Windows-only today (WinForms via the warm PowerShell host); macOS/Linux are
+ * silent no-ops — the API is platform-neutral so adapters can land later.
+ * Disable via `--no-banner` or CLAWD_NO_BANNER=1.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.controlBanner = void 0;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const paths_1 = require("../paths");
+const IDLE_HIDE_MS = 30_000;
+class ControlBanner {
+    child = null; // the pill (carries BANNER_STOP)
+    glowChild = null; // the screen-edge glow overlay
+    idleTimer = null;
+    pinned = false;
+    enabled = process.platform === 'win32' && process.env.CLAWD_NO_BANNER !== '1';
+    // The edge glow rides the same lifecycle as the pill but is independently
+    // opt-out-able (some users find ambient pulsing distracting) without losing
+    // the pill's double-click-to-stop affordance.
+    glowEnabled = process.env.CLAWD_NO_GLOW !== '1';
+    onStopRequested;
+    spawner = () => {
+        const script = path.join((0, paths_1.getPackageRoot)(), 'scripts', 'banner.ps1');
+        return (0, child_process_1.spawn)('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden', '-File', script], { stdio: ['ignore', 'pipe', 'ignore'] });
+    };
+    glowSpawner = () => {
+        const script = path.join((0, paths_1.getPackageRoot)(), 'scripts', 'edge-glow.ps1');
+        return (0, child_process_1.spawn)('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden', '-File', script], { stdio: ['ignore', 'ignore', 'ignore'] }); // click-through visual only — no stdout contract
+    };
+    /** Wire the double-click → stop callback (the `clawdcursor stop` flow). */
+    configure(opts) {
+        this.onStopRequested = opts.onStopRequested;
+    }
+    /** Hard enable/disable (CLI --no-banner / config). Disabling hides immediately. */
+    setEnabled(v) {
+        this.enabled = v && process.platform === 'win32' && process.env.CLAWD_NO_BANNER !== '1';
+        if (!this.enabled)
+            this.forceHide();
+    }
+    isVisible() {
+        return this.child !== null;
+    }
+    /** Show and keep shown until unpin() — the autonomous-task lifecycle. */
+    pin() {
+        if (!this.enabled)
+            return;
+        this.pinned = true;
+        this.clearIdleTimer();
+        this.show();
+    }
+    /** Release the task pin; hides unless tool activity re-touches it. */
+    unpin() {
+        this.pinned = false;
+        this.forceHide();
+    }
+    /**
+     * Activity poke from a consequential tool call: show now, auto-hide after
+     * IDLE_HIDE_MS without further pokes. No-op on the timer while pinned.
+     */
+    touch(idleMs = IDLE_HIDE_MS) {
+        if (!this.enabled)
+            return;
+        this.show();
+        if (this.pinned)
+            return; // task lifecycle owns visibility
+        this.clearIdleTimer();
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            if (!this.pinned)
+                this.forceHide();
+        }, idleMs);
+        this.idleTimer.unref?.();
+    }
+    exitHookInstalled = false;
+    show() {
+        if (!this.enabled)
+            return;
+        this.installExitHook();
+        this.spawnPill();
+        this.spawnGlow();
+    }
+    /** The "control in progress" pill — also the BANNER_STOP / kill-switch source. */
+    spawnPill() {
+        if (this.child)
+            return;
+        let child;
+        try {
+            child = this.spawner();
+        }
+        catch {
+            return; // cosmetic feature — never let it break control
+        }
+        this.child = child;
+        if (child.stdout) {
+            const rl = readline.createInterface({ input: child.stdout });
+            rl.on('line', line => {
+                if (line.trim() === 'BANNER_STOP') {
+                    try {
+                        this.onStopRequested?.();
+                    }
+                    catch { /* never throw into the rl loop */ }
+                }
+            });
+        }
+        child.on('error', () => { if (this.child === child)
+            this.child = null; });
+        // If the pill dies, take the glow down with it so the two never desync
+        // into a half-on state (glow without the stop affordance).
+        child.on('exit', () => { if (this.child === child) {
+            this.child = null;
+            this.killGlow();
+        } });
+    }
+    /** The ambient screen-edge glow — pure visual, click-through, no stdout. */
+    spawnGlow() {
+        if (!this.glowEnabled || this.glowChild)
+            return;
+        let child;
+        try {
+            child = this.glowSpawner();
+        }
+        catch {
+            return; // cosmetic — never let it break control
+        }
+        this.glowChild = child;
+        child.on('error', () => { if (this.glowChild === child)
+            this.glowChild = null; });
+        child.on('exit', () => { if (this.glowChild === child)
+            this.glowChild = null; });
+    }
+    // Neither overlay may outlive its owner — an orphaned "control in progress"
+    // pill or glow after the daemon stopped would be a lie on screen. kill() is a
+    // sync syscall, safe inside an 'exit' handler.
+    installExitHook() {
+        if (this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = true;
+        process.on('exit', () => {
+            try {
+                this.child?.kill();
+            }
+            catch { /* gone */ }
+            try {
+                this.glowChild?.kill();
+            }
+            catch { /* gone */ }
+        });
+    }
+    killGlow() {
+        const g = this.glowChild;
+        this.glowChild = null;
+        if (g) {
+            try {
+                g.kill();
+            }
+            catch { /* already gone */ }
+        }
+    }
+    forceHide() {
+        this.clearIdleTimer();
+        const c = this.child;
+        this.child = null;
+        if (c) {
+            try {
+                c.kill();
+            }
+            catch { /* already gone */ }
+        }
+        this.killGlow();
+    }
+    clearIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+    }
+    // ── test hooks ──
+    __setSpawnerForTests(s) { this.spawner = s; }
+    __setGlowSpawnerForTests(s) { this.glowSpawner = s; }
+    __setPlatformEnabledForTests(v) { this.enabled = v; }
+    __setGlowEnabledForTests(v) { this.glowEnabled = v; }
+    __resetForTests() {
+        this.forceHide();
+        this.pinned = false;
+        this.glowEnabled = true;
+        this.onStopRequested = undefined;
+    }
+}
+/** Singleton — one banner per process (daemon or stdio MCP server). */
+exports.controlBanner = new ControlBanner();
+//# sourceMappingURL=banner.js.map

package/dist/core/banner.js.map

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

package/dist/core/classify/capability.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Capability classifier — finer-grained tagging of subtask INTENT.
+ *
+ * Lives alongside `classifyTask` but asks a different question.
+ * `classifyTask` buckets into {mechanical, navigation, reasoning, spatial}
+ * to pick a PIPELINE PATH (router / blind / hybrid / vision). The
+ * capability classifier is the layer below: given this subtask's text,
+ * which TOOLS does the LLM plausibly need?
+ *
+ * Pure regex, zero LLM, ~30 LOC. Falls back to `general` (full tool
+ * catalog, same as pre-Tranche-2.5 behavior) when nothing matches, so
+ * this change is safe by construction.
+ *
+ * Precedence (first match wins):
+ *   spatial > window_mgmt > file_ops > form_fill > text_input >
+ *   navigation > app_launch > general
+ *
+ * Why that order: the most specific verbs fire first. "drag file to
+ * trash" matches both `spatial` (drag) and `file_ops` (file); spatial
+ * wins because the user's INTENT is a physical gesture, and the
+ * correct tool palette is the spatial one (needs drag/mouse tools,
+ * not file APIs).
+ */
+export type Capability = 
+/** `open Notepad`, `launch Chrome`, `focus Outlook`. Router usually handles — agent fallback needs launch + focus tools only. */
+'app_launch'
+/** `type hello`, `enter your email`, `write "foo"`. Focus + type + a11y set-value. */
+ | 'text_input'
+/** `go to github.com`, `visit docs.anthropic.com`. Router handles — agent fallback wants key_press + switch_tab. */
+ | 'navigation'
+/** `fill out the form`, `complete the signup`. Form iteration over named fields. */
+ | 'form_fill'
+/** `draw a square`, `drag the file to trash`, `resize this element`. Needs pixel-level mouse primitives. */
+ | 'spatial'
+/** `open the README`, `save as`, `open this URL`. System-open helpers + clipboard. */
+ | 'file_ops'
+/** `maximize`, `minimize`, `close window`, `resize to 1280x720`. setWindowState + setWindowBounds. */
+ | 'window_mgmt'
+/** Fallback — shows the full catalog. Same behavior as before this feature existed. */
+ | 'general';
+/**
+ * Classify a subtask string into a Capability. Pure, zero-LLM.
+ * Caller uses the result to scope the agent's tool catalog.
+ */
+export declare function classifyCapability(subtaskText: string): Capability;

package/dist/core/classify/capability.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Capability classifier — finer-grained tagging of subtask INTENT.
+ *
+ * Lives alongside `classifyTask` but asks a different question.
+ * `classifyTask` buckets into {mechanical, navigation, reasoning, spatial}
+ * to pick a PIPELINE PATH (router / blind / hybrid / vision). The
+ * capability classifier is the layer below: given this subtask's text,
+ * which TOOLS does the LLM plausibly need?
+ *
+ * Pure regex, zero LLM, ~30 LOC. Falls back to `general` (full tool
+ * catalog, same as pre-Tranche-2.5 behavior) when nothing matches, so
+ * this change is safe by construction.
+ *
+ * Precedence (first match wins):
+ *   spatial > window_mgmt > file_ops > form_fill > text_input >
+ *   navigation > app_launch > general
+ *
+ * Why that order: the most specific verbs fire first. "drag file to
+ * trash" matches both `spatial` (drag) and `file_ops` (file); spatial
+ * wins because the user's INTENT is a physical gesture, and the
+ * correct tool palette is the spatial one (needs drag/mouse tools,
+ * not file APIs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyCapability = classifyCapability;
+const CAPABILITY_RULES = [
+    // spatial — physical gestures. Leading check so "drag file to trash" lands here.
+    {
+        name: 'spatial',
+        pattern: /\b(draw|sketch|paint|drag\s+.*\b(to|onto|into)\b|resize\s+(the\s+)?(element|image|layer)|crop|rotate|annotate|illustrate|diagram)\b/i,
+    },
+    // window_mgmt — verbs about the window itself
+    {
+        name: 'window_mgmt',
+        pattern: /\b(maximi[sz]e|minimi[sz]e|close\s+(the\s+)?(window|tab)|resize\s+(the\s+)?window|move\s+(the\s+)?window\s+to|restore\s+(the\s+)?window|snap\s+(to\s+)?(left|right|top|bottom))\b/i,
+    },
+    // file_ops — file system / URL targets
+    {
+        name: 'file_ops',
+        pattern: /\b(open\s+(the\s+)?file|save\s+as|open\s+in\s+default|show\s+in\s+(finder|explorer)|open\s+(this\s+)?url|open\s+https?:|copy\s+(file|text|url)\s+to\s+clipboard)\b/i,
+    },
+    // form_fill — explicit form interaction
+    {
+        name: 'form_fill',
+        pattern: /\b(fill\s+(in|out|the)|complete\s+(the\s+)?form|check\s+(the\s+)?box|select\s+(the\s+)?(option|item|radio)|submit\s+(the\s+)?form)\b/i,
+    },
+    // text_input — anything saying type / enter / write text
+    {
+        name: 'text_input',
+        pattern: /\b(type\b|enter\s+["'\w]|write\s+["'\w]|paste\s+["'\w]|input\s+["'\w]|key\s*in\b)/i,
+    },
+    // navigation — URL or "go to" style
+    {
+        name: 'navigation',
+        pattern: /\b(go\s+to|navigate\s+to|visit|browse\s+to|search\s+(for|on\s+page)|find\s+on\s+page|switch\s+to\s+.*tab)\b/i,
+    },
+    // app_launch — open/launch/focus app
+    {
+        name: 'app_launch',
+        pattern: /^\s*(open|launch|start|run|focus|switch\s+to)\b/i,
+    },
+];
+/**
+ * Classify a subtask string into a Capability. Pure, zero-LLM.
+ * Caller uses the result to scope the agent's tool catalog.
+ */
+function classifyCapability(subtaskText) {
+    const t = subtaskText.trim();
+    if (!t)
+        return 'general';
+    for (const rule of CAPABILITY_RULES) {
+        if (rule.pattern.test(t))
+            return rule.name;
+    }
+    return 'general';
+}
+//# sourceMappingURL=capability.js.map

package/dist/core/classify/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/core/classify/capability.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AAoEH,gDAOC;AAvDD,MAAM,gBAAgB,GAAiD;IACrE,iFAAiF;IACjF;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,sIAAsI;KAChJ;IAED,8CAA8C;IAC9C;QACE,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,oLAAoL;KAC9L;IAED,uCAAuC;IACvC;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,qKAAqK;KAC/K;IAED,wCAAwC;IACxC;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,uIAAuI;KACjJ;IAED,yDAAyD;IACzD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,oFAAoF;KAC9F;IAED,oCAAoC;IACpC;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,8GAA8G;KACxH;IAED,qCAAqC;IACrC;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,kDAAkD;KAC5D;CACF,CAAC;AAEF;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,WAAmB;IACpD,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC7C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/decompose/llm-decomposer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * LLM task decomposer — fallback when the offline parser returns null.
+ *
+ * Ported from src/ai-brain.ts::decomposeTask + DECOMPOSE_SYSTEM_PROMPT.
+ * Pure text LLM call, no screenshots, no tool calls. One input/output round.
+ *
+ * v0.8.1 scaffold: exposes a clean interface the pipeline can wire. The
+ * actual LLM call is injected — the text-agent's LLM client and this
+ * module's client share infrastructure. Keeps this file pure/testable.
+ */
+export declare const DECOMPOSE_SYSTEM_PROMPT = "You are a task decomposer. Read the ENTIRE input first, then break the natural-language desktop task into an ordered list of concrete, atomic subtasks.\n\nRules:\n- Use ONE concrete action per subtask string.\n- \"type\" subtasks MUST contain the literal text to type, never an instruction.\n  Bad:  \"Type the user's name\"\n  Good: \"type John Smith\"\n- Subtasks must be in execution order.\n- USE AS FEW SUBTASKS AS POSSIBLE. Hard cap is 8. Each subtask runs through\n  its own perception+plan+act loop IN COMPLETE ISOLATION \u2014 the agent for\n  subtask 3 has NO IDEA what subtask 2 did. State does NOT persist between\n  subtasks. So chunky \"do the whole thing\" subtasks cost less and succeed\n  more than micro-steps.\n- SINGLE-APP WORKFLOWS ARE ONE SUBTASK. If the entire task happens in one\n  app, emit just \"open <app>\" + \"do the thing in <app>\" \u2014 at most 2\n  subtasks. Do NOT break click/type/click sequences inside one app into\n  separate subtasks. This rule is app-agnostic; it applies to any app.\n    Bad:  [\"open <mail app>\", \"click Compose\", \"type address\", \"type subject\", \"type body\", \"click Send\"]\n    Why:  6 isolated agents, each blind to what prior agents did. Subtask 4\n          runs, sees the app but no compose window (subtask 2's window\n          closed), fails.\n    Good: [\"open <mail app>\", \"compose and send an email to john@example.com introducing yourself\"]\n    Why:  1 agent opens the app, 1 agent does the entire compose flow.\n  Same rule for any app: spreadsheet edits, image edits, document writing,\n  music playback, calendar events, chat messages \u2014 always one subtask for\n  \"open the app\", one subtask for the WHOLE in-app workflow.\n- Each subtask must be SELF-CONTAINED. The downstream agent sees ONLY this\n  one string, not the original task or prior subtasks. So every subtask must\n  carry enough context to execute correctly on its own.\n    Bad task split:  [\"open Edge\", \"navigate to outlook.office.com\", \"wait for Outlook to load\", \"click compose\"]\n    Why bad: subtask 3 \"wait for Outlook to load\" \u2014 the agent has no idea this means the WEB page in Edge.\n              It will see no desktop Outlook running and incorrectly call open_app(\"Outlook\").\n    Good split:      [\"navigate to https://outlook.office.com in the default browser\", \"click the New / Compose button on outlook.office.com\"]\n    Why good: each step names what app/page it's acting on, no orphan \"wait\" steps, no scaffolding.\n- DROP \"wait for X to load\" subtasks entirely. The downstream agent's\n  perception loop already polls the screen \u2014 explicit waits are scaffolding\n  the OS handles for free, and they confuse the agent in isolation.\n- DROP \"create a new canvas / new document / new sheet / new tab / new file\"\n  subtasks when they immediately follow an \"open <app>\" step. Apps open\n  with a fresh blank state by default \u2014 Paint opens with a blank canvas,\n  Word opens with a blank document, browsers open with a new tab. Adding\n  a \"create new X\" subtask after \"open X\" creates a phantom no-op step\n  that the downstream verifier flags as failure (zero pixel change \u2192 false\n  negative), which can kill the chain before the actual work runs.\n    Bad:  [\"open Paint\", \"create a new canvas in Paint\", \"draw a stickfigure\"]\n    Good: [\"open Paint\", \"draw a stickfigure\"]\n    Bad:  [\"open Notepad\", \"create a new document\", \"type Hello\"]\n    Good: [\"open Notepad\", \"type Hello\"]\n  Only emit a \"create new X\" step when the user EXPLICITLY says they're\n  working in an already-open instance (e.g. \"in my open Word doc, start a\n  new section\" \u2014 that's a real new-section step, not scaffolding).\n- NEVER bundle an app LAUNCH with an in-app ACTION in one subtask string.\n  \"open X\" must be its OWN subtask, separate from what you do inside X. A\n  bundled \"open X and <do Y>\" is both un-routable (looks compound) and gets\n  mis-handled (the launch never happens cleanly).\n    Bad:  [\"open Notepad and paste the copied text\"]\n    Good: [\"open Notepad\", \"paste the copied text\"]\n    Bad:  [\"open Calculator and compute 5*7\"]\n    Good: [\"open Calculator\", \"compute 5*7\"]\n- NAME THE WINDOW in a dependent subtask. When subtask N opens an app or\n  navigates to a page and subtask N+1 acts INSIDE it, the N+1 string MUST name\n  that app/page \u2014 each subtask runs in isolation and otherwise opens the wrong\n  app. (e.g. after \"navigate to docs.google.com\", the next subtask must say \"in\n  the Google Docs tab\" or it will open Notepad and type there.)\n    Bad:  [\"navigate to docs.google.com\", \"create a document and type a sentence\"]\n    Good: [\"navigate to docs.google.com\", \"in the Google Docs tab, start a new document and type a sentence about dogs\"]\n- Verbs to prefer: open, focus, click, type, press, navigate, select, scroll, save, send.\n  Avoid: wait (redundant \u2014 see above), check, verify (the verifier handles those).\n- Do NOT invent information the task didn't provide. If an email address or value is missing, leave the subtask at the level of \"type the recipient email\".\n\nINTERPRET INDEFINITE PHRASES (CRITICAL \u2014 agents below this layer take strings literally):\n- \"any X\" / \"a random X\" / \"some X\" means \"pick a representative X yourself\" \u2014 RESOLVE it into a concrete step. Do NOT pass the indefinite phrase through.\n    Bad:  \"open any Wikipedia page\"     \u2192   Good: \"navigate to https://en.wikipedia.org/wiki/Special:Random\"\n    Bad:  \"search for any restaurant\"   \u2192   Good: \"navigate to https://www.google.com/maps/search/restaurants near me\"\n    Bad:  \"open a random YouTube video\" \u2192   Good: \"navigate to https://www.youtube.com\" then \"click the first recommended video\"\n- \"the latest X\" / \"today's X\" means \"the most recent visible X\" \u2014 pick the topmost / first-listed item in the relevant view. Don't ask the user.\n    Bad:  \"summarize the latest email\"   \u2192   Good: \"open Outlook\" then \"click the first email in the inbox\"\n- \"an example\" / \"anything\" \u2014 same rule: pick something concrete and proceed.\n\nDO NOT EMIT SCAFFOLDING STEPS the OS does for free:\n- A \"navigate to <url>\" subtask ALREADY launches the default browser as a side effect \u2014 the OS opens whichever browser is the registered http handler. Do NOT emit a separate \"open default browser\" / \"open Chrome\" / \"open Edge\" step before it. That makes the agent type the literal phrase \"default browser\" into a search bar.\n    Bad:  [\"open default browser\", \"navigate to https://github.com\"]\n    Good: [\"navigate to https://github.com\"]\n- Same applies to \"open default mail client\" / \"open the default editor\" \u2014 drop the scaffolding, the OS routes the right app.\n- If the user EXPLICITLY named a browser (\"open Chrome and go to github.com\"), you MAY emit \"open Chrome\" as a step \u2014 that's a concrete app name, not scaffolding.\n\nApp-name normalization (CRITICAL \u2014 wrong app names cause launch failures):\n- Use the canonical short name. Strip filler words: \"app\", \"application\",\n  \"browser\", \"window\", \"program\", and articles (\"the\", \"a\", \"an\") when they\n  precede a brand name.\n    Bad:  \"open the Outlook app\"     \u2192   Good: \"open Outlook\"\n    Bad:  \"launch Edge browser\"      \u2192   Good: \"open Edge\"\n    Bad:  \"start the calculator app\" \u2192   Good: \"open Calculator\"\n    Bad:  \"run Microsoft Word app\"   \u2192   Good: \"open Microsoft Word\"\n- Keep brand-qualified names that the user gave you (\"Microsoft Word\",\n  \"Google Chrome\") \u2014 those are the canonical alias keys, not filler.\n\nOutput FORMAT \u2014 JSON only, no prose:\n{ \"subtasks\": [\"...\", \"...\"] }";
+export interface LlmDecomposerDeps {
+    /**
+     * Text-only LLM call. Returns the raw model output. Caller is responsible
+     * for retries and timeouts — this module just composes the prompt and parses.
+     */
+    callTextLlm: (systemPrompt: string, userPrompt: string, opts?: {
+        maxTokens?: number;
+    }) => Promise<string>;
+}
+/** Extracts the first JSON object from a possibly-messy LLM response. */
+export declare function extractJson(raw: string): unknown | null;
+/**
+ * Decompose via LLM. Returns the subtasks array on success, null when the
+ * response can't be parsed or is empty (caller falls through to one-shot
+ * text-agent).
+ *
+ * `desktopContext` (optional) is a rendered DesktopSurvey block — the live
+ * list of open windows and resolved default handlers. When present it's
+ * prepended to the task so the model grounds decomposition in what's actually
+ * available (skip "open X" for an already-open app, route capabilities to the
+ * real default handler) instead of guessing. Passed as a plain string to keep
+ * this module decoupled from the survey type.
+ */
+export declare function decomposeWithLlm(task: string, deps: LlmDecomposerDeps, desktopContext?: string): Promise<string[] | null>;

package/dist/core/decompose/llm-decomposer.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * LLM task decomposer — fallback when the offline parser returns null.
+ *
+ * Ported from src/ai-brain.ts::decomposeTask + DECOMPOSE_SYSTEM_PROMPT.
+ * Pure text LLM call, no screenshots, no tool calls. One input/output round.
+ *
+ * v0.8.1 scaffold: exposes a clean interface the pipeline can wire. The
+ * actual LLM call is injected — the text-agent's LLM client and this
+ * module's client share infrastructure. Keeps this file pure/testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECOMPOSE_SYSTEM_PROMPT = void 0;
+exports.extractJson = extractJson;
+exports.decomposeWithLlm = decomposeWithLlm;
+exports.DECOMPOSE_SYSTEM_PROMPT = `You are a task decomposer. Read the ENTIRE input first, then break the natural-language desktop task into an ordered list of concrete, atomic subtasks.
+
+Rules:
+- Use ONE concrete action per subtask string.
+- "type" subtasks MUST contain the literal text to type, never an instruction.
+  Bad:  "Type the user's name"
+  Good: "type John Smith"
+- Subtasks must be in execution order.
+- USE AS FEW SUBTASKS AS POSSIBLE. Hard cap is 8. Each subtask runs through
+  its own perception+plan+act loop IN COMPLETE ISOLATION — the agent for
+  subtask 3 has NO IDEA what subtask 2 did. State does NOT persist between
+  subtasks. So chunky "do the whole thing" subtasks cost less and succeed
+  more than micro-steps.
+- SINGLE-APP WORKFLOWS ARE ONE SUBTASK. If the entire task happens in one
+  app, emit just "open <app>" + "do the thing in <app>" — at most 2
+  subtasks. Do NOT break click/type/click sequences inside one app into
+  separate subtasks. This rule is app-agnostic; it applies to any app.
+    Bad:  ["open <mail app>", "click Compose", "type address", "type subject", "type body", "click Send"]
+    Why:  6 isolated agents, each blind to what prior agents did. Subtask 4
+          runs, sees the app but no compose window (subtask 2's window
+          closed), fails.
+    Good: ["open <mail app>", "compose and send an email to john@example.com introducing yourself"]
+    Why:  1 agent opens the app, 1 agent does the entire compose flow.
+  Same rule for any app: spreadsheet edits, image edits, document writing,
+  music playback, calendar events, chat messages — always one subtask for
+  "open the app", one subtask for the WHOLE in-app workflow.
+- Each subtask must be SELF-CONTAINED. The downstream agent sees ONLY this
+  one string, not the original task or prior subtasks. So every subtask must
+  carry enough context to execute correctly on its own.
+    Bad task split:  ["open Edge", "navigate to outlook.office.com", "wait for Outlook to load", "click compose"]
+    Why bad: subtask 3 "wait for Outlook to load" — the agent has no idea this means the WEB page in Edge.
+              It will see no desktop Outlook running and incorrectly call open_app("Outlook").
+    Good split:      ["navigate to https://outlook.office.com in the default browser", "click the New / Compose button on outlook.office.com"]
+    Why good: each step names what app/page it's acting on, no orphan "wait" steps, no scaffolding.
+- DROP "wait for X to load" subtasks entirely. The downstream agent's
+  perception loop already polls the screen — explicit waits are scaffolding
+  the OS handles for free, and they confuse the agent in isolation.
+- DROP "create a new canvas / new document / new sheet / new tab / new file"
+  subtasks when they immediately follow an "open <app>" step. Apps open
+  with a fresh blank state by default — Paint opens with a blank canvas,
+  Word opens with a blank document, browsers open with a new tab. Adding
+  a "create new X" subtask after "open X" creates a phantom no-op step
+  that the downstream verifier flags as failure (zero pixel change → false
+  negative), which can kill the chain before the actual work runs.
+    Bad:  ["open Paint", "create a new canvas in Paint", "draw a stickfigure"]
+    Good: ["open Paint", "draw a stickfigure"]
+    Bad:  ["open Notepad", "create a new document", "type Hello"]
+    Good: ["open Notepad", "type Hello"]
+  Only emit a "create new X" step when the user EXPLICITLY says they're
+  working in an already-open instance (e.g. "in my open Word doc, start a
+  new section" — that's a real new-section step, not scaffolding).
+- NEVER bundle an app LAUNCH with an in-app ACTION in one subtask string.
+  "open X" must be its OWN subtask, separate from what you do inside X. A
+  bundled "open X and <do Y>" is both un-routable (looks compound) and gets
+  mis-handled (the launch never happens cleanly).
+    Bad:  ["open Notepad and paste the copied text"]
+    Good: ["open Notepad", "paste the copied text"]
+    Bad:  ["open Calculator and compute 5*7"]
+    Good: ["open Calculator", "compute 5*7"]
+- NAME THE WINDOW in a dependent subtask. When subtask N opens an app or
+  navigates to a page and subtask N+1 acts INSIDE it, the N+1 string MUST name
+  that app/page — each subtask runs in isolation and otherwise opens the wrong
+  app. (e.g. after "navigate to docs.google.com", the next subtask must say "in
+  the Google Docs tab" or it will open Notepad and type there.)
+    Bad:  ["navigate to docs.google.com", "create a document and type a sentence"]
+    Good: ["navigate to docs.google.com", "in the Google Docs tab, start a new document and type a sentence about dogs"]
+- Verbs to prefer: open, focus, click, type, press, navigate, select, scroll, save, send.
+  Avoid: wait (redundant — see above), check, verify (the verifier handles those).
+- Do NOT invent information the task didn't provide. If an email address or value is missing, leave the subtask at the level of "type the recipient email".
+
+INTERPRET INDEFINITE PHRASES (CRITICAL — agents below this layer take strings literally):
+- "any X" / "a random X" / "some X" means "pick a representative X yourself" — RESOLVE it into a concrete step. Do NOT pass the indefinite phrase through.
+    Bad:  "open any Wikipedia page"     →   Good: "navigate to https://en.wikipedia.org/wiki/Special:Random"
+    Bad:  "search for any restaurant"   →   Good: "navigate to https://www.google.com/maps/search/restaurants near me"
+    Bad:  "open a random YouTube video" →   Good: "navigate to https://www.youtube.com" then "click the first recommended video"
+- "the latest X" / "today's X" means "the most recent visible X" — pick the topmost / first-listed item in the relevant view. Don't ask the user.
+    Bad:  "summarize the latest email"   →   Good: "open Outlook" then "click the first email in the inbox"
+- "an example" / "anything" — same rule: pick something concrete and proceed.
+
+DO NOT EMIT SCAFFOLDING STEPS the OS does for free:
+- A "navigate to <url>" subtask ALREADY launches the default browser as a side effect — the OS opens whichever browser is the registered http handler. Do NOT emit a separate "open default browser" / "open Chrome" / "open Edge" step before it. That makes the agent type the literal phrase "default browser" into a search bar.
+    Bad:  ["open default browser", "navigate to https://github.com"]
+    Good: ["navigate to https://github.com"]
+- Same applies to "open default mail client" / "open the default editor" — drop the scaffolding, the OS routes the right app.
+- If the user EXPLICITLY named a browser ("open Chrome and go to github.com"), you MAY emit "open Chrome" as a step — that's a concrete app name, not scaffolding.
+
+App-name normalization (CRITICAL — wrong app names cause launch failures):
+- Use the canonical short name. Strip filler words: "app", "application",
+  "browser", "window", "program", and articles ("the", "a", "an") when they
+  precede a brand name.
+    Bad:  "open the Outlook app"     →   Good: "open Outlook"
+    Bad:  "launch Edge browser"      →   Good: "open Edge"
+    Bad:  "start the calculator app" →   Good: "open Calculator"
+    Bad:  "run Microsoft Word app"   →   Good: "open Microsoft Word"
+- Keep brand-qualified names that the user gave you ("Microsoft Word",
+  "Google Chrome") — those are the canonical alias keys, not filler.
+
+Output FORMAT — JSON only, no prose:
+{ "subtasks": ["...", "..."] }`;
+/** Extracts the first JSON object from a possibly-messy LLM response. */
+function extractJson(raw) {
+    const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fence ? fence[1] : raw;
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        return JSON.parse(candidate.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decompose via LLM. Returns the subtasks array on success, null when the
+ * response can't be parsed or is empty (caller falls through to one-shot
+ * text-agent).
+ *
+ * `desktopContext` (optional) is a rendered DesktopSurvey block — the live
+ * list of open windows and resolved default handlers. When present it's
+ * prepended to the task so the model grounds decomposition in what's actually
+ * available (skip "open X" for an already-open app, route capabilities to the
+ * real default handler) instead of guessing. Passed as a plain string to keep
+ * this module decoupled from the survey type.
+ */
+async function decomposeWithLlm(task, deps, desktopContext) {
+    const userPrompt = desktopContext && desktopContext.trim()
+        ? `${desktopContext.trim()}\n\nTASK:\n${task}`
+        : task;
+    const raw = await deps.callTextLlm(exports.DECOMPOSE_SYSTEM_PROMPT, userPrompt, { maxTokens: 400 });
+    const parsed = extractJson(raw);
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const subtasks = parsed.subtasks;
+    if (!Array.isArray(subtasks))
+        return null;
+    const filtered = subtasks.filter(s => typeof s === 'string' && s.trim().length > 0).map(s => s.trim());
+    return filtered.length > 0 ? filtered : null;
+}
+//# sourceMappingURL=llm-decomposer.js.map

package/dist/core/decompose/llm-decomposer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-decomposer.js","sourceRoot":"","sources":["../../../src/core/decompose/llm-decomposer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AA+GH,kCAWC;AAcD,4CAeC;AArJY,QAAA,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAkGR,CAAC;AAUhC,yEAAyE;AACzE,SAAgB,WAAW,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACzC,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,IAAuB,EACvB,cAAuB;IAEvB,MAAM,UAAU,GAAG,cAAc,IAAI,cAAc,CAAC,IAAI,EAAE;QACxD,CAAC,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,cAAc,IAAI,EAAE;QAC9C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,+BAAuB,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,QAAQ,GAAI,MAAiC,CAAC,QAAQ,CAAC;IAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAE,CAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IACnH,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/core/decompose/parser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Offline task decomposer — regex + quote-aware compound split.
+ *
+ * Ported from src/local-parser.ts. Zero LLM calls, zero dependencies. Returns
+ * the task split into subtask strings, or null when the task is too ambiguous
+ * to split safely (caller falls back to the LLM decomposer).
+ *
+ * v0.6.3 product knowledge preserved:
+ *   - The `actionVerb` validator is the guard against dangerous splits like
+ *     "scroll through and read" where one half lacks a terminal condition and
+ *     would infinite-loop the text-agent.
+ *   - Quote-aware splitter so "send 'hello, world' to Bob" isn't broken.
+ */
+export interface DecomposeResult {
+    subtasks: string[];
+    /** True when the parser chose to keep the task as one unit despite
+     *  encountering delimiters — signals "we deliberately did not split". */
+    keptAsOne: boolean;
+}
+/**
+ * Split a compound task on ` and `, ` then `, or `,` — quote-aware.
+ */
+export declare function splitCompound(task: string): string[];
+/**
+ * Decompose a task. Null → ambiguous, caller escalates to LLM decomposer.
+ */
+export declare function decompose(task: string): DecomposeResult | null;