@aexol/spectral 0.9.211 → 0.9.215

package/dist/extensions/browser/index.d.ts

@@ -6,16 +6,19 @@
  * control a real browser: navigate, click, type, evaluate JS, take
  * screenshots, inspect network traffic, and more.
  *
- * All 20 tools match the same API surface as playwright-mcp, but without
+ * All 31 tools match the same API surface as playwright-mcp, but without
  * the MCP protocol layer — they call Playwright directly from Node.js.
  *
  * Architecture:
  *   - BrowserService (singleton) — one browser, one context, multiple pages
  *   - Tools register via ext.registerTool() — same pattern as aexol-mcp
- *   - Browser auto-closes on session_shutdown
+ *   - Browser auto-closes on session_shutdown (stream + recording stopped
+ *     first, then the browser, then a SIGKILL fallback for the Chromium
+ *     process so a visible window is never orphaned)
  *
- * Registered tools (20):
- *   Core:        browser_navigate, browser_navigate_back, browser_close, browser_resize
+ * Registered tools (31):
+ *   Core:        browser_navigate, browser_navigate_back, browser_close, browser_resize,
+ *                browser_quit
  *   Tabs:        browser_tabs
  *   Input:       browser_click, browser_type, browser_press_key, browser_hover,
  *                browser_drag, browser_select_option, browser_fill_form, browser_file_upload
@@ -26,6 +29,9 @@
  *   Dialog:      browser_handle_dialog
  *   Wait:        browser_wait_for
  *   Drop:        browser_drop
+ *   Stream:      browser_stream_start, browser_stream_stop, browser_stream_status
+ *   Record:      browser_record_start, browser_record_stop, browser_record_status
+ *   Scenario:    browser_run_scenario
  *
  * Usage:
  *   spectral --extension ./cli-node/src/extensions/browser/index.ts

package/dist/extensions/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAgBpE,wBAA8B,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsE/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAiBpE,wBAA8B,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAkG/E"}

package/dist/extensions/browser/index.js

@@ -6,16 +6,19 @@
  * control a real browser: navigate, click, type, evaluate JS, take
  * screenshots, inspect network traffic, and more.
  *
- * All 20 tools match the same API surface as playwright-mcp, but without
+ * All 31 tools match the same API surface as playwright-mcp, but without
  * the MCP protocol layer — they call Playwright directly from Node.js.
  *
  * Architecture:
  *   - BrowserService (singleton) — one browser, one context, multiple pages
  *   - Tools register via ext.registerTool() — same pattern as aexol-mcp
- *   - Browser auto-closes on session_shutdown
+ *   - Browser auto-closes on session_shutdown (stream + recording stopped
+ *     first, then the browser, then a SIGKILL fallback for the Chromium
+ *     process so a visible window is never orphaned)
  *
- * Registered tools (20):
- *   Core:        browser_navigate, browser_navigate_back, browser_close, browser_resize
+ * Registered tools (31):
+ *   Core:        browser_navigate, browser_navigate_back, browser_close, browser_resize,
+ *                browser_quit
  *   Tabs:        browser_tabs
  *   Input:       browser_click, browser_type, browser_press_key, browser_hover,
  *                browser_drag, browser_select_option, browser_fill_form, browser_file_upload
@@ -26,6 +29,9 @@
  *   Dialog:      browser_handle_dialog
  *   Wait:        browser_wait_for
  *   Drop:        browser_drop
+ *   Stream:      browser_stream_start, browser_stream_stop, browser_stream_status
+ *   Record:      browser_record_start, browser_record_stop, browser_record_status
+ *   Scenario:    browser_run_scenario
  *
  * Usage:
  *   spectral --extension ./cli-node/src/extensions/browser/index.ts
@@ -42,6 +48,7 @@ import { registerDialogTools } from "./tools/dialog.js";
 import { registerWaitTools } from "./tools/wait.js";
 import { registerDropTools } from "./tools/drop.js";
 import { registerStreamTools } from "./stream/stream-tool.js";
+import { stopActiveStream } from "./stream/stream-tool.js";
 import { registerRecordTools } from "./record/record-tool.js";
 import { registerScenarioTools } from "./scenario/scenario-tool.js";
 export default async function browserExtension(ext) {
@@ -61,8 +68,31 @@ export default async function browserExtension(ext) {
         return;
     }
     const bs = BrowserService.getInstance();
-    // Auto-close browser when the session ends
+    // Auto-close browser when the session ends. Every step is best-effort: a
+    // failing step must never prevent the next one (and must never prevent the
+    // Chromium process from being killed).
     ext.on("session_shutdown", async () => {
+        // 1. Stop an in-flight WebRTC stream (never re-starts signaling).
+        try {
+            const stopped = await stopActiveStream();
+            if (stopped.stopped) {
+                process.stderr.write("[browser] Stream stopped on shutdown.\n");
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[browser] Error stopping stream: ${msg}\n`);
+        }
+        // 2. Finalize an in-flight recording (context.close() writes the .webm).
+        try {
+            // relaunch:false — never spawn a fresh Chromium just to close it again.
+            await bs.stopRecording({ relaunch: false });
+            process.stderr.write("[browser] Recording finalized on shutdown.\n");
+        }
+        catch {
+            // No recording active (the common case) — ignore.
+        }
+        // 3. Close the browser.
         try {
             await bs.close();
             process.stderr.write("[browser] Browser closed.\n");
@@ -71,6 +101,14 @@ export default async function browserExtension(ext) {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[browser] Error closing browser: ${msg}\n`);
         }
+        // 4. Belt and braces: if anything above bailed out early, SIGKILL the
+        //    Chromium process tree instead of leaving it behind.
+        try {
+            bs.forceKillBrowserProcess();
+        }
+        catch {
+            // ignore
+        }
     });
     // Register all tool groups
     const registrars = [
@@ -112,6 +150,7 @@ function countRegisteredTools(ext) {
         let count = 0;
         const knownTools = [
             "browser_navigate", "browser_navigate_back", "browser_close", "browser_resize",
+            "browser_quit",
             "browser_tabs",
             "browser_click", "browser_type", "browser_press_key", "browser_hover",
             "browser_drag", "browser_select_option", "browser_fill_form", "browser_file_upload",

package/dist/extensions/browser/stream/stream-tool.d.ts

@@ -6,5 +6,15 @@
  */
 import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
 import { BrowserService } from "../browser-service.js";
+export interface StopActiveStreamResult {
+    stopped: boolean;
+    sessionId?: string;
+    durationSeconds?: number;
+}
+/**
+ * Tear down the module-level stream (WebRTC + injected page code) if one is
+ * running. Never throws, never re-starts signaling. Safe to call at shutdown.
+ */
+export declare function stopActiveStream(): Promise<StopActiveStreamResult>;
 export declare function registerStreamTools(ext: ExtensionAPI, bs: BrowserService): void;
 //# sourceMappingURL=stream-tool.d.ts.map

package/dist/extensions/browser/stream/stream-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-tool.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/stream/stream-tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAYvD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CA2L/E"}
+{"version":3,"file":"stream-tool.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/stream/stream-tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAmBvD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAsBxE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CA+K/E"}

package/dist/extensions/browser/stream/stream-tool.js

@@ -7,7 +7,46 @@
 import { SignalingClient } from "./signaling-client.js";
 import { injectStreamingCode, stopStreaming } from "./stream-injector.js";
 let activeStream = null;
+/**
+ * Service the stream was registered with. Kept so `stopActiveStream()` can be
+ * called from outside the tool (e.g. the `session_shutdown` handler) without
+ * having to reach for `BrowserService.getInstance()` — which would resurrect
+ * a fresh instance after the singleton was already torn down.
+ */
+let activeService = null;
+/**
+ * Tear down the module-level stream (WebRTC + injected page code) if one is
+ * running. Never throws, never re-starts signaling. Safe to call at shutdown.
+ */
+export async function stopActiveStream() {
+    const stream = activeStream;
+    if (!stream)
+        return { stopped: false };
+    // Clear first so a concurrent/second call (or a throwing stop) cannot
+    // double-close the same state.
+    activeStream = null;
+    try {
+        const page = activeService?.getActivePage();
+        if (page)
+            await stopStreaming(page);
+    }
+    catch {
+        /* ignore page-level errors — the page may already be gone */
+    }
+    try {
+        stream.signalingClient.close();
+    }
+    catch {
+        /* ignore */
+    }
+    return {
+        stopped: true,
+        sessionId: stream.sessionId,
+        durationSeconds: Math.round((Date.now() - stream.startedAt) / 1000),
+    };
+}
 export function registerStreamTools(ext, bs) {
+    activeService = bs;
     const startTool = {
         name: "browser_stream_start",
         label: "Start Browser Stream",
@@ -111,28 +150,17 @@ export function registerStreamTools(ext, bs) {
             properties: {},
         },
         async execute() {
-            if (!activeStream) {
+            const result = await stopActiveStream();
+            if (!result.stopped) {
                 return {
                     content: [{ type: "text", text: "No active stream." }],
                     details: {},
                 };
             }
-            try {
-                const page = bs.getActivePage();
-                await stopStreaming(page);
-            }
-            catch { /* ignore page-level errors */ }
-            try {
-                activeStream.signalingClient.close();
-            }
-            catch { /* ignore */ }
-            const duration = Math.round((Date.now() - activeStream.startedAt) / 1000);
-            const sessionId = activeStream.sessionId;
-            activeStream = null;
             return {
                 content: [{
                         type: "text",
-                        text: `✓ Stream stopped.\nSession: ${sessionId}\nDuration: ${duration}s`,
+                        text: `✓ Stream stopped.\nSession: ${result.sessionId}\nDuration: ${result.durationSeconds}s`,
                     }],
                 details: {},
             };

package/dist/extensions/browser/tools/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/core.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CA8G7E"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/core.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAwBvD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAoJ7E"}

package/dist/extensions/browser/tools/core.js

@@ -1,6 +1,29 @@
 /**
  * Core browser tools: navigate, navigate_back, close, resize.
  */
+import { stopActiveStream } from "../stream/stream-tool.js";
+/**
+ * Best-effort pre-close teardown shared by `browser_quit`: stop an in-flight
+ * WebRTC stream (it keeps a signaling WS and injected page code alive) and
+ * finalize a running recording — `context.close()` is what writes the .webm,
+ * so closing the browser first would lose the file. Every step is wrapped in
+ * its own try/catch: a failure must never stop the browser from being closed.
+ */
+async function stopStreamAndRecording(bs) {
+    try {
+        await stopActiveStream();
+    }
+    catch {
+        /* no stream active or the page is already gone — ignore */
+    }
+    try {
+        // relaunch:false — never spawn a fresh Chromium just to close it again.
+        await bs.stopRecording({ relaunch: false });
+    }
+    catch {
+        // No recording active (the common case) — ignore.
+    }
+}
 export function registerCoreTools(ext, bs) {
     const navigateTool = {
         name: "browser_navigate",
@@ -61,7 +84,7 @@ export function registerCoreTools(ext, bs) {
     const closeTool = {
         name: "browser_close",
         label: "Browser Close Page",
-        description: "Close the current page. A blank page is opened if it was the last one.",
+        description: "Closes only the current page (tab) — it does NOT close the browser. A blank page is opened if it was the last one. Use browser_quit to close the whole browser.",
         promptSnippet: "`browser_close` — close the current browser page",
         parameters: {
             type: "object",
@@ -78,6 +101,44 @@ export function registerCoreTools(ext, bs) {
             }
         },
     };
+    const quitTool = {
+        name: "browser_quit",
+        label: "Browser Quit",
+        description: "Close the WHOLE browser: closes the browser context, the browser itself and kills the Chromium process. Unlike browser_close (which only closes the current tab), this tears the browser down completely. Use it when you are done working with the browser or when the browser window does not want to close.",
+        promptSnippet: "`browser_quit` — close the whole browser and kill the Chromium process",
+        parameters: {
+            type: "object",
+            properties: {},
+        },
+        async execute() {
+            try {
+                // Same order as the `session_shutdown` handler in ../index.ts: stream
+                // → recording → browser → SIGKILL fallback.
+                await stopStreamAndRecording(bs);
+                await bs.close();
+                // close() already SIGKILLs a process that refuses to exit; this is a
+                // belt-and-braces fallback for the case where close() returned early.
+                bs.forceKillBrowserProcess();
+                return { content: [{ type: "text", text: "✓ Browser closed." }], details: {} };
+            }
+            catch (err) {
+                try {
+                    await stopStreamAndRecording(bs);
+                }
+                catch {
+                    /* ignore — already best-effort */
+                }
+                try {
+                    bs.forceKillBrowserProcess();
+                }
+                catch {
+                    /* ignore */
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: [{ type: "text", text: `Browser quit failed: ${msg}` }], details: { isError: true } };
+            }
+        },
+    };
     const resizeTool = {
         name: "browser_resize",
         label: "Browser Resize",
@@ -103,7 +164,7 @@ export function registerCoreTools(ext, bs) {
             }
         },
     };
-    for (const tool of [navigateTool, navigateBackTool, closeTool, resizeTool]) {
+    for (const tool of [navigateTool, navigateBackTool, closeTool, quitTool, resizeTool]) {
         try {
             ext.registerTool(tool);
         }

package/dist/extensions/desktop-control/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Desktop Control Extension (computer-use with a safety layer)
+ *
+ * Registers snake_case `desktop_*` tools that inject REAL mouse/keyboard
+ * input via native OS commands:
+ *   - macOS:   JXA (osascript -l JavaScript) + CoreGraphics CGEventPost
+ *   - Windows: PowerShell + Add-Type user32 SendInput/SetCursorPos
+ *   - Linux:   xdotool (X11) / wtype (Wayland, keyboard-only)
+ *
+ * Tools are registered ONLY when the platform/session is capable. Every
+ * mutating action is wrapped by the safety layer:
+ *   1. By default there is NO confirmation prompt: enabling the extension
+ *      (enabledNativeExtensions contains "desktop-control") is the explicit
+ *      user consent, so actions run in interactive, headless, serve and RPC
+ *      sessions alike. Opt-in SPECTRAL_DESKTOP_REQUIRE_CONFIRM=1|true restores
+ *      the per-session interactive confirmation (ctx.hasUI; headless
+ *      auto-denies single actions without locking the session).
+ *   2. Optional SPECTRAL_DESKTOP_ALLOWLIST restricts actions to matching
+ *      frontmost apps.
+ *   3. Screenshot BEFORE -> execute -> screenshot AFTER; both images are
+ *      returned as image content so the model verifies the outcome
+ *      (spectral-vision-fallback analyzes them automatically). A pointer
+ *      read-back and a "no visible change" hint expose silent injection
+ *      failures (CGEventPost never errors).
+ *   4. SPECTRAL_DESKTOP_DRY_RUN=1 returns action plans without executing.
+ *
+ * This extension is registered with defaultEnabled: false — it must be
+ * opted in via Settings.enabledNativeExtensions: ["desktop-control"].
+ *
+ * Zero external npm dependencies beyond cross-spawn (Windows PATH is trimmed
+ * under Electron). No native modules.
+ */
+import type { ExtensionAPI, ToolDefinition } from "../../sdk/coding-agent/index.js";
+import { type ScreenshotFormat, type WindowInfo } from "../desktop-screenshot/index.js";
+import { DesktopActionPolicy } from "./safety.js";
+import type { DesktopAdapter } from "./types.js";
+export declare function createAdapter(env?: NodeJS.ProcessEnv): Promise<{
+    adapter: DesktopAdapter | null;
+    reason?: string;
+}>;
+export interface DesktopControlDeps {
+    adapter: DesktopAdapter;
+    /** Screenshot capture (defaults to desktop-screenshot's full-screen capture). */
+    capture?: (options?: {
+        format?: ScreenshotFormat;
+    }) => Promise<Buffer>;
+    /** Window listing (defaults to desktop-screenshot's listWindows). */
+    listWindowsFn?: () => Promise<WindowInfo[]>;
+    env?: NodeJS.ProcessEnv;
+    policy?: DesktopActionPolicy;
+}
+/** Build the 8 desktop tools supported by the adapter's capabilities. */
+export declare function createDesktopTools(deps: DesktopControlDeps): Array<ToolDefinition<Record<string, unknown>, Record<string, unknown>>>;
+export default function desktopControlExtension(ext: ExtensionAPI): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/desktop-control/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/desktop-control/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAEX,YAAY,EAEZ,cAAc,EACd,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAIN,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,MAAM,gCAAgC,CAAC;AAKxC,OAAO,EACN,mBAAmB,EAQnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAA6B,cAAc,EAAE,MAAM,YAAY,CAAC;AAQ5E,wBAAsB,aAAa,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAW9D;AAMD,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,cAAc,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,gBAAgB,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAmQD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CA0SpI;AAMD,wBAA8B,uBAAuB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BtF"}