@xpert-ai/plugin-live-dashboard 0.1.3 → 0.2.0

package/dist/lib/dashboard-view.schema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardViewDataSchema = exports.dashboardSavedSchema = exports.dashboardSummarySchema = void 0;
+const v3_1 = require("zod/v3");
+const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const dashboard_schema_1 = require("./dashboard.schema");
+const dashboard_navigation_1 = require("./dashboard-navigation");
+exports.dashboardSummarySchema = v3_1.z.object({ artifactId: v3_1.z.string(), versionId: v3_1.z.string().nullish(), versionNumber: v3_1.z.number().optional(), title: v3_1.z.string().nullish(), updatedAt: v3_1.z.string().optional(), draftRevision: v3_1.z.number().optional(), isDraft: v3_1.z.boolean().optional(), baseVersionId: v3_1.z.string().nullish() });
+exports.dashboardSavedSchema = exports.dashboardSummarySchema.extend({ manifest: dashboard_schema_1.dashboardSchema, dependencies: artifact_document_1.artifactDocumentDependencyAssets.optional() });
+// Source identities belong to Analytics, including immutable Definitions and Artifacts.
+// The viewer consumes only the reference and label; DataSource fields are not universal.
+exports.dashboardViewDataSchema = v3_1.z.object({ meta: v3_1.z.object({
+        navigationTarget: dashboard_navigation_1.dashboardNavigationTargetSchema.optional(),
+        dashboards: v3_1.z.array(exports.dashboardSummarySchema),
+        sources: v3_1.z.array(v3_1.z.object({ source: analytics_1.analyticsSourceRefSchema, name: v3_1.z.string() })),
+        saved: exports.dashboardSavedSchema.optional(),
+        versions: v3_1.z.array(exports.dashboardSummarySchema).optional()
+    }) });

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

@@ -1,6 +1,6 @@
 import { z } from 'zod/v3';
 export declare const dashboardSchema: z.ZodEffects<z.ZodObject<{
-    schema: z.ZodLiteral<"xpert.live-dashboard/v1">;
+    schema: z.ZodLiteral<"xpert.live-dashboard">;
     id: z.ZodString;
     title: z.ZodString;
     bindings: z.ZodArray<z.ZodType<import("@xpert-ai/contracts").AnalyticsBinding, z.ZodTypeDef, import("@xpert-ai/contracts").AnalyticsBinding>, "many">;
@@ -114,7 +114,7 @@ export declare const dashboardSchema: z.ZodEffects<z.ZodObject<{
         fields: string[];
     }>, "many">;
 }, "strict", z.ZodTypeAny, {
-    schema: "xpert.live-dashboard/v1";
+    schema: "xpert.live-dashboard";
     id: string;
     title: string;
     bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -146,7 +146,7 @@ export declare const dashboardSchema: z.ZodEffects<z.ZodObject<{
         dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
     } | undefined;
 }, {
-    schema: "xpert.live-dashboard/v1";
+    schema: "xpert.live-dashboard";
     id: string;
     title: string;
     bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -184,7 +184,7 @@ export declare const dashboardSchema: z.ZodEffects<z.ZodObject<{
         }[] | undefined;
     } | undefined;
 }>, {
-    schema: "xpert.live-dashboard/v1";
+    schema: "xpert.live-dashboard";
     id: string;
     title: string;
     bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -216,7 +216,7 @@ export declare const dashboardSchema: z.ZodEffects<z.ZodObject<{
         dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
     } | undefined;
 }, {
-    schema: "xpert.live-dashboard/v1";
+    schema: "xpert.live-dashboard";
     id: string;
     title: string;
     bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -442,7 +442,7 @@ export type DashboardChanges = z.output<typeof dashboardChangesSchema>;
 export declare const controlsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
 export declare const saveSchema: z.ZodObject<{
     manifest: z.ZodEffects<z.ZodObject<{
-        schema: z.ZodLiteral<"xpert.live-dashboard/v1">;
+        schema: z.ZodLiteral<"xpert.live-dashboard">;
         id: z.ZodString;
         title: z.ZodString;
         bindings: z.ZodArray<z.ZodType<import("@xpert-ai/contracts").AnalyticsBinding, z.ZodTypeDef, import("@xpert-ai/contracts").AnalyticsBinding>, "many">;
@@ -556,7 +556,7 @@ export declare const saveSchema: z.ZodObject<{
             fields: string[];
         }>, "many">;
     }, "strict", z.ZodTypeAny, {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -588,7 +588,7 @@ export declare const saveSchema: z.ZodObject<{
             dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
         } | undefined;
     }, {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -626,7 +626,7 @@ export declare const saveSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
     }>, {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -658,7 +658,7 @@ export declare const saveSchema: z.ZodObject<{
             dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
         } | undefined;
     }, {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -700,7 +700,7 @@ export declare const saveSchema: z.ZodObject<{
     expectedRevision: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     manifest: {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -736,7 +736,7 @@ export declare const saveSchema: z.ZodObject<{
     expectedRevision: number;
 }, {
     manifest: {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];

package/dist/lib/dashboard.schema.js

@@ -6,8 +6,8 @@ const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
 const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
 const id = v3_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,79}$/);
 exports.dashboardSchema = v3_1.z.object({
-    schema: v3_1.z.literal('xpert.live-dashboard/v1'), id: v3_1.z.string().uuid(), title: v3_1.z.string().min(1).max(160),
-    bindings: v3_1.z.array(analytics_1.analyticsBindingSchema).min(1).max(8),
+    schema: v3_1.z.literal('xpert.live-dashboard'), id: v3_1.z.string().uuid(), title: v3_1.z.string().min(1).max(160),
+    bindings: v3_1.z.array(analytics_1.analyticsBindingSchema).max(8),
     presentation: v3_1.z.object({ type: v3_1.z.literal('html'), html: artifact_document_1.artifactDocumentHtml, dependencies: artifact_document_1.artifactDocumentDependencyLocks.optional() }).strict().optional(),
     controls: v3_1.z.array(v3_1.z.object({ controlId: id, type: v3_1.z.enum(['string', 'number', 'boolean', 'date']),
         defaultValue: v3_1.z.union([v3_1.z.string(), v3_1.z.number(), v3_1.z.boolean(), v3_1.z.null()]).optional(),
@@ -21,11 +21,13 @@ exports.dashboardSchema = v3_1.z.object({
         if (new Set(values).size !== values.length)
             ctx.addIssue({ code: 'custom', message: `Duplicate ${name}` });
     };
+    if (!manifest.bindings.length && (manifest.presentation || manifest.controls.length || manifest.charts.length || manifest.tables.length))
+        ctx.addIssue({ code: 'custom', message: 'An unconfigured draft must contain no views or controls' });
     unique(manifest.bindings.map((binding) => binding.id), 'binding');
     unique(manifest.bindings.map((binding) => binding.output.datasetId), 'dataset');
     unique(manifest.controls.map((control) => control.controlId), 'control');
     unique([...manifest.charts, ...manifest.tables].map((view) => view.id), 'view');
-    if (!manifest.presentation && !manifest.charts.length && !manifest.tables.length)
+    if (manifest.bindings.length && !manifest.presentation && !manifest.charts.length && !manifest.tables.length)
         ctx.addIssue({ code: 'custom', message: 'At least one chart or table is required' });
     if (manifest.presentation && (manifest.charts.length || manifest.tables.length))
         ctx.addIssue({ code: 'custom', message: 'HTML presentation owns its charts; use empty charts/tables arrays' });

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

@@ -27,7 +27,7 @@ export declare class DashboardService {
     }>;
     open(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
         manifest: {
-            schema: "xpert.live-dashboard/v1";
+            schema: "xpert.live-dashboard";
             id: string;
             title: string;
             bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -72,7 +72,7 @@ export declare class DashboardService {
     /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
     openDocument(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
         manifest: {
-            schema: "xpert.live-dashboard/v1";
+            schema: "xpert.live-dashboard";
             id: string;
             title: string;
             bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -194,8 +194,13 @@ export declare class DashboardService {
             };
         } | undefined;
         datasets: import("@xpert-ai/contracts").AnalyticalDataset[];
+        failures: {
+            bindingId: string;
+            datasetId: string;
+            reason: "unavailable";
+        }[];
         manifest: {
-            schema: "xpert.live-dashboard/v1";
+            schema: "xpert.live-dashboard";
             id: string;
             title: string;
             bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
@@ -238,6 +243,9 @@ export declare class DashboardService {
         versionNumber: number | undefined;
     }>;
     queryBinding(context: XpertResolvedViewHostContext, artifactId: string, versionId: string | undefined, bindingId: string, input: Record<string, AnalyticsValue>, draftRevision?: number): Promise<import("@xpert-ai/contracts").AnalyticalDataset>;
+    /** Every operation uses the current human's Project role; data queries still use actor(context). */
+    authorizeProject(context: XpertResolvedViewHostContext, operation?: 'read' | 'write' | 'manage'): Promise<void>;
     private execute;
     private probeControls;
 }
+export declare function projectId(context: XpertResolvedViewHostContext): string | null | undefined;

package/dist/lib/dashboard.service.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DashboardService = exports.PLUGIN_NAME = void 0;
+exports.projectId = projectId;
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
@@ -39,20 +40,24 @@ let DashboardService = class DashboardService {
         return dataset;
     }
     async list(context) {
-        actor(context);
+        await this.authorizeProject(context);
         const result = await this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability).listArtifacts({ pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceIdPrefix: hostPrefix(context), status: 'active', pageSize: 100, includeCurrentVersion: true });
-        const items = result.items.filter((item) => item.resourceId.startsWith(hostPrefix(context)) && item.userId === context.userId);
+        const items = result.items.filter((item) => item.resourceId.startsWith(hostPrefix(context)) && (item.userId === context.userId || !item.userId && item.projectId === projectId(context)));
         const drafts = new Map((await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).list(items.map(item => item.id))).map(draft => [draft.artifactId, draft]));
         return items.map(item => ({ ...summary(item), ...(drafts.has(item.id) ? { title: drafts.get(item.id).title ?? item.title } : {}) }));
     }
     async save(context, manifest, expectedVersionId, expectedRevision = 0) {
+        await this.authorizeProject(context, 'write');
         const scopedActor = actor(context);
         const parsed = dashboard_schema_1.dashboardSchema.parse(manifest);
         const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
         const source = { pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceId: `${hostPrefix(context)}${parsed.id}` };
         const existing = await artifacts.findArtifactBySource(source);
-        if (existing && existing.userId !== scopedActor.userId)
-            throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
+        if (existing) {
+            assertOwned(context, existing);
+            if (existing.status !== 'active')
+                throw new common_1.ForbiddenException('DASHBOARD_ARCHIVED');
+        }
         // A failed first upload can leave an Artifact with no saved content; revision 0 initializes it.
         const previous = existing && (existing.currentVersionId || expectedRevision > 0) ? await this.openDocument(context, existing.id) : null;
         const dependencies = await (0, document_libraries_1.resolveLibraryAssets)(parsed.presentation?.dependencies ?? [], previous?.dependencies);
@@ -70,14 +75,22 @@ let DashboardService = class DashboardService {
             await this.probeControls(context, binding, Object.fromEntries(parsed.controls.filter((control) => control.defaultValue !== undefined).map((control) => [control.controlId, control.defaultValue ?? null])));
         const htmlValidation = await this.htmlValidation.validate(context, parsed, preview, dependencies);
         const artifact = existing ?? await artifacts.createArtifact({ source, kind: 'file', title: parsed.title,
-            scope: { ...scopedActor, ...(context.hostType === 'project' ? { projectId: context.hostId } : { xpertId: context.hostId }) } });
+            scope: { ...scopedActor, ...(projectId(context) ? { projectId: projectId(context), userId: null } : { xpertId: context.hostId }) } });
         const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
-        const scope = { tenantId: scopedActor.tenantId, userId: scopedActor.userId, catalog: 'users' };
-        const file = await files.uploadBuffer({ ...scope, buffer, originalName: 'dashboard.json', fileName: `${digest}.json`, folder: `live-dashboards/${parsed.id}`, mimeType: MIME_TYPE });
+        const project = projectId(context);
+        // Shared definitions live in the Project volume; private legacy dashboards retain their user volume.
+        const privateScope = { tenantId: scopedActor.tenantId, userId: scopedActor.userId, catalog: 'users' };
+        const reference = project
+            ? (await files.writeRuntimeBuffer({ tenantId: scopedActor.tenantId, userId: scopedActor.userId,
+                catalog: 'projects', scopeId: project, projectId: project, buffer, originalName: 'dashboard.json',
+                fileName: `${digest}.json`, folder: `.xpert/live-dashboards/${parsed.id}`, mimeType: MIME_TYPE })).reference
+            : await files.uploadBuffer({ ...privateScope, buffer, originalName: 'dashboard.json', fileName: `${digest}.json`,
+                folder: `live-dashboards/${parsed.id}`, mimeType: MIME_TYPE }).then(file => ({
+                source: 'platform.workspace.files', ...privateScope, filePath: file.filePath, workspacePath: file.workspacePath
+            }));
         const result = await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).save({ artifactId: artifact.id, expectedRevision,
             expectedCurrentVersionId: expectedVersionId, mimeType: MIME_TYPE, title: parsed.title, fileName: 'dashboard.json', sha256: digest,
-            ...(htmlValidation ? { metadata: { htmlValidation } } : {}),
-            workspaceFileRef: { source: 'platform.workspace.files', ...scope, filePath: file.filePath, workspacePath: file.workspacePath } });
+            ...(htmlValidation ? { metadata: { htmlValidation } } : {}), workspaceFileRef: reference });
         return { artifactId: artifact.id, draftId: result.id, draftRevision: result.revision, baseVersionId: result.baseVersionId, status: 'draft', title: parsed.title };
     }
     async open(context, artifactId, versionId, draftRevision) {
@@ -86,10 +99,12 @@ let DashboardService = class DashboardService {
     }
     /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
     async openDocument(context, artifactId, versionId, draftRevision) {
-        actor(context);
+        await this.authorizeProject(context);
         const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
         const artifact = await artifacts.getArtifact(artifactId);
         assertOwned(context, artifact);
+        if (artifact.status !== 'active')
+            throw new common_1.ForbiddenException('DASHBOARD_ARCHIVED');
         const draft = !versionId || draftRevision !== undefined ? await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).get(artifactId) : null;
         if (draftRevision !== undefined && draft?.revision !== draftRevision)
             throw new common_1.ConflictException('DASHBOARD_DRAFT_CONFLICT');
@@ -109,10 +124,12 @@ let DashboardService = class DashboardService {
                 isDraft: draft.revision !== draft.publishedRevision, title: draft.title, updatedAt: draft.updatedAt } : {}), manifest, dependencies };
     }
     async history(context, artifactId) {
-        actor(context);
+        await this.authorizeProject(context);
         const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
         const artifact = await artifacts.getArtifact(artifactId);
         assertOwned(context, artifact);
+        if (artifact.status !== 'active')
+            throw new common_1.ForbiddenException('DASHBOARD_ARCHIVED');
         const versions = await artifacts.listArtifactVersions({ artifactId, status: 'active' });
         return versions.map(version => ({ ...summary(artifact, version), current: version.id === artifact.currentVersionId }))
             .sort((a, b) => (b.versionNumber ?? 0) - (a.versionNumber ?? 0));
@@ -124,7 +141,10 @@ let DashboardService = class DashboardService {
         return this.save(context, dashboard_schema_1.dashboardSchema.parse({ ...saved.manifest, ...dashboard_schema_1.dashboardChangesSchema.parse(changes) }), saved.baseVersionId ?? saved.versionId ?? null, expectedRevision);
     }
     async publish(context, artifactId, expectedRevision, expectedCurrentVersionId) {
+        await this.authorizeProject(context, 'manage');
         const saved = await this.open(context, artifactId, undefined, expectedRevision);
+        if (!saved.manifest.bindings.length)
+            throw new common_1.BadRequestException('DASHBOARD_CONFIGURE_BEFORE_PUBLISHING');
         const share = await this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability).getArtifactShare({ artifactId, shareKey: dashboard_sharing_1.DASHBOARD_SHARE_KEY });
         if (share?.status === 'active' && share.versionMode === 'latest' && (!share.expiresAt || new Date(share.expiresAt).getTime() > Date.now())) {
             const issues = (0, dashboard_sharing_1.dashboardSharingIssues)(saved.manifest, await this.sources(context));
@@ -138,13 +158,29 @@ let DashboardService = class DashboardService {
     }
     async query(context, artifactId, versionId, controls, draftRevision) {
         const saved = await this.open(context, artifactId, versionId, draftRevision);
-        const datasets = await this.execute(context, saved.manifest, controls);
-        return { ...saved, datasets, ...(saved.manifest.presentation ? {} : { payload: (0, renderer_1.toDataAnalyticsPayload)(saved.manifest, datasets) }) };
+        const { datasets, failures } = await (0, dashboard_queries_1.queryDashboardPartial)(this.runtime, actor(context), saved.manifest, controls);
+        return { ...saved, datasets, failures, ...(saved.manifest.presentation ? {} : { payload: (0, renderer_1.toDataAnalyticsPayload)(saved.manifest, datasets) }) };
     }
     async queryBinding(context, artifactId, versionId, bindingId, input, draftRevision) {
         const saved = await this.open(context, artifactId, versionId, draftRevision);
         return (0, dashboard_queries_1.queryDashboardBinding)(this.runtime, actor(context), saved.manifest, bindingId, input);
     }
+    /** Every operation uses the current human's Project role; data queries still use actor(context). */
+    async authorizeProject(context, operation = 'read') {
+        const scopedActor = actor(context), project = projectId(context);
+        if (!project)
+            return;
+        const access = this.runtime.require(plugin_sdk_1.ProjectAccessRuntimeCapability);
+        const input = { actor: scopedActor, projectId: project };
+        if (context.hostType === 'agent')
+            await access.assertAssistant({ ...input, assistantId: context.hostId });
+        if (operation === 'write')
+            await access.assertEdit(input);
+        else if (operation === 'manage')
+            await access.assertManage(input);
+        else if (!(await access.listReadable({ actor: scopedActor, projectIds: [project] })).length)
+            throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
+    }
     execute(context, manifest, input) {
         return (0, dashboard_queries_1.queryDashboard)(this.runtime, actor(context), manifest, input);
     }
@@ -159,12 +195,9 @@ let DashboardService = class DashboardService {
             const samples = [...(alternative !== undefined ? [alternative] : []),
                 ...(current !== null && parameter.allowedValues?.includes(null) ? [null] : [])];
             for (const value of samples) {
-                try {
-                    await this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).query(actor(context), { binding, controls: { ...controls, [parameter.controlId]: value } });
-                }
-                catch {
-                    throw new common_1.BadRequestException(`DASHBOARD_FILTER_PREVIEW_FAILED: ${parameter.controlId}; a declared non-default filter failed. Inspect the native parameter type and operator before retrying.`);
-                }
+                // Analytics already redacts provider failures. Preserve its actionable validation
+                // errors: a duplicate grain is not a malformed filter and needs a different repair.
+                await this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).query(actor(context), { binding, controls: { ...controls, [parameter.controlId]: value } });
             }
         }
     }
@@ -180,10 +213,11 @@ function actor(context) {
         throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
     return { tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId };
 }
-function hostPrefix(context) { return `${context.hostType}/${context.hostId}/`; }
+function projectId(context) { return context.hostType === 'project' ? context.hostId : context.runtimeScope?.projectId; }
+function hostPrefix(context) { return projectId(context) ? `project/${projectId(context)}/` : `${context.hostType}/${context.hostId}/`; }
 function assertOwned(context, artifact) {
     if (artifact.pluginName !== exports.PLUGIN_NAME || artifact.resourceType !== RESOURCE_TYPE || !artifact.resourceId.startsWith(hostPrefix(context)) ||
-        artifact.tenantId !== context.tenantId || artifact.organizationId !== context.organizationId || artifact.userId !== context.userId)
+        artifact.tenantId !== context.tenantId || artifact.organizationId !== context.organizationId || (artifact.userId ? artifact.userId !== context.userId : !projectId(context) || artifact.projectId !== projectId(context)))
         throw new common_1.ForbiddenException('DASHBOARD_ACCESS_DENIED');
 }
 function summary(artifact, version = artifact.currentVersion) {

package/dist/lib/definition-tools.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod/v3';
+import { type IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
+export declare const DEFINITION_GUIDANCE = "If dashboard_list_sources lacks the requested source, call analytics_definition_connections, then analytics_definition_inspect with an exact returned selection and inputJson=\"{}\". Follow its instructions, inspect real source data and generate the business definition yourself. Never ask users to fill internal IDs/configuration. Register using analytics_definition_register and a stable requestId, refresh dashboard_list_sources, discover the returned source and preview before saving. Settings \u2192 Analytics is for viewing, correction and version management. Do not create redundant definitions for already governed sources.";
+export declare function createDefinitionTools(context: IAgentMiddlewareContext, registered: () => void): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>, {}, {}, string> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    providerId: z.ZodString;
+    connectionKey: z.ZodString;
+} & {
+    inputJson: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    providerId: string;
+    connectionKey: string;
+    inputJson: string;
+}, {
+    providerId: string;
+    connectionKey: string;
+    inputJson: string;
+}>, {
+    providerId: string;
+    connectionKey: string;
+    inputJson: string;
+}, {
+    providerId: string;
+    connectionKey: string;
+    inputJson: string;
+}, string> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    providerId: z.ZodString;
+    connectionKey: z.ZodString;
+} & {
+    requestId: z.ZodString;
+    name: z.ZodString;
+    definitionJson: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    providerId: string;
+    connectionKey: string;
+    requestId: string;
+    definitionJson: string;
+}, {
+    name: string;
+    providerId: string;
+    connectionKey: string;
+    requestId: string;
+    definitionJson: string;
+}>, {
+    name: string;
+    providerId: string;
+    connectionKey: string;
+    requestId: string;
+    definitionJson: string;
+}, {
+    name: string;
+    providerId: string;
+    connectionKey: string;
+    requestId: string;
+    definitionJson: string;
+}, string>)[];

package/dist/lib/definition-tools.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFINITION_GUIDANCE = void 0;
+exports.createDefinitionTools = createDefinitionTools;
+const tools_1 = require("@langchain/core/tools");
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const selection = v3_1.z.object({ providerId: v3_1.z.string().min(1).max(160), connectionKey: v3_1.z.string().min(1).max(400) }).strict();
+exports.DEFINITION_GUIDANCE = 'If dashboard_list_sources lacks the requested source, call analytics_definition_connections, then analytics_definition_inspect with an exact returned selection and inputJson="{}". Follow its instructions, inspect real source data and generate the business definition yourself. Never ask users to fill internal IDs/configuration. Register using analytics_definition_register and a stable requestId, refresh dashboard_list_sources, discover the returned source and preview before saving. Settings → Analytics is for viewing, correction and version management. Do not create redundant definitions for already governed sources.';
+function createDefinitionTools(context, registered) {
+    const api = () => {
+        if (!context.workspaceId || !context.xpertId || !context.organizationId || !context.runtime?.capabilities)
+            throw new Error('ANALYTICS_ASSISTANT_SCOPE_REQUIRED');
+        return { runtime: context.runtime.capabilities.require(plugin_sdk_1.AnalyticsDefinitionAuthoringCapability), scope: {
+                actor: { tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId },
+                workspaceId: context.workspaceId, xpertId: context.xpertId,
+                files: context.runtime.capabilities.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability)
+            } };
+    };
+    return [
+        (0, tools_1.tool)(async () => { const { runtime, scope } = api(); return JSON.stringify(await runtime.catalog(scope)); }, {
+            name: 'analytics_definition_connections', description: 'List authorized connections for generating a missing analytics source. Returns exact providerId/connectionKey selections; no credentials.',
+            schema: v3_1.z.object({}).strict(), metadata: { toolName: { en_US: 'Find analytics inputs', zh_Hans: '发现分析输入' } }
+        }),
+        (0, tools_1.tool)(async ({ inputJson, ...selection }) => {
+            const { runtime, scope } = api();
+            return JSON.stringify(await runtime.inspect(scope, selection, plugin_sdk_1.analyticsOptionsSchema.parse(JSON.parse(inputJson))));
+        }, { name: 'analytics_definition_inspect', description: 'Inspect approved input metadata and provider authoring schemas. Start inputJson="{}". Follow inspectSchema for operation samples/file inspection. Input cannot override host scope.',
+            schema: selection.extend({ inputJson: v3_1.z.string().min(2).max(100000) }).strict(), verboseParsingErrors: true,
+            metadata: { toolName: { en_US: 'Inspect analytics input', zh_Hans: '检查分析输入' } }
+        }),
+        (0, tools_1.tool)(async ({ definitionJson, ...input }) => {
+            const { runtime, scope } = api();
+            const receipt = await runtime.register(scope, { ...input, definition: plugin_sdk_1.analyticsOptionsSchema.parse(JSON.parse(definitionJson)) });
+            registered();
+            return JSON.stringify(receipt);
+        }, { name: 'analytics_definition_register', description: 'Register an Agent-generated definition matching definitionSchema. System supplies identities and validates real input. Keep requestId stable on retries; changed intent needs another key. Returns an immutable source and discoveryRequest. Refresh sources, discover and preview it before saving a dashboard.',
+            schema: selection.extend({ requestId: v3_1.z.string().min(1).max(128), name: v3_1.z.string().min(1).max(200), definitionJson: v3_1.z.string().min(2).max(100000) }).strict(), verboseParsingErrors: true,
+            metadata: { toolName: { en_US: 'Register analytics definition', zh_Hans: '生成分析定义' } }
+        })
+    ];
+}

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

@@ -0,0 +1,4 @@
+import { type ArtifactDocumentHostOptions } from '@xpert-ai/plugin-sdk/artifact-document';
+/** The HTML never supplies or overrides its network permissions. */
+export declare function mountDashboardDocument<T>(frame: HTMLIFrameElement, options: ArtifactDocumentHostOptions<T>): import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentHost;
+export declare function isDashboardResourceAllowed(resourceType: string, url: string): boolean;

package/dist/lib/document-host.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountDashboardDocument = mountDashboardDocument;
+exports.isDashboardResourceAllowed = isDashboardResourceAllowed;
+const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const document_network_1 = require("./document-network");
+/** The HTML never supplies or overrides its network permissions. */
+function mountDashboardDocument(frame, options) {
+    return (0, artifact_document_1.mountArtifactDocument)(frame, { ...options, networkPolicy: document_network_1.DASHBOARD_NETWORK_POLICY });
+}
+function isDashboardResourceAllowed(resourceType, url) {
+    return (0, artifact_document_1.isArtifactDocumentResourceAllowed)(document_network_1.DASHBOARD_NETWORK_POLICY, resourceType, url);
+}

package/dist/lib/document-network.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactDocumentNetworkPolicy } from '@xpert-ai/plugin-sdk/artifact-document';
+/** Trusted plugin policy, shared by the displayed document and browser preflight. */
+export declare const DASHBOARD_NETWORK_POLICY: ArtifactDocumentNetworkPolicy;

package/dist/lib/document-network.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DASHBOARD_NETWORK_POLICY = void 0;
+/** Trusted plugin policy, shared by the displayed document and browser preflight. */
+exports.DASHBOARD_NETWORK_POLICY = {
+    scripts: ['https://cdn.tailwindcss.com', 'https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com'],
+    styles: ['https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com', 'https://fonts.googleapis.com'],
+    fonts: ['https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com', 'https://fonts.gstatic.com']
+};

package/dist/lib/document-package.d.ts

@@ -5,7 +5,7 @@ export declare const MAX_DASHBOARD_PACKAGE_BYTES = 9000000;
 export declare function encodeDashboardPackage(manifest: DashboardManifest, dependencies: ArtifactDocumentDependencyAsset[]): Buffer<ArrayBuffer>;
 export declare function decodeDashboardPackage(bytes: Buffer): {
     manifest: {
-        schema: "xpert.live-dashboard/v1";
+        schema: "xpert.live-dashboard";
         id: string;
         title: string;
         bindings: import("@xpert-ai/contracts").AnalyticsBinding[];

package/dist/lib/document-package.js

@@ -8,13 +8,13 @@ const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
 const dashboard_schema_1 = require("./dashboard.schema");
 exports.MAX_DASHBOARD_PACKAGE_BYTES = 9_000_000;
 const storedSchema = v3_1.z.union([
-    v3_1.z.object({ schema: v3_1.z.literal('xpert.live-dashboard.package/v1'), manifest: dashboard_schema_1.dashboardSchema, dependencies: artifact_document_1.artifactDocumentDependencyAssets }).strict(),
+    v3_1.z.object({ schema: v3_1.z.literal('xpert.live-dashboard.package'), manifest: dashboard_schema_1.dashboardSchema, dependencies: artifact_document_1.artifactDocumentDependencyAssets }).strict(),
     dashboard_schema_1.dashboardSchema.transform(manifest => ({ manifest, dependencies: [] }))
 ]);
 /** Definition and exact library bytes share one immutable Artifact Version and content checksum. */
 function encodeDashboardPackage(manifest, dependencies) {
     (0, artifact_document_1.verifyArtifactDocumentDependencies)(dependencies, manifest.presentation?.dependencies ?? []);
-    return Buffer.from(JSON.stringify(dependencies.length ? { schema: 'xpert.live-dashboard.package/v1', manifest, dependencies } : manifest));
+    return Buffer.from(JSON.stringify(dependencies.length ? { schema: 'xpert.live-dashboard.package', manifest, dependencies } : manifest));
 }
 function decodeDashboardPackage(bytes) {
     if (bytes.byteLength > exports.MAX_DASHBOARD_PACKAGE_BYTES)

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

@@ -1 +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.";
+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. Call dashboard_libraries for packaged ECharts/Three.js and the allowed HTTPS origins for online scripts, stylesheets and fonts. Tailwind CDN is supported through script src; pin a version when possible. Online resource failures must be repaired before saving. Do not add online URLs to the packaged libraries array; 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

@@ -1,4 +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.`;
+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. Call dashboard_libraries for packaged ECharts/Three.js and the allowed HTTPS origins for online scripts, stylesheets and fonts. Tailwind CDN is supported through script src; pin a version when possible. Online resource failures must be repaired before saving. Do not add online URLs to the packaged libraries array; 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.`;