@databricks/appkit 0.31.0 → 0.33.0

package/dist/core/plugin-context.d.ts

@@ -0,0 +1,133 @@
+import { ToolProvider } from "../shared/src/agent.js";
+import { BasePlugin, IAppRequest } from "../shared/src/plugin.js";
+import "../shared/src/index.js";
+import express from "express";
+
+//#region src/core/plugin-context.d.ts
+interface RouteTarget {
+  addExtension(fn: (app: express.Application) => void): void;
+}
+/**
+ * A tool-provider plugin that also exposes user-scoped execution. Plugins
+ * derived from {@link Plugin} satisfy this implicitly because `asUser` lives
+ * on the base class. {@link isToolProvider} narrows to this shape so
+ * `executeTool` can call `asUser` without an unsafe cast.
+ */
+type ToolProviderPlugin = BasePlugin & ToolProvider & {
+  asUser: (req: IAppRequest) => ToolProvider;
+};
+type LifecycleEvent = "setup:complete" | "server:ready" | "shutdown";
+/**
+ * Mediator for inter-plugin communication.
+ *
+ * Created by AppKit core and passed to every plugin. Plugins request
+ * capabilities from the context instead of holding direct references
+ * to sibling plugin instances.
+ *
+ * Capabilities:
+ * - Route mounting with buffering (order-independent)
+ * - Typed ToolProvider registry (live, not snapshot-based)
+ * - User-scoped tool execution with automatic telemetry
+ * - Lifecycle hooks for plugin coordination
+ */
+declare class PluginContext {
+  private routeBuffer;
+  private routeTarget;
+  private toolProviders;
+  private plugins;
+  private lifecycleHooks;
+  private telemetry;
+  /**
+   * Register a route on the root Express application.
+   *
+   * If a route target (server plugin) has registered, the route is applied
+   * immediately. Otherwise it is buffered and flushed when a route target
+   * becomes available.
+   */
+  addRoute(method: string, path: string, ...handlers: express.RequestHandler[]): void;
+  /**
+   * Register middleware on the root Express application.
+   *
+   * Same buffering semantics as `addRoute`.
+   */
+  addMiddleware(path: string, ...handlers: express.RequestHandler[]): void;
+  /**
+   * Called by the server plugin to opt in as the route target.
+   * Flushes all buffered routes via the server's `addExtension`.
+   *
+   * Only the first caller wins — subsequent calls are ignored with a warning.
+   * In practice only the server plugin registers, but a misconfigured app
+   * (two server plugins, or duplicate AppKit setup in tests) would otherwise
+   * silently drop the first target's later extensions.
+   */
+  registerAsRouteTarget(target: RouteTarget): void;
+  /**
+   * Register a plugin that implements the ToolProvider interface.
+   * Called by AppKit core after constructing each plugin.
+   *
+   * Plugin names should be unique (they are derived from `manifest.name`).
+   * A duplicate registration overwrites the previous entry and emits a
+   * warning so the misconfiguration is visible in startup logs.
+   */
+  registerToolProvider(name: string, plugin: ToolProviderPlugin): void;
+  /**
+   * Register a plugin instance.
+   * Called by AppKit core after constructing each plugin.
+   */
+  registerPlugin(name: string, instance: BasePlugin): void;
+  /**
+   * Returns all registered plugin instances keyed by name.
+   * Used by the server plugin for route injection, client config,
+   * and shutdown coordination. The returned map is read-only at the
+   * type level — callers must not mutate the live registry.
+   */
+  getPlugins(): ReadonlyMap<string, BasePlugin>;
+  /**
+   * Returns all registered ToolProvider plugins.
+   * Always returns the current set — not a frozen snapshot.
+   */
+  getToolProviders(): Array<{
+    name: string;
+    provider: ToolProvider;
+  }>;
+  /**
+   * Execute a tool on a ToolProvider plugin with automatic user scoping
+   * and telemetry.
+   *
+   * The context:
+   * 1. Resolves the plugin by name
+   * 2. Calls `asUser(req)` for user-scoped execution
+   * 3. Wraps the call in a telemetry span with a configurable timeout
+   *
+   * @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor
+   *   for cold SQL Warehouse round-trips, long Genie conversations, and
+   *   busy serverless Lakebase queries. The agents plugin overrides this
+   *   per-app via `agents({ limits: { toolCallTimeoutMs } })`.
+   */
+  executeTool(req: express.Request, pluginName: string, toolName: string, args: unknown, signal?: AbortSignal, timeoutMs?: number): Promise<unknown>;
+  /**
+   * Register a lifecycle hook callback.
+   */
+  onLifecycle(event: LifecycleEvent, fn: () => void | Promise<void>): void;
+  /**
+   * Emit a lifecycle event, calling all registered callbacks.
+   * Errors in individual callbacks are logged but do not prevent
+   * other callbacks from running.
+   *
+   * @internal Called by AppKit core only.
+   */
+  emitLifecycle(event: LifecycleEvent): Promise<void>;
+  /**
+   * Returns all registered plugin names.
+   */
+  getPluginNames(): string[];
+  /**
+   * Check if a plugin with the given name is registered.
+   */
+  hasPlugin(name: string): boolean;
+  private applyRoute;
+  private applyMiddleware;
+}
+//#endregion
+export { PluginContext };
+//# sourceMappingURL=plugin-context.d.ts.map

package/dist/core/plugin-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context.d.ts","names":[],"sources":["../../src/core/plugin-context.ts"],"mappings":";;;;;;UAaU,WAAA;EACR,YAAA,CAAa,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;AAAA;;AAbmC;;;;;KAsB/D,kBAAA,GAAqB,UAAA,GACxB,YAAA;EAAiB,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,YAAA;AAAA;AAAA,KAE5C,cAAA;;;AAZgD;;;;;;;;;;;cA2BxC,aAAA;EAAA,QACH,WAAA;EAAA,QACA,WAAA;EAAA,QACA,aAAA;EAAA,QACA,OAAA;EAAA,QACA,cAAA;EAAA,QAIA,SAAA;EAxBS;;;;AAenB;;;EAkBE,QAAA,CACE,MAAA,UACA,IAAA,aACG,QAAA,EAAU,OAAA,CAAQ,cAAA;EAckB;;;;;EAAzC,aAAA,CAAc,IAAA,aAAiB,QAAA,EAAU,OAAA,CAAQ,cAAA;EA4EG;;;;;;;;;EA3DpD,qBAAA,CAAsB,MAAA,EAAQ,WAAA;EAoJqB;;;;;;;;EAzHnD,oBAAA,CAAqB,IAAA,UAAc,MAAA,EAAQ,kBAAA;EA3DzC;;;;EAyEF,cAAA,CAAe,IAAA,UAAc,QAAA,EAAU,UAAA;EA1DzB;;;;;;EAoEd,UAAA,CAAA,GAAc,WAAA,SAAoB,UAAA;EAxBlC;;;;EAgCA,gBAAA,CAAA,GAAoB,KAAA;IAAQ,IAAA;IAAc,QAAA,EAAU,YAAA;EAAA;EARpD;;;;;;;;;;;;;;EA6BM,WAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,UAAA,UACA,QAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,EACT,SAAA,YACC,OAAA;EAFQ;;;EA+CX,WAAA,CAAY,KAAA,EAAO,cAAA,EAAgB,EAAA,eAAiB,OAAA;EAApD;;;;;;;EAgBM,aAAA,CAAc,KAAA,EAAO,cAAA,GAAiB,OAAA;EAAA;;;EA8B5C,cAAA,CAAA;EAWQ;;;EAJR,SAAA,CAAU,IAAA;EAAA,QAIF,UAAA;EAAA,QAaA,eAAA;AAAA"}

package/dist/core/plugin-context.js

@@ -0,0 +1,220 @@
+import { createLogger } from "../logging/logger.js";
+import { TelemetryManager } from "../telemetry/telemetry-manager.js";
+import { SpanStatusCode } from "../telemetry/index.js";
+
+//#region src/core/plugin-context.ts
+const logger = createLogger("plugin-context");
+/**
+* Mediator for inter-plugin communication.
+*
+* Created by AppKit core and passed to every plugin. Plugins request
+* capabilities from the context instead of holding direct references
+* to sibling plugin instances.
+*
+* Capabilities:
+* - Route mounting with buffering (order-independent)
+* - Typed ToolProvider registry (live, not snapshot-based)
+* - User-scoped tool execution with automatic telemetry
+* - Lifecycle hooks for plugin coordination
+*/
+var PluginContext = class {
+	routeBuffer = [];
+	routeTarget = null;
+	toolProviders = /* @__PURE__ */ new Map();
+	plugins = /* @__PURE__ */ new Map();
+	lifecycleHooks = /* @__PURE__ */ new Map();
+	telemetry = TelemetryManager.getProvider("plugin-context");
+	/**
+	* Register a route on the root Express application.
+	*
+	* If a route target (server plugin) has registered, the route is applied
+	* immediately. Otherwise it is buffered and flushed when a route target
+	* becomes available.
+	*/
+	addRoute(method, path, ...handlers) {
+		if (this.routeTarget) this.applyRoute({
+			method,
+			path,
+			handlers
+		});
+		else this.routeBuffer.push({
+			method,
+			path,
+			handlers
+		});
+	}
+	/**
+	* Register middleware on the root Express application.
+	*
+	* Same buffering semantics as `addRoute`.
+	*/
+	addMiddleware(path, ...handlers) {
+		if (this.routeTarget) this.applyMiddleware(path, handlers);
+		else this.routeBuffer.push({
+			method: "use",
+			path,
+			handlers
+		});
+	}
+	/**
+	* Called by the server plugin to opt in as the route target.
+	* Flushes all buffered routes via the server's `addExtension`.
+	*
+	* Only the first caller wins — subsequent calls are ignored with a warning.
+	* In practice only the server plugin registers, but a misconfigured app
+	* (two server plugins, or duplicate AppKit setup in tests) would otherwise
+	* silently drop the first target's later extensions.
+	*/
+	registerAsRouteTarget(target) {
+		if (this.routeTarget) {
+			logger.warn("registerAsRouteTarget called more than once; ignoring duplicate registration");
+			return;
+		}
+		this.routeTarget = target;
+		for (const route of this.routeBuffer) if (route.method === "use") this.applyMiddleware(route.path, route.handlers);
+		else this.applyRoute(route);
+		this.routeBuffer = [];
+	}
+	/**
+	* Register a plugin that implements the ToolProvider interface.
+	* Called by AppKit core after constructing each plugin.
+	*
+	* Plugin names should be unique (they are derived from `manifest.name`).
+	* A duplicate registration overwrites the previous entry and emits a
+	* warning so the misconfiguration is visible in startup logs.
+	*/
+	registerToolProvider(name, plugin) {
+		if (this.toolProviders.has(name)) logger.warn("Tool provider \"%s\" registered more than once; the previous registration is being overwritten", name);
+		this.toolProviders.set(name, plugin);
+	}
+	/**
+	* Register a plugin instance.
+	* Called by AppKit core after constructing each plugin.
+	*/
+	registerPlugin(name, instance) {
+		this.plugins.set(name, instance);
+	}
+	/**
+	* Returns all registered plugin instances keyed by name.
+	* Used by the server plugin for route injection, client config,
+	* and shutdown coordination. The returned map is read-only at the
+	* type level — callers must not mutate the live registry.
+	*/
+	getPlugins() {
+		return this.plugins;
+	}
+	/**
+	* Returns all registered ToolProvider plugins.
+	* Always returns the current set — not a frozen snapshot.
+	*/
+	getToolProviders() {
+		return Array.from(this.toolProviders.entries()).map(([name, provider]) => ({
+			name,
+			provider
+		}));
+	}
+	/**
+	* Execute a tool on a ToolProvider plugin with automatic user scoping
+	* and telemetry.
+	*
+	* The context:
+	* 1. Resolves the plugin by name
+	* 2. Calls `asUser(req)` for user-scoped execution
+	* 3. Wraps the call in a telemetry span with a configurable timeout
+	*
+	* @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor
+	*   for cold SQL Warehouse round-trips, long Genie conversations, and
+	*   busy serverless Lakebase queries. The agents plugin overrides this
+	*   per-app via `agents({ limits: { toolCallTimeoutMs } })`.
+	*/
+	async executeTool(req, pluginName, toolName, args, signal, timeoutMs = 3e5) {
+		const provider = this.toolProviders.get(pluginName);
+		if (!provider) throw new Error(`PluginContext: unknown plugin "${pluginName}". Available: ${Array.from(this.toolProviders.keys()).join(", ")}`);
+		const tracer = this.telemetry.getTracer();
+		const operationName = `executeTool:${pluginName}.${toolName}`;
+		return tracer.startActiveSpan(operationName, async (span) => {
+			const timeoutSignal = AbortSignal.timeout(timeoutMs);
+			const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+			try {
+				const result = await provider.asUser(req).executeAgentTool(toolName, args, combinedSignal);
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error instanceof Error ? error.message : "Tool execution failed"
+				});
+				span.recordException(error instanceof Error ? error : new Error(String(error)));
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	}
+	/**
+	* Register a lifecycle hook callback.
+	*/
+	onLifecycle(event, fn) {
+		let hooks = this.lifecycleHooks.get(event);
+		if (!hooks) {
+			hooks = /* @__PURE__ */ new Set();
+			this.lifecycleHooks.set(event, hooks);
+		}
+		hooks.add(fn);
+	}
+	/**
+	* Emit a lifecycle event, calling all registered callbacks.
+	* Errors in individual callbacks are logged but do not prevent
+	* other callbacks from running.
+	*
+	* @internal Called by AppKit core only.
+	*/
+	async emitLifecycle(event) {
+		const hooks = this.lifecycleHooks.get(event);
+		if (!hooks) return;
+		if (event === "setup:complete" && this.routeBuffer.length > 0 && !this.routeTarget) logger.warn("%d buffered routes were never applied — no server plugin registered as route target", this.routeBuffer.length);
+		for (const fn of [...hooks]) try {
+			await fn();
+		} catch (error) {
+			logger.error("Lifecycle hook '%s' failed: %O", event, error);
+		}
+	}
+	/**
+	* Returns all registered plugin names.
+	*/
+	getPluginNames() {
+		return Array.from(this.plugins.keys());
+	}
+	/**
+	* Check if a plugin with the given name is registered.
+	*/
+	hasPlugin(name) {
+		return this.plugins.has(name);
+	}
+	applyRoute(route) {
+		if (!this.routeTarget) return;
+		this.routeTarget.addExtension((app) => {
+			const method = route.method.toLowerCase();
+			if (typeof app[method] === "function") app[method](route.path, ...route.handlers);
+		});
+	}
+	applyMiddleware(path, handlers) {
+		if (!this.routeTarget) return;
+		this.routeTarget.addExtension((app) => {
+			app.use(path, ...handlers);
+		});
+	}
+};
+/**
+* Type guard: checks whether a plugin implements the ToolProvider interface
+* and exposes the user-scoped `asUser` helper that the {@link Plugin} base
+* class provides. Narrowing to {@link ToolProviderPlugin} lets `executeTool`
+* call `asUser` without an unsafe cast.
+*/
+function isToolProvider(plugin) {
+	return typeof plugin === "object" && plugin !== null && "getAgentTools" in plugin && typeof plugin.getAgentTools === "function" && "executeAgentTool" in plugin && typeof plugin.executeAgentTool === "function" && "asUser" in plugin && typeof plugin.asUser === "function";
+}
+
+//#endregion
+export { PluginContext, isToolProvider };
+//# sourceMappingURL=plugin-context.js.map

package/dist/core/plugin-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context.js","names":[],"sources":["../../src/core/plugin-context.ts"],"sourcesContent":["import type express from \"express\";\nimport type { BasePlugin, IAppRequest, ToolProvider } from \"shared\";\nimport { createLogger } from \"../logging/logger\";\nimport { SpanStatusCode, TelemetryManager } from \"../telemetry\";\n\nconst logger = createLogger(\"plugin-context\");\n\ninterface BufferedRoute {\n  method: string;\n  path: string;\n  handlers: express.RequestHandler[];\n}\n\ninterface RouteTarget {\n  addExtension(fn: (app: express.Application) => void): void;\n}\n\n/**\n * A tool-provider plugin that also exposes user-scoped execution. Plugins\n * derived from {@link Plugin} satisfy this implicitly because `asUser` lives\n * on the base class. {@link isToolProvider} narrows to this shape so\n * `executeTool` can call `asUser` without an unsafe cast.\n */\ntype ToolProviderPlugin = BasePlugin &\n  ToolProvider & { asUser: (req: IAppRequest) => ToolProvider };\n\ntype LifecycleEvent = \"setup:complete\" | \"server:ready\" | \"shutdown\";\n\n/**\n * Mediator for inter-plugin communication.\n *\n * Created by AppKit core and passed to every plugin. Plugins request\n * capabilities from the context instead of holding direct references\n * to sibling plugin instances.\n *\n * Capabilities:\n * - Route mounting with buffering (order-independent)\n * - Typed ToolProvider registry (live, not snapshot-based)\n * - User-scoped tool execution with automatic telemetry\n * - Lifecycle hooks for plugin coordination\n */\nexport class PluginContext {\n  private routeBuffer: BufferedRoute[] = [];\n  private routeTarget: RouteTarget | null = null;\n  private toolProviders = new Map<string, ToolProviderPlugin>();\n  private plugins = new Map<string, BasePlugin>();\n  private lifecycleHooks = new Map<\n    LifecycleEvent,\n    Set<() => void | Promise<void>>\n  >();\n  private telemetry = TelemetryManager.getProvider(\"plugin-context\");\n\n  /**\n   * Register a route on the root Express application.\n   *\n   * If a route target (server plugin) has registered, the route is applied\n   * immediately. Otherwise it is buffered and flushed when a route target\n   * becomes available.\n   */\n  addRoute(\n    method: string,\n    path: string,\n    ...handlers: express.RequestHandler[]\n  ): void {\n    if (this.routeTarget) {\n      this.applyRoute({ method, path, handlers });\n    } else {\n      this.routeBuffer.push({ method, path, handlers });\n    }\n  }\n\n  /**\n   * Register middleware on the root Express application.\n   *\n   * Same buffering semantics as `addRoute`.\n   */\n  addMiddleware(path: string, ...handlers: express.RequestHandler[]): void {\n    if (this.routeTarget) {\n      this.applyMiddleware(path, handlers);\n    } else {\n      this.routeBuffer.push({ method: \"use\", path, handlers });\n    }\n  }\n\n  /**\n   * Called by the server plugin to opt in as the route target.\n   * Flushes all buffered routes via the server's `addExtension`.\n   *\n   * Only the first caller wins — subsequent calls are ignored with a warning.\n   * In practice only the server plugin registers, but a misconfigured app\n   * (two server plugins, or duplicate AppKit setup in tests) would otherwise\n   * silently drop the first target's later extensions.\n   */\n  registerAsRouteTarget(target: RouteTarget): void {\n    if (this.routeTarget) {\n      logger.warn(\n        \"registerAsRouteTarget called more than once; ignoring duplicate registration\",\n      );\n      return;\n    }\n    this.routeTarget = target;\n\n    for (const route of this.routeBuffer) {\n      if (route.method === \"use\") {\n        this.applyMiddleware(route.path, route.handlers);\n      } else {\n        this.applyRoute(route);\n      }\n    }\n    this.routeBuffer = [];\n  }\n\n  /**\n   * Register a plugin that implements the ToolProvider interface.\n   * Called by AppKit core after constructing each plugin.\n   *\n   * Plugin names should be unique (they are derived from `manifest.name`).\n   * A duplicate registration overwrites the previous entry and emits a\n   * warning so the misconfiguration is visible in startup logs.\n   */\n  registerToolProvider(name: string, plugin: ToolProviderPlugin): void {\n    if (this.toolProviders.has(name)) {\n      logger.warn(\n        'Tool provider \"%s\" registered more than once; the previous registration is being overwritten',\n        name,\n      );\n    }\n    this.toolProviders.set(name, plugin);\n  }\n\n  /**\n   * Register a plugin instance.\n   * Called by AppKit core after constructing each plugin.\n   */\n  registerPlugin(name: string, instance: BasePlugin): void {\n    this.plugins.set(name, instance);\n  }\n\n  /**\n   * Returns all registered plugin instances keyed by name.\n   * Used by the server plugin for route injection, client config,\n   * and shutdown coordination. The returned map is read-only at the\n   * type level — callers must not mutate the live registry.\n   */\n  getPlugins(): ReadonlyMap<string, BasePlugin> {\n    return this.plugins;\n  }\n\n  /**\n   * Returns all registered ToolProvider plugins.\n   * Always returns the current set — not a frozen snapshot.\n   */\n  getToolProviders(): Array<{ name: string; provider: ToolProvider }> {\n    return Array.from(this.toolProviders.entries()).map(([name, provider]) => ({\n      name,\n      provider,\n    }));\n  }\n\n  /**\n   * Execute a tool on a ToolProvider plugin with automatic user scoping\n   * and telemetry.\n   *\n   * The context:\n   * 1. Resolves the plugin by name\n   * 2. Calls `asUser(req)` for user-scoped execution\n   * 3. Wraps the call in a telemetry span with a configurable timeout\n   *\n   * @param timeoutMs Per-call timeout. Defaults to 5 minutes — the floor\n   *   for cold SQL Warehouse round-trips, long Genie conversations, and\n   *   busy serverless Lakebase queries. The agents plugin overrides this\n   *   per-app via `agents({ limits: { toolCallTimeoutMs } })`.\n   */\n  async executeTool(\n    req: express.Request,\n    pluginName: string,\n    toolName: string,\n    args: unknown,\n    signal?: AbortSignal,\n    timeoutMs: number = 300_000,\n  ): Promise<unknown> {\n    const provider = this.toolProviders.get(pluginName);\n    if (!provider) {\n      throw new Error(\n        `PluginContext: unknown plugin \"${pluginName}\". Available: ${Array.from(this.toolProviders.keys()).join(\", \")}`,\n      );\n    }\n\n    const tracer = this.telemetry.getTracer();\n    const operationName = `executeTool:${pluginName}.${toolName}`;\n\n    return tracer.startActiveSpan(operationName, async (span) => {\n      const timeoutSignal = AbortSignal.timeout(timeoutMs);\n      const combinedSignal = signal\n        ? AbortSignal.any([signal, timeoutSignal])\n        : timeoutSignal;\n\n      try {\n        const userScoped = provider.asUser(req);\n        const result = await userScoped.executeAgentTool(\n          toolName,\n          args,\n          combinedSignal,\n        );\n        span.setStatus({ code: SpanStatusCode.OK });\n        return result;\n      } catch (error) {\n        span.setStatus({\n          code: SpanStatusCode.ERROR,\n          message:\n            error instanceof Error ? error.message : \"Tool execution failed\",\n        });\n        span.recordException(\n          error instanceof Error ? error : new Error(String(error)),\n        );\n        throw error;\n      } finally {\n        span.end();\n      }\n    });\n  }\n\n  /**\n   * Register a lifecycle hook callback.\n   */\n  onLifecycle(event: LifecycleEvent, fn: () => void | Promise<void>): void {\n    let hooks = this.lifecycleHooks.get(event);\n    if (!hooks) {\n      hooks = new Set();\n      this.lifecycleHooks.set(event, hooks);\n    }\n    hooks.add(fn);\n  }\n\n  /**\n   * Emit a lifecycle event, calling all registered callbacks.\n   * Errors in individual callbacks are logged but do not prevent\n   * other callbacks from running.\n   *\n   * @internal Called by AppKit core only.\n   */\n  async emitLifecycle(event: LifecycleEvent): Promise<void> {\n    const hooks = this.lifecycleHooks.get(event);\n    if (!hooks) return;\n\n    if (\n      event === \"setup:complete\" &&\n      this.routeBuffer.length > 0 &&\n      !this.routeTarget\n    ) {\n      logger.warn(\n        \"%d buffered routes were never applied — no server plugin registered as route target\",\n        this.routeBuffer.length,\n      );\n    }\n\n    // Snapshot before iterating so a callback that registers a new hook for\n    // the same event does not mutate the loop. ECMAScript Set iteration would\n    // otherwise visit late-added entries, risking unexpected re-entry.\n    for (const fn of [...hooks]) {\n      try {\n        await fn();\n      } catch (error) {\n        logger.error(\"Lifecycle hook '%s' failed: %O\", event, error);\n      }\n    }\n  }\n\n  /**\n   * Returns all registered plugin names.\n   */\n  getPluginNames(): string[] {\n    return Array.from(this.plugins.keys());\n  }\n\n  /**\n   * Check if a plugin with the given name is registered.\n   */\n  hasPlugin(name: string): boolean {\n    return this.plugins.has(name);\n  }\n\n  private applyRoute(route: BufferedRoute): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      const method = route.method.toLowerCase() as keyof express.Application;\n      if (typeof app[method] === \"function\") {\n        (app[method] as (...a: unknown[]) => void)(\n          route.path,\n          ...route.handlers,\n        );\n      }\n    });\n  }\n\n  private applyMiddleware(\n    path: string,\n    handlers: express.RequestHandler[],\n  ): void {\n    if (!this.routeTarget) return;\n    this.routeTarget.addExtension((app) => {\n      app.use(path, ...handlers);\n    });\n  }\n}\n\n/**\n * Type guard: checks whether a plugin implements the ToolProvider interface\n * and exposes the user-scoped `asUser` helper that the {@link Plugin} base\n * class provides. Narrowing to {@link ToolProviderPlugin} lets `executeTool`\n * call `asUser` without an unsafe cast.\n */\nexport function isToolProvider(plugin: unknown): plugin is ToolProviderPlugin {\n  return (\n    typeof plugin === \"object\" &&\n    plugin !== null &&\n    \"getAgentTools\" in plugin &&\n    typeof (plugin as ToolProvider).getAgentTools === \"function\" &&\n    \"executeAgentTool\" in plugin &&\n    typeof (plugin as ToolProvider).executeAgentTool === \"function\" &&\n    \"asUser\" in plugin &&\n    typeof (plugin as { asUser?: unknown }).asUser === \"function\"\n  );\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -4,14 +4,23 @@ import { CacheConfig } from "./shared/src/cache.js";
 import { StreamExecutionSettings } from "./shared/src/execute.js";
 import { isSQLTypeMarker, sql } from "./shared/src/sql/helpers.js";
 import "./shared/src/index.js";
+import { ExecutionResult } from "./plugin/execution-result.js";
 import { CacheManager } from "./cache/index.js";
+import { ITelemetry, TelemetryConfig } from "./telemetry/types.js";
+import { Counter, Histogram, SeverityNumber, Span, SpanStatusCode } from "./telemetry/index.js";
+import { Plugin } from "./plugin/plugin.js";
+import { toPlugin } from "./plugin/to-plugin.js";
+import "./plugin/index.js";
+import { ResourcePermission, ResourceType } from "./registry/types.generated.js";
+import { ConfigSchema, PluginManifest, ResourceEntry, ResourceRequirement, ValidationResult } from "./registry/types.js";
+import { getPluginManifest, getResourceRequirements } from "./registry/manifest-loader.js";
+import { ResourceRegistry } from "./registry/resource-registry.js";
+import "./registry/index.js";
 import { JobsConnectorConfig } from "./connectors/jobs/types.js";
 import "./connectors/jobs/index.js";
 import { DatabaseCredential, GenerateDatabaseCredentialRequest, LakebasePoolConfig, RequestedClaims, RequestedClaimsPermissionSet, RequestedResource, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getUsernameWithApiLookup, getWorkspaceClient } from "./connectors/lakebase/index.js";
 import { getExecutionContext } from "./context/execution-context.js";
 import "./context/index.js";
-import { ITelemetry, TelemetryConfig } from "./telemetry/types.js";
-import { Counter, Histogram, SeverityNumber, Span, SpanStatusCode } from "./telemetry/index.js";
 import { createApp } from "./core/appkit.js";
 import "./core/index.js";
 import { AppKitError } from "./errors/base.js";
@@ -23,16 +32,7 @@ import { InitializationError } from "./errors/initialization.js";
 import { ServerError } from "./errors/server.js";
 import { TunnelError } from "./errors/tunnel.js";
 import { ValidationError } from "./errors/validation.js";
-import { ExecutionResult } from "./plugin/execution-result.js";
-import { Plugin } from "./plugin/plugin.js";
-import { toPlugin } from "./plugin/to-plugin.js";
-import "./plugin/index.js";
 import { FileAction, FilePolicy, FilePolicyUser, FileResource, PolicyDeniedError, READ_ACTIONS, WRITE_ACTIONS } from "./plugins/files/policy.js";
-import { ResourcePermission, ResourceType } from "./registry/types.generated.js";
-import { ConfigSchema, PluginManifest, ResourceEntry, ResourceRequirement, ValidationResult } from "./registry/types.js";
-import { getPluginManifest, getResourceRequirements } from "./registry/manifest-loader.js";
-import { ResourceRegistry } from "./registry/resource-registry.js";
-import "./registry/index.js";
 import { analytics } from "./plugins/analytics/analytics.js";
 import { files } from "./plugins/files/plugin.js";
 import { genie } from "./plugins/genie/genie.js";

package/dist/internal-telemetry/appkit-log.js

@@ -0,0 +1,19 @@
+//#region src/internal-telemetry/appkit-log.ts
+function wrapAppkitLog(log) {
+	return {
+		frontend_log_event_id: `appkit-${log.event_name.toLowerCase()}-${crypto.randomUUID()}`,
+		inferred_timestamp_millis: Date.now(),
+		entry: { appkit_log: log }
+	};
+}
+function buildAppkitPayload(logs) {
+	return {
+		uploadTime: Date.now(),
+		items: [],
+		protoLogs: logs.map((log) => JSON.stringify(wrapAppkitLog(log)))
+	};
+}
+
+//#endregion
+export { buildAppkitPayload };
+//# sourceMappingURL=appkit-log.js.map

package/dist/internal-telemetry/appkit-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appkit-log.js","names":[],"sources":["../../src/internal-telemetry/appkit-log.ts"],"sourcesContent":["// IMPORTANT: keep this file in sync with the AppkitLog proto schema served by\n// the Databricks client telemetry endpoint. Field names use proto JSON\n// conventions (snake_case) so the wire format matches the backend.\n\nexport type AppkitEventName =\n  | \"APPKIT_EVENT_NAME_UNSPECIFIED\"\n  | \"APP_STARTUP\"\n  | \"HEARTBEAT\"\n  | \"REQUEST_METRICS\";\n\nexport type AppStartupEvent = Record<string, never>;\n\nexport type HeartbeatEvent = Record<string, never>;\n\nexport interface RequestMetricsEvent {\n  endpoint?: string;\n  request_count?: number;\n  request_latency_ms_avg?: number;\n  response_count_http4xx?: number;\n  response_count_http5xx?: number;\n}\n\nexport interface AppkitLog {\n  event_name: AppkitEventName;\n  app_id?: string;\n  appkit_version?: string;\n  app_startup_event?: AppStartupEvent;\n  heartbeat_event?: HeartbeatEvent;\n  request_metrics_event?: RequestMetricsEvent;\n}\n\ninterface AppkitLogEnvelope {\n  frontend_log_event_id: string;\n  inferred_timestamp_millis: number;\n  entry: { appkit_log: AppkitLog };\n}\n\ninterface TelemetryPayload {\n  uploadTime: number;\n  items: never[];\n  protoLogs: string[];\n}\n\nexport function wrapAppkitLog(log: AppkitLog): AppkitLogEnvelope {\n  return {\n    frontend_log_event_id: `appkit-${log.event_name.toLowerCase()}-${crypto.randomUUID()}`,\n    inferred_timestamp_millis: Date.now(),\n    entry: { appkit_log: log },\n  };\n}\n\nexport function buildAppkitPayload(logs: AppkitLog[]): TelemetryPayload {\n  return {\n    uploadTime: Date.now(),\n    items: [],\n    protoLogs: logs.map((log) => JSON.stringify(wrapAppkitLog(log))),\n  };\n}\n"],"mappings":";AA2CA,SAAgB,cAAc,KAAmC;AAC/D,QAAO;EACL,uBAAuB,UAAU,IAAI,WAAW,aAAa,CAAC,GAAG,OAAO,YAAY;EACpF,2BAA2B,KAAK,KAAK;EACrC,OAAO,EAAE,YAAY,KAAK;EAC3B;;AAGH,SAAgB,mBAAmB,MAAqC;AACtE,QAAO;EACL,YAAY,KAAK,KAAK;EACtB,OAAO,EAAE;EACT,WAAW,KAAK,KAAK,QAAQ,KAAK,UAAU,cAAc,IAAI,CAAC,CAAC;EACjE"}

package/dist/internal-telemetry/config.js

@@ -0,0 +1,15 @@
+//#region src/internal-telemetry/config.ts
+/**
+* Checks whether internal telemetry is enabled.
+* Shared across all telemetry event types (startup, heartbeat, metrics, etc.).
+*/
+function isInternalTelemetryEnabled(opts) {
+	if (opts?.disableInternalTelemetry) return false;
+	if (process.env.DISABLE_APPKIT_INTERNAL_TELEMETRY === "true") return false;
+	if (process.env.DO_NOT_TRACK === "1") return false;
+	return true;
+}
+
+//#endregion
+export { isInternalTelemetryEnabled };
+//# sourceMappingURL=config.js.map

package/dist/internal-telemetry/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":[],"sources":["../../src/internal-telemetry/config.ts"],"sourcesContent":["/**\n * Checks whether internal telemetry is enabled.\n * Shared across all telemetry event types (startup, heartbeat, metrics, etc.).\n */\nexport function isInternalTelemetryEnabled(opts?: {\n  disableInternalTelemetry?: boolean;\n}): boolean {\n  if (opts?.disableInternalTelemetry) return false;\n  if (process.env.DISABLE_APPKIT_INTERNAL_TELEMETRY === \"true\") return false;\n  if (process.env.DO_NOT_TRACK === \"1\") return false;\n  return true;\n}\n"],"mappings":";;;;;AAIA,SAAgB,2BAA2B,MAE/B;AACV,KAAI,MAAM,yBAA0B,QAAO;AAC3C,KAAI,QAAQ,IAAI,sCAAsC,OAAQ,QAAO;AACrE,KAAI,QAAQ,IAAI,iBAAiB,IAAK,QAAO;AAC7C,QAAO"}

package/dist/internal-telemetry/index.js

@@ -0,0 +1,4 @@
+import { isInternalTelemetryEnabled } from "./config.js";
+import { TelemetryReporter } from "./reporter.js";
+
+export {  };

package/dist/internal-telemetry/reporter.js

@@ -0,0 +1,132 @@
+import { buildAppkitPayload } from "./appkit-log.js";
+
+//#region src/internal-telemetry/reporter.ts
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 300 * 1e3;
+const DEFAULT_METRICS_FLUSH_INTERVAL_MS = 60 * 1e3;
+function envIntervalMs(name, fallback) {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	const n = Number(raw);
+	return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+var TelemetryReporter = class TelemetryReporter {
+	static #instance = null;
+	#workspaceIdPromise;
+	#client;
+	#appId;
+	#appkitVersion;
+	#heartbeatIntervalMs;
+	#metricsFlushIntervalMs;
+	#heartbeatTimer = null;
+	#metricsTimer = null;
+	#buckets = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.#workspaceIdPromise = Promise.resolve(opts.workspaceId);
+		this.#workspaceIdPromise.catch(() => {});
+		this.#client = opts.client;
+		this.#appId = opts.appId;
+		this.#appkitVersion = opts.appkitVersion;
+		this.#heartbeatIntervalMs = opts.heartbeatIntervalMs ?? envIntervalMs("APPKIT_TELEMETRY_HEARTBEAT_INTERVAL_MS", DEFAULT_HEARTBEAT_INTERVAL_MS);
+		this.#metricsFlushIntervalMs = opts.metricsFlushIntervalMs ?? envIntervalMs("APPKIT_TELEMETRY_METRICS_FLUSH_INTERVAL_MS", DEFAULT_METRICS_FLUSH_INTERVAL_MS);
+	}
+	static initialize(opts) {
+		TelemetryReporter.#instance?.stop();
+		TelemetryReporter.#instance = new TelemetryReporter(opts);
+		return TelemetryReporter.#instance;
+	}
+	static getInstance() {
+		return TelemetryReporter.#instance;
+	}
+	/** @internal Test-only reset. */
+	static _reset() {
+		TelemetryReporter.#instance?.stop();
+		TelemetryReporter.#instance = null;
+	}
+	start() {
+		if (this.#heartbeatTimer || this.#metricsTimer) return;
+		this.#heartbeatTimer = setInterval(() => {
+			this.sendHeartbeat().catch(() => {});
+		}, this.#heartbeatIntervalMs);
+		this.#heartbeatTimer.unref?.();
+		this.#metricsTimer = setInterval(() => {
+			this.flushRequestMetrics().catch(() => {});
+		}, this.#metricsFlushIntervalMs);
+		this.#metricsTimer.unref?.();
+	}
+	stop() {
+		if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
+		if (this.#metricsTimer) clearInterval(this.#metricsTimer);
+		this.#heartbeatTimer = null;
+		this.#metricsTimer = null;
+	}
+	recordRequest(method, routeTemplate, statusCode, latencyMs) {
+		if (!routeTemplate) return;
+		const key = `${method.toUpperCase()} ${routeTemplate}`;
+		const bucket = this.#buckets.get(key) ?? {
+			count: 0,
+			latencyMsTotal: 0,
+			http4xx: 0,
+			http5xx: 0
+		};
+		bucket.count += 1;
+		bucket.latencyMsTotal += Math.max(0, latencyMs);
+		if (statusCode >= 400 && statusCode < 500) bucket.http4xx += 1;
+		if (statusCode >= 500 && statusCode < 600) bucket.http5xx += 1;
+		this.#buckets.set(key, bucket);
+	}
+	async sendStartup() {
+		await this.#send([this.#wrap({
+			event_name: "APP_STARTUP",
+			app_startup_event: {}
+		})]);
+	}
+	async sendHeartbeat() {
+		await this.#send([this.#wrap({
+			event_name: "HEARTBEAT",
+			heartbeat_event: {}
+		})]);
+	}
+	async flushRequestMetrics() {
+		if (this.#buckets.size === 0) return;
+		const drained = this.#buckets;
+		this.#buckets = /* @__PURE__ */ new Map();
+		const logs = [];
+		for (const [endpoint, bucket] of drained) {
+			const event = {
+				endpoint,
+				request_count: bucket.count,
+				request_latency_ms_avg: Math.round(bucket.latencyMsTotal / bucket.count),
+				response_count_http4xx: bucket.http4xx,
+				response_count_http5xx: bucket.http5xx
+			};
+			logs.push(this.#wrap({
+				event_name: "REQUEST_METRICS",
+				request_metrics_event: event
+			}));
+		}
+		await this.#send(logs);
+	}
+	#wrap(partial) {
+		return {
+			...partial,
+			app_id: this.#appId,
+			appkit_version: this.#appkitVersion
+		};
+	}
+	async #send(logs) {
+		if (logs.length === 0) return;
+		const workspaceId = await this.#workspaceIdPromise;
+		await this.#client.apiClient.request({
+			path: "/telemetry-ext",
+			method: "POST",
+			query: { o: workspaceId },
+			headers: new Headers(),
+			payload: buildAppkitPayload(logs),
+			raw: false
+		});
+	}
+};
+
+//#endregion
+export { TelemetryReporter };
+//# sourceMappingURL=reporter.js.map

package/dist/internal-telemetry/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","names":["#instance","#workspaceIdPromise","#client","#appId","#appkitVersion","#heartbeatIntervalMs","#metricsFlushIntervalMs","#heartbeatTimer","#metricsTimer","#buckets","#send","#wrap"],"sources":["../../src/internal-telemetry/reporter.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport {\n  type AppkitLog,\n  buildAppkitPayload,\n  type RequestMetricsEvent,\n} from \"./appkit-log\";\n\nconst DEFAULT_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;\nconst DEFAULT_METRICS_FLUSH_INTERVAL_MS = 60 * 1000;\n\ninterface ReporterOptions {\n  workspaceId: Promise<string> | string;\n  client: WorkspaceClient;\n  appId: string;\n  appkitVersion: string;\n  heartbeatIntervalMs?: number;\n  metricsFlushIntervalMs?: number;\n}\n\ninterface RequestBucket {\n  count: number;\n  latencyMsTotal: number;\n  http4xx: number;\n  http5xx: number;\n}\n\nfunction envIntervalMs(name: string, fallback: number): number {\n  const raw = process.env[name];\n  if (!raw) return fallback;\n  const n = Number(raw);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n\nexport class TelemetryReporter {\n  static #instance: TelemetryReporter | null = null;\n\n  readonly #workspaceIdPromise: Promise<string>;\n  readonly #client: WorkspaceClient;\n  readonly #appId: string;\n  readonly #appkitVersion: string;\n  readonly #heartbeatIntervalMs: number;\n  readonly #metricsFlushIntervalMs: number;\n\n  #heartbeatTimer: NodeJS.Timeout | null = null;\n  #metricsTimer: NodeJS.Timeout | null = null;\n  #buckets: Map<string, RequestBucket> = new Map();\n\n  private constructor(opts: ReporterOptions) {\n    this.#workspaceIdPromise = Promise.resolve(opts.workspaceId);\n    // Mark the rejection (if any) as handled so a misconfigured workspaceId\n    // doesn't trigger an unhandled-rejection warning before the first #send\n    // awaits it. The original promise still rejects when awaited.\n    this.#workspaceIdPromise.catch(() => {});\n    this.#client = opts.client;\n    this.#appId = opts.appId;\n    this.#appkitVersion = opts.appkitVersion;\n    this.#heartbeatIntervalMs =\n      opts.heartbeatIntervalMs ??\n      envIntervalMs(\n        \"APPKIT_TELEMETRY_HEARTBEAT_INTERVAL_MS\",\n        DEFAULT_HEARTBEAT_INTERVAL_MS,\n      );\n    this.#metricsFlushIntervalMs =\n      opts.metricsFlushIntervalMs ??\n      envIntervalMs(\n        \"APPKIT_TELEMETRY_METRICS_FLUSH_INTERVAL_MS\",\n        DEFAULT_METRICS_FLUSH_INTERVAL_MS,\n      );\n  }\n\n  static initialize(opts: ReporterOptions): TelemetryReporter {\n    TelemetryReporter.#instance?.stop();\n    TelemetryReporter.#instance = new TelemetryReporter(opts);\n    return TelemetryReporter.#instance;\n  }\n\n  static getInstance(): TelemetryReporter | null {\n    return TelemetryReporter.#instance;\n  }\n\n  /** @internal Test-only reset. */\n  static _reset(): void {\n    TelemetryReporter.#instance?.stop();\n    TelemetryReporter.#instance = null;\n  }\n\n  start(): void {\n    if (this.#heartbeatTimer || this.#metricsTimer) return;\n    this.#heartbeatTimer = setInterval(() => {\n      this.sendHeartbeat().catch(() => {});\n    }, this.#heartbeatIntervalMs);\n    this.#heartbeatTimer.unref?.();\n\n    this.#metricsTimer = setInterval(() => {\n      this.flushRequestMetrics().catch(() => {});\n    }, this.#metricsFlushIntervalMs);\n    this.#metricsTimer.unref?.();\n  }\n\n  stop(): void {\n    if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);\n    if (this.#metricsTimer) clearInterval(this.#metricsTimer);\n    this.#heartbeatTimer = null;\n    this.#metricsTimer = null;\n  }\n\n  recordRequest(\n    method: string,\n    routeTemplate: string,\n    statusCode: number,\n    latencyMs: number,\n  ): void {\n    if (!routeTemplate) return;\n    const key = `${method.toUpperCase()} ${routeTemplate}`;\n    const bucket = this.#buckets.get(key) ?? {\n      count: 0,\n      latencyMsTotal: 0,\n      http4xx: 0,\n      http5xx: 0,\n    };\n    bucket.count += 1;\n    bucket.latencyMsTotal += Math.max(0, latencyMs);\n    if (statusCode >= 400 && statusCode < 500) bucket.http4xx += 1;\n    if (statusCode >= 500 && statusCode < 600) bucket.http5xx += 1;\n    this.#buckets.set(key, bucket);\n  }\n\n  async sendStartup(): Promise<void> {\n    await this.#send([\n      this.#wrap({ event_name: \"APP_STARTUP\", app_startup_event: {} }),\n    ]);\n  }\n\n  async sendHeartbeat(): Promise<void> {\n    await this.#send([\n      this.#wrap({ event_name: \"HEARTBEAT\", heartbeat_event: {} }),\n    ]);\n  }\n\n  async flushRequestMetrics(): Promise<void> {\n    if (this.#buckets.size === 0) return;\n    const drained = this.#buckets;\n    this.#buckets = new Map();\n\n    const logs: AppkitLog[] = [];\n    for (const [endpoint, bucket] of drained) {\n      const event: RequestMetricsEvent = {\n        endpoint,\n        request_count: bucket.count,\n        request_latency_ms_avg: Math.round(\n          bucket.latencyMsTotal / bucket.count,\n        ),\n        response_count_http4xx: bucket.http4xx,\n        response_count_http5xx: bucket.http5xx,\n      };\n      logs.push(\n        this.#wrap({\n          event_name: \"REQUEST_METRICS\",\n          request_metrics_event: event,\n        }),\n      );\n    }\n    await this.#send(logs);\n  }\n\n  #wrap(partial: AppkitLog): AppkitLog {\n    return {\n      ...partial,\n      app_id: this.#appId,\n      appkit_version: this.#appkitVersion,\n    };\n  }\n\n  async #send(logs: AppkitLog[]): Promise<void> {\n    if (logs.length === 0) return;\n    const workspaceId = await this.#workspaceIdPromise;\n    await this.#client.apiClient.request({\n      path: \"/telemetry-ext\",\n      method: \"POST\",\n      query: { o: workspaceId },\n      headers: new Headers(),\n      payload: buildAppkitPayload(logs),\n      raw: false,\n    });\n  }\n}\n"],"mappings":"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"}