@agent-native/core 0.87.0 → 0.88.0

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -6,97 +6,12 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
-import { buildDashboardPanelGroups } from "../app/pages/adhoc/sql-dashboard/dashboard-layout";
 import {
-  clampDashboardColumns,
-  type SqlPanel,
-} from "../app/pages/adhoc/sql-dashboard/types";
+  buildDashboardAgentContext,
+  buildDashboardSeedAgentContext,
+} from "../server/lib/agent-readable-resource-context";
 import { loadDashboardSeed } from "../server/lib/dashboard-seeds";
 import { getDashboard } from "../server/lib/dashboards-store";
-import { getPanelOrder } from "./dashboard-panel-order";
-
-function dashboardLayoutSummary(config: Record<string, unknown>) {
-  const panels = Array.isArray(config.panels)
-    ? (config.panels as SqlPanel[])
-    : [];
-  const columns = clampDashboardColumns(config.columns);
-  const groups = buildDashboardPanelGroups(panels, columns);
-  const panelOrder = getPanelOrder(config);
-  let visibleRowNumber = 1;
-
-  return {
-    panelCount: panelOrder.length,
-    panelOrder,
-    firstPanelIds: panelOrder.slice(0, 10),
-    groups: groups.map((group) => ({
-      key: group.key,
-      sectionId: group.section?.id ?? null,
-      sectionTitle: group.section?.title ?? null,
-      columns: group.columns,
-      rows: group.rows.map((row, rowIndex) => {
-        const rowNumber = visibleRowNumber++;
-        return {
-          rowNumber,
-          rowIndex,
-          panelIds: row.panels.map((panel) => panel.id),
-        };
-      }),
-    })),
-  };
-}
-
-function panelSummaries(config: Record<string, unknown>) {
-  const panels = Array.isArray(config.panels)
-    ? (config.panels as Array<Record<string, unknown>>)
-    : [];
-  return panels.map((panel, index) => {
-    const panelConfig =
-      panel.config &&
-      typeof panel.config === "object" &&
-      !Array.isArray(panel.config)
-        ? (panel.config as Record<string, unknown>)
-        : {};
-    return {
-      index,
-      id: typeof panel.id === "string" ? panel.id : "",
-      title: typeof panel.title === "string" ? panel.title : "",
-      chartType: typeof panel.chartType === "string" ? panel.chartType : "",
-      source: typeof panel.source === "string" ? panel.source : undefined,
-      width: typeof panel.width === "number" ? panel.width : undefined,
-      columns: typeof panel.columns === "number" ? panel.columns : undefined,
-      tab: typeof panel.tab === "string" ? panel.tab : undefined,
-      description:
-        typeof panelConfig.description === "string"
-          ? panelConfig.description
-          : undefined,
-    };
-  });
-}
-
-function seededResponse(
-  id: string,
-  seed: Record<string, unknown>,
-  includeConfig: boolean,
-): Record<string, unknown> {
-  const base = {
-    id,
-    name: typeof seed.name === "string" ? seed.name : id,
-    description:
-      typeof seed.description === "string" ? seed.description : undefined,
-    filters: seed.filters,
-    variables: seed.variables,
-    columns: seed.columns,
-    panels: panelSummaries(seed),
-    layout: dashboardLayoutSummary(seed),
-    ownerEmail: null,
-    orgId: null,
-    visibility: "org",
-    archivedAt: null,
-    hiddenAt: null,
-    hiddenBy: null,
-  };
-  return includeConfig ? { ...base, ...seed } : base;
-}
 
 export default defineAction({
   description:
@@ -149,34 +64,15 @@ export default defineAction({
     if (!dash || dash.kind !== "sql") {
       const seed = loadDashboardSeed(args.id);
       if (seed)
-        return seededResponse(args.id, seed, args.includeConfig === true);
+        return buildDashboardSeedAgentContext(args.id, seed, {
+          includeConfig: args.includeConfig === true,
+        });
       throw Object.assign(new Error("Dashboard not found"), {
         statusCode: 404,
       });
     }
-    const config = dash.config as Record<string, unknown>;
-    const base = {
-      id: args.id,
-      name: typeof config.name === "string" ? config.name : args.id,
-      description:
-        typeof config.description === "string" ? config.description : undefined,
-      filters: config.filters,
-      variables: config.variables,
-      columns: config.columns,
-      panels: panelSummaries(config),
-      layout: dashboardLayoutSummary(config),
-      ownerEmail: dash.ownerEmail,
-      orgId: dash.orgId,
-      visibility: dash.visibility,
-      role: dash.role,
-      canEdit: dash.canEdit,
-      canManage: dash.canManage,
-      archivedAt: dash.archivedAt,
-      hiddenAt: dash.hiddenAt,
-      hiddenBy: dash.hiddenBy,
-      createdAt: dash.createdAt,
-      updatedAt: dash.updatedAt,
-    };
-    return args.includeConfig === true ? { ...base, ...config } : base;
+    return buildDashboardAgentContext(dash, {
+      includeConfig: args.includeConfig === true,
+    });
   },
 });

package/corpus/templates/analytics/server/db/index.ts

@@ -1,6 +1,12 @@
 import { createGetDb } from "@agent-native/core/db";
 import { registerShareableResource } from "@agent-native/core/sharing";
 
+import {
+  ANALYTICS_ANALYSIS_AGENT_CONTEXT_ENDPOINT,
+  ANALYTICS_ANALYSIS_AGENT_RESOURCE_KIND,
+  ANALYTICS_DASHBOARD_AGENT_CONTEXT_ENDPOINT,
+  ANALYTICS_DASHBOARD_AGENT_RESOURCE_KIND,
+} from "../../shared/resource-agent-access.js";
 import * as schema from "./schema.js";
 
 export const getDb = createGetDb(schema);
@@ -13,6 +19,10 @@ registerShareableResource({
   displayName: "Dashboard",
   titleColumn: "title",
   getResourcePath: (dashboard) => `/dashboards/${dashboard.id}`,
+  agentReadable: {
+    resourceKind: ANALYTICS_DASHBOARD_AGENT_RESOURCE_KIND,
+    getContextPath: () => ANALYTICS_DASHBOARD_AGENT_CONTEXT_ENDPOINT,
+  },
   getDb,
 });
 
@@ -23,6 +33,10 @@ registerShareableResource({
   displayName: "Analysis",
   titleColumn: "name",
   getResourcePath: (analysis) => `/analyses/${analysis.id}`,
+  agentReadable: {
+    resourceKind: ANALYTICS_ANALYSIS_AGENT_RESOURCE_KIND,
+    getContextPath: () => ANALYTICS_ANALYSIS_AGENT_CONTEXT_ENDPOINT,
+  },
   getDb,
 });
 

package/corpus/templates/analytics/server/lib/agent-readable-resource-context.ts

@@ -0,0 +1,156 @@
+import { getPanelOrder } from "../../actions/dashboard-panel-order.js";
+import { buildDashboardPanelGroups } from "../../app/pages/adhoc/sql-dashboard/dashboard-layout";
+import {
+  clampDashboardColumns,
+  type SqlPanel,
+} from "../../app/pages/adhoc/sql-dashboard/types";
+import type { AnalysisRecord, DashboardRecord } from "./dashboards-store.js";
+
+function dashboardLayoutSummary(config: Record<string, unknown>) {
+  const panels = Array.isArray(config.panels)
+    ? (config.panels as SqlPanel[])
+    : [];
+  const columns = clampDashboardColumns(config.columns);
+  const groups = buildDashboardPanelGroups(panels, columns);
+  const panelOrder = getPanelOrder(config);
+  let visibleRowNumber = 1;
+
+  return {
+    panelCount: panelOrder.length,
+    panelOrder,
+    firstPanelIds: panelOrder.slice(0, 10),
+    groups: groups.map((group) => ({
+      key: group.key,
+      sectionId: group.section?.id ?? null,
+      sectionTitle: group.section?.title ?? null,
+      columns: group.columns,
+      rows: group.rows.map((row, rowIndex) => {
+        const rowNumber = visibleRowNumber++;
+        return {
+          rowNumber,
+          rowIndex,
+          panelIds: row.panels.map((panel) => panel.id),
+        };
+      }),
+    })),
+  };
+}
+
+function panelSummaries(config: Record<string, unknown>) {
+  const panels = Array.isArray(config.panels)
+    ? (config.panels as Array<Record<string, unknown>>)
+    : [];
+  return panels.map((panel, index) => {
+    const panelConfig =
+      panel.config &&
+      typeof panel.config === "object" &&
+      !Array.isArray(panel.config)
+        ? (panel.config as Record<string, unknown>)
+        : {};
+    return {
+      index,
+      id: typeof panel.id === "string" ? panel.id : "",
+      title: typeof panel.title === "string" ? panel.title : "",
+      chartType: typeof panel.chartType === "string" ? panel.chartType : "",
+      source: typeof panel.source === "string" ? panel.source : undefined,
+      width: typeof panel.width === "number" ? panel.width : undefined,
+      columns: typeof panel.columns === "number" ? panel.columns : undefined,
+      tab: typeof panel.tab === "string" ? panel.tab : undefined,
+      description:
+        typeof panelConfig.description === "string"
+          ? panelConfig.description
+          : undefined,
+    };
+  });
+}
+
+export function buildDashboardAgentContext(
+  dashboard: DashboardRecord,
+  options: { includeConfig?: boolean } = {},
+): Record<string, unknown> {
+  const config = dashboard.config as Record<string, unknown>;
+  const base = {
+    resourceType: "analytics-dashboard",
+    id: dashboard.id,
+    kind: dashboard.kind,
+    name: typeof config.name === "string" ? config.name : dashboard.title,
+    title: dashboard.title,
+    description:
+      typeof config.description === "string" ? config.description : undefined,
+    filters: config.filters,
+    variables: config.variables,
+    columns: config.columns,
+    panels: panelSummaries(config),
+    layout: dashboardLayoutSummary(config),
+    ownerEmail: dashboard.ownerEmail,
+    orgId: dashboard.orgId,
+    visibility: dashboard.visibility,
+    role: dashboard.role,
+    canEdit: dashboard.canEdit,
+    canManage: dashboard.canManage,
+    archivedAt: dashboard.archivedAt,
+    hiddenAt: dashboard.hiddenAt,
+    hiddenBy: dashboard.hiddenBy,
+    createdAt: dashboard.createdAt,
+    updatedAt: dashboard.updatedAt,
+    url: `/dashboards/${dashboard.id}`,
+  };
+  return options.includeConfig === false ? base : { ...base, ...config };
+}
+
+export function buildDashboardSeedAgentContext(
+  id: string,
+  seed: Record<string, unknown>,
+  options: { includeConfig?: boolean } = {},
+): Record<string, unknown> {
+  const base = {
+    resourceType: "analytics-dashboard",
+    id,
+    kind: "sql",
+    name: typeof seed.name === "string" ? seed.name : id,
+    title: typeof seed.name === "string" ? seed.name : id,
+    description:
+      typeof seed.description === "string" ? seed.description : undefined,
+    filters: seed.filters,
+    variables: seed.variables,
+    columns: seed.columns,
+    panels: panelSummaries(seed),
+    layout: dashboardLayoutSummary(seed),
+    ownerEmail: null,
+    orgId: null,
+    visibility: "org",
+    archivedAt: null,
+    hiddenAt: null,
+    hiddenBy: null,
+    url: `/dashboards/${id}`,
+  };
+  return options.includeConfig === false ? base : { ...base, ...seed };
+}
+
+export function buildAnalysisAgentContext(
+  analysis: AnalysisRecord,
+): Record<string, unknown> {
+  return {
+    resourceType: "analytics-analysis",
+    id: analysis.id,
+    name: analysis.name,
+    description: analysis.description,
+    question: analysis.question,
+    instructions: analysis.instructions,
+    dataSources: analysis.dataSources,
+    resultMarkdown: analysis.resultMarkdown,
+    resultData: analysis.resultData,
+    author: analysis.author,
+    createdAt: analysis.createdAt,
+    updatedAt: analysis.updatedAt,
+    ownerEmail: analysis.ownerEmail,
+    orgId: analysis.orgId,
+    visibility: analysis.visibility,
+    role: analysis.role,
+    canEdit: analysis.canEdit,
+    canManage: analysis.canManage,
+    hiddenAt: analysis.hiddenAt,
+    hiddenBy: analysis.hiddenBy,
+    url: `/analyses/${analysis.id}`,
+  };
+}

package/corpus/templates/analytics/server/routes/[...page].get.ts

@@ -1,4 +1,9 @@
+import { AGENT_ACCESS_PARAM } from "@agent-native/core/server";
 import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
+import {
+  buildAgentReadableResourceDiscovery,
+  renderAgentReadableResourceDiscoveryScript,
+} from "@agent-native/core/shared";
 import {
   defineEventHandler,
   getQuery,
@@ -6,6 +11,10 @@ import {
   setResponseHeader,
 } from "h3";
 
+import {
+  ANALYTICS_ANALYSIS_AGENT_CONTEXT_ENDPOINT,
+  ANALYTICS_DASHBOARD_AGENT_CONTEXT_ENDPOINT,
+} from "../../shared/resource-agent-access.js";
 import {
   buildSessionReplayAgentContext,
   safeJsonForHtml,
@@ -43,36 +52,92 @@ function sessionRecordingIdFromPath(pathname: string): string | null {
   }
 }
 
+function analyticsResourceFromPath(
+  pathname: string,
+): { type: "dashboard" | "analysis"; id: string } | null {
+  const stripped = stripAppBasePath(pathname);
+  const dashboard = stripped.match(/^\/dashboards\/([^/]+)\/?$/);
+  const analysis = stripped.match(/^\/analyses\/([^/]+)\/?$/);
+  const type = dashboard ? "dashboard" : analysis ? "analysis" : null;
+  const rawId = dashboard?.[1] ?? analysis?.[1];
+  if (!type || !rawId) return null;
+  try {
+    return { type, id: decodeURIComponent(rawId) };
+  } catch {
+    return { type, id: rawId };
+  }
+}
+
 function queryString(value: unknown): string {
   if (typeof value === "string") return value;
   if (Array.isArray(value) && typeof value[0] === "string") return value[0];
   return "";
 }
 
-async function buildAgentDiscoveryScript(event: any): Promise<string | null> {
+interface AgentDiscoveryInjection {
+  script: string;
+  privateResponse: boolean;
+}
+
+async function buildAgentDiscoveryScript(
+  event: any,
+): Promise<AgentDiscoveryInjection | null> {
   const requestUrl = getRequestURL(event);
   const recordingId = sessionRecordingIdFromPath(requestUrl.pathname);
-  if (!recordingId) return null;
-
   const query = getQuery(event);
-  const token = queryString(query[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
-  if (!token) return null;
-
-  const context = await buildSessionReplayAgentContext({
-    recordingId,
-    token,
-    origin: requestUrl.origin,
-    includeTimeline: false,
-  }).catch(() => null);
-  if (!context) return null;
-
-  return `<script type="application/agent-native+json" id="analytics-session-replay-agent-context">${safeJsonForHtml(
-    context,
-  )}</script>`;
+  if (recordingId) {
+    const token = queryString(query[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
+    if (!token) return null;
+
+    const context = await buildSessionReplayAgentContext({
+      recordingId,
+      token,
+      origin: requestUrl.origin,
+      includeTimeline: false,
+    }).catch(() => null);
+    if (!context) return null;
+
+    return {
+      script: `<script type="application/agent-native+json" id="analytics-session-replay-agent-context">${safeJsonForHtml(
+        context,
+      )}</script>`,
+      privateResponse: true,
+    };
+  }
+
+  const resource = analyticsResourceFromPath(requestUrl.pathname);
+  if (!resource) return null;
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const isDashboard = resource.type === "dashboard";
+  return {
+    script: renderAgentReadableResourceDiscoveryScript(
+      buildAgentReadableResourceDiscovery({
+        resourceType: isDashboard ? "dashboard" : "analysis",
+        resourceId: resource.id,
+        path: `/${isDashboard ? "dashboards" : "analyses"}/${encodeURIComponent(resource.id)}`,
+        contextEndpoint: isDashboard
+          ? ANALYTICS_DASHBOARD_AGENT_CONTEXT_ENDPOINT
+          : ANALYTICS_ANALYSIS_AGENT_CONTEXT_ENDPOINT,
+        origin: requestUrl.origin,
+        basePath: configuredAppBasePath(),
+        token,
+        instructions:
+          "Use contextUrl to read this Analytics artifact as structured JSON. Token links are read-only and do not grant edit access.",
+      }),
+      {
+        id: isDashboard
+          ? "analytics-dashboard-agent-context"
+          : "analytics-analysis-agent-context",
+      },
+    ),
+    privateResponse: Boolean(token),
+  };
 }
 
 function injectAgentDiscovery(html: string, script: string): string {
-  if (html.includes('id="analytics-session-replay-agent-context"')) {
+  const scriptId = script.match(/\sid="([^"]+)"/)?.[1];
+  if (scriptId && html.includes(`id="${scriptId}"`)) {
     return html;
   }
   if (html.includes("</head>")) {
@@ -86,8 +151,8 @@ function injectAgentDiscovery(html: string, script: string): string {
 
 export default defineEventHandler(async (event) => {
   const response = (await ssrHandler(event)) as Response;
-  const script = await buildAgentDiscoveryScript(event);
-  if (!script) return response;
+  const discovery = await buildAgentDiscoveryScript(event);
+  if (!discovery) return response;
 
   const contentType = response.headers.get("content-type") ?? "";
   if (!contentType.includes("text/html")) return response;
@@ -95,12 +160,14 @@ export default defineEventHandler(async (event) => {
   const html = await response.text();
   const headers = new Headers(response.headers);
   headers.delete("content-length");
-  headers.set("Cache-Control", "private, max-age=0, no-store");
-  headers.set("Referrer-Policy", "no-referrer");
-  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
-  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  if (discovery.privateResponse) {
+    headers.set("Cache-Control", "private, max-age=0, no-store");
+    headers.set("Referrer-Policy", "no-referrer");
+    setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+    setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  }
 
-  return new Response(injectAgentDiscovery(html, script), {
+  return new Response(injectAgentDiscovery(html, discovery.script), {
     status: response.status,
     statusText: response.statusText,
     headers,

package/corpus/templates/analytics/server/routes/api/analysis-agent-context.json.get.ts

@@ -0,0 +1,94 @@
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { ANALYTICS_ANALYSIS_AGENT_RESOURCE_KIND } from "../../../shared/resource-agent-access.js";
+import { getDb, schema } from "../../db/index.js";
+import { buildAnalysisAgentContext } from "../../lib/agent-readable-resource-context.js";
+import type { AnalysisRecord } from "../../lib/dashboards-store.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (typeof value !== "string") return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function rowToAnalysis(row: any): AnalysisRecord {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    question: row.question,
+    instructions: row.instructions,
+    dataSources: parseJson<string[]>(row.dataSources, []),
+    resultMarkdown: row.resultMarkdown,
+    resultData: row.resultData
+      ? parseJson<Record<string, unknown> | null>(row.resultData, null)
+      : null,
+    author: row.author ?? null,
+    ownerEmail: row.ownerEmail,
+    orgId: row.orgId ?? null,
+    visibility: row.visibility,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    hiddenAt: row.hiddenAt ?? null,
+    hiddenBy: row.hiddenBy ?? null,
+  };
+}
+
+export default defineEventHandler(async (event) => {
+  setResponseHeader(event, "Cache-Control", "no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  if (!id) {
+    setResponseStatus(event, 400);
+    return { error: "Analysis id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const db = getDb() as any;
+  // guard:allow-unscoped -- this endpoint returns analysis context only when the analysis is public or an analysis-scoped agent_access token verifies for this id.
+  const [row] = await db
+    .select()
+    .from(schema.analyses)
+    .where(eq(schema.analyses.id, id))
+    .limit(1);
+
+  if (!row) {
+    setResponseStatus(event, 404);
+    return { error: "Analysis not found" };
+  }
+
+  const tokenAccess = token
+    ? verifyScopedAgentAccessToken(token, {
+        resourceKind: ANALYTICS_ANALYSIS_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  if (row.visibility !== "public" && !tokenAccess) {
+    setResponseStatus(event, 403);
+    return { error: "Invalid or expired agent access token" };
+  }
+
+  return buildAnalysisAgentContext(rowToAnalysis(row));
+});

package/corpus/templates/analytics/server/routes/api/dashboard-agent-context.json.get.ts

@@ -0,0 +1,109 @@
+import {
+  AGENT_ACCESS_PARAM,
+  verifyScopedAgentAccessToken,
+} from "@agent-native/core/server";
+import { eq } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import { ANALYTICS_DASHBOARD_AGENT_RESOURCE_KIND } from "../../../shared/resource-agent-access.js";
+import { getDb, schema } from "../../db/index.js";
+import {
+  buildDashboardAgentContext,
+  buildDashboardSeedAgentContext,
+} from "../../lib/agent-readable-resource-context.js";
+import { loadDashboardSeed } from "../../lib/dashboard-seeds.js";
+import type { DashboardRecord } from "../../lib/dashboards-store.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function parseJsonObject(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function rowToDashboard(row: any): DashboardRecord {
+  return {
+    id: row.id,
+    kind: row.kind,
+    title: row.title,
+    config: parseJsonObject(row.config),
+    ownerEmail: row.ownerEmail,
+    orgId: row.orgId ?? null,
+    visibility: row.visibility,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    archivedAt: row.archivedAt ?? null,
+    hiddenAt: row.hiddenAt ?? null,
+    hiddenBy: row.hiddenBy ?? null,
+  };
+}
+
+export default defineEventHandler(async (event) => {
+  setResponseHeader(event, "Cache-Control", "no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  if (!id) {
+    setResponseStatus(event, 400);
+    return { error: "Dashboard id is required" };
+  }
+
+  const token = queryString(query[AGENT_ACCESS_PARAM]);
+  const tokenAccess = token
+    ? verifyScopedAgentAccessToken(token, {
+        resourceKind: ANALYTICS_DASHBOARD_AGENT_RESOURCE_KIND,
+        resourceId: id,
+      }).ok
+    : false;
+  const db = getDb() as any;
+  // guard:allow-unscoped -- this endpoint returns dashboard context only when the dashboard is public or a dashboard-scoped agent_access token verifies for this id.
+  const [row] = await db
+    .select()
+    .from(schema.dashboards)
+    .where(eq(schema.dashboards.id, id))
+    .limit(1);
+
+  const seed = row ? null : loadDashboardSeed(id);
+  if (!row && seed) {
+    if (!tokenAccess) {
+      setResponseStatus(event, 403);
+      return { error: "Invalid or expired agent access token" };
+    }
+    return buildDashboardSeedAgentContext(id, seed, { includeConfig: true });
+  }
+
+  if (!row) {
+    setResponseStatus(event, 404);
+    return { error: "Dashboard not found" };
+  }
+
+  if (row.visibility !== "public" && !tokenAccess) {
+    setResponseStatus(event, 403);
+    return { error: "Invalid or expired agent access token" };
+  }
+
+  return buildDashboardAgentContext(rowToDashboard(row), {
+    includeConfig: true,
+  });
+});