@aexol/spectral 0.9.212 → 0.9.216

package/dist/extensions/image-generation/index.js

@@ -2,13 +2,14 @@ import { Type } from "typebox";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
 import { generateImages, getImageModel, getImageModels } from "../../sdk/ai/index.js";
-// App-layer routing helpers (mirror aexol-mcp.ts): obtain backendUrl +
-// machineJwt the same way agent-bridge.ts gets them for text models, so image
-// generation routes through the backend proxy (POST /image/generation) using
-// the backend's own OPENROUTER_API_KEY instead of a local env key.
-import { getApiUrl, readConfig } from "../../config.js";
-import { loadMachine } from "../../relay/machine-store.js";
-import { isJwtExpired } from "../../relay/registration.js";
+import { base64FromImageData } from "../../sdk/ai/utils/image-source.js";
+import { uploadImage } from "../../backend/generated-images.js";
+// Backend routing (backendUrl + machineJwt) is resolved the same way
+// agent-bridge.ts gets them for text models, so image generation routes
+// through the backend proxy (POST /image/generation) using the backend's own
+// OPENROUTER_API_KEY instead of a local env key. Shared with every other
+// CLI-side image hoster (e.g. desktop screenshots).
+import { resolveBackendRouting } from "../../backend/machine-routing.js";
 const imageReferenceSchema = Type.Union([
     Type.String({
         description: "Path to a reference image file (relative to the project working directory or absolute).",
@@ -132,7 +133,10 @@ function saveGeneratedImages(images, prompt, cwd) {
     mkdirSync(dir, { recursive: true });
     const base = slugFromPrompt(prompt);
     const ts = timestamp();
-    return images.map((image, index) => {
+    return images.flatMap((image, index) => {
+        // URL-only images are not persisted locally (no bytes available here).
+        if (!image.data)
+            return [];
         const ext = extensionForMimeType(image.mimeType);
         const filename = `${base}-${ts}-${String(index + 1).padStart(2, "0")}.${ext}`;
         const filepath = join(dir, filename);
@@ -140,7 +144,60 @@ function saveGeneratedImages(images, prompt, cwd) {
         return filepath;
     });
 }
-function resultText(count, model, credits, savedPaths) {
+function bytesFromImageData(data) {
+    return new Uint8Array(Buffer.from(base64FromImageData(data), "base64"));
+}
+/**
+ * Make every generated image reachable through a backend URL so the session
+ * can carry a URL instead of base64.
+ *
+ * Images the backend already stored (`store: true` on `/image/generation`) are
+ * passed through untouched — no upload-url, no PUT, no `/confirm`. Only images
+ * that came back as base64 (fallback: object storage unavailable) are uploaded
+ * from here. Best effort by design: a storage outage (503, network) must not
+ * fail image generation — the caller falls back to the local file + inline
+ * bytes and annotates the result text.
+ *
+ * The returned array is aligned 1:1 with `images`.
+ */
+async function hostGeneratedImages(images, routing, signal) {
+    return Promise.all(images.map(async (image) => {
+        // Already stored server-side: the bytes never travelled to the CLI.
+        if (image.url && image.imageId)
+            return { hosted: { url: image.url, imageId: image.imageId } };
+        if (!routing)
+            return { error: "not routed through the backend (image kept local)" };
+        if (!image.data)
+            return { error: "image has no inline bytes (kept local)" };
+        try {
+            const result = await uploadImage({
+                backendUrl: routing.backendUrl,
+                token: routing.machineJwt,
+                bytes: bytesFromImageData(image.data),
+                contentType: image.mimeType || "image/png",
+                kind: "generated",
+                signal,
+            });
+            return { result };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+    }));
+}
+/** Whether the image ended up reachable through a backend URL. */
+function isHosted(outcome) {
+    return Boolean(outcome.hosted ?? outcome.result);
+}
+/** Backend-relative url of a hosted image (server-stored or CLI-uploaded). */
+function hostedUrl(outcome) {
+    return outcome.hosted?.url ?? outcome.result.url;
+}
+/** Backend image id of a hosted image. */
+function hostedId(outcome) {
+    return outcome.hosted?.imageId ?? outcome.result.imageId;
+}
+function resultText(count, model, credits, savedPaths, outcomes) {
     const lines = [`✓ Generated ${count} image${count === 1 ? "" : "s"}`, `Model: ${model}`];
     lines.push(`Cost: ${credits ?? 0} credits`);
     if (savedPaths.length > 0) {
@@ -148,29 +205,29 @@ function resultText(count, model, credits, savedPaths) {
         for (const path of savedPaths)
             lines.push(`- ${path}`);
     }
-    return lines.join("\n");
-}
-/**
- * Resolve backend routing for image generation, mirroring how agent-bridge.ts
- * obtains `backendUrl` + `machineJwt` for text models. The machine JWT is the
- * same token the CLI registers with (see serve.ts → registration.record), so
- * this is exactly equivalent to `AgentBridgeOptions.machineJwt`.
- *
- * Returns `null` when routing cannot be resolved (e.g. not logged in); the
- * caller then falls back to the SDK's local-key path.
- */
-async function resolveBackendRouting() {
-    const cfg = await readConfig();
-    if (!cfg)
-        return null;
-    const machine = await loadMachine();
-    if (machine?.machineJwt && !isJwtExpired(machine.machineJwt)) {
-        const backendUrl = process.env.SPECTRAL_BACKEND_URL ||
-            getApiUrl(cfg.apiUrl).replace(/\/mcp\/?$/, "");
-        return { backendUrl, machineJwt: machine.machineJwt };
+    // Images the backend stored itself never get a local copy, because the
+    // bytes were never sent to the CLI — say so instead of staying silent.
+    const serverStored = outcomes.filter((outcome) => outcome.hosted);
+    if (serverStored.length > 0) {
+        lines.push(`Stored in backend object storage: ${serverStored.length} image${serverStored.length === 1 ? "" : "s"}` +
+            (savedPaths.length === 0 ? " (no local copy written)" : ""));
+    }
+    const hosted = outcomes.filter(isHosted);
+    if (hosted.length > 0) {
+        lines.push("Hosted:");
+        for (const outcome of hosted)
+            lines.push(`- ${hostedUrl(outcome)}`);
+    }
+    const failed = outcomes.filter((outcome) => !outcome.hosted && !outcome.result && outcome.error);
+    if (failed.length > 0) {
+        // Explicit annotation: the image bytes were NOT uploaded, so they exist
+        // only as local files (and inline base64 in this result).
+        lines.push(`⚠️ ${failed.length} image${failed.length === 1 ? "" : "s"} could not be uploaded to cloud storage and ` +
+            "exist only locally (paths above); remote URL unavailable.");
+        for (const upload of failed)
+            lines.push(`- ${upload.error}`);
     }
-    // No usable machine JWT — let the SDK fall back to local OPENROUTER_API_KEY.
-    return null;
+    return lines.join("\n");
 }
 export default async function imageGenerationExtension(ext) {
     const tool = {
@@ -204,6 +261,12 @@ export default async function imageGenerationExtension(ext) {
             const routing = await resolveBackendRouting();
             const response = await generateImages(model, context, {
                 ...input,
+                // Ask the backend proxy to keep the bytes in its own object
+                // storage: they are already there after OpenRouter answered, so
+                // this avoids shipping base64 to the CLI and uploading it back.
+                // The proxy degrades to base64 on its own when storage is
+                // unavailable, in which case the upload below takes over.
+                store: true,
                 signal,
                 ...(routing ? { backendUrl: routing.backendUrl, apiKey: routing.machineJwt } : {}),
             });
@@ -215,13 +278,49 @@ export default async function imageGenerationExtension(ext) {
                 };
             }
             const images = response.output.filter((item) => item.type === "image");
+            // Local copy first — for images that actually came back as bytes.
+            // Server-stored images have no `data` here, so they are skipped
+            // (and reported as such in the result text). It remains the
+            // fallback when the backend storage is unavailable, never a hard
+            // error.
             const savedPaths = saveGeneratedImages(images, input.prompt, ctx.cwd);
+            const outcomes = await hostGeneratedImages(images, routing, signal);
+            // Swap base64 for the hosted URL: the session keeps `{ url, imageId }`
+            // and never stores `data`. Images that failed to upload keep their
+            // inline bytes (fallback, annotated in the result text).
+            let imageCursor = 0;
+            const blocks = response.output.map((item) => {
+                if (item.type !== "image")
+                    return item;
+                const outcome = outcomes[imageCursor++];
+                if (isHosted(outcome)) {
+                    return {
+                        type: "image",
+                        url: hostedUrl(outcome),
+                        imageId: hostedId(outcome),
+                        mimeType: item.mimeType,
+                    };
+                }
+                return item;
+            });
+            const hosted = outcomes.filter(isHosted);
             return {
                 content: [
-                    { type: "text", text: resultText(images.length, response.model, response.usage?.credits, savedPaths) },
-                    ...response.output,
+                    {
+                        type: "text",
+                        text: resultText(images.length, response.model, response.usage?.credits, savedPaths, outcomes),
+                    },
+                    ...blocks,
                 ],
-                details: { isError: false, model: response.model, count: images.length, usage: response.usage, savedPaths },
+                details: {
+                    isError: false,
+                    model: response.model,
+                    count: images.length,
+                    usage: response.usage,
+                    savedPaths,
+                    imageIds: hosted.map(hostedId),
+                    urls: hosted.map(hostedUrl),
+                },
             };
         },
     };

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/seo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAoBpE,wBAA8B,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6D3E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/seo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAqBpE,wBAA8B,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA8D3E"}

package/dist/extensions/seo/index.js

@@ -16,6 +16,7 @@ import { registerCrawlTools } from "./tools/crawl.js";
 import { registerKeywordTools } from "./tools/keywords.js";
 import { registerPerformanceTools } from "./tools/performance.js";
 import { registerBatchTools } from "./tools/batch.js";
+import { registerBackendBridgeTools } from "./tools/backend-bridge.js";
 export default async function seoExtension(ext) {
     const config = loadSeoConfig();
     // Clean up resources on session shutdown.
@@ -59,6 +60,7 @@ export default async function seoExtension(ext) {
         { name: "keywords", fn: () => registerKeywordTools(ext, config) },
         { name: "performance", fn: () => registerPerformanceTools(ext, config) },
         { name: "batch", fn: () => registerBatchTools(ext, config) },
+        { name: "backend-bridge", fn: () => registerBackendBridgeTools(ext, config) },
     ];
     let totalRegistered = 0;
     for (const registrar of registrars) {
@@ -101,6 +103,8 @@ const SEO_TOOL_NAMES = [
     "seo_keyword_density",
     "seo_readability",
     "seo_content_optimize",
+    "seo_record_audit",
+    "seo_list_audits",
     "seo_performance",
     "seo_page_weight",
     "seo_render_blocking",

package/dist/extensions/seo/tools/backend-bridge.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerBackendBridgeTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=backend-bridge.d.ts.map

package/dist/extensions/seo/tools/backend-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-bridge.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/backend-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA4I9C,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAmXrF"}

package/dist/extensions/seo/tools/backend-bridge.js

@@ -0,0 +1,378 @@
+import { runFullAudit } from "./full-audit.js";
+import { generateMarkdownReport } from "./report.js";
+import { errorResult, textResult } from "./helpers.js";
+// ── Auth resolution (mirrors kanban-bridge pattern) ──
+import { getApiUrl, readConfig } from "../../../config.js";
+import { ensureAuthenticated } from "../../../auth-helper.js";
+import { loadMachine } from "../../../relay/machine-store.js";
+import { isJwtExpired } from "../../../relay/registration.js";
+let _reauthAttempted = false;
+async function resolveSeoBridgeConfig() {
+    const cfg = await readConfig();
+    if (!cfg) {
+        if (!_reauthAttempted) {
+            _reauthAttempted = true;
+            process.stderr.write("[seo-bridge] No config found. Attempting OAuth login...\n");
+            const result = await ensureAuthenticated();
+            if (result.ok && result.config) {
+                return resolveSeoBridgeConfig();
+            }
+        }
+        process.stderr.write("[seo-bridge] No config found. Run `spectral login`.\n");
+        return null;
+    }
+    if (cfg.teamApiKey && !cfg.userJwt && !_reauthAttempted) {
+        _reauthAttempted = true;
+        process.stderr.write("[seo-bridge] Team API key found but no user JWT. SEO audit requires user auth — skip for now.\n");
+        return null;
+    }
+    let token = "";
+    const machine = await loadMachine();
+    if (machine?.machineJwt && !isJwtExpired(machine.machineJwt)) {
+        token = machine.machineJwt;
+        process.stderr.write(`[seo-bridge] Using machine JWT (machine: ${machine.machineName}).\n`);
+    }
+    else if (cfg.userJwt) {
+        token = cfg.userJwt;
+        process.stderr.write("[seo-bridge] Using user JWT.\n");
+    }
+    else {
+        process.stderr.write("[seo-bridge] No valid auth token. Run `spectral login`.\n");
+        return null;
+    }
+    const backendUrl = getApiUrl(cfg.apiUrl);
+    return { token, backendUrl };
+}
+// ── GraphQL helpers ──
+class GraphQLError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "GraphQLError";
+        this.status = status;
+    }
+}
+async function graphqlRequest(backendUrl, token, query, variables) {
+    const body = JSON.stringify({ query, variables });
+    const res = await fetch(`${backendUrl}/graphql`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body,
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = (await res.text()).slice(0, 300);
+        }
+        catch { /* */ }
+        throw new GraphQLError(`HTTP ${res.status} from GraphQL${detail ? `: ${detail}` : ""}`, res.status);
+    }
+    const rawBody = await res.text();
+    let json;
+    try {
+        json = JSON.parse(rawBody);
+    }
+    catch {
+        throw new GraphQLError(`GraphQL returned non-JSON: ${rawBody.slice(0, 200)}`);
+    }
+    if (json.errors && json.errors.length > 0) {
+        throw new GraphQLError(json.errors.map((e) => e.message).join("; "));
+    }
+    return json.data;
+}
+const AUDIT_TASK_FRAGMENT = `
+  id
+  url
+  status
+  score
+  summary
+  result
+  report
+  error
+  createdAt
+  completedAt
+`;
+// ── Tool registration ──
+export function registerBackendBridgeTools(ext, config) {
+    const processAuditQueueTool = {
+        name: "seo_process_audit_queue",
+        label: "Process Pending SEO Audits",
+        description: "Poll the Aexol Studio backend for pending SEO audit tasks, run each audit locally, " +
+            "generate a formatted report, and push the results back to the backend. " +
+            "This bridges the gap between the landing UI (where users request audits) and " +
+            "the local CLI extension (which runs the actual offline SEO analysis). " +
+            "Requires an active `spectral login` session.",
+        promptSnippet: "`seo_process_audit_queue` — process all pending SEO audit tasks from Studio",
+        promptGuidelines: [
+            "When a user asks to run pending SEO audits, process the audit queue, check for SEO tasks, or sync audit results to the backend, use seo_process_audit_queue.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of pending audits to process. Default: 5.",
+                },
+                status: {
+                    type: "string",
+                    description: "Filter by status. Default: 'PENDING'.",
+                },
+            },
+            required: [],
+        },
+        async execute(_toolCallId, params) {
+            const { limit: rawLimit, status: rawStatus } = (params ?? {});
+            const limit = rawLimit ?? 5;
+            const status = rawStatus ?? "PENDING";
+            try {
+                // 1. Resolve auth
+                const auth = await resolveSeoBridgeConfig();
+                if (!auth) {
+                    return errorResult("Not authenticated. Run `spectral login` first, then retry.");
+                }
+                // 2. Fetch pending tasks
+                const data = await graphqlRequest(auth.backendUrl, auth.token, `query($limit: Int, $status: String) {
+            seoAuditTasks(limit: $limit, status: $status) {
+              ${AUDIT_TASK_FRAGMENT}
+            }
+          }`, { limit, status });
+                const tasks = data.seoAuditTasks;
+                if (!tasks || tasks.length === 0) {
+                    return textResult("No pending SEO audit tasks found.");
+                }
+                // 3. Process each task
+                const results = [];
+                let succeeded = 0;
+                let failed = 0;
+                for (const task of tasks) {
+                    try {
+                        process.stderr.write(`[seo-bridge] Running audit for ${task.url} (task ${task.id})...\n`);
+                        // Update status to RUNNING
+                        await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!) {
+                seoStartAuditProcessing(id: $id) { id status }
+              }`, { id: task.id });
+                        // Run the full audit
+                        const auditResult = await runFullAudit(task.url, config, [
+                            "technical",
+                            "content",
+                            "schema",
+                            "images",
+                            "preload",
+                            "agentUx",
+                            "performance",
+                        ]);
+                        // Generate markdown report
+                        const report = generateMarkdownReport(auditResult, config);
+                        // Push results back
+                        const score = auditResult.overallScore;
+                        const summary = auditResult.summary;
+                        await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!, $score: Int!, $summary: String!, $result: JSON!, $report: String) {
+                seoCompleteAudit(id: $id, score: $score, summary: $summary, result: $result, report: $report) {
+                  id status
+                }
+              }`, {
+                            id: task.id,
+                            score,
+                            summary,
+                            result: auditResult,
+                            report,
+                        });
+                        succeeded++;
+                        results.push(`✓ ${task.url} — Score: ${score}/100 — ${auditResult.allIssues.length} issues`);
+                        process.stderr.write(`[seo-bridge] ✓ Completed ${task.url} (score: ${score}/100)\n`);
+                    }
+                    catch (err) {
+                        failed++;
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        results.push(`✗ ${task.url} — Error: ${errMsg}`);
+                        process.stderr.write(`[seo-bridge] ✗ Failed ${task.url}: ${errMsg}\n`);
+                        // Report failure to backend
+                        try {
+                            await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!, $error: String!) {
+                  seoFailAudit(id: $id, error: $error) { id status }
+                }`, { id: task.id, error: errMsg.slice(0, 500) });
+                        }
+                        catch {
+                            // Best effort
+                        }
+                    }
+                }
+                const summary = [
+                    `SEO Audit Queue — Processed ${tasks.length} task(s)`,
+                    `Succeeded: ${succeeded} | Failed: ${failed}`,
+                    "",
+                    ...results,
+                ].join("\n");
+                return textResult(summary, { succeeded, failed, results });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(processAuditQueueTool);
+    const recordAuditTool = {
+        name: "seo_record_audit",
+        label: "Run SEO Audit & Save to Studio",
+        description: "Run a full SEO audit on a URL and save the results to the Aexol Studio backend " +
+            "so they appear on the SEO dashboard. This runs all 7 audit categories (technical, " +
+            "content, schema, images, preload, agent UX, performance) and persists the score, " +
+            "summary, and full report. Use this when the user asks to audit a site and wants " +
+            "results saved for later reference.",
+        parameters: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "The URL to audit (must include https://). Example: https://aexol.com",
+                },
+            },
+            required: ["url"],
+        },
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            const { url } = (params ?? {});
+            if (!url) {
+                return errorResult("Missing required parameter: url");
+            }
+            try {
+                const auth = await resolveSeoBridgeConfig();
+                if (!auth) {
+                    return errorResult("Not authenticated. Run `spectral login` first, then retry.");
+                }
+                // Step 1: Create PENDING task
+                process.stderr.write(`[seo-bridge] Creating PENDING audit task for ${url}...\n`);
+                const startResp = await graphqlRequest(auth.backendUrl, auth.token, `mutation($url: String!) {
+            seoStartAudit(url: $url) { id url status }
+          }`, { url });
+                const taskId = startResp.seoStartAudit.id;
+                process.stderr.write(`[seo-bridge] Created PENDING task ${taskId} for ${url}\n`);
+                // Step 2: Transition to RUNNING
+                await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!) {
+            seoStartAuditProcessing(id: $id) { id status }
+          }`, { id: taskId });
+                process.stderr.write(`[seo-bridge] Task ${taskId} is now RUNNING\n`);
+                // Step 3: Run the local audit
+                process.stderr.write(`[seo-bridge] Running full audit on ${url}...\n`);
+                let auditResult;
+                let report;
+                let score;
+                let summary;
+                try {
+                    auditResult = await runFullAudit(url, config, [
+                        "technical",
+                        "content",
+                        "schema",
+                        "images",
+                        "preload",
+                        "agentUx",
+                        "performance",
+                    ]);
+                    report = generateMarkdownReport(auditResult, config);
+                    score = auditResult.overallScore;
+                    summary = auditResult.summary;
+                }
+                catch (auditErr) {
+                    const errMsg = auditErr instanceof Error ? auditErr.message : String(auditErr);
+                    await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!, $error: String!) {
+              seoFailAudit(id: $id, error: $error) { id url status error }
+            }`, { id: taskId, error: errMsg.slice(0, 500) }).catch(() => { });
+                    throw auditErr;
+                }
+                process.stderr.write(`[seo-bridge] Audit complete — Score: ${score}/100, ${auditResult.allIssues.length} issues. Saving to backend...\n`);
+                // Step 4: Complete the audit
+                await graphqlRequest(auth.backendUrl, auth.token, `mutation($id: ID!, $score: Int!, $summary: String!, $result: JSON!, $report: String) {
+            seoCompleteAudit(id: $id, score: $score, summary: $summary, result: $result, report: $report) {
+              id url status score
+            }
+          }`, {
+                    id: taskId,
+                    score,
+                    summary,
+                    result: auditResult,
+                    report,
+                });
+                process.stderr.write(`[seo-bridge] \u2713 Saved audit for ${url} to Studio.\n`);
+                return textResult(`\u2713 SEO audit complete and saved for ${url}\n` +
+                    `  Score: ${score}/100\n` +
+                    `  Issues: ${auditResult.allIssues.length}\n` +
+                    `  Summary: ${summary}\n\n` +
+                    `View the full report on your SEO dashboard at https://aexol.com/account/admin/seo/`, { url, score, issues: auditResult.allIssues.length, summary });
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[seo-bridge] \u2717 Failed to record audit for ${url}: ${errMsg}\n`);
+                return errorResult(`Failed to audit ${url}: ${errMsg}`);
+            }
+        },
+    };
+    const listAuditsTool = {
+        name: "seo_list_audits",
+        label: "List Past SEO Audits",
+        description: "Query past SEO audits from the Aexol Studio backend. Use this to check if a URL " +
+            "has already been audited, compare scores over time, or reference previous findings. " +
+            "Returns audit id, url, score, issue count, and date for each result.",
+        parameters: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Maximum number of audits to return. Default: 10.",
+                },
+                url: {
+                    type: "string",
+                    description: "Filter by URL (partial match supported). Use to check if a specific site has been audited.",
+                },
+                status: {
+                    type: "string",
+                    description: "Filter by status. Default: COMPLETED. Use for finding pending/failed audits.",
+                },
+            },
+        },
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            const { limit: rawLimit, url: urlFilter, status: rawStatus } = (params ?? {});
+            const limit = rawLimit ?? 10;
+            const status = rawStatus ?? "COMPLETED";
+            try {
+                const auth = await resolveSeoBridgeConfig();
+                if (!auth) {
+                    return errorResult("Not authenticated. Run `spectral login` first, then retry.");
+                }
+                const data = await graphqlRequest(auth.backendUrl, auth.token, `query($limit: Int, $status: String) {
+            seoAuditTasks(limit: $limit, status: $status) {
+              ${AUDIT_TASK_FRAGMENT}
+            }
+          }`, { limit, status });
+                const tasks = data.seoAuditTasks;
+                let filtered = tasks ?? [];
+                if (urlFilter) {
+                    const lower = urlFilter.toLowerCase();
+                    filtered = filtered.filter((t) => t.url.toLowerCase().includes(lower));
+                }
+                if (filtered.length === 0) {
+                    const hint = urlFilter
+                        ? `No audits found matching "${urlFilter}".`
+                        : "No past audits found. Run `seo_audit` first, then use `seo_record_audit` to save results.";
+                    return textResult(hint);
+                }
+                const lines = filtered.map((t) => {
+                    const scoreStr = t.score != null ? `${t.score}/100` : "\u2014";
+                    const dateStr = t.completedAt
+                        ? new Date(t.completedAt).toISOString().split("T")[0]
+                        : new Date(t.createdAt).toISOString().split("T")[0];
+                    return `  \u2022 ${t.url} \u2014 Score: ${scoreStr} \u2014 ${t.status} \u2014 ${dateStr} (id: ${t.id})`;
+                });
+                return textResult(`Past SEO Audits (${filtered.length} result${filtered.length !== 1 ? "s" : ""}):\n\n${lines.join("\n")}`);
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(recordAuditTool);
+    ext.registerTool(listAuditsTool);
+}

package/dist/extensions/seo/tools/full-audit.d.ts

@@ -6,6 +6,8 @@
  */
 import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
 import type { SeoConfig } from "../config.js";
+import type { FullAuditResult } from "../types.js";
 export type AuditCategory = "technical" | "content" | "schema" | "images" | "preload" | "agentUx" | "performance";
 export declare function registerFullAuditTools(ext: ExtensionAPI, config: SeoConfig): void;
+export declare function runFullAudit(url: string, config: SeoConfig, categories: AuditCategory[]): Promise<FullAuditResult>;
 //# sourceMappingURL=full-audit.d.ts.map

package/dist/extensions/seo/tools/full-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"full-audit.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/full-audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAe9C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAIlH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAqEjF"}
+{"version":3,"file":"full-audit.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/full-audit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAc,eAAe,EAAkC,MAAM,aAAa,CAAC;AAc/F,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAIlH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAqEjF;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,aAAa,EAAE,GAC1B,OAAO,CAAC,eAAe,CAAC,CAsa1B"}

package/dist/extensions/seo/tools/full-audit.js

@@ -74,7 +74,7 @@ export function registerFullAuditTools(ext, config) {
     };
     ext.registerTool(fullAuditTool);
 }
-async function runFullAudit(url, config, categories) {
+export async function runFullAudit(url, config, categories) {
     // Fetch the page once and reuse for all sub-audits.
     const fetchResult = await fetchPage(url, config);
     const allIssues = [];