fix: protocol for dashboard

Author: manfredsteyer

ai-server/src/mastra/dashboard-dsl/compile-dashboard.ts

@@ -27,10 +27,23 @@ type Component = Record<string, unknown> & {
   component: string;
 };
 
+/**
+ * Record of a single data-fetch step the compiler ran while assembling
+ * the dashboard. The route surfaces these as synthetic AG-UI tool-call
+ * events so the user keeps the same "tool calls" visibility they had
+ * before the DSL refactor (where every call originated from the LLM).
+ */
+export interface DataStep {
+  name: string;
+  args: unknown;
+  result?: unknown;
+}
+
 export interface CompiledDashboard {
   surfaceId: string;
   structural: A2uiMessage[];
   dataModel: A2uiMessage[];
+  dataSteps: DataStep[];
 }
 
 interface DashboardData {
@@ -56,12 +69,14 @@ export async function compileDashboard(
   spec: DashboardSpec,
   options: { surfaceId?: string } = {},
 ): Promise<CompiledDashboard> {
-  const data = await fetchAllDashboardData(spec);
-  return assembleDashboard(spec, data, options.surfaceId);
+  const dataSteps: DataStep[] = [];
+  const data = await fetchAllDashboardData(spec, dataSteps);
+  return assembleDashboard(spec, data, options.surfaceId, dataSteps);
 }
 
 async function fetchAllDashboardData(
   spec: DashboardSpec,
+  dataSteps: DataStep[],
 ): Promise<DashboardData> {
   const routes = new Set<string>();
   let needsBookedFlights = false;
@@ -88,6 +103,19 @@ async function fetchAllDashboardData(
   }
 
   const routeList = [...routes];
+  const flightStepIndices: number[] = [];
+  for (const key of routeList) {
+    const [from, to] = key.split('|');
+    flightStepIndices.push(
+      dataSteps.push({ name: 'searchFlights', args: { from, to } }) - 1,
+    );
+  }
+  let findBookedStepIdx: number | null = null;
+  if (needsBookedFlights) {
+    findBookedStepIdx =
+      dataSteps.push({ name: 'findBookedFlights', args: {} }) - 1;
+  }
+
   const [bookedFlights, ...flightLists] = await Promise.all([
     needsBookedFlights ? getBookedFlights() : Promise.resolve([]),
     ...routeList.map((key) => {
@@ -96,6 +124,13 @@ async function fetchAllDashboardData(
     }),
   ]);
 
+  flightStepIndices.forEach((stepIdx, i) => {
+    dataSteps[stepIdx].result = { count: flightLists[i]?.length ?? 0 };
+  });
+  if (findBookedStepIdx !== null) {
+    dataSteps[findBookedStepIdx].result = { count: bookedFlights.length };
+  }
+
   const flightsByRoute = new Map<string, FlightRecord[]>();
   routeList.forEach((key, idx) => {
     flightsByRoute.set(key, flightLists[idx] ?? []);
@@ -108,6 +143,7 @@ function assembleDashboard(
   spec: DashboardSpec,
   data: DashboardData,
   givenSurfaceId: string | undefined,
+  dataSteps: DataStep[],
 ): CompiledDashboard {
   const surfaceId = givenSurfaceId ?? `dash-${randomUUID()}`;
 
@@ -116,7 +152,7 @@ function assembleDashboard(
   const rootChildren: string[] = [];
 
   spec.tiles.forEach((tile, idx) => {
-    const result = buildTile(idx, tile, data, surfaceId);
+    const result = buildTile(idx, tile, data, surfaceId, dataSteps);
     rootChildren.push(...result.rootChildren);
     allComponents.push(...result.components);
     allDataOps.push(...result.dataOps);
@@ -140,36 +176,37 @@ function assembleDashboard(
     } as unknown as A2uiMessage,
   ];
 
-  return { surfaceId, structural, dataModel: allDataOps };
+  return { surfaceId, structural, dataModel: allDataOps, dataSteps };
 }
 
 function buildTile(
   idx: number,
   tile: DashboardTile,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   switch (tile.type) {
     case 'flightsTable':
       return buildFlightsTable(idx, tile, data, surfaceId, false);
     case 'delayedFlightsTable':
       return buildFlightsTable(idx, tile, data, surfaceId, true);
     case 'delayShareChart':
-      return buildDelayShareChart(idx, tile, data, surfaceId);
+      return buildDelayShareChart(idx, tile, data, surfaceId, dataSteps);
     case 'delaysPerDayChart':
-      return buildDelaysPerDayChart(idx, tile, data, surfaceId);
+      return buildDelaysPerDayChart(idx, tile, data, surfaceId, dataSteps);
     case 'boardingPasses':
       return buildBoardingPasses(idx, tile, data, surfaceId);
     case 'bookedFlightsList':
-      return buildBookedFlightsList(idx, data, surfaceId);
+      return buildBookedFlightsList(idx, data, surfaceId, dataSteps);
     case 'flightSearch':
       return buildFlightSearch(idx, tile, surfaceId);
     case 'rentalCars':
-      return buildRentalCars(idx, tile, data, surfaceId);
+      return buildRentalCars(idx, tile, data, surfaceId, dataSteps);
     case 'hotels':
-      return buildHotels(idx, tile, data, surfaceId);
+      return buildHotels(idx, tile, data, surfaceId, dataSteps);
     case 'weatherList':
-      return buildWeatherList(idx, data, surfaceId);
+      return buildWeatherList(idx, data, surfaceId, dataSteps);
   }
 }
 
@@ -294,6 +331,7 @@ function buildDelayShareChart(
   tile: Extract<DashboardTile, { type: 'delayShareChart' }>,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const flights = data.flightsByRoute.get(routeKey(tile.from, tile.to)) ?? [];
   let onTime = 0;
@@ -302,12 +340,23 @@ function buildDelayShareChart(
     if (f.delay > 0) delayed += 1;
     else onTime += 1;
   }
+  const chartType = tile.chartType ?? 'pie';
   const url = buildAndCacheChartUrl({
-    type: tile.chartType ?? 'pie',
+    type: chartType,
     title: `On-time vs. delayed (${tile.from} → ${tile.to})`,
     labels: ['On time', 'Delayed'],
     datasets: [{ label: 'Flights', data: [onTime, delayed] }],
   });
+  dataSteps.push({
+    name: 'renderFlightChart',
+    args: {
+      from: tile.from,
+      to: tile.to,
+      type: 'delayShare',
+      chartType,
+    },
+    result: { onTime, delayed, total: onTime + delayed, url },
+  });
   return chartTile(
     idx,
     surfaceId,
@@ -321,6 +370,7 @@ function buildDelaysPerDayChart(
   tile: Extract<DashboardTile, { type: 'delaysPerDayChart' }>,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const flights = data.flightsByRoute.get(routeKey(tile.from, tile.to)) ?? [];
   const buckets = new Map<string, { onTime: number; delayed: number }>();
@@ -343,6 +393,16 @@ function buildDelaysPerDayChart(
       { label: 'Delayed', data: sortedDays.map(([, v]) => v.delayed) },
     ],
   });
+  dataSteps.push({
+    name: 'renderFlightChart',
+    args: {
+      from: tile.from,
+      to: tile.to,
+      type: 'delaysPerDay',
+      chartType: 'bar',
+    },
+    result: { days: sortedDays.length, url },
+  });
   return chartTile(
     idx,
     surfaceId,
@@ -426,6 +486,7 @@ function buildBookedFlightsList(
   idx: number,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const flights = data.bookedFlights;
   const cardId = tileId(idx, 'card');
@@ -511,6 +572,11 @@ function buildBookedFlightsList(
     );
 
     const w = weatherForecast(flight.to, flight.date);
+    dataSteps.push({
+      name: 'weatherForecast',
+      args: { city: flight.to, date: flight.date.slice(0, 10) },
+      result: { condition: w.condition, temperatureC: w.temperatureC },
+    });
     const meta = `${flight.date.slice(0, 10)} · ${weatherIconFor(w.condition)} ${w.condition} — ${w.temperatureC} °C · ${
       flight.delay > 0 ? `Delayed by ${flight.delay} min` : 'On time'
     }`;
@@ -610,9 +676,15 @@ function buildRentalCars(
   tile: Extract<DashboardTile, { type: 'rentalCars' }>,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const city = tile.city ?? data.bookedFlights[0]?.to ?? FALLBACK_CITY;
   const result = searchRentalCars(city);
+  dataSteps.push({
+    name: 'searchRentalCars',
+    args: { city },
+    result: { count: result.cars.length },
+  });
   return imageRowList({
     idx,
     surfaceId,
@@ -630,9 +702,15 @@ function buildHotels(
   tile: Extract<DashboardTile, { type: 'hotels' }>,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const city = tile.city ?? data.bookedFlights[0]?.to ?? FALLBACK_CITY;
   const result = searchHotels(city);
+  dataSteps.push({
+    name: 'searchHotels',
+    args: { city },
+    result: { count: result.hotels.length },
+  });
   return imageRowList({
     idx,
     surfaceId,
@@ -649,6 +727,7 @@ function buildWeatherList(
   idx: number,
   data: DashboardData,
   surfaceId: string,
+  dataSteps: DataStep[],
 ): TileBuildResult {
   const flights = data.bookedFlights;
   const cardId = tileId(idx, 'card');
@@ -694,6 +773,11 @@ function buildWeatherList(
       variant: 'body',
     });
     const w = weatherForecast(flight.to, flight.date);
+    dataSteps.push({
+      name: 'weatherForecast',
+      args: { city: flight.to, date: flight.date.slice(0, 10) },
+      result: { condition: w.condition, temperatureC: w.temperatureC },
+    });
     const line = `${flight.to} · ${flight.date.slice(0, 10)} · ${weatherIconFor(w.condition)} ${w.condition} — ${w.temperatureC} °C`;
     dataOps.push(dataOp(surfaceId, path, line));
   });

ai-server/src/mastra/dashboard-dsl/spec-channel.ts

@@ -1,43 +1,52 @@
+import type { DataStep } from './compile-dashboard.js';
 import type { DashboardSpec } from './dashboard-spec.js';
 
-// Module-scoped relay used to ferry the parsed `DashboardSpec` from
-// `renderDashboardTool.execute` (called by Mastra during a streamed run)
-// to the route handler that owns the cache. Mastra's tool result event
-// only carries the surface id + A2UI messages, so we cannot read the
-// spec back via the AG-UI snapshot pipeline. A short-lived in-memory
-// map keyed by surface id is the smallest viable side channel.
+// Module-scoped relay used to ferry the parsed `DashboardSpec` and the
+// list of compiler data steps from `renderDashboardTool.execute` to the
+// route handler. Mastra's tool result event only carries the surface id
+// + A2UI messages, so we cannot read these back via the AG-UI snapshot
+// pipeline. A short-lived in-memory map keyed by surface id is the
+// smallest viable side channel.
 //
-// Entries are removed by `consumeRecordedSpec` after the route reads
-// them, with a cleanup timer for safety in case the route fails before
-// reading.
+// Entries are removed by the consume helpers after the route reads
+// them; the cleanup timer is a safety net for runs that fail before
+// reaching the consume call.
 
 const TTL_MS = 60_000;
 
-const recordedSpecs = new Map<string, DashboardSpec>();
+interface RecordedRun {
+  spec: DashboardSpec;
+  dataSteps: readonly DataStep[];
+}
+
+const recordedRuns = new Map<string, RecordedRun>();
 const expirationTimers = new Map<string, NodeJS.Timeout>();
 
-export function recordDashboardSpec(
+export function recordDashboardRun(
   surfaceId: string,
   spec: DashboardSpec,
+  dataSteps: readonly DataStep[],
 ): void {
-  recordedSpecs.set(surfaceId, spec);
+  recordedRuns.set(surfaceId, { spec, dataSteps });
   clearExpiration(surfaceId);
   expirationTimers.set(
     surfaceId,
     setTimeout(() => {
-      recordedSpecs.delete(surfaceId);
+      recordedRuns.delete(surfaceId);
       expirationTimers.delete(surfaceId);
     }, TTL_MS),
   );
 }
 
-export function consumeRecordedSpec(
-  surfaceId: string,
-): DashboardSpec | undefined {
-  const spec = recordedSpecs.get(surfaceId);
-  recordedSpecs.delete(surfaceId);
+export function peekRecordedRun(surfaceId: string): RecordedRun | undefined {
+  return recordedRuns.get(surfaceId);
+}
+
+export function consumeRecordedRun(surfaceId: string): RecordedRun | undefined {
+  const run = recordedRuns.get(surfaceId);
+  recordedRuns.delete(surfaceId);
   clearExpiration(surfaceId);
-  return spec;
+  return run;
 }
 
 function clearExpiration(surfaceId: string): void {

ai-server/src/mastra/routes/ag-ui-stream.ts

@@ -17,6 +17,18 @@ export interface CreateAgUiEventStreamOptions {
    * full operation list.
    */
   transformA2uiOperations?: (operations: unknown[]) => unknown[];
+  /**
+   * Hook fired right before an `a2ui-surface` `ACTIVITY_SNAPSHOT` is
+   * forwarded. Returned events are written to the SSE stream first, in
+   * the order returned, then the snapshot itself. Used by the dashboard
+   * route to surface the compiler's data fetches as synthetic AG-UI
+   * tool-call events so the user retains the same "tool calls" insight
+   * they had before the DSL refactor (when each fetch was an individual
+   * LLM tool call).
+   */
+  injectBeforeA2uiSurface?: (
+    operations: readonly unknown[],
+  ) => readonly BaseEvent[];
 }
 
 export type ParseRunAgentInputResult =
@@ -80,6 +92,12 @@ export async function streamAgentEvents(
           event,
           options.transformA2uiOperations,
         );
+        const ops = readA2uiSurfaceOperations(transformed);
+        if (ops && options.injectBeforeA2uiSurface) {
+          for (const injected of options.injectBeforeA2uiSurface(ops)) {
+            enqueueEvent(injected);
+          }
+        }
         tryCaptureA2uiSurface(transformed, options.onA2uiSurface);
         enqueueEvent(transformed);
       },