@aexol/spectral 0.9.41 → 0.9.43

package/dist/auth-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-helper.d.ts","sourceRoot":"","sources":["../src/auth-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,GAAE,MAAyB,GACnC,OAAO,CAAC,WAAW,CAAC,CAyDtB;AAMD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAUjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA6CrE"}
+{"version":3,"file":"auth-helper.d.ts","sourceRoot":"","sources":["../src/auth-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8FD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,GAAE,MAAyB,GACnC,OAAO,CAAC,WAAW,CAAC,CA8DtB;AAMD,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAUjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAkDrE"}

package/dist/auth-helper.js

@@ -33,6 +33,34 @@ function deriveLandingUrl(backendUrl) {
     }
     return DEFAULT_BACKEND_URL;
 }
+function decodeJwtExp(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        return null;
+    try {
+        const payloadJson = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isJwtExpired(jwt, skewSec = 60) {
+    const exp = decodeJwtExp(jwt);
+    if (exp === null)
+        return true;
+    return Date.now() / 1000 + skewSec >= exp;
+}
+function validateCallbackToken(token) {
+    if (!token || token.split(".").length !== 3) {
+        return { ok: false, reason: "Authorization callback returned an invalid token format." };
+    }
+    if (isJwtExpired(token)) {
+        return { ok: false, reason: "Authorization callback returned an expired token." };
+    }
+    return { ok: true };
+}
 /**
  * Start a temporary HTTP server to receive the OAuth callback.
  * Returns the server and a promise that resolves with the JWT token.
@@ -104,6 +132,10 @@ export async function runOAuthFlow(apiUrl, timeoutMs = OAUTH_TIMEOUT_MS) {
             }
         });
         const token = await tokenPromise;
+        const validation = validateCallbackToken(token);
+        if (!validation.ok) {
+            return { ok: false, reason: validation.reason };
+        }
         // Save the token, preserving existing config (especially teamApiKey).
         const cfg = existingCfg ?? {
             apiUrl: resolvedApiUrl,
@@ -159,19 +191,25 @@ export async function ensureAuthenticated() {
     const token = existingCfg?.teamApiKey || existingCfg?.userJwt || "";
     // If we have a token, verify it still works
     if (token) {
-        try {
-            const client = new AexolMcpClient(apiUrl, token);
-            await client.listTools();
-            // Token is still valid
-            return { ok: true, config: existingCfg };
+        // If the stored user JWT is locally known to be expired, skip the network roundtrip
+        if (existingCfg?.userJwt && isJwtExpired(existingCfg.userJwt)) {
+            // fall through to OAuth
         }
-        catch (err) {
-            if (!isAuthError(err)) {
-                // Non-auth error (network, server down) — don't re-auth, just report
-                const msg = err instanceof Error ? err.message : String(err);
-                return { ok: false, config: existingCfg, reason: `Backend unreachable: ${msg}` };
+        else {
+            try {
+                const client = new AexolMcpClient(apiUrl, token);
+                await client.listTools();
+                // Token is still valid
+                return { ok: true, config: existingCfg };
+            }
+            catch (err) {
+                if (!isAuthError(err)) {
+                    // Non-auth error (network, server down) — don't re-auth, just report
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { ok: false, config: existingCfg, reason: `Backend unreachable: ${msg}` };
+                }
+                // Token is invalid/expired — fall through to OAuth
             }
-            // Token is invalid/expired — fall through to OAuth
         }
     }
     // No valid token — run OAuth flow

package/dist/extensions/aexol-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aexol-mcp.d.ts","sourceRoot":"","sources":["../../src/extensions/aexol-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AA8HnG,wBAA8B,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiShF"}
+{"version":3,"file":"aexol-mcp.d.ts","sourceRoot":"","sources":["../../src/extensions/aexol-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AAsKnG,wBAA8B,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuShF"}

package/dist/extensions/aexol-mcp.js

@@ -128,17 +128,46 @@ async function refreshBindingFromDisk() {
  * Studio binding when they are not already set by the model. Only applies
  * to remote tools (names that start with `remote_`).
  */
-function augmentParams(toolName, params) {
-    if (!currentBinding || !toolName.startsWith("remote_"))
-        return params;
+/**
+ * Tools that accept a `model` parameter. For these, the session model is
+ * always injected from ctx.model — the agent never picks a model itself.
+ */
+const MODEL_INJECTING_TOOLS = new Set([
+    "remote_start_from",
+    "remote_start_inference",
+    "remote_refine_inference_artifact",
+    "remote_refine_from_task",
+    "remote_refine_aexol_content",
+]);
+const SPECTRAL_PROXY_USER_MODEL = "spectral-proxy-user-model";
+const BUILT_IN_PREFIX = "built-in/";
+function augmentParams(toolName, params, ctx) {
+    if (!toolName.startsWith("remote_"))
+        return { params };
     const augmented = { ...params };
-    if (currentBinding.teamId && !("teamId" in params)) {
+    if (currentBinding?.teamId && !("teamId" in params)) {
         augmented.teamId = currentBinding.teamId;
     }
-    if (currentBinding.projectId && !("projectId" in params)) {
+    if (currentBinding?.projectId && !("projectId" in params)) {
         augmented.projectId = currentBinding.projectId;
     }
-    return augmented;
+    if (MODEL_INJECTING_TOOLS.has(toolName)) {
+        const model = ctx.model;
+        if (!model) {
+            return {
+                error: "No session model is selected. Select a Studio built-in model in the agent before running this task.",
+            };
+        }
+        if (model.provider !== SPECTRAL_PROXY_USER_MODEL ||
+            !model.id.startsWith(BUILT_IN_PREFIX)) {
+            return {
+                error: `Session model "${model.provider}/${model.id}" is not a Studio built-in model. ` +
+                    "Select a built-in model (e.g. aexol-coder) in the agent before running this task.",
+            };
+        }
+        augmented.model = model.id.slice(BUILT_IN_PREFIX.length);
+    }
+    return { params: augmented };
 }
 export default async function aexolMcpExtension(ext) {
     const cfg = await readConfig();
@@ -223,10 +252,16 @@ export default async function aexolMcpExtension(ext) {
             label: toLabel(tool.name),
             description: tool.description ?? "",
             parameters,
-            async execute(_toolCallId, params) {
+            async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
                 await refreshBindingFromDisk();
-                const augmented = augmentParams(tool.name, params);
-                const res = await client.callTool(tool.name, augmented);
+                const augmented = augmentParams(tool.name, params, ctx);
+                if ("error" in augmented) {
+                    return {
+                        content: [{ type: "text", text: augmented.error }],
+                        details: { isError: true },
+                    };
+                }
+                const res = await client.callTool(tool.name, augmented.params);
                 const text = renderContentToString(res.content);
                 if (res.isError === true) {
                     // Surface backend tool errors as a textual result, not a thrown

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

@@ -75,7 +75,10 @@ export declare class BrowserService {
     getNetworkRequest(index: number): NetworkRequest | undefined;
     clearNetworkRequests(): void;
     close(): Promise<void>;
-    startRecording(outputDir?: string): Promise<{
+    startRecording(opts?: {
+        outputDir?: string;
+        filename?: string;
+    }): Promise<{
         outputPath: string;
         startedAt: number;
     }>;

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":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAkB,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsBjD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAA8D;IACnF,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAKd;IACR,OAAO,CAAC,UAAU,CAAuE;gBAC7E,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC;IAG3C,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,cAAc;IAMnE,MAAM,CAAC,aAAa,IAAI,IAAI;IAG5B,MAAM,CAAC,WAAW,IAAI,OAAO;IAQ7B,MAAM,CAAC,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAUtC,aAAa,IAAI,OAAO,CAAC;QAC7B,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,cAAc,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC;KACZ,CAAC;IA8CF,UAAU,IAAI,OAAO;IAIrB,gBAAgB,IAAI,cAAc;IAIlC,aAAa,IAAI,IAAI;IAKf,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAS9D,YAAY,IAAI,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAKvD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAY1B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1D,QAAQ,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAO1D,SAAS,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IASvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAS1D,OAAO,CAAC,wBAAwB;IAchC,iBAAiB,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAGvD,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYzE,kBAAkB,CAChB,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,EAC9C,GAAG,UAAQ,GACV,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IASzD,oBAAoB,IAAI,IAAI;IAG5B,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAwBrC,kBAAkB,IAAI,cAAc,EAAE;IAGtC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAG5D,oBAAoB,IAAI,IAAI;IAItB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAyDtF,aAAa,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAkB/E,eAAe,IAAI;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IASxG,YAAY,IAAI,IAAI;IAIpB,SAAS,IAAI,aAAa;CAG3B"}
+{"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

@@ -300,11 +300,11 @@ export class BrowserService {
         this._recording = null;
     }
     // ── Recording ──────────────────────────────────────────────
-    async startRecording(outputDir) {
+    async startRecording(opts) {
         if (this._recording) {
             throw new Error("Recording is already active. Use stopRecording() first.");
         }
-        const dir = outputDir ?? this.config.recordOutputDir;
+        const dir = opts?.outputDir ?? this.config.recordOutputDir;
         const { mkdirSync } = await import("node:fs");
         mkdirSync(dir, { recursive: true });
         // Save current URL before tearing down
@@ -324,8 +324,9 @@ export class BrowserService {
         }
         // Create new browser+context with recording enabled
         const pw = loadPlaywright();
+        const recordHeadless = this.config.recordHeadless;
         const launchOpts = {
-            headless: this.config.headless,
+            headless: recordHeadless,
             args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"],
         };
         if (!this.browser?.isConnected()) {
@@ -342,7 +343,10 @@ export class BrowserService {
             }
         }
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const outputPath = `${dir}/recording-${timestamp}.webm`;
+        const base = opts?.filename
+            ? opts.filename.replace(/\.webm$/i, "")
+            : `recording-${timestamp}`;
+        const outputPath = `${dir}/${base}.webm`;
         this.context = await this.browser.newContext({
             viewport: this.config.recordViewport ?? this.config.viewport,
             recordVideo: {
@@ -363,15 +367,18 @@ export class BrowserService {
         this.pages = [page];
         this.activePageIndex = 0;
         await page.goto(currentUrl, { waitUntil: "domcontentloaded", timeout: this.config.navigationTimeout }).catch(() => { });
-        this._recording = { dir, startedAt: Date.now(), outputPath };
+        this._recording = { dir, startedAt: Date.now(), outputPath, filename: opts?.filename };
         return { outputPath, startedAt: this._recording.startedAt };
     }
     async stopRecording() {
         if (!this._recording) {
             throw new Error("No active recording.");
         }
-        const { outputPath, startedAt } = this._recording;
+        const { outputPath, startedAt, dir, filename } = this._recording;
         const durationSeconds = Math.round((Date.now() - startedAt) / 1000);
+        // Capture the real Playwright-generated video path before closing context.
+        let realVideoPath = null;
+        const pageForVideo = this.pages[0];
         // Close the recording context — Playwright finalizes the .webm on context.close()
         if (this.context) {
             await Promise.allSettled(this.pages.map((p) => p.close().catch(() => { })));
@@ -379,10 +386,30 @@ export class BrowserService {
             await this.context.close().catch(() => { });
             this.context = null;
         }
+        if (pageForVideo) {
+            try {
+                const v = pageForVideo.video();
+                if (v)
+                    realVideoPath = await v.path();
+            }
+            catch { /* ignore */ }
+        }
+        // If a custom filename was requested, rename the Playwright-generated file.
+        let finalPath = realVideoPath ?? outputPath;
+        if (realVideoPath && filename) {
+            const { renameSync } = await import("node:fs");
+            const base = filename.replace(/\.webm$/i, "");
+            const target = `${dir}/${base}.webm`;
+            try {
+                renameSync(realVideoPath, target);
+                finalPath = target;
+            }
+            catch { /* ignore rename failure, keep real path */ }
+        }
         this._recording = null;
         // Create a fresh non-recording context for continued use
         await this.ensureBrowser();
-        return { outputPath, durationSeconds };
+        return { outputPath: finalPath, durationSeconds };
     }
     getRecordStatus() {
         if (!this._recording)

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

@@ -14,6 +14,9 @@ export interface BrowserConfig {
         width: number;
         height: number;
     };
+    /** Whether to run the browser headless during recordings. Defaults to false
+     * (headful) for higher-quality video capture, mirroring the demo recorder. */
+    recordHeadless: boolean;
 }
 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,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"}
+{"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;IACnD;kFAC8E;IAC9E,cAAc,EAAE,OAAO,CAAC;CACzB;AACD,wBAAgB,gBAAgB,IAAI,aAAa,CAgBhD"}

package/dist/extensions/browser/config.js

@@ -12,5 +12,6 @@ export function getBrowserConfig() {
         debug: process.env.BROWSER_DEBUG === "true" ? true : false,
         recordOutputDir: process.env.BROWSER_RECORD_DIR ?? ".spectral/browser-recordings",
         recordViewport: undefined, // defaults to viewport via code
+        recordHeadless: process.env.BROWSER_RECORD_HEADLESS === "true" ? true : false,
     };
 }

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

package/dist/extensions/browser/index.js

@@ -43,6 +43,7 @@ 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";
+import { registerScenarioTools } from "./scenario/scenario-tool.js";
 export default async function browserExtension(ext) {
     const available = BrowserService.isAvailable();
     if (!available) {
@@ -79,6 +80,7 @@ export default async function browserExtension(ext) {
         { name: "drop", fn: () => registerDropTools(ext, bs) },
         { name: "stream", fn: () => registerStreamTools(ext, bs) },
         { name: "record", fn: () => registerRecordTools(ext, bs) },
+        { name: "scenario", fn: () => registerScenarioTools(ext, bs) },
     ];
     let totalRegistered = 0;
     for (const registrar of registrars) {
@@ -116,6 +118,7 @@ function countRegisteredTools(ext) {
             "browser_drop",
             "browser_stream_start", "browser_stream_stop", "browser_stream_status",
             "browser_record_start", "browser_record_stop", "browser_record_status",
+            "browser_run_scenario",
         ];
         for (const name of knownTools) {
             if (ext.getToolDefinition(name))

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

@@ -1 +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"}
+{"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;AAc5D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAmJ/E"}

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

@@ -1,12 +1,26 @@
+/** Build ffmpeg conversion hints for a recorded .webm file. */
+function ffmpegHints(webmPath) {
+    const mp4 = webmPath.replace(/\.webm$/i, ".mp4");
+    const gif = webmPath.replace(/\.webm$/i, ".gif");
+    return [
+        "Convert to MP4:",
+        `  ffmpeg -i "${webmPath}" -c:v libx264 -crf 23 "${mp4}"`,
+        "Convert to GIF:",
+        `  ffmpeg -i "${webmPath}" -vf "fps=15,scale=1280:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" "${gif}"`,
+    ].join("\n");
+}
 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. " +
+            "Use this when the user asks to record/demo/capture/walk through a browser session as 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",
+            "Use browser_record_stop to finalize and save the video. " +
+            "TIP: for full multi-step scenario walkthroughs with recording, prefer browser_run_scenario with record:true " +
+            "instead of manually wrapping browser steps with start/stop.",
+        promptSnippet: "`browser_record_start { outputDir?, filename? }` — start recording browser as .webm video (prefer browser_run_scenario for scenario walkthroughs)",
         parameters: {
             type: "object",
             properties: {
@@ -14,12 +28,19 @@ export function registerRecordTools(ext, bs) {
                     type: "string",
                     description: "Directory to save the recording. Default: .spectral/browser-recordings/ (configurable via BROWSER_RECORD_DIR env).",
                 },
+                filename: {
+                    type: "string",
+                    description: "Optional base filename (without extension) for the recording, e.g. 'login-demo'. Defaults to a timestamp-based name.",
+                },
             },
         },
         async execute(_toolCallId, params) {
             const p = params;
             try {
-                const { outputPath, startedAt } = await bs.startRecording(p.outputDir);
+                const { outputPath, startedAt } = await bs.startRecording({
+                    outputDir: p.outputDir,
+                    filename: p.filename,
+                });
                 return {
                     content: [
                         {
@@ -50,7 +71,7 @@ export function registerRecordTools(ext, bs) {
         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.",
+            "for continued use. Returns the video file path, recording duration, and ffmpeg conversion commands.",
         promptSnippet: "`browser_record_stop` — stop recording and save .webm video",
         parameters: {
             type: "object",
@@ -68,6 +89,8 @@ export function registerRecordTools(ext, bs) {
                                 `File: ${outputPath}`,
                                 `Duration: ${durationSeconds}s (${Math.floor(durationSeconds / 60)}m ${durationSeconds % 60}s)`,
                                 "",
+                                ffmpegHints(outputPath),
+                                "",
                                 "A fresh browser context has been created — you can continue browsing.",
                             ].join("\n"),
                         },

package/dist/extensions/browser/scenario/markdown-parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parse a markdown test scenario into a list of executable browser steps.
+ *
+ * Recognises the scenario format produced by @scenario_writer, e.g.:
+ *
+ *   ### Steps
+ *   1. **Navigate** to http://localhost:3008
+ *   2. **Click** the "Login" button
+ *   3. **Type** `user@example.com` into the email field
+ *   4. **Wait** for text "Dashboard" to appear
+ *   5. **Screenshot** checkpoint
+ *
+ * Each numbered list item becomes one step. The leading bold token (e.g.
+ * **Click**) maps to a browser action. Unrecognised actions are returned as
+ * `note` steps so the caller can still record timing without failing.
+ */
+export type ScenarioAction = "navigate" | "click" | "type" | "press" | "select" | "hover" | "wait" | "screenshot" | "evaluate" | "fill_form" | "note";
+export interface ScenarioStep {
+    action: ScenarioAction;
+    /** Raw original line text, for reporting. */
+    raw: string;
+    /** Primary target: CSS selector, text, or URL depending on action. */
+    target?: string;
+    /** Value to type / press / select / wait-for. */
+    value?: string;
+    /** Extra form fields for fill_form: [{ name, value }]. */
+    fields?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Per-step pause (ms) after the action, for readable video. */
+    waitMs?: number;
+}
+/**
+ * Parse a markdown scenario string into steps.
+ *
+ * Only numbered list items (`1.`, `2.`, ...) inside a "### Steps" section (or
+ * anywhere in the document if no such heading exists) are converted. Other
+ * content is ignored.
+ */
+export declare function parseMarkdownScenario(md: string): ScenarioStep[];
+/** Read a scenario file from disk and parse it. */
+export declare function parseMarkdownScenarioFile(filePath: string): Promise<ScenarioStep[]>;
+//# sourceMappingURL=markdown-parser.d.ts.map

package/dist/extensions/browser/scenario/markdown-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-parser.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/scenario/markdown-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,GACP,MAAM,GACN,YAAY,GACZ,UAAU,GACV,WAAW,GACX,MAAM,CAAC;AAEX,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8GD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE,CA6BhE;AAED,mDAAmD;AACnD,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,EAAE,CAAC,CAIzB"}

package/dist/extensions/browser/scenario/markdown-parser.js

@@ -0,0 +1,159 @@
+/**
+ * Parse a markdown test scenario into a list of executable browser steps.
+ *
+ * Recognises the scenario format produced by @scenario_writer, e.g.:
+ *
+ *   ### Steps
+ *   1. **Navigate** to http://localhost:3008
+ *   2. **Click** the "Login" button
+ *   3. **Type** `user@example.com` into the email field
+ *   4. **Wait** for text "Dashboard" to appear
+ *   5. **Screenshot** checkpoint
+ *
+ * Each numbered list item becomes one step. The leading bold token (e.g.
+ * **Click**) maps to a browser action. Unrecognised actions are returned as
+ * `note` steps so the caller can still record timing without failing.
+ */
+const ACTION_KEYWORDS = {
+    navigate: "navigate",
+    go: "navigate",
+    open: "navigate",
+    visit: "navigate",
+    click: "click",
+    tap: "click",
+    type: "type",
+    enter: "type",
+    fill: "type",
+    press: "press",
+    key: "press",
+    select: "select",
+    choose: "select",
+    hover: "hover",
+    wait: "wait",
+    pause: "wait",
+    screenshot: "screenshot",
+    snapshot: "screenshot",
+    capture: "screenshot",
+    evaluate: "evaluate",
+    run: "evaluate",
+    fill_form: "fill_form",
+    fillform: "fill_form",
+};
+/** Extract the first bold token (e.g. **Click**) and map it to an action. */
+function parseAction(line) {
+    const bold = line.match(/\*\*([A-Za-z_]+)\*\*/);
+    if (bold) {
+        const key = bold[1].toLowerCase().replace(/\s+/g, "_");
+        if (ACTION_KEYWORDS[key])
+            return ACTION_KEYWORDS[key];
+    }
+    // Fallback: first word of the line.
+    const first = line.trim().split(/[\s,]+/)[0]?.toLowerCase().replace(/[^a-z_]/g, "");
+    if (first && ACTION_KEYWORDS[first])
+        return ACTION_KEYWORDS[first];
+    return "note";
+}
+/** Extract a backtick-quoted code/value from the line. */
+function parseBacktick(line) {
+    const m = line.match(/`([^`]+)`/);
+    return m ? m[1] : undefined;
+}
+/** Extract a quoted string (double or single quotes) from the line. */
+function parseQuoted(line) {
+    const m = line.match(/"([^"]+)"|'([^']+)'/);
+    return m ? (m[1] ?? m[2]) : undefined;
+}
+/** Extract a URL from the line. */
+function parseUrl(line) {
+    const m = line.match(/https?:\/\/[^\s)"`]+/);
+    return m ? m[0] : undefined;
+}
+function buildStep(line, index) {
+    const raw = line.trim();
+    const action = parseAction(raw);
+    const step = { action, raw: `Step ${index}: ${raw}`, waitMs: undefined };
+    switch (action) {
+        case "navigate": {
+            step.target = parseUrl(raw) ?? parseBacktick(raw) ?? parseQuoted(raw);
+            break;
+        }
+        case "click":
+        case "hover": {
+            step.target = parseQuoted(raw) ?? parseBacktick(raw);
+            break;
+        }
+        case "type": {
+            // "Type `value` into <target>" — value is backtick, target is quoted.
+            step.value = parseBacktick(raw);
+            step.target = parseQuoted(raw);
+            break;
+        }
+        case "press": {
+            step.value = parseBacktick(raw) ?? parseQuoted(raw);
+            break;
+        }
+        case "select": {
+            step.target = parseQuoted(raw);
+            step.value = parseBacktick(raw);
+            break;
+        }
+        case "wait": {
+            // "Wait for text 'X'" or "Wait 500ms"
+            step.value = parseQuoted(raw) ?? parseBacktick(raw);
+            const ms = raw.match(/(\d+)\s*ms/);
+            if (ms) {
+                step.value = ms[1];
+                step.waitMs = Number(ms[1]);
+            }
+            break;
+        }
+        case "screenshot":
+        case "note":
+        case "evaluate":
+        case "fill_form": {
+            step.target = parseBacktick(raw) ?? parseQuoted(raw);
+            break;
+        }
+    }
+    return step;
+}
+/**
+ * Parse a markdown scenario string into steps.
+ *
+ * Only numbered list items (`1.`, `2.`, ...) inside a "### Steps" section (or
+ * anywhere in the document if no such heading exists) are converted. Other
+ * content is ignored.
+ */
+export function parseMarkdownScenario(md) {
+    const lines = md.split("\n");
+    const steps = [];
+    let inStepsSection = false;
+    let stepIndex = 0;
+    // Match "1." "2." etc. at line start (after optional whitespace).
+    const numberedRe = /^\s*\d+\.\s+(.+)/;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const lower = trimmed.toLowerCase();
+        // Track whether we are inside a Steps section.
+        if (/^#{1,6}\s+/.test(trimmed)) {
+            inStepsSection = /step/i.test(lower);
+            continue;
+        }
+        if (!inStepsSection) {
+            // Still allow top-level numbered steps if no Steps heading has been seen
+            // yet — but only once we encounter the first numbered item.
+        }
+        const m = line.match(numberedRe);
+        if (m && m[1].trim().length > 0) {
+            stepIndex++;
+            steps.push(buildStep(m[1], stepIndex));
+        }
+    }
+    return steps;
+}
+/** Read a scenario file from disk and parse it. */
+export async function parseMarkdownScenarioFile(filePath) {
+    const { readFile } = await import("node:fs/promises");
+    const content = await readFile(filePath, "utf-8");
+    return parseMarkdownScenario(content);
+}

package/dist/extensions/browser/scenario/scenario-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 registerScenarioTools(ext: ExtensionAPI, bs: BrowserService): void;
+//# sourceMappingURL=scenario-tool.d.ts.map

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

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