@xpert-ai/plugin-live-dashboard 0.0.0-stage → 0.1.1

package/dist/lib/html-guidance.d.ts

@@ -0,0 +1 @@
+export declare const HTML_DASHBOARD_GUIDANCE = "For free-layout HTML dashboards, read the installed live-dashboard skill's references/html-runtime.md through read_skill_file, relative to its SKILL.md path in the skill catalog. Create/edit the HTML with SandboxFile; then dashboard_create_html or dashboard_update validates and saves it. Do not use generic present_files to save or preview a live dashboard. Its preview belongs to the Live dashboards Workbench. ECharts/Three.js are available via dashboard_libraries; all data access remains declarative Binding queries through window.xpertLiveArtifact. The page MUST declare const live = window.xpertLiveArtifact in its script (live is not a host global), register live.subscribe(bindingId, render), await live.ready(), and invoke live.query(bindingId, typedControls) for initial data and filter changes. window.__datasets and window.__refresh are not platform APIs and are never populated by the host. Read the runtime reference and its html-lifecycle.md example before writing HTML; preserve that lifecycle while freely changing the layout. Use one complete Dataset for KPI, trend and details when they share the same metric and filters; do not create a redundant unfiltered total Binding. Never let filtered and unfiltered subscriptions both write the same KPI: a refresh would race and overwrite the selected-region total. Distinct global totals need distinct, clearly labeled elements. Native data selects require data-dashboard-control=\"<controlId>\"; purely visual selects use data-dashboard-presentation. A data filter must query, not only filter cached browser rows. bindSelect controls ONE binding only. For a shared dimension filter across multiple bindings, follow the skill custom-select example and query every affected binding with the same typed controls; matching control IDs do not broadcast automatically. bindSelect derives options from Dataset fields and is only for dimension filters. Fixed query enums (days, page size, granularity) need options from parameter.allowedValues and a typed change listener calling live.query; never use date rows as numeric day-count options.";

package/dist/lib/html-guidance.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTML_DASHBOARD_GUIDANCE = void 0;
+exports.HTML_DASHBOARD_GUIDANCE = `For free-layout HTML dashboards, read the installed live-dashboard skill's references/html-runtime.md through read_skill_file, relative to its SKILL.md path in the skill catalog. Create/edit the HTML with SandboxFile; then dashboard_create_html or dashboard_update validates and saves it. Do not use generic present_files to save or preview a live dashboard. Its preview belongs to the Live dashboards Workbench. ECharts/Three.js are available via dashboard_libraries; all data access remains declarative Binding queries through window.xpertLiveArtifact. The page MUST declare const live = window.xpertLiveArtifact in its script (live is not a host global), register live.subscribe(bindingId, render), await live.ready(), and invoke live.query(bindingId, typedControls) for initial data and filter changes. window.__datasets and window.__refresh are not platform APIs and are never populated by the host. Read the runtime reference and its html-lifecycle.md example before writing HTML; preserve that lifecycle while freely changing the layout. Use one complete Dataset for KPI, trend and details when they share the same metric and filters; do not create a redundant unfiltered total Binding. Never let filtered and unfiltered subscriptions both write the same KPI: a refresh would race and overwrite the selected-region total. Distinct global totals need distinct, clearly labeled elements. Native data selects require data-dashboard-control="<controlId>"; purely visual selects use data-dashboard-presentation. A data filter must query, not only filter cached browser rows. bindSelect controls ONE binding only. For a shared dimension filter across multiple bindings, follow the skill custom-select example and query every affected binding with the same typed controls; matching control IDs do not broadcast automatically. bindSelect derives options from Dataset fields and is only for dimension filters. Fixed query enums (days, page size, granularity) need options from parameter.allowedValues and a typed change listener calling live.query; never use date rows as numeric day-count options.`;

package/dist/lib/html-validation.d.ts

@@ -0,0 +1,19 @@
+import type { AnalyticalDataset, XpertResolvedViewHostContext } from '@xpert-ai/contracts';
+import { type ManagedQueueJob, type ManagedQueueJobContext, type ManagedQueueService, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import type { DashboardManifest } from './dashboard.schema';
+import { type ArtifactDocumentDependencyAsset } from '@xpert-ai/plugin-sdk/artifact-document';
+/** Browser execution belongs to the platform's bounded background pool, not the API request. */
+export declare class HtmlDashboardValidation {
+    private readonly runtime;
+    private readonly queue;
+    constructor(runtime: RuntimeCapabilityRegistry, queue: ManagedQueueService);
+    validate(context: XpertResolvedViewHostContext, manifest: DashboardManifest, datasets: AnalyticalDataset[], dependencies?: ArtifactDocumentDependencyAsset[]): Promise<{
+        jobId: `${string}-${string}-${string}-${string}-${string}`;
+        requestedBindings: string[];
+        status: string;
+    } | null>;
+    /** Ownership comes from persisted queue context. This handler needs no HTTP request or conversation. */
+    handle(job: ManagedQueueJob<{
+        validationId: string;
+    }>, context: ManagedQueueJobContext): Promise<void>;
+}

package/dist/lib/html-validation.js

@@ -0,0 +1,136 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.HtmlDashboardValidation = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+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 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();
+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');
+const recordKey = (id) => `live_dashboard:validation:${id}`;
+/** Browser execution belongs to the platform's bounded background pool, not the API request. */
+let HtmlDashboardValidation = class HtmlDashboardValidation {
+    constructor(runtime, queue) {
+        this.runtime = runtime;
+        this.queue = queue;
+    }
+    async validate(context, manifest, datasets, dependencies = []) {
+        if (!manifest.presentation)
+            return null;
+        if (!context.tenantId || !context.organizationId || !context.userId)
+            throw new common_1.BadRequestException('DASHBOARD_ACCESS_DENIED');
+        const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability), jobs = this.runtime.require(plugin_sdk_1.SandboxJobsRuntimeCapability);
+        const [health, pool] = await Promise.all([jobs.getActionHealth({ pluginName: PLUGIN, action: ACTION, actionVersion: '1.0.0' }),
+            this.queue.getExecutionPoolHealth({ executionPool: POOL })]);
+        if (!health.available || !pool.available)
+            throw new common_1.BadRequestException(`DASHBOARD_HTML_VALIDATION_UNAVAILABLE: ${health.reason ?? pool.warning ?? 'Browser Runtime unavailable'}`);
+        const jobId = (0, node_crypto_1.randomUUID)(), scope = { tenantId: context.tenantId, userId: context.userId, catalog: 'users' };
+        const buffer = Buffer.from(JSON.stringify({ html: manifest.presentation.html,
+            dependencies: (0, artifact_document_1.verifyArtifactDocumentDependencies)(dependencies, manifest.presentation.dependencies ?? []),
+            context: { bindingIds: manifest.bindings.map(binding => binding.id), defaults: Object.fromEntries(manifest.controls.filter(control => control.defaultValue !== undefined).map(control => [control.controlId, control.defaultValue ?? null])), theme: 'light', locale: 'en' },
+            parameters: Object.fromEntries(manifest.bindings.map(binding => [binding.id, binding.parameters])),
+            datasets: Object.fromEntries(manifest.bindings.map(binding => [binding.id, datasets.find(dataset => dataset.datasetId === binding.output.datasetId)])) }));
+        const stored = await files.uploadBuffer({ ...scope, buffer, originalName: 'document.json', fileName: 'document.json', folder: `live-dashboard-validation/${jobId}`, mimeType: 'application/json' });
+        const reference = { source: 'platform.workspace.files', ...scope, filePath: stored.filePath, workspacePath: stored.workspacePath };
+        const redis = await this.queue.getRedis(), key = recordKey(jobId), deadline = Date.now() + 90000;
+        const record = { tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId, manifestId: manifest.id,
+            deadline, filePath: stored.filePath, workspacePath: stored.workspacePath, size: buffer.length, sha256: digest(buffer) };
+        let finished = false;
+        try {
+            // Transient plugin-owned task record; queue payloads contain only its identity, never HTML or rows.
+            await redis.set(key, JSON.stringify(record), 'EX', 300);
+            const queued = await this.queue.enqueue({ pluginName: PLUGIN, queueName: 'html-validation', jobName: 'validate', payload: { validationId: jobId },
+                tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId, scopeKey: 'system:global', jobId,
+                attempts: 1, executionPool: POOL, removeOnComplete: { age: 3600, count: 100 }, removeOnFail: { age: 86400, count: 100 } });
+            while (Date.now() < deadline) {
+                const state = await this.queue.getJob({ jobId: queued.jobId, executionPool: POOL });
+                if (state?.state === 'failed') {
+                    finished = true;
+                    throw new common_1.BadRequestException(`DASHBOARD_HTML_VALIDATION_FAILED: ${state.failedReason?.slice(0, 500) ?? 'Browser Job failed'}`);
+                }
+                if (state?.state === 'completed') {
+                    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.`);
+                    return { jobId, requestedBindings: report.requestedBindings, status: 'passed' };
+                }
+                await (0, promises_1.setTimeout)(250);
+            }
+            throw new common_1.BadRequestException('DASHBOARD_HTML_VALIDATION_TIMEOUT');
+        }
+        finally {
+            if (!finished) {
+                await Promise.allSettled([this.queue.cancel({ jobId, executionPool: POOL }), jobs.cancel({ jobId })]);
+            }
+            await removeTemporary(() => files.deleteFile(reference));
+            await redis.del(key, `${key}:report`);
+        }
+    }
+    /** Ownership comes from persisted queue context. This handler needs no HTTP request or conversation. */
+    async handle(job, context) {
+        const jobId = v3_1.z.string().uuid().parse(job.data.validationId), key = recordKey(jobId), redis = await this.queue.getRedis();
+        const record = recordSchema.parse(JSON.parse(await redis.get(key) ?? 'null'));
+        if (record.deadline <= Date.now() || record.tenantId !== context.tenantId || record.organizationId !== context.organizationId || record.userId !== context.userId)
+            throw new Error('DASHBOARD_HTML_VALIDATION_EXPIRED_OR_DENIED');
+        const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability), jobs = this.runtime.require(plugin_sdk_1.SandboxJobsRuntimeCapability);
+        const scope = { tenantId: record.tenantId, userId: record.userId, catalog: 'users' };
+        const reference = { source: 'platform.workspace.files', ...scope, filePath: record.filePath, workspacePath: record.workspacePath };
+        try {
+            const result = await jobs.run({ jobId, action: ACTION, actionVersion: '1.0.0', idempotencyKey: `live_dashboard/${jobId}`,
+                scope: { tenantId: record.tenantId, organizationId: record.organizationId, userId: record.userId, pluginName: PLUGIN, businessResourceType: 'html-validation', businessResourceId: record.manifestId },
+                payload: {}, files: [{ reference, targetPath: 'document.json', size: record.size, sha256: record.sha256 }], timeoutMs: Math.min(60000, record.deadline - Date.now()),
+                outputs: [{ path: 'report.json', originalName: 'report.json', mimeType: 'application/json', destination: { ...scope, folder: `live-dashboard-validation/${jobId}` } }] });
+            const output = result.outputs.find(output => output.path === 'report.json');
+            if (!output)
+                throw new Error('DASHBOARD_HTML_VALIDATION_UNAVAILABLE');
+            try {
+                const bytes = (await files.readBuffer(output.reference)).buffer;
+                if (bytes.length > 16000 || digest(bytes) !== output.sha256)
+                    throw new Error('DASHBOARD_HTML_VALIDATION_INVALID');
+                await redis.set(`${key}:report`, JSON.stringify(reportSchema.parse(JSON.parse(bytes.toString('utf8')))), 'EX', 300);
+            }
+            finally {
+                await removeTemporary(() => files.deleteFile(output.reference));
+            }
+        }
+        finally {
+            await removeTemporary(() => files.deleteFile(reference));
+        }
+    }
+};
+exports.HtmlDashboardValidation = HtmlDashboardValidation;
+exports.HtmlDashboardValidation = HtmlDashboardValidation = __decorate([
+    (0, common_1.Injectable)(),
+    (0, plugin_sdk_1.PluginJobProcessor)({ pluginName: PLUGIN, queueName: 'html-validation', jobName: 'validate', concurrency: 1 }),
+    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __param(1, (0, common_1.Inject)(plugin_sdk_1.MANAGED_QUEUE_SERVICE_TOKEN)),
+    __metadata("design:paramtypes", [Object, Object])
+], HtmlDashboardValidation);
+async function removeTemporary(remove) {
+    try {
+        await remove();
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+}

package/dist/lib/middleware.d.ts

@@ -0,0 +1,10 @@
+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;
+    readonly meta: TAgentMiddlewareMeta;
+    constructor(service: DashboardService);
+    createMiddleware(_options: object, context: IAgentMiddlewareContext): AgentMiddleware;
+}

package/dist/lib/middleware.js

@@ -0,0 +1,225 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DashboardMiddleware = exports.DASHBOARD_GUIDANCE = void 0;
+const messages_1 = require("@langchain/core/messages");
+const tools_1 = require("@langchain/core/tools");
+const node_crypto_1 = require("node:crypto");
+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 document_libraries_1 = require("./document-libraries");
+const agent_schema_1 = require("./agent.schema");
+const html_guidance_1 = require("./html-guidance");
+const dashboard_service_1 = require("./dashboard.service");
+const dashboard_schema_1 = require("./dashboard.schema");
+const view_provider_1 = require("./view.provider");
+const editing_1 = require("./editing");
+const dashboard_receipt_1 = require("./dashboard-receipt");
+const filter_evidence_1 = require("./filter-evidence");
+const save_evidence_1 = require("./save-evidence");
+const resource_card_1 = require("./resource-card");
+const dashboard_icon_1 = require("./dashboard-icon");
+const middlewareOptionsSchema = v3_1.z.object({ allowedFinalProviders: v3_1.z.array(v3_1.z.string().min(1)).min(1).max(20).optional() }).strict();
+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) {
+        this.service = service;
+        this.meta = {
+            name: 'LiveDashboard', label: { en_US: 'Live dashboards', zh_Hans: '实时看板' },
+            description: { en_US: 'Discover, preview, create and update governed live dashboards.', zh_Hans: '发现业务数据、验证查询并持续修改实时看板。' },
+            // Tools inherit this self-contained icon through the platform middleware metadata.
+            icon: dashboard_icon_1.dashboardIcon, features: [view_provider_1.FEATURE], configSchema: { type: 'object', properties: {
+                    allowedFinalProviders: { type: 'array', items: { type: 'string' }, title: { en_US: 'Allowed final dashboard providers', zh_Hans: '最终看板允许的 Provider' },
+                        description: { en_US: 'Optional provider IDs required for saved Agent dashboards. Upstream previews remain available.', zh_Hans: '可选的最终看板 Provider ID 列表，不限制上游来源预览。' } }
+                }, additionalProperties: false }
+        };
+    }
+    createMiddleware(_options, context) {
+        const options = middlewareOptionsSchema.parse(_options);
+        if (!context.xpertId)
+            throw new Error('DASHBOARD_ASSISTANT_REQUIRED');
+        const scope = {
+            tenantId: context.tenantId ?? plugin_sdk_1.RequestContext.currentTenantId(), organizationId: context.organizationId ?? plugin_sdk_1.RequestContext.getOrganizationId(),
+            userId: context.userId ?? plugin_sdk_1.RequestContext.currentUserId(), hostType: context.projectId ? 'project' : 'agent', hostId: context.projectId ?? context.xpertId, slots: []
+        };
+        // Evidence belongs to this run and actor, never a process-wide cache of business data.
+        const discovered = new Map(), previews = new Map();
+        let listedSources;
+        const filterEvidence = (0, filter_evidence_1.createFilterEvidence)(this.service, scope, previews);
+        const created = new Map();
+        const preview = async (binding) => {
+            const contract = discovered.get(`${binding.dataSourceId}/${binding.providerId}`);
+            if (!contract)
+                throw new Error('DASHBOARD_DISCOVER_REQUIRED');
+            (0, plugin_sdk_1.validateAnalyticsPayload)(binding.payload, contract.payloadSchema);
+            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))
+                throw new Error('DASHBOARD_PREVIEW_LIMIT');
+            previews.set(previewId, binding);
+            const rows = dataset.rows.slice(0, 20);
+            while (Buffer.byteLength(JSON.stringify(rows)) > 32000)
+                rows.pop();
+            return JSON.stringify({ ...dataset, previewId, bindingJson: JSON.stringify(binding), rows, validation: filterEvidence.requirements(binding, previewId, rows), preview: { displayedRows: rows.length,
+                    omittedRows: dataset.rows.length - rows.length, note: 'Display sample only; completeness describes the full bounded query. Verify business semantics before create.' } });
+        };
+        const resolvePreviews = (previewIds) => previewIds.map(id => {
+            const binding = previews.get(id);
+            if (!binding)
+                throw new Error('DASHBOARD_PREVIEW_REQUIRED: use a previewId returned in this run');
+            return binding;
+        });
+        const validateFinal = (manifest, requirePreviews) => {
+            const allowedProviders = options.allowedFinalProviders;
+            if (allowedProviders && manifest.bindings.some(binding => !allowedProviders.includes(binding.providerId)))
+                throw new Error(`DASHBOARD_PROVIDER_REQUIRED: final bindings must use ${allowedProviders.join(', ')}`);
+            if (requirePreviews) {
+                const controls = Object.fromEntries(manifest.controls.filter(item => item.defaultValue !== undefined).map(item => [item.controlId, item.defaultValue ?? null]));
+                for (const binding of manifest.bindings) {
+                    const previewId = previewKey(binding, controls);
+                    if (!previews.has(previewId))
+                        throw new Error('DASHBOARD_PREVIEW_REQUIRED: preview the exact binding and default controls before saving');
+                    filterEvidence.assert(binding, previewId);
+                }
+            }
+        };
+        const save = async (input, config, html, dependencies = []) => {
+            const { previewIds, supersedesPaths, ...definition } = input;
+            const bindings = resolvePreviews(previewIds);
+            const manifest = dashboard_schema_1.dashboardSchema.parse({ ...definition, bindings, schema: 'xpert.live-dashboard/v1', id: (0, node_crypto_1.randomUUID)(),
+                ...(html ? { presentation: { type: 'html', html, ...(dependencies.length ? { dependencies } : {}) } } : {}) });
+            validateFinal(manifest, true);
+            const key = hash({ input: { ...definition, previewIds }, html, dependencies });
+            const previous = created.get(key);
+            if (previous) {
+                const receipt = await this.service.save(scope, previous.manifest, previous.receipt.baseVersionId, previous.receipt.draftRevision);
+                created.set(key, { manifest: previous.manifest, receipt });
+                const resourceCard = await (0, resource_card_1.emitDashboardCard)(scope, { ...receipt, state: 'draft', revision: receipt.draftRevision }, config);
+                return JSON.stringify({ dashboard: receipt, resourceCard });
+            }
+            const sameTitle = [...created.values()].find(item => item.manifest.title === manifest.title);
+            if (sameTitle)
+                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.`);
+            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);
+            return JSON.stringify({ dashboard: result, resourceCard });
+        };
+        const evidence = (0, save_evidence_1.dashboardSaveEvidence)(() => {
+            const files = context.runtime?.capabilities?.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
+            if (!files)
+                throw new Error('DASHBOARD_WORKSPACE_REQUIRED');
+            return files;
+        });
+        let modelCalls = 0;
+        return { name: 'LiveDashboard', contextSchema: editing_1.dashboardContextSchema,
+            wrapToolCall: async (request, handler) => {
+                const name = request.toolCall.name;
+                const args = request.toolCall.args;
+                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 result = path && (evidence.has(path) || previews.size > 0 && agent_schema_1.htmlPathSchema.safeParse(path).success)
+                    ? await evidence.trackWrite(path, async () => handler(request)) : await handler(request);
+                if (save && 'content' in result && (!('status' in result) || result.status !== 'error'))
+                    await evidence.accept(save, result.content);
+                return result;
+            }, wrapModelCall: async (request, handler) => {
+                const exhausted = ++modelCalls > 24;
+                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: [
+                            ...(typeof request.systemMessage?.content === 'string' ? [{ type: 'text', text: request.systemMessage.content }] : request.systemMessage?.content ?? []),
+                            { type: 'text', text: exports.DASHBOARD_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.' : '') }
+                        ] }) });
+                if (evidence.pending && result && !result.tool_calls?.length)
+                    throw new Error('DASHBOARD_SAVE_NOT_CONFIRMED: the model stopped without a successful draft save receipt.');
+                return result;
+            }, tools: [
+                filterEvidence.tool,
+                (0, tools_1.tool)(async () => JSON.stringify({ libraries: await (0, document_libraries_1.libraryLocks)(['echarts', 'three']),
+                    pageRuntime: {
+                        global: 'window.xpertLiveArtifact',
+                        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.',
+                        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: { echarts: 'window.echarts: init(element, null, {renderer:"svg"}) then setOption(completeOption, {notMerge:true}). Canvas is also available. Derive active series/legend dimensions from each received Dataset, including filtered results; never retain excluded groups as zero-valued series. Aggregate repeated categories using all grain dimensions, clear empty results, and redraw KPI, chart and details together in subscribe. Use ResizeObserver to resize and reuse the instance on filter/refresh.',
+                        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 libraries IDs to dashboard_create_html or dashboard_update. Actual version and bytes are pinned on save; omitted libraries on update preserves saved locks. No CDN, imports or network access.' }), { name: 'dashboard_libraries', description: 'Discover packaged frontend libraries and exact versions available to HTML dashboards. Read before using ECharts/Three.js. 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)),
+                (0, tools_1.tool)(async () => {
+                    listedSources = await this.service.sources(scope);
+                    return JSON.stringify(listedSources);
+                }, {
+                    name: 'dashboard_list_sources', description: 'List authorized analytics sources and versioned providers. Start here; IDs must come from this list.',
+                    schema: v3_1.z.object({}).strict(), verboseParsingErrors: true, metadata: { toolName: { en_US: 'List analytics sources', zh_Hans: '发现分析数据源' } }
+                }),
+                (0, tools_1.tool)(async (input) => {
+                    if (listedSources && !listedSources.some(source => source.id === input.dataSourceId && source.providers.some(provider => provider.id === input.providerId)))
+                        throw new Error(`DASHBOARD_SOURCE_SELECTION_INVALID: copy an exact dataSourceId/providerId pair from dashboard_list_sources; do not invent or combine IDs. Known pairs: ${JSON.stringify(listedSources.map(source => ({ dataSourceId: source.id, name: source.name, providerIds: source.providers.map(provider => provider.id) })))}. Refresh the list if the source changed. Initial requestJson is "{}"; then follow inspectRequest/nextRequest.`);
+                    const parsed = { dataSourceId: input.dataSourceId, providerId: input.providerId, request: (0, agent_schema_1.parseObjectJson)(input.requestJson) };
+                    const result = await this.service.discover(scope, parsed);
+                    discovered.set(`${parsed.dataSourceId}/${parsed.providerId}`, result.queryContract);
+                    return JSON.stringify(result);
+                }, { name: 'dashboard_discover', description: 'Discover provider-owned business metadata. Start requestJson="{}" then serialize inspectRequest/nextRequest. Inspect dataset fields, comments, measures and native query format before preview.',
+                    schema: agent_schema_1.discoverToolSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Inspect business data', zh_Hans: '理解业务数据与指标' } } }),
+                (0, tools_1.tool)(async (input) => {
+                    const contract = discovered.get(`${input.binding.dataSourceId}/${input.binding.providerId}`);
+                    if (!contract)
+                        throw new Error('DASHBOARD_DISCOVER_REQUIRED: discover the source before preview');
+                    const binding = (0, agent_schema_1.fromAgentBinding)(input.binding, contract);
+                    return preview(binding);
+                }, { name: 'dashboard_preview', description: 'Run one read-only binding using parameters[].defaultValue. 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. Discovery of the source is still required. Returns the same previewId receipt for dashboard_create.',
+                    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: '验证已注册数据集' } }
+                }),
+                (0, tools_1.tool)(async (input, config) => save(input, config), { name: 'dashboard_create', description: 'Save a standard chart/table dashboard from previewId receipts. For custom HTML use dashboard_create_html. Fields and defaults must match previewed parameters. Returns a saved Artifact receipt after current access/data revalidation.',
+                    schema: agent_schema_1.createToolSchema, verboseParsingErrors: true,
+                    metadata: { toolName: { en_US: 'Save live dashboard', zh_Hans: '生成并保存实时看板' } } }),
+                (0, tools_1.tool)(async (input, config) => {
+                    if (input.supersedesPaths?.includes(input.path))
+                        throw new Error('DASHBOARD_SUPERSEDE_INVALID: the saved path cannot supersede itself');
+                    const files = context.runtime?.capabilities?.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
+                    if (!files)
+                        throw new Error('DASHBOARD_WORKSPACE_REQUIRED');
+                    const file = await files.readRuntimeBuffer(input.path);
+                    if (file.buffer.byteLength > 300000)
+                        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 ?? [])));
+                    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,
+                    metadata: { toolName: { en_US: 'Save HTML dashboard', zh_Hans: '保存自由样式看板' } } })
+            ] };
+    }
+};
+exports.DashboardMiddleware = DashboardMiddleware;
+exports.DashboardMiddleware = DashboardMiddleware = __decorate([
+    (0, plugin_sdk_1.AgentMiddlewareStrategy)('LiveDashboard'),
+    __metadata("design:paramtypes", [dashboard_service_1.DashboardService])
+], 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])) });
+}
+function hash(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item)).digest('hex');
+}

package/dist/lib/plugin.d.ts

@@ -0,0 +1,2 @@
+export declare class LiveDashboardPlugin {
+}

package/dist/lib/plugin.js

@@ -0,0 +1,22 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveDashboardPlugin = void 0;
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const dashboard_service_1 = require("./dashboard.service");
+const view_provider_1 = require("./view.provider");
+const middleware_1 = require("./middleware");
+const html_validation_1 = require("./html-validation");
+const presentation_provider_1 = require("./presentation.provider");
+const sharing_service_1 = require("./sharing.service");
+let LiveDashboardPlugin = class LiveDashboardPlugin {
+};
+exports.LiveDashboardPlugin = LiveDashboardPlugin;
+exports.LiveDashboardPlugin = LiveDashboardPlugin = __decorate([
+    (0, plugin_sdk_1.XpertServerPlugin)({ providers: [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

@@ -0,0 +1,122 @@
+import type { ArtifactPresentationQuery } from '@xpert-ai/contracts';
+import { type ArtifactPresentationContext, type IArtifactPresentationProvider, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+export declare class DashboardPresentationProvider implements IArtifactPresentationProvider {
+    private readonly runtime;
+    readonly operations: readonly ["query", "query-binding"];
+    constructor(runtime: RuntimeCapabilityRegistry);
+    getEntry(): Promise<{
+        html: string;
+        contentType: "text/html; charset=utf-8";
+    }>;
+    read(context: ArtifactPresentationContext): Promise<{
+        meta: {
+            saved: {
+                artifactId: string;
+                versionId: string;
+                versionNumber: number;
+                title: string;
+                isDraft: boolean;
+                manifest: {
+                    schema: "xpert.live-dashboard/v1";
+                    id: string;
+                    title: string;
+                    bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+                    controls: {
+                        type: "string" | "number" | "boolean" | "date";
+                        controlId: string;
+                        label: string;
+                        defaultValue?: string | number | boolean | null | undefined;
+                        allowedValues?: (string | number | boolean | null)[] | undefined;
+                    }[];
+                    charts: {
+                        type: "bar" | "line" | "area" | "pie" | "scatter";
+                        id: string;
+                        title: string;
+                        datasetId: string;
+                        x: string;
+                        y: string;
+                        color?: string | undefined;
+                    }[];
+                    tables: {
+                        id: string;
+                        title: string;
+                        datasetId: string;
+                        fields: string[];
+                    }[];
+                    presentation?: {
+                        type: "html";
+                        html: string;
+                        dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+                    } | undefined;
+                };
+                dependencies: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyAsset[];
+            };
+            dashboards: {
+                artifactId: string;
+                versionId: string;
+                title: string;
+            }[];
+            sources: never[];
+            versions: never[];
+        };
+    }>;
+    query(context: ArtifactPresentationContext, request: ArtifactPresentationQuery): Promise<import("@xpert-ai/contracts").AnalyticalDataset | {
+        payload?: {
+            ok: boolean;
+            widget_type: string;
+            surface: string;
+            sources: never[];
+            manifest: {
+                version: number;
+                surface: string;
+                title: string;
+                cards: never[];
+                filters: never[];
+                sources: never[];
+                charts: {
+                    id: string;
+                    title: string;
+                    type: "bar" | "line" | "area" | "pie" | "scatter";
+                    dataset: string;
+                    encodings: {
+                        color?: {
+                            field: string;
+                        } | undefined;
+                        x: {
+                            field: string;
+                        };
+                        y: {
+                            field: string;
+                        };
+                    };
+                }[];
+                tables: {
+                    id: string;
+                    title: string;
+                    dataset: string;
+                    columns: {
+                        field: string;
+                        label: string;
+                    }[];
+                }[];
+                blocks: ({
+                    id: string;
+                    type: string;
+                    chartId: string;
+                } | {
+                    id: string;
+                    type: string;
+                    tableId: string;
+                })[];
+            };
+            snapshot: {
+                version: number;
+                generatedAt: string;
+                status: string;
+                datasets: any;
+            };
+        } | undefined;
+        datasets: import("@xpert-ai/contracts").AnalyticalDataset[];
+    }>;
+    private open;
+}