@databricks/appkit 0.70.0 → 0.72.0

package/dist/connectors/mlflow/client.d.ts

@@ -0,0 +1,51 @@
+//#region src/connectors/mlflow/client.d.ts
+/** Shared client for talking to the Databricks/MLflow REST API. */
+/** Ensure the host has a scheme (Databricks env often lacks `https://`). */
+declare function normalizeHost(raw: string): string;
+/** Structured result for a best-effort POST that must not throw. */
+interface PostResult {
+  ok: boolean;
+  status?: number;
+  error?: string;
+}
+/**
+ * A thin client over the Databricks workspace REST API, owning the host + bearer
+ * token so callers (eval-run creation, assessment writes, the judge's serving
+ * endpoint) don't each re-derive URLs or re-attach auth. The host is normalized
+ * once at construction.
+ */
+declare class MlflowClient {
+  /** Normalized workspace base URL (scheme guaranteed, no trailing slash). */
+  readonly baseUrl: string;
+  private readonly token;
+  constructor(host: string, token: string);
+  private headers;
+  /**
+   * POST JSON to an MLflow REST endpoint. Returns the parsed JSON body, or
+   * throws with the status + response text so callers can surface a precise
+   * error. Use for calls whose failure should abort (e.g. `runs/create`).
+   *
+   * The thrown message embeds up to 500 chars of the upstream response body to
+   * aid debugging. That is fine for the dev-facing eval CLI, but do NOT relay
+   * it into an end-user HTTP response if this client is reused in a request
+   * handler — the body can carry workspace-internal detail.
+   */
+  post<T = unknown>(path: string, body: unknown): Promise<T>;
+  /**
+   * POST JSON without throwing: returns `{ ok, status, error }` so best-effort
+   * writes (e.g. per-trace assessments) can be collected and reported without
+   * aborting the run.
+   *
+   * `error` embeds up to 500 chars of the upstream body — same caveat as
+   * {@link post}: fine to log for the dev CLI, don't relay it to end users.
+   */
+  postResult(path: string, body: unknown): Promise<PostResult>;
+  /**
+   * OpenAI-compatible base URL for Databricks Model Serving, used as the judge's
+   * `OPENAI_BASE_URL`. Same workspace host + token as the MLflow REST calls.
+   */
+  servingEndpointsUrl(): string;
+}
+//#endregion
+export { MlflowClient, PostResult, normalizeHost };
+//# sourceMappingURL=client.d.ts.map

package/dist/connectors/mlflow/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","names":[],"sources":["../../../src/connectors/mlflow/client.ts"],"mappings":";;AAGA;AAAA,iBAAgB,aAAA,CAAc,GAAA;;UAMb,UAAA;EACf,EAAA;EACA,MAAA;EACA,KAAA;AAAA;;;;;;;cASW,YAAA;EAAY;EAAA,SAEd,OAAA;EAAA,iBACQ,KAAA;cAEL,IAAA,UAAc,KAAA;EAAA,QAKlB,OAAA;EAuCuC;;;;;;;;;;EAtBzC,IAAA,aAAA,CAAkB,IAAA,UAAc,IAAA,YAAgB,OAAA,CAAQ,CAAA;EAAtC;;;;;;;;EAsBlB,UAAA,CAAW,IAAA,UAAc,IAAA,YAAgB,OAAA,CAAQ,UAAA;EAwBvD;;;;EAAA,mBAAA,CAAA;AAAA"}

package/dist/connectors/mlflow/client.js

@@ -0,0 +1,93 @@
+//#region src/connectors/mlflow/client.ts
+/** Shared client for talking to the Databricks/MLflow REST API. */
+/** Ensure the host has a scheme (Databricks env often lacks `https://`). */
+function normalizeHost(raw) {
+	const h = raw.trim().replace(/\/+$/, "");
+	return /^https?:\/\//i.test(h) ? h : `https://${h}`;
+}
+/**
+* A thin client over the Databricks workspace REST API, owning the host + bearer
+* token so callers (eval-run creation, assessment writes, the judge's serving
+* endpoint) don't each re-derive URLs or re-attach auth. The host is normalized
+* once at construction.
+*/
+var MlflowClient = class {
+	/** Normalized workspace base URL (scheme guaranteed, no trailing slash). */
+	baseUrl;
+	token;
+	constructor(host, token) {
+		this.baseUrl = normalizeHost(host);
+		this.token = token;
+	}
+	headers() {
+		return {
+			"content-type": "application/json",
+			authorization: `Bearer ${this.token}`
+		};
+	}
+	/**
+	* POST JSON to an MLflow REST endpoint. Returns the parsed JSON body, or
+	* throws with the status + response text so callers can surface a precise
+	* error. Use for calls whose failure should abort (e.g. `runs/create`).
+	*
+	* The thrown message embeds up to 500 chars of the upstream response body to
+	* aid debugging. That is fine for the dev-facing eval CLI, but do NOT relay
+	* it into an end-user HTTP response if this client is reused in a request
+	* handler — the body can carry workspace-internal detail.
+	*/
+	async post(path, body) {
+		const res = await fetch(`${this.baseUrl}${path}`, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify(body)
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`${path} -> ${res.status} ${text.slice(0, 500)}`);
+		}
+		const text = await res.text();
+		return text ? JSON.parse(text) : {};
+	}
+	/**
+	* POST JSON without throwing: returns `{ ok, status, error }` so best-effort
+	* writes (e.g. per-trace assessments) can be collected and reported without
+	* aborting the run.
+	*
+	* `error` embeds up to 500 chars of the upstream body — same caveat as
+	* {@link post}: fine to log for the dev CLI, don't relay it to end users.
+	*/
+	async postResult(path, body) {
+		try {
+			const res = await fetch(`${this.baseUrl}${path}`, {
+				method: "POST",
+				headers: this.headers(),
+				body: JSON.stringify(body)
+			});
+			if (!res.ok) {
+				const text = await res.text().catch(() => "");
+				return {
+					ok: false,
+					status: res.status,
+					error: text.slice(0, 500)
+				};
+			}
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	/**
+	* OpenAI-compatible base URL for Databricks Model Serving, used as the judge's
+	* `OPENAI_BASE_URL`. Same workspace host + token as the MLflow REST calls.
+	*/
+	servingEndpointsUrl() {
+		return `${this.baseUrl}/serving-endpoints`;
+	}
+};
+
+//#endregion
+export { MlflowClient, normalizeHost };
+//# sourceMappingURL=client.js.map

package/dist/connectors/mlflow/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/mlflow/client.ts"],"sourcesContent":["/** Shared client for talking to the Databricks/MLflow REST API. */\n\n/** Ensure the host has a scheme (Databricks env often lacks `https://`). */\nexport function normalizeHost(raw: string): string {\n  const h = raw.trim().replace(/\\/+$/, \"\");\n  return /^https?:\\/\\//i.test(h) ? h : `https://${h}`;\n}\n\n/** Structured result for a best-effort POST that must not throw. */\nexport interface PostResult {\n  ok: boolean;\n  status?: number;\n  error?: string;\n}\n\n/**\n * A thin client over the Databricks workspace REST API, owning the host + bearer\n * token so callers (eval-run creation, assessment writes, the judge's serving\n * endpoint) don't each re-derive URLs or re-attach auth. The host is normalized\n * once at construction.\n */\nexport class MlflowClient {\n  /** Normalized workspace base URL (scheme guaranteed, no trailing slash). */\n  readonly baseUrl: string;\n  private readonly token: string;\n\n  constructor(host: string, token: string) {\n    this.baseUrl = normalizeHost(host);\n    this.token = token;\n  }\n\n  private headers(): Record<string, string> {\n    return {\n      \"content-type\": \"application/json\",\n      authorization: `Bearer ${this.token}`,\n    };\n  }\n\n  /**\n   * POST JSON to an MLflow REST endpoint. Returns the parsed JSON body, or\n   * throws with the status + response text so callers can surface a precise\n   * error. Use for calls whose failure should abort (e.g. `runs/create`).\n   *\n   * The thrown message embeds up to 500 chars of the upstream response body to\n   * aid debugging. That is fine for the dev-facing eval CLI, but do NOT relay\n   * it into an end-user HTTP response if this client is reused in a request\n   * handler — the body can carry workspace-internal detail.\n   */\n  async post<T = unknown>(path: string, body: unknown): Promise<T> {\n    const res = await fetch(`${this.baseUrl}${path}`, {\n      method: \"POST\",\n      headers: this.headers(),\n      body: JSON.stringify(body),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => \"\");\n      throw new Error(`${path} -> ${res.status} ${text.slice(0, 500)}`);\n    }\n    const text = await res.text();\n    return (text ? JSON.parse(text) : {}) as T;\n  }\n\n  /**\n   * POST JSON without throwing: returns `{ ok, status, error }` so best-effort\n   * writes (e.g. per-trace assessments) can be collected and reported without\n   * aborting the run.\n   *\n   * `error` embeds up to 500 chars of the upstream body — same caveat as\n   * {@link post}: fine to log for the dev CLI, don't relay it to end users.\n   */\n  async postResult(path: string, body: unknown): Promise<PostResult> {\n    try {\n      const res = await fetch(`${this.baseUrl}${path}`, {\n        method: \"POST\",\n        headers: this.headers(),\n        body: JSON.stringify(body),\n      });\n      if (!res.ok) {\n        const text = await res.text().catch(() => \"\");\n        return { ok: false, status: res.status, error: text.slice(0, 500) };\n      }\n      return { ok: true };\n    } catch (err) {\n      return {\n        ok: false,\n        error: err instanceof Error ? err.message : String(err),\n      };\n    }\n  }\n\n  /**\n   * OpenAI-compatible base URL for Databricks Model Serving, used as the judge's\n   * `OPENAI_BASE_URL`. Same workspace host + token as the MLflow REST calls.\n   */\n  servingEndpointsUrl(): string {\n    return `${this.baseUrl}/serving-endpoints`;\n  }\n}\n"],"mappings":";;;AAGA,SAAgB,cAAc,KAAqB;CACjD,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,QAAQ,GAAG;AACxC,QAAO,gBAAgB,KAAK,EAAE,GAAG,IAAI,WAAW;;;;;;;;AAgBlD,IAAa,eAAb,MAA0B;;CAExB,AAAS;CACT,AAAiB;CAEjB,YAAY,MAAc,OAAe;AACvC,OAAK,UAAU,cAAc,KAAK;AAClC,OAAK,QAAQ;;CAGf,AAAQ,UAAkC;AACxC,SAAO;GACL,gBAAgB;GAChB,eAAe,UAAU,KAAK;GAC/B;;;;;;;;;;;;CAaH,MAAM,KAAkB,MAAc,MAA2B;EAC/D,MAAM,MAAM,MAAM,MAAM,GAAG,KAAK,UAAU,QAAQ;GAChD,QAAQ;GACR,SAAS,KAAK,SAAS;GACvB,MAAM,KAAK,UAAU,KAAK;GAC3B,CAAC;AACF,MAAI,CAAC,IAAI,IAAI;GACX,MAAM,OAAO,MAAM,IAAI,MAAM,CAAC,YAAY,GAAG;AAC7C,SAAM,IAAI,MAAM,GAAG,KAAK,MAAM,IAAI,OAAO,GAAG,KAAK,MAAM,GAAG,IAAI,GAAG;;EAEnE,MAAM,OAAO,MAAM,IAAI,MAAM;AAC7B,SAAQ,OAAO,KAAK,MAAM,KAAK,GAAG,EAAE;;;;;;;;;;CAWtC,MAAM,WAAW,MAAc,MAAoC;AACjE,MAAI;GACF,MAAM,MAAM,MAAM,MAAM,GAAG,KAAK,UAAU,QAAQ;IAChD,QAAQ;IACR,SAAS,KAAK,SAAS;IACvB,MAAM,KAAK,UAAU,KAAK;IAC3B,CAAC;AACF,OAAI,CAAC,IAAI,IAAI;IACX,MAAM,OAAO,MAAM,IAAI,MAAM,CAAC,YAAY,GAAG;AAC7C,WAAO;KAAE,IAAI;KAAO,QAAQ,IAAI;KAAQ,OAAO,KAAK,MAAM,GAAG,IAAI;KAAE;;AAErE,UAAO,EAAE,IAAI,MAAM;WACZ,KAAK;AACZ,UAAO;IACL,IAAI;IACJ,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;IACxD;;;;;;;CAQL,sBAA8B;AAC5B,SAAO,GAAG,KAAK,QAAQ"}

package/dist/core/appkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appkit.d.ts","names":[],"sources":["../../src/core/appkit.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwXsB,SAAA,WACV,UAAA,CAAW,iBAAA,qBAAA,CAErB,MAAA;EACE,OAAA,GAAU,CAAA;EACV,SAAA,GAAY,eAAA;EACZ,KAAA,GAAQ,WAAA;EACR,MAAA,GAAS,eAAA;EACT,cAAA,IAAkB,MAAA,EAAQ,SAAA,CAAU,CAAA,aAAc,OAAA;EAClD,wBAAA;AAAA,IAED,OAAA,CAAQ,SAAA,CAAU,CAAA"}
+{"version":3,"file":"appkit.d.ts","names":[],"sources":["../../src/core/appkit.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8XsB,SAAA,WACV,UAAA,CAAW,iBAAA,qBAAA,CAErB,MAAA;EACE,OAAA,GAAU,CAAA;EACV,SAAA,GAAY,eAAA;EACZ,KAAA,GAAQ,WAAA;EACR,MAAA,GAAS,eAAA;EACT,cAAA,IAAkB,MAAA,EAAQ,SAAA,CAAU,CAAA,aAAc,OAAA;EAClD,wBAAA;AAAA,IAED,OAAA,CAAQ,SAAA,CAAU,CAAA"}

package/dist/core/appkit.js

@@ -110,6 +110,7 @@ var AppKit = class AppKit {
 		registry.enforceValidation();
 		const instance = new AppKit({ plugins: AppKit.preparePlugins(rawPlugins) });
 		await Promise.all(instance.#setupPromises);
+		TelemetryManager.start();
 		await instance.#context.emitLifecycle("setup:complete");
 		const handle = instance;
 		if (config.onPluginsReady) {

package/dist/core/appkit.js.map

@@ -1 +1 @@
-{"version":3,"file":"appkit.js","names":["#context","#pluginInstances","#setupPromises","productVersion"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type {\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\n\nimport { version as productVersion } from \"../../package.json\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport {\n  isInternalTelemetryEnabled,\n  TelemetryReporter,\n} from \"../internal-telemetry\";\nimport { createLogger } from \"../logging/logger\";\nimport { isPlainObject } from \"../plugin/plugin\";\nimport { uiVariants } from \"../plugins/ui-variants\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\nimport type { WorkspaceClient } from \"../workspace-client\";\nimport { LifecycleManager } from \"./lifecycle-manager\";\nimport { isToolProvider, PluginContext } from \"./plugin-context\";\n\nconst logger = createLogger(\"appkit\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n  #context: PluginContext;\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    this.#context = new PluginContext();\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    if (typeof pluginInstance.attachContext === \"function\") {\n      pluginInstance.attachContext({\n        context: this.#context,\n        telemetryConfig: baseConfig.telemetry,\n      });\n    }\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#context.registerPlugin(name, pluginInstance);\n    if (isToolProvider(pluginInstance)) {\n      this.#context.registerToolProvider(name, pluginInstance);\n    }\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    // The manifest `name` is camelCase, so it doubles as the public handle key\n    // (`appkit.aiSearch`). The kebab HTTP route is derived separately.\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   *\n   * The OBO-side wrapping lives inside `Plugin.asUser` — calling\n   * `plugin.asUser(req).exports()` returns exports whose functions already\n   * run inside the user's AsyncLocalStorage scope. AppKit only adapts the\n   * shape; it does not own the user-context concept.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return pluginExports;\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return objExports;\n    }\n\n    return {\n      ...objExports,\n      /**\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) =>\n        (plugin as any).asUser(req).exports() as Record<string, unknown>,\n    };\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n      disableInternalTelemetry?: boolean;\n    } = {},\n  ): Promise<PluginMap<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const withDefaults = AppKit.withDefaultPlugins(config.plugins as T);\n    const rawPlugins = AppKit.filterDevOnlyPlugins(withDefaults);\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      { warehouseId: needsWarehouse },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n    await instance.#context.emitLifecycle(\"setup:complete\");\n\n    const handle = instance as unknown as PluginMap<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(handle);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    if (isInternalTelemetryEnabled(config)) {\n      AppKit.bootstrapInternalTelemetry();\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    // Core owns graceful shutdown: install the signal handlers once every\n    // plugin has started. Applies uniformly whether or not a server plugin\n    // is present — server-less apps still get their telemetry flushed and\n    // plugin shutdown() hooks run.\n    new LifecycleManager(instance.#context).installSignalHandlers();\n\n    return handle;\n  }\n\n  private static bootstrapInternalTelemetry(): void {\n    const serviceCtx = ServiceContext.get();\n    const reporter = TelemetryReporter.initialize({\n      workspaceId: serviceCtx.workspaceId,\n      client: serviceCtx.client,\n      appId: process.env.DATABRICKS_CLIENT_ID || \"\",\n      appkitVersion: productVersion,\n    });\n    reporter.start();\n    reporter.sendStartup().catch(() => {});\n  }\n\n  /**\n   * Injects framework-owned default plugins the app author shouldn't have to\n   * register by hand. Runs before {@link filterDevOnlyPlugins}, so a default\n   * that is itself `devOnly` (like `ui-variants`) is present in dev and stripped\n   * in prod through the exact same guard as any user plugin — never alive in a\n   * deployed app.\n   *\n   * Currently injects the dev-only `ui-variants` recorder that backs the\n   * `<Variants>` UI picker, so neither the developer nor their coding agent has\n   * to remember to add it. If the app already registered it explicitly, that\n   * entry wins and no duplicate is added.\n   */\n  private static withDefaultPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    const list = (plugins ?? []) as PluginData<\n      PluginConstructor,\n      unknown,\n      string\n    >[];\n\n    const defaults: PluginData<PluginConstructor, unknown, string>[] = [\n      uiVariants(),\n    ];\n\n    const missing = defaults.filter(\n      (def) => !list.some((p) => p?.name === def.name),\n    );\n\n    return [...list, ...missing] as T;\n  }\n\n  /**\n   * Drops plugins whose manifest declares `devOnly: true` unless\n   * `NODE_ENV === \"development\"`. Runs before resource collection so a skipped\n   * plugin is never constructed, never injects routes, and has its resource\n   * requirements ignored — the framework, not the app author, enforces that\n   * dev-only tooling can never run in a deployed app.\n   *\n   * This is the primary guard; plugins that expose a mutating dev endpoint\n   * should still keep an in-handler `NODE_ENV` check as fail-safe defense\n   * against being mounted through a path that bypasses this filter.\n   */\n  private static filterDevOnlyPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    if (!plugins || process.env.NODE_ENV === \"development\") return plugins;\n\n    return plugins.filter((pluginData) => {\n      const isDevOnly = pluginData?.plugin?.manifest?.devOnly === true;\n      if (isDevOnly) {\n        logger.debug(\n          \"Skipping dev-only plugin %s (NODE_ENV=%s)\",\n          pluginData?.name ?? \"unknown\",\n          process.env.NODE_ENV ?? \"<unset>\",\n        );\n      }\n      return !isDevOnly;\n    }) as T;\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n    disableInternalTelemetry?: boolean;\n  } = {},\n): Promise<PluginMap<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":"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"}
+{"version":3,"file":"appkit.js","names":["#context","#pluginInstances","#setupPromises","productVersion"],"sources":["../../src/core/appkit.ts"],"sourcesContent":["import type {\n  BasePlugin,\n  CacheConfig,\n  InputPluginMap,\n  OptionalConfigPluginDef,\n  PluginConstructor,\n  PluginData,\n  PluginMap,\n} from \"shared\";\n\nimport { version as productVersion } from \"../../package.json\";\nimport { CacheManager } from \"../cache\";\nimport { ServiceContext } from \"../context\";\nimport {\n  isInternalTelemetryEnabled,\n  TelemetryReporter,\n} from \"../internal-telemetry\";\nimport { createLogger } from \"../logging/logger\";\nimport { isPlainObject } from \"../plugin/plugin\";\nimport { uiVariants } from \"../plugins/ui-variants\";\nimport { ResourceRegistry, ResourceType } from \"../registry\";\nimport type { TelemetryConfig } from \"../telemetry\";\nimport { TelemetryManager } from \"../telemetry\";\nimport type { WorkspaceClient } from \"../workspace-client\";\nimport { LifecycleManager } from \"./lifecycle-manager\";\nimport { isToolProvider, PluginContext } from \"./plugin-context\";\n\nconst logger = createLogger(\"appkit\");\n\nexport class AppKit<TPlugins extends InputPluginMap> {\n  #pluginInstances: Record<string, BasePlugin> = {};\n  #setupPromises: Promise<void>[] = [];\n  #context: PluginContext;\n\n  private constructor(config: { plugins: TPlugins }) {\n    const { plugins, ...globalConfig } = config;\n\n    this.#context = new PluginContext();\n\n    const pluginEntries = Object.entries(plugins);\n\n    const corePlugins = pluginEntries.filter(([_, p]) => {\n      return (p?.plugin?.phase ?? \"normal\") === \"core\";\n    });\n    const normalPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"normal\",\n    );\n    const deferredPlugins = pluginEntries.filter(\n      ([_, p]) => (p?.plugin?.phase ?? \"normal\") === \"deferred\",\n    );\n\n    for (const [name, pluginData] of corePlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of normalPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n\n    for (const [name, pluginData] of deferredPlugins) {\n      if (pluginData) {\n        this.createAndRegisterPlugin(globalConfig, name, pluginData, {\n          context: this.#context,\n        });\n      }\n    }\n  }\n\n  private createAndRegisterPlugin<T extends PluginConstructor>(\n    config: Omit<{ plugins: TPlugins }, \"plugins\">,\n    name: string,\n    pluginData: OptionalConfigPluginDef<T>,\n    extraData?: Record<string, unknown>,\n  ) {\n    const { plugin: Plugin, config: pluginConfig } = pluginData;\n    const baseConfig = {\n      ...config,\n      ...Plugin.DEFAULT_CONFIG,\n      ...pluginConfig,\n      name,\n      ...extraData,\n    };\n    const pluginInstance = new Plugin(baseConfig);\n\n    if (typeof pluginInstance.attachContext === \"function\") {\n      pluginInstance.attachContext({\n        context: this.#context,\n        telemetryConfig: baseConfig.telemetry,\n      });\n    }\n\n    this.#pluginInstances[name] = pluginInstance;\n\n    this.#context.registerPlugin(name, pluginInstance);\n    if (isToolProvider(pluginInstance)) {\n      this.#context.registerToolProvider(name, pluginInstance);\n    }\n\n    this.#setupPromises.push(pluginInstance.setup());\n\n    const self = this;\n\n    // The manifest `name` is camelCase, so it doubles as the public handle key\n    // (`appkit.aiSearch`). The kebab HTTP route is derived separately.\n    Object.defineProperty(this, name, {\n      get() {\n        const plugin = self.#pluginInstances[name];\n        return self.wrapWithAsUser(plugin);\n      },\n      enumerable: true,\n    });\n  }\n\n  /**\n   * Binds all function properties in an exports object to the given context.\n   * Recurses into plain objects to handle nested APIs (e.g., volume APIs).\n   */\n  private bindExportMethods(\n    exports: Record<string, unknown>,\n    context: BasePlugin,\n  ) {\n    for (const key in exports) {\n      if (!Object.hasOwn(exports, key)) continue;\n      const val = exports[key];\n      if (typeof val === \"function\") {\n        exports[key] = (val as (...args: unknown[]) => unknown).bind(context);\n      } else if (isPlainObject(val)) {\n        this.bindExportMethods(val as Record<string, unknown>, context);\n      }\n    }\n  }\n\n  /**\n   * Wraps a plugin's exports with an `asUser` method that returns\n   * a user-scoped version of the exports.\n   *\n   * When `exports()` returns a callable (function), it is returned as-is\n   * since the plugin manages its own `asUser` per-call (e.g. files plugin).\n   * When it returns a plain object, the standard `asUser` wrapper is added.\n   *\n   * The OBO-side wrapping lives inside `Plugin.asUser` — calling\n   * `plugin.asUser(req).exports()` returns exports whose functions already\n   * run inside the user's AsyncLocalStorage scope. AppKit only adapts the\n   * shape; it does not own the user-context concept.\n   */\n  private wrapWithAsUser<T extends BasePlugin>(plugin: T) {\n    // If plugin doesn't implement exports(), return empty object\n    const pluginExports = plugin.exports?.() ?? {};\n\n    // If exports is a function, the plugin manages its own asUser pattern\n    if (typeof pluginExports === \"function\") {\n      return pluginExports;\n    }\n\n    const objExports = pluginExports as Record<string, unknown>;\n    this.bindExportMethods(objExports, plugin);\n\n    // If plugin doesn't support asUser (no asUser method), return exports as-is\n    if (typeof (plugin as any).asUser !== \"function\") {\n      return objExports;\n    }\n\n    return {\n      ...objExports,\n      /**\n       * Execute operations using the user's identity from the request.\n       * Returns user-scoped exports where all methods execute with the\n       * user's Databricks credentials instead of the service principal.\n       */\n      asUser: (req: import(\"express\").Request) =>\n        (plugin as any).asUser(req).exports() as Record<string, unknown>,\n    };\n  }\n\n  static async _createApp<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(\n    config: {\n      plugins?: T;\n      telemetry?: TelemetryConfig;\n      cache?: CacheConfig;\n      client?: WorkspaceClient;\n      onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n      disableInternalTelemetry?: boolean;\n    } = {},\n  ): Promise<PluginMap<T>> {\n    // Initialize core services\n    TelemetryManager.initialize(config?.telemetry);\n    await CacheManager.getInstance(config?.cache);\n\n    const withDefaults = AppKit.withDefaultPlugins(config.plugins as T);\n    const rawPlugins = AppKit.filterDevOnlyPlugins(withDefaults);\n\n    // Collect manifest resources via registry\n    const registry = new ResourceRegistry();\n    registry.collectResources(rawPlugins);\n\n    // Derive ServiceContext needs from what manifests declared\n    const needsWarehouse = registry\n      .getRequired()\n      .some((r) => r.type === ResourceType.SQL_WAREHOUSE);\n    await ServiceContext.initialize(\n      { warehouseId: needsWarehouse },\n      config?.client,\n    );\n\n    // Validate env vars\n    registry.enforceValidation();\n\n    const preparedPlugins = AppKit.preparePlugins(rawPlugins);\n    const mergedConfig = {\n      plugins: preparedPlugins,\n    };\n\n    const instance = new AppKit(mergedConfig);\n\n    await Promise.all(instance.#setupPromises);\n\n    // Build the global tracer provider now that every plugin's setup() has run\n    // and contributed any span processors. Deferred to here so a single provider\n    // carries all processors (OTLP + plugin-contributed); see TelemetryManager.\n    TelemetryManager.start();\n\n    await instance.#context.emitLifecycle(\"setup:complete\");\n\n    const handle = instance as unknown as PluginMap<T>;\n\n    if (config.onPluginsReady) {\n      logger.debug(\"Running onPluginsReady hook\");\n      await config.onPluginsReady(handle);\n      logger.debug(\"onPluginsReady hook completed\");\n    }\n\n    if (isInternalTelemetryEnabled(config)) {\n      AppKit.bootstrapInternalTelemetry();\n    }\n\n    const serverPlugin = instance.#pluginInstances.server;\n    if (serverPlugin && typeof (serverPlugin as any).start === \"function\") {\n      await (serverPlugin as any).start();\n    }\n\n    // Core owns graceful shutdown: install the signal handlers once every\n    // plugin has started. Applies uniformly whether or not a server plugin\n    // is present — server-less apps still get their telemetry flushed and\n    // plugin shutdown() hooks run.\n    new LifecycleManager(instance.#context).installSignalHandlers();\n\n    return handle;\n  }\n\n  private static bootstrapInternalTelemetry(): void {\n    const serviceCtx = ServiceContext.get();\n    const reporter = TelemetryReporter.initialize({\n      workspaceId: serviceCtx.workspaceId,\n      client: serviceCtx.client,\n      appId: process.env.DATABRICKS_CLIENT_ID || \"\",\n      appkitVersion: productVersion,\n    });\n    reporter.start();\n    reporter.sendStartup().catch(() => {});\n  }\n\n  /**\n   * Injects framework-owned default plugins the app author shouldn't have to\n   * register by hand. Runs before {@link filterDevOnlyPlugins}, so a default\n   * that is itself `devOnly` (like `ui-variants`) is present in dev and stripped\n   * in prod through the exact same guard as any user plugin — never alive in a\n   * deployed app.\n   *\n   * Currently injects the dev-only `ui-variants` recorder that backs the\n   * `<Variants>` UI picker, so neither the developer nor their coding agent has\n   * to remember to add it. If the app already registered it explicitly, that\n   * entry wins and no duplicate is added.\n   */\n  private static withDefaultPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    const list = (plugins ?? []) as PluginData<\n      PluginConstructor,\n      unknown,\n      string\n    >[];\n\n    const defaults: PluginData<PluginConstructor, unknown, string>[] = [\n      uiVariants(),\n    ];\n\n    const missing = defaults.filter(\n      (def) => !list.some((p) => p?.name === def.name),\n    );\n\n    return [...list, ...missing] as T;\n  }\n\n  /**\n   * Drops plugins whose manifest declares `devOnly: true` unless\n   * `NODE_ENV === \"development\"`. Runs before resource collection so a skipped\n   * plugin is never constructed, never injects routes, and has its resource\n   * requirements ignored — the framework, not the app author, enforces that\n   * dev-only tooling can never run in a deployed app.\n   *\n   * This is the primary guard; plugins that expose a mutating dev endpoint\n   * should still keep an in-handler `NODE_ENV` check as fail-safe defense\n   * against being mounted through a path that bypasses this filter.\n   */\n  private static filterDevOnlyPlugins<\n    T extends PluginData<PluginConstructor, unknown, string>[],\n  >(plugins: T): T {\n    if (!plugins || process.env.NODE_ENV === \"development\") return plugins;\n\n    return plugins.filter((pluginData) => {\n      const isDevOnly = pluginData?.plugin?.manifest?.devOnly === true;\n      if (isDevOnly) {\n        logger.debug(\n          \"Skipping dev-only plugin %s (NODE_ENV=%s)\",\n          pluginData?.name ?? \"unknown\",\n          process.env.NODE_ENV ?? \"<unset>\",\n        );\n      }\n      return !isDevOnly;\n    }) as T;\n  }\n\n  private static preparePlugins(\n    plugins: PluginData<PluginConstructor, unknown, string>[],\n  ) {\n    const result: InputPluginMap = {};\n    for (const currentPlugin of plugins) {\n      result[currentPlugin.name] = {\n        plugin: currentPlugin.plugin,\n        config: currentPlugin.config as Record<string, unknown>,\n      };\n    }\n    return result;\n  }\n}\n\n/**\n * Bootstraps AppKit with the provided configuration.\n *\n * Initializes telemetry, cache, and service context, then registers plugins\n * in phase order (core, normal, deferred) and awaits their setup.\n * If a `onPluginsReady` callback is provided it runs after plugin setup but\n * before the server starts, giving you access to the full appkit handle\n * for registering custom routes or performing async setup.\n * The returned object maps each plugin name to its `exports()` API,\n * with an `asUser(req)` method for user-scoped execution.\n *\n * @returns A `PluginMap` keyed by plugin name with typed exports\n *\n * @example Minimal server\n * ```ts\n * import { createApp, server } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server()],\n * });\n * ```\n *\n * @example Server with custom routes via onPluginsReady\n * ```ts\n * import { createApp, server, analytics } from \"@databricks/appkit\";\n *\n * await createApp({\n *   plugins: [server(), analytics({})],\n *   onPluginsReady(appkit) {\n *     appkit.server.extend((app) => {\n *       app.get(\"/custom\", (_req, res) => res.json({ ok: true }));\n *     });\n *   },\n * });\n * ```\n */\nexport async function createApp<\n  T extends PluginData<PluginConstructor, unknown, string>[],\n>(\n  config: {\n    plugins?: T;\n    telemetry?: TelemetryConfig;\n    cache?: CacheConfig;\n    client?: WorkspaceClient;\n    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;\n    disableInternalTelemetry?: boolean;\n  } = {},\n): Promise<PluginMap<T>> {\n  return AppKit._createApp(config);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2BA,MAAM,SAAS,aAAa,SAAS;AAErC,IAAa,SAAb,MAAa,OAAwC;CACnD,mBAA+C,EAAE;CACjD,iBAAkC,EAAE;CACpC;CAEA,AAAQ,YAAY,QAA+B;EACjD,MAAM,EAAE,SAAS,GAAG,iBAAiB;AAErC,QAAKA,UAAW,IAAI,eAAe;EAEnC,MAAM,gBAAgB,OAAO,QAAQ,QAAQ;EAE7C,MAAM,cAAc,cAAc,QAAQ,CAAC,GAAG,OAAO;AACnD,WAAQ,GAAG,QAAQ,SAAS,cAAc;IAC1C;EACF,MAAM,gBAAgB,cAAc,QACjC,CAAC,GAAG,QAAQ,GAAG,QAAQ,SAAS,cAAc,SAChD;EACD,MAAM,kBAAkB,cAAc,QACnC,CAAC,GAAG,QAAQ,GAAG,QAAQ,SAAS,cAAc,WAChD;AAED,OAAK,MAAM,CAAC,MAAM,eAAe,YAC/B,KAAI,WACF,MAAK,wBAAwB,cAAc,MAAM,YAAY,EAC3D,SAAS,MAAKA,SACf,CAAC;AAIN,OAAK,MAAM,CAAC,MAAM,eAAe,cAC/B,KAAI,WACF,MAAK,wBAAwB,cAAc,MAAM,YAAY,EAC3D,SAAS,MAAKA,SACf,CAAC;AAIN,OAAK,MAAM,CAAC,MAAM,eAAe,gBAC/B,KAAI,WACF,MAAK,wBAAwB,cAAc,MAAM,YAAY,EAC3D,SAAS,MAAKA,SACf,CAAC;;CAKR,AAAQ,wBACN,QACA,MACA,YACA,WACA;EACA,MAAM,EAAE,QAAQ,QAAQ,QAAQ,iBAAiB;EACjD,MAAM,aAAa;GACjB,GAAG;GACH,GAAG,OAAO;GACV,GAAG;GACH;GACA,GAAG;GACJ;EACD,MAAM,iBAAiB,IAAI,OAAO,WAAW;AAE7C,MAAI,OAAO,eAAe,kBAAkB,WAC1C,gBAAe,cAAc;GAC3B,SAAS,MAAKA;GACd,iBAAiB,WAAW;GAC7B,CAAC;AAGJ,QAAKC,gBAAiB,QAAQ;AAE9B,QAAKD,QAAS,eAAe,MAAM,eAAe;AAClD,MAAI,eAAe,eAAe,CAChC,OAAKA,QAAS,qBAAqB,MAAM,eAAe;AAG1D,QAAKE,cAAe,KAAK,eAAe,OAAO,CAAC;EAEhD,MAAM,OAAO;AAIb,SAAO,eAAe,MAAM,MAAM;GAChC,MAAM;IACJ,MAAM,SAAS,MAAKD,gBAAiB;AACrC,WAAO,KAAK,eAAe,OAAO;;GAEpC,YAAY;GACb,CAAC;;;;;;CAOJ,AAAQ,kBACN,SACA,SACA;AACA,OAAK,MAAM,OAAO,SAAS;AACzB,OAAI,CAAC,OAAO,OAAO,SAAS,IAAI,CAAE;GAClC,MAAM,MAAM,QAAQ;AACpB,OAAI,OAAO,QAAQ,WACjB,SAAQ,OAAQ,IAAwC,KAAK,QAAQ;YAC5D,cAAc,IAAI,CAC3B,MAAK,kBAAkB,KAAgC,QAAQ;;;;;;;;;;;;;;;;CAkBrE,AAAQ,eAAqC,QAAW;EAEtD,MAAM,gBAAgB,OAAO,WAAW,IAAI,EAAE;AAG9C,MAAI,OAAO,kBAAkB,WAC3B,QAAO;EAGT,MAAM,aAAa;AACnB,OAAK,kBAAkB,YAAY,OAAO;AAG1C,MAAI,OAAQ,OAAe,WAAW,WACpC,QAAO;AAGT,SAAO;GACL,GAAG;GAMH,SAAS,QACN,OAAe,OAAO,IAAI,CAAC,SAAS;GACxC;;CAGH,aAAa,WAGX,SAOI,EAAE,EACiB;AAEvB,mBAAiB,WAAW,QAAQ,UAAU;AAC9C,QAAM,aAAa,YAAY,QAAQ,MAAM;EAE7C,MAAM,eAAe,OAAO,mBAAmB,OAAO,QAAa;EACnE,MAAM,aAAa,OAAO,qBAAqB,aAAa;EAG5D,MAAM,WAAW,IAAI,kBAAkB;AACvC,WAAS,iBAAiB,WAAW;EAGrC,MAAM,iBAAiB,SACpB,aAAa,CACb,MAAM,MAAM,EAAE,SAAS,aAAa,cAAc;AACrD,QAAM,eAAe,WACnB,EAAE,aAAa,gBAAgB,EAC/B,QAAQ,OACT;AAGD,WAAS,mBAAmB;EAO5B,MAAM,WAAW,IAAI,OAJA,EACnB,SAFsB,OAAO,eAAe,WAAW,EAGxD,CAEwC;AAEzC,QAAM,QAAQ,IAAI,UAASC,cAAe;AAK1C,mBAAiB,OAAO;AAExB,QAAM,UAASF,QAAS,cAAc,iBAAiB;EAEvD,MAAM,SAAS;AAEf,MAAI,OAAO,gBAAgB;AACzB,UAAO,MAAM,8BAA8B;AAC3C,SAAM,OAAO,eAAe,OAAO;AACnC,UAAO,MAAM,gCAAgC;;AAG/C,MAAI,2BAA2B,OAAO,CACpC,QAAO,4BAA4B;EAGrC,MAAM,eAAe,UAASC,gBAAiB;AAC/C,MAAI,gBAAgB,OAAQ,aAAqB,UAAU,WACzD,OAAO,aAAqB,OAAO;AAOrC,MAAI,iBAAiB,UAASD,QAAS,CAAC,uBAAuB;AAE/D,SAAO;;CAGT,OAAe,6BAAmC;EAChD,MAAM,aAAa,eAAe,KAAK;EACvC,MAAM,WAAW,kBAAkB,WAAW;GAC5C,aAAa,WAAW;GACxB,QAAQ,WAAW;GACnB,OAAO,QAAQ,IAAI,wBAAwB;GAC3C,eAAeG;GAChB,CAAC;AACF,WAAS,OAAO;AAChB,WAAS,aAAa,CAAC,YAAY,GAAG;;;;;;;;;;;;;;CAexC,OAAe,mBAEb,SAAe;EACf,MAAM,OAAQ,WAAW,EAAE;EAU3B,MAAM,UAJ6D,CACjE,YAAY,CACb,CAEwB,QACtB,QAAQ,CAAC,KAAK,MAAM,MAAM,GAAG,SAAS,IAAI,KAAK,CACjD;AAED,SAAO,CAAC,GAAG,MAAM,GAAG,QAAQ;;;;;;;;;;;;;CAc9B,OAAe,qBAEb,SAAe;AACf,MAAI,CAAC,WAAW,QAAQ,IAAI,aAAa,cAAe,QAAO;AAE/D,SAAO,QAAQ,QAAQ,eAAe;GACpC,MAAM,YAAY,YAAY,QAAQ,UAAU,YAAY;AAC5D,OAAI,UACF,QAAO,MACL,6CACA,YAAY,QAAQ,WACpB,QAAQ,IAAI,YAAY,UACzB;AAEH,UAAO,CAAC;IACR;;CAGJ,OAAe,eACb,SACA;EACA,MAAM,SAAyB,EAAE;AACjC,OAAK,MAAM,iBAAiB,QAC1B,QAAO,cAAc,QAAQ;GAC3B,QAAQ,cAAc;GACtB,QAAQ,cAAc;GACvB;AAEH,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCX,eAAsB,UAGpB,SAOI,EAAE,EACiB;AACvB,QAAO,OAAO,WAAW,OAAO"}

package/dist/evals/define-eval.d.ts

@@ -0,0 +1,26 @@
+import { EvalDefinition } from "./types.js";
+
+//#region src/evals/define-eval.d.ts
+/**
+ * Define an agent eval. Default-export the result from a
+ * `server/agents/<id>/evals/*.eval.ts` file.
+ *
+ * @example
+ * ```ts
+ * import { defineEval, includes } from "@databricks/appkit/beta";
+ *
+ * export default defineEval({
+ *   description: "Weather agent basic coverage",
+ *   async test(t) {
+ *     await t.send("What's the weather in Brooklyn?");
+ *     t.succeeded();
+ *     t.calledTool("get_weather");
+ *     t.check(t.reply, includes("Sunny"));
+ *   },
+ * });
+ * ```
+ */
+declare function defineEval(def: EvalDefinition): EvalDefinition;
+//#endregion
+export { defineEval };
+//# sourceMappingURL=define-eval.d.ts.map

package/dist/evals/define-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-eval.d.ts","names":[],"sources":["../../src/evals/define-eval.ts"],"mappings":";;;;;AAqBA;;;;;;;;;;;;;;;;;iBAAgB,UAAA,CAAW,GAAA,EAAK,cAAA,GAAiB,cAAA"}

package/dist/evals/define-eval.js

@@ -0,0 +1,28 @@
+//#region src/evals/define-eval.ts
+/**
+* Define an agent eval. Default-export the result from a
+* `server/agents/<id>/evals/*.eval.ts` file.
+*
+* @example
+* ```ts
+* import { defineEval, includes } from "@databricks/appkit/beta";
+*
+* export default defineEval({
+*   description: "Weather agent basic coverage",
+*   async test(t) {
+*     await t.send("What's the weather in Brooklyn?");
+*     t.succeeded();
+*     t.calledTool("get_weather");
+*     t.check(t.reply, includes("Sunny"));
+*   },
+* });
+* ```
+*/
+function defineEval(def) {
+	if (typeof def.test !== "function") throw new Error("defineEval: `test` must be a function");
+	return def;
+}
+
+//#endregion
+export { defineEval };
+//# sourceMappingURL=define-eval.js.map

package/dist/evals/define-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-eval.js","names":[],"sources":["../../src/evals/define-eval.ts"],"sourcesContent":["import type { EvalDefinition } from \"./types\";\n\n/**\n * Define an agent eval. Default-export the result from a\n * `server/agents/<id>/evals/*.eval.ts` file.\n *\n * @example\n * ```ts\n * import { defineEval, includes } from \"@databricks/appkit/beta\";\n *\n * export default defineEval({\n *   description: \"Weather agent basic coverage\",\n *   async test(t) {\n *     await t.send(\"What's the weather in Brooklyn?\");\n *     t.succeeded();\n *     t.calledTool(\"get_weather\");\n *     t.check(t.reply, includes(\"Sunny\"));\n *   },\n * });\n * ```\n */\nexport function defineEval(def: EvalDefinition): EvalDefinition {\n  if (typeof def.test !== \"function\") {\n    throw new Error(\"defineEval: `test` must be a function\");\n  }\n  return def;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,WAAW,KAAqC;AAC9D,KAAI,OAAO,IAAI,SAAS,WACtB,OAAM,IAAI,MAAM,wCAAwC;AAE1D,QAAO"}

package/dist/evals/discover.d.ts

@@ -0,0 +1,20 @@
+//#region src/evals/discover.d.ts
+/** An eval file found under `server/agents/<agent>/evals/`. */
+interface DiscoveredEval {
+  /** Absolute path to the `*.eval.ts` file. */
+  file: string;
+  /** Id relative to the agent's evals dir, without `.eval.ts` (e.g. `weather/basic`). */
+  id: string;
+  /** The agent id (the `server/agents/<agent>` directory name). */
+  agent: string;
+}
+/**
+ * Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located
+ * with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents
+ * plugin discovers). The agent id is the folder name; the eval id is the file
+ * path relative to that evals dir with `.eval.ts` stripped. Sorted + stable.
+ */
+declare function discoverEvalFiles(rootDir: string): DiscoveredEval[];
+//#endregion
+export { DiscoveredEval, discoverEvalFiles };
+//# sourceMappingURL=discover.d.ts.map

package/dist/evals/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","names":[],"sources":["../../src/evals/discover.ts"],"mappings":";;UAOiB,cAAA;EAAc;EAE7B,IAAA;EAF6B;EAI7B,EAAA;EAAA;EAEA,KAAA;AAAA;;AAoBF;;;;;iBAAgB,iBAAA,CAAkB,OAAA,WAAkB,cAAA"}

package/dist/evals/discover.js

@@ -0,0 +1,49 @@
+import { agentDirNames } from "../core/agent/agent-dirs.js";
+import { CODE_AGENTS_SOURCE_DIR } from "../core/agent/load-code-agents.js";
+import path from "node:path";
+import { readdirSync } from "node:fs";
+
+//#region src/evals/discover.ts
+/** Recursively collect `*.eval.ts` files under `dir`. Empty when `dir` is absent. */
+function evalFilesIn(dir) {
+	try {
+		return readdirSync(dir, {
+			recursive: true,
+			withFileTypes: true
+		}).filter((e) => e.isFile() && e.name.endsWith(".eval.ts")).map((e) => path.join(e.parentPath, e.name));
+	} catch {
+		return [];
+	}
+}
+/**
+* Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located
+* with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents
+* plugin discovers). The agent id is the folder name; the eval id is the file
+* path relative to that evals dir with `.eval.ts` stripped. Sorted + stable.
+*/
+function discoverEvalFiles(rootDir) {
+	const agentsDir = path.join(rootDir, CODE_AGENTS_SOURCE_DIR);
+	const out = [];
+	let entries;
+	try {
+		entries = readdirSync(agentsDir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const agent of agentDirNames(entries)) {
+		const evalsDir = path.join(agentsDir, agent, "evals");
+		for (const file of evalFilesIn(evalsDir)) {
+			const id = path.relative(evalsDir, file).replace(/\.eval\.ts$/, "").split(path.sep).join("/");
+			out.push({
+				file,
+				id,
+				agent
+			});
+		}
+	}
+	return out.sort((a, b) => a.agent.localeCompare(b.agent) || a.id.localeCompare(b.id));
+}
+
+//#endregion
+export { discoverEvalFiles };
+//# sourceMappingURL=discover.js.map

package/dist/evals/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","names":[],"sources":["../../src/evals/discover.ts"],"sourcesContent":["import { type Dirent, readdirSync } from \"node:fs\";\nimport path from \"node:path\";\n\nimport { agentDirNames } from \"../core/agent/agent-dirs\";\nimport { CODE_AGENTS_SOURCE_DIR } from \"../core/agent/load-code-agents\";\n\n/** An eval file found under `server/agents/<agent>/evals/`. */\nexport interface DiscoveredEval {\n  /** Absolute path to the `*.eval.ts` file. */\n  file: string;\n  /** Id relative to the agent's evals dir, without `.eval.ts` (e.g. `weather/basic`). */\n  id: string;\n  /** The agent id (the `server/agents/<agent>` directory name). */\n  agent: string;\n}\n\n/** Recursively collect `*.eval.ts` files under `dir`. Empty when `dir` is absent. */\nfunction evalFilesIn(dir: string): string[] {\n  try {\n    return readdirSync(dir, { recursive: true, withFileTypes: true })\n      .filter((e) => e.isFile() && e.name.endsWith(\".eval.ts\"))\n      .map((e) => path.join(e.parentPath, e.name));\n  } catch {\n    return [];\n  }\n}\n\n/**\n * Discover evals under `<rootDir>/server/agents/<agent>/evals/` — co-located\n * with each agent's `agent.{md,ts}` (same folder-per-agent layout the agents\n * plugin discovers). The agent id is the folder name; the eval id is the file\n * path relative to that evals dir with `.eval.ts` stripped. Sorted + stable.\n */\nexport function discoverEvalFiles(rootDir: string): DiscoveredEval[] {\n  const agentsDir = path.join(rootDir, CODE_AGENTS_SOURCE_DIR);\n  const out: DiscoveredEval[] = [];\n\n  let entries: Dirent[];\n  try {\n    entries = readdirSync(agentsDir, { withFileTypes: true });\n  } catch {\n    return out;\n  }\n\n  for (const agent of agentDirNames(entries)) {\n    const evalsDir = path.join(agentsDir, agent, \"evals\");\n    for (const file of evalFilesIn(evalsDir)) {\n      const id = path\n        .relative(evalsDir, file)\n        .replace(/\\.eval\\.ts$/, \"\")\n        .split(path.sep)\n        .join(\"/\");\n      out.push({ file, id, agent });\n    }\n  }\n\n  return out.sort(\n    (a, b) => a.agent.localeCompare(b.agent) || a.id.localeCompare(b.id),\n  );\n}\n"],"mappings":";;;;;;;AAiBA,SAAS,YAAY,KAAuB;AAC1C,KAAI;AACF,SAAO,YAAY,KAAK;GAAE,WAAW;GAAM,eAAe;GAAM,CAAC,CAC9D,QAAQ,MAAM,EAAE,QAAQ,IAAI,EAAE,KAAK,SAAS,WAAW,CAAC,CACxD,KAAK,MAAM,KAAK,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC;SACxC;AACN,SAAO,EAAE;;;;;;;;;AAUb,SAAgB,kBAAkB,SAAmC;CACnE,MAAM,YAAY,KAAK,KAAK,SAAS,uBAAuB;CAC5D,MAAM,MAAwB,EAAE;CAEhC,IAAI;AACJ,KAAI;AACF,YAAU,YAAY,WAAW,EAAE,eAAe,MAAM,CAAC;SACnD;AACN,SAAO;;AAGT,MAAK,MAAM,SAAS,cAAc,QAAQ,EAAE;EAC1C,MAAM,WAAW,KAAK,KAAK,WAAW,OAAO,QAAQ;AACrD,OAAK,MAAM,QAAQ,YAAY,SAAS,EAAE;GACxC,MAAM,KAAK,KACR,SAAS,UAAU,KAAK,CACxB,QAAQ,eAAe,GAAG,CAC1B,MAAM,KAAK,IAAI,CACf,KAAK,IAAI;AACZ,OAAI,KAAK;IAAE;IAAM;IAAI;IAAO,CAAC;;;AAIjC,QAAO,IAAI,MACR,GAAG,MAAM,EAAE,MAAM,cAAc,EAAE,MAAM,IAAI,EAAE,GAAG,cAAc,EAAE,GAAG,CACrE"}

package/dist/evals/http-driver.d.ts

@@ -0,0 +1,33 @@
+import { EvalDriver } from "./types.js";
+
+//#region src/evals/http-driver.d.ts
+interface HttpDriverOptions {
+  /** Base URL of the running app, e.g. `http://localhost:3000`. */
+  baseUrl: string;
+  /** Agent alias to target. Omit to use the app's default agent. */
+  agent?: string;
+  /** Extra request headers (e.g. auth for a deployed app). */
+  headers?: Record<string, string>;
+  /** Chat endpoint path. Defaults to `/api/agents/chat`. */
+  path?: string;
+  /** MLflow run id to link each turn's trace to (for evaluation runs). */
+  mlflowRunId?: string;
+  /**
+   * Max wall-clock time for a single turn before it is abandoned as a failed
+   * turn (`succeeded: false`). Without this a hung agent — a blocked tool, a
+   * stalled model — never ends the SSE stream (heartbeats keep it alive), so
+   * the read loop spins forever and wedges the whole sequential suite.
+   * Defaults to 120s.
+   */
+  timeoutMs?: number;
+}
+/**
+ * Drives an agent by POSTing to a running app's chat endpoint and parsing the
+ * SSE response. Keeps the thread id across `send`s so multi-turn evals share a
+ * conversation. Agent/stream errors surface as `succeeded: false` rather than
+ * throwing, so `t.succeeded()` can assert on them.
+ */
+declare function createHttpDriver(options: HttpDriverOptions): EvalDriver;
+//#endregion
+export { HttpDriverOptions, createHttpDriver };
+//# sourceMappingURL=http-driver.d.ts.map

package/dist/evals/http-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-driver.d.ts","names":[],"sources":["../../src/evals/http-driver.ts"],"mappings":";;;UAGiB,iBAAA;;EAEf,OAAA;EAFgC;EAIhC,KAAA;EAEgB;EAAhB,OAAA,GAAU,MAAA;EAFV;EAIA,IAAA;EAFU;EAIV,WAAA;EAAA;;;;AA6GF;;;EApGE,SAAA;AAAA;;;;;;;iBAoGc,gBAAA,CAAiB,OAAA,EAAS,iBAAA,GAAoB,UAAA"}

package/dist/evals/http-driver.js

@@ -0,0 +1,118 @@
+import { readSseEvents } from "../stream/sse-reader.js";
+
+//#region src/evals/http-driver.ts
+/** Record a `function_call` output item once per call id (deduped). */
+function recordToolCall(item, state) {
+	if (item?.type !== "function_call" || !item.name) return;
+	const key = item.call_id ?? item.name;
+	if (state.seen.has(key)) return;
+	state.seen.add(key);
+	state.toolCalls.push(item.name);
+}
+/** Apply an `appkit.metadata` event's thread/trace ids. */
+function applyMetadata(data, state, setThread) {
+	if (data?.threadId) setThread(data.threadId);
+	if (data?.mlflowTraceId) state.traceId = data.mlflowTraceId;
+}
+/** Parse a single Responses-API SSE `data:` payload into the running totals. */
+function applyEvent(event, state, setThread) {
+	const type = event.type;
+	if (type === "response.output_text.delta") {
+		if (typeof event.delta === "string") state.reply += event.delta;
+		return;
+	}
+	if (type === "response.output_item.added" || type === "response.output_item.done") {
+		const item = event.item;
+		recordToolCall(item, state);
+		if (type === "response.output_item.done" && item.type === "message") {
+			const text = (item.content ?? []).map((c) => c.text ?? "").join("");
+			if (text) state.reply = text;
+		}
+		return;
+	}
+	if (type === "error" || type === "response.failed") {
+		state.ok = false;
+		return;
+	}
+	if (type === "appkit.metadata") applyMetadata(event.data, state, setThread);
+}
+/** Build the chat request payload, including only the optional fields that are set. */
+function buildRequestBody(message, options, threadId) {
+	return JSON.stringify({
+		message,
+		...options.agent ? { agent: options.agent } : {},
+		...threadId ? { threadId } : {},
+		...options.mlflowRunId ? { mlflowRunId: options.mlflowRunId } : {}
+	});
+}
+/**
+* Drives an agent by POSTing to a running app's chat endpoint and parsing the
+* SSE response. Keeps the thread id across `send`s so multi-turn evals share a
+* conversation. Agent/stream errors surface as `succeeded: false` rather than
+* throwing, so `t.succeeded()` can assert on them.
+*/
+function createHttpDriver(options) {
+	const chatPath = options.path ?? "/api/agents/chat";
+	const timeoutMs = options.timeoutMs ?? 12e4;
+	let threadId;
+	return { async send(message) {
+		const signal = AbortSignal.timeout(timeoutMs);
+		let res;
+		try {
+			res = await fetch(`${options.baseUrl}${chatPath}`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					...options.headers
+				},
+				body: buildRequestBody(message, options, threadId),
+				redirect: "manual",
+				signal
+			});
+		} catch {
+			return {
+				reply: "",
+				toolCalls: [],
+				succeeded: false
+			};
+		}
+		if (!res.ok || !res.body) return {
+			reply: "",
+			toolCalls: [],
+			succeeded: false,
+			sessionId: threadId
+		};
+		const state = {
+			reply: "",
+			toolCalls: [],
+			seen: /* @__PURE__ */ new Set(),
+			ok: true
+		};
+		const setThread = (id) => {
+			threadId = id;
+		};
+		try {
+			for await (const { event, data } of readSseEvents(res.body, signal)) {
+				if (data === "[DONE]") continue;
+				if (event === "error") state.ok = false;
+				try {
+					applyEvent(JSON.parse(data), state, setThread);
+				} catch {}
+			}
+		} catch {
+			state.ok = false;
+		}
+		if (signal.aborted) state.ok = false;
+		return {
+			reply: state.reply,
+			toolCalls: state.toolCalls,
+			succeeded: state.ok,
+			sessionId: threadId,
+			traceId: state.traceId
+		};
+	} };
+}
+
+//#endregion
+export { createHttpDriver };
+//# sourceMappingURL=http-driver.js.map

package/dist/evals/http-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-driver.js","names":[],"sources":["../../src/evals/http-driver.ts"],"sourcesContent":["import { readSseEvents } from \"../stream/sse-reader\";\nimport type { DriveResult, EvalDriver } from \"./types\";\n\nexport interface HttpDriverOptions {\n  /** Base URL of the running app, e.g. `http://localhost:3000`. */\n  baseUrl: string;\n  /** Agent alias to target. Omit to use the app's default agent. */\n  agent?: string;\n  /** Extra request headers (e.g. auth for a deployed app). */\n  headers?: Record<string, string>;\n  /** Chat endpoint path. Defaults to `/api/agents/chat`. */\n  path?: string;\n  /** MLflow run id to link each turn's trace to (for evaluation runs). */\n  mlflowRunId?: string;\n  /**\n   * Max wall-clock time for a single turn before it is abandoned as a failed\n   * turn (`succeeded: false`). Without this a hung agent — a blocked tool, a\n   * stalled model — never ends the SSE stream (heartbeats keep it alive), so\n   * the read loop spins forever and wedges the whole sequential suite.\n   * Defaults to 120s.\n   */\n  // ponytail: total per-turn cap; switch to an idle timeout if long legit turns get killed.\n  timeoutMs?: number;\n}\n\n/** Mutable running totals accumulated while draining one turn's SSE stream. */\ninterface DriveState {\n  reply: string;\n  toolCalls: string[];\n  seen: Set<string>;\n  ok: boolean;\n  traceId?: string;\n}\n\n/** Record a `function_call` output item once per call id (deduped). */\nfunction recordToolCall(\n  item: { type?: string; name?: string; call_id?: string } | undefined,\n  state: DriveState,\n): void {\n  if (item?.type !== \"function_call\" || !item.name) return;\n  const key = item.call_id ?? item.name;\n  if (state.seen.has(key)) return;\n  state.seen.add(key);\n  state.toolCalls.push(item.name);\n}\n\n/** Apply an `appkit.metadata` event's thread/trace ids. */\nfunction applyMetadata(\n  data: { threadId?: string; mlflowTraceId?: string } | undefined,\n  state: DriveState,\n  setThread: (id: string) => void,\n): void {\n  if (data?.threadId) setThread(data.threadId);\n  if (data?.mlflowTraceId) state.traceId = data.mlflowTraceId;\n}\n\n/** Parse a single Responses-API SSE `data:` payload into the running totals. */\nfunction applyEvent(\n  event: Record<string, unknown>,\n  state: DriveState,\n  setThread: (id: string) => void,\n): void {\n  const type = event.type;\n  if (type === \"response.output_text.delta\") {\n    if (typeof event.delta === \"string\") state.reply += event.delta;\n    return;\n  }\n  if (\n    type === \"response.output_item.added\" ||\n    type === \"response.output_item.done\"\n  ) {\n    const item = event.item as {\n      type?: string;\n      name?: string;\n      call_id?: string;\n      content?: Array<{ text?: string }>;\n    };\n    recordToolCall(item, state);\n    // A terminal `message` item carries the full reply text and *replaces*\n    // the accumulated deltas — the server emits no delta for a full message\n    // (event-translator `handleFullMessage`), so a non-streaming adapter's\n    // whole reply arrives only here. Guard on non-empty so a streaming turn's\n    // trailing done event can't clobber the deltas with \"\".\n    if (type === \"response.output_item.done\" && item.type === \"message\") {\n      const text = (item.content ?? []).map((c) => c.text ?? \"\").join(\"\");\n      if (text) state.reply = text;\n    }\n    return;\n  }\n  if (type === \"error\" || type === \"response.failed\") {\n    state.ok = false;\n    return;\n  }\n  if (type === \"appkit.metadata\") {\n    applyMetadata(\n      event.data as { threadId?: string; mlflowTraceId?: string },\n      state,\n      setThread,\n    );\n  }\n}\n\n/** Build the chat request payload, including only the optional fields that are set. */\nfunction buildRequestBody(\n  message: string,\n  options: HttpDriverOptions,\n  threadId: string | undefined,\n): string {\n  return JSON.stringify({\n    message,\n    ...(options.agent ? { agent: options.agent } : {}),\n    ...(threadId ? { threadId } : {}),\n    ...(options.mlflowRunId ? { mlflowRunId: options.mlflowRunId } : {}),\n  });\n}\n\n/**\n * Drives an agent by POSTing to a running app's chat endpoint and parsing the\n * SSE response. Keeps the thread id across `send`s so multi-turn evals share a\n * conversation. Agent/stream errors surface as `succeeded: false` rather than\n * throwing, so `t.succeeded()` can assert on them.\n */\nexport function createHttpDriver(options: HttpDriverOptions): EvalDriver {\n  const chatPath = options.path ?? \"/api/agents/chat\";\n  const timeoutMs = options.timeoutMs ?? 120_000;\n  let threadId: string | undefined;\n\n  return {\n    async send(message: string): Promise<DriveResult> {\n      // Bounds connect + the entire read below. Passed to both the fetch and\n      // the SSE reader: on expiry the reader is cancelled and the turn fails.\n      const signal = AbortSignal.timeout(timeoutMs);\n      let res: Response;\n      try {\n        res = await fetch(`${options.baseUrl}${chatPath}`, {\n          method: \"POST\",\n          headers: { \"content-type\": \"application/json\", ...options.headers },\n          body: buildRequestBody(message, options, threadId),\n          // A chat endpoint never needs a redirect; following one would replay\n          // custom auth headers (`options.headers`) to the redirect target.\n          // A 3xx becomes an opaque response (res.ok === false), handled as a\n          // failed turn by the !res.ok guard below.\n          redirect: \"manual\",\n          signal,\n        });\n      } catch {\n        return { reply: \"\", toolCalls: [], succeeded: false };\n      }\n\n      if (!res.ok || !res.body) {\n        return {\n          reply: \"\",\n          toolCalls: [],\n          succeeded: false,\n          sessionId: threadId,\n        };\n      }\n\n      const state: DriveState = {\n        reply: \"\",\n        toolCalls: [],\n        seen: new Set<string>(),\n        ok: true,\n      };\n      const setThread = (id: string) => {\n        threadId = id;\n      };\n      try {\n        for await (const { event, data } of readSseEvents(res.body, signal)) {\n          if (data === \"[DONE]\") continue;\n          // A stream-level error frame (a thrown exception in the generator)\n          // is framed as `event: error` with a payload that carries no `type`,\n          // so the SSE event name — not the payload — is the real signal.\n          if (event === \"error\") state.ok = false;\n          try {\n            applyEvent(\n              JSON.parse(data) as Record<string, unknown>,\n              state,\n              setThread,\n            );\n          } catch {\n            // skip malformed event payloads\n          }\n        }\n      } catch {\n        // mid-stream transport error or DoS-guard throw: a broken turn.\n        state.ok = false;\n      }\n      // A timeout ends the iterator cleanly (reader cancel) rather than\n      // throwing, so mark an aborted turn failed explicitly.\n      if (signal.aborted) state.ok = false;\n\n      return {\n        reply: state.reply,\n        toolCalls: state.toolCalls,\n        succeeded: state.ok,\n        sessionId: threadId,\n        traceId: state.traceId,\n      };\n    },\n  };\n}\n"],"mappings":";;;;AAmCA,SAAS,eACP,MACA,OACM;AACN,KAAI,MAAM,SAAS,mBAAmB,CAAC,KAAK,KAAM;CAClD,MAAM,MAAM,KAAK,WAAW,KAAK;AACjC,KAAI,MAAM,KAAK,IAAI,IAAI,CAAE;AACzB,OAAM,KAAK,IAAI,IAAI;AACnB,OAAM,UAAU,KAAK,KAAK,KAAK;;;AAIjC,SAAS,cACP,MACA,OACA,WACM;AACN,KAAI,MAAM,SAAU,WAAU,KAAK,SAAS;AAC5C,KAAI,MAAM,cAAe,OAAM,UAAU,KAAK;;;AAIhD,SAAS,WACP,OACA,OACA,WACM;CACN,MAAM,OAAO,MAAM;AACnB,KAAI,SAAS,8BAA8B;AACzC,MAAI,OAAO,MAAM,UAAU,SAAU,OAAM,SAAS,MAAM;AAC1D;;AAEF,KACE,SAAS,gCACT,SAAS,6BACT;EACA,MAAM,OAAO,MAAM;AAMnB,iBAAe,MAAM,MAAM;AAM3B,MAAI,SAAS,+BAA+B,KAAK,SAAS,WAAW;GACnE,MAAM,QAAQ,KAAK,WAAW,EAAE,EAAE,KAAK,MAAM,EAAE,QAAQ,GAAG,CAAC,KAAK,GAAG;AACnE,OAAI,KAAM,OAAM,QAAQ;;AAE1B;;AAEF,KAAI,SAAS,WAAW,SAAS,mBAAmB;AAClD,QAAM,KAAK;AACX;;AAEF,KAAI,SAAS,kBACX,eACE,MAAM,MACN,OACA,UACD;;;AAKL,SAAS,iBACP,SACA,SACA,UACQ;AACR,QAAO,KAAK,UAAU;EACpB;EACA,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,OAAO,GAAG,EAAE;EACjD,GAAI,WAAW,EAAE,UAAU,GAAG,EAAE;EAChC,GAAI,QAAQ,cAAc,EAAE,aAAa,QAAQ,aAAa,GAAG,EAAE;EACpE,CAAC;;;;;;;;AASJ,SAAgB,iBAAiB,SAAwC;CACvE,MAAM,WAAW,QAAQ,QAAQ;CACjC,MAAM,YAAY,QAAQ,aAAa;CACvC,IAAI;AAEJ,QAAO,EACL,MAAM,KAAK,SAAuC;EAGhD,MAAM,SAAS,YAAY,QAAQ,UAAU;EAC7C,IAAI;AACJ,MAAI;AACF,SAAM,MAAM,MAAM,GAAG,QAAQ,UAAU,YAAY;IACjD,QAAQ;IACR,SAAS;KAAE,gBAAgB;KAAoB,GAAG,QAAQ;KAAS;IACnE,MAAM,iBAAiB,SAAS,SAAS,SAAS;IAKlD,UAAU;IACV;IACD,CAAC;UACI;AACN,UAAO;IAAE,OAAO;IAAI,WAAW,EAAE;IAAE,WAAW;IAAO;;AAGvD,MAAI,CAAC,IAAI,MAAM,CAAC,IAAI,KAClB,QAAO;GACL,OAAO;GACP,WAAW,EAAE;GACb,WAAW;GACX,WAAW;GACZ;EAGH,MAAM,QAAoB;GACxB,OAAO;GACP,WAAW,EAAE;GACb,sBAAM,IAAI,KAAa;GACvB,IAAI;GACL;EACD,MAAM,aAAa,OAAe;AAChC,cAAW;;AAEb,MAAI;AACF,cAAW,MAAM,EAAE,OAAO,UAAU,cAAc,IAAI,MAAM,OAAO,EAAE;AACnE,QAAI,SAAS,SAAU;AAIvB,QAAI,UAAU,QAAS,OAAM,KAAK;AAClC,QAAI;AACF,gBACE,KAAK,MAAM,KAAK,EAChB,OACA,UACD;YACK;;UAIJ;AAEN,SAAM,KAAK;;AAIb,MAAI,OAAO,QAAS,OAAM,KAAK;AAE/B,SAAO;GACL,OAAO,MAAM;GACb,WAAW,MAAM;GACjB,WAAW,MAAM;GACjB,WAAW;GACX,SAAS,MAAM;GAChB;IAEJ"}

package/dist/evals/index.js

@@ -0,0 +1,13 @@
+import { resolveDatabricksAuth } from "../connectors/mlflow/auth.js";
+import { MlflowClient, normalizeHost } from "../connectors/mlflow/client.js";
+import { defineEval } from "./define-eval.js";
+import { discoverEvalFiles } from "./discover.js";
+import { createHttpDriver } from "./http-driver.js";
+import { configureJudge, isJudgeConfigured } from "./judge.js";
+import { equals, includes, matches } from "./matchers.js";
+import { buildAssessments, reportToMlflow } from "./mlflow-report.js";
+import { evalGlyph, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, summarize } from "./report.js";
+import { runEval } from "./run-eval.js";
+import { runEvalsInDir } from "./run-evals.js";
+
+export {  };

package/dist/evals/judge.d.ts

@@ -0,0 +1,26 @@
+import { MlflowClient } from "../connectors/mlflow/client.js";
+
+//#region src/evals/judge.d.ts
+interface JudgeConfig {
+  /** Client for the workspace hosting the judge serving endpoint. */
+  client: MlflowClient;
+  /** Bearer token for the serving endpoint. */
+  token: string;
+  /** Serving endpoint name used as the judge model. */
+  model: string;
+}
+/** A normalized judge result. `score` is 0..1. */
+interface JudgeScore {
+  score: number;
+  rationale?: string;
+}
+/**
+ * Configure the judge once. Sets the OpenAI-compatible client env autoevals
+ * reads and the default judge model. No-op-safe: on failure, judging stays
+ * disabled and {@link isJudgeConfigured} returns false.
+ */
+declare function configureJudge(config: JudgeConfig): Promise<void>;
+declare function isJudgeConfigured(): boolean;
+//#endregion
+export { JudgeConfig, JudgeScore, configureJudge, isJudgeConfigured };
+//# sourceMappingURL=judge.d.ts.map

package/dist/evals/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","names":[],"sources":["../../src/evals/judge.ts"],"mappings":";;;UAuBiB,WAAA;;EAEf,MAAA,EAAQ,YAAA;EAFkB;EAI1B,KAAA;EAFoB;EAIpB,KAAA;AAAA;;UAIe,UAAA;EACf,KAAA;EACA,SAAA;AAAA;;;;;AAQF;iBAAsB,cAAA,CAAe,MAAA,EAAQ,WAAA,GAAc,OAAA;AAAA,iBAe3C,iBAAA,CAAA"}