@dbx-tools/shared-mastra 0.3.44 → 0.4.1

package/lib/src/wire.d.ts

@@ -0,0 +1,877 @@
+/**
+ * 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`.
+ *
+ * @module
+ */
+import { genieModel } from "@dbx-tools/shared-genie";
+import { model } from "@dbx-tools/shared-model";
+import { z } from "zod";
+/**
+ * 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 declare const MastraClientConfigSchema: z.ZodObject<{
+    basePath: z.ZodString;
+    defaultAgent: z.ZodString;
+    agents: z.ZodArray<z.ZodString>;
+    feedbackEnabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type MastraClientConfig = z.infer<typeof MastraClientConfigSchema>;
+/**
+ * JSON payload returned by `GET ${basePath}/default-model[?agentId=]`. The
+ * static default model the agent resolves to when the client pins no model,
+ * as both the raw serving-endpoint `model` id and a `displayName` (the
+ * humanized label the picker shows). Both are `null` when the agent decides
+ * its model dynamically at call time (nothing static to advertise). Lets the
+ * picker label its default option WITHOUT waiting on the `/models` catalogue,
+ * so it never flashes a raw id on load. Kept off the static bootstrap
+ * `clientConfig` on purpose: it is per-agent and can be dynamic, so it is
+ * fetched like `/models`.
+ */
+export declare const DefaultModelResponseSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type DefaultModelResponse = z.infer<typeof DefaultModelResponseSchema>;
+/**
+ * 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 declare const ServingEndpointsResponseSchema: z.ZodObject<{
+    endpoints: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        task: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        profile: z.ZodOptional<z.ZodObject<{
+            quality: z.ZodOptional<z.ZodNumber>;
+            speed: z.ZodOptional<z.ZodNumber>;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        class: z.ZodOptional<z.ZodEnum<typeof model.ModelClass>>;
+        dimension: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ServingEndpointsResponse = z.infer<typeof ServingEndpointsResponseSchema>;
+/**
+ * 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 declare const MastraHistoryUIMessageSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        system: "system";
+        user: "user";
+        assistant: "assistant";
+    }>;
+    parts: z.ZodReadonly<z.ZodArray<z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+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 declare const MastraHistoryResponseSchema: z.ZodObject<{
+    uiMessages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        parts: z.ZodReadonly<z.ZodArray<z.ZodUnknown>>;
+        metadata: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+    total: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+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 declare const MastraClearHistoryResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    agentId: z.ZodString;
+    threadId: z.ZodString;
+    cleared: z.ZodNumber;
+}, z.core.$strip>;
+export type MastraClearHistoryResponse = z.infer<typeof MastraClearHistoryResponseSchema>;
+/**
+ * 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 declare const MastraThreadSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    resourceId: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    metadata: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+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 declare const MastraThreadsResponseSchema: z.ZodObject<{
+    threads: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        resourceId: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        metadata: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>;
+    page: z.ZodNumber;
+    perPage: z.ZodNumber;
+    total: z.ZodNumber;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;
+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 declare const MastraDeleteThreadResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    agentId: z.ZodString;
+    threadId: z.ZodString;
+    deleted: z.ZodBoolean;
+}, z.core.$strip>;
+export type MastraDeleteThreadResponse = z.infer<typeof MastraDeleteThreadResponseSchema>;
+/** Longest thread title the rename route accepts (trimmed server-side). */
+export declare 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 declare const MastraUpdateThreadRequestSchema: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strip>;
+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 declare const MastraUpdateThreadResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    agentId: z.ZodString;
+    thread: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        resourceId: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        metadata: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MastraUpdateThreadResponse = z.infer<typeof MastraUpdateThreadResponseSchema>;
+/**
+ * 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 declare const MastraSuggestionsResponseSchema: z.ZodObject<{
+    questions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type MastraSuggestionsResponse = z.infer<typeof MastraSuggestionsResponseSchema>;
+/**
+ * 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 declare const ChartTypeSchema: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+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 declare const ChartResultSchema: z.ZodObject<{
+    chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+    option: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+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 declare const ChartSchema: z.ZodObject<{
+    chartId: z.ZodString;
+    error: z.ZodOptional<z.ZodString>;
+    result: z.ZodOptional<z.ZodObject<{
+        chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+        option: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Chart = z.infer<typeof ChartSchema>;
+/**
+ * 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 declare const StatementDataSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    rowCount: z.ZodNumber;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+export type StatementData = z.infer<typeof StatementDataSchema>;
+/**
+ * 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 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 declare const StartedEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"started">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+}, z.core.$strip>;
+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 declare const AskGenieDoneEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ask_genie_done">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    answer: z.ZodOptional<z.ZodString>;
+    statementIds: z.ZodArray<z.ZodString>;
+    status: z.ZodCustom<"ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED", "ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED">;
+}, z.core.$strip>;
+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 declare const MastraGenieErrorEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    spaceId: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    error: z.ZodString;
+}, z.core.$strip>;
+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 declare const SummaryEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"summary">;
+    spaceId: z.ZodString;
+    items: z.ZodNumber;
+    textItems: z.ZodNumber;
+    dataItems: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const GenieAgentEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"started">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ask_genie_done">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    answer: z.ZodOptional<z.ZodString>;
+    statementIds: z.ZodArray<z.ZodString>;
+    status: z.ZodCustom<"ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED", "ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    spaceId: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"summary">;
+    spaceId: z.ZodString;
+    items: z.ZodNumber;
+    textItems: z.ZodNumber;
+    dataItems: z.ZodNumber;
+}, z.core.$strip>], "type">;
+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 declare const GenieWriterEventSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    conversation_id: z.ZodOptional<z.ZodString>;
+    space_id: z.ZodString;
+    message_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"question">;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    conversation_id: z.ZodOptional<z.ZodString>;
+    space_id: z.ZodString;
+    message_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"message">;
+    message: z.ZodObject<{
+        content: z.ZodString;
+        conversation_id: z.ZodString;
+        created_timestamp: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodObject<{
+            error: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_CLIENT_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_NETWORK_EXCEPTION">, z.ZodLiteral<"CONTENT_FILTER_EXCEPTION">, z.ZodLiteral<"CONTEXT_EXCEEDED_EXCEPTION">, z.ZodLiteral<"COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION">, z.ZodLiteral<"COULD_NOT_GET_UC_SCHEMA_EXCEPTION">, z.ZodLiteral<"DEPLOYMENT_NOT_FOUND_EXCEPTION">, z.ZodLiteral<"DESCRIBE_QUERY_INVALID_SQL_ERROR">, z.ZodLiteral<"DESCRIBE_QUERY_TIMEOUT">, z.ZodLiteral<"DESCRIBE_QUERY_UNEXPECTED_FAILURE">, z.ZodLiteral<"EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION">, z.ZodLiteral<"FUNCTIONS_NOT_AVAILABLE_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION">, z.ZodLiteral<"FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION">, z.ZodLiteral<"GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION">, z.ZodLiteral<"GENERIC_CHAT_COMPLETION_EXCEPTION">, z.ZodLiteral<"GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION">, z.ZodLiteral<"GENERIC_SQL_EXEC_API_CALL_EXCEPTION">, z.ZodLiteral<"ILLEGAL_PARAMETER_DEFINITION_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION">, z.ZodLiteral<"INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION">, z.ZodLiteral<"INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION">, z.ZodLiteral<"INVALID_CHAT_COMPLETION_ARGUMENTS_JSON_EXCEPTION">, z.ZodLiteral<"INVALID_CHAT_COMPLETION_JSON_EXCEPTION">, z.ZodLiteral<"INVALID_COMPLETION_REQUEST_EXCEPTION">, z.ZodLiteral<"INVALID_FUNCTION_CALL_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_UNKNOWN_TABLE_EXCEPTION">, z.ZodLiteral<"INVALID_TABLE_IDENTIFIER_EXCEPTION">, z.ZodLiteral<"LOCAL_CONTEXT_EXCEEDED_EXCEPTION">, z.ZodLiteral<"MESSAGE_ATTACHMENT_TOO_LONG_ERROR">, z.ZodLiteral<"MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MISSING_SQL_QUERY_EXCEPTION">, z.ZodLiteral<"NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE">, z.ZodLiteral<"NO_QUERY_TO_VISUALIZE_EXCEPTION">, z.ZodLiteral<"NO_TABLES_TO_QUERY_EXCEPTION">, z.ZodLiteral<"RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION">, z.ZodLiteral<"RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION">, z.ZodLiteral<"REPLY_PROCESS_TIMEOUT_EXCEPTION">, z.ZodLiteral<"RETRYABLE_PROCESSING_EXCEPTION">, z.ZodLiteral<"SQL_EXECUTION_EXCEPTION">, z.ZodLiteral<"STOP_PROCESS_DUE_TO_AUTO_REGENERATE">, z.ZodLiteral<"TABLES_MISSING_EXCEPTION">, z.ZodLiteral<"TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION">, z.ZodLiteral<"TOO_MANY_TABLES_EXCEPTION">, z.ZodLiteral<"UNEXPECTED_REPLY_PROCESS_EXCEPTION">, z.ZodLiteral<"UNKNOWN_AI_MODEL">, z.ZodLiteral<"UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION">, z.ZodLiteral<"WAREHOUSE_ACCESS_MISSING_EXCEPTION">, z.ZodLiteral<"WAREHOUSE_NOT_FOUND_EXCEPTION">]>>;
+        }, z.core.$strip>>;
+        feedback: z.ZodOptional<z.ZodObject<{
+            rating: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"NEGATIVE">, z.ZodLiteral<"NONE">, z.ZodLiteral<"POSITIVE">]>>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        last_updated_timestamp: z.ZodOptional<z.ZodNumber>;
+        message_id: z.ZodString;
+        query_result: z.ZodOptional<z.ZodObject<{
+            is_truncated: z.ZodOptional<z.ZodBoolean>;
+            row_count: z.ZodOptional<z.ZodNumber>;
+            statement_id: z.ZodOptional<z.ZodString>;
+            statement_id_signature: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        space_id: z.ZodString;
+        status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ASKING_AI">, z.ZodLiteral<"CANCELLED">, z.ZodLiteral<"COMPLETED">, z.ZodLiteral<"EXECUTING_QUERY">, z.ZodLiteral<"FAILED">, z.ZodLiteral<"FETCHING_METADATA">, z.ZodLiteral<"FILTERING_CONTEXT">, z.ZodLiteral<"PENDING_WAREHOUSE">, z.ZodLiteral<"QUERY_RESULT_EXPIRED">, z.ZodLiteral<"SUBMITTED">]>>;
+        user_id: z.ZodOptional<z.ZodNumber>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            attachment_id: z.ZodOptional<z.ZodString>;
+            suggested_questions: z.ZodOptional<z.ZodObject<{
+                questions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            text: z.ZodOptional<z.ZodObject<{
+                content: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                purpose: z.ZodOptional<z.ZodLiteral<"FOLLOW_UP_QUESTION">>;
+            }, z.core.$strip>>;
+            query: z.ZodOptional<z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                last_updated_timestamp: z.ZodOptional<z.ZodNumber>;
+                parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    keyword: z.ZodOptional<z.ZodString>;
+                    sql_type: z.ZodOptional<z.ZodString>;
+                    value: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                query: z.ZodOptional<z.ZodString>;
+                query_result_metadata: z.ZodOptional<z.ZodObject<{
+                    is_truncated: z.ZodOptional<z.ZodBoolean>;
+                    row_count: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                statement_id: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                thoughts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    thought_type: z.ZodCustom<genieModel.GenieThoughtType, genieModel.GenieThoughtType>;
+                    content: z.ZodString;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            attachment_type: z.ZodOptional<z.ZodCustom<genieModel.AttachmentType, genieModel.AttachmentType>>;
+        }, z.core.$strip>>>;
+        auto_regenerate_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    conversation_id: z.ZodOptional<z.ZodString>;
+    space_id: z.ZodString;
+    message_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"status">;
+    status: z.ZodUnion<readonly [z.ZodLiteral<"ASKING_AI">, z.ZodLiteral<"CANCELLED">, z.ZodLiteral<"COMPLETED">, z.ZodLiteral<"EXECUTING_QUERY">, z.ZodLiteral<"FAILED">, z.ZodLiteral<"FETCHING_METADATA">, z.ZodLiteral<"FILTERING_CONTEXT">, z.ZodLiteral<"PENDING_WAREHOUSE">, z.ZodLiteral<"QUERY_RESULT_EXPIRED">, z.ZodLiteral<"SUBMITTED">]>;
+    previous_status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ASKING_AI">, z.ZodLiteral<"CANCELLED">, z.ZodLiteral<"COMPLETED">, z.ZodLiteral<"EXECUTING_QUERY">, z.ZodLiteral<"FAILED">, z.ZodLiteral<"FETCHING_METADATA">, z.ZodLiteral<"FILTERING_CONTEXT">, z.ZodLiteral<"PENDING_WAREHOUSE">, z.ZodLiteral<"QUERY_RESULT_EXPIRED">, z.ZodLiteral<"SUBMITTED">]>>;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"attachment">;
+    index: z.ZodNumber;
+    attachment_type: z.ZodCustom<genieModel.AttachmentType, genieModel.AttachmentType>;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"thinking">;
+    text: z.ZodString;
+    thought_type: z.ZodCustom<genieModel.GenieThoughtType, genieModel.GenieThoughtType>;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"query">;
+    sql: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"statement">;
+    statement_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"rows">;
+    row_count: z.ZodNumber;
+    previous_row_count: z.ZodOptional<z.ZodNumber>;
+    statement_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    space_id: z.ZodString;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    message_id: z.ZodOptional<z.ZodString>;
+    attachment_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"suggested_questions">;
+    questions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    conversation_id: z.ZodOptional<z.ZodString>;
+    space_id: z.ZodString;
+    message_id: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"result">;
+    status: z.ZodEnum<{
+        CANCELLED: "CANCELLED";
+        COMPLETED: "COMPLETED";
+        FAILED: "FAILED";
+    }>;
+    message: z.ZodObject<{
+        content: z.ZodString;
+        conversation_id: z.ZodString;
+        created_timestamp: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodObject<{
+            error: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_CLIENT_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION">, z.ZodLiteral<"CHAT_COMPLETION_NETWORK_EXCEPTION">, z.ZodLiteral<"CONTENT_FILTER_EXCEPTION">, z.ZodLiteral<"CONTEXT_EXCEEDED_EXCEPTION">, z.ZodLiteral<"COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION">, z.ZodLiteral<"COULD_NOT_GET_UC_SCHEMA_EXCEPTION">, z.ZodLiteral<"DEPLOYMENT_NOT_FOUND_EXCEPTION">, z.ZodLiteral<"DESCRIBE_QUERY_INVALID_SQL_ERROR">, z.ZodLiteral<"DESCRIBE_QUERY_TIMEOUT">, z.ZodLiteral<"DESCRIBE_QUERY_UNEXPECTED_FAILURE">, z.ZodLiteral<"EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION">, z.ZodLiteral<"FUNCTIONS_NOT_AVAILABLE_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION">, z.ZodLiteral<"FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION">, z.ZodLiteral<"FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION">, z.ZodLiteral<"GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION">, z.ZodLiteral<"GENERIC_CHAT_COMPLETION_EXCEPTION">, z.ZodLiteral<"GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION">, z.ZodLiteral<"GENERIC_SQL_EXEC_API_CALL_EXCEPTION">, z.ZodLiteral<"ILLEGAL_PARAMETER_DEFINITION_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION">, z.ZodLiteral<"INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION">, z.ZodLiteral<"INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION">, z.ZodLiteral<"INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION">, z.ZodLiteral<"INVALID_CHAT_COMPLETION_ARGUMENTS_JSON_EXCEPTION">, z.ZodLiteral<"INVALID_CHAT_COMPLETION_JSON_EXCEPTION">, z.ZodLiteral<"INVALID_COMPLETION_REQUEST_EXCEPTION">, z.ZodLiteral<"INVALID_FUNCTION_CALL_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION">, z.ZodLiteral<"INVALID_SQL_UNKNOWN_TABLE_EXCEPTION">, z.ZodLiteral<"INVALID_TABLE_IDENTIFIER_EXCEPTION">, z.ZodLiteral<"LOCAL_CONTEXT_EXCEEDED_EXCEPTION">, z.ZodLiteral<"MESSAGE_ATTACHMENT_TOO_LONG_ERROR">, z.ZodLiteral<"MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION">, z.ZodLiteral<"MISSING_SQL_QUERY_EXCEPTION">, z.ZodLiteral<"NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE">, z.ZodLiteral<"NO_QUERY_TO_VISUALIZE_EXCEPTION">, z.ZodLiteral<"NO_TABLES_TO_QUERY_EXCEPTION">, z.ZodLiteral<"RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION">, z.ZodLiteral<"RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION">, z.ZodLiteral<"REPLY_PROCESS_TIMEOUT_EXCEPTION">, z.ZodLiteral<"RETRYABLE_PROCESSING_EXCEPTION">, z.ZodLiteral<"SQL_EXECUTION_EXCEPTION">, z.ZodLiteral<"STOP_PROCESS_DUE_TO_AUTO_REGENERATE">, z.ZodLiteral<"TABLES_MISSING_EXCEPTION">, z.ZodLiteral<"TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION">, z.ZodLiteral<"TOO_MANY_TABLES_EXCEPTION">, z.ZodLiteral<"UNEXPECTED_REPLY_PROCESS_EXCEPTION">, z.ZodLiteral<"UNKNOWN_AI_MODEL">, z.ZodLiteral<"UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION">, z.ZodLiteral<"WAREHOUSE_ACCESS_MISSING_EXCEPTION">, z.ZodLiteral<"WAREHOUSE_NOT_FOUND_EXCEPTION">]>>;
+        }, z.core.$strip>>;
+        feedback: z.ZodOptional<z.ZodObject<{
+            rating: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"NEGATIVE">, z.ZodLiteral<"NONE">, z.ZodLiteral<"POSITIVE">]>>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        last_updated_timestamp: z.ZodOptional<z.ZodNumber>;
+        message_id: z.ZodString;
+        query_result: z.ZodOptional<z.ZodObject<{
+            is_truncated: z.ZodOptional<z.ZodBoolean>;
+            row_count: z.ZodOptional<z.ZodNumber>;
+            statement_id: z.ZodOptional<z.ZodString>;
+            statement_id_signature: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        space_id: z.ZodString;
+        status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"ASKING_AI">, z.ZodLiteral<"CANCELLED">, z.ZodLiteral<"COMPLETED">, z.ZodLiteral<"EXECUTING_QUERY">, z.ZodLiteral<"FAILED">, z.ZodLiteral<"FETCHING_METADATA">, z.ZodLiteral<"FILTERING_CONTEXT">, z.ZodLiteral<"PENDING_WAREHOUSE">, z.ZodLiteral<"QUERY_RESULT_EXPIRED">, z.ZodLiteral<"SUBMITTED">]>>;
+        user_id: z.ZodOptional<z.ZodNumber>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            attachment_id: z.ZodOptional<z.ZodString>;
+            suggested_questions: z.ZodOptional<z.ZodObject<{
+                questions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            text: z.ZodOptional<z.ZodObject<{
+                content: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                purpose: z.ZodOptional<z.ZodLiteral<"FOLLOW_UP_QUESTION">>;
+            }, z.core.$strip>>;
+            query: z.ZodOptional<z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                last_updated_timestamp: z.ZodOptional<z.ZodNumber>;
+                parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    keyword: z.ZodOptional<z.ZodString>;
+                    sql_type: z.ZodOptional<z.ZodString>;
+                    value: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                query: z.ZodOptional<z.ZodString>;
+                query_result_metadata: z.ZodOptional<z.ZodObject<{
+                    is_truncated: z.ZodOptional<z.ZodBoolean>;
+                    row_count: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                statement_id: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                thoughts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    thought_type: z.ZodCustom<genieModel.GenieThoughtType, genieModel.GenieThoughtType>;
+                    content: z.ZodString;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+            attachment_type: z.ZodOptional<z.ZodCustom<genieModel.AttachmentType, genieModel.AttachmentType>>;
+        }, z.core.$strip>>>;
+        auto_regenerate_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"started">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ask_genie_done">;
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    answer: z.ZodOptional<z.ZodString>;
+    statementIds: z.ZodArray<z.ZodString>;
+    status: z.ZodCustom<"ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED", "ASKING_AI" | "CANCELLED" | "COMPLETED" | "EXECUTING_QUERY" | "FAILED" | "FETCHING_METADATA" | "FILTERING_CONTEXT" | "PENDING_WAREHOUSE" | "QUERY_RESULT_EXPIRED" | "SUBMITTED">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    spaceId: z.ZodOptional<z.ZodString>;
+    conversationId: z.ZodOptional<z.ZodString>;
+    messageId: z.ZodOptional<z.ZodString>;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"summary">;
+    spaceId: z.ZodString;
+    items: z.ZodNumber;
+    textItems: z.ZodNumber;
+    dataItems: z.ZodNumber;
+}, z.core.$strip>], "type">]>;
+export type GenieWriterEvent = z.infer<typeof GenieWriterEventSchema>;
+/** Discriminator type for {@link GenieWriterEvent}. */
+export type GenieWriterEventType = GenieWriterEvent["type"];
+/**
+ * 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 declare const GenieDatasetDataSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    rowCount: z.ZodNumber;
+}, z.core.$strip>;
+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` from the plugin's embed route (derived from
+ * `basePath` + {@link MASTRA_ROUTES}.embed, i.e. `/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 declare const GenieDatasetChartSchema: z.ZodObject<{
+    chartId: z.ZodString;
+    chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+}, z.core.$strip>;
+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 declare const GenieDatasetSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        columns: z.ZodArray<z.ZodString>;
+        rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        rowCount: z.ZodNumber;
+    }, z.core.$strip>;
+    chart: z.ZodOptional<z.ZodObject<{
+        chartId: z.ZodString;
+        chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const GenieSummaryItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"visualize">;
+    statementId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodObject<{
+        data: z.ZodObject<{
+            columns: z.ZodArray<z.ZodString>;
+            rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            rowCount: z.ZodNumber;
+        }, z.core.$strip>;
+        chart: z.ZodOptional<z.ZodObject<{
+            chartId: z.ZodString;
+            chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+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 declare const GenieAgentResultSchema: z.ZodObject<{
+    spaceId: z.ZodString;
+    conversationId: z.ZodOptional<z.ZodString>;
+    summary: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"string">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"visualize">;
+        statementId: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        dataset: z.ZodObject<{
+            data: z.ZodObject<{
+                columns: z.ZodArray<z.ZodString>;
+                rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                rowCount: z.ZodNumber;
+            }, z.core.$strip>;
+            chart: z.ZodOptional<z.ZodObject<{
+                chartId: z.ZodString;
+                chartType: z.ZodUnion<readonly [z.ZodLiteral<"bar">, z.ZodLiteral<"line">, z.ZodLiteral<"area">, z.ZodLiteral<"scatter">, z.ZodLiteral<"pie">]>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "type">>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GenieAgentResult = z.infer<typeof GenieAgentResultSchema>;