@dbx-tools/shared-genie

Browser-safe Genie schemas, event vocabulary, and snapshot diff helpers.

Validate Genie wire payloads and derive high-level UI events from raw message snapshots without importing the Databricks SDK. The Node driver that calls Genie is @dbx-tools/genie.

Quick Start

import { genieModel } from "@dbx-tools/shared-genie";

const response = genieModel.GenieResponseSchema.parse(await request.json());

Key features:

• Runtime schemas for Genie messages, responses, spaces, attachments, and statuses, including fields observed on the live wire.
• Forward-compatible Agent Mode SSE schemas plus a pure reducer that projects reasoning, SQL, Markdown output, structured table metadata, and terminal status into GenieMessage.
• A flat GenieChatEvent vocabulary for thinking, SQL, rows, result, status, and error rendering.
• Snapshot diff helpers that emit only newly observed semantic events.
• Attachment and status helpers for UI display logic.
• Browser-safe types that allow clients to validate Genie payloads without bundling Databricks SDK runtime code.
• Generated zod schemas for the upstream SDK Dashboard/Genie shapes, so validating an unwidened SDK payload needs no SDK import either.

Use With AppKit Genie Types

Use AppKit’s Genie plugin and UI types when you are building directly against the native AppKit Genie routes. Use this package when you need a browser-safe event vocabulary independent of AppKit transport:

• validating raw Genie messages captured from the Databricks SDK;
• replaying persisted snapshots into semantic events;
• sharing a flat event union between @dbx-tools/genie, @dbx-tools/appkit-mastra, and custom UI/tests;
• detecting attachment/status shapes that are present on the live wire but not always convenient in generated SDK types.

Validate Message Snapshots

import { genieModel } from "@dbx-tools/shared-genie";

const message = genieModel.GenieMessageSchema.parse(rawMessage);
const attachments = genieModel.GenieResponseSchema.parse(rawMessage);

The schemas extend generated Databricks SDK Genie types with fields observed on the wire, including query thoughts, attachment discriminators, and serialized space data.

Handle Typed Chat Events

import { type GenieChatEvent } from "@dbx-tools/shared-genie";

function render(event: GenieChatEvent) {
  switch (event.type) {
    case "thinking":
      return showThought(event.thought_type, event.text);
    case "query":
      return showSql(event.sql);
    case "result":
      return markDone(event.status);
  }
}

The event union is flat: every variant has type plus its own fields and shared location fields such as space_id, conversation_id, and message_id.

Derive Events From Snapshots

import { event } from "@dbx-tools/shared-genie";

for (const evt of event.eventsFromMessage(current, previous, spaceId)) {
  render(evt);
}

Use eventsFromMessage() when replaying persisted Genie messages, testing UI event handling, diffing Agent Mode or polling GenieMessage snapshots into the shared vocabulary, or building a custom polling loop. Individual detectors are also exported for targeted checks: detectStatus, detectThinking, detectQuery, detectRows, and the other event-specific helpers.

Work With Status And Attachments

import { genieModel } from "@dbx-tools/shared-genie";

if (genieModel.isTerminalStatus(message.status)) {
  console.log(genieModel.humanizeStatus(message.status));
}

const kind = genieModel.detectAttachmentType(message.attachments?.[0]);

humanizeStatus() is the shared display-label function. detectAttachmentType() lets consumers switch on query, text, or suggested_questions instead of probing optional fields.

Event Model

The event detector compares the current Genie message with the previous snapshot from the same turn. This keeps streaming UIs from re-rendering duplicate thought or query fragments while still allowing full history replay from persisted raw messages. Consumers can use the full eventsFromMessage() helper or individual detectors when a test needs to assert one specific behavior.

Generated SDK Schemas

dashboards holds zod schemas generated from the upstream @databricks/sdk-experimental dashboards declarations. Import it when code needs to validate a raw Databricks Genie/Dashboard payload against the SDK’s own shape:

import { dashboards } from "@dbx-tools/shared-genie";

const space = dashboards.genieSpaceSchema.parse(rawSpace);

Most consumers want genieModel instead - those schemas are these shapes widened with the fields Genie actually sends. Reach for dashboards only when the unwidened SDK shape is the contract you mean.

The module is generated at synth time and is read-only: the dbxToolsConfig.codegenInputs field in package.json names the input declaration file. To change what is generated, change that input and re-synth; never hand-edit src/dashboards.ts. The SDK itself is a dev dependency, so importing this package pulls in zod only.

Modules

• agentMode - forward-compatible zod schemas plus the pure Agent Mode event reducer and GenieMessage projector, including inline table metadata.
• genieModel - Genie schemas, status helpers, attachment helpers, and event union schemas/types.
• event - event detector factory, individual detectors, and eventsFromMessage().
• dashboards - generated, read-only zod schemas and inferred types for the upstream SDK Dashboard/Genie shapes that genieModel extends.

Server-side streaming is in @dbx-tools/genie.

See more

Open the complete API reference