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

package/dist/lib/middleware.js

@@ -10,9 +10,11 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DashboardMiddleware = exports.DASHBOARD_GUIDANCE = void 0;
+const runtime_context_1 = require("./runtime-context");
 const definition_tools_1 = require("./definition-tools");
 const analytics_source_1 = require("./analytics-source");
 const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
+const langgraph_1 = require("@langchain/langgraph");
 const messages_1 = require("@langchain/core/messages");
 const tools_1 = require("@langchain/core/tools");
 const node_crypto_1 = require("node:crypto");
@@ -27,6 +29,7 @@ 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 editing_session_1 = require("./editing-session");
 const dashboard_receipt_1 = require("./dashboard-receipt");
 const filter_evidence_1 = require("./filter-evidence");
 const save_evidence_1 = require("./save-evidence");
@@ -34,7 +37,8 @@ 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 middlewareOptionsSchema = v3_1.z.object({ allowedFinalProviders: v3_1.z.array(v3_1.z.string().min(1)).min(1).max(20).optional() }).strict().default({});
+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 = {
     type: 'string',
     'x-ui': { component: 'remoteSelect', selectUrl: '/api/live-dashboard/provider-options' }
@@ -49,6 +53,9 @@ let DashboardMiddleware = class DashboardMiddleware {
             slashCommands: prompt_workflows_1.dashboardPromptWorkflows,
             // 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: {
+                    maxModelCalls: { type: 'integer', minimum: 1, maximum: 64, default: 24,
+                        title: { en_US: 'Model call limit', zh_Hans: '模型调用上限' },
+                        description: { en_US: 'Bounded per-run budget, including recipe reads and source setup. Save validation remains required.', zh_Hans: '每次执行的调用预算，包含配方读取和数据源准备；保存校验仍然必须通过。' } },
                     allowedFinalProviders: { type: 'array', minItems: 1, maxItems: 20, items: providerOptionSchema, title: { en_US: 'Allowed final dashboard providers', zh_Hans: '最终看板允许的数据源类型' },
                         description: { en_US: 'Choose at least one provider from sources you can access when setting this policy. Existing unavailable IDs are retained. Upstream previews remain available.', zh_Hans: '配置此限制时至少选择一种当前可访问数据源的 Provider；暂不可用的已有值会保留，不影响上游来源预览。' } }
                 }, additionalProperties: false }
@@ -58,10 +65,8 @@ let DashboardMiddleware = class DashboardMiddleware {
         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: []
-        };
+        const scope = (0, runtime_context_1.dashboardRuntimeContext)(context);
+        const editing = (0, editing_session_1.editingSession)({ ...context, tenantId: scope.tenantId, organizationId: scope.organizationId, userId: scope.userId });
         // Evidence belongs to this run and actor, never a process-wide cache of business data.
         const discovered = new Map(), previews = new Map();
         const discovering = new Map();
@@ -114,13 +119,13 @@ let DashboardMiddleware = class DashboardMiddleware {
                 throw new Error('DASHBOARD_PREVIEW_REQUIRED: use a previewId returned in this run');
             return binding;
         });
-        const validateFinal = (manifest, requirePreviews) => {
+        const validateFinal = (manifest, requirePreviews, changedBindingIds) => {
             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) {
+                for (const binding of manifest.bindings.filter(binding => !changedBindingIds || changedBindingIds.includes(binding.id))) {
                     const previewId = previewKey(binding, controls);
                     if (!previews.has(previewId))
                         throw new Error('DASHBOARD_PREVIEW_REQUIRED: preview the exact binding and default controls before saving');
@@ -129,13 +134,16 @@ let DashboardMiddleware = class DashboardMiddleware {
             }
         };
         const save = async (input, config, html, dependencies = []) => {
-            const { previewIds, supersedesPaths, ...definition } = input;
+            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)(),
                 ...(html ? { presentation: { type: 'html', html, ...(dependencies.length ? { dependencies } : {}) } } : {}) });
             validateFinal(manifest, true);
             const key = hash({ input: { ...definition, previewIds }, html, dependencies });
             const previous = created.get(key);
+            const active = editing.resolve(config);
+            if (active && !creationIntent && (!previous || previous.receipt.artifactId !== active.artifactId))
+                throw new Error('DASHBOARD_EDIT_TARGET_ACTIVE: use dashboard_open/update for the active dashboard. Creating a new Artifact requires an explicit user request and creationIntent=new or copy.');
             if (previous) {
                 const receipt = await this.service.save(scope, previous.manifest, previous.receipt.baseVersionId, previous.receipt.draftRevision);
                 created.set(key, { manifest: previous.manifest, receipt });
@@ -143,7 +151,7 @@ let DashboardMiddleware = class DashboardMiddleware {
                 return JSON.stringify({ dashboard: receipt, resourceCard });
             }
             const sameTitle = [...created.values()].find(item => item.manifest.title === manifest.title);
-            if (sameTitle)
+            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.`);
             const result = await this.service.save(scope, manifest, null);
             created.set(key, { manifest, receipt: result });
@@ -158,7 +166,9 @@ let DashboardMiddleware = class DashboardMiddleware {
         });
         const previewRetries = (0, preview_retry_1.createPreviewRetryGuard)();
         let modelCalls = 0;
-        return { name: 'LiveDashboard', contextSchema: editing_1.dashboardContextSchema,
+        return { name: 'LiveDashboard', contextSchema: editing_1.dashboardContextSchema, stateSchema: editing_session_1.dashboardStateSchema,
+            // Platform execution scope and request context occupy different runtime fields.
+            beforeAgent: (state, runtime) => editing.restore(state, { live_dashboard: (0, editing_session_1.selectionFromConfig)(runtime) }),
             wrapToolCall: async (request, handler) => {
                 const name = request.toolCall.name;
                 const args = request.toolCall.args;
@@ -170,6 +180,16 @@ let DashboardMiddleware = class DashboardMiddleware {
                     ? await evidence.trackWrite(path, async () => handler(request)) : await previewRetries.run(request, handler);
                 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')) {
+                    const receipt = (0, dashboard_receipt_1.createdDashboard)(result.content);
+                    if (receipt)
+                        return new langgraph_1.Command({ update: { messages: [result], ...editing.select({ schemaVersion: 1, artifactId: receipt.artifactId, draftRevision: receipt.draftRevision }) } });
+                    if (name === 'dashboard_open' && typeof result.content === 'string') {
+                        const opened = v3_1.z.object({ artifactId: v3_1.z.string().uuid(), readVersionId: v3_1.z.string().uuid().optional(), expectedRevision: v3_1.z.number() }).safeParse(JSON.parse(result.content));
+                        if (opened.success && !opened.data.readVersionId)
+                            return new langgraph_1.Command({ update: { messages: [result], ...editing.select({ schemaVersion: 1, artifactId: opened.data.artifactId, ...(opened.data.expectedRevision > 0 ? { draftRevision: opened.data.expectedRevision } : {}) }) } });
+                    }
+                }
                 return result;
             }, wrapModelCall: async (request, handler) => {
                 if (previewRetries.exhausted) {
@@ -181,12 +201,12 @@ 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 > 24;
+                const exhausted = ++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: [
                             ...(typeof request.systemMessage?.content === 'string' ? [{ type: 'text', text: request.systemMessage.content }] : request.systemMessage?.content ?? []),
-                            { type: 'text', text: exports.DASHBOARD_GUIDANCE + '\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: 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.' : '') }
                         ] }) });
                 if (evidence.pending && result && !result.tool_calls?.length)
                     throw new Error('DASHBOARD_SAVE_NOT_CONFIRMED: the model stopped without a successful draft save receipt.');
@@ -194,9 +214,9 @@ let DashboardMiddleware = class DashboardMiddleware {
             }, tools: [
                 filterEvidence.tool,
                 ...(0, definition_tools_1.createDefinitionTools)(context, () => { listedSources = undefined; }),
-                (0, tools_1.tool)(async () => JSON.stringify({ libraries: await (0, document_libraries_1.libraryLocks)(['echarts', 'three']),
-                    online: { ...document_network_1.DASHBOARD_NETWORK_POLICY,
-                        usage: 'HTML may load scripts, stylesheets and fonts directly from these exact HTTPS origins. Use script src and link rel="stylesheet"; pin exact versions where available. Tailwind CDN https://cdn.tailwindcss.com is supported. Online resources require connectivity when saving and viewing; loading failures fail preflight. Keep all business data queries on window.xpertLiveArtifact; fetch/XHR, external images, workers, iframes and eval remain unavailable. Online resources do not belong in the packaged libraries array.' },
+                (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,
+                        usage: 'Network access is temporarily unrestricted for functional acceptance: CDN scripts/styles/fonts, external images, CSS imports and fetch/XHR are available, subject to browser CORS and mixed-content rules. Tailwind CDN is supported. Use exact versions when possible. Business data from platform sources must still use window.xpertLiveArtifact and saved Bindings; never embed credentials.' },
                     pageRuntime: {
                         global: 'window.xpertLiveArtifact',
                         bindingIds: [...new Set([...previews.values()].map(binding => binding.id))],
@@ -204,11 +224,15 @@ let DashboardMiddleware = class DashboardMiddleware {
                         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.',
+                    usage: { 'trend-workspace': 'window.TrendWorkspace: pale-blue KPI rail and aligned trends. Read themes/trend-workspace/README.md.',
+                        'profit-atlas': 'window.ProfitAtlas: dark profitability workbench, horizontal KPIs, scatter-first analysis and signed rankings. Read themes/profit-atlas/README.md.',
+                        'customer-brief': 'window.CustomerBrief: warm editorial customer brief, serif hierarchy, grouped return metrics and segment comparisons. Read themes/customer-brief/README.md.',
+                        themes: 'Select exactly one theme with echarts. Each provides enhanceSelect(nativeSelect) and charts.line/horizontal/scatter with isolated CSS and pinned bytes. Read themes/README.md; preserve an existing dashboard theme unless the user requests a change.',
+                        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 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 are listed separately under online, are not pinned in the Artifact, and must load successfully when saving and viewing.' }), { name: 'dashboard_libraries', description: 'Discover packaged frontend libraries, exact versions and allowed HTTPS origins for online scripts, stylesheets and fonts. Read before using Tailwind CDN or ECharts/Three.js. Returns metadata, never library source.',
+                    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)),
+                ...(0, editing_1.createEditingTools)(this.service, scope, context, resolvePreviews, validateFinal, (path, artifactId) => evidence.opened(path, artifactId), editing.resolve),
                 (0, tools_1.tool)(async () => {
                     listedSources = await this.service.sources(scope);
                     return JSON.stringify(listedSources);

package/dist/lib/monitor.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod/v3';
+import { type AgentMiddleware, type IAgentMiddlewareStrategy, type IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
+import type { TAgentMiddlewareMeta, XpertResolvedViewHostContext } from '@xpert-ai/contracts';
+import { DashboardService } from './dashboard.service';
+declare const freshnessRuleSchema: z.ZodObject<{
+    bindingId: z.ZodString;
+    fieldId: z.ZodString;
+    maxAgeSeconds: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    bindingId: string;
+    fieldId: string;
+    maxAgeSeconds: number;
+}, {
+    bindingId: string;
+    fieldId: string;
+    maxAgeSeconds: number;
+}>;
+type FreshnessRule = z.infer<typeof freshnessRuleSchema>;
+export declare class DashboardMonitor {
+    private readonly dashboards;
+    constructor(dashboards: DashboardService);
+    inspect(context: XpertResolvedViewHostContext, artifactId: string, freshnessRule?: FreshnessRule): Promise<{
+        artifactId: string;
+        versionId: string;
+        title: string;
+        status: "attention" | "healthy";
+        checkedAt: string;
+        failures: {
+            bindingId: string;
+            datasetId: string;
+            reason: "unavailable";
+        }[];
+        datasets: {
+            datasetId: string;
+            queryFetchedAt: string;
+            truncated: boolean;
+            returnedRows: number;
+        }[];
+        businessFreshness: {
+            status: "unknown" | "stale" | "fresh";
+            latestTimestamp: string | null;
+            coverage: "latest_returned_timestamp";
+            bindingId: string;
+            fieldId: string;
+            maxAgeSeconds: number;
+        } | "not_asserted";
+        availableFreshnessFields: {
+            bindingId: string;
+            fieldId: string;
+            label: string;
+        }[];
+    }>;
+}
+export declare class DashboardMonitorMiddleware implements IAgentMiddlewareStrategy {
+    private readonly monitor;
+    private readonly dashboards;
+    readonly meta: TAgentMiddlewareMeta;
+    constructor(monitor: DashboardMonitor, dashboards: DashboardService);
+    createMiddleware(options: unknown, context: IAgentMiddlewareContext): AgentMiddleware;
+}
+/** Business freshness must be an explicit data contract, never the query fetch timestamp. */
+export declare function assessFreshness(manifest: import('./dashboard.schema').DashboardManifest, datasets: import('@xpert-ai/contracts').AnalyticalDataset[], input: FreshnessRule, now: number): {
+    status: "unknown" | "stale" | "fresh";
+    latestTimestamp: string | null;
+    coverage: "latest_returned_timestamp";
+    bindingId: string;
+    fieldId: string;
+    maxAgeSeconds: number;
+};
+export {};

package/dist/lib/monitor.js

@@ -0,0 +1,101 @@
+"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.DashboardMonitorMiddleware = exports.DashboardMonitor = void 0;
+exports.assessFreshness = assessFreshness;
+const common_1 = require("@nestjs/common");
+const tools_1 = require("@langchain/core/tools");
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const dashboard_service_1 = require("./dashboard.service");
+const runtime_context_1 = require("./runtime-context");
+const dashboard_icon_1 = require("./dashboard-icon");
+const freshnessRuleSchema = v3_1.z.object({ bindingId: v3_1.z.string().min(1), fieldId: v3_1.z.string().min(1), maxAgeSeconds: v3_1.z.number().int().min(1).max(31536000) }).strict();
+let DashboardMonitor = class DashboardMonitor {
+    constructor(dashboards) {
+        this.dashboards = dashboards;
+    }
+    async inspect(context, artifactId, freshnessRule) {
+        const access = await this.dashboards.access(context);
+        if (!access.project || access.archived)
+            throw new common_1.ForbiddenException('DASHBOARD_ACTIVE_PROJECT_REQUIRED');
+        const saved = await this.dashboards.open(context, artifactId, undefined, undefined, 'published');
+        if (!saved.versionId)
+            throw new Error('DASHBOARD_NOT_PUBLISHED');
+        const result = await this.dashboards.query(context, artifactId, saved.versionId, {});
+        // Reauthorize the target after the queries; a receipt is bound to this formal version.
+        const current = await this.dashboards.open(context, artifactId, undefined, undefined, 'published');
+        if (current.versionId !== saved.versionId || (await this.dashboards.access(context)).archived)
+            throw new Error('DASHBOARD_INSPECTION_CHANGED');
+        const freshness = freshnessRule ? assessFreshness(saved.manifest, result.datasets, freshnessRule, Date.now()) : undefined;
+        return { artifactId, versionId: saved.versionId, title: saved.manifest.title,
+            status: result.failures.length || freshness && freshness.status !== 'fresh' ? 'attention' : 'healthy',
+            checkedAt: new Date().toISOString(), failures: result.failures,
+            datasets: result.datasets.map(dataset => ({ datasetId: dataset.datasetId, queryFetchedAt: dataset.freshness.sourceFetchedAt,
+                truncated: dataset.completeness.truncated, returnedRows: dataset.completeness.returnedRows })),
+            businessFreshness: freshness ?? 'not_asserted',
+            availableFreshnessFields: saved.manifest.bindings.flatMap(binding => binding.output.fields.filter(field => field.logicalType === 'timestamp')
+                .map(field => ({ bindingId: binding.id, fieldId: field.id, label: field.label }))) };
+    }
+};
+exports.DashboardMonitor = DashboardMonitor;
+exports.DashboardMonitor = DashboardMonitor = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [dashboard_service_1.DashboardService])
+], DashboardMonitor);
+let DashboardMonitorMiddleware = class DashboardMonitorMiddleware {
+    constructor(monitor, dashboards) {
+        this.monitor = monitor;
+        this.dashboards = dashboards;
+        this.meta = { name: 'LiveDashboardMonitor', icon: dashboard_icon_1.dashboardIcon, features: ['live_dashboard.monitor'],
+            label: { en_US: 'Dashboard inspection', zh_Hans: '看板巡检' },
+            description: { en_US: 'Inspect published Project dashboards without editing or publishing.', zh_Hans: '检查项目正式看板，不修改或发布。' },
+            configSchema: { type: 'object', properties: {}, additionalProperties: false } };
+    }
+    createMiddleware(options, context) {
+        v3_1.z.object({}).strict().parse(options ?? {});
+        const scope = (0, runtime_context_1.dashboardRuntimeContext)(context);
+        return { name: 'LiveDashboardMonitor', tools: [
+                (0, tools_1.tool)(async ({ artifactId, freshness }) => JSON.stringify(await this.monitor.inspect(scope, artifactId, freshness)), {
+                    name: 'dashboard_inspect', description: 'Check one explicitly selected published Project dashboard as the current run actor. Returns compact binding availability and query timestamps, never data rows. Does not modify or publish. Query time is not proof of business-data freshness. Only an explicitly configured freshness rule checks the latest returned declared timestamp, and incomplete results remain unknown. Scheduled runs retain this receipt in platform execution history.',
+                    schema: v3_1.z.object({ artifactId: v3_1.z.string().uuid(), freshness: freshnessRuleSchema.optional() }).strict(), verboseParsingErrors: true,
+                    metadata: { toolName: { en_US: 'Inspect published dashboard', zh_Hans: '巡检正式看板' } }
+                }),
+                (0, tools_1.tool)(async ({ page }) => {
+                    const access = await this.dashboards.access(scope);
+                    if (!access.project || access.archived)
+                        throw new common_1.ForbiddenException('DASHBOARD_ACTIVE_PROJECT_REQUIRED');
+                    const result = await this.dashboards.listPage(scope, page, 50);
+                    return JSON.stringify({ ...result, items: result.items.filter(item => !!item.versionId).map(({ artifactId, versionId, versionNumber, title }) => ({ artifactId, versionId, versionNumber, title })) });
+                }, { name: 'dashboard_list_published', description: 'List published dashboards in the current Project. Follow hasMore/page; never infer the target from recency.',
+                    schema: v3_1.z.object({ page: v3_1.z.number().int().positive().default(1) }).strict(), verboseParsingErrors: true,
+                    metadata: { toolName: { en_US: 'List published dashboards', zh_Hans: '列出正式看板' } } })
+            ] };
+    }
+};
+exports.DashboardMonitorMiddleware = DashboardMonitorMiddleware;
+exports.DashboardMonitorMiddleware = DashboardMonitorMiddleware = __decorate([
+    (0, plugin_sdk_1.AgentMiddlewareStrategy)('LiveDashboardMonitor'),
+    __metadata("design:paramtypes", [DashboardMonitor, dashboard_service_1.DashboardService])
+], DashboardMonitorMiddleware);
+/** Business freshness must be an explicit data contract, never the query fetch timestamp. */
+function assessFreshness(manifest, datasets, input, now) {
+    const rule = freshnessRuleSchema.parse(input);
+    const binding = manifest.bindings.find(binding => binding.id === rule.bindingId);
+    const field = binding?.output.fields.find(field => field.id === rule.fieldId && field.logicalType === 'timestamp');
+    const dataset = datasets.find(dataset => dataset.datasetId === binding?.output.datasetId);
+    const values = dataset?.rows.map(row => row[rule.fieldId]) ?? [];
+    const times = values.map(value => typeof value === 'string' && /(?:Z|[+-]\d{2}:\d{2})$/.test(value) ? Date.parse(value) : NaN);
+    const unknown = !field || !dataset || dataset.completeness.truncated || !times.length || times.some(time => !Number.isFinite(time) || time > now + 60000);
+    const latest = unknown ? null : times.reduce((latest, time) => Math.max(latest, time), -Infinity);
+    return { ...rule, status: unknown ? 'unknown' : now - latest > rule.maxAgeSeconds * 1000 ? 'stale' : 'fresh',
+        latestTimestamp: latest === null ? null : new Date(latest).toISOString(), coverage: 'latest_returned_timestamp' };
+}

package/dist/lib/plugin.js

@@ -7,7 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiveDashboardPlugin = void 0;
+const projects_service_1 = require("./projects.service");
 const content_capability_1 = require("./content-capability");
+const monitor_1 = require("./monitor");
 const content_provider_1 = require("./content.provider");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const dashboard_service_1 = require("./dashboard.service");
@@ -16,10 +18,11 @@ 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");
+const artifact_type_provider_1 = require("./artifact-type.provider");
 const provider_options_controller_1 = require("./provider-options.controller");
 let LiveDashboardPlugin = class LiveDashboardPlugin {
 };
 exports.LiveDashboardPlugin = LiveDashboardPlugin;
 exports.LiveDashboardPlugin = LiveDashboardPlugin = __decorate([
-    (0, plugin_sdk_1.XpertServerPlugin)({ controllers: [provider_options_controller_1.DashboardProviderOptionsController], providers: [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: [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/project.d.ts

@@ -0,0 +1,106 @@
+export declare const DASHBOARD_PROJECT_TYPE: {
+    readonly applicationKey: "@xpert-ai/plugin-live-dashboard:live-dashboard";
+    readonly projectTypeKey: "dashboard";
+};
+export declare const dashboardApp: {
+    type: "app";
+    name: string;
+    icon: {
+        type: "svg";
+        alt: string;
+        value: string;
+    };
+    appConfig: {
+        scope: "organization";
+        assistantTemplateKey: string;
+        workspace: {
+            mode: "dedicated";
+            sharing: "private";
+            name: {
+                en_US: string;
+                zh_Hans: string;
+            };
+            description: {
+                en_US: string;
+                zh_Hans: string;
+            };
+        };
+        knowledgebases: never[];
+        modelRequirements: {
+            primary: true;
+        };
+        presentation: {
+            developer: string;
+            tagline: {
+                en_US: string;
+                zh_Hans: string;
+            };
+            longDescription: {
+                en_US: string;
+                zh_Hans: string;
+            };
+            screenshots: string[];
+            features: {
+                key: string;
+                title: {
+                    en_US: string;
+                    zh_Hans: string;
+                };
+                description: {
+                    en_US: string;
+                    zh_Hans: string;
+                };
+            }[];
+            useCases: {
+                en_US: string;
+                zh_Hans: string;
+            }[];
+            dataScope: {
+                en_US: string;
+                zh_Hans: string;
+            };
+            initializationSummary: {
+                en_US: string;
+                zh_Hans: string;
+            };
+            initializationSteps: {
+                en_US: string;
+                zh_Hans: string;
+            }[];
+        };
+        entry: {
+            type: "assistant-chat";
+        };
+    };
+    displayName: {
+        en_US: string;
+        zh_Hans: string;
+    };
+    description: {
+        en_US: string;
+        zh_Hans: string;
+    };
+    projectTypes: {
+        key: "dashboard";
+        title: {
+            en_US: string;
+            zh_Hans: string;
+        };
+        icon: {
+            type: "svg";
+            alt: string;
+            value: string;
+        };
+        binding: {
+            kind: "project";
+        };
+    }[];
+};
+export type DashboardAccess = {
+    project: boolean;
+    archived: boolean;
+    canReadDraft: boolean;
+    canEdit: boolean;
+    canManage: boolean;
+};
+export type DashboardMode = 'published' | 'draft';

package/dist/lib/project.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardApp = exports.DASHBOARD_PROJECT_TYPE = void 0;
+const dashboard_icon_1 = require("./dashboard-icon");
+const app_config_1 = require("./app-config");
+exports.DASHBOARD_PROJECT_TYPE = {
+    applicationKey: '@xpert-ai/plugin-live-dashboard:live-dashboard', projectTypeKey: 'dashboard'
+};
+exports.dashboardApp = {
+    type: 'app', name: 'live-dashboard', icon: dashboard_icon_1.dashboardIcon,
+    appConfig: app_config_1.dashboardAppConfig,
+    displayName: { en_US: 'Live Dashboard', zh_Hans: '实时看板' },
+    description: { en_US: 'Create and use live dashboards in Assistant ChatKit with a synchronized Project selection.', zh_Hans: '在助理 ChatKit 中按项目制作和使用实时看板，项目选择双向同步。' },
+    projectTypes: [{ key: exports.DASHBOARD_PROJECT_TYPE.projectTypeKey,
+            title: { en_US: 'Live Dashboard project', zh_Hans: '实时看板项目' }, icon: dashboard_icon_1.dashboardIcon,
+            binding: { kind: 'project' } }]
+};

package/dist/lib/projects.schema.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod/v3';
+export declare const projectSearchSchema: z.ZodObject<{
+    search: z.ZodDefault<z.ZodString>;
+    page: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    search: string;
+    page: number;
+}, {
+    search?: string | undefined;
+    page?: number | undefined;
+}>;
+export declare const dashboardSearchSchema: z.ZodObject<{
+    search: z.ZodDefault<z.ZodString>;
+    page: z.ZodDefault<z.ZodNumber>;
+} & {
+    projectId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    search: string;
+    page: number;
+    projectId?: string | undefined;
+}, {
+    search?: string | undefined;
+    page?: number | undefined;
+    projectId?: string | undefined;
+}>;
+export declare const dashboardProjectSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+}, {
+    id: string;
+    name: string;
+}>;
+export declare const dashboardProjectsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+    }, {
+        id: string;
+        name: string;
+    }>, "many">;
+    page: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    items: {
+        id: string;
+        name: string;
+    }[];
+    hasMore: boolean;
+}, {
+    page: number;
+    items: {
+        id: string;
+        name: string;
+    }[];
+    hasMore: boolean;
+}>;

package/dist/lib/projects.schema.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardProjectsSchema = exports.dashboardProjectSchema = exports.dashboardSearchSchema = exports.projectSearchSchema = void 0;
+const v3_1 = require("zod/v3");
+exports.projectSearchSchema = v3_1.z.object({ search: v3_1.z.string().trim().max(200).default(''), page: v3_1.z.number().int().positive().default(1) }).strict();
+exports.dashboardSearchSchema = exports.projectSearchSchema.extend({ projectId: v3_1.z.string().uuid().optional() });
+exports.dashboardProjectSchema = v3_1.z.object({ id: v3_1.z.string().uuid(), name: v3_1.z.string() });
+exports.dashboardProjectsSchema = v3_1.z.object({ items: v3_1.z.array(exports.dashboardProjectSchema), page: v3_1.z.number().int().positive(), hasMore: v3_1.z.boolean() });

package/dist/lib/projects.service.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod/v3';
+import type { XpertResolvedViewHostContext } from '@xpert-ai/contracts';
+import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+import { projectSearchSchema } from './projects.schema';
+export { projectSearchSchema } from './projects.schema';
+/** Selection uses the host's membership and Assistant binding policy, never a client-supplied data scope. */
+export declare class DashboardProjectsService {
+    private readonly runtime;
+    constructor(runtime: RuntimeCapabilityRegistry);
+    private actor;
+    current(context: XpertResolvedViewHostContext): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    /** A picker target is untrusted until membership and the Assistant binding are revalidated. */
+    pickerContext(context: XpertResolvedViewHostContext, targetProjectId: string): Promise<XpertResolvedViewHostContext>;
+    list(context: XpertResolvedViewHostContext, input: z.infer<typeof projectSearchSchema>): Promise<{
+        items: {
+            id: string;
+            name: string;
+        }[];
+        page: number;
+        hasMore: boolean;
+    }>;
+}