@dbx-tools/shared-mastra 0.1.9

package/README.md

@@ -0,0 +1,117 @@
+# @dbx-tools/shared-mastra
+
+Browser-safe contract for the AppKit Mastra plugin.
+
+Import this package when a client, test, or server route needs the same route
+constants, header names, embed-marker parsing, feedback schemas, thread
+selection fields, and Mastra response schemas used by
+[`@dbx-tools/node-appkit-mastra`](../../node/appkit-mastra).
+
+Key features:
+
+- Route constants for the AppKit-Mastra client surface, including history,
+  threads, suggestions, model lists, embeds, and feedback.
+- Header/query/body constants for thread selection and model override requests.
+- Embed-marker parsing for delayed chart and statement-data payloads in
+  streaming assistant text.
+- Zod schemas for plugin-published client config and route responses.
+- MLflow feedback request/response schemas and trace-header constants.
+- Browser-safe types that let UI packages stay aligned with the server without
+  importing Node or Mastra runtime code.
+
+## Parse Client Configuration
+
+```ts
+import { wire } from "@dbx-tools/shared-mastra";
+
+const config = wire.MastraClientConfigSchema.parse(await response.json());
+```
+
+`wire.MastraClientConfigSchema` describes the plugin-published client config:
+mount path, default agent, feedback enablement, and MCP route details. Use it to
+bootstrap a UI without hard-coding server paths.
+
+## Use Route Constants
+
+```ts
+import { routes } from "@dbx-tools/shared-mastra";
+
+const historyUrl = `${basePath}${routes.MASTRA_ROUTES.history}`;
+const threadsUrl = `${basePath}${routes.MASTRA_ROUTES.threads}`;
+```
+
+`routes.MASTRA_ROUTES` keeps client fetch calls aligned with plugin route names
+for history, threads, models, suggestions, feedback, and embeds.
+
+## Select Threads And Models
+
+```ts
+import { override, thread } from "@dbx-tools/shared-mastra";
+
+await fetch(chatUrl, {
+  method: "POST",
+  headers: {
+    [thread.THREAD_ID_HEADER]: activeThreadId,
+    [override.MODEL_OVERRIDE_HEADER]: "claude sonnet",
+  },
+  body: JSON.stringify({ messages }),
+});
+```
+
+Use the header/query constants instead of string literals so browser code,
+server middleware, and tests agree on how a request selects the active
+conversation and model.
+
+## Parse Embed Markers
+
+```ts
+import { marker } from "@dbx-tools/shared-mastra";
+
+const parts = marker.parseMarkers("Here is the chart:\n[chart:abc123]");
+const safeText = marker.stripIncompleteMarkerTail(streamingText);
+```
+
+Markers let an agent mention large or delayed artifacts by id, such as
+`[chart:<id>]` and `[data:<statement_id>]`. The parser is useful for rendering
+assistant text while a stream is still arriving.
+
+## Validate Feedback
+
+```ts
+import { feedback } from "@dbx-tools/shared-mastra";
+
+const body = feedback.MastraFeedbackRequestSchema.parse({
+  traceId: "tr-abc",
+  value: true,
+  comment: "Helpful",
+});
+```
+
+Feedback constants include the MLflow trace header and default assessment names.
+The schemas validate thumbs/comment payloads before they are sent to the plugin.
+
+## Validate Plugin Responses
+
+```ts
+const threads = wire.MastraThreadsResponseSchema.parse(await res.json());
+const chart = wire.ChartSchema.parse(await chartRes.json());
+const event = wire.GenieWriterEventSchema.parse(writerPayload);
+```
+
+The `wire` module contains response schemas for history, threads, suggestions,
+model lists, charts, statement data, and Genie writer events. It also defines the
+chart/data result shapes consumed by embed renderers.
+
+## Modules
+
+- `wire` - zod schemas and types for client config, history, threads, model
+  lists, suggestions, charts, statement data, and writer events.
+- `routes` - plugin route segment constants.
+- `marker` - embed-marker parsing and incomplete-tail stripping.
+- `feedback` - MLflow feedback headers, assessment names, request/response
+  schemas.
+- `override` - model override header/query/body constants.
+- `thread` - thread id header/query constants.
+
+Server-side implementation is in
+[`@dbx-tools/node-appkit-mastra`](../../node/appkit-mastra).

package/index.ts

@@ -0,0 +1,13 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as feedback from "./src/feedback";
+export * as marker from "./src/marker";
+export * as override from "./src/override";
+export * as routes from "./src/routes";
+export * as thread from "./src/thread";
+export * as wire from "./src/wire";
+export type { MastraFeedbackValue, MastraFeedbackRequest, MastraFeedbackResponse } from "./src/feedback";
+export type { MarkerType, ParsedMarker } from "./src/marker";
+export type { MastraClientConfig, ServingEndpointsResponse, MastraHistoryUIMessage, MastraHistoryResponse, MastraClearHistoryResponse, MastraThread, MastraThreadsResponse, MastraDeleteThreadResponse, MastraUpdateThreadRequest, MastraUpdateThreadResponse, MastraSuggestionsResponse, ChartType, ChartResult, Chart, StatementData, MastraWriter, StartedEvent, AskGenieDoneEvent, MastraGenieErrorEvent, SummaryEvent, GenieAgentEvent, GenieWriterEvent, GenieWriterEventType, GenieDatasetData, GenieDatasetChart, GenieDataset, GenieSummaryItem, GenieSummaryItemType, GenieAgentResult } from "./src/wire";

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dbx-tools/shared-mastra",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/shared/mastra"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/shared-genie": "0.1.9",
+    "@dbx-tools/shared-model": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/feedback.ts

@@ -0,0 +1,84 @@
+/**
+ * Wire-format contract for the Mastra plugin's user-feedback surface:
+ * the response header that carries a turn's MLflow trace id back to the
+ * browser, plus the request / response schemas for the feedback route
+ * (`MASTRA_ROUTES.feedback`).
+ *
+ * Feedback is logged to MLflow as a trace *assessment* (thumbs up/down
+ * as a boolean, or a freeform comment as text), so it must be tied to a
+ * trace. The plugin stamps the active OTel trace id of each turn on the
+ * response as {@link MLFLOW_TRACE_ID_HEADER} (`tr-<hex>`); the client
+ * captures it per assistant message and sends it back here when the
+ * user reacts. Kept dependency-free so both the browser client and the
+ * server plugin share one definition.
+ */
+
+import { z } from "zod";
+
+/**
+ * Response header carrying the turn's MLflow trace id (`tr-<hex>`),
+ * derived from the active OpenTelemetry trace id. Present only when
+ * MLflow logging is enabled and a trace was active for the request.
+ * The chat client reads it off the stream response and pairs it with
+ * the assistant message so a later thumbs / comment attaches to the
+ * right trace.
+ */
+export const MLFLOW_TRACE_ID_HEADER = "x-mlflow-trace-id";
+
+/** Assessment name used for thumbs feedback when the caller omits one. */
+export const DEFAULT_FEEDBACK_NAME = "user_feedback";
+
+/** Assessment name used for a freeform comment when no explicit value is sent. */
+export const DEFAULT_COMMENT_NAME = "user_comment";
+
+/**
+ * Feedback value the assessment records. Boolean for thumbs up/down,
+ * number for a rating scale, string for a short categorical label.
+ * A freeform comment travels in `comment` instead (or as the value
+ * when no thumbs value is present).
+ */
+export const MastraFeedbackValueSchema = z.union([z.boolean(), z.number(), z.string()]);
+export type MastraFeedbackValue = z.infer<typeof MastraFeedbackValueSchema>;
+
+/**
+ * Request body for `POST ${basePath}/route/feedback`.
+ *
+ * Fields:
+ *   - `traceId`: MLflow trace id the feedback attaches to (the
+ *     `tr-<hex>` value the server sent via {@link MLFLOW_TRACE_ID_HEADER}).
+ *   - `name`: assessment name. Defaults to {@link DEFAULT_FEEDBACK_NAME}
+ *     for a value, {@link DEFAULT_COMMENT_NAME} for a comment-only submit.
+ *   - `value`: the thumbs / rating value (omit for a comment-only submit).
+ *   - `comment`: freeform rationale. Logged as the assessment value when
+ *     `value` is absent, or as the rationale alongside a `value`.
+ *
+ * Refined so an empty submission (neither a value nor a non-empty
+ * comment) is rejected rather than logging a meaningless assessment.
+ */
+export const MastraFeedbackRequestSchema = z
+  .object({
+    traceId: z.string().min(1),
+    name: z.string().optional(),
+    value: MastraFeedbackValueSchema.optional(),
+    comment: z.string().optional(),
+  })
+  .refine((v) => v.value !== undefined || (v.comment?.trim().length ?? 0) > 0, {
+    message: "feedback requires a value or a non-empty comment",
+  });
+export type MastraFeedbackRequest = z.infer<typeof MastraFeedbackRequestSchema>;
+
+/**
+ * Response from `POST ${basePath}/route/feedback`.
+ *
+ * `ok` is `true` when the assessment was recorded. It can be `false`
+ * (with `ok: false`) without the call throwing - most commonly because
+ * the trace hasn't finished exporting to MLflow yet (trace export is
+ * asynchronous); the client surfaces a soft "try again" hint rather
+ * than an error. `assessmentId` is the created assessment's id on
+ * success.
+ */
+export const MastraFeedbackResponseSchema = z.object({
+  ok: z.boolean(),
+  assessmentId: z.string().optional(),
+});
+export type MastraFeedbackResponse = z.infer<typeof MastraFeedbackResponseSchema>;

package/src/marker.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent-prose embed marker grammar.
+ *
+ * The Mastra agent is instructed to defer visualizations to the host
+ * UI by embedding markers in its markdown reply; the UI parses them
+ * out and swaps in the matching slot. This module is the single
+ * source of truth for that grammar so every consumer parses markers
+ * the same way and can't drift from the shapes documented on
+ * {@link ChartSchema} / {@link StatementDataSchema} in `protocol.ts`
+ * and the instructions the server hands the model.
+ *
+ * One grammar, open-ended type. A marker is `[<type>:<id>]`. The
+ * `<type>` is an opaque token that names the embed kind; the host
+ * resolves it against the generic `/embed/<type>/<id>` route, which
+ * 404s any type the server doesn't register. The grammar does NOT
+ * hard-code the known types - new embed kinds work end to end
+ * without touching this regex. Today the server registers:
+ *
+ *   - `[chart:<chartId>]` - the `<chartId>` is a v4 UUID minted by
+ *     the chart subsystem (`prepare_chart` / `render_data`) and
+ *     resolves to a cached Echarts spec.
+ *   - `[data:<statementId>]` - the `<statementId>` is a Databricks
+ *     statement id (a time-ordered UUID) and resolves to the
+ *     statement's rows.
+ *
+ * The `<id>` of a real embed is UUID-shaped (`8-4-4-4-12` hex): both
+ * id kinds above are UUIDs, just different versions (chart = v4,
+ * statement = v7-style). The grammar deliberately captures ANY
+ * non-bracket id token, not just UUID-shaped ones, so a fabricated
+ * marker the model glued together from a label
+ * (e.g. `[chart:placeholder]` or
+ * `[chart:01f163b6-1eac-region-fill-oos]`) still parses as a marker.
+ * Matching it - rather than letting the broad regex miss it - is what
+ * lets the host UI consume and obscure the bogus marker instead of
+ * leaking the literal `[chart:...]` text into the rendered prose.
+ * Whether an id is a genuine embed is a separate {@link isUuid}
+ * check the caller runs on {@link ParsedMarker.id}.
+ *
+ * Parse everything through {@link parseMarkers}, validate the id with
+ * {@link isUuid}, and branch on the returned {@link ParsedMarker.type}.
+ */
+
+/**
+ * The embed kind named by a marker's `<type>` segment. Left as an
+ * open `string` (not a closed union) so the grammar stays generic:
+ * the authoritative set of supported types lives in the server's
+ * `/embed/:type/:id` resolver registry, and an unknown type simply
+ * 404s. The two types the server ships today are `"chart"` and
+ * `"data"`.
+ */
+export type MarkerType = string;
+
+/**
+ * Single matcher for ANY embed marker, regardless of type. Matches
+ * `[<type>:<id>]`. Capture group 1 is the marker type token (e.g.
+ * `chart`, `data`); group 2 is the id - any run of non-bracket,
+ * non-whitespace characters, NOT constrained to a UUID shape.
+ *
+ * Neither the type nor the id shape is enumerated here. The type is
+ * left open because the server's resolver registry decides which
+ * types are real and 404s the rest, so a new embed kind needs no
+ * grammar change. The id is left broad on purpose: a fabricated
+ * marker the model emits from a label (e.g. `[chart:placeholder]`)
+ * MUST still match so the host UI can consume and obscure it rather
+ * than leak the literal `[chart:...]` text into the prose. The id is
+ * then validated with {@link isUuid} downstream; non-UUID ids resolve
+ * to no embed.
+ *
+ * Safe to share as a `/g` constant: it's only ever consumed via
+ * {@link String.prototype.matchAll}, which clones the regex and
+ * never advances this object's `lastIndex`. (A `.exec()`/`.test()`
+ * loop would need a fresh regex each time, but we don't do that.)
+ */
+const MARKER_RE = /\[([A-Za-z][A-Za-z0-9_-]*):([^\]\s]+)\]/g;
+
+/**
+ * UUID matcher (`8-4-4-4-12` hex, any version) anchored to the whole
+ * string. Covers v4 chart ids and time-ordered (v7-style) statement
+ * ids alike. Used by {@link isUuid} to tell a genuine embed id apart
+ * from a label the model fabricated into a marker.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Whether `id` is a UUID-shaped embed id. The marker grammar
+ * ({@link MARKER_RE}) matches any non-bracket id token so fabricated
+ * markers don't leak as literal prose; this is the guard callers run
+ * to decide whether an id is a real embed (render the slot) or a
+ * bogus label to obscure (drop the marker entirely).
+ */
+export function isUuid(id: string): boolean {
+  return UUID_RE.test(id);
+}
+
+/** One marker found in agent prose, with its source span. */
+export interface ParsedMarker {
+  /** Marker kind token (e.g. `chart`, `data`); see {@link MarkerType}. */
+  type: MarkerType;
+  /** Raw id captured from the marker (chart id or statement id). */
+  id: string;
+  /** Index of the marker's first character in the source text. */
+  start: number;
+  /** Index one past the marker's last character. */
+  end: number;
+}
+
+/**
+ * Parse every embed marker out of `text`, in source order. A single
+ * regex pass means matches never overlap, so callers can splice the
+ * spans directly without a sort/dedupe step. This is the one entry
+ * point for marker parsing: type branching runs on the returned
+ * markers. The grammar ({@link MARKER_RE}) matches any non-bracket id
+ * token, so a returned {@link ParsedMarker.id} is NOT guaranteed to
+ * be a real embed id - run it through {@link isUuid} to tell a
+ * genuine embed apart from a fabricated label, which the caller then
+ * obscures rather than rendering.
+ */
+export function parseMarkers(text: string): ParsedMarker[] {
+  const out: ParsedMarker[] = [];
+  for (const match of text.matchAll(MARKER_RE)) {
+    const start = match.index ?? 0;
+    out.push({
+      // Group 1 is the `<type>` token; the server's embed registry
+      // (not this parser) decides whether it's supported.
+      type: match[1] ?? "",
+      id: match[2] ?? "",
+      start,
+      end: start + match[0].length,
+    });
+  }
+  return out;
+}
+
+/**
+ * Strip a trailing partial marker (`[chart`, `[data:01f1`, ...) that
+ * hasn't received its closing `]` yet. While the model streams
+ * text-deltas a marker arrives across several chunks, and rendering
+ * each interim state would briefly flash the literal `[chart:abc-`
+ * prefix before the closing bracket swaps it for a slot. Hiding any
+ * trailing `[<non-whitespace-non-bracket>...` suffix keeps the prose
+ * stable until either a `]` (full marker) or whitespace (definitely
+ * not a marker) lands. Persisted transcripts never end mid-marker,
+ * so this is a no-op on reload.
+ */
+export function stripIncompleteMarkerTail(text: string): string {
+  return text.replace(/\[[^\s[\]]*$/, "");
+}

package/src/override.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-request model-override wire convention shared by the Mastra
+ * plugin server (`@dbx-tools/appkit-mastra`'s `extractModelOverride`)
+ * and the browser chat client (`@dbx-tools/appkit-mastra-ui`). Kept
+ * here so the header / query / body field names can never drift
+ * between the side that sets them and the side that reads them.
+ */
+
+/** HTTP header inspected for a per-request model override. */
+export const MODEL_OVERRIDE_HEADER = "x-mastra-model";
+
+/**
+ * HTTP header that pins a specific thread id for the request. When
+ * present, the server uses it as the conversation thread id instead of
+ * the session cookie, enabling the client to switch between stored
+ * conversations without resetting the cookie.
+ */
+export const THREAD_OVERRIDE_HEADER = "x-mastra-thread-id";
+
+/** Query string parameter inspected for a per-request model override. */
+export const MODEL_OVERRIDE_QUERY = "model";
+
+/** Body fields (in priority order) inspected for a per-request model override. */
+export const MODEL_OVERRIDE_BODY_FIELDS = ["model", "modelId"] as const;

package/src/routes.ts

@@ -0,0 +1,26 @@
+/**
+ * Route segments the Mastra plugin mounts under its `basePath`
+ * (`/api/<plugin-name>`). Shared between the server's route
+ * registration and the browser client (`MastraPluginClient` in
+ * `@dbx-tools/appkit-mastra-ui`) so a relayout - or a rename of a
+ * sub-path - is a one-line change here and the two can never drift.
+ *
+ * The agent-scoped segments (`history`, `threads`, `suggestions`) take
+ * an optional `/:agentId` suffix; the default agent uses the bare
+ * segment. Conversation streaming itself rides the standard Mastra
+ * agent routes (`@mastra/client-js`'s `getAgent(id).stream()`), so
+ * there's no chat segment here.
+ *
+ * `feedback` is the plugin-owned POST endpoint the chat UI calls to
+ * log a thumbs / comment assessment against a turn's MLflow trace (see
+ * `feedback.ts`); it is not agent-scoped (a trace id identifies the
+ * turn on its own).
+ */
+export const MASTRA_ROUTES = {
+  history: "/route/history",
+  threads: "/route/threads",
+  feedback: "/route/feedback",
+  suggestions: "/suggestions",
+  models: "/models",
+  embed: "/embed",
+} as const;

package/src/thread.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-request thread-selection wire convention shared by the Mastra
+ * plugin server (`@dbx-tools/appkit-mastra`'s thread-id resolver) and
+ * the browser chat client (`@dbx-tools/appkit-mastra-ui`).
+ *
+ * A chat client owns multiple conversations ("threads") for the same
+ * resource (the authenticated user). It names the thread a given
+ * request targets by stamping its id here; the server reads it back
+ * and pins `RequestContext`'s thread id to that value (falling back to
+ * the per-session cookie when absent). Keeping the header / query
+ * names in one place means the side that sets them and the side that
+ * reads them can never drift.
+ */
+
+/** HTTP header inspected for the thread id a request targets. */
+export const THREAD_ID_HEADER = "x-mastra-thread-id";
+
+/** Query string parameter inspected for the thread id a request targets. */
+export const THREAD_ID_QUERY = "threadId";

package/src/wire.ts

@@ -0,0 +1,649 @@
+/**
+ * Wire-format contract for `@dbx-tools/appkit-mastra`: the
+ * dependency-free zod schemas + inferred types every consumer (the
+ * React client, browser bundles, the server plugin) shares.
+ *
+ * Kept free of `pg`, `fastembed`, and the Mastra runtime so the
+ * client can import these schemas without dragging in server-only
+ * dependencies. Three layers live here:
+ *
+ *   1. The descriptor published by `MastraPlugin.clientConfig()`
+ *      plus the REST payloads its routes return (models, history,
+ *      suggestions, chart embeds, statement data). The server
+ *      derives every path from the plugin mount and publishes the
+ *      resolved paths so the client composes URLs without
+ *      hard-coding `/api/mastra` - rename the plugin and the client
+ *      keeps working.
+ *   2. The `ctx.writer` event vocabulary: the wire-derived
+ *      {@link GenieChatEvent}s from `@dbx-tools/genie-shared` plus
+ *      the Mastra-only agent lifecycle events, unified as
+ *      {@link GenieWriterEvent} so subscribers narrow both halves
+ *      with a single `switch (event.type)`.
+ *   3. The Genie agent's workflow output shapes
+ *      ({@link GenieAgentResult} and its summary / dataset items).
+ *
+ * The route segments live in the sibling `routes.ts`
+ * ({@link MASTRA_ROUTES}) and the embed-marker grammar in `marker.ts`,
+ * so this file stays purely declarative (schemas + inferred types).
+ * The browser client that drives these routes (`MastraPluginClient`)
+ * ships from `@dbx-tools/appkit-mastra-ui`.
+ */
+
+import { genieModel, type GenieChatEvent, type MessageStatus } from "@dbx-tools/shared-genie";
+import { model } from "@dbx-tools/shared-model";
+import { z } from "zod";
+
+/* ---------------------------- client config ---------------------------- */
+
+/**
+ * JSON-safe descriptor published by the Mastra plugin's
+ * `clientConfig()`.
+ *
+ * Only the irreducible data lives here: `basePath` (the one path the
+ * client can't otherwise know, since it encodes the plugin's mount
+ * name) plus the runtime agent roster. Every concrete endpoint URL is
+ * derived from `basePath` by the browser client
+ * (`MastraPluginClient`) using the shared {@link MASTRA_ROUTES}
+ * segments, so there's nothing to publish per-route.
+ *
+ * Fields:
+ *   - `basePath`: plugin mount path. Always `/api/<pluginName>`. Feed
+ *     it to `new MastraPluginClient(config)` (from
+ *     `@dbx-tools/appkit-mastra-ui`) to get a typed client over every
+ *     route plus the standard agent stream.
+ *   - `defaultAgent`: agent id the client converses with when it
+ *     doesn't name one.
+ *   - `agents`: every registered agent id in registration order.
+ *   - `feedbackEnabled`: whether the server can log user feedback to
+ *     MLflow (MLflow tracing is configured). Drives whether the chat UI
+ *     surfaces thumbs / comment controls. Defaults to `false` so a
+ *     config published by an older server (without the field) parses
+ *     cleanly to "off".
+ */
+export const MastraClientConfigSchema = z.object({
+  basePath: z.string(),
+  defaultAgent: z.string(),
+  agents: z.array(z.string()),
+  feedbackEnabled: z.boolean().default(false),
+});
+export type MastraClientConfig = z.infer<typeof MastraClientConfigSchema>;
+
+/* ---------------------------- model catalogue ---------------------------- */
+
+/**
+ * JSON payload returned by `GET ${basePath}/models`. Wraps the shared
+ * {@link model.ServingEndpointSummarySchema} (re-exported from
+ * `@dbx-tools/shared-model`) so the catalogue
+ * descriptor has a single definition the client, server, and the
+ * standalone `@dbx-tools/model` toolkit all agree on.
+ */
+export const ServingEndpointsResponseSchema = z.object({
+  endpoints: z.array(model.ServingEndpointSummarySchema),
+});
+export type ServingEndpointsResponse = z.infer<typeof ServingEndpointsResponseSchema>;
+
+/* ----------------------------- chat history ----------------------------- */
+
+/**
+ * Structural shape for an AI SDK V5 `UIMessage`. Defined locally
+ * so the shared types package stays dependency-free (no `ai`
+ * import). The runtime values returned by the `/history` endpoint
+ * are produced by `toAISdkV5Messages` and are 1:1 compatible with
+ * `UIMessage` from the `ai` package; clients can safely cast when
+ * needed.
+ */
+export const MastraHistoryUIMessageSchema = z.object({
+  id: z.string(),
+  role: z.enum(["system", "user", "assistant"]),
+  parts: z.array(z.unknown()).readonly(),
+  metadata: z.unknown().optional(),
+});
+export type MastraHistoryUIMessage = z.infer<typeof MastraHistoryUIMessageSchema>;
+
+/**
+ * JSON payload returned by `GET ${basePath}/history`.
+ *
+ * Fields:
+ *   - `uiMessages`: page of UI-formatted messages, oldest -> newest.
+ *     Always chronological regardless of the underlying pagination
+ *     order so the client can prepend the array to the live
+ *     transcript without sorting.
+ *   - `page`: zero-indexed page that produced this response.
+ *   - `perPage`: number of items requested per page.
+ *   - `total`: total number of messages in the thread.
+ *   - `hasMore`: true when at least one older page is still
+ *     available.
+ */
+export const MastraHistoryResponseSchema = z.object({
+  uiMessages: z.array(MastraHistoryUIMessageSchema),
+  page: z.number(),
+  perPage: z.number(),
+  total: z.number(),
+  hasMore: z.boolean(),
+});
+export type MastraHistoryResponse = z.infer<typeof MastraHistoryResponseSchema>;
+
+/**
+ * JSON payload returned by `DELETE ${basePath}/history`. Deletes
+ * every persisted message + workflow snapshot tied to the caller's
+ * thread, so the next chat turn starts from a clean slate. The
+ * session cookie that anchors the thread id is preserved so the
+ * caller doesn't lose its identity - only the contents go away.
+ *
+ * `ok` is always `true` on success; the response object is kept
+ * as a struct (vs a bare 204) so future fields (e.g. `deletedAt`,
+ * `messages`) can be added without bumping the contract.
+ *
+ * Fields:
+ *   - `ok`: literal `true` on success.
+ *   - `agentId`: agent whose history was cleared.
+ *   - `threadId`: thread id that was wiped.
+ *   - `cleared`: number of messages the thread held before
+ *     deletion. Useful for client-side "cleared 12 messages"
+ *     toasts; `0` is reported when the thread was already empty
+ *     (call is idempotent).
+ */
+export const MastraClearHistoryResponseSchema = z.object({
+  ok: z.literal(true),
+  agentId: z.string(),
+  threadId: z.string(),
+  cleared: z.number(),
+});
+export type MastraClearHistoryResponse = z.infer<typeof MastraClearHistoryResponseSchema>;
+
+/* -------------------------------- threads -------------------------------- */
+
+/**
+ * A single conversation thread the resource (authenticated user) owns,
+ * as returned by `GET ${basePath}/threads`. Mirrors Mastra's
+ * `StorageThreadType` but with JSON-safe ISO-8601 timestamps (the wire
+ * can't carry `Date`).
+ *
+ * Fields:
+ *   - `id`: thread id. Pass it back as the thread-selection header
+ *     (`THREAD_ID_HEADER`) on a stream / history / delete call to act
+ *     on this conversation.
+ *   - `title`: human-readable title. Present once the agent's memory
+ *     has auto-generated one (after the first turn); absent on a
+ *     brand-new thread, so the UI falls back to a placeholder.
+ *   - `resourceId`: owning resource (the user id). Always the caller's
+ *     own resource - the list route filters by it server-side.
+ *   - `createdAt` / `updatedAt`: ISO-8601 timestamps. `updatedAt` is
+ *     the natural sort key for "most recent conversations first".
+ *   - `metadata`: opaque thread metadata, passed through untouched.
+ */
+export const MastraThreadSchema = z.object({
+  id: z.string(),
+  title: z.string().optional(),
+  resourceId: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  metadata: z.unknown().optional(),
+});
+export type MastraThread = z.infer<typeof MastraThreadSchema>;
+
+/**
+ * JSON payload returned by `GET ${basePath}/threads`. One page of the
+ * caller's conversation threads, newest (`updatedAt` DESC) first.
+ *
+ * Fields:
+ *   - `threads`: page of threads for the caller's resource.
+ *   - `page`: zero-indexed page that produced this response.
+ *   - `perPage`: number of items requested per page.
+ *   - `total`: total number of threads the resource owns.
+ *   - `hasMore`: true when at least one more page is available.
+ */
+export const MastraThreadsResponseSchema = z.object({
+  threads: z.array(MastraThreadSchema),
+  page: z.number(),
+  perPage: z.number(),
+  total: z.number(),
+  hasMore: z.boolean(),
+});
+export type MastraThreadsResponse = z.infer<typeof MastraThreadsResponseSchema>;
+
+/**
+ * JSON payload returned by `DELETE ${basePath}/threads` (thread id
+ * supplied via the thread-selection header / `threadId` query). Wipes
+ * the named thread and every message on it.
+ *
+ * Fields:
+ *   - `ok`: literal `true` on success.
+ *   - `agentId`: agent whose thread was deleted.
+ *   - `threadId`: thread id that was removed.
+ *   - `deleted`: `true` when a thread row existed and was removed,
+ *     `false` when it was already gone (call is idempotent).
+ */
+export const MastraDeleteThreadResponseSchema = z.object({
+  ok: z.literal(true),
+  agentId: z.string(),
+  threadId: z.string(),
+  deleted: z.boolean(),
+});
+export type MastraDeleteThreadResponse = z.infer<typeof MastraDeleteThreadResponseSchema>;
+
+/** Longest thread title the rename route accepts (trimmed server-side). */
+export const MASTRA_THREAD_TITLE_MAX = 200;
+
+/**
+ * JSON body for `PATCH ${basePath}/threads` (thread id supplied via the
+ * thread-selection header / `threadId` query). Renames a single
+ * conversation.
+ *
+ * Fields:
+ *   - `title`: the new human-readable title. Trimmed and capped at
+ *     {@link MASTRA_THREAD_TITLE_MAX} characters server-side; must be
+ *     non-empty after trimming.
+ */
+export const MastraUpdateThreadRequestSchema = z.object({
+  title: z.string().trim().min(1).max(MASTRA_THREAD_TITLE_MAX),
+});
+export type MastraUpdateThreadRequest = z.infer<typeof MastraUpdateThreadRequestSchema>;
+
+/**
+ * JSON payload returned by `PATCH ${basePath}/threads`. Echoes the
+ * renamed thread in its post-update wire shape so the client can reflect
+ * the new title without a re-fetch.
+ *
+ * Fields:
+ *   - `ok`: literal `true` on success.
+ *   - `agentId`: agent whose thread was renamed.
+ *   - `thread`: the updated thread (carries the new `title`).
+ */
+export const MastraUpdateThreadResponseSchema = z.object({
+  ok: z.literal(true),
+  agentId: z.string(),
+  thread: MastraThreadSchema,
+});
+export type MastraUpdateThreadResponse = z.infer<typeof MastraUpdateThreadResponseSchema>;
+
+/* ------------------------------ suggestions ------------------------------ */
+
+/**
+ * JSON payload returned by `GET ${basePath}/suggestions`.
+ *
+ * Carries the curated starter questions for an agent's Genie space -
+ * the `sample_questions` an author configured on the space, surfaced
+ * as one-tap prompts on the chat's empty state. `questions` is empty
+ * when the agent has no Genie space (or the space defines none), so
+ * the client renders nothing in that case rather than falling back to
+ * built-in example prompts.
+ */
+export const MastraSuggestionsResponseSchema = z.object({
+  questions: z.array(z.string()),
+});
+export type MastraSuggestionsResponse = z.infer<typeof MastraSuggestionsResponseSchema>;
+
+/* --------------------------------- charts --------------------------------- */
+
+/**
+ * Allowed chart types the planner can pick. Defined as a
+ * discriminated literal union so each variant carries its own
+ * `.describe()` clause - the server-side planner's prompt
+ * formatter walks `.options` to inline the descriptions into the
+ * model instructions, keeping the prompt in lock-step with the
+ * schema by construction. The runtime type is the plain string
+ * union (`"bar" | "line" | ...`), so consumers that just need a
+ * discriminator value behave the same as if it were a
+ * `z.enum([...])`.
+ */
+export const ChartTypeSchema = z
+  .union([
+    z
+      .literal("bar")
+      .describe(
+        "comparing a numeric value across a small/medium set of discrete categories (top-N, ranking, group-by)",
+      ),
+    z
+      .literal("line")
+      .describe(
+        "ordered-axis trend (time series, sequence, rank) where the x-axis has natural order",
+      ),
+    z.literal("area").describe("stacked-trend emphasis - cumulative or composition over time"),
+    z
+      .literal("scatter")
+      .describe("two-numeric-axis correlations between fields (e.g. price vs. quantity)"),
+    z.literal("pie").describe("parts-of-a-whole when 2-7 categories sum to a meaningful total"),
+  ])
+  .describe("The chart shape that best matches the data and intent.");
+export type ChartType = z.infer<typeof ChartTypeSchema>;
+
+/**
+ * Resolved chart plan a settled chart entry carries on its
+ * `result` field. `option` is the full Echarts spec; pass
+ * straight into `<ReactECharts option={...}>`.
+ */
+export const ChartResultSchema = z.object({
+  chartType: ChartTypeSchema,
+  option: z
+    .record(z.string(), z.unknown())
+    .describe(
+      "Fully-resolved Echarts `EChartsOption` JSON for this chart - drop directly into an Echarts instance (or `<ReactECharts option={...} />`) without further processing. Includes title / tooltip / legend / grid / axis / series defaults already merged in.",
+    ),
+});
+export type ChartResult = z.infer<typeof ChartResultSchema>;
+
+/**
+ * Wire-format AND server-side cache shape for a chart entry.
+ * Three lifecycle states inferred from the two optional fields
+ * (no discriminator needed):
+ *
+ *   - `result` set                    -> chart is ready to render
+ *   - `error` set                     -> planner / data fetch failed
+ *   - both `result` and `error` unset -> still processing
+ *
+ * `option` is typed as a generic record so this package stays
+ * dependency-free of `echarts`. The server (`chart.ts`) imports
+ * this schema directly; the demo client polls the
+ * `/embed/chart/:id` route and parses responses against it.
+ */
+export const ChartSchema = z.object({
+  chartId: z
+    .string()
+    .describe(
+      "Opaque id minted by the chart subsystem. Embed verbatim as `[chart:<chartId>]` in agent prose; the host UI resolves it against this cache entry.",
+    ),
+  error: z
+    .string()
+    .optional()
+    .describe(
+      "Error message when the chart failed (data fetch error, planner error, empty dataset). Mutually exclusive with `result`; absent on success and while processing.",
+    ),
+  result: ChartResultSchema.optional().describe(
+    "Resolved chart plan. Absent while processing and when the run errored.",
+  ),
+});
+export type Chart = z.infer<typeof ChartSchema>;
+
+/* ------------------------------- statements ------------------------------- */
+
+/**
+ * Wire-format payload returned by `GET ${basePath}/embed/data/:id`.
+ *
+ * Mirrors the agent-side `get_statement` tool's output so the
+ * host UI and the LLM see the exact same shape for the same
+ * statement; the route is what resolves `[data:<statement_id>]`
+ * markers the agent embeds in prose.
+ *
+ * Fields:
+ *   - `columns`: column names in declaration order.
+ *   - `rows`: row records keyed by column name. Cell values are
+ *     either coerced numbers or the original strings (Genie /
+ *     Statement Execution returns every cell as `string | null`;
+ *     numeric-looking cells are coerced server-side so the UI
+ *     can format with `tabular-nums` without re-parsing).
+ *   - `rowCount`: total row count upstream (independent of the
+ *     `limit` cap). Compare against `rows.length` to detect
+ *     truncation - `truncated` is the precomputed flag.
+ *   - `truncated`: `true` when the server clipped rows to honor
+ *     the route's row cap; the UI should surface a "showing N of
+ *     M rows" affordance in that case.
+ */
+export const StatementDataSchema = z.object({
+  columns: z.array(z.string()),
+  rows: z.array(z.record(z.string(), z.unknown())),
+  rowCount: z.number(),
+  truncated: z.boolean(),
+});
+export type StatementData = z.infer<typeof StatementDataSchema>;
+
+/* ----------------------------- writer surface ---------------------------- */
+
+/**
+ * The `ToolStream`-shaped writer the Mastra Genie agent and chart
+ * helpers publish events through. Defined here (vs imported from
+ * `@mastra/core`) so helpers in `@dbx-tools/appkit-mastra` can
+ * accept any object with a `.write` method without dragging
+ * Mastra's full `ToolStream` (and its agent / tool typings) into
+ * call sites. The actual Mastra `ctx.writer` is assignable to
+ * this shape so callers pass it straight through.
+ *
+ * Kept as a plain TypeScript interface (vs a zod schema) because
+ * the contract is a method - zod can only validate the shape via
+ * `z.custom`, which adds noise without buying any runtime check.
+ */
+export interface MastraWriter {
+  write: (chunk: unknown) => unknown;
+}
+
+/* ---------------- mastra-only genie-agent events ---------------- */
+
+/**
+ * Mastra-only lifecycle event: the Genie tool invocation started.
+ * Emitted immediately when the calling agent invokes the Genie
+ * tool, before any inner agent / wire activity, so the UI can
+ * pop a "Thinking..." pill the instant the model decides to
+ * delegate. `conversationId` / `messageId` are absent on this
+ * first emit (no Genie round-trip yet). Field names are
+ * camelCase (vs the snake_case wire events) to mirror the
+ * Genie agent's own internal data plumbing.
+ */
+export const StartedEventSchema = z.object({
+  type: z.literal("started"),
+  spaceId: z.string(),
+  /**
+   * Genie conversation id, populated only when this `started`
+   * event corresponds to a follow-up turn on an existing
+   * conversation. Absent on the first turn.
+   */
+  conversationId: z.string().optional(),
+  /**
+   * Genie message id, populated only after the first wire
+   * `message` event lands. Absent on the immediate-on-invoke
+   * emit.
+   */
+  messageId: z.string().optional(),
+  /** Question the Genie agent sent to Genie. */
+  content: z.string(),
+});
+export type StartedEvent = z.infer<typeof StartedEventSchema>;
+
+/**
+ * Mastra-only lifecycle event: one `ask_genie` invocation
+ * finished. Carries the hydrated `statementIds` (rows are fetched
+ * via `getStatement` separately) and Genie's final prose answer
+ * so the UI can move from "thinking" to "answered" without
+ * waiting for the Genie agent's whole reasoning loop to end.
+ */
+export const AskGenieDoneEventSchema = z.object({
+  type: z.literal("ask_genie_done"),
+  spaceId: z.string(),
+  conversationId: z.string().optional(),
+  messageId: z.string().optional(),
+  /** Genie's natural-language answer for the turn, if any. */
+  answer: z.string().optional(),
+  /** Statement ids for any non-empty result sets this turn produced. */
+  statementIds: z.array(z.string()),
+  /**
+   * Terminal wire status (`COMPLETED` / `FAILED` / `CANCELLED`).
+   * Mirrors the source `result` event's status so subscribers
+   * can react to ask-level completion without re-walking history.
+   * Treated as `z.custom<MessageStatus>` because the SDK is the
+   * source of truth for the enum values.
+   */
+  status: z.custom<MessageStatus>((v) => typeof v === "string"),
+});
+export type AskGenieDoneEvent = z.infer<typeof AskGenieDoneEventSchema>;
+
+/**
+ * Mastra-only error event: terminal Genie agent / transport
+ * error. Genie's own `FAILED` / `CANCELLED` come through the
+ * wire's `result` event - this variant is for failures the wire
+ * can't represent (network, Genie agent crash, planner error,
+ * etc.) plus a UI-friendly mirror of `result` when the status is
+ * non-`COMPLETED`.
+ */
+export const MastraGenieErrorEventSchema = z.object({
+  type: z.literal("error"),
+  spaceId: z.string().optional(),
+  conversationId: z.string().optional(),
+  messageId: z.string().optional(),
+  error: z.string(),
+});
+export type MastraGenieErrorEvent = z.infer<typeof MastraGenieErrorEventSchema>;
+
+/**
+ * Mastra-only lifecycle event: the inner Genie agent's
+ * structured-output coercion has landed. Fires once per Genie
+ * tool invocation, AFTER `agent.generate(...)` completes (i.e.
+ * the inner loop + Mastra's structuring pass have both
+ * finished) and BEFORE the wrapper hydrates each `data` item
+ * with a chart. Signals to the host UI that the agent has
+ * stopped reasoning and is moving into chart generation.
+ *
+ * The structuring pass itself is opaque (it runs inside
+ * Mastra's `agent.generate(...)` together with the tool loop)
+ * so this is the earliest hook we can offer; we can't fire a
+ * "summary started" event the way we fire `started`.
+ */
+export const SummaryEventSchema = z.object({
+  type: z.literal("summary"),
+  spaceId: z.string(),
+  /** Total number of items in the agent's structured summary. */
+  items: z.number().int().nonnegative(),
+  /** Count of `text` / prose items in the summary. */
+  textItems: z.number().int().nonnegative(),
+  /**
+   * Count of `data` items the wrapper will hydrate into charts.
+   * The host UI can use this to seed N chart skeletons before
+   * the per-chart events arrive.
+   */
+  dataItems: z.number().int().nonnegative(),
+});
+export type SummaryEvent = z.infer<typeof SummaryEventSchema>;
+
+/**
+ * Mastra-only event union. Each variant uses the same flat
+ * `{type, ...fields}` shape as {@link GenieChatEvent} so
+ * subscribers union both with a single `switch (event.type)`.
+ */
+export const GenieAgentEventSchema = z.discriminatedUnion("type", [
+  StartedEventSchema,
+  AskGenieDoneEventSchema,
+  MastraGenieErrorEventSchema,
+  SummaryEventSchema,
+]);
+export type GenieAgentEvent = z.infer<typeof GenieAgentEventSchema>;
+
+/**
+ * The unified writer-event vocabulary subscribers see on
+ * `ctx.writer`: the wire-derived {@link GenieChatEvent} union
+ * **plus** Mastra-only events from {@link GenieAgentEvent}. Each
+ * variant is a flat `{type, ...fields}` object; consumers narrow
+ * on `type` and read fields inline - there is no payload wrapper
+ * and no writer-boundary translator.
+ *
+ * Composed via `z.union` (not `z.discriminatedUnion`) because
+ * both halves are themselves discriminated unions on the same
+ * `type` key.
+ */
+export const GenieWriterEventSchema = z.union([
+  genieModel.GenieChatEventSchema,
+  GenieAgentEventSchema,
+]);
+export type GenieWriterEvent = z.infer<typeof GenieWriterEventSchema>;
+
+/** Discriminator type for {@link GenieWriterEvent}. */
+export type GenieWriterEventType = GenieWriterEvent["type"];
+
+/* ------------------------- summary + dataset ------------------------ */
+
+/**
+ * Tabular payload embedded in every {@link GenieSummaryItem}
+ * `visualize` dataset. Always present: hydrated by the workflow's
+ * agent step before the finalize step runs, so consumers can render
+ * a table fallback regardless of chart-planner outcome.
+ *
+ * Fields:
+ *   - `columns`: column names in display order.
+ *   - `rows`: tabular rows keyed by column name.
+ *   - `rowCount`: total row count Genie reported (may exceed
+ *     `rows.length` when the statement was truncated).
+ */
+export const GenieDatasetDataSchema = z.object({
+  columns: z.array(z.string()),
+  rows: z.array(z.record(z.string(), z.unknown())),
+  rowCount: z.number(),
+});
+export type GenieDatasetData = z.infer<typeof GenieDatasetDataSchema>;
+
+/**
+ * Slim chart reference attached to a visualize dataset. Only
+ * present when planning succeeded.
+ *
+ * `option` is intentionally NOT included. The resolved Echarts
+ * spec lives off-band in the chart cache: the host UI fetches it
+ * by `chartId` via `${MastraClientConfig.embedPathTemplate}`
+ * (`/embed/chart/:id`, see {@link Chart}). Embedding the full spec inline would
+ * inflate every dataset by several KB per chart and round-trip
+ * through the LLM context for zero benefit (the model only needs
+ * the `chartId` to place a `[chart:<chartId>]` marker in its
+ * reply).
+ */
+export const GenieDatasetChartSchema = z.object({
+  chartId: z.string(),
+  chartType: z.enum(["bar", "line", "area", "scatter", "pie"]),
+});
+export type GenieDatasetChart = z.infer<typeof GenieDatasetChartSchema>;
+
+/**
+ * Dataset bundle attached to a {@link GenieSummaryItem} `visualize`
+ * item. `data` is always populated; `chart` is best-effort and
+ * absent when the workflow's chart-planner failed (timeout,
+ * malformed plan, abort) so the host UI can still render the
+ * underlying table.
+ */
+export const GenieDatasetSchema = z.object({
+  data: GenieDatasetDataSchema,
+  chart: GenieDatasetChartSchema.optional(),
+});
+export type GenieDataset = z.infer<typeof GenieDatasetSchema>;
+
+/**
+ * One item inside the Genie workflow's final summary. The
+ * workflow produces a mixed sequence of:
+ *
+ *   - `string`: a markdown paragraph (interpretation, callouts,
+ *     transitions between data blocks).
+ *   - `visualize`: a request from the agent step to visualize a
+ *     specific Genie statement at this position in the prose.
+ *     The finalize step hydrates `dataset.data` (rows from the
+ *     matching `statementId`) and attaches `dataset.chart` after
+ *     running the chart-planner. The agent NEVER picks the chart
+ *     type - it only marks where a visualization belongs.
+ *
+ * The host UI walks the array in display order to compose the
+ * final assistant message.
+ */
+export const GenieSummaryItemSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("string"),
+    text: z.string(),
+  }),
+  z.object({
+    type: z.literal("visualize"),
+    statementId: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    dataset: GenieDatasetSchema,
+  }),
+]);
+export type GenieSummaryItem = z.infer<typeof GenieSummaryItemSchema>;
+
+/** Discriminator type for {@link GenieSummaryItem}. */
+export type GenieSummaryItemType = GenieSummaryItem["type"];
+
+/**
+ * The Genie agent's final output shape - what the calling agent's
+ * Genie tool returns to the calling LLM. The `summary` array is
+ * the user-facing renderable; `conversationId` lets the calling
+ * agent (or the UI) follow up in the same Genie thread on the
+ * next turn.
+ */
+export const GenieAgentResultSchema = z.object({
+  spaceId: z.string(),
+  conversationId: z.string().optional(),
+  summary: z.array(GenieSummaryItemSchema),
+  error: z.string().optional(),
+});
+export type GenieAgentResult = z.infer<typeof GenieAgentResultSchema>;

package/tsconfig.json

@@ -0,0 +1,40 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022",
+      "WebWorker"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}