@dbx-tools/shared-genie 0.1.9

package/README.md

@@ -0,0 +1,113 @@
+# @dbx-tools/shared-genie
+
+Browser-safe Genie schemas, event vocabulary, and snapshot diff helpers.
+
+Import this package when a UI, test, or server component needs to validate Genie
+wire payloads or derive high-level events from raw Genie message snapshots
+without importing the Databricks SDK. The Node driver that calls Genie is
+[`@dbx-tools/node-genie`](../../node/genie).
+
+Key features:
+
+- Runtime schemas for Genie messages, responses, spaces, attachments, and
+  statuses, including fields observed on the live wire.
+- 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.
+
+## Why Not Just 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/node-genie`,
+  `@dbx-tools/node-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 Genie Wire Payloads
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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, 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
+
+```ts
+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.
+
+## Modules
+
+- `genieModel` - Genie schemas, status helpers, attachment helpers, and event
+  union schemas/types.
+- `event` - event detector factory, individual detectors, and
+  `eventsFromMessage()`.
+
+Server-side streaming is in [`@dbx-tools/node-genie`](../../node/genie).

package/index.ts

@@ -0,0 +1,7 @@
+// 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 event from "./src/event";
+export * as genieModel from "./src/genie-model";
+export type { MessageStatus, GenieThoughtType, GenieThought, KnownAttachmentType, AttachmentType, GenieQueryAttachment, GenieAttachment, GenieMessage, GenieResponse, GenieSpace, TerminalStatus, GenieChatLocation, QuestionEvent, MessageEvent, StatusEvent, AttachmentEvent, ThinkingEvent, TextEvent, QueryEvent, StatementEvent, RowsEvent, SuggestedQuestionsEvent, ResultEvent, GenieChatEvent, GenieChatEventType, GenieChatEventFields } from "./src/genie-model";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dbx-tools/shared-genie",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/shared/genie"
+  },
+  "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-sdk-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/event.ts

@@ -0,0 +1,350 @@
+/**
+ * Pure event-detection for `genieEventChat`. Given two
+ * `GenieMessage` snapshots (current + prior) and the surrounding
+ * `space_id`, derive the semantic deltas (status transitions, new
+ * attachments, new thoughts, SQL emission, warehouse submission,
+ * row-count progress, follow-up suggestions, text deltas) and
+ * yield them as typed {@link GenieChatEvent}s.
+ *
+ * Detectors are built through a single typed factory that ties
+ * each event's name to its scope (whole-message vs per-attachment)
+ * and payload shape, so a misnamed event or a payload that doesn't
+ * match its event fails to compile. An orchestrator walks the
+ * snapshot diff and yields every detector that fires in a stable
+ * order (status first, then per-attachment field deltas) so a
+ * subscriber that logs events as they arrive sees a sensible
+ * sequence.
+ *
+ * The module is intentionally pure: no `EventEmitter`, no `this`,
+ * no I/O, no module-level mutable state. The `message` and
+ * `result` events are NOT derived here - they belong to the chat
+ * lifecycle layer (the `genieEventChat` driver) because they track
+ * per-yield / per-turn-completion semantics rather than a
+ * field-level snapshot diff.
+ */
+
+import {
+  detectAttachmentType,
+  type GenieAttachment,
+  type GenieChatEvent,
+  type GenieChatEventFields,
+  type GenieChatEventType,
+  type GenieChatLocation,
+  type GenieMessage,
+  type GenieThought,
+} from "./genie-model";
+
+/* ----------------------------- contract ---------------------------- */
+
+/**
+ * What a single detector call returns: zero (`undefined`), one
+ * (fields object), or many (`fields[]`) events of the same type.
+ * Each result is the variant's payload fields **without** the
+ * `type` discriminator - the orchestrator stamps `type` when it
+ * yields the event.
+ */
+type DetectorResult<T extends GenieChatEventType> =
+  GenieChatEventFields<T> | GenieChatEventFields<T>[] | undefined;
+
+/**
+ * Where in the wire shape a given event is derived from. Drives
+ * which arguments `detect` receives. `"message"` events watch
+ * `GenieMessage` itself; `"attachment"` events watch one slot of
+ * `message.attachments[]`. `"lifecycle"` events (`message`,
+ * `result`) are emitted by the chat driver directly and can't be
+ * built with {@link eventDetector} - they have no diff signature.
+ */
+interface DetectorScope {
+  // Message-scoped: top-level field diff on `GenieMessage`.
+  status: "message";
+  // Per-attachment: field diff on one `GenieAttachment` slot.
+  attachment: "attachment";
+  thinking: "attachment";
+  text: "attachment";
+  query: "attachment";
+  statement: "attachment";
+  rows: "attachment";
+  suggested_questions: "attachment";
+  // Lifecycle: not derived via diff, handled by the chat driver.
+  question: "lifecycle";
+  message: "lifecycle";
+  result: "lifecycle";
+}
+
+/**
+ * `detect` callback signature for a given event type. Resolved
+ * from {@link DetectorScope}: `"message"` events get the top-level
+ * snapshot triple, `"attachment"` events get the per-slot quad,
+ * `"lifecycle"` events resolve to `never` (no diff-based detector
+ * exists for them).
+ */
+type DetectFn<T extends GenieChatEventType> = DetectorScope[T] extends "message"
+  ? (
+      current: GenieMessage,
+      previous: GenieMessage | undefined,
+      space_id: string,
+    ) => DetectorResult<T>
+  : DetectorScope[T] extends "attachment"
+    ? (
+        current: GenieAttachment,
+        previous: GenieAttachment | undefined,
+        location: GenieChatLocation,
+        index: number,
+      ) => DetectorResult<T>
+    : never;
+
+/**
+ * Typed detector for one event in the {@link GenieChatEvent}
+ * union. The `type` field is the event name; `detect`'s signature
+ * is picked from {@link DetectorScope} based on `T`.
+ */
+interface EventDetector<T extends GenieChatEventType> {
+  readonly type: T;
+  detect: DetectFn<T>;
+}
+
+/* ----------------------- detector factory ----------------------- */
+
+/**
+ * Build an {@link EventDetector}. Pass the event name as the
+ * literal first arg and the matching `detect` callback as the
+ * second. TS infers `T` from the literal, narrows `detect`'s
+ * signature accordingly, and types the return as
+ * `EventDetector<T>`.
+ *
+ * Build-time guarantees:
+ *
+ *   - `eventDetector("status2", ...)` fails - the name isn't in
+ *     {@link GenieChatEvent}.
+ *   - `eventDetector("status", attachmentArgsCallback)` fails -
+ *     `"status"` is message-scoped, so `detect` must take
+ *     `(GenieMessage, GenieMessage | undefined, string)`.
+ *   - Returning a `ThinkingEvent`-shaped fields object from a
+ *     `"status"` detector fails - the return type is constrained
+ *     to `DetectorResult<"status">`.
+ *
+ * Lifecycle event names (`"message"`, `"result"`) resolve `detect`
+ * to `never` and won't compile, which is intentional: those have
+ * no diff signature and are emitted directly by the chat driver.
+ */
+export function eventDetector<T extends GenieChatEventType>(
+  type: T,
+  detect: DetectFn<T>,
+): EventDetector<T> {
+  return { type, detect };
+}
+
+/* ---------------------------- detectors ---------------------------- */
+
+/** Top-level `message.status` transitioned. */
+export const detectStatus = eventDetector("status", (current, previous, space_id) => {
+  if (!current.status || current.status === previous?.status) return;
+  return {
+    status: current.status,
+    previous_status: previous?.status,
+    space_id,
+    conversation_id: current.conversation_id,
+    message_id: current.message_id,
+  };
+});
+
+/** First time we see an attachment slot. */
+export const detectAttachmentAdded = eventDetector(
+  "attachment",
+  (current, previous, location, index) => {
+    if (previous) return;
+    return {
+      ...location,
+      index,
+      attachment_type: detectAttachmentType(current),
+    };
+  },
+);
+
+/**
+ * One emit per new `(thought_type, content)` tuple on a query
+ * attachment. Value-based set diff: Genie can mutate existing
+ * thought slots in place (e.g. re-typing index 0 from
+ * `DATA_SOURCING` to `DESCRIPTION` while re-appending the
+ * original at index 1), so positional / append-only diff would
+ * miss re-types and double-count re-orders.
+ */
+export const detectThinking = eventDetector("thinking", (current, previous, location) => {
+  const currThoughts = current.query?.thoughts ?? [];
+  if (currThoughts.length === 0) return;
+  const seen = new Set((previous?.query?.thoughts ?? []).map(thoughtKey));
+  const out: GenieChatEventFields<"thinking">[] = [];
+  for (const t of currThoughts) {
+    const key = thoughtKey(t);
+    if (seen.has(key)) continue;
+    // Defensive: dedupe within a single snapshot in case Genie
+    // ever ships the same thought twice in one `thoughts[]`.
+    seen.add(key);
+    out.push({ ...location, text: t.content, thought_type: t.thought_type });
+  }
+  return out;
+});
+
+/** Text-attachment `content` appeared or changed. */
+export const detectText = eventDetector("text", (current, previous, location) => {
+  const curr = current.text?.content;
+  const prev = previous?.text?.content;
+  if (curr === undefined || curr === prev) return;
+  return { ...location, text: curr };
+});
+
+/** SQL transitioned undefined -> string, or changed. */
+export const detectQuery = eventDetector("query", (current, previous, location) => {
+  const curr = current.query?.query;
+  const prev = previous?.query?.query;
+  if (!curr || curr === prev) return;
+  return {
+    ...location,
+    sql: curr,
+    title: current.query?.title,
+    description: current.query?.description,
+  };
+});
+
+/** Warehouse-statement id assigned. */
+export const detectStatement = eventDetector("statement", (current, previous, location) => {
+  const curr = current.query?.statement_id;
+  const prev = previous?.query?.statement_id;
+  if (!curr || curr === prev) return;
+  return { ...location, statement_id: curr };
+});
+
+/**
+ * `row_count` changed - fires on every transition including the
+ * initial `undefined -> 0` and the post-execution `0 -> N`.
+ * Carries the statement id when available for correlation.
+ */
+export const detectRows = eventDetector("rows", (current, previous, location) => {
+  const curr = current.query?.query_result_metadata?.row_count;
+  const prev = previous?.query?.query_result_metadata?.row_count;
+  if (curr === undefined || curr === prev) return;
+  return {
+    ...location,
+    row_count: curr,
+    previous_row_count: prev,
+    statement_id: current.query?.statement_id ?? previous?.query?.statement_id,
+  };
+});
+
+/**
+ * Follow-up suggested-questions array appeared or changed.
+ * Compares JSON-stringified arrays so a length-preserving content
+ * rewrite still fires.
+ */
+export const detectSuggestedQuestions = eventDetector(
+  "suggested_questions",
+  (current, previous, location) => {
+    const curr = current.suggested_questions?.questions;
+    const prev = previous?.suggested_questions?.questions;
+    if (!curr || curr.length === 0) return;
+    if (JSON.stringify(curr) === JSON.stringify(prev)) return;
+    return { ...location, questions: curr };
+  },
+);
+
+/* --------------------------- orchestrator --------------------------- */
+
+/**
+ * Walk the diff between `current` and `previous` and yield every
+ * derived event the snapshot produced. Detector order mirrors
+ * Genie's wire ordering (status first, then per-attachment field
+ * deltas) so a subscriber that simply logs events as they arrive
+ * sees them in a sensible sequence.
+ *
+ * Caller responsibilities (not handled here):
+ *
+ *   - Yield `{ type: "message", message: current }` BEFORE
+ *     calling this, once per poll yield.
+ *   - Yield `{ type: "result", ... }` AFTER calling this when
+ *     `isTerminalStatus(current.status)` - per-turn lifecycle,
+ *     not a per-snapshot field diff.
+ *   - Decide what counts as a "fresh turn" and pass `undefined`
+ *     for `previous` on turn boundaries, so anonymous-attachment
+ *     state from a prior turn doesn't bleed in.
+ *
+ * Sync generator: the diff is pure CPU work, no awaits. Use
+ * `yield*` from an async generator to splice the events into a
+ * stream.
+ */
+export function* eventsFromMessage(
+  current: GenieMessage,
+  previous: GenieMessage | undefined,
+  space_id: string,
+): Generator<GenieChatEvent, void, void> {
+  // Stamp `type` onto each detector result and yield it. Returning
+  // a typed generator keeps the `yield*` callsite tidy. The double
+  // cast (`unknown` -> `GenieChatEvent`) is needed because the
+  // generic merge `{type: T} & GenieChatEventFields<T>` doesn't
+  // structurally narrow back to a discriminated-union member -
+  // each detector's runtime output is shaped correctly by
+  // construction, so the cast is sound.
+  function* emit<T extends GenieChatEventType>(
+    detector: EventDetector<T>,
+    result: DetectorResult<T>,
+  ): Generator<GenieChatEvent, void, void> {
+    if (result === undefined) return;
+    if (Array.isArray(result)) {
+      for (const fields of result) {
+        yield { type: detector.type, ...fields } as unknown as GenieChatEvent;
+      }
+    } else {
+      yield { type: detector.type, ...result } as unknown as GenieChatEvent;
+    }
+  }
+
+  // Message-scoped detectors run once per snapshot.
+  yield* emit(detectStatus, detectStatus.detect(current, previous, space_id));
+
+  // Per-attachment detectors run once per attachment slot.
+  const currAtts = current.attachments ?? [];
+  const prevAtts = previous?.attachments ?? [];
+  for (let i = 0; i < currAtts.length; i++) {
+    const curr = currAtts[i]!;
+    const prev = matchPrevAttachment(curr, prevAtts, i);
+    const location: GenieChatLocation = {
+      space_id,
+      conversation_id: current.conversation_id,
+      message_id: current.message_id,
+      attachment_id: curr.attachment_id,
+    };
+    yield* emit(detectAttachmentAdded, detectAttachmentAdded.detect(curr, prev, location, i));
+    yield* emit(detectThinking, detectThinking.detect(curr, prev, location, i));
+    yield* emit(detectText, detectText.detect(curr, prev, location, i));
+    yield* emit(detectQuery, detectQuery.detect(curr, prev, location, i));
+    yield* emit(detectStatement, detectStatement.detect(curr, prev, location, i));
+    yield* emit(detectRows, detectRows.detect(curr, prev, location, i));
+    yield* emit(detectSuggestedQuestions, detectSuggestedQuestions.detect(curr, prev, location, i));
+  }
+}
+
+/* ----------------------------- helpers ----------------------------- */
+
+/**
+ * Find the prior version of `curr` in `prevAtts`. Attachments
+ * with ids match by id (Genie keeps ids stable across polls);
+ * anonymous attachments (Genie's main-answer text doesn't get
+ * one) match positionally against an anonymous prev at the same
+ * index, so they don't accidentally bind to an id'd predecessor
+ * that happened to share the slot.
+ */
+function matchPrevAttachment(
+  curr: GenieAttachment,
+  prevAtts: GenieAttachment[],
+  i: number,
+): GenieAttachment | undefined {
+  if (curr.attachment_id) {
+    return prevAtts.find((a) => a.attachment_id === curr.attachment_id);
+  }
+  const p = prevAtts[i];
+  return p && !p.attachment_id ? p : undefined;
+}
+
+/** Stable key for {@link detectThinking}'s value-based set diff. */
+function thoughtKey(t: GenieThought): string {
+  return `${t.thought_type}|${t.content}`;
+}