@aexol/spectral 0.9.19 → 0.9.20

package/dist/extensions/browser/browser-service.d.ts

@@ -1,14 +1,3 @@
-/**
- * BrowserService — singleton managing Playwright browser lifecycle.
- *
- * One browser instance, one persistent context, multiple pages (tabs).
- * Collects console messages and network requests automatically.
- * Follows the same singleton pattern as fetcher-mcp's BrowserService.
- *
- * Playwright is loaded lazily on first use (not at import time). This allows
- * the module to load in standalone Bun binaries where playwright is unavailable.
- * Tools will report a clear "Browser unavailable" error instead of crashing.
- */
 import type { Browser, BrowserContext, Page } from "playwright";
 import type { BrowserConfig } from "./config.js";
 export interface NetworkRequest {
@@ -33,39 +22,29 @@ export declare class BrowserService {
     private networkBuffer;
     private nextNetworkIndex;
     private pendingDialogs;
+    private _recording;
     constructor(config?: Partial<BrowserConfig>);
-    /** Get or create the singleton instance. */
     static getInstance(config?: Partial<BrowserConfig>): BrowserService;
-    /** Reset singleton (for testing). */
     static resetInstance(): void;
-    /** Check whether Playwright is installed and loadable (static, does NOT start a browser). */
     static isAvailable(): boolean;
-    /**
-     * Human-readable message explaining why the browser is unavailable.
-     * Returns null when the browser is available.
-     */
     static unavailabilityReason(): string | null;
-    /** Ensure browser, context, and at least one page are ready. */
     ensureBrowser(): Promise<{
         browser: Browser;
         context: BrowserContext;
         page: Page;
     }>;
-    /** Get the currently active page. */
+    getBrowser(): Browser;
+    getActiveContext(): BrowserContext;
     getActivePage(): Page;
-    /** Navigate to a URL on the active page. */
     navigate(url: string): Promise<{
-        title: string;
         url: string;
+        title: string;
     }>;
-    /** Navigate back. */
     navigateBack(): Promise<{
-        title: string;
         url: string;
+        title: string;
     }>;
-    /** Close the active page. If last page, create a blank one. */
     closePage(): Promise<void>;
-    /** Resize the viewport. */
     resize(width: number, height: number): Promise<void>;
     listTabs(): Array<{
         index: number;
@@ -95,9 +74,21 @@ export declare class BrowserService {
     getNetworkRequests(): NetworkRequest[];
     getNetworkRequest(index: number): NetworkRequest | undefined;
     clearNetworkRequests(): void;
-    /** Close browser, context, and all pages. */
     close(): Promise<void>;
-    /** Reset console/network buffers. */
+    startRecording(outputDir?: string): Promise<{
+        outputPath: string;
+        startedAt: number;
+    }>;
+    stopRecording(): Promise<{
+        outputPath: string;
+        durationSeconds: number;
+    }>;
+    getRecordStatus(): {
+        active: boolean;
+        outputPath?: string;
+        startedAt?: number;
+        elapsedSeconds?: number;
+    };
     resetBuffers(): void;
     getConfig(): BrowserConfig;
 }

package/dist/extensions/browser/browser-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-service.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/browser-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-service.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/browser-service.ts"],"names":[],"mappings":"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"}

package/dist/extensions/browser/browser-service.js

@@ -1,14 +1,3 @@
-/**
- * BrowserService — singleton managing Playwright browser lifecycle.
- *
- * One browser instance, one persistent context, multiple pages (tabs).
- * Collects console messages and network requests automatically.
- * Follows the same singleton pattern as fetcher-mcp's BrowserService.
- *
- * Playwright is loaded lazily on first use (not at import time). This allows
- * the module to load in standalone Bun binaries where playwright is unavailable.
- * Tools will report a clear "Browser unavailable" error instead of crashing.
- */
 import { createRequire } from "node:module";
 import { getBrowserConfig } from "./config.js";
 const _require = createRequire(import.meta.url);
@@ -40,21 +29,19 @@ export class BrowserService {
     networkBuffer = new Map();
     nextNetworkIndex = 0;
     pendingDialogs = [];
+    _recording = null;
     constructor(config) {
         this.config = { ...getBrowserConfig(), ...config };
     }
-    /** Get or create the singleton instance. */
     static getInstance(config) {
         if (!instance) {
             instance = new BrowserService(config);
         }
         return instance;
     }
-    /** Reset singleton (for testing). */
     static resetInstance() {
         instance = null;
     }
-    /** Check whether Playwright is installed and loadable (static, does NOT start a browser). */
     static isAvailable() {
         try {
             loadPlaywright();
@@ -64,10 +51,6 @@ export class BrowserService {
             return false;
         }
     }
-    /**
-     * Human-readable message explaining why the browser is unavailable.
-     * Returns null when the browser is available.
-     */
     static unavailabilityReason() {
         if (_pwError)
             return _pwError;
@@ -81,7 +64,6 @@ export class BrowserService {
             return err instanceof Error ? err.message : String(err);
         }
     }
-    /** Ensure browser, context, and at least one page are ready. */
     async ensureBrowser() {
         if (this.browser?.isConnected() && this.context && this.pages.length > 0) {
             const page = this.pages[this.activePageIndex];
@@ -110,7 +92,6 @@ export class BrowserService {
         this.context = await this.browser.newContext({
             viewport: this.config.viewport,
         });
-        // Auto-collect console messages and network requests
         this.context.on("page", (page) => {
             page.on("console", (msg) => {
                 this.consoleBuffer.push({
@@ -129,34 +110,38 @@ export class BrowserService {
         this.activePageIndex = 0;
         return { browser: this.browser, context: this.context, page };
     }
-    /** Get the currently active page. */
+    getBrowser() {
+        if (!this.browser?.isConnected())
+            throw new Error("Browser is not connected.");
+        return this.browser;
+    }
+    getActiveContext() {
+        if (!this.context)
+            throw new Error("No active context.");
+        return this.context;
+    }
     getActivePage() {
-        if (this.pages.length === 0) {
-            throw new Error("No browser pages available. Call ensureBrowser() first.");
-        }
+        if (this.pages.length === 0)
+            throw new Error("No active page.");
+        if (this.activePageIndex >= this.pages.length)
+            this.activePageIndex = 0;
         return this.pages[this.activePageIndex];
     }
-    /** Navigate to a URL on the active page. */
     async navigate(url) {
-        const { page } = await this.ensureBrowser();
-        // Auto-prepend https if missing
-        const normalizedUrl = url.startsWith("http") ? url : `https://${url}`;
-        await page.goto(normalizedUrl, {
-            timeout: this.config.navigationTimeout,
+        const page = this.getActivePage();
+        const start = Date.now();
+        await page.goto(url, {
             waitUntil: "domcontentloaded",
+            timeout: this.config.navigationTimeout,
         });
-        return { title: await page.title(), url: page.url() };
+        return { url: page.url(), title: await page.title() };
     }
-    /** Navigate back. */
     async navigateBack() {
         const page = this.getActivePage();
         await page.goBack({ timeout: this.config.navigationTimeout });
-        return { title: await page.title(), url: page.url() };
+        return { url: page.url(), title: await page.title() };
     }
-    /** Close the active page. If last page, create a blank one. */
     async closePage() {
-        if (this.pages.length === 0)
-            return;
         const page = this.pages[this.activePageIndex];
         await page.close();
         this.pages.splice(this.activePageIndex, 1);
@@ -169,13 +154,11 @@ export class BrowserService {
             this.activePageIndex = Math.min(this.activePageIndex, this.pages.length - 1);
         }
     }
-    /** Resize the viewport. */
     async resize(width, height) {
         const page = this.getActivePage();
         await page.setViewportSize({ width, height });
         this.config.viewport = { width, height };
     }
-    // --- Tab management ---
     listTabs() {
         return this.pages.map((p, i) => ({
             index: i,
@@ -214,10 +197,8 @@ export class BrowserService {
         await page.bringToFront();
         return { index };
     }
-    // --- Dialog interception ---
     installDialogInterceptor(page) {
         page.on("dialog", (dialog) => {
-            // Hold the dialog until agent handles it via browser_handle_dialog
             this.pendingDialogs.push({
                 message: dialog.message(),
                 type: dialog.type(),
@@ -246,7 +227,6 @@ export class BrowserService {
         }
         return dialog.message;
     }
-    // --- Console messages ---
     getConsoleMessages(level, all = false) {
         const msgs = all ? [...this.consoleBuffer] : [...this.consoleBuffer];
         if (level) {
@@ -259,7 +239,6 @@ export class BrowserService {
     clearConsoleMessages() {
         this.consoleBuffer = [];
     }
-    // --- Network requests ---
     trackNetworkRequest(page) {
         page.on("request", (request) => {
             const index = this.nextNetworkIndex++;
@@ -282,7 +261,6 @@ export class BrowserService {
                 entry.statusText = response.statusText();
                 entry.responseHeaders = response.headers();
             }).catch(() => {
-                // Request may fail or be aborted
             });
         });
     }
@@ -296,8 +274,6 @@ export class BrowserService {
         this.networkBuffer.clear();
         this.nextNetworkIndex = 0;
     }
-    // --- Lifecycle ---
-    /** Close browser, context, and all pages. */
     async close() {
         for (const page of this.pages) {
             try {
@@ -321,8 +297,103 @@ export class BrowserService {
             catch { /* ignore */ }
             this.browser = null;
         }
+        this._recording = null;
+    }
+    // ── Recording ──────────────────────────────────────────────
+    async startRecording(outputDir) {
+        if (this._recording) {
+            throw new Error("Recording is already active. Use stopRecording() first.");
+        }
+        const dir = outputDir ?? this.config.recordOutputDir;
+        const { mkdirSync } = await import("node:fs");
+        mkdirSync(dir, { recursive: true });
+        // Save current URL before tearing down
+        let currentUrl = "about:blank";
+        if (this.pages.length > 0 && this.activePageIndex < this.pages.length) {
+            try {
+                currentUrl = this.pages[this.activePageIndex].url() || currentUrl;
+            }
+            catch { /* ignore */ }
+        }
+        // Close existing context (finalizes any prior video)
+        if (this.context) {
+            await Promise.allSettled(this.pages.map((p) => p.close().catch(() => { })));
+            this.pages = [];
+            await this.context.close().catch(() => { });
+            this.context = null;
+        }
+        // Create new browser+context with recording enabled
+        const pw = loadPlaywright();
+        const launchOpts = {
+            headless: this.config.headless,
+            args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
+        };
+        if (!this.browser?.isConnected()) {
+            switch (this.config.browserName) {
+                case "firefox":
+                    this.browser = await pw.firefox.launch(launchOpts);
+                    break;
+                case "webkit":
+                    this.browser = await pw.webkit.launch(launchOpts);
+                    break;
+                default:
+                    this.browser = await pw.chromium.launch(launchOpts);
+                    break;
+            }
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const outputPath = `${dir}/recording-${timestamp}.webm`;
+        this.context = await this.browser.newContext({
+            viewport: this.config.recordViewport ?? this.config.viewport,
+            recordVideo: {
+                dir,
+                size: this.config.recordViewport ?? this.config.viewport,
+            },
+        });
+        this.context.on("page", (page) => {
+            page.on("console", (msg) => {
+                this.consoleBuffer.push({ type: msg.type(), text: msg.text(), pageUrl: page.url() });
+            });
+            this.trackNetworkRequest(page);
+            this.installDialogInterceptor(page);
+        });
+        const page = await this.context.newPage();
+        this.trackNetworkRequest(page);
+        this.installDialogInterceptor(page);
+        this.pages = [page];
+        this.activePageIndex = 0;
+        await page.goto(currentUrl, { waitUntil: "domcontentloaded", timeout: this.config.navigationTimeout }).catch(() => { });
+        this._recording = { dir, startedAt: Date.now(), outputPath };
+        return { outputPath, startedAt: this._recording.startedAt };
+    }
+    async stopRecording() {
+        if (!this._recording) {
+            throw new Error("No active recording.");
+        }
+        const { outputPath, startedAt } = this._recording;
+        const durationSeconds = Math.round((Date.now() - startedAt) / 1000);
+        // Close the recording context — Playwright finalizes the .webm on context.close()
+        if (this.context) {
+            await Promise.allSettled(this.pages.map((p) => p.close().catch(() => { })));
+            this.pages = [];
+            await this.context.close().catch(() => { });
+            this.context = null;
+        }
+        this._recording = null;
+        // Create a fresh non-recording context for continued use
+        await this.ensureBrowser();
+        return { outputPath, durationSeconds };
+    }
+    getRecordStatus() {
+        if (!this._recording)
+            return { active: false };
+        return {
+            active: true,
+            outputPath: this._recording.outputPath,
+            startedAt: this._recording.startedAt,
+            elapsedSeconds: Math.round((Date.now() - this._recording.startedAt) / 1000),
+        };
     }
-    /** Reset console/network buffers. */
     resetBuffers() {
         this.clearConsoleMessages();
         this.clearNetworkRequests();

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

@@ -1,24 +1,19 @@
-/**
- * Browser extension configuration.
- */
 export interface BrowserConfig {
-    /** Default browser name to launch. */
     browserName: "chromium" | "firefox" | "webkit";
-    /** Whether to run headless. */
     headless: boolean;
-    /** Default viewport size. */
     viewport: {
         width: number;
         height: number;
     };
-    /** Default navigation timeout (ms). */
     navigationTimeout: number;
-    /** Default action timeout (ms). */
     actionTimeout: number;
-    /** Directory to save screenshots and output files. */
     outputDir: string;
-    /** Whether to enable debug mode (keep browser visible, verbose logging). */
     debug: boolean;
+    recordOutputDir: string;
+    recordViewport?: {
+        width: number;
+        height: number;
+    };
 }
 export declare function getBrowserConfig(): BrowserConfig;
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,+BAA+B;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,6BAA6B;IAC7B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,uCAAuC;IACvC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAahD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AACD,wBAAgB,gBAAgB,IAAI,aAAa,CAehD"}

package/dist/extensions/browser/config.js

@@ -1,6 +1,3 @@
-/**
- * Browser extension configuration.
- */
 export function getBrowserConfig() {
     return {
         browserName: process.env.BROWSER_NAME ?? "chromium",
@@ -13,5 +10,7 @@ export function getBrowserConfig() {
         actionTimeout: Number(process.env.BROWSER_ACTION_TIMEOUT) || 5_000,
         outputDir: process.env.BROWSER_OUTPUT_DIR ?? ".spectral/browser-output",
         debug: process.env.BROWSER_DEBUG === "true" ? true : false,
+        recordOutputDir: process.env.BROWSER_RECORD_DIR ?? ".spectral/browser-recordings",
+        recordViewport: undefined, // defaults to viewport via code
     };
 }

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;AAcpE,wBAA8B,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4D/E"}
+{"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;AAepE,wBAA8B,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D/E"}

package/dist/extensions/browser/index.js

@@ -42,6 +42,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 { registerRecordTools } from "./record/record-tool.js";
 export default async function browserExtension(ext) {
     const available = BrowserService.isAvailable();
     if (!available) {
@@ -77,6 +78,7 @@ export default async function browserExtension(ext) {
         { name: "wait", fn: () => registerWaitTools(ext, bs) },
         { name: "drop", fn: () => registerDropTools(ext, bs) },
         { name: "stream", fn: () => registerStreamTools(ext, bs) },
+        { name: "record", fn: () => registerRecordTools(ext, bs) },
     ];
     let totalRegistered = 0;
     for (const registrar of registrars) {
@@ -113,6 +115,7 @@ function countRegisteredTools(ext) {
             "browser_wait_for",
             "browser_drop",
             "browser_stream_start", "browser_stream_stop", "browser_stream_status",
+            "browser_record_start", "browser_record_stop", "browser_record_status",
         ];
         for (const name of knownTools) {
             if (ext.getToolDefinition(name))

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

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { BrowserService } from "../browser-service.js";
+export declare function registerRecordTools(ext: ExtensionAPI, bs: BrowserService): void;
+//# sourceMappingURL=record-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record-tool.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/record/record-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAwI/E"}

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

@@ -0,0 +1,134 @@
+export function registerRecordTools(ext, bs) {
+    const startTool = {
+        name: "browser_record_start",
+        label: "Start Browser Recording",
+        description: "Start recording the browser session as a .webm video. " +
+            "Uses Playwright's built-in video recording (actual page capture, not a canvas overlay). " +
+            "Recording continues across navigation, clicks, typing — everything the agent does in the browser. " +
+            "Use browser_record_stop to finalize and save the video.",
+        promptSnippet: "`browser_record_start { outputDir? }` — start recording browser as .webm video",
+        parameters: {
+            type: "object",
+            properties: {
+                outputDir: {
+                    type: "string",
+                    description: "Directory to save the recording. Default: .spectral/browser-recordings/ (configurable via BROWSER_RECORD_DIR env).",
+                },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const p = params;
+            try {
+                const { outputPath, startedAt } = await bs.startRecording(p.outputDir);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "✓ Browser recording started",
+                                `Output: ${outputPath}`,
+                                `Started at: ${new Date(startedAt).toISOString()}`,
+                                "",
+                                "All browser actions (navigation, clicks, typing, etc.) are now being recorded.",
+                                "Use browser_record_stop to finalize and save the video.",
+                            ].join("\n"),
+                        },
+                    ],
+                    details: { outputPath, startedAt },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Failed to start recording: ${msg}` }],
+                    details: { isError: true },
+                };
+            }
+        },
+    };
+    const stopTool = {
+        name: "browser_record_stop",
+        label: "Stop Browser Recording",
+        description: "Stop the active recording, finalize the .webm video, and create a fresh non-recording browser context " +
+            "for continued use. Returns the video file path and recording duration.",
+        promptSnippet: "`browser_record_stop` — stop recording and save .webm video",
+        parameters: {
+            type: "object",
+            properties: {},
+        },
+        async execute() {
+            try {
+                const { outputPath, durationSeconds } = await bs.stopRecording();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "✓ Recording stopped and saved",
+                                `File: ${outputPath}`,
+                                `Duration: ${durationSeconds}s (${Math.floor(durationSeconds / 60)}m ${durationSeconds % 60}s)`,
+                                "",
+                                "A fresh browser context has been created — you can continue browsing.",
+                            ].join("\n"),
+                        },
+                    ],
+                    details: { outputPath, durationSeconds },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Failed to stop recording: ${msg}` }],
+                    details: { isError: true },
+                };
+            }
+        },
+    };
+    const statusTool = {
+        name: "browser_record_status",
+        label: "Browser Recording Status",
+        description: "Check whether a browser recording is currently active.",
+        promptSnippet: "`browser_record_status` — check recording status",
+        parameters: {
+            type: "object",
+            properties: {},
+        },
+        async execute() {
+            const status = bs.getRecordStatus();
+            if (!status.active) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No active recording. Use browser_record_start to begin.",
+                        },
+                    ],
+                    details: {},
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "● Recording active",
+                            `Output: ${status.outputPath}`,
+                            `Started: ${status.startedAt ? new Date(status.startedAt).toISOString() : "?"}`,
+                            `Elapsed: ${status.elapsedSeconds ?? 0}s`,
+                        ].join("\n"),
+                    },
+                ],
+                details: status,
+            };
+        },
+    };
+    for (const tool of [startTool, stopTool, statusTool]) {
+        try {
+            ext.registerTool(tool);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[browser-record] Failed to register ${tool.name}: ${msg}\n`);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,