@databricks/appkit 0.45.0 → 0.47.0

package/dist/type-generator/vite-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  ANALYTICS_TYPES_FILE,\n  generateFromEntryPoint,\n  TYPES_DIR,\n  TypegenFatalError,\n  TypegenSyntaxError,\n} from \"./index\";\nimport type { PreflightMode } from \"./preflight\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\n\n/**\n * How long the DEV background watcher waits for a STARTING warehouse to reach\n * RUNNING before giving up. Short relative to the CLI's preflight budget: this\n * is a best-effort \"regenerate once the warehouse warms up\" convenience, not a\n * gate, so we'd rather stop polling than hold a detached task open for minutes.\n */\nconst DEV_WAREHOUSE_WATCH_MAX_MS = 60_000;\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /**\n   * Path to the metric registry d.ts file (relative to client folder).\n   * Defaults to a sibling of `outFile`, computed by the generator.\n   */\n  mvOutFile?: string;\n  /** Folders to watch for changes. */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let outFile: string;\n  let mvOutFile: string | undefined;\n  let watchFolders: string[];\n\n  // Single-flight state for runGenerate(). `inFlight` is the promise of the\n  // currently-running drain (null when idle); `queued` records that a trigger\n  // arrived while a run was active so exactly ONE trailing run fires afterwards\n  // (latest-wins — coalesces any number of overlapping triggers into a single\n  // rerun). `queued` is read/cleared synchronously inside the drain loop so a\n  // trigger landing in any window is caught before the drain exits.\n  //\n  // `pendingMode` is the mode the next generate should run in (latest-wins, like\n  // `queued`): the foreground build runs non-blocking in dev (instant degrade)\n  // while the background warehouse watch runs blocking (real DESCRIBEs). A\n  // blocking watch trigger that lands while a non-blocking foreground run is in\n  // flight therefore still describes when its trailing run fires.\n  let inFlight: Promise<void> | null = null;\n  let queued = false;\n  let pendingMode: PreflightMode = \"non-blocking\";\n\n  // The currently-armed DEV background warehouse watch, if any. Aborting it\n  // stops a pending waitUntilRunning (server shutdown, or a newer arm replacing\n  // an older one).\n  let watchController: AbortController | null = null;\n\n  /**\n   * Generate types once in the given preflight {@link PreflightMode}. Never\n   * throws in dev (logs instead); in production it rethrows so the build fails.\n   * This is the un-guarded core — callers should go through {@link runGenerate}\n   * so concurrent triggers can't race-write the .d.ts.\n   *\n   * @param mode - preflight policy for this run. The foreground build passes a\n   *   NODE_ENV-derived mode (blocking in production, non-blocking in dev so it\n   *   degrades instantly); the background warehouse watch passes \"blocking\" so\n   *   its regenerate actually DESCRIBEs and lands real (non-degraded) types.\n   */\n  async function generateOnce(mode: PreflightMode) {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder: watchFolders[0],\n        warehouseId,\n        noCache: false,\n        mode,\n        mvOutFile,\n      });\n    } catch (error) {\n      // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n      // report in their message. Their stack frames and attached query arrays\n      // point into appkit internals and only add noise, so surface just the\n      // message — both when failing the prod build and when logging in dev.\n      const isTypegenError =\n        error instanceof TypegenSyntaxError ||\n        error instanceof TypegenFatalError;\n\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        if (isTypegenError) error.stack = error.message;\n        throw error;\n      }\n\n      if (isTypegenError) {\n        logger.error(\"%s\", error.message);\n      } else {\n        logger.error(\"Error generating types: %O\", error);\n      }\n    }\n  }\n\n  /**\n   * Single-flight wrapper around {@link generateOnce}. The initial build, the\n   * .sql watcher, and the DEV warehouse watch all route through here so they can\n   * never run typegen concurrently (which would race-write the .d.ts).\n   *\n   * If a run is already in flight, this does NOT start a second one — it records\n   * the requested mode and sets a trailing flag so exactly one more run fires\n   * after the current finishes, coalescing any number of overlapping triggers\n   * (latest-wins, including the mode: a blocking watch trigger that arrives mid\n   * non-blocking foreground run still describes when its trailing run fires).\n   *\n   * @param mode - preflight policy for this run. Recorded into `pendingMode`,\n   *   which the drain reads for each generate (latest trigger wins).\n   * @returns A promise that resolves when this trigger's work (including any\n   *   trailing run it scheduled) has completed.\n   */\n  function runGenerate(mode: PreflightMode): Promise<void> {\n    pendingMode = mode;\n\n    if (inFlight) {\n      // A run is active: remember that another trigger arrived and ride out the\n      // current run. One trailing run then covers all coalesced triggers and\n      // runs in the latest requested mode (recorded above).\n      queued = true;\n      return inFlight;\n    }\n\n    // Drain in a loop rather than recursing after a single queued-check: a\n    // trigger can land in the window between generateOnce() resolving and the\n    // check, so we re-test `queued` until it's clear. Critically, `inFlight` is\n    // cleared synchronously in the SAME tick as the final `queued === false`\n    // observation — never deferred to a .finally microtask — so there's no\n    // window where a trigger sees `inFlight` set but the drain has already\n    // decided to exit. The guard stays held for the whole drain, so concurrent\n    // triggers only ever set the flag; they never start a parallel generate.\n    const drain = async (): Promise<void> => {\n      while (true) {\n        queued = false;\n        // Snapshot the mode synchronously alongside clearing `queued` so a\n        // trigger landing during this generate is observed (via `queued`) on the\n        // next loop with its own mode, not silently dropped.\n        const runMode = pendingMode;\n        await generateOnce(runMode);\n        // Synchronous check + clear, atomic w.r.t. other (synchronous) callers.\n        if (!queued) {\n          inFlight = null;\n          return;\n        }\n      }\n    };\n\n    inFlight = drain();\n    return inFlight;\n  }\n\n  /**\n   * DEV-only: get the warehouse to RUNNING in the background and regenerate with\n   * real (non-degraded) types once it is — without blocking dev startup. The\n   * foreground build only ever degrades in dev (instant `unknown`/cached types),\n   * so this is what lands actual DESCRIBE results in the editor for EVERY\n   * reachable warehouse state, not just one that happens to already be warm.\n   *\n   * Post-probe behaviour by state:\n   *  - RUNNING → describe right away (the dev foreground degraded, so a running\n   *    warehouse would otherwise never get real types). `waitUntilRunning`\n   *    returns immediately for an already-running warehouse, then the blocking\n   *    regenerate fires.\n   *  - STARTING → it's already coming up; just wait for RUNNING, then describe.\n   *  - STOPPED / STOPPING → kick off a start, wait for RUNNING, then describe.\n   *  - DELETED / DELETING → return (a deleted warehouse can't be started, and\n   *    blocking typegen would treat it as fatal); leave the degraded types.\n   *\n   * No-op in production or without a warehouse id. Replaces any previously-armed\n   * watch (aborting it first). Fully self-contained: it never throws into the\n   * caller and never re-arms itself. The whole lifecycle is abortable via the\n   * shared {@link watchController} — its signal is threaded into\n   * `waitUntilRunning`, so a dev-server shutdown cancels a pending wait — and the\n   * regenerate routes through {@link runGenerate} so it can't race-write the\n   * .d.ts with the foreground degrade or a `.sql` re-trigger.\n   *\n   * The regenerate runs in \"blocking\" mode (not the foreground's non-blocking)\n   * so it actually DESCRIBEs the now-RUNNING warehouse and lands real types —\n   * the whole point of warming the warehouse in the background.\n   */\n  function armWarehouseWatch(): void {\n    if (process.env.NODE_ENV === \"production\") return;\n\n    const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n    if (!warehouseId) return;\n\n    // Supersede any in-flight watch so we never run two concurrently.\n    watchController?.abort();\n    const controller = new AbortController();\n    watchController = controller;\n    const { signal } = controller;\n\n    void (async () => {\n      try {\n        const client = new WorkspaceClient({});\n        const state = await getWarehouseState(client, warehouseId);\n\n        // A deleted/deleting warehouse can't be started and blocking typegen\n        // would treat it as fatal — leave the degraded types and stop. Every\n        // other state (including RUNNING) proceeds to wait-then-describe so the\n        // dev editor gets real types, not just the foreground's degraded ones.\n        if (state === \"DELETED\" || state === \"DELETING\") {\n          return;\n        }\n\n        // Stopped/stopping won't reach RUNNING on its own — nudge it. RUNNING and\n        // STARTING need no start (RUNNING is already up; STARTING is coming up),\n        // so don't issue a redundant one. A failed start is non-fatal: give up\n        // silently rather than throw out of the detached task (the developer\n        // still has degraded/cached types).\n        let startedByUs = false;\n        if (state === \"STOPPED\" || state === \"STOPPING\") {\n          try {\n            logger.debug(\"Warehouse is %s; starting it.\", state);\n            await startWarehouse(client, warehouseId);\n            startedByUs = true;\n          } catch {\n            return;\n          }\n        }\n\n        // Wait for RUNNING. For an already-RUNNING warehouse this returns on the\n        // first poll; for STARTING/STOPPED it polls (abortably) until the\n        // warehouse warms up, a terminal state, or the deadline.\n        const final = await waitUntilRunning(client, warehouseId, {\n          maxMs: DEV_WAREHOUSE_WATCH_MAX_MS,\n          signal,\n          // We just issued the start, so the first poll(s) often still report\n          // STOPPED/STOPPING before the start propagates. Poll through those\n          // instead of bailing, or the regenerate would never fire. When we\n          // didn't start it (RUNNING/STARTING branch), keep the default terminal\n          // states.\n          treatStoppedAsTransient: startedByUs,\n        });\n\n        if (final === \"RUNNING\" && !signal.aborted) {\n          logger.debug(\"Warehouse is RUNNING; regenerating types.\");\n          // Blocking: the warehouse is RUNNING now, so describe it and emit real\n          // (non-degraded) types — unlike the foreground dev run, which degraded.\n          // Routed through the single-flight guard so it coalesces with the\n          // foreground degrade / any `.sql` re-trigger instead of racing them.\n          await runGenerate(\"blocking\");\n        }\n      } catch {\n        // Detached background task: any failure (timeout, abort, connectivity,\n        // auth) is non-fatal — the developer still has degraded/cached types.\n      }\n    })();\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return false;\n      }\n\n      if (!existsSync(path.join(process.cwd(), \"config\", \"queries\"))) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      const projectRoot = path.resolve(config.root, \"..\");\n      outFile = path.resolve(\n        projectRoot,\n        options?.outFile ?? `shared/${TYPES_DIR}/${ANALYTICS_TYPES_FILE}`,\n      );\n      // The metric out-path resolves against projectRoot only when explicitly\n      // provided; an unset option passes through as undefined so the generator\n      // computes its sibling-of-outFile default. In the all-defaults case the\n      // final path is identical (the default outFile above lives in\n      // shared/<TYPES_DIR>/), and a customized outFile now keeps its metric\n      // sibling next to it instead of pinning it under shared/.\n      mvOutFile =\n        options?.mvOutFile !== undefined\n          ? path.resolve(projectRoot, options.mvOutFile)\n          : undefined;\n      watchFolders = options?.watchFolders ?? [\n        path.join(process.cwd(), \"config\", \"queries\"),\n      ];\n    },\n\n    buildStart() {\n      // Production: block the build on this generate (and surface failures).\n      // The watch is a dev-only no-op, so just run typegen.\n      if (process.env.NODE_ENV === \"production\") {\n        return runGenerate(\"blocking\");\n      }\n\n      // Dev: don't block startup waiting on typegen. The foreground generate runs\n      // non-blocking — it skips the warehouse entirely and writes degraded\n      // (cached/`unknown`) types instantly. Then arm the warehouse watch so the\n      // warehouse gets a one-shot BLOCKING regenerate (real types) in the\n      // background for EVERY reachable state: RUNNING describes right away, while\n      // STARTING/STOPPED are waited (and started) until they reach RUNNING.\n      void runGenerate(\"non-blocking\");\n      armWarehouseWatch();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        if (\n          isWatchedFile &&\n          (changedFile.endsWith(\".sql\") ||\n            // Basename equality, not endsWith: a sibling like\n            // \"legacy-metric-views.json\" must not trigger a regenerate —\n            // only the real config file does.\n            path.basename(changedFile) === \"metric-views.json\")\n        ) {\n          // Route through the single-flight runner (was fire-and-forget\n          // generate(), which could race the initial build / watch). This is a\n          // dev-only hook, so degrade instantly (non-blocking), then re-arm the\n          // warehouse watch so the edited query or metric-view source is\n          // re-described in the background against the running warehouse (or\n          // once a still-starting one warms up), landing fresh\n          // blocking-described types.\n          void runGenerate(\"non-blocking\");\n          armWarehouseWatch();\n        }\n      });\n\n      // Tear down any pending warehouse watch when the dev server closes so a\n      // long backoff can't keep the process alive after shutdown.\n      server.httpServer?.once(\"close\", () => {\n        watchController?.abort();\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;AAmBA,MAAM,SAAS,aAAa,6BAA6B;;;;;;;AAQzD,MAAM,6BAA6B;;;;;;;AAuBnC,SAAgB,kBAAkB,SAA4C;CAC5E,IAAI;CACJ,IAAI;CACJ,IAAI;CAcJ,IAAI,WAAiC;CACrC,IAAI,SAAS;CACb,IAAI,cAA6B;CAKjC,IAAI,kBAA0C;;;;;;;;;;;;CAa9C,eAAe,aAAa,MAAqB;AAC/C,MAAI;GACF,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAE3D,OAAI,CAAC,aAAa;AAChB,WAAO,MAAM,oDAAoD;AACjE;;AAGF,SAAM,uBAAuB;IAC3B;IACA,aAAa,aAAa;IAC1B;IACA,SAAS;IACT;IACA;IACD,CAAC;WACK,OAAO;GAKd,MAAM,iBACJ,iBAAiB,sBACjB,iBAAiB;AAGnB,OAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,QAAI,eAAgB,OAAM,QAAQ,MAAM;AACxC,UAAM;;AAGR,OAAI,eACF,QAAO,MAAM,MAAM,MAAM,QAAQ;OAEjC,QAAO,MAAM,8BAA8B,MAAM;;;;;;;;;;;;;;;;;;;CAqBvD,SAAS,YAAY,MAAoC;AACvD,gBAAc;AAEd,MAAI,UAAU;AAIZ,YAAS;AACT,UAAO;;EAWT,MAAM,QAAQ,YAA2B;AACvC,UAAO,MAAM;AACX,aAAS;AAKT,UAAM,aADU,YACW;AAE3B,QAAI,CAAC,QAAQ;AACX,gBAAW;AACX;;;;AAKN,aAAW,OAAO;AAClB,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCT,SAAS,oBAA0B;AACjC,MAAI,QAAQ,IAAI,aAAa,aAAc;EAE3C,MAAM,cAAc,QAAQ,IAAI,2BAA2B;AAC3D,MAAI,CAAC,YAAa;AAGlB,mBAAiB,OAAO;EACxB,MAAM,aAAa,IAAI,iBAAiB;AACxC,oBAAkB;EAClB,MAAM,EAAE,WAAW;AAEnB,GAAM,YAAY;AAChB,OAAI;IACF,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;IACtC,MAAM,QAAQ,MAAM,kBAAkB,QAAQ,YAAY;AAM1D,QAAI,UAAU,aAAa,UAAU,WACnC;IAQF,IAAI,cAAc;AAClB,QAAI,UAAU,aAAa,UAAU,WACnC,KAAI;AACF,YAAO,MAAM,iCAAiC,MAAM;AACpD,WAAM,eAAe,QAAQ,YAAY;AACzC,mBAAc;YACR;AACN;;AAkBJ,QAXc,MAAM,iBAAiB,QAAQ,aAAa;KACxD,OAAO;KACP;KAMA,yBAAyB;KAC1B,CAAC,KAEY,aAAa,CAAC,OAAO,SAAS;AAC1C,YAAO,MAAM,4CAA4C;AAKzD,WAAM,YAAY,WAAW;;WAEzB;MAIN;;AAGN,QAAO;EACL,MAAM;EAEN,QAAQ;AAGN,OAAI,EAFgB,QAAQ,IAAI,2BAA2B,KAEzC;AAChB,WAAO,MAAM,oDAAoD;AACjE,WAAO;;AAGT,OAAI,CAAC,WAAW,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAAC,CAC5D,QAAO;AAGT,UAAO;;EAGT,eAAe,QAAQ;GACrB,MAAM,cAAc,KAAK,QAAQ,OAAO,MAAM,KAAK;AACnD,aAAU,KAAK,QACb,aACA,SAAS,WAAW,UAAU,UAAU,GAAG,uBAC5C;AAOD,eACE,SAAS,cAAc,SACnB,KAAK,QAAQ,aAAa,QAAQ,UAAU,GAC5C;AACN,kBAAe,SAAS,gBAAgB,CACtC,KAAK,KAAK,QAAQ,KAAK,EAAE,UAAU,UAAU,CAC9C;;EAGH,aAAa;AAGX,OAAI,QAAQ,IAAI,aAAa,aAC3B,QAAO,YAAY,WAAW;AAShC,GAAK,YAAY,eAAe;AAChC,sBAAmB;;EAGrB,gBAAgB,QAAQ;AACtB,UAAO,QAAQ,IAAI,aAAa;AAEhC,UAAO,QAAQ,GAAG,WAAW,gBAAgB;AAK3C,QAJsB,aAAa,MAAM,WACvC,YAAY,WAAW,OAAO,CAC/B,KAIE,YAAY,SAAS,OAAO,IAI3B,KAAK,SAAS,YAAY,KAAK,sBACjC;AAQA,KAAK,YAAY,eAAe;AAChC,wBAAmB;;KAErB;AAIF,UAAO,YAAY,KAAK,eAAe;AACrC,qBAAiB,OAAO;KACxB;;EAEL"}
+{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { Plugin } from \"vite\";\nimport { METRIC_CONFIG_FILE } from \"../../../shared/src/schemas/metric-fqn\";\nimport { createLogger } from \"../logging/logger\";\nimport {\n  ANALYTICS_TYPES_FILE,\n  generateFromEntryPoint,\n  TYPES_DIR,\n  TypegenFatalError,\n  TypegenSyntaxError,\n} from \"./index\";\nimport type { PreflightMode } from \"./preflight\";\nimport {\n  getWarehouseState,\n  startWarehouse,\n  waitUntilRunning,\n} from \"./warehouse-status\";\n\nconst logger = createLogger(\"type-generator:vite-plugin\");\n\n/**\n * How long the DEV background watcher waits for a STARTING warehouse to reach\n * RUNNING before giving up. Short relative to the CLI's preflight budget: this\n * is a best-effort \"regenerate once the warehouse warms up\" convenience, not a\n * gate, so we'd rather stop polling than hold a detached task open for minutes.\n */\nconst DEV_WAREHOUSE_WATCH_MAX_MS = 60_000;\n\n/**\n * Options for the AppKit types plugin.\n */\ninterface AppKitTypesPluginOptions {\n  /* Path to the output d.ts file (relative to client folder). */\n  outFile?: string;\n  /**\n   * Path to the metric registry d.ts file (relative to client folder).\n   * Defaults to a sibling of `outFile`, computed by the generator.\n   */\n  mvOutFile?: string;\n  /**\n   * Folders to watch for changes. Defaults to `config/queries` and\n   * `config/metric-views`. When overridden, include a `queries` folder and/or a\n   * `metric-views` folder — they are resolved by their trailing path segment.\n   */\n  watchFolders?: string[];\n}\n\n/**\n * Vite plugin to generate types for AppKit queries.\n * Calls generateFromEntryPoint under the hood.\n * @param options - Options to override default values.\n * @returns Vite plugin to generate types for AppKit queries.\n */\nexport function appKitTypesPlugin(options?: AppKitTypesPluginOptions): Plugin {\n  let outFile: string;\n  let mvOutFile: string | undefined;\n  let watchFolders: string[];\n  // The queries + metric-views config folders, resolved in `configResolved`.\n  // Passed explicitly into generateFromEntryPoint so neither is inferred from\n  // `watchFolders` ordering (which used to assume queries was `watchFolders[0]`).\n  let queryFolder: string | undefined;\n  let metricViewsFolder: string | undefined;\n\n  // Single-flight state for runGenerate(). `inFlight` is the promise of the\n  // currently-running drain (null when idle); `queued` records that a trigger\n  // arrived while a run was active so exactly ONE trailing run fires afterwards\n  // (latest-wins — coalesces any number of overlapping triggers into a single\n  // rerun). `queued` is read/cleared synchronously inside the drain loop so a\n  // trigger landing in any window is caught before the drain exits.\n  //\n  // `pendingMode` is the mode the next generate should run in (latest-wins, like\n  // `queued`): the foreground build runs non-blocking in dev (instant degrade)\n  // while the background warehouse watch runs blocking (real DESCRIBEs). A\n  // blocking watch trigger that lands while a non-blocking foreground run is in\n  // flight therefore still describes when its trailing run fires.\n  let inFlight: Promise<void> | null = null;\n  let queued = false;\n  let pendingMode: PreflightMode = \"non-blocking\";\n\n  // The currently-armed DEV background warehouse watch, if any. Aborting it\n  // stops a pending waitUntilRunning (server shutdown, or a newer arm replacing\n  // an older one).\n  let watchController: AbortController | null = null;\n\n  /**\n   * Generate types once in the given preflight {@link PreflightMode}. Never\n   * throws in dev (logs instead); in production it rethrows so the build fails.\n   * This is the un-guarded core — callers should go through {@link runGenerate}\n   * so concurrent triggers can't race-write the .d.ts.\n   *\n   * @param mode - preflight policy for this run. The foreground build passes a\n   *   NODE_ENV-derived mode (blocking in production, non-blocking in dev so it\n   *   degrades instantly); the background warehouse watch passes \"blocking\" so\n   *   its regenerate actually DESCRIBEs and lands real (non-degraded) types.\n   */\n  async function generateOnce(mode: PreflightMode) {\n    try {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return;\n      }\n\n      await generateFromEntryPoint({\n        outFile,\n        queryFolder,\n        metricViewsFolder,\n        warehouseId,\n        noCache: false,\n        mode,\n        mvOutFile,\n      });\n    } catch (error) {\n      // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n      // report in their message. Their stack frames and attached query arrays\n      // point into appkit internals and only add noise, so surface just the\n      // message — both when failing the prod build and when logging in dev.\n      const isTypegenError =\n        error instanceof TypegenSyntaxError ||\n        error instanceof TypegenFatalError;\n\n      // throw in production to fail the build\n      if (process.env.NODE_ENV === \"production\") {\n        if (isTypegenError) error.stack = error.message;\n        throw error;\n      }\n\n      if (isTypegenError) {\n        logger.error(\"%s\", error.message);\n      } else {\n        logger.error(\"Error generating types: %O\", error);\n      }\n    }\n  }\n\n  /**\n   * Single-flight wrapper around {@link generateOnce}. The initial build, the\n   * .sql watcher, and the DEV warehouse watch all route through here so they can\n   * never run typegen concurrently (which would race-write the .d.ts).\n   *\n   * If a run is already in flight, this does NOT start a second one — it records\n   * the requested mode and sets a trailing flag so exactly one more run fires\n   * after the current finishes, coalescing any number of overlapping triggers\n   * (latest-wins, including the mode: a blocking watch trigger that arrives mid\n   * non-blocking foreground run still describes when its trailing run fires).\n   *\n   * @param mode - preflight policy for this run. Recorded into `pendingMode`,\n   *   which the drain reads for each generate (latest trigger wins).\n   * @returns A promise that resolves when this trigger's work (including any\n   *   trailing run it scheduled) has completed.\n   */\n  function runGenerate(mode: PreflightMode): Promise<void> {\n    pendingMode = mode;\n\n    if (inFlight) {\n      // A run is active: remember that another trigger arrived and ride out the\n      // current run. One trailing run then covers all coalesced triggers and\n      // runs in the latest requested mode (recorded above).\n      queued = true;\n      return inFlight;\n    }\n\n    // Drain in a loop rather than recursing after a single queued-check: a\n    // trigger can land in the window between generateOnce() resolving and the\n    // check, so we re-test `queued` until it's clear. Critically, `inFlight` is\n    // cleared synchronously in the SAME tick as the final `queued === false`\n    // observation — never deferred to a .finally microtask — so there's no\n    // window where a trigger sees `inFlight` set but the drain has already\n    // decided to exit. The guard stays held for the whole drain, so concurrent\n    // triggers only ever set the flag; they never start a parallel generate.\n    const drain = async (): Promise<void> => {\n      while (true) {\n        queued = false;\n        // Snapshot the mode synchronously alongside clearing `queued` so a\n        // trigger landing during this generate is observed (via `queued`) on the\n        // next loop with its own mode, not silently dropped.\n        const runMode = pendingMode;\n        await generateOnce(runMode);\n        // Synchronous check + clear, atomic w.r.t. other (synchronous) callers.\n        if (!queued) {\n          inFlight = null;\n          return;\n        }\n      }\n    };\n\n    inFlight = drain();\n    return inFlight;\n  }\n\n  /**\n   * DEV-only: get the warehouse to RUNNING in the background and regenerate with\n   * real (non-degraded) types once it is — without blocking dev startup. The\n   * foreground build only ever degrades in dev (instant `unknown`/cached types),\n   * so this is what lands actual DESCRIBE results in the editor for EVERY\n   * reachable warehouse state, not just one that happens to already be warm.\n   *\n   * Post-probe behaviour by state:\n   *  - RUNNING → describe right away (the dev foreground degraded, so a running\n   *    warehouse would otherwise never get real types). `waitUntilRunning`\n   *    returns immediately for an already-running warehouse, then the blocking\n   *    regenerate fires.\n   *  - STARTING → it's already coming up; just wait for RUNNING, then describe.\n   *  - STOPPED / STOPPING → kick off a start, wait for RUNNING, then describe.\n   *  - DELETED / DELETING → return (a deleted warehouse can't be started, and\n   *    blocking typegen would treat it as fatal); leave the degraded types.\n   *\n   * No-op in production or without a warehouse id. Replaces any previously-armed\n   * watch (aborting it first). Fully self-contained: it never throws into the\n   * caller and never re-arms itself. The whole lifecycle is abortable via the\n   * shared {@link watchController} — its signal is threaded into\n   * `waitUntilRunning`, so a dev-server shutdown cancels a pending wait — and the\n   * regenerate routes through {@link runGenerate} so it can't race-write the\n   * .d.ts with the foreground degrade or a `.sql` re-trigger.\n   *\n   * The regenerate runs in \"blocking\" mode (not the foreground's non-blocking)\n   * so it actually DESCRIBEs the now-RUNNING warehouse and lands real types —\n   * the whole point of warming the warehouse in the background.\n   */\n  function armWarehouseWatch(): void {\n    if (process.env.NODE_ENV === \"production\") return;\n\n    const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n    if (!warehouseId) return;\n\n    // Supersede any in-flight watch so we never run two concurrently.\n    watchController?.abort();\n    const controller = new AbortController();\n    watchController = controller;\n    const { signal } = controller;\n\n    void (async () => {\n      try {\n        const client = new WorkspaceClient({});\n        const state = await getWarehouseState(client, warehouseId);\n\n        // A deleted/deleting warehouse can't be started and blocking typegen\n        // would treat it as fatal — leave the degraded types and stop. Every\n        // other state (including RUNNING) proceeds to wait-then-describe so the\n        // dev editor gets real types, not just the foreground's degraded ones.\n        if (state === \"DELETED\" || state === \"DELETING\") {\n          return;\n        }\n\n        // Stopped/stopping won't reach RUNNING on its own — nudge it. RUNNING and\n        // STARTING need no start (RUNNING is already up; STARTING is coming up),\n        // so don't issue a redundant one. A failed start is non-fatal: give up\n        // silently rather than throw out of the detached task (the developer\n        // still has degraded/cached types).\n        let startedByUs = false;\n        if (state === \"STOPPED\" || state === \"STOPPING\") {\n          try {\n            logger.debug(\"Warehouse is %s; starting it.\", state);\n            await startWarehouse(client, warehouseId);\n            startedByUs = true;\n          } catch {\n            return;\n          }\n        }\n\n        // Wait for RUNNING. For an already-RUNNING warehouse this returns on the\n        // first poll; for STARTING/STOPPED it polls (abortably) until the\n        // warehouse warms up, a terminal state, or the deadline.\n        const final = await waitUntilRunning(client, warehouseId, {\n          maxMs: DEV_WAREHOUSE_WATCH_MAX_MS,\n          signal,\n          // We just issued the start, so the first poll(s) often still report\n          // STOPPED/STOPPING before the start propagates. Poll through those\n          // instead of bailing, or the regenerate would never fire. When we\n          // didn't start it (RUNNING/STARTING branch), keep the default terminal\n          // states.\n          treatStoppedAsTransient: startedByUs,\n        });\n\n        if (final === \"RUNNING\" && !signal.aborted) {\n          logger.debug(\"Warehouse is RUNNING; regenerating types.\");\n          // Blocking: the warehouse is RUNNING now, so describe it and emit real\n          // (non-degraded) types — unlike the foreground dev run, which degraded.\n          // Routed through the single-flight guard so it coalesces with the\n          // foreground degrade / any `.sql` re-trigger instead of racing them.\n          await runGenerate(\"blocking\");\n        }\n      } catch {\n        // Detached background task: any failure (timeout, abort, connectivity,\n        // auth) is non-fatal — the developer still has degraded/cached types.\n      }\n    })();\n  }\n\n  return {\n    name: \"appkit-types\",\n\n    apply() {\n      const warehouseId = process.env.DATABRICKS_WAREHOUSE_ID || \"\";\n\n      if (!warehouseId) {\n        logger.debug(\"Warehouse ID not found. Skipping type generation.\");\n        return false;\n      }\n\n      // Run when either config surface exists. Metric-view types are\n      // independent of `.sql` queries, so a metric-only project (a\n      // `config/metric-views/` with no `config/queries/`) must still activate\n      // the plugin.\n      const hasQueries = existsSync(\n        path.join(process.cwd(), \"config\", \"queries\"),\n      );\n      const hasMetricViews = existsSync(\n        path.join(process.cwd(), \"config\", \"metric-views\"),\n      );\n      if (!hasQueries && !hasMetricViews) {\n        return false;\n      }\n\n      return true;\n    },\n\n    configResolved(config) {\n      const projectRoot = path.resolve(config.root, \"..\");\n      outFile = path.resolve(\n        projectRoot,\n        options?.outFile ?? `shared/${TYPES_DIR}/${ANALYTICS_TYPES_FILE}`,\n      );\n      // The metric out-path resolves against projectRoot only when explicitly\n      // provided; an unset option passes through as undefined so the generator\n      // computes its sibling-of-outFile default. In the all-defaults case the\n      // final path is identical (the default outFile above lives in\n      // shared/<TYPES_DIR>/), and a customized outFile now keeps its metric\n      // sibling next to it instead of pinning it under shared/.\n      mvOutFile =\n        options?.mvOutFile !== undefined\n          ? path.resolve(projectRoot, options.mvOutFile)\n          : undefined;\n\n      const defaultQueryFolder = path.join(process.cwd(), \"config\", \"queries\");\n      const defaultMetricViewsFolder = path.join(\n        process.cwd(),\n        \"config\",\n        \"metric-views\",\n      );\n      watchFolders = options?.watchFolders ?? [\n        defaultQueryFolder,\n        defaultMetricViewsFolder,\n      ];\n\n      // Resolve the two config folders explicitly rather than assuming a\n      // position in `watchFolders`. With a custom `watchFolders`, match by the\n      // trailing segment; otherwise use the computed defaults.\n      if (options?.watchFolders) {\n        queryFolder = watchFolders.find((f) => path.basename(f) === \"queries\");\n        metricViewsFolder = watchFolders.find(\n          (f) => path.basename(f) === \"metric-views\",\n        );\n      } else {\n        queryFolder = defaultQueryFolder;\n        metricViewsFolder = defaultMetricViewsFolder;\n      }\n    },\n\n    buildStart() {\n      // Production: block the build on this generate (and surface failures).\n      // The watch is a dev-only no-op, so just run typegen.\n      if (process.env.NODE_ENV === \"production\") {\n        return runGenerate(\"blocking\");\n      }\n\n      // Dev: don't block startup waiting on typegen. The foreground generate runs\n      // non-blocking — it skips the warehouse entirely and writes degraded\n      // (cached/`unknown`) types instantly. Then arm the warehouse watch so the\n      // warehouse gets a one-shot BLOCKING regenerate (real types) in the\n      // background for EVERY reachable state: RUNNING describes right away, while\n      // STARTING/STOPPED are waited (and started) until they reach RUNNING.\n      void runGenerate(\"non-blocking\");\n      armWarehouseWatch();\n    },\n\n    configureServer(server) {\n      server.watcher.add(watchFolders);\n\n      server.watcher.on(\"change\", (changedFile) => {\n        const isWatchedFile = watchFolders.some((folder) =>\n          changedFile.startsWith(folder),\n        );\n\n        // The metric config is `definitions.json` — a far more generic name\n        // than the old `metric-views.json`. Match it by DIRECTORY, not bare\n        // basename: only a `definitions.json` sitting directly in the\n        // metric-views folder is the config (a `definitions.json` elsewhere in\n        // a watched tree must not trigger a regenerate).\n        const isMetricConfig =\n          metricViewsFolder !== undefined &&\n          path.basename(changedFile) === METRIC_CONFIG_FILE &&\n          path.dirname(path.resolve(changedFile)) ===\n            path.resolve(metricViewsFolder);\n\n        if (isWatchedFile && (changedFile.endsWith(\".sql\") || isMetricConfig)) {\n          // Route through the single-flight runner (was fire-and-forget\n          // generate(), which could race the initial build / watch). This is a\n          // dev-only hook, so degrade instantly (non-blocking), then re-arm the\n          // warehouse watch so the edited query or metric-view source is\n          // re-described in the background against the running warehouse (or\n          // once a still-starting one warms up), landing fresh\n          // blocking-described types.\n          void runGenerate(\"non-blocking\");\n          armWarehouseWatch();\n        }\n      });\n\n      // Tear down any pending warehouse watch when the dev server closes so a\n      // long backoff can't keep the process alive after shutdown.\n      server.httpServer?.once(\"close\", () => {\n        watchController?.abort();\n      });\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/utils/safe-handler.js

@@ -0,0 +1,28 @@
+//#region src/utils/safe-handler.ts
+/**
+* Wrap an Express handler so synchronous throws and async rejections are
+* forwarded to the error-handling middleware via `next(err)`.
+*
+* Express 4 does not catch rejected promises from async handlers — a
+* rejection (e.g. `asUser()` throwing `AuthenticationError` before any
+* response is written) escapes as an unhandledRejection, which leaves the
+* request hanging and crashes Node by default.
+*
+* Error-handling middleware (arity 4, `(err, req, res, next)`) is returned
+* unchanged: Express identifies it by function arity, so wrapping it would
+* silently turn it into a regular handler.
+*
+* Note: handlers must RETURN their promise (e.g. `(req, res) =>
+* this._handle(req, res)` or `async (req, res) => { await ... }`) for
+* rejections to be caught — a fire-and-forget body like
+* `(req, res) => { this._handle(req, res); }` hides the promise from the
+* wrapper and rejections escape as unhandledRejection again.
+*/
+function forwardAsyncErrors(handler) {
+	if (handler.length > 3) return handler;
+	return (req, res, next) => Promise.resolve().then(() => handler(req, res, next)).catch(next);
+}
+
+//#endregion
+export { forwardAsyncErrors };
+//# sourceMappingURL=safe-handler.js.map

package/dist/utils/safe-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-handler.js","names":[],"sources":["../../src/utils/safe-handler.ts"],"sourcesContent":["import type express from \"express\";\n\n/**\n * Wrap an Express handler so synchronous throws and async rejections are\n * forwarded to the error-handling middleware via `next(err)`.\n *\n * Express 4 does not catch rejected promises from async handlers — a\n * rejection (e.g. `asUser()` throwing `AuthenticationError` before any\n * response is written) escapes as an unhandledRejection, which leaves the\n * request hanging and crashes Node by default.\n *\n * Error-handling middleware (arity 4, `(err, req, res, next)`) is returned\n * unchanged: Express identifies it by function arity, so wrapping it would\n * silently turn it into a regular handler.\n *\n * Note: handlers must RETURN their promise (e.g. `(req, res) =>\n * this._handle(req, res)` or `async (req, res) => { await ... }`) for\n * rejections to be caught — a fire-and-forget body like\n * `(req, res) => { this._handle(req, res); }` hides the promise from the\n * wrapper and rejections escape as unhandledRejection again.\n */\nexport function forwardAsyncErrors(\n  handler: (\n    req: express.Request,\n    res: express.Response,\n    next: express.NextFunction,\n  ) => unknown,\n): express.RequestHandler {\n  if (handler.length > 3) return handler as express.RequestHandler;\n  return (req, res, next) =>\n    Promise.resolve()\n      .then(() => handler(req, res, next))\n      .catch(next);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,mBACd,SAKwB;AACxB,KAAI,QAAQ,SAAS,EAAG,QAAO;AAC/B,SAAQ,KAAK,KAAK,SAChB,QAAQ,SAAS,CACd,WAAW,QAAQ,KAAK,KAAK,KAAK,CAAC,CACnC,MAAM,KAAK"}

package/docs/api/appkit/Class.Plugin.md

@@ -224,6 +224,8 @@ abortActiveOperations(): void;
 
 ```
 
+Cancel in-flight work (abort signals, SSE streams). Runs in the first phase of graceful shutdown, BEFORE any plugin's `shutdown()` hook — so it must not tear down shared resources (e.g. connection pools) that other plugins' hooks may still need. Put teardown in `shutdown()`.
+
 #### Returns[​](#returns-1 "Direct link to Returns")
 
 `void`

package/docs/api/appkit/Class.ResourceRegistry.md

@@ -249,7 +249,7 @@ const registry = ResourceRegistry.getInstance();
 const result = registry.validate();
 
 if (!result.valid) {
-  console.error("Missing resources:", result.missing.map(r => Object.values(r.fields).map(f => f.env)));
+  console.error(ResourceRegistry.formatMissingResources(result.missing));
 }
 
 ```

package/docs/api/appkit/Interface.AgentDefinition.md

@@ -35,6 +35,17 @@ When true, the thread used for a chat request against this agent is deleted from
 
 ***
 
+### generationParams?[​](#generationparams "Direct link to generationParams?")
+
+```ts
+optional generationParams: GenerationParams;
+
+```
+
+Optional generation parameters (`temperature`, `top_p`, `stop`, `frequency_penalty`, `presence_penalty`) forwarded to the OpenAI-compatible serving request body. Only set keys are sent. Applied only when AppKit builds the adapter itself (string or omitted `model`); when you pass a pre-built `AgentAdapter`, configure generation params on it directly.
+
+***
+
 ### instructions[​](#instructions "Direct link to instructions")
 
 ```ts

package/docs/api/appkit/Interface.GenerationParams.md

@@ -0,0 +1,58 @@
+# Interface: GenerationParams
+
+Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### frequency\_penalty?[​](#frequency_penalty "Direct link to frequency_penalty?")
+
+```ts
+optional frequency_penalty: number;
+
+```
+
+Penalize tokens by frequency.
+
+***
+
+### presence\_penalty?[​](#presence_penalty "Direct link to presence_penalty?")
+
+```ts
+optional presence_penalty: number;
+
+```
+
+Penalize tokens by prior presence.
+
+***
+
+### stop?[​](#stop "Direct link to stop?")
+
+```ts
+optional stop: string | string[];
+
+```
+
+Stop sequence(s) that end generation.
+
+***
+
+### temperature?[​](#temperature "Direct link to temperature?")
+
+```ts
+optional temperature: number;
+
+```
+
+Sampling temperature.
+
+***
+
+### top\_p?[​](#top_p "Direct link to top_p?")
+
+```ts
+optional top_p: number;
+
+```
+
+Nucleus sampling probability mass (`top_p`).

package/docs/api/appkit/Interface.RegisteredAgent.md

@@ -31,6 +31,17 @@ Mirrors `AgentDefinition.ephemeral` — skip thread persistence.
 
 ***
 
+### generationParams?[​](#generationparams "Direct link to generationParams?")
+
+```ts
+optional generationParams: GenerationParams;
+
+```
+
+Mirrors `AgentDefinition.generationParams`.
+
+***
+
 ### instructions[​](#instructions "Direct link to instructions")
 
 ```ts

package/docs/api/appkit.md

@@ -47,6 +47,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [FileResource](./docs/api/appkit/Interface.FileResource.md)                                           | Describes the file or directory being acted upon.                                                                                                                                                                                                                                                                                                                                                                                          |
 | [FunctionTool](./docs/api/appkit/Interface.FunctionTool.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials                                                                                                                                                                                                                                                                                                                                                                               |
+| [GenerationParams](./docs/api/appkit/Interface.GenerationParams.md)                                   | Optional generation parameters forwarded to the OpenAI-compatible serving request body. Names match the serving API wire keys. Only keys that are set are sent — undefined values are omitted so the endpoint applies its own defaults. Ranges are not validated here; the serving endpoint validates.                                                                                                                                     |
 | [IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md)                                             | Configuration for the Jobs plugin.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [ITelemetry](./docs/api/appkit/Interface.ITelemetry.md)                                               | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins.                                                                                                                                                                                                                                                                                                                |
 | [JobAPI](./docs/api/appkit/Interface.JobAPI.md)                                                       | User-facing API for a single configured job.                                                                                                                                                                                                                                                                                                                                                                                               |

package/docs/development/type-generation.md

@@ -88,13 +88,13 @@ In blocking mode the generator starts a stopped warehouse, waits (bounded) for i
 
 ## Metric-view types[​](#metric-view-types "Direct link to Metric-view types")
 
-`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/queries/metric-views.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](./docs/plugins/analytics.md) and writes `metric-views.d.ts` into `shared/appkit-types/`:
+`generate-types` (and the Vite plugin) emit metric-view types **additively** — there is no separate command. When a `config/metric-views/definitions.json` file is present, the same run that generates your query types also DESCRIBEs each declared [UC Metric View](./docs/plugins/analytics.md) and writes `metric-views.d.ts` into `shared/appkit-types/`:
 
 * `metric-views.d.ts` — augments the `MetricRegistry` interface so `useMetricView('<key>', …)` is autocompleted and type-checked. Each view's measures, dimensions, and their semantic metadata (SQL type, display name, format, time grains) are encoded at the type level.
 
-If `metric-views.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` that same situation fails the build so CI never ships incomplete metric types. A malformed `metric-views.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
+If `config/metric-views/definitions.json` is absent the metric path stays dormant (nothing is emitted). When present it follows the **same** warehouse-readiness contract as query types: in the default non-blocking run a view that can't be described yet — a cold warehouse, or a bad/unreachable source — is written with permissive types and a warning, while under `--wait` that same situation fails the build so CI never ships incomplete metric types. A malformed `definitions.json` (invalid JSON, or a source that isn't a three-part UC FQN) fails fast in every mode.
 
-`metric-views.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
+`definitions.json` is keyed by metric key; each entry names the three-part UC FQN of the view and, optionally, the executor it runs as (`app_service_principal`, the default, or `user`):
 
 ```json
 {

package/docs/plugins/analytics.md

@@ -86,12 +86,154 @@ The analytics plugin exposes these endpoints (mounted under `/api/analytics`):
 
 * `POST /api/analytics/query/:query_key`
 * `GET /api/analytics/arrow-result/:jobId`
+* `POST /api/analytics/metric/:key` — measure a Unity Catalog Metric View (see [Metric views](#metric-views))
 
 ## Format options[​](#format-options "Direct link to Format options")
 
 * `format: "JSON"` (default) returns JSON rows
 * `format: "ARROW"` returns an Arrow "statement\_id" payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
 
+## Metric views[​](#metric-views "Direct link to Metric views")
+
+`POST /api/analytics/metric/:key` measures a [Unity Catalog Metric View](https://docs.databricks.com/en/metric-views/index.html) that you declared in `config/metric-views/definitions.json`. Instead of writing SQL, the caller sends a structured request — which measures to aggregate, which dimensions to group by, and an optional filter — and the plugin builds and runs the `SELECT MEASURE(...) ... GROUP BY ALL` for you against the view.
+
+The route is **dormant until `config/metric-views/definitions.json` exists**: with no config file, every metric key returns `404`. Declaring the file (and generating types) is covered in [Metric-view types](./docs/development/type-generation.md#metric-view-types); this section documents the runtime endpoint that config activates.
+
+### Request body[​](#request-body "Direct link to Request body")
+
+```text
+POST /api/analytics/metric/:key
+Content-Type: application/json
+
+{
+  "measures": ["arr", "revenue"],
+  "dimensions": ["region", "order_date"],
+  "timeGrain": "month",
+  "timeDimension": "order_date",
+  "filter": { "member": "region", "operator": "in", "values": ["EMEA", "APAC"] },
+  "limit": 100
+}
+
+```
+
+`:key` is a metric key from `definitions.json`. The body fields:
+
+| Field           | Type       | Required | Description                                                                                                                                  |
+| --------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `measures`      | `string[]` | yes      | Measures to aggregate. At least 1, at most 50. Each becomes `MEASURE(<name>) AS <name>`.                                                     |
+| `dimensions`    | `string[]` | no       | Dimensions to group by (max 20). Selected verbatim and grouped via `GROUP BY ALL`.                                                           |
+| `filter`        | object     | no       | Structured predicate tree translated into a parameterized `WHERE` clause (see [Filters](#filters)).                                          |
+| `timeGrain`     | `string`   | no       | Bucket a time dimension via `date_trunc('<grain>', …)` — e.g. `day`, `month`. Requires `timeDimension`.                                      |
+| `timeDimension` | `string`   | no       | The single dimension `timeGrain` buckets. Must be one of `dimensions`. Required whenever `timeGrain` is set.                                 |
+| `limit`         | `number`   | no       | Positive integer row cap (max 100000).                                                                                                       |
+| `format`        | `string`   | no       | `JSON_ARRAY` (default). `JSON` is accepted as a deprecated alias for it; Arrow formats (`ARROW`, `ARROW_STREAM`) are rejected on this route. |
+
+Measures and dimensions must be unique across both lists — a name cannot repeat, nor appear as both a measure and a dimension.
+
+### How the request becomes SQL[​](#how-the-request-becomes-sql "Direct link to How the request becomes SQL")
+
+Given a view registered as `catalog.schema.revenue_metrics`, the request above produces (measures and dimensions are sorted for a deterministic SELECT list):
+
+```sql
+SELECT MEASURE(`arr`) AS `arr`, MEASURE(`revenue`) AS `revenue`,
+       date_trunc('month', `order_date`) AS `order_date`, `region`
+FROM `catalog`.`schema`.`revenue_metrics`
+WHERE `region` IN (:f_0, :f_1)
+GROUP BY ALL
+LIMIT 100
+
+```
+
+The metric view's FQN and every measure/dimension identifier are backtick-quoted; filter values are bound as parameters (`:f_0`, `:f_1`, …), never interpolated into the SQL string.
+
+### Filters[​](#filters "Direct link to Filters")
+
+`filter` is a recursive tree. A leaf is a single predicate:
+
+```json
+{ "member": "region", "operator": "equals", "values": ["EMEA"] }
+
+```
+
+Predicates combine with `and` / `or` groups, which can nest:
+
+```json
+{
+  "and": [
+    { "member": "region", "operator": "in", "values": ["EMEA", "APAC"] },
+    {
+      "or": [
+        { "member": "segment", "operator": "equals", "values": ["Enterprise"] },
+        { "member": "deal_size", "operator": "gt", "values": [50000] }
+      ]
+    }
+  ]
+}
+
+```
+
+The operator vocabulary:
+
+| Operator                    | SQL                     | Values             |
+| --------------------------- | ----------------------- | ------------------ |
+| `equals`                    | `=`                     | exactly one        |
+| `notEquals`                 | `<>`                    | exactly one        |
+| `in`                        | `IN (…)`                | one or more        |
+| `notIn`                     | `NOT IN (…)`            | one or more        |
+| `gt` / `gte` / `lt` / `lte` | `>` / `>=` / `<` / `<=` | exactly one        |
+| `contains`                  | `LIKE :param`           | exactly one string |
+| `notContains`               | `NOT LIKE :param`       | exactly one string |
+| `set`                       | `IS NOT NULL`           | none               |
+| `notSet`                    | `IS NULL`               | none               |
+
+For `contains` / `notContains`, the `%…%` wildcards are applied to the *bound parameter value* (`%value%`), not written into the SQL text — so the value is never interpolated, consistent with every other operator.
+
+Empty groups of either kind (`{ "or": [] }`, `{ "and": [] }`) are rejected with `400` — every `and` / `or` group must contain at least one predicate. To send no filter, omit the `filter` field entirely rather than passing an empty group.
+
+Filters are bounded to keep hostile input from exhausting the server: nesting depth ≤ 8, ≤ 100 children per `and` / `or` group, and ≤ 1000 values per predicate. A request that exceeds a cap is rejected with `400`.
+
+### Executors (cache scope)[​](#executors-cache-scope "Direct link to Executors (cache scope)")
+
+Each entry in `definitions.json` names the executor the query runs as, which also sets the cache scope. This is fixed by config, not the request:
+
+| `executor`                        | Runs as                            | Cache                   |
+| --------------------------------- | ---------------------------------- | ----------------------- |
+| `app_service_principal` (default) | The app service principal          | Shared across all users |
+| `user`                            | The requesting user (on-behalf-of) | Per user                |
+
+This mirrors the `<key>.sql` vs `<key>.obo.sql` distinction for [file-based queries](#execution-context).
+
+### Response[​](#response "Direct link to Response")
+
+The response is the same SSE stream as `POST /api/analytics/query/:query_key`. If the SQL warehouse is cold it first emits `warehouse_status` events (see [Warehouse readiness](#warehouse-readiness)), then a single `result` event with the rows as objects:
+
+```json
+{
+  "type": "result",
+  "data": [
+    {
+      "region": "EMEA",
+      "order_date": "2025-01-01",
+      "arr": 1200000,
+      "revenue": 340000
+    }
+  ]
+}
+
+```
+
+On failure it emits an `error` event instead.
+
+### Errors and behavior[​](#errors-and-behavior "Direct link to Errors and behavior")
+
+| Status | Body                                                                                  | When                                                                                                             |
+| ------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `404`  | `{ "error": "Metric not found" }`                                                     | `:key` is not declared in `definitions.json` (also the response for every key when the file is absent).          |
+| `400`  | `{ "error": "Invalid metric request body (fields: …)", "code": … }`                   | The request body fails validation. The message names only the offending field paths, never the submitted values. |
+| `503`  | `{ "error": "Metric registry not available", "code": "METRIC_REGISTRY_LOAD_FAILED" }` | `definitions.json` is present but malformed or unreadable.                                                       |
+
+Editing `definitions.json` is picked up on the next request — no server restart is needed. A previously malformed file that you fix likewise starts working on the next request.
+
 ## Frontend usage[​](#frontend-usage "Direct link to Frontend usage")
 
 ### useAnalyticsQuery[​](#useanalyticsquery "Direct link to useAnalyticsQuery")
@@ -101,7 +243,11 @@ React hook that subscribes to an analytics query over SSE and returns its latest
 ```ts
 import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
 
-const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options);
+const { data, loading, error } = useAnalyticsQuery(
+  queryKey,
+  parameters,
+  options,
+);
 
 ```
 
@@ -109,8 +255,8 @@ const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options
 
 ```ts
 {
-  data: T | null;      // query result (typed array for JSON, TypedArrowTable for ARROW)
-  loading: boolean;    // true while the query is executing
+  data: T | null; // query result (typed array for JSON, TypedArrowTable for ARROW)
+  loading: boolean; // true while the query is executing
   error: string | null; // error message, or null on success
   warehouseStatus: WarehouseStatus | null; // see "Warehouse readiness" below
 }
@@ -139,8 +285,10 @@ This means a cold start no longer freezes the UI on a stalled spinner. Render th
 import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
 
 function SpendTable() {
-  const { data, loading, error, warehouseStatus } =
-    useAnalyticsQuery("spend_summary", params);
+  const { data, loading, error, warehouseStatus } = useAnalyticsQuery(
+    "spend_summary",
+    params,
+  );
 
   if (warehouseStatus && warehouseStatus.state !== "RUNNING") {
     return <div>Warehouse is {warehouseStatus.state.toLowerCase()}…</div>;
@@ -184,10 +332,7 @@ export function AppShell({ children }) {
 If you already render your own `<Toaster />` for unrelated app toasts, drop the indicator and call `useResourceStatusToaster()` instead so resource-status toasts share that single Toaster:
 
 ```tsx
-import {
-  useResourceStatusToaster,
-  Toaster,
-} from "@databricks/appkit-ui/react";
+import { useResourceStatusToaster, Toaster } from "@databricks/appkit-ui/react";
 
 function App() {
   useResourceStatusToaster();
@@ -207,7 +352,8 @@ For a fully custom toast body, pass `render` (rendered through `toast.custom`):
 <ResourceStatusIndicator
   render={(agg) => (
     <div className="rounded-lg border bg-background p-3 shadow">
-      {agg.worst?.kind} {agg.worst?.state.toLowerCase()} ({agg.activeCount} waiting)
+      {agg.worst?.kind} {agg.worst?.state.toLowerCase()} ({agg.activeCount}{" "}
+      waiting)
     </div>
   )}
 />
@@ -221,8 +367,7 @@ To override copy for a specific kind without rewriting the whole UI, pass `rende
   renderers={{
     warehouse: {
       title: () => "Spinning up your data",
-      description: (_s, agg) =>
-        `${agg.affectedLabels.length} chart(s) waiting`,
+      description: (_s, agg) => `${agg.affectedLabels.length} chart(s) waiting`,
     },
   }}
 />
@@ -254,11 +399,9 @@ import { useEffect, useId } from "react";
 
 function useLakebaseReadiness() {
   const id = useId();
-  const { publish, unpublish } = useResourceStatusPublisher(
-    id,
-    "lakebase",
-    { kindHint: "lakebase" },
-  );
+  const { publish, unpublish } = useResourceStatusPublisher(id, "lakebase", {
+    kindHint: "lakebase",
+  });
 
   useEffect(() => {
     publish({
@@ -288,21 +431,27 @@ import { sql } from "@databricks/appkit-ui/js";
 import { Skeleton } from "@databricks/appkit-ui";
 
 function SpendTable() {
-  const params = useMemo(() => ({
-    startDate: sql.date("2025-01-01"),
-    endDate: sql.date("2025-12-31"),
-  }), []);
+  const params = useMemo(
+    () => ({
+      startDate: sql.date("2025-01-01"),
+      endDate: sql.date("2025-12-31"),
+    }),
+    [],
+  );
 
   const { data, loading, error } = useAnalyticsQuery("spend_summary", params);
 
   if (loading) return <Skeleton className="h-32 w-full" />;
   if (error) return <div className="text-destructive">{error}</div>;
-  if (!data?.length) return <div className="text-muted-foreground">No results</div>;
+  if (!data?.length)
+    return <div className="text-muted-foreground">No results</div>;
 
   return (
     <ul>
       {data.map((row) => (
-        <li key={row.id}>{row.name}: ${row.cost_usd}</li>
+        <li key={row.id}>
+          {row.name}: ${row.cost_usd}
+        </li>
       ))}
     </ul>
   );

package/llms.txt

@@ -125,6 +125,7 @@ npx @databricks/appkit docs <query>
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
+- [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
 - [Interface: IJobsConfig](./docs/api/appkit/Interface.IJobsConfig.md): Configuration for the Jobs plugin.
 - [Interface: ITelemetry](./docs/api/appkit/Interface.ITelemetry.md): Plugin-facing interface for OpenTelemetry instrumentation.
 - [Interface: JobAPI](./docs/api/appkit/Interface.JobAPI.md): User-facing API for a single configured job.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {