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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +2 -2
  2. package/dist/index.d.ts +2 -0
  3. package/dist/index.js +2 -0
  4. package/dist/src/genie.d.ts +635 -0
  5. package/dist/src/genie.js +349 -0
  6. package/dist/src/mastra.d.ts +31 -0
  7. package/dist/src/mastra.js +44 -0
  8. package/dist/src/protocol.d.ts +148 -105
  9. package/dist/src/protocol.js +132 -36
  10. package/dist/tsconfig.build.tsbuildinfo +1 -1
  11. package/index.ts +2 -0
  12. package/package.json +13 -3
  13. package/src/genie.ts +407 -0
  14. package/src/mastra.ts +53 -0
  15. package/src/protocol.ts +137 -125
package/dist/src/protocol.d.ts CHANGED
@@ -1,13 +1,18 @@
1
1
  /**
2
- * Shape of the data published by {@link MastraPlugin.clientConfig} plus
3
- * a tiny URL helper. Kept dependency-free so the React client can
4
- * import it without dragging in `pg`, `fastembed`, or Mastra itself.
2
+ * Shape of the data published by {@link MastraPlugin.clientConfig}.
3
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime)
4
+ * so the React client can import these schemas without dragging in
5
+ * server-only dependencies.
5
6
  *
6
- * Server-side, `MastraPlugin` derives every path from the plugin mount
7
- * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
8
- * the resolved paths lets the client compute URLs without hard-coding
9
- * `/api/mastra` anywhere - rename the plugin and the React client
10
- * keeps working.
7
+ * Server-side, `MastraPlugin` derives every path from the plugin
8
+ * mount (AppKit conventionally serves plugin `foo` at `/api/foo`).
9
+ * Publishing the resolved paths lets the client compute URLs
10
+ * without hard-coding `/api/mastra` anywhere - rename the plugin
11
+ * and the React client keeps working.
12
+ *
13
+ * URL helpers ({@link chatUrl}, {@link historyUrl}) live in the
14
+ * sibling `mastra.ts` module so this file stays purely declarative
15
+ * (schemas + inferred types only).
11
16
  *
12
17
  * @example
13
18
  * ```tsx
@@ -20,109 +25,147 @@
20
25
  * });
21
26
  * ```
22
27
  */
23
- /** JSON-safe descriptor published by the Mastra plugin's `clientConfig()`. */
24
- export interface MastraClientConfig {
25
- /** Plugin mount path. Always `/api/<pluginName>`. */
26
- basePath: string;
27
- /**
28
- * Chat endpoint for the **default** agent, i.e.
29
- * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
30
- */
31
- chatPath: string;
32
- /**
33
- * Template form used by the route handler:
34
- * `${basePath}/route/chat/:agentId`. Provided for documentation /
35
- * tools that want the OpenAPI-style placeholder; clients should
36
- * normally call {@link chatUrl} instead.
37
- */
38
- chatPathTemplate: string;
39
- /** Models catalogue endpoint: `${basePath}/models`. */
40
- modelsPath: string;
41
- /**
42
- * Thread history endpoint for the **default** agent:
43
- * `${basePath}/route/history`. Returns AI SDK V5 `UIMessage`s for
44
- * the current session's thread; takes `page` and `perPage` query
45
- * params. See {@link historyUrl}.
46
- */
47
- historyPath: string;
48
- /**
49
- * Templated form of {@link historyPath}: `${basePath}/route/history/:agentId`.
50
- * Use this to reach a non-default agent's history; clients should
51
- * normally call {@link historyUrl} instead.
52
- */
53
- historyPathTemplate: string;
54
- /** Agent id `chatRoute` binds to when the client doesn't name one. */
55
- defaultAgent: string;
56
- /** Every registered agent id in registration order. */
57
- agents: string[];
58
- }
28
+ import { z } from "zod";
29
+ /**
30
+ * JSON-safe descriptor published by the Mastra plugin's
31
+ * `clientConfig()`.
32
+ *
33
+ * Fields:
34
+ * - `basePath`: plugin mount path. Always `/api/<pluginName>`.
35
+ * - `chatPath`: chat endpoint for the **default** agent, i.e.
36
+ * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
37
+ * - `chatPathTemplate`: template form used by the route handler:
38
+ * `${basePath}/route/chat/:agentId`. Provided for documentation
39
+ * / tools that want the OpenAPI-style placeholder; clients
40
+ * should normally call {@link chatUrl} instead.
41
+ * - `modelsPath`: models catalogue endpoint: `${basePath}/models`.
42
+ * - `historyPath`: thread history endpoint for the **default**
43
+ * agent: `${basePath}/route/history`. Returns AI SDK V5
44
+ * `UIMessage`s for the current session's thread; takes `page`
45
+ * and `perPage` query params. See {@link historyUrl}.
46
+ * - `historyPathTemplate`: templated form of `historyPath`:
47
+ * `${basePath}/route/history/:agentId`. Use this to reach a
48
+ * non-default agent's history; clients should normally call
49
+ * {@link historyUrl} instead.
50
+ * - `defaultAgent`: agent id `chatRoute` binds to when the client
51
+ * doesn't name one.
52
+ * - `agents`: every registered agent id in registration order.
53
+ */
54
+ export declare const MastraClientConfigSchema: z.ZodObject<{
55
+ basePath: z.ZodString;
56
+ chatPath: z.ZodString;
57
+ chatPathTemplate: z.ZodString;
58
+ modelsPath: z.ZodString;
59
+ historyPath: z.ZodString;
60
+ historyPathTemplate: z.ZodString;
61
+ defaultAgent: z.ZodString;
62
+ agents: z.ZodArray<z.ZodString>;
63
+ }, z.core.$strip>;
64
+ export type MastraClientConfig = z.infer<typeof MastraClientConfigSchema>;
59
65
  /**
60
- * Minimal descriptor for a Databricks Model Serving endpoint. Mirrors
61
- * the server-side `ServingEndpointSummary` from `serving.ts` and is
62
- * kept here so the React client can type the `/models` response
63
- * without importing the full plugin (which would pull in `pg`,
64
- * `fastembed`, and Mastra itself).
66
+ * Minimal descriptor for a Databricks Model Serving endpoint.
67
+ * Mirrors the server-side `ServingEndpointSummary` from `serving.ts`
68
+ * and is kept here so the React client can type the `/models`
69
+ * response without importing the full plugin (which would pull in
70
+ * `pg`, `fastembed`, and Mastra itself).
71
+ *
72
+ * Fields:
73
+ * - `name`: endpoint name as listed by the Model Serving REST API.
74
+ * - `task`: task hint (e.g. `"llm/v1/chat"`). Useful for filtering.
75
+ * - `state`: ready / updating / failed state.
76
+ * - `description`: free-form description; mostly informational.
65
77
  */
66
- export interface ServingEndpointSummary {
67
- /** Endpoint name as listed by the Model Serving REST API. */
68
- name: string;
69
- /** Task hint (e.g. `"llm/v1/chat"`). Useful for filtering. */
70
- task?: string;
71
- /** Ready / updating / failed state. */
72
- state?: string;
73
- /** Free-form description; mostly informational. */
74
- description?: string;
75
- }
78
+ export declare const ServingEndpointSummarySchema: z.ZodObject<{
79
+ name: z.ZodString;
80
+ task: z.ZodOptional<z.ZodString>;
81
+ state: z.ZodOptional<z.ZodString>;
82
+ description: z.ZodOptional<z.ZodString>;
83
+ }, z.core.$strip>;
84
+ export type ServingEndpointSummary = z.infer<typeof ServingEndpointSummarySchema>;
76
85
  /** JSON payload returned by `GET ${basePath}/models`. */
77
- export interface ServingEndpointsResponse {
78
- endpoints: ServingEndpointSummary[];
79
- }
86
+ export declare const ServingEndpointsResponseSchema: z.ZodObject<{
87
+ endpoints: z.ZodArray<z.ZodObject<{
88
+ name: z.ZodString;
89
+ task: z.ZodOptional<z.ZodString>;
90
+ state: z.ZodOptional<z.ZodString>;
91
+ description: z.ZodOptional<z.ZodString>;
92
+ }, z.core.$strip>>;
93
+ }, z.core.$strip>;
94
+ export type ServingEndpointsResponse = z.infer<typeof ServingEndpointsResponseSchema>;
80
95
  /**
81
- * Compute the chat URL for a given agent, falling back to the default
82
- * when `agentId` is omitted. Returns `config.chatPath` directly for
83
- * the default agent (the `chatRoute` mount that does not require an
84
- * `:agentId` segment).
96
+ * Structural shape for an AI SDK V5 `UIMessage`. Defined locally
97
+ * so the shared types package stays dependency-free (no `ai`
98
+ * import). The runtime values returned by the `/history` endpoint
99
+ * are produced by `toAISdkV5Messages` and are 1:1 compatible with
100
+ * `UIMessage` from the `ai` package; clients can safely cast when
101
+ * needed.
85
102
  */
86
- export declare function chatUrl(config: Pick<MastraClientConfig, "chatPath" | "defaultAgent">, agentId?: string): string;
103
+ export declare const MastraHistoryUIMessageSchema: z.ZodObject<{
104
+ id: z.ZodString;
105
+ role: z.ZodEnum<{
106
+ system: "system";
107
+ user: "user";
108
+ assistant: "assistant";
109
+ }>;
110
+ parts: z.ZodReadonly<z.ZodArray<z.ZodUnknown>>;
111
+ metadata: z.ZodOptional<z.ZodUnknown>;
112
+ }, z.core.$strip>;
113
+ export type MastraHistoryUIMessage = z.infer<typeof MastraHistoryUIMessageSchema>;
87
114
  /**
88
- * Structural shape for an AI SDK V5 `UIMessage`. Defined locally so
89
- * the shared types package stays dependency-free (no `ai` import).
90
- * The runtime values returned by the `/history` endpoint are produced
91
- * by `toAISdkV5Messages` and are 1:1 compatible with `UIMessage` from
92
- * the `ai` package; clients can safely cast when needed.
115
+ * JSON payload returned by `GET ${basePath}/history`.
116
+ *
117
+ * Fields:
118
+ * - `uiMessages`: page of UI-formatted messages, oldest -> newest.
119
+ * Always chronological regardless of the underlying pagination
120
+ * order so the client can prepend the array to the live
121
+ * transcript without sorting.
122
+ * - `page`: zero-indexed page that produced this response.
123
+ * - `perPage`: number of items requested per page.
124
+ * - `total`: total number of messages in the thread.
125
+ * - `hasMore`: true when at least one older page is still
126
+ * available.
93
127
  */
94
- export interface MastraHistoryUIMessage {
95
- id: string;
96
- role: "system" | "user" | "assistant";
97
- parts: ReadonlyArray<unknown>;
98
- metadata?: unknown;
99
- }
100
- /** JSON payload returned by `GET ${basePath}/history`. */
101
- export interface MastraHistoryResponse {
102
- /**
103
- * Page of UI-formatted messages, oldest -> newest. Always
104
- * chronological regardless of the underlying pagination order so
105
- * the client can prepend the array to the live transcript without
106
- * sorting.
107
- */
108
- uiMessages: MastraHistoryUIMessage[];
109
- /** Zero-indexed page that produced this response. */
110
- page: number;
111
- /** Number of items requested per page. */
112
- perPage: number;
113
- /** Total number of messages in the thread. */
114
- total: number;
115
- /** True when at least one older page is still available. */
116
- hasMore: boolean;
117
- }
128
+ export declare const MastraHistoryResponseSchema: z.ZodObject<{
129
+ uiMessages: z.ZodArray<z.ZodObject<{
130
+ id: z.ZodString;
131
+ role: z.ZodEnum<{
132
+ system: "system";
133
+ user: "user";
134
+ assistant: "assistant";
135
+ }>;
136
+ parts: z.ZodReadonly<z.ZodArray<z.ZodUnknown>>;
137
+ metadata: z.ZodOptional<z.ZodUnknown>;
138
+ }, z.core.$strip>>;
139
+ page: z.ZodNumber;
140
+ perPage: z.ZodNumber;
141
+ total: z.ZodNumber;
142
+ hasMore: z.ZodBoolean;
143
+ }, z.core.$strip>;
144
+ export type MastraHistoryResponse = z.infer<typeof MastraHistoryResponseSchema>;
118
145
  /**
119
- * Build the history URL for a given agent + page. Mirrors
120
- * {@link chatUrl}: the default agent uses the bare `historyPath`,
121
- * any other agent appends `/<encoded id>` to it. `page` and
122
- * `perPage` are appended as query parameters when provided.
146
+ * JSON payload returned by `DELETE ${basePath}/history`. Deletes
147
+ * every persisted message + workflow snapshot tied to the caller's
148
+ * thread, so the next chat turn starts from a clean slate. The
149
+ * session cookie that anchors the thread id is preserved so the
150
+ * caller doesn't lose its identity - only the contents go away.
151
+ *
152
+ * `ok` is always `true` on success; the response object is kept
153
+ * as a struct (vs a bare 204) so future fields (e.g. `deletedAt`,
154
+ * `messages`) can be added without bumping the contract.
155
+ *
156
+ * Fields:
157
+ * - `ok`: literal `true` on success.
158
+ * - `agentId`: agent whose history was cleared.
159
+ * - `threadId`: thread id that was wiped.
160
+ * - `cleared`: number of messages the thread held before
161
+ * deletion. Useful for client-side "cleared 12 messages"
162
+ * toasts; `0` is reported when the thread was already empty
163
+ * (call is idempotent).
123
164
  */
124
- export declare function historyUrl(config: Pick<MastraClientConfig, "historyPath" | "defaultAgent">, options?: {
125
- agentId?: string;
126
- page?: number;
127
- perPage?: number;
128
- }): string;
165
+ export declare const MastraClearHistoryResponseSchema: z.ZodObject<{
166
+ ok: z.ZodLiteral<true>;
167
+ agentId: z.ZodString;
168
+ threadId: z.ZodString;
169
+ cleared: z.ZodNumber;
170
+ }, z.core.$strip>;
171
+ export type MastraClearHistoryResponse = z.infer<typeof MastraClearHistoryResponseSchema>;
package/dist/src/protocol.js CHANGED
@@ -1,13 +1,18 @@
1
1
  /**
2
- * Shape of the data published by {@link MastraPlugin.clientConfig} plus
3
- * a tiny URL helper. Kept dependency-free so the React client can
4
- * import it without dragging in `pg`, `fastembed`, or Mastra itself.
2
+ * Shape of the data published by {@link MastraPlugin.clientConfig}.
3
+ * Kept dependency-free (no `pg`, no `fastembed`, no Mastra runtime)
4
+ * so the React client can import these schemas without dragging in
5
+ * server-only dependencies.
5
6
  *
6
- * Server-side, `MastraPlugin` derives every path from the plugin mount
7
- * (AppKit conventionally serves plugin `foo` at `/api/foo`). Publishing
8
- * the resolved paths lets the client compute URLs without hard-coding
9
- * `/api/mastra` anywhere - rename the plugin and the React client
10
- * keeps working.
7
+ * Server-side, `MastraPlugin` derives every path from the plugin
8
+ * mount (AppKit conventionally serves plugin `foo` at `/api/foo`).
9
+ * Publishing the resolved paths lets the client compute URLs
10
+ * without hard-coding `/api/mastra` anywhere - rename the plugin
11
+ * and the React client keeps working.
12
+ *
13
+ * URL helpers ({@link chatUrl}, {@link historyUrl}) live in the
14
+ * sibling `mastra.ts` module so this file stays purely declarative
15
+ * (schemas + inferred types only).
11
16
  *
12
17
  * @example
13
18
  * ```tsx
@@ -20,35 +25,126 @@
20
25
  * });
21
26
  * ```
22
27
  */
28
+ import { z } from "zod";
29
+ /* ---------------------------- client config ---------------------------- */
30
+ /**
31
+ * JSON-safe descriptor published by the Mastra plugin's
32
+ * `clientConfig()`.
33
+ *
34
+ * Fields:
35
+ * - `basePath`: plugin mount path. Always `/api/<pluginName>`.
36
+ * - `chatPath`: chat endpoint for the **default** agent, i.e.
37
+ * `${basePath}/route/chat`. Equivalent to `chatUrl(config)`.
38
+ * - `chatPathTemplate`: template form used by the route handler:
39
+ * `${basePath}/route/chat/:agentId`. Provided for documentation
40
+ * / tools that want the OpenAPI-style placeholder; clients
41
+ * should normally call {@link chatUrl} instead.
42
+ * - `modelsPath`: models catalogue endpoint: `${basePath}/models`.
43
+ * - `historyPath`: thread history endpoint for the **default**
44
+ * agent: `${basePath}/route/history`. Returns AI SDK V5
45
+ * `UIMessage`s for the current session's thread; takes `page`
46
+ * and `perPage` query params. See {@link historyUrl}.
47
+ * - `historyPathTemplate`: templated form of `historyPath`:
48
+ * `${basePath}/route/history/:agentId`. Use this to reach a
49
+ * non-default agent's history; clients should normally call
50
+ * {@link historyUrl} instead.
51
+ * - `defaultAgent`: agent id `chatRoute` binds to when the client
52
+ * doesn't name one.
53
+ * - `agents`: every registered agent id in registration order.
54
+ */
55
+ export const MastraClientConfigSchema = z.object({
56
+ basePath: z.string(),
57
+ chatPath: z.string(),
58
+ chatPathTemplate: z.string(),
59
+ modelsPath: z.string(),
60
+ historyPath: z.string(),
61
+ historyPathTemplate: z.string(),
62
+ defaultAgent: z.string(),
63
+ agents: z.array(z.string()),
64
+ });
65
+ /* ---------------------------- model catalogue ---------------------------- */
66
+ /**
67
+ * Minimal descriptor for a Databricks Model Serving endpoint.
68
+ * Mirrors the server-side `ServingEndpointSummary` from `serving.ts`
69
+ * and is kept here so the React client can type the `/models`
70
+ * response without importing the full plugin (which would pull in
71
+ * `pg`, `fastembed`, and Mastra itself).
72
+ *
73
+ * Fields:
74
+ * - `name`: endpoint name as listed by the Model Serving REST API.
75
+ * - `task`: task hint (e.g. `"llm/v1/chat"`). Useful for filtering.
76
+ * - `state`: ready / updating / failed state.
77
+ * - `description`: free-form description; mostly informational.
78
+ */
79
+ export const ServingEndpointSummarySchema = z.object({
80
+ name: z.string(),
81
+ task: z.string().optional(),
82
+ state: z.string().optional(),
83
+ description: z.string().optional(),
84
+ });
85
+ /** JSON payload returned by `GET ${basePath}/models`. */
86
+ export const ServingEndpointsResponseSchema = z.object({
87
+ endpoints: z.array(ServingEndpointSummarySchema),
88
+ });
89
+ /* ----------------------------- chat history ----------------------------- */
90
+ /**
91
+ * Structural shape for an AI SDK V5 `UIMessage`. Defined locally
92
+ * so the shared types package stays dependency-free (no `ai`
93
+ * import). The runtime values returned by the `/history` endpoint
94
+ * are produced by `toAISdkV5Messages` and are 1:1 compatible with
95
+ * `UIMessage` from the `ai` package; clients can safely cast when
96
+ * needed.
97
+ */
98
+ export const MastraHistoryUIMessageSchema = z.object({
99
+ id: z.string(),
100
+ role: z.enum(["system", "user", "assistant"]),
101
+ parts: z.array(z.unknown()).readonly(),
102
+ metadata: z.unknown().optional(),
103
+ });
23
104
  /**
24
- * Compute the chat URL for a given agent, falling back to the default
25
- * when `agentId` is omitted. Returns `config.chatPath` directly for
26
- * the default agent (the `chatRoute` mount that does not require an
27
- * `:agentId` segment).
105
+ * JSON payload returned by `GET ${basePath}/history`.
106
+ *
107
+ * Fields:
108
+ * - `uiMessages`: page of UI-formatted messages, oldest -> newest.
109
+ * Always chronological regardless of the underlying pagination
110
+ * order so the client can prepend the array to the live
111
+ * transcript without sorting.
112
+ * - `page`: zero-indexed page that produced this response.
113
+ * - `perPage`: number of items requested per page.
114
+ * - `total`: total number of messages in the thread.
115
+ * - `hasMore`: true when at least one older page is still
116
+ * available.
28
117
  */
29
- export function chatUrl(config, agentId) {
30
- const id = agentId ?? config.defaultAgent;
31
- if (!id || id === config.defaultAgent)
32
- return config.chatPath;
33
- return `${config.chatPath}/${encodeURIComponent(id)}`;
34
- }
118
+ export const MastraHistoryResponseSchema = z.object({
119
+ uiMessages: z.array(MastraHistoryUIMessageSchema),
120
+ page: z.number(),
121
+ perPage: z.number(),
122
+ total: z.number(),
123
+ hasMore: z.boolean(),
124
+ });
35
125
  /**
36
- * Build the history URL for a given agent + page. Mirrors
37
- * {@link chatUrl}: the default agent uses the bare `historyPath`,
38
- * any other agent appends `/<encoded id>` to it. `page` and
39
- * `perPage` are appended as query parameters when provided.
126
+ * JSON payload returned by `DELETE ${basePath}/history`. Deletes
127
+ * every persisted message + workflow snapshot tied to the caller's
128
+ * thread, so the next chat turn starts from a clean slate. The
129
+ * session cookie that anchors the thread id is preserved so the
130
+ * caller doesn't lose its identity - only the contents go away.
131
+ *
132
+ * `ok` is always `true` on success; the response object is kept
133
+ * as a struct (vs a bare 204) so future fields (e.g. `deletedAt`,
134
+ * `messages`) can be added without bumping the contract.
135
+ *
136
+ * Fields:
137
+ * - `ok`: literal `true` on success.
138
+ * - `agentId`: agent whose history was cleared.
139
+ * - `threadId`: thread id that was wiped.
140
+ * - `cleared`: number of messages the thread held before
141
+ * deletion. Useful for client-side "cleared 12 messages"
142
+ * toasts; `0` is reported when the thread was already empty
143
+ * (call is idempotent).
40
144
  */
41
- export function historyUrl(config, options = {}) {
42
- const id = options.agentId ?? config.defaultAgent;
43
- const base = !id || id === config.defaultAgent
44
- ? config.historyPath
45
- : `${config.historyPath}/${encodeURIComponent(id)}`;
46
- const params = new URLSearchParams();
47
- if (options.page !== undefined)
48
- params.set("page", String(options.page));
49
- if (options.perPage !== undefined) {
50
- params.set("perPage", String(options.perPage));
51
- }
52
- const qs = params.toString();
53
- return qs ? `${base}?${qs}` : base;
54
- }
145
+ export const MastraClearHistoryResponseSchema = z.object({
146
+ ok: z.literal(true),
147
+ agentId: z.string(),
148
+ threadId: z.string(),
149
+ cleared: z.number(),
150
+ });