@xpert-ai/plugin-live-dashboard 0.4.1 → 0.6.0

package/dist/lib/html-validation.js

@@ -19,9 +19,10 @@ const promises_1 = require("node:timers/promises");
 const v3_1 = require("zod/v3");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const html_validation_feedback_1 = require("./html-validation-feedback");
 const PLUGIN = '@xpert-ai/plugin-live-dashboard', ACTION = 'live_dashboard.validate-html', POOL = 'sandbox-browser';
 const reportSchema = v3_1.z.object({ ok: v3_1.z.boolean(), errors: v3_1.z.array(v3_1.z.string().max(300)).max(16),
-    requestedBindings: v3_1.z.array(v3_1.z.string().max(80)).max(60), renderedTextLength: v3_1.z.number().int().nonnegative() }).strict();
+    requestedBindings: v3_1.z.array(v3_1.z.string().max(80)).max(64), renderedTextLength: v3_1.z.number().int().nonnegative() }).strict();
 const recordSchema = v3_1.z.object({ tenantId: v3_1.z.string(), organizationId: v3_1.z.string(), userId: v3_1.z.string(), manifestId: v3_1.z.string(), deadline: v3_1.z.number(),
     filePath: v3_1.z.string(), workspacePath: v3_1.z.string(), size: v3_1.z.number(), sha256: v3_1.z.string() }).strict();
 const digest = (buffer) => (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
@@ -70,7 +71,7 @@ let HtmlDashboardValidation = class HtmlDashboardValidation {
                     const report = reportSchema.parse(JSON.parse(await redis.get(`${key}:report`) ?? 'null'));
                     finished = true;
                     if (!report.ok)
-                        throw new common_1.BadRequestException(`DASHBOARD_HTML_PREFLIGHT_FAILED: ${JSON.stringify(report.errors)}. Repair the Workspace HTML or include every required previewId, then retry. No dashboard was saved.`);
+                        throw (0, html_validation_feedback_1.htmlPreflightFailure)(manifest, report);
                     return { jobId, requestedBindings: report.requestedBindings, status: 'passed' };
                 }
                 await (0, promises_1.setTimeout)(250);

package/dist/lib/inspection-host.d.ts

@@ -0,0 +1,7 @@
+import { type DashboardComponent } from './dashboard-sources';
+/** One frame generation, one nonce; inspection is UI metadata and grants no query authority. */
+export declare function createDashboardInspector(frame: HTMLIFrameElement, components: DashboardComponent[], onSelect: (id: string | null) => void, onExit: () => void, standard?: boolean): {
+    prefix: string;
+    setEnabled(value: boolean): void;
+    dispose(): void;
+};

package/dist/lib/inspection-host.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDashboardInspector = createDashboardInspector;
+const v3_1 = require("zod/v3");
+const inspection_runtime_1 = require("./inspection-runtime");
+const dashboard_sources_1 = require("./dashboard-sources");
+const message = v3_1.z.discriminatedUnion('type', [
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('ready') }).strict(),
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('exit') }).strict(),
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('selected'), componentId: dashboard_sources_1.componentId.nullable() }).strict()
+]);
+/** One frame generation, one nonce; inspection is UI metadata and grants no query authority. */
+function createDashboardInspector(frame, components, onSelect, onExit, standard = false) {
+    const key = Array.from(crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, '0')).join('');
+    const host = frame.ownerDocument.defaultView;
+    let connected = false, enabled = false, disposed = false;
+    const send = () => {
+        if (connected && !disposed)
+            frame.contentWindow?.postMessage({ channel: 'live-dashboard.inspection', key, type: 'mode', enabled,
+                standard, components: components.map(({ id, elementId }) => ({ id, elementId })) }, '*');
+    };
+    const receive = (event) => {
+        if (disposed || event.source !== frame.contentWindow)
+            return;
+        const parsed = message.safeParse(event.data);
+        if (!parsed.success || parsed.data.key !== key)
+            return;
+        if (parsed.data.type === 'ready') {
+            connected = true;
+            send();
+        }
+        else if (parsed.data.type === 'exit') {
+            enabled = false;
+            onExit();
+        }
+        else {
+            const selected = parsed.data.componentId;
+            if (enabled && (selected === null || components.some(item => item.id === selected)))
+                onSelect(selected);
+        }
+    };
+    host.addEventListener('message', receive);
+    return {
+        prefix: `<script>${inspection_runtime_1.DASHBOARD_INSPECTION_RUNTIME.replace('__INSPECTION_SESSION__', key)}</script>`,
+        setEnabled(value) { enabled = value; send(); },
+        dispose() { enabled = false; send(); disposed = true; host.removeEventListener('message', receive); }
+    };
+}

package/dist/lib/inspection-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Injected into the isolated dashboard only; it never reads or executes query definitions. */
+export declare const DASHBOARD_INSPECTION_RUNTIME: string;

package/dist/lib/inspection-runtime.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DASHBOARD_INSPECTION_RUNTIME = void 0;
+/** Injected into the isolated dashboard only; it never reads or executes query definitions. */
+exports.DASHBOARD_INSPECTION_RUNTIME = String.raw `
+(() => {
+  const key = '__INSPECTION_SESSION__', channel = 'live-dashboard.inspection';
+  let enabled = false, standard = false, components = [], selected = null, overlay, previousFocus;
+  const tabs = new Map();
+  const post = (type, data = {}) => parent.postMessage({ channel, key, type, ...data }, '*');
+  function outline(element) {
+    selected = element;
+    if (!element || !enabled) { if (overlay) overlay.hidden = true; return; }
+    if (!overlay) {
+      overlay = document.createElement('div');
+      overlay.setAttribute('aria-hidden', 'true');
+      overlay.style.cssText = 'position:fixed;pointer-events:none;z-index:2147483647;border:2px solid #2563eb;background:rgba(37,99,235,.06);box-sizing:border-box';
+      document.documentElement.append(overlay);
+    }
+    const r = element.getBoundingClientRect();
+    Object.assign(overlay.style, { left:r.left+'px', top:r.top+'px', width:r.width+'px', height:r.height+'px' });
+    overlay.hidden = false;
+  }
+  function target(node) {
+    for (let element = node instanceof Element ? node : null; element; element = element.parentElement) {
+      if (components.some(c => c.elementId === (standard ? element.getAttribute('data-layout-block-id') : element.id))) return element;
+    }
+    return null;
+  }
+  function registerTargets() {
+    if (!enabled) return;
+    for (const component of components) {
+      const element = standard ? [...document.querySelectorAll('[data-layout-block-id]')].find(e => e.getAttribute('data-layout-block-id') === component.elementId) : document.getElementById(component.elementId);
+      if (element && !tabs.has(element)) { tabs.set(element, element.getAttribute('tabindex')); element.setAttribute('tabindex', '0'); }
+    }
+  }
+  new MutationObserver(registerTargets).observe(document, { childList:true, subtree:true });
+  function activate(value) {
+    if (value === enabled) return;
+    enabled = value;
+    if (enabled) {
+      previousFocus = document.activeElement;
+      registerTargets();
+    } else {
+      outline(null);
+      for (const [element, value] of tabs) value === null ? element.removeAttribute('tabindex') : element.setAttribute('tabindex', value);
+      tabs.clear();
+      if (previousFocus instanceof HTMLElement && previousFocus.isConnected) previousFocus.focus({ preventScroll:true });
+    }
+  }
+  function choose(event) {
+    if (!enabled) return;
+    event.preventDefault(); event.stopImmediatePropagation();
+    const element = target(event.target), component = components.find(c => c.elementId === (standard ? element?.getAttribute('data-layout-block-id') : element?.id));
+    outline(element);
+    post('selected', { componentId:component?.id ?? null });
+  }
+  window.addEventListener('message', event => {
+    const m = event.data;
+    if (event.source !== parent || !m || m.channel !== channel || m.key !== key) return;
+    if (m.type === 'mode') { components = m.components; standard = m.standard; activate(m.enabled === true); }
+  });
+  window.addEventListener('pointermove', e => { if (enabled) outline(target(e.target)); }, true);
+  window.addEventListener('focusin', e => { if (enabled) outline(target(e.target)); }, true);
+  for (const name of ['pointerdown', 'pointerup', 'mousedown', 'mouseup', 'dblclick']) window.addEventListener(name, e => {
+    if (enabled) { e.preventDefault(); e.stopImmediatePropagation(); }
+  }, true);
+  window.addEventListener('click', choose, true);
+  window.addEventListener('keydown', e => {
+    if (!enabled) return;
+    if (e.key === 'Escape') { e.preventDefault(); e.stopImmediatePropagation(); activate(false); post('exit'); }
+    else if (e.key === 'Enter' || e.key === ' ') choose(e);
+  }, true);
+  window.addEventListener('scroll', () => { if (enabled) outline(selected); }, true);
+  window.addEventListener('resize', () => { if (enabled) outline(selected); });
+  post('ready');
+})();`;

package/dist/lib/json-input.d.ts

@@ -0,0 +1,4 @@
+type JsonInputField = 'requestJson' | 'binding.payloadJson' | 'bindingJson';
+/** Report syntax locations without echoing query text or native errors containing input fragments. */
+export declare function parseJsonInput(text: string, field: JsonInputField): unknown;
+export {};

package/dist/lib/json-input.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonInput = parseJsonInput;
+/** Report syntax locations without echoing query text or native errors containing input fragments. */
+function parseJsonInput(text, field) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        const match = /\bat position (\d+)(?: \(line \d+ column \d+\))?$/.exec(error.message);
+        const offset = match ? Number(match[1]) : error.message === 'Unexpected end of JSON input' ? text.length : undefined;
+        if (offset === undefined || offset > text.length) {
+            throw new Error(`DASHBOARD_INVALID_JSON: ${field} contains invalid JSON; the parser did not provide a character position. Supply one complete JSON object without Markdown fences.`);
+        }
+        const lines = text.slice(0, offset).split(/\r\n|\r|\n/);
+        const character = offset === text.length ? 'end of input' : JSON.stringify(String.fromCodePoint(text.codePointAt(offset)));
+        throw new Error(`DASHBOARD_INVALID_JSON: ${field} has invalid JSON at offset ${offset} (0-based UTF-16), line ${lines.length}, column ${lines.at(-1).length + 1} (1-based); found ${character}. Check this position and the preceding JSON delimiter or value.`);
+    }
+}

package/dist/lib/middleware.d.ts

@@ -1,10 +1,12 @@
+import { DashboardSaveRequests } from './save-requests';
 import type { TAgentMiddlewareMeta } from '@xpert-ai/contracts';
 import { type AgentMiddleware, type IAgentMiddlewareStrategy, type IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
 import { DashboardService } from './dashboard.service';
 export declare const DASHBOARD_GUIDANCE = "For a new independent dashboard, use a new unused HTML file path. An existing filename or matching title is not authorization to edit another Artifact; do not switch from creation to dashboard_open/update because a file already exists. For a new dashboard, call dashboard_list_sources before searching raw files, reading old scripts or creating transformations. Named governed sources may already provide the required query; inspect their provider contracts first. File-backed sources do not imply that a script must be written. For creating or editing live dashboards, first read the installed live-dashboard skill using read_skill_file and follow only the references relevant to the task. Use SandboxFile tools for all source-file authoring; HTML alone is not a saved dashboard. Follow preview.validation.checks immediately before authoring HTML; each suggestedCall must actually succeed. Business definitions, real data previews and nullable-filter tests are required before saving new or changed Bindings. Do not invent business data or substitute a different metric without agreement. Report completion only from a successful dashboard_create/dashboard_create_html/dashboard_update draft receipt. Human publication is separate. Successful create, update and open tools emit a chat resource card automatically; resourceCard.status reports emission. Its Open button selects the exact dashboard in Workbench. Never fabricate a link, call present_files for dashboard HTML, or output card JSON as text. If card delivery is unavailable, report the saved receipt and use the Workbench picker.";
 export declare class DashboardMiddleware implements IAgentMiddlewareStrategy {
     private readonly service;
+    private readonly saveRequests?;
     readonly meta: TAgentMiddlewareMeta;
-    constructor(service: DashboardService);
+    constructor(service: DashboardService, saveRequests?: DashboardSaveRequests | undefined);
     createMiddleware(_options: unknown, context: IAgentMiddlewareContext): AgentMiddleware;
 }

package/dist/lib/middleware.js

@@ -8,8 +8,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DashboardMiddleware = exports.DASHBOARD_GUIDANCE = void 0;
+const common_1 = require("@nestjs/common");
+const save_requests_1 = require("./save-requests");
+const bounded_map_1 = require("./bounded-map");
 const runtime_context_1 = require("./runtime-context");
 const definition_tools_1 = require("./definition-tools");
 const analytics_source_1 = require("./analytics-source");
@@ -37,6 +43,7 @@ const resource_card_1 = require("./resource-card");
 const dashboard_icon_1 = require("./dashboard-icon");
 const preview_retry_1 = require("./preview-retry");
 const prompt_workflows_1 = require("./prompt-workflows");
+const json_input_1 = require("./json-input");
 const middlewareOptionsSchema = v3_1.z.object({ allowedFinalProviders: v3_1.z.array(v3_1.z.string().min(1)).min(1).max(20).optional(),
     maxModelCalls: v3_1.z.number().int().min(1).max(64).default(24) }).strict().default({});
 const providerOptionSchema = {
@@ -45,8 +52,9 @@ const providerOptionSchema = {
 };
 exports.DASHBOARD_GUIDANCE = `For a new independent dashboard, use a new unused HTML file path. An existing filename or matching title is not authorization to edit another Artifact; do not switch from creation to dashboard_open/update because a file already exists. For a new dashboard, call dashboard_list_sources before searching raw files, reading old scripts or creating transformations. Named governed sources may already provide the required query; inspect their provider contracts first. File-backed sources do not imply that a script must be written. For creating or editing live dashboards, first read the installed live-dashboard skill using read_skill_file and follow only the references relevant to the task. Use SandboxFile tools for all source-file authoring; HTML alone is not a saved dashboard. Follow preview.validation.checks immediately before authoring HTML; each suggestedCall must actually succeed. Business definitions, real data previews and nullable-filter tests are required before saving new or changed Bindings. Do not invent business data or substitute a different metric without agreement. Report completion only from a successful dashboard_create/dashboard_create_html/dashboard_update draft receipt. Human publication is separate. Successful create, update and open tools emit a chat resource card automatically; resourceCard.status reports emission. Its Open button selects the exact dashboard in Workbench. Never fabricate a link, call present_files for dashboard HTML, or output card JSON as text. If card delivery is unavailable, report the saved receipt and use the Workbench picker.`;
 let DashboardMiddleware = class DashboardMiddleware {
-    constructor(service) {
+    constructor(service, saveRequests) {
         this.service = service;
+        this.saveRequests = saveRequests;
         this.meta = {
             name: 'LiveDashboard', label: { en_US: 'Live dashboards', zh_Hans: '实时看板' },
             description: { en_US: 'Discover, preview, create and update governed live dashboards.', zh_Hans: '发现业务数据、验证查询并持续修改实时看板。' },
@@ -62,6 +70,7 @@ let DashboardMiddleware = class DashboardMiddleware {
         };
     }
     createMiddleware(_options, context) {
+        const runId = (0, node_crypto_1.randomUUID)();
         const options = middlewareOptionsSchema.parse(_options);
         if (!context.xpertId)
             throw new Error('DASHBOARD_ASSISTANT_REQUIRED');
@@ -104,7 +113,7 @@ let DashboardMiddleware = class DashboardMiddleware {
             const controls = Object.fromEntries(binding.parameters.map((parameter) => [parameter.controlId, parameter.defaultValue ?? null]));
             const dataset = await this.service.preview(scope, { binding, controls });
             const previewId = previewKey(binding, controls);
-            if (previews.size >= 24 && !previews.has(previewId))
+            if (previews.size >= 256 && !previews.has(previewId))
                 throw new Error('DASHBOARD_PREVIEW_LIMIT');
             previews.set(previewId, binding);
             const rows = dataset.rows.slice(0, 20);
@@ -133,7 +142,7 @@ let DashboardMiddleware = class DashboardMiddleware {
                 }
             }
         };
-        const save = async (input, config, html, dependencies = []) => {
+        const save = async (input, config, html, dependencies = [], sourceFile) => {
             const { previewIds, supersedesPaths, creationIntent, ...definition } = input;
             const bindings = resolvePreviews(previewIds);
             const manifest = dashboard_schema_1.dashboardSchema.parse({ ...definition, bindings, schema: 'xpert.live-dashboard', id: (0, node_crypto_1.randomUUID)(),
@@ -153,6 +162,8 @@ let DashboardMiddleware = class DashboardMiddleware {
             const sameTitle = [...created.values()].find(item => item.manifest.title === manifest.title);
             if (sameTitle && !creationIntent)
                 throw new Error(`DASHBOARD_ALREADY_CREATED: this run already saved this dashboard. Use dashboard_open with artifactId ${sameTitle.receipt.artifactId}, then dashboard_update with fresh previewIds for data changes; preserve the Artifact instead of creating another one.`);
+            if (this.saveRequests && bindings.length > 8)
+                return JSON.stringify(await this.saveRequests.submit(scope, manifest, null, 0, `${runId}/${key}`, sourceFile));
             const result = await this.service.save(scope, manifest, null);
             created.set(key, { manifest, receipt: result });
             const resourceCard = await (0, resource_card_1.emitDashboardCard)(scope, { ...result, state: 'draft', revision: result.draftRevision }, config);
@@ -164,6 +175,20 @@ let DashboardMiddleware = class DashboardMiddleware {
                 throw new Error('DASHBOARD_WORKSPACE_REQUIRED');
             return files;
         });
+        const pendingRequests = new Map();
+        const activeRequests = new Set(), delivered = new Set();
+        const observeRequest = async (result, config) => {
+            if (!result.terminal)
+                activeRequests.add(result.requestId);
+            else
+                activeRequests.delete(result.requestId);
+            if (!result.dashboard || delivered.has(result.requestId))
+                return JSON.stringify(result);
+            delivered.add(result.requestId);
+            const resourceCard = await (0, resource_card_1.emitDashboardCard)(scope, { ...result.dashboard, state: 'draft', revision: result.dashboard.draftRevision }, config);
+            return JSON.stringify({ ...result, resourceCard });
+        };
+        let observing = false, waits = 0;
         const previewRetries = (0, preview_retry_1.createPreviewRetryGuard)();
         let modelCalls = 0;
         return { name: 'LiveDashboard', contextSchema: editing_1.dashboardContextSchema, stateSchema: editing_session_1.dashboardStateSchema,
@@ -172,12 +197,28 @@ let DashboardMiddleware = class DashboardMiddleware {
             wrapToolCall: async (request, handler) => {
                 const name = request.toolCall.name;
                 const args = request.toolCall.args;
+                observing = name === 'dashboard_wait_request';
+                if (observing && ++waits > 40)
+                    throw new Error('DASHBOARD_WAIT_BUDGET: resume with dashboard_get_request using the existing requestId; do not resubmit.');
                 const path = (0, plugin_sdk_1.workspaceFileMutationPath)(request.tool && 'metadata' in request.tool ? request.tool.metadata : undefined, args);
                 const creation = name === 'dashboard_create_html' ? agent_schema_1.createHtmlToolSchema.safeParse(args)
                     : name === 'dashboard_create' ? agent_schema_1.createToolSchema.safeParse(args) : undefined;
-                const save = dashboard_receipt_1.DASHBOARD_MUTATION_TOOLS.includes(name) ? evidence.beginSave(creation?.success ? creation.data.supersedesPaths : undefined, name === 'dashboard_create' ? 'draft' : 'source') : undefined;
+                const priorAttempt = (name === 'dashboard_wait_request' || name === 'dashboard_get_request') && typeof args.requestId === 'string' ? pendingRequests.get(args.requestId) : undefined;
+                const save = priorAttempt ?? (dashboard_receipt_1.DASHBOARD_MUTATION_TOOLS.includes(name) ? evidence.beginSave(creation?.success ? creation.data.supersedesPaths : undefined, name === 'dashboard_create' ? 'draft' : 'source') : undefined);
                 const result = path && (evidence.has(path) || previews.size > 0 && agent_schema_1.htmlPathSchema.safeParse(path).success)
                     ? await evidence.trackWrite(path, async () => handler(request)) : await previewRetries.run(request, handler);
+                if (save && 'content' in result && typeof result.content === 'string') {
+                    try {
+                        const pending = save_requests_1.saveRequestSchema.extend({ terminal: v3_1.z.boolean() }).passthrough().parse(JSON.parse(result.content));
+                        if (pending.terminal)
+                            activeRequests.delete(pending.requestId);
+                        else {
+                            pendingRequests.set(pending.requestId, save);
+                            activeRequests.add(pending.requestId);
+                        }
+                    }
+                    catch { /* normal synchronous result */ }
+                }
                 if (save && 'content' in result && (!('status' in result) || result.status !== 'error'))
                     await evidence.accept(save, result.content);
                 if ('content' in result && (!('status' in result) || result.status !== 'error')) {
@@ -201,18 +242,54 @@ let DashboardMiddleware = class DashboardMiddleware {
                     // A noncompliant model must not restart the failed loop even after tools were removed.
                     return result?.tool_calls?.length ? new messages_1.AIMessage(summary) : result;
                 }
-                const exhausted = ++modelCalls > options.maxModelCalls;
+                const exhausted = (observing ? modelCalls : ++modelCalls) > options.maxModelCalls;
                 if (exhausted && evidence.pending)
                     throw new Error('DASHBOARD_SAVE_NOT_CONFIRMED: no successful draft save receipt; Workspace changes have not been saved to the dashboard.');
-                const result = await handler({ ...request, ...(evidence.pending ? { toolChoice: 'required' } : {}), ...(exhausted ? { tools: [] } : {}), systemMessage: new messages_1.SystemMessage({ content: [
+                const result = await handler({ ...request, ...(evidence.pending || activeRequests.size ? { toolChoice: 'required' } : {}), ...(exhausted ? { tools: [] } : {}), systemMessage: new messages_1.SystemMessage({ content: [
                             ...(typeof request.systemMessage?.content === 'string' ? [{ type: 'text', text: request.systemMessage.content }] : request.systemMessage?.content ?? []),
-                            { type: 'text', text: exports.DASHBOARD_GUIDANCE + (editing.current() ? `\nCurrent editing target: ${JSON.stringify(editing.current())}. Continue this Artifact with dashboard_open/update unless the user explicitly requests a new independent dashboard.` : '') + '\n' + definition_tools_1.DEFINITION_GUIDANCE + '\n' + html_guidance_1.HTML_DASHBOARD_GUIDANCE + '\n' + editing_1.EDITING_GUIDANCE + (evidence.pending ? `\nDashboard changes are pending without a matching draft save receipt. Unsaved files: ${JSON.stringify(evidence.pendingPaths)}. Continue reading/repairing and call dashboard_create_html or dashboard_update with the exact file path; do not finish or claim it was saved. When abandoning earlier unsaved HTML creation candidates, explicitly pass their exact paths as supersedesPaths to dashboard_create or dashboard_create_html, matching the requested presentation mode. If a standard dashboard is already saved, repeat dashboard_create with the same definition/previewIds and supersedesPaths; do not create an unwanted HTML dashboard. This only abandons those candidates after a successful save; it never discards another Artifact editing copy.` : '') + (options.allowedFinalProviders ? `\nThis Assistant requires every saved dashboard binding to use one of these providers: ${options.allowedFinalProviders.join(', ')}. Other providers may be previewed only as upstream inputs. Do not save a direct-source substitute.` : '') + (exhausted ? '\nThe dashboard tool budget is exhausted. Stop calls; report only saved receipts or explain the concrete blocker truthfully.' : '') }
+                            { type: 'text', text: `Current dashboard authoring limit: ${this.service.maxBindings} Bindings (storage maximum 64). Shared charts may reuse one Binding; independent filter-option queries count too. Preview in batches, preserving each receipt and filter check.\n` + exports.DASHBOARD_GUIDANCE + (editing.current() ? `\nCurrent editing target: ${JSON.stringify(editing.current())}. Continue this Artifact with dashboard_open/update unless the user explicitly requests a new independent dashboard.` : '') + '\n' + definition_tools_1.DEFINITION_GUIDANCE + '\n' + html_guidance_1.HTML_DASHBOARD_GUIDANCE + '\n' + html_guidance_1.HTML_QUERY_ROUNDS + '\n' + editing_1.EDITING_GUIDANCE + (activeRequests.size ? `\nDurable save requests pending: ${JSON.stringify([...activeRequests])}. Keep calling dashboard_wait_request with the returned requestId and cursor until terminal. Do not resubmit or claim saved before a dashboard receipt. On a later conversation use dashboard_get_request to recover.` : '') + (evidence.pending ? `\nDashboard changes are pending without a matching draft save receipt. Unsaved files: ${JSON.stringify(evidence.pendingPaths)}. Continue reading/repairing and call dashboard_create_html or dashboard_update with the exact file path; do not finish or claim it was saved. When abandoning earlier unsaved HTML creation candidates, explicitly pass their exact paths as supersedesPaths to dashboard_create or dashboard_create_html, matching the requested presentation mode. If a standard dashboard is already saved, repeat dashboard_create with the same definition/previewIds and supersedesPaths; do not create an unwanted HTML dashboard. This only abandons those candidates after a successful save; it never discards another Artifact editing copy.` : '') + (options.allowedFinalProviders ? `\nThis Assistant requires every saved dashboard binding to use one of these providers: ${options.allowedFinalProviders.join(', ')}. Other providers may be previewed only as upstream inputs. Do not save a direct-source substitute.` : '') + (exhausted ? '\nThe dashboard tool budget is exhausted. Stop calls; report only saved receipts or explain the concrete blocker truthfully.' : '') }
                         ] }) });
-                if (evidence.pending && result && !result.tool_calls?.length)
+                if ((evidence.pending || activeRequests.size) && result && !result.tool_calls?.length)
                     throw new Error('DASHBOARD_SAVE_NOT_CONFIRMED: the model stopped without a successful draft save receipt.');
                 return result;
             }, tools: [
+                ...(this.saveRequests ? [
+                    (0, tools_1.tool)(async ({ requestId, cursor }, config) => observeRequest(await this.saveRequests.wait(scope, requestId, cursor, config.signal), config), {
+                        name: 'dashboard_wait_request', description: 'Wait up to 20 seconds for a durable save to change. Repeat with its returned cursor while nextAction=wait. A pending request is not a saved dashboard.', schema: save_requests_1.waitSaveRequestSchema
+                    }),
+                    (0, tools_1.tool)(async ({ requestId }, config) => observeRequest(await this.saveRequests.get(scope, requestId), config), {
+                        name: 'dashboard_get_request', description: 'Recover a prior durable save by its requestId. Do not submit duplicate work after reconnecting.', schema: save_requests_1.saveRequestSchema
+                    })
+                ] : []),
                 filterEvidence.tool,
+                (0, tools_1.tool)(async ({ items }) => JSON.stringify({ results: await (0, bounded_map_1.boundedMap)(items, async (item, index) => {
+                        try {
+                            return { index, status: 'succeeded', result: await previewRetries.attempt('dashboard_test_filter', item, () => filterEvidence.tool.invoke(item)) };
+                        }
+                        catch (error) {
+                            return { index, status: 'failed', message: error instanceof Error ? error.message : 'DASHBOARD_FILTER_TEST_FAILED' };
+                        }
+                    }) }), { name: 'dashboard_test_filter_batch', description: 'Run up to eight required filter checks with four workers. Preserves the exact per-preview filter evidence and retry limits.',
+                    schema: v3_1.z.object({ items: v3_1.z.array(filter_evidence_1.filterTestSchema).min(1).max(8) }).strict(), verboseParsingErrors: true }),
+                (0, tools_1.tool)(async ({ items }) => {
+                    const results = await (0, bounded_map_1.boundedMap)(items, async (item, index) => {
+                        try {
+                            const value = await previewRetries.attempt('dashboard_preview_binding', item, () => preview(plugin_sdk_1.analyticsBindingSchema.parse((0, json_input_1.parseJsonInput)(item.bindingJson, 'bindingJson'))));
+                            const result = JSON.parse(value), rows = result.rows.slice(0, 5);
+                            while (Buffer.byteLength(JSON.stringify(rows)) > 8000)
+                                rows.pop();
+                            return { index, status: 'succeeded', preview: { previewId: result.previewId, datasetId: result.datasetId, rows,
+                                    completeness: result.completeness, freshness: result.freshness, validation: result.validation,
+                                    preview: { displayedRows: rows.length, omittedRows: result.completeness.returnedRows - rows.length, note: 'Bounded display sample. Binding definition is unchanged from this batch item.' } } };
+                        }
+                        catch (error) {
+                            return { index, status: 'failed', message: error instanceof Error ? error.message : 'DASHBOARD_PREVIEW_FAILED' };
+                        }
+                    });
+                    return JSON.stringify({ results, next: 'Keep every successful previewId. Complete each preview.validation.checks using dashboard_test_filter or dashboard_test_filter_batch. Repair only failed items; never invent a receipt.' });
+                }, { name: 'dashboard_preview_batch', description: 'Preview up to eight complete canonical Bindings with at most four concurrent queries. Returns independent receipts and diagnostics; preserves retry and filter-evidence requirements.',
+                    schema: v3_1.z.object({ items: v3_1.z.array(v3_1.z.object({ bindingJson: v3_1.z.string().min(2).max(200000) }).strict()).min(1).max(8) }).strict(),
+                    verboseParsingErrors: true, metadata: { toolName: { en_US: 'Verify a batch of sources', zh_Hans: '批量验证看板来源' } } }),
                 ...(0, definition_tools_1.createDefinitionTools)(context, () => { listedSources = undefined; }),
                 (0, tools_1.tool)(async () => JSON.stringify({ libraries: (await (0, document_libraries_1.bundledLibraries)()).map(({ source, ...lock }) => lock),
                     online: { enabled: true, ...document_network_1.DASHBOARD_NETWORK_POLICY,
@@ -222,6 +299,7 @@ let DashboardMiddleware = class DashboardMiddleware {
                         bindingIds: [...new Set([...previews.values()].map(binding => binding.id))],
                         startup: 'const live = window.xpertLiveArtifact; live.subscribe(bindingId, renderDataset); await live.ready(); await live.query(bindingId, typedControls); Use an async function, with the exact binding IDs from saved previews.',
                         refresh: 'live.refresh(bindingId) requires a Binding ID. live.refresh() without an ID is invalid. For a page refresh button or timer, call Promise.all(bindingIds.map(id => live.refresh(id))). Each subscription redraws its KPI, chart and details.',
+                        batch: 'await live.queryMany(bindingIds, typedControls) returns {datasets, failures}; it commits successful subscriptions together after the group settles. Use for shared filters and initial multi-source rounds. Display unavailable sources from failures, never retain old values as current.',
                         filters: 'Mark native data selects with data-dashboard-control="<exact controlId>". Mark purely visual selects with data-dashboard-presentation instead. Changing a data select must call live.query for every affected Binding, not only filter cached rows in JS. bindSelect updates one Binding only. Read references/html-lifecycle.md before writing the page.'
                     },
                     usage: { 'trend-workspace': 'window.TrendWorkspace: pale-blue KPI rail and aligned trends. Read themes/trend-workspace/README.md.',
@@ -232,7 +310,7 @@ let DashboardMiddleware = class DashboardMiddleware {
                         three: 'window.THREE: bundled core including WebGLRenderer. Requires WebGL2; catch unavailable GPU contexts and show a clear fallback. External textures/models, loaders/addons, WebGPU and workers are not bundled.' },
                     lifecycle: 'Pass packaged library IDs to dashboard_create_html or dashboard_update. Actual version and bytes are pinned on save; omitted libraries on update preserves saved locks. Online resources must load successfully during preflight and viewing; they are not frozen with the Artifact.' }), { name: 'dashboard_libraries', description: 'Discover packaged libraries, themes, exact versions and the current unrestricted network policy. Tailwind CDN and other online dependencies are supported. Returns metadata, never library source.',
                     schema: v3_1.z.object({}).strict(), verboseParsingErrors: true, metadata: { toolName: { en_US: 'Discover dashboard libraries', zh_Hans: '查看看板前端图库' } } }),
-                ...(0, editing_1.createEditingTools)(this.service, scope, context, resolvePreviews, validateFinal, (path, artifactId) => evidence.opened(path, artifactId), editing.resolve),
+                ...(0, editing_1.createEditingTools)(this.service, scope, context, resolvePreviews, validateFinal, (path, artifactId) => evidence.opened(path, artifactId), editing.resolve, this.saveRequests),
                 (0, tools_1.tool)(async () => {
                     listedSources = await this.service.sources(scope);
                     return JSON.stringify(listedSources);
@@ -251,8 +329,8 @@ let DashboardMiddleware = class DashboardMiddleware {
                     return preview(binding);
                 }, { name: 'dashboard_preview', description: 'Run one read-only binding using parameters[].defaultValue. Automatically discovers the source/provider query contract when absent in this run; use dashboard_discover to inspect business metadata or repair invalid queries. Returns validated Dataset fields, first 20 rows, full query completeness and audit. Required before create; changes to binding/defaults require another preview.',
                     schema: agent_schema_1.previewToolSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Verify dashboard data', zh_Hans: '预览并验证看板数据' } } }),
-                (0, tools_1.tool)(async ({ bindingJson }) => preview(plugin_sdk_1.analyticsBindingSchema.parse(JSON.parse(bindingJson))), {
-                    name: 'dashboard_preview_binding', description: 'Preview a complete canonical AnalyticsBinding returned by another tool. Serialize the complete canonical Binding (for example discovery items[].metadata.binding), including parameters[].controlId. bindingPayload is only the payload, not a Binding. If adding a parameter, include name, controlId, type, required and defaultValue. Do not convert it to the simplified dashboard_preview input. Automatically discovers the source/provider query contract when absent in this run; use dashboard_discover for business metadata. Returns the same previewId receipt for dashboard_create.',
+                (0, tools_1.tool)(async ({ bindingJson }) => preview(plugin_sdk_1.analyticsBindingSchema.parse((0, json_input_1.parseJsonInput)(bindingJson, 'bindingJson'))), {
+                    name: 'dashboard_preview_binding', description: 'Preview a complete canonical AnalyticsBinding returned by another tool. When editing an existing dashboard, copy dashboard_open.bindings[], preserve binding.id and existing parameters[].controlId, and change only the requested query/parameters. Binding ID is independent of output.datasetId. Serialize the complete Binding (also supported: discovery items[].metadata.binding), including parameters[].controlId. bindingPayload is only the payload, not a Binding. If adding a parameter, include name, controlId, type, required and defaultValue. Do not convert it to the simplified dashboard_preview input, which derives binding.id from output.datasetId. Automatically discovers the source/provider query contract when absent in this run. Returns a current-run previewId for dashboard_create or dashboard_update; include every intended changed/new Binding receipt and matching controls in the same save.',
                     schema: v3_1.z.object({ bindingJson: v3_1.z.string().min(2).max(200000) }).strict(), verboseParsingErrors: true,
                     metadata: { toolName: { en_US: 'Verify registered dataset', zh_Hans: '验证已注册数据集' } }
                 }),
@@ -270,7 +348,7 @@ let DashboardMiddleware = class DashboardMiddleware {
                         throw new Error('DASHBOARD_HTML_TOO_LARGE');
                     const html = artifact_document_1.artifactDocumentHtml.parse(new TextDecoder('utf-8', { fatal: true }).decode(file.buffer));
                     const { path, libraries, supersedesPaths, ...definition } = input;
-                    const result = JSON.parse(await save({ ...definition, charts: [], tables: [] }, config, html, await (0, document_libraries_1.libraryLocks)(libraries ?? [])));
+                    const result = JSON.parse(await save({ ...definition, charts: [], tables: [] }, config, html, await (0, document_libraries_1.libraryLocks)(libraries ?? []), { path, sha256: (0, node_crypto_1.createHash)('sha256').update(file.buffer).digest('hex') }));
                     return JSON.stringify({ ...result, sourceFile: { path, sha256: (0, node_crypto_1.createHash)('sha256').update(file.buffer).digest('hex') } });
                 }, { name: 'dashboard_create_html', description: 'Save custom HTML from a Workspace path together with run-local preview receipts and controls in one persistent draft (human publication is separate). Requires real data preview; does not accept query payloads or cached rows.',
                     schema: agent_schema_1.createHtmlToolSchema, verboseParsingErrors: true,
@@ -281,7 +359,8 @@ let DashboardMiddleware = class DashboardMiddleware {
 exports.DashboardMiddleware = DashboardMiddleware;
 exports.DashboardMiddleware = DashboardMiddleware = __decorate([
     (0, plugin_sdk_1.AgentMiddlewareStrategy)('LiveDashboard'),
-    __metadata("design:paramtypes", [dashboard_service_1.DashboardService])
+    __param(1, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [dashboard_service_1.DashboardService, save_requests_1.DashboardSaveRequests])
 ], DashboardMiddleware);
 function previewKey(binding, controls) {
     return hash({ binding, controls: Object.fromEntries(binding.parameters.map((parameter) => [parameter.controlId, Object.hasOwn(controls, parameter.controlId) ? controls[parameter.controlId] : parameter.defaultValue ?? null])) });

package/dist/lib/plugin.js

@@ -7,6 +7,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiveDashboardPlugin = void 0;
+const save_requests_1 = require("./save-requests");
+const archive_service_1 = require("./archive.service");
 const projects_service_1 = require("./projects.service");
 const content_capability_1 = require("./content-capability");
 const monitor_1 = require("./monitor");
@@ -24,5 +26,5 @@ let LiveDashboardPlugin = class LiveDashboardPlugin {
 };
 exports.LiveDashboardPlugin = LiveDashboardPlugin;
 exports.LiveDashboardPlugin = LiveDashboardPlugin = __decorate([
-    (0, plugin_sdk_1.XpertServerPlugin)({ controllers: [provider_options_controller_1.DashboardProviderOptionsController], providers: [projects_service_1.DashboardProjectsService, monitor_1.DashboardMonitor, monitor_1.DashboardMonitorMiddleware, artifact_type_provider_1.DashboardArtifactType, content_capability_1.DashboardCapability, content_provider_1.DashboardContentProvider, content_provider_1.DashboardContentEditor, dashboard_service_1.DashboardService, view_provider_1.DashboardViewProvider, middleware_1.DashboardMiddleware, html_validation_1.HtmlDashboardValidation, presentation_provider_1.DashboardPresentationProvider, sharing_service_1.DashboardSharingService] })
+    (0, plugin_sdk_1.XpertServerPlugin)({ controllers: [provider_options_controller_1.DashboardProviderOptionsController], providers: [save_requests_1.DashboardSaveRequests, archive_service_1.DashboardArchiveService, projects_service_1.DashboardProjectsService, monitor_1.DashboardMonitor, monitor_1.DashboardMonitorMiddleware, artifact_type_provider_1.DashboardArtifactType, content_capability_1.DashboardCapability, content_provider_1.DashboardContentProvider, content_provider_1.DashboardContentEditor, dashboard_service_1.DashboardService, view_provider_1.DashboardViewProvider, middleware_1.DashboardMiddleware, html_validation_1.HtmlDashboardValidation, presentation_provider_1.DashboardPresentationProvider, sharing_service_1.DashboardSharingService] })
 ], LiveDashboardPlugin);

package/dist/lib/presentation.provider.d.ts

@@ -11,15 +11,10 @@ export declare class DashboardPresentationProvider implements IArtifactPresentat
     read(context: ArtifactPresentationContext): Promise<{
         meta: {
             saved: {
-                artifactId: string;
-                versionId: string;
-                versionNumber: number;
-                title: string;
-                isDraft: boolean;
                 manifest: {
-                    schema: "xpert.live-dashboard";
-                    id: string;
                     title: string;
+                    id: string;
+                    schema: "xpert.live-dashboard";
                     bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
                     controls: {
                         type: "string" | "number" | "boolean" | "date";
@@ -30,25 +25,45 @@ export declare class DashboardPresentationProvider implements IArtifactPresentat
                     }[];
                     charts: {
                         type: "bar" | "line" | "area" | "pie" | "scatter";
-                        id: string;
                         title: string;
+                        id: string;
                         datasetId: string;
                         x: string;
                         y: string;
                         color?: string | undefined;
                     }[];
                     tables: {
-                        id: string;
                         title: string;
+                        id: string;
                         datasetId: string;
                         fields: string[];
                     }[];
+                    sourceMetadata?: {
+                        bindingId: string;
+                        title: string;
+                        description?: string | undefined;
+                    }[] | undefined;
+                    components?: {
+                        title: string;
+                        id: string;
+                        elementId: string;
+                        kind: "filter" | "metric" | "chart" | "table" | "text";
+                        sources: {
+                            bindingId: string;
+                            fieldIds?: string[] | undefined;
+                        }[];
+                    }[] | undefined;
                     presentation?: {
                         type: "html";
                         html: string;
                         dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
                     } | undefined;
                 };
+                artifactId: string;
+                versionId: string;
+                versionNumber: number;
+                title: string;
+                isDraft: boolean;
                 dependencies: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyAsset[];
             };
             dashboards: {

package/dist/lib/presentation.provider.js

@@ -22,6 +22,7 @@ const remote_entry_1 = require("./remote-entry");
 const dashboard_schema_1 = require("./dashboard.schema");
 const dashboard_queries_1 = require("./dashboard-queries");
 const renderer_1 = require("./renderer");
+const dashboard_sources_1 = require("./dashboard-sources");
 let DashboardPresentationProvider = class DashboardPresentationProvider {
     constructor(runtime) {
         this.runtime = runtime;
@@ -30,7 +31,7 @@ let DashboardPresentationProvider = class DashboardPresentationProvider {
     getEntry() { return (0, remote_entry_1.dashboardRemoteEntry)(true); }
     async read(context) {
         const saved = this.open(context);
-        return { meta: { saved, dashboards: [{ artifactId: saved.artifactId, versionId: saved.versionId, title: saved.title }], sources: [], versions: [] } };
+        return { meta: { saved: { ...saved, manifest: (0, dashboard_sources_1.publicDashboardManifest)(saved.manifest) }, dashboards: [{ artifactId: saved.artifactId, versionId: saved.versionId, title: saved.title }], sources: [], versions: [] } };
     }
     async query(context, request) {
         const saved = this.open(context);

package/dist/lib/preview-retry.d.ts

@@ -1,7 +1,8 @@
 import type { AgentBuiltInState, ToolCallHandler, ToolCallRequest } from '@xpert-ai/plugin-sdk';
 /** Run-local bounds include tool-schema failures, before any discovery or query executes. */
 export declare function createPreviewRetryGuard(): {
-    readonly exhausted: boolean;
-    readonly summary: string;
-    run(request: ToolCallRequest<AgentBuiltInState>, handler: ToolCallHandler): Promise<import("@langchain/core/messages").ToolMessage | import("@langchain/langgraph").Command<unknown, Record<string, unknown>, string>>;
+    exhausted: boolean;
+    summary: string;
+    run(request: ToolCallRequest<AgentBuiltInState>, handler: ToolCallHandler): import("@xpert-ai/plugin-sdk").PromiseOrValue<import("@langchain/core/messages").ToolMessage | import("@langchain/langgraph").Command<unknown, Record<string, unknown>, string>>;
+    attempt<T>(name: string, args: unknown, handler: () => Promise<T>): Promise<T>;
 };

package/dist/lib/preview-retry.js

@@ -12,13 +12,11 @@ function createPreviewRetryGuard() {
         consecutiveFailures++;
         lastError = message.slice(0, 2000);
     };
-    return {
+    const guard = {
         get exhausted() { return consecutiveFailures >= 6; },
         get summary() { return `DASHBOARD_PREVIEW_RETRY_LIMIT: preview validation repeatedly failed. This run has stopped making tool calls. Report the last error and the required repair; do not claim an unconfirmed save. Last error: ${lastError}`; },
-        async run(request, handler) {
-            if (!PREVIEW_TOOLS.has(request.toolCall.name))
-                return handler(request);
-            const key = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify({ name: request.toolCall.name, args: request.toolCall.args }, (_key, value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value)).digest('hex');
+        async attempt(name, args, handler) {
+            const key = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify({ name, args }, (_key, value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value)).digest('hex');
             if (consecutiveFailures >= 6)
                 throw new Error(this.summary);
             if ((failures.get(key)?.count ?? 0) >= 2) {
@@ -30,8 +28,8 @@ function createPreviewRetryGuard() {
                 throw new Error('DASHBOARD_PREVIEW_IN_PROGRESS: wait for the identical preview already in progress; do not submit duplicates.');
             pending.add(key);
             try {
-                const result = await handler(request);
-                if ('status' in result && result.status === 'error' && 'content' in result) {
+                const result = await handler();
+                if (result && typeof result === 'object' && 'status' in result && result.status === 'error' && 'content' in result) {
                     recordFailure(key, typeof result.content === 'string' ? result.content : 'Preview tool returned an error');
                 }
                 else {
@@ -49,4 +47,12 @@ function createPreviewRetryGuard() {
             }
         }
     };
+    return { ...guard,
+        get exhausted() { return guard.exhausted; },
+        get summary() { return guard.summary; },
+        run(request, handler) {
+            return PREVIEW_TOOLS.has(request.toolCall.name)
+                ? guard.attempt(request.toolCall.name, request.toolCall.args, async () => handler(request)) : handler(request);
+        }
+    };
 }