@dbx-tools/appkit-mastra-shared 0.1.12 → 0.1.18

package/src/protocol.ts

@@ -1,13 +1,18 @@
 /**
- * Shape of the data published by {@link MastraPlugin.clientConfig} plus
- * a tiny URL helper. Kept dependency-free so the React client can
- * import it without dragging in `pg`, `fastembed`, or Mastra itself.
+ * Shape of the data published by {@link MastraPlugin.clientConfig}.
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime)
+ * so the React client can import these schemas without dragging in
+ * server-only dependencies.
  *
- * Server-side, `MastraPlugin` derives every path from the plugin mount
- * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
- * the resolved paths lets the client compute URLs without hard-coding
- * `/api/mastra` anywhere - rename the plugin and the React client
- * keeps working.
+ * Server-side, `MastraPlugin` derives every path from the plugin
+ * mount (AppKit conventionally serves plugin `foo` at `/api/foo`).
+ * Publishing the resolved paths lets the client compute URLs
+ * without hard-coding `/api/mastra` anywhere - rename the plugin
+ * and the React client keeps working.
+ *
+ * URL helpers ({@link chatUrl}, {@link historyUrl}) live in the
+ * sibling `mastra.ts` module so this file stays purely declarative
+ * (schemas + inferred types only).
  *
  * @example
  * ```tsx
@@ -21,134 +26,141 @@
  * ```
  */
 
-/** JSON-safe descriptor published by the Mastra plugin's `clientConfig()`. */
-export interface MastraClientConfig {
-  /** Plugin mount path. Always `/api/<pluginName>`. */
-  basePath: string;
-  /**
-   * Chat endpoint for the **default** agent, i.e.
-   * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
-   */
-  chatPath: string;
-  /**
-   * Template form used by the route handler:
-   * `${basePath}/route/chat/:agentId`. Provided for documentation /
-   * tools that want the OpenAPI-style placeholder; clients should
-   * normally call {@link chatUrl} instead.
-   */
-  chatPathTemplate: string;
-  /** Models catalogue endpoint: `${basePath}/models`. */
-  modelsPath: string;
-  /**
-   * Thread history endpoint for the **default** agent:
-   * `${basePath}/route/history`. Returns AI SDK V5 `UIMessage`s for
-   * the current session's thread; takes `page` and `perPage` query
-   * params. See {@link historyUrl}.
-   */
-  historyPath: string;
-  /**
-   * Templated form of {@link historyPath}: `${basePath}/route/history/:agentId`.
-   * Use this to reach a non-default agent's history; clients should
-   * normally call {@link historyUrl} instead.
-   */
-  historyPathTemplate: string;
-  /** Agent id `chatRoute` binds to when the client doesn't name one. */
-  defaultAgent: string;
-  /** Every registered agent id in registration order. */
-  agents: string[];
-}
+import { z } from "zod";
+
+/* ---------------------------- client config ---------------------------- */
 
 /**
- * Minimal descriptor for a Databricks Model Serving endpoint. Mirrors
- * the server-side `ServingEndpointSummary` from `serving.ts` and is
- * kept here so the React client can type the `/models` response
- * without importing the full plugin (which would pull in `pg`,
- * `fastembed`, and Mastra itself).
+ * JSON-safe descriptor published by the Mastra plugin's
+ * `clientConfig()`.
+ *
+ * Fields:
+ *   - `basePath`: plugin mount path. Always `/api/<pluginName>`.
+ *   - `chatPath`: chat endpoint for the **default** agent, i.e.
+ *     `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
+ *   - `chatPathTemplate`: template form used by the route handler:
+ *     `${basePath}/route/chat/:agentId`. Provided for documentation
+ *     / tools that want the OpenAPI-style placeholder; clients
+ *     should normally call {@link chatUrl} instead.
+ *   - `modelsPath`: models catalogue endpoint: `${basePath}/models`.
+ *   - `historyPath`: thread history endpoint for the **default**
+ *     agent: `${basePath}/route/history`. Returns AI SDK V5
+ *     `UIMessage`s for the current session's thread; takes `page`
+ *     and `perPage` query params. See {@link historyUrl}.
+ *   - `historyPathTemplate`: templated form of `historyPath`:
+ *     `${basePath}/route/history/:agentId`. Use this to reach a
+ *     non-default agent's history; clients should normally call
+ *     {@link historyUrl} instead.
+ *   - `defaultAgent`: agent id `chatRoute` binds to when the client
+ *     doesn't name one.
+ *   - `agents`: every registered agent id in registration order.
  */
-export interface ServingEndpointSummary {
-  /** Endpoint name as listed by the Model Serving REST API. */
-  name: string;
-  /** Task hint (e.g. `"llm/v1/chat"`). Useful for filtering. */
-  task?: string;
-  /** Ready / updating / failed state. */
-  state?: string;
-  /** Free-form description; mostly informational. */
-  description?: string;
-}
+export const MastraClientConfigSchema = z.object({
+  basePath: z.string(),
+  chatPath: z.string(),
+  chatPathTemplate: z.string(),
+  modelsPath: z.string(),
+  historyPath: z.string(),
+  historyPathTemplate: z.string(),
+  defaultAgent: z.string(),
+  agents: z.array(z.string()),
+});
+export type MastraClientConfig = z.infer<typeof MastraClientConfigSchema>;
 
-/** JSON payload returned by `GET ${basePath}/models`. */
-export interface ServingEndpointsResponse {
-  endpoints: ServingEndpointSummary[];
-}
+/* ---------------------------- model catalogue ---------------------------- */
 
 /**
- * Compute the chat URL for a given agent, falling back to the default
- * when `agentId` is omitted. Returns `config.chatPath` directly for
- * the default agent (the `chatRoute` mount that does not require an
- * `:agentId` segment).
+ * Minimal descriptor for a Databricks Model Serving endpoint.
+ * Mirrors the server-side `ServingEndpointSummary` from `serving.ts`
+ * and is kept here so the React client can type the `/models`
+ * response without importing the full plugin (which would pull in
+ * `pg`, `fastembed`, and Mastra itself).
+ *
+ * Fields:
+ *   - `name`: endpoint name as listed by the Model Serving REST API.
+ *   - `task`: task hint (e.g. `"llm/v1/chat"`). Useful for filtering.
+ *   - `state`: ready / updating / failed state.
+ *   - `description`: free-form description; mostly informational.
  */
-export function chatUrl(
-  config: Pick<MastraClientConfig, "chatPath" | "defaultAgent">,
-  agentId?: string,
-): string {
-  const id = agentId ?? config.defaultAgent;
-  if (!id || id === config.defaultAgent) return config.chatPath;
-  return `${config.chatPath}/${encodeURIComponent(id)}`;
-}
+export const ServingEndpointSummarySchema = z.object({
+  name: z.string(),
+  task: z.string().optional(),
+  state: z.string().optional(),
+  description: z.string().optional(),
+});
+export type ServingEndpointSummary = z.infer<typeof ServingEndpointSummarySchema>;
+
+/** JSON payload returned by `GET ${basePath}/models`. */
+export const ServingEndpointsResponseSchema = z.object({
+  endpoints: z.array(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.
+ * 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 interface MastraHistoryUIMessage {
-  id: string;
-  role: "system" | "user" | "assistant";
-  parts: ReadonlyArray<unknown>;
-  metadata?: unknown;
-}
+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`. */
-export interface MastraHistoryResponse {
-  /**
-   * 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.
-   */
-  uiMessages: MastraHistoryUIMessage[];
-  /** Zero-indexed page that produced this response. */
-  page: number;
-  /** Number of items requested per page. */
-  perPage: number;
-  /** Total number of messages in the thread. */
-  total: number;
-  /** True when at least one older page is still available. */
-  hasMore: boolean;
-}
+/**
+ * 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>;
 
 /**
- * Build the history URL for a given agent + page. Mirrors
- * {@link chatUrl}: the default agent uses the bare `historyPath`,
- * any other agent appends `/<encoded id>` to it. `page` and
- * `perPage` are appended as query parameters when provided.
+ * 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 function historyUrl(
-  config: Pick<MastraClientConfig, "historyPath" | "defaultAgent">,
-  options: { agentId?: string; page?: number; perPage?: number } = {},
-): string {
-  const id = options.agentId ?? config.defaultAgent;
-  const base =
-    !id || id === config.defaultAgent
-      ? config.historyPath
-      : `${config.historyPath}/${encodeURIComponent(id)}`;
-  const params = new URLSearchParams();
-  if (options.page !== undefined) params.set("page", String(options.page));
-  if (options.perPage !== undefined) {
-    params.set("perPage", String(options.perPage));
-  }
-  const qs = params.toString();
-  return qs ? `${base}?${qs}` : base;
-}
+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>;