@databricks/appkit 0.45.0 → 0.46.0

package/dist/plugins/lakebase/lakebase.d.ts

@@ -93,9 +93,17 @@ declare class LakebasePlugin extends Plugin implements ToolProvider {
   private runReadOnlyStatement;
   /**
    * Gracefully drains and closes all connection pools (SP + OBO).
-   * Called automatically by AppKit during shutdown.
+   *
+   * Runs as the plugin's `shutdown()` hook (phase 3 of the core lifecycle
+   * manager's graceful shutdown), NOT in `abortActiveOperations()` (phase 2):
+   * other plugins' `shutdown()` hooks may still need database connections to
+   * drain state,
+   * so the pools must outlive the abort phase. `pg.Pool#end()` waits for
+   * checked-out clients to be released, so hooks running concurrently with
+   * this one can still finish their in-flight queries. Errors are caught
+   * and logged; this hook never throws.
    */
-  abortActiveOperations(): void;
+  shutdown(): Promise<void>;
   /**
    * Agent tool registry. Empty by default — the Lakebase plugin does NOT
    * expose its SQL connection to LLM agents unless the developer explicitly

package/dist/plugins/lakebase/lakebase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lakebase.d.ts","names":[],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA;;;;;;;;;;;;;;;;cAAa,cAAA,SAAuB,MAAA,YAAkB,YAAA;EAkP5B;EAAA,OAhPjB,QAAA,EAAuB,cAAA;EAAA,UAEZ,MAAA,EAAQ,eAAA;EAAA,QAClB,IAAA;EAAA,QACA,cAAA;;;;;;;;;EAUF,KAAA,CAAA,GAAK,OAAA;EAhBqD;;;;;;;;;;;;;;;;;;EAsE1D,KAAA,WAAgB,cAAA,OAAA,CACpB,IAAA,UACA,MAAA,eACC,OAAA,CAAQ,WAAA,CAAY,CAAA;EAmBT;;;;;;;;;;;;;;EAAA,QAAA,oBAAA;EAsHd;;;;EA/FA,qBAAA,CAAA;EAuGQ;;;;;EAAA,QA7EA,KAAA;cAEI,MAAA,EAAQ,eAAA;EAAA,QAYZ,cAAA;EA2CR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EAIH,OAAA,CAAQ,IAAA,GAJE,cAAA,GAIoD,MAAA,SAAA,YAAA;EAzIvC;;;;EAAA,QAiJf,gBAAA;;;;;;;;;;;;;EAqBR,OAAA,CAAA;UAGwB,YAAA;sBA5KF,cAAA,QAAc,IAAA,UACtB,MAAA,iBAEX,OAAA,CAAQ,WAAA,CAAY,CAAA;;;;;;;;;;iBA1Ff,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8QG,QAAA,EAAQ,QAAA,QAAA,cAAA,EAAA,eAAA"}
+{"version":3,"file":"lakebase.d.ts","names":[],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA;;;;;;;;;;;;;;;;cAAa,cAAA,SAAuB,MAAA,YAAkB,YAAA;EA6NU;EAAA,OA3NvD,QAAA,EAAuB,cAAA;EAAA,UAEZ,MAAA,EAAQ,eAAA;EAAA,QAClB,IAAA;EAAA,QACA,cAAA;EAmEL;;;;;;;;EAzDG,KAAA,CAAA,GAAK,OAAA;EAhBqD;;;;;;;;;;;;;;;;;;EAsE1D,KAAA,WAAgB,cAAA,OAAA,CACpB,IAAA,UACA,MAAA,eACC,OAAA,CAAQ,WAAA,CAAY,CAAA;EAAA;;;;;;;;;;;;;;EAAA,QAmBT,oBAAA;EA4HZ;;;;;;;;;;;;EA7FI,QAAA,CAAA,GAAY,OAAA;EArDI;;;;;EAAA,QAkFd,KAAA;cAEI,MAAA,EAAQ,eAAA;EAAA,QAYZ,cAAA;EA2CR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EAIH,OAAA,CAAQ,IAAA,GAJE,cAAA,GAIoD,MAAA,SAAA,YAAA;;;;;UAQtD,gBAAA;EAtPA;;;;;;;;;;;;EA2QR,OAAA,CAAA;UAGwB,YAAA;sBAvLF,cAAA,QAAc,IAAA,UACtB,MAAA,iBAEX,OAAA,CAAQ,WAAA,CAAY,CAAA;;;;;;;;;;iBA1Ff,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyRG,QAAA,EAAQ,QAAA,QAAA,cAAA,EAAA,eAAA"}

package/dist/plugins/lakebase/lakebase.js

@@ -141,22 +141,33 @@ var LakebasePlugin = class extends Plugin {
 	}
 	/**
 	* Gracefully drains and closes all connection pools (SP + OBO).
-	* Called automatically by AppKit during shutdown.
+	*
+	* Runs as the plugin's `shutdown()` hook (phase 3 of the core lifecycle
+	* manager's graceful shutdown), NOT in `abortActiveOperations()` (phase 2):
+	* other plugins' `shutdown()` hooks may still need database connections to
+	* drain state,
+	* so the pools must outlive the abort phase. `pg.Pool#end()` waits for
+	* checked-out clients to be released, so hooks running concurrently with
+	* this one can still finish their in-flight queries. Errors are caught
+	* and logged; this hook never throws.
 	*/
-	abortActiveOperations() {
-		super.abortActiveOperations();
+	async shutdown() {
 		if (this.pool) {
 			logger.info("Closing Lakebase SP pool");
-			this.pool.end().catch((err) => {
+			try {
+				await this.pool.end();
+			} catch (err) {
 				logger.error("Error closing Lakebase SP pool: %O", err);
-			});
+			}
 			this.pool = null;
 		}
 		if (this.oboPoolManager) {
 			logger.info("Closing all Lakebase OBO pools (%d)", this.oboPoolManager.size);
-			this.oboPoolManager.closeAll().catch((err) => {
+			try {
+				await this.oboPoolManager.closeAll();
+			} catch (err) {
 				logger.error("Error closing Lakebase OBO pools: %O", err);
-			});
+			}
 			this.oboPoolManager = null;
 		}
 	}

package/dist/plugins/lakebase/lakebase.js.map

@@ -1 +1 @@
-{"version":3,"file":"lakebase.js","names":["manifest"],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"sourcesContent":["import { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { QueryResult, QueryResultRow } from \"pg\";\nimport type { AgentToolDefinition, ToolProvider } from \"shared\";\nimport { z } from \"zod\";\nimport {\n  createLakebasePool,\n  createLakebasePoolManager,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n  type LakebasePool,\n  type LakebasePoolManager,\n  RoutingPool,\n} from \"../../connectors/lakebase\";\nimport { getClientOptions } from \"../../context/client-options\";\nimport { getUserContext } from \"../../context/execution-context\";\nimport { buildToolkitEntries } from \"../../core/agent/build-toolkit\";\nimport {\n  defineTool,\n  executeFromRegistry,\n  toolsFromRegistry,\n} from \"../../core/agent/tools/define-tool\";\nimport { assertReadOnlySql } from \"../../core/agent/tools/sql-policy\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport manifest from \"./manifest.json\";\nimport type { ILakebaseConfig } from \"./types\";\n\nconst logger = createLogger(\"lakebase\");\n\n/** Default pool settings for per-user OBO pools. */\nconst OBO_POOL_DEFAULTS = {\n  max: 3,\n  allowExitOnIdle: true,\n  idleTimeoutMillis: 30_000,\n};\n\n/**\n * AppKit plugin for Databricks Lakebase Autoscaling.\n *\n * Wraps `@databricks/lakebase` to provide a standard `pg.Pool` with automatic\n * OAuth token refresh, integrated with AppKit's logger and OpenTelemetry setup.\n *\n * Supports On-Behalf-Of (OBO) via `asUser(req)` — each user gets a separate\n * `pg.Pool` authenticated with their Databricks identity, enabling features\n * like Row-Level Security (RLS). Routing is handled transparently by\n * {@link RoutingPool}, which reads the execution context set by the base\n * class `asUser()`.\n *\n * @example\n * ```ts\n * import { createApp, lakebase, server } from \"@databricks/appkit\";\n *\n * const AppKit = await createApp({\n *   plugins: [server(), lakebase()],\n * });\n *\n * // Service principal query\n * const result = await AppKit.lakebase.query(\"SELECT * FROM users WHERE id = $1\", [userId]);\n *\n * // User-scoped query (per-user pool, RLS enforced)\n * const mine = await AppKit.lakebase.asUser(req).query(\"SELECT * FROM my_data\");\n * ```\n */\nexport class LakebasePlugin extends Plugin implements ToolProvider {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"lakebase\">;\n\n  protected declare config: ILakebaseConfig;\n  private pool: RoutingPool | null = null;\n  private oboPoolManager: LakebasePoolManager | null = null;\n\n  /**\n   * Initializes the Lakebase connection pool and OBO pool manager.\n   * Called automatically by AppKit during the plugin setup phase.\n   *\n   * Creates a {@link RoutingPool} that automatically routes queries to either\n   * the service-principal pool or a per-user pool based on the execution\n   * context (set by `Plugin.asUser(req)` via AsyncLocalStorage).\n   */\n  async setup() {\n    const poolConfig = {\n      ...this.config.pool,\n      workspaceClient:\n        this.config.pool?.workspaceClient ??\n        new WorkspaceClient({}, getClientOptions()),\n    };\n    const user = await getUsernameWithApiLookup(poolConfig);\n\n    const spPool = createLakebasePool({ ...poolConfig, user });\n    logger.info(\"Lakebase SP pool initialized\");\n\n    this.oboPoolManager = createLakebasePoolManager({\n      ...poolConfig,\n      ...OBO_POOL_DEFAULTS,\n    });\n    logger.info(\"Lakebase OBO pool manager initialized\");\n\n    const oboManager = this.oboPoolManager;\n    this.pool = new RoutingPool(spPool, (ctx) => {\n      if (!oboManager) throw new Error(\"OBO pool manager not initialized\");\n      // Lakebase OAuth roles use email as the postgres role when available\n      const userKey = ctx.userEmail ?? ctx.userId;\n      const isNew = !oboManager.hasPool(userKey);\n      const pool = oboManager.getPool(\n        userKey,\n        { workspaceClient: ctx.client, user: userKey },\n        ctx.tokenFingerprint,\n      );\n      if (isNew) {\n        logger.debug(\"Created OBO pool for user (total: %d)\", oboManager.size);\n      }\n      return pool;\n    });\n  }\n\n  /**\n   * Executes a parameterized SQL query against the Lakebase pool.\n   *\n   * When called inside `asUser(req)`, the query automatically routes to\n   * the per-user pool via {@link RoutingPool}.\n   *\n   * @param text - SQL query string, using `$1`, `$2`, ... placeholders\n   * @param values - Parameter values corresponding to placeholders\n   * @returns Query result with typed rows\n   *\n   * @example\n   * ```ts\n   * const result = await AppKit.lakebase.query<{ id: number; name: string }>(\n   *   \"SELECT id, name FROM users WHERE active = $1\",\n   *   [true],\n   * );\n   * ```\n   */\n  async query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n    return this.pool!.query<T>(text, values);\n  }\n\n  /**\n   * Execute a single statement inside a `BEGIN READ ONLY … ROLLBACK`\n   * transaction on a dedicated client.\n   *\n   * The three commands MUST share a connection — a naive\n   * `pool.query(\"BEGIN READ ONLY; <stmt>; ROLLBACK\")` batch cannot accept\n   * parameter values (PostgreSQL's Extended Query protocol rejects multi-\n   * statement prepared queries), which would silently break every\n   * parameterized query the agent tool issues.\n   *\n   * Returns the raw `rows` array for the user's statement. Side effects the\n   * statement may attempt (writes, writable-function side effects) are\n   * rejected by PostgreSQL under the read-only transaction posture.\n   */\n  private async runReadOnlyStatement(\n    text: string,\n    values?: unknown[],\n  ): Promise<unknown[]> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup()\n    const client = await this.pool!.connect();\n    try {\n      await client.query(\"BEGIN READ ONLY\");\n      const result = await client.query(text, values);\n      return result.rows;\n    } finally {\n      try {\n        await client.query(\"ROLLBACK\");\n      } finally {\n        client.release();\n      }\n    }\n  }\n\n  /**\n   * Gracefully drains and closes all connection pools (SP + OBO).\n   * Called automatically by AppKit during shutdown.\n   */\n  abortActiveOperations(): void {\n    super.abortActiveOperations();\n    if (this.pool) {\n      logger.info(\"Closing Lakebase SP pool\");\n      this.pool.end().catch((err) => {\n        logger.error(\"Error closing Lakebase SP pool: %O\", err);\n      });\n      this.pool = null;\n    }\n    if (this.oboPoolManager) {\n      logger.info(\n        \"Closing all Lakebase OBO pools (%d)\",\n        this.oboPoolManager.size,\n      );\n      this.oboPoolManager.closeAll().catch((err) => {\n        logger.error(\"Error closing Lakebase OBO pools: %O\", err);\n      });\n      this.oboPoolManager = null;\n    }\n  }\n\n  /**\n   * Agent tool registry. Empty by default — the Lakebase plugin does NOT\n   * expose its SQL connection to LLM agents unless the developer explicitly\n   * opts in via `config.exposeAsAgentTool`. See {@link buildQueryTool}.\n   */\n  private tools: Record<string, ReturnType<typeof this.buildQueryTool>> = {};\n\n  constructor(config: ILakebaseConfig) {\n    super(config);\n    this.config = config;\n    if (config.exposeAsAgentTool) {\n      this.tools = { query: this.buildQueryTool(config.exposeAsAgentTool) };\n      logger.warn(\n        \"Lakebase agent tool is enabled (readOnly=%s). Every agent with access to this plugin can execute SQL against the Lakebase database as the requesting user's identity.\",\n        config.exposeAsAgentTool.readOnly !== false,\n      );\n    }\n  }\n\n  private buildQueryTool(\n    opt: NonNullable<ILakebaseConfig[\"exposeAsAgentTool\"]>,\n  ) {\n    const readOnly = opt.readOnly !== false;\n    return defineTool({\n      description: readOnly\n        ? \"Execute a read-only SQL query against the Lakebase PostgreSQL database. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted. Use $1, $2, etc. as placeholders and pass values separately.\"\n        : \"Execute a parameterized SQL statement against the Lakebase PostgreSQL database. Use $1, $2, etc. as placeholders and pass values separately. This tool can modify data; every invocation requires explicit human approval.\",\n      schema: z.object({\n        text: z\n          .string()\n          .describe(\n            \"SQL statement with $1, $2, ... placeholders for parameters\",\n          ),\n        values: z\n          .array(z.unknown())\n          .optional()\n          .describe(\"Parameter values corresponding to placeholders\"),\n      }),\n      annotations: {\n        effect: readOnly ? \"read\" : \"destructive\",\n        idempotent: false,\n        requiresUserContext: true,\n      },\n      execute: async (args, signal) => {\n        // Matches the files plugin pattern: the pg connection API\n        // doesn't accept AbortSignal in its current shape, so deeper\n        // mid-call cancellation needs a separate plumbing pass on the\n        // connector. This entry check still catches the common case —\n        // a tool dispatched after the user already cancelled the\n        // stream — and unwinds cleanly instead of running to\n        // completion against the SQL warehouse.\n        signal?.throwIfAborted();\n        if (readOnly) {\n          assertReadOnlySql(args.text);\n          return this.runReadOnlyStatement(args.text, args.values);\n        }\n        const result = await this.query(args.text, args.values);\n        return result.rows;\n      },\n    });\n  }\n\n  getAgentTools(): AgentToolDefinition[] {\n    return toolsFromRegistry(this.tools);\n  }\n\n  async executeAgentTool(\n    name: string,\n    args: unknown,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    return executeFromRegistry(this.tools, name, args, signal);\n  }\n\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the pool config for the current execution context.\n   * Inside `asUser(req)`, returns user-scoped config; otherwise SP config.\n   */\n  private activePoolConfig() {\n    const ctx = getUserContext();\n    if (ctx) {\n      const user = ctx.userEmail ?? ctx.userId;\n      return { ...this.config.pool, workspaceClient: ctx.client, user };\n    }\n    return this.config.pool;\n  }\n\n  /**\n   * Returns the plugin's public API, accessible via `AppKit.lakebase`.\n   *\n   * - `pool` — The connection pool (routes to per-user pool when inside `asUser(req)`)\n   * - `query` — Convenience method for executing parameterized SQL queries\n   * - `getOrmConfig()` — Returns a config object compatible with Drizzle, TypeORM, Sequelize, etc.\n   *   Inside `asUser(req)`, returns user-scoped config.\n   * - `getPgConfig()` — Returns a `pg.PoolConfig` object for manual pool construction.\n   *   Inside `asUser(req)`, returns user-scoped config.\n   *\n   * Use `AppKit.lakebase.asUser(req)` to get the same API backed by a per-user pool.\n   */\n  exports() {\n    return {\n      // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n      pool: this.pool! as LakebasePool,\n      query: this.query.bind(this),\n      getOrmConfig: () => getLakebaseOrmConfig(this.activePoolConfig()),\n      getPgConfig: () => getLakebasePgConfig(this.activePoolConfig()),\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const lakebase = toPlugin(LakebasePlugin);\n"],"mappings":"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"}
+{"version":3,"file":"lakebase.js","names":["manifest"],"sources":["../../../src/plugins/lakebase/lakebase.ts"],"sourcesContent":["import { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { QueryResult, QueryResultRow } from \"pg\";\nimport type { AgentToolDefinition, ToolProvider } from \"shared\";\nimport { z } from \"zod\";\nimport {\n  createLakebasePool,\n  createLakebasePoolManager,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n  type LakebasePool,\n  type LakebasePoolManager,\n  RoutingPool,\n} from \"../../connectors/lakebase\";\nimport { getClientOptions } from \"../../context/client-options\";\nimport { getUserContext } from \"../../context/execution-context\";\nimport { buildToolkitEntries } from \"../../core/agent/build-toolkit\";\nimport {\n  defineTool,\n  executeFromRegistry,\n  toolsFromRegistry,\n} from \"../../core/agent/tools/define-tool\";\nimport { assertReadOnlySql } from \"../../core/agent/tools/sql-policy\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport manifest from \"./manifest.json\";\nimport type { ILakebaseConfig } from \"./types\";\n\nconst logger = createLogger(\"lakebase\");\n\n/** Default pool settings for per-user OBO pools. */\nconst OBO_POOL_DEFAULTS = {\n  max: 3,\n  allowExitOnIdle: true,\n  idleTimeoutMillis: 30_000,\n};\n\n/**\n * AppKit plugin for Databricks Lakebase Autoscaling.\n *\n * Wraps `@databricks/lakebase` to provide a standard `pg.Pool` with automatic\n * OAuth token refresh, integrated with AppKit's logger and OpenTelemetry setup.\n *\n * Supports On-Behalf-Of (OBO) via `asUser(req)` — each user gets a separate\n * `pg.Pool` authenticated with their Databricks identity, enabling features\n * like Row-Level Security (RLS). Routing is handled transparently by\n * {@link RoutingPool}, which reads the execution context set by the base\n * class `asUser()`.\n *\n * @example\n * ```ts\n * import { createApp, lakebase, server } from \"@databricks/appkit\";\n *\n * const AppKit = await createApp({\n *   plugins: [server(), lakebase()],\n * });\n *\n * // Service principal query\n * const result = await AppKit.lakebase.query(\"SELECT * FROM users WHERE id = $1\", [userId]);\n *\n * // User-scoped query (per-user pool, RLS enforced)\n * const mine = await AppKit.lakebase.asUser(req).query(\"SELECT * FROM my_data\");\n * ```\n */\nexport class LakebasePlugin extends Plugin implements ToolProvider {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"lakebase\">;\n\n  protected declare config: ILakebaseConfig;\n  private pool: RoutingPool | null = null;\n  private oboPoolManager: LakebasePoolManager | null = null;\n\n  /**\n   * Initializes the Lakebase connection pool and OBO pool manager.\n   * Called automatically by AppKit during the plugin setup phase.\n   *\n   * Creates a {@link RoutingPool} that automatically routes queries to either\n   * the service-principal pool or a per-user pool based on the execution\n   * context (set by `Plugin.asUser(req)` via AsyncLocalStorage).\n   */\n  async setup() {\n    const poolConfig = {\n      ...this.config.pool,\n      workspaceClient:\n        this.config.pool?.workspaceClient ??\n        new WorkspaceClient({}, getClientOptions()),\n    };\n    const user = await getUsernameWithApiLookup(poolConfig);\n\n    const spPool = createLakebasePool({ ...poolConfig, user });\n    logger.info(\"Lakebase SP pool initialized\");\n\n    this.oboPoolManager = createLakebasePoolManager({\n      ...poolConfig,\n      ...OBO_POOL_DEFAULTS,\n    });\n    logger.info(\"Lakebase OBO pool manager initialized\");\n\n    const oboManager = this.oboPoolManager;\n    this.pool = new RoutingPool(spPool, (ctx) => {\n      if (!oboManager) throw new Error(\"OBO pool manager not initialized\");\n      // Lakebase OAuth roles use email as the postgres role when available\n      const userKey = ctx.userEmail ?? ctx.userId;\n      const isNew = !oboManager.hasPool(userKey);\n      const pool = oboManager.getPool(\n        userKey,\n        { workspaceClient: ctx.client, user: userKey },\n        ctx.tokenFingerprint,\n      );\n      if (isNew) {\n        logger.debug(\"Created OBO pool for user (total: %d)\", oboManager.size);\n      }\n      return pool;\n    });\n  }\n\n  /**\n   * Executes a parameterized SQL query against the Lakebase pool.\n   *\n   * When called inside `asUser(req)`, the query automatically routes to\n   * the per-user pool via {@link RoutingPool}.\n   *\n   * @param text - SQL query string, using `$1`, `$2`, ... placeholders\n   * @param values - Parameter values corresponding to placeholders\n   * @returns Query result with typed rows\n   *\n   * @example\n   * ```ts\n   * const result = await AppKit.lakebase.query<{ id: number; name: string }>(\n   *   \"SELECT id, name FROM users WHERE active = $1\",\n   *   [true],\n   * );\n   * ```\n   */\n  async query<T extends QueryResultRow = any>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<T>> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n    return this.pool!.query<T>(text, values);\n  }\n\n  /**\n   * Execute a single statement inside a `BEGIN READ ONLY … ROLLBACK`\n   * transaction on a dedicated client.\n   *\n   * The three commands MUST share a connection — a naive\n   * `pool.query(\"BEGIN READ ONLY; <stmt>; ROLLBACK\")` batch cannot accept\n   * parameter values (PostgreSQL's Extended Query protocol rejects multi-\n   * statement prepared queries), which would silently break every\n   * parameterized query the agent tool issues.\n   *\n   * Returns the raw `rows` array for the user's statement. Side effects the\n   * statement may attempt (writes, writable-function side effects) are\n   * rejected by PostgreSQL under the read-only transaction posture.\n   */\n  private async runReadOnlyStatement(\n    text: string,\n    values?: unknown[],\n  ): Promise<unknown[]> {\n    // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup()\n    const client = await this.pool!.connect();\n    try {\n      await client.query(\"BEGIN READ ONLY\");\n      const result = await client.query(text, values);\n      return result.rows;\n    } finally {\n      try {\n        await client.query(\"ROLLBACK\");\n      } finally {\n        client.release();\n      }\n    }\n  }\n\n  /**\n   * Gracefully drains and closes all connection pools (SP + OBO).\n   *\n   * Runs as the plugin's `shutdown()` hook (phase 3 of the core lifecycle\n   * manager's graceful shutdown), NOT in `abortActiveOperations()` (phase 2):\n   * other plugins' `shutdown()` hooks may still need database connections to\n   * drain state,\n   * so the pools must outlive the abort phase. `pg.Pool#end()` waits for\n   * checked-out clients to be released, so hooks running concurrently with\n   * this one can still finish their in-flight queries. Errors are caught\n   * and logged; this hook never throws.\n   */\n  async shutdown(): Promise<void> {\n    if (this.pool) {\n      logger.info(\"Closing Lakebase SP pool\");\n      try {\n        await this.pool.end();\n      } catch (err) {\n        logger.error(\"Error closing Lakebase SP pool: %O\", err);\n      }\n      this.pool = null;\n    }\n    if (this.oboPoolManager) {\n      logger.info(\n        \"Closing all Lakebase OBO pools (%d)\",\n        this.oboPoolManager.size,\n      );\n      try {\n        await this.oboPoolManager.closeAll();\n      } catch (err) {\n        logger.error(\"Error closing Lakebase OBO pools: %O\", err);\n      }\n      this.oboPoolManager = null;\n    }\n  }\n\n  /**\n   * Agent tool registry. Empty by default — the Lakebase plugin does NOT\n   * expose its SQL connection to LLM agents unless the developer explicitly\n   * opts in via `config.exposeAsAgentTool`. See {@link buildQueryTool}.\n   */\n  private tools: Record<string, ReturnType<typeof this.buildQueryTool>> = {};\n\n  constructor(config: ILakebaseConfig) {\n    super(config);\n    this.config = config;\n    if (config.exposeAsAgentTool) {\n      this.tools = { query: this.buildQueryTool(config.exposeAsAgentTool) };\n      logger.warn(\n        \"Lakebase agent tool is enabled (readOnly=%s). Every agent with access to this plugin can execute SQL against the Lakebase database as the requesting user's identity.\",\n        config.exposeAsAgentTool.readOnly !== false,\n      );\n    }\n  }\n\n  private buildQueryTool(\n    opt: NonNullable<ILakebaseConfig[\"exposeAsAgentTool\"]>,\n  ) {\n    const readOnly = opt.readOnly !== false;\n    return defineTool({\n      description: readOnly\n        ? \"Execute a read-only SQL query against the Lakebase PostgreSQL database. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted. Use $1, $2, etc. as placeholders and pass values separately.\"\n        : \"Execute a parameterized SQL statement against the Lakebase PostgreSQL database. Use $1, $2, etc. as placeholders and pass values separately. This tool can modify data; every invocation requires explicit human approval.\",\n      schema: z.object({\n        text: z\n          .string()\n          .describe(\n            \"SQL statement with $1, $2, ... placeholders for parameters\",\n          ),\n        values: z\n          .array(z.unknown())\n          .optional()\n          .describe(\"Parameter values corresponding to placeholders\"),\n      }),\n      annotations: {\n        effect: readOnly ? \"read\" : \"destructive\",\n        idempotent: false,\n        requiresUserContext: true,\n      },\n      execute: async (args, signal) => {\n        // Matches the files plugin pattern: the pg connection API\n        // doesn't accept AbortSignal in its current shape, so deeper\n        // mid-call cancellation needs a separate plumbing pass on the\n        // connector. This entry check still catches the common case —\n        // a tool dispatched after the user already cancelled the\n        // stream — and unwinds cleanly instead of running to\n        // completion against the SQL warehouse.\n        signal?.throwIfAborted();\n        if (readOnly) {\n          assertReadOnlySql(args.text);\n          return this.runReadOnlyStatement(args.text, args.values);\n        }\n        const result = await this.query(args.text, args.values);\n        return result.rows;\n      },\n    });\n  }\n\n  getAgentTools(): AgentToolDefinition[] {\n    return toolsFromRegistry(this.tools);\n  }\n\n  async executeAgentTool(\n    name: string,\n    args: unknown,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    return executeFromRegistry(this.tools, name, args, signal);\n  }\n\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the pool config for the current execution context.\n   * Inside `asUser(req)`, returns user-scoped config; otherwise SP config.\n   */\n  private activePoolConfig() {\n    const ctx = getUserContext();\n    if (ctx) {\n      const user = ctx.userEmail ?? ctx.userId;\n      return { ...this.config.pool, workspaceClient: ctx.client, user };\n    }\n    return this.config.pool;\n  }\n\n  /**\n   * Returns the plugin's public API, accessible via `AppKit.lakebase`.\n   *\n   * - `pool` — The connection pool (routes to per-user pool when inside `asUser(req)`)\n   * - `query` — Convenience method for executing parameterized SQL queries\n   * - `getOrmConfig()` — Returns a config object compatible with Drizzle, TypeORM, Sequelize, etc.\n   *   Inside `asUser(req)`, returns user-scoped config.\n   * - `getPgConfig()` — Returns a `pg.PoolConfig` object for manual pool construction.\n   *   Inside `asUser(req)`, returns user-scoped config.\n   *\n   * Use `AppKit.lakebase.asUser(req)` to get the same API backed by a per-user pool.\n   */\n  exports() {\n    return {\n      // biome-ignore lint/style/noNonNullAssertion: pool is guaranteed non-null after setup(), which AppKit always awaits before exposing the plugin API\n      pool: this.pool! as LakebasePool,\n      query: this.query.bind(this),\n      getOrmConfig: () => getLakebaseOrmConfig(this.activePoolConfig()),\n      getPgConfig: () => getLakebasePgConfig(this.activePoolConfig()),\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const lakebase = toPlugin(LakebasePlugin);\n"],"mappings":";;;;;;;;;;;;;;;;;AA6BA,MAAM,SAAS,aAAa,WAAW;;AAGvC,MAAM,oBAAoB;CACxB,KAAK;CACL,iBAAiB;CACjB,mBAAmB;CACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BD,IAAa,iBAAb,cAAoC,OAA+B;;CAEjE,OAAO,WAAWA;CAGlB,AAAQ,OAA2B;CACnC,AAAQ,iBAA6C;;;;;;;;;CAUrD,MAAM,QAAQ;EACZ,MAAM,aAAa;GACjB,GAAG,KAAK,OAAO;GACf,iBACE,KAAK,OAAO,MAAM,mBAClB,IAAI,gBAAgB,EAAE,EAAE,kBAAkB,CAAC;GAC9C;EACD,MAAM,OAAO,MAAM,yBAAyB,WAAW;EAEvD,MAAM,SAAS,mBAAmB;GAAE,GAAG;GAAY;GAAM,CAAC;AAC1D,SAAO,KAAK,+BAA+B;AAE3C,OAAK,iBAAiB,0BAA0B;GAC9C,GAAG;GACH,GAAG;GACJ,CAAC;AACF,SAAO,KAAK,wCAAwC;EAEpD,MAAM,aAAa,KAAK;AACxB,OAAK,OAAO,IAAI,YAAY,SAAS,QAAQ;AAC3C,OAAI,CAAC,WAAY,OAAM,IAAI,MAAM,mCAAmC;GAEpE,MAAM,UAAU,IAAI,aAAa,IAAI;GACrC,MAAM,QAAQ,CAAC,WAAW,QAAQ,QAAQ;GAC1C,MAAM,OAAO,WAAW,QACtB,SACA;IAAE,iBAAiB,IAAI;IAAQ,MAAM;IAAS,EAC9C,IAAI,iBACL;AACD,OAAI,MACF,QAAO,MAAM,yCAAyC,WAAW,KAAK;AAExE,UAAO;IACP;;;;;;;;;;;;;;;;;;;;CAqBJ,MAAM,MACJ,MACA,QACyB;AAEzB,SAAO,KAAK,KAAM,MAAS,MAAM,OAAO;;;;;;;;;;;;;;;;CAiB1C,MAAc,qBACZ,MACA,QACoB;EAEpB,MAAM,SAAS,MAAM,KAAK,KAAM,SAAS;AACzC,MAAI;AACF,SAAM,OAAO,MAAM,kBAAkB;AAErC,WADe,MAAM,OAAO,MAAM,MAAM,OAAO,EACjC;YACN;AACR,OAAI;AACF,UAAM,OAAO,MAAM,WAAW;aACtB;AACR,WAAO,SAAS;;;;;;;;;;;;;;;;CAiBtB,MAAM,WAA0B;AAC9B,MAAI,KAAK,MAAM;AACb,UAAO,KAAK,2BAA2B;AACvC,OAAI;AACF,UAAM,KAAK,KAAK,KAAK;YACd,KAAK;AACZ,WAAO,MAAM,sCAAsC,IAAI;;AAEzD,QAAK,OAAO;;AAEd,MAAI,KAAK,gBAAgB;AACvB,UAAO,KACL,uCACA,KAAK,eAAe,KACrB;AACD,OAAI;AACF,UAAM,KAAK,eAAe,UAAU;YAC7B,KAAK;AACZ,WAAO,MAAM,wCAAwC,IAAI;;AAE3D,QAAK,iBAAiB;;;;;;;;CAS1B,AAAQ,QAAgE,EAAE;CAE1E,YAAY,QAAyB;AACnC,QAAM,OAAO;AACb,OAAK,SAAS;AACd,MAAI,OAAO,mBAAmB;AAC5B,QAAK,QAAQ,EAAE,OAAO,KAAK,eAAe,OAAO,kBAAkB,EAAE;AACrE,UAAO,KACL,yKACA,OAAO,kBAAkB,aAAa,MACvC;;;CAIL,AAAQ,eACN,KACA;EACA,MAAM,WAAW,IAAI,aAAa;AAClC,SAAO,WAAW;GAChB,aAAa,WACT,iNACA;GACJ,QAAQ,EAAE,OAAO;IACf,MAAM,EACH,QAAQ,CACR,SACC,6DACD;IACH,QAAQ,EACL,MAAM,EAAE,SAAS,CAAC,CAClB,UAAU,CACV,SAAS,iDAAiD;IAC9D,CAAC;GACF,aAAa;IACX,QAAQ,WAAW,SAAS;IAC5B,YAAY;IACZ,qBAAqB;IACtB;GACD,SAAS,OAAO,MAAM,WAAW;AAQ/B,YAAQ,gBAAgB;AACxB,QAAI,UAAU;AACZ,uBAAkB,KAAK,KAAK;AAC5B,YAAO,KAAK,qBAAqB,KAAK,MAAM,KAAK,OAAO;;AAG1D,YADe,MAAM,KAAK,MAAM,KAAK,MAAM,KAAK,OAAO,EACzC;;GAEjB,CAAC;;CAGJ,gBAAuC;AACrC,SAAO,kBAAkB,KAAK,MAAM;;CAGtC,MAAM,iBACJ,MACA,MACA,QACkB;AAClB,SAAO,oBAAoB,KAAK,OAAO,MAAM,MAAM,OAAO;;CAG5D,QAAQ,MAAwD;AAC9D,SAAO,oBAAoB,KAAK,MAAM,KAAK,OAAO,KAAK;;;;;;CAOzD,AAAQ,mBAAmB;EACzB,MAAM,MAAM,gBAAgB;AAC5B,MAAI,KAAK;GACP,MAAM,OAAO,IAAI,aAAa,IAAI;AAClC,UAAO;IAAE,GAAG,KAAK,OAAO;IAAM,iBAAiB,IAAI;IAAQ;IAAM;;AAEnE,SAAO,KAAK,OAAO;;;;;;;;;;;;;;CAerB,UAAU;AACR,SAAO;GAEL,MAAM,KAAK;GACX,OAAO,KAAK,MAAM,KAAK,KAAK;GAC5B,oBAAoB,qBAAqB,KAAK,kBAAkB,CAAC;GACjE,mBAAmB,oBAAoB,KAAK,kBAAkB,CAAC;GAChE;;;;;;AAOL,MAAa,WAAW,SAAS,eAAe"}

package/dist/plugins/server/index.d.ts

@@ -36,6 +36,13 @@ declare class ServerPlugin extends Plugin {
     host: string;
     port: number;
   };
+  /**
+   * Budget for awaiting `server.close()` during shutdown. Bounded because
+   * `closeAllConnections()` runs immediately before the await, so the close
+   * is expected to resolve promptly; the core lifecycle manager's overall
+   * force-exit timer is the ultimate backstop if it does not.
+   */
+  private static readonly SERVER_CLOSE_TIMEOUT_MS;
   /** Plugin manifest declaring metadata and resource requirements */
   static manifest: PluginManifest<"server">;
   private serverApplication;
@@ -47,6 +54,12 @@ declare class ServerPlugin extends Plugin {
   protected config: ServerConfig;
   private serverExtensions;
   private rawBodyPaths;
+  /**
+   * Resolves when `server.close()` completes. Created in
+   * {@link abortActiveOperations} (which initiates the close) and awaited in
+   * {@link closeRemainingConnections} after other plugins have drained.
+   */
+  private serverClosed?;
   static phase: PluginPhase;
   constructor(config: ServerConfig);
   attachContext(deps?: Parameters<Plugin["attachContext"]>[0]): void;
@@ -86,6 +99,11 @@ declare class ServerPlugin extends Plugin {
    * Call this inside the `onPluginsReady` callback of `createApp` to register
    * custom Express routes or middleware before the server starts listening.
    *
+   * Note: async handlers registered directly on the app must handle their own
+   * rejections — Express 4 does not forward rejected promises to the error
+   * middleware. Errors passed explicitly to `next(err)` are formatted by the
+   * terminal error middleware.
+   *
    * @param fn - A function that receives the express application.
    * @returns The server plugin instance for chaining.
    */
@@ -120,7 +138,39 @@ declare class ServerPlugin extends Plugin {
    */
   private resolveListenPort;
   private logStartupInfo;
-  private _gracefulShutdown;
+  /**
+   * Cancel in-flight work and begin closing the HTTP server.
+   *
+   * Runs in the first phase of the core LifecycleManager's graceful shutdown,
+   * before any plugin `shutdown()` hook. In addition to the base behavior
+   * (aborting SSE streams), it stops the server accepting new connections and
+   * drops idle keep-alive sockets — without `closeIdleConnections()`, a
+   * connected browser would pin `server.close()` open until the force-exit
+   * timer fires. The close is only *initiated* here; the returned promise is
+   * awaited later in {@link closeRemainingConnections} so peer plugins can
+   * still drain in-flight requests through the server first.
+   */
+  abortActiveOperations(): void;
+  /**
+   * Drain the dev-only servers as this plugin's `shutdown()` hook.
+   *
+   * Runs concurrently with the other plugins' hooks during graceful shutdown.
+   * These are no-ops in production (neither is created), so this hook is
+   * effectively dev-only.
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Force-close whatever sockets remain and await the server close.
+   *
+   * Registered on the `"shutdown"` lifecycle event in {@link start}, so it
+   * fires after every plugin's `shutdown()` hook has run — meaning any
+   * in-flight request a peer plugin was draining has already completed.
+   * `closeAllConnections()` destroys the leftover sockets (aborted SSE
+   * responses, keep-alive connections) synchronously so the pending
+   * `server.close()` can complete; the await is bounded because the close is
+   * expected to resolve promptly once the sockets are gone.
+   */
+  private closeRemainingConnections;
   /**
    * Returns the public exports for the server plugin.
    * Exposes server management methods.

package/dist/plugins/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AAkDA;;;;;;;;;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;EADkB;EAAA,OAOzB,QAAA,EAAuB,cAAA;EAAA,QACtB,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAHA;EAAA,QAKA,kBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,QACA,YAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAepB,aAAA,CAAc,IAAA,GAAM,UAAA,CAAW,MAAA;EAlBvB;EA4BF,KAAA,CAAA,GAAK,OAAA;EA3BG;EA8Bd,SAAA,CAAA;IAAA;;;;;;gBAHW,gBAAA;EAAA;EAGX;;;;;;;;EAcM,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;EAAzB;;;;;;;;EAqEN,SAAA,CAAA,GAAa,MAAA;EAiBD;;;;;;;;;EAAZ,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;EAuJX;;;;;;EA5Id,YAAA,CAAa,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;EAwPf;;;;;;;EAAA,QA7OF,YAAA;;;;;;;UAmEA,aAAA;EAAA,eA4CC,cAAA;EAoLJ;;;;;EAAA,QAlKG,iBAAA;EAAA,QAqBN,cAAA;EAAA,QA+BM,iBAAA;EA8GG;;;;EA1DjB,OAAA,CAAA;yEAIgB,GAAA,EAAK,OAAA,CAAQ,WAAA;qBApRhB,MAAA;;;;;;;;kBAAU,gBAAA;IAAA;;;;;;;cA0UZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"mappings":";;;;;;;;;;;;;;;;AAkDA;;;;;;;;;;;;;;;;;cAAa,YAAA,SAAqB,MAAA;EAAA,OAClB,cAAA;;;;EADwB;;;;;;EAAA,wBAYd,uBAAA;EAGM;EAAA,OAAvB,QAAA,EAAuB,cAAA;EAAA,QACtB,iBAAA;EAAA,QACA,MAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAGU;EAAA,QADV,kBAAA;EAAA,UACU,MAAA,EAAQ,YAAA;EAAA,QAClB,gBAAA;EAAA,QACA,YAAA;EAOD;;;;;EAAA,QADC,YAAA;EAAA,OACD,KAAA,EAAO,WAAA;cAEF,MAAA,EAAQ,YAAA;EAepB,aAAA,CAAc,IAAA,GAAM,UAAA,CAAW,MAAA;EAUzB;EAAA,KAAA,CAAA,GAAK,OAAA;EAGX;EAAA,SAAA,CAAA;IAAA;;;;;;gBAHW,gBAAA;EAAA;EAiBI;;;;;;;;EAAT,KAAA,CAAA,GAAS,OAAA,CAAQ,OAAA,CAAQ,WAAA;EAwGxB;;;;;;;;EAtBP,SAAA,CAAA,GAAa,MAAA;EA6KC;;;;;;;;;;;;;;EAvJd,MAAA,CAAO,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;;;;;;;EAWzB,YAAA,CAAa,EAAA,GAAK,GAAA,EAAK,OAAA,CAAQ,WAAA;;;;;AA8YjC;;;UAnYgB,YAAA;EAmYG;;;;;;EAAA,QAhUH,aAAA;EAAA,eA4CC,cAAA;EAoRE;;;;;EAAA,QAlQH,iBAAA;EAAA,QAqBN,cAAA;;;;;;;;;;;;;EA2CR,qBAAA,CAAA;;;;;;;;EAmBM,QAAA,CAAA,GAAY,OAAA;;;;;;;;;;;;UAoBJ,yBAAA;;;;;EAoBd,OAAA,CAAA;yEAIgB,GAAA,EAAK,OAAA,CAAQ,WAAA;qBA5ShB,MAAA;;;;;;;;kBAAU,gBAAA;IAAA;;;;;;;cA+aZ,MAAA,EAAM,QAAA,QAAA,YAAA,EAAA,YAAA"}

package/dist/plugins/server/index.js

@@ -1,4 +1,5 @@
 import { createLogger } from "../../logging/logger.js";
+import { AppKitError } from "../../errors/base.js";
 import { ServerError } from "../../errors/server.js";
 import "../../errors/index.js";
 import { instrumentations } from "../../telemetry/instrumentations.js";
@@ -52,6 +53,13 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		host: process.env.FLASK_RUN_HOST || "0.0.0.0",
 		port: Number(process.env.DATABRICKS_APP_PORT) || 8e3
 	};
+	/**
+	* Budget for awaiting `server.close()` during shutdown. Bounded because
+	* `closeAllConnections()` runs immediately before the await, so the close
+	* is expected to resolve promptly; the core lifecycle manager's overall
+	* force-exit timer is the ultimate backstop if it does not.
+	*/
+	static SERVER_CLOSE_TIMEOUT_MS = 2e3;
 	/** Plugin manifest declaring metadata and resource requirements */
 	static manifest = manifest_default;
 	serverApplication;
@@ -62,6 +70,12 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	resolvedListenPort;
 	serverExtensions = [];
 	rawBodyPaths = /* @__PURE__ */ new Set();
+	/**
+	* Resolves when `server.close()` completes. Created in
+	* {@link abortActiveOperations} (which initiates the close) and awaited in
+	* {@link closeRemainingConnections} after other plugins have drained.
+	*/
+	serverClosed;
 	static phase = "deferred";
 	constructor(config) {
 		super(config);
@@ -106,12 +120,12 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		this.remoteTunnelController = new RemoteTunnelController(this.devFileReader);
 		this.serverApplication.use(this.remoteTunnelController.middleware);
 		await this.setupFrontend(endpoints, pluginConfigs);
+		this.serverApplication.use(errorHandlerMiddleware);
 		const listenPort = await this.resolveListenPort();
 		const server = this.serverApplication.listen(listenPort, this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host, () => this.logStartupInfo());
 		this.server = server;
 		this.remoteTunnelController.setServer(server);
-		process.on("SIGTERM", () => this._gracefulShutdown());
-		process.on("SIGINT", () => this._gracefulShutdown());
+		this.context?.onLifecycle("shutdown", () => this.closeRemainingConnections());
 		if (process.env.NODE_ENV === "development") printRoutes(getRoutes(this.serverApplication._router.stack));
 		return this.serverApplication;
 	}
@@ -133,6 +147,11 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 	* Call this inside the `onPluginsReady` callback of `createApp` to register
 	* custom Express routes or middleware before the server starts listening.
 	*
+	* Note: async handlers registered directly on the app must handle their own
+	* rejections — Express 4 does not forward rejected promises to the error
+	* middleware. Errors passed explicitly to `next(err)` are formatted by the
+	* terminal error middleware.
+	*
 	* @param fn - A function that receives the express application.
 	* @returns The server plugin instance for chaining.
 	*/
@@ -262,29 +281,57 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		if (!remoteServerController) logger.debug("Remote tunnel: disabled (controller not initialized)");
 		else logger.debug("Remote tunnel: %s; %s", remoteServerController.isAllowedByEnv() ? "allowed" : "blocked", remoteServerController.isActive() ? "active" : "inactive");
 	}
-	async _gracefulShutdown() {
-		logger.info("Starting graceful shutdown...");
-		if (this.viteDevServer) await this.viteDevServer.close();
-		if (this.remoteTunnelController) this.remoteTunnelController.cleanup();
-		TelemetryReporter.getInstance()?.stop();
-		const shutdownPlugins = this.context?.getPlugins();
-		if (shutdownPlugins) {
-			for (const plugin of shutdownPlugins.values()) if (plugin.abortActiveOperations) try {
-				plugin.abortActiveOperations();
-			} catch (err) {
-				logger.error("Error aborting operations for plugin %s: %O", plugin.name, err);
-			}
-		}
+	/**
+	* Cancel in-flight work and begin closing the HTTP server.
+	*
+	* Runs in the first phase of the core LifecycleManager's graceful shutdown,
+	* before any plugin `shutdown()` hook. In addition to the base behavior
+	* (aborting SSE streams), it stops the server accepting new connections and
+	* drops idle keep-alive sockets — without `closeIdleConnections()`, a
+	* connected browser would pin `server.close()` open until the force-exit
+	* timer fires. The close is only *initiated* here; the returned promise is
+	* awaited later in {@link closeRemainingConnections} so peer plugins can
+	* still drain in-flight requests through the server first.
+	*/
+	abortActiveOperations() {
+		super.abortActiveOperations();
 		if (this.server) {
-			this.server.close(() => {
-				logger.debug("Server closed gracefully");
-				process.exit(0);
+			const server = this.server;
+			this.serverClosed = new Promise((resolve) => {
+				server.close(() => resolve());
 			});
-			setTimeout(() => {
-				logger.debug("Force shutdown after timeout");
-				process.exit(1);
-			}, 15e3);
-		} else process.exit(0);
+			server.closeIdleConnections();
+		}
+	}
+	/**
+	* Drain the dev-only servers as this plugin's `shutdown()` hook.
+	*
+	* Runs concurrently with the other plugins' hooks during graceful shutdown.
+	* These are no-ops in production (neither is created), so this hook is
+	* effectively dev-only.
+	*/
+	async shutdown() {
+		if (this.viteDevServer) await this.viteDevServer.close();
+		if (this.remoteTunnelController) this.remoteTunnelController.cleanup();
+	}
+	/**
+	* Force-close whatever sockets remain and await the server close.
+	*
+	* Registered on the `"shutdown"` lifecycle event in {@link start}, so it
+	* fires after every plugin's `shutdown()` hook has run — meaning any
+	* in-flight request a peer plugin was draining has already completed.
+	* `closeAllConnections()` destroys the leftover sockets (aborted SSE
+	* responses, keep-alive connections) synchronously so the pending
+	* `server.close()` can complete; the await is bounded because the close is
+	* expected to resolve promptly once the sockets are gone.
+	*/
+	async closeRemainingConnections() {
+		if (this.server) this.server.closeAllConnections();
+		if (!this.serverClosed) return;
+		await Promise.race([this.serverClosed, new Promise((resolve) => {
+			setTimeout(resolve, ServerPlugin.SERVER_CLOSE_TIMEOUT_MS).unref();
+		})]);
+		logger.debug("Server closed gracefully");
 	}
 	/**
 	* Returns the public exports for the server plugin.
@@ -320,6 +367,46 @@ function requestMetricsMiddleware(req, res, next) {
 	next();
 }
 /**
+* Narrow an unknown thrown value to an Error that carries a numeric
+* `statusCode` property in the HTTP error range (e.g. `ApiError` from
+* `@databricks/sdk-experimental`).
+*/
+function hasHttpStatusCode(error) {
+	if (!(error instanceof Error) || !("statusCode" in error)) return false;
+	const statusCode = error.statusCode;
+	return typeof statusCode === "number" && Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599;
+}
+/**
+* Terminal Express error-handling middleware.
+*
+* Converts errors forwarded via `next(err)` (including async handler
+* rejections forwarded by `Plugin.route()`) into JSON error responses,
+* following the same status/message conventions as `Plugin.execute()`:
+* - errors carrying an HTTP `statusCode` (including `AppKitError`) → that
+*   status; 5xx messages are masked in production to avoid leaking internals
+* - anything else → 500 with a generic message in production
+*
+* 4xx errors are expected client errors (e.g. missing auth headers) and are
+* logged at `warn` with just the message; 5xx/unknown errors are logged at
+* `error` with the full error.
+*
+* @internal Exported for unit tests.
+*/
+function errorHandlerMiddleware(err, req, res, next) {
+	const httpError = err instanceof AppKitError || hasHttpStatusCode(err) ? err : null;
+	const statusCode = httpError ? httpError.statusCode : 500;
+	const isClientError = statusCode < 500;
+	if (isClientError) logger.warn("Request failed for %s %s with status %d: %s", req.method, req.originalUrl, statusCode, err instanceof Error ? err.message : String(err));
+	else logger.error("Unhandled error for %s %s: %O", req.method, req.originalUrl, err instanceof AppKitError ? err.toJSON() : err);
+	if (res.headersSent) {
+		next(err);
+		return;
+	}
+	const isDev = process.env.NODE_ENV !== "production";
+	const message = err instanceof Error ? err.message : "Server error";
+	res.status(statusCode).json({ error: isDev || isClientError ? message : "Server error" });
+}
+/**
 * @internal
 */
 const server = toPlugin(ServerPlugin);

package/dist/plugins/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport getPort, { portNumbers } from \"get-port\";\nimport type { PluginClientConfigs, PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { TelemetryReporter } from \"../../internal-telemetry\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport { sanitizeClientConfig } from \"./client-config-sanitizer\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/** Dev-only: try `requested` then consecutive ports (see `get-port` `portNumbers`). */\nconst devListenPortSpan = 100;\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * The server is started automatically by `createApp` after all plugins are set up\n * and the optional `onPluginsReady` callback has run.\n *\n * @example\n * ```ts\n * 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 *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"server\">;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  /** Bound listen port after optional dev-time resolution. */\n  private resolvedListenPort?: number;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  private rawBodyPaths: Set<string> = new Set();\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    if (\"autoStart\" in config) {\n      throw new ServerError(\n        \"server({ autoStart }) has been removed. \" +\n          \"The server is now started automatically by createApp.\\n\\n\" +\n          \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n      );\n    }\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n  }\n\n  attachContext(deps: Parameters<Plugin[\"attachContext\"]>[0] = {}): void {\n    super.attachContext(deps);\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n    this.context?.registerAsRouteTarget(this);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {}\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(requestMetricsMiddleware);\n    this.serverApplication.use(\n      express.json({\n        // Express's stock 100kb default is too tight for modern apps —\n        // agent chat payloads and any base64-encoded upload (e.g. the\n        // dev playground's smart-dashboard \"save view\" screenshot at\n        // ~105KB) blow past it instantly. Raise to 1mb by default and\n        // let consumers tune via `server({ bodyLimit })` if they need\n        // more headroom.\n        limit: this.config.bodyLimit ?? \"1mb\",\n        type: (req) => {\n          // Skip JSON parsing for routes that declared skipBodyParsing\n          // (e.g. file uploads where the raw body must flow through).\n          // rawBodyPaths is populated by extendRoutes() below; the type\n          // callback runs per-request so the set is already filled.\n          const urlPath = req.url?.split(\"?\")[0];\n          if (urlPath && this.rawBodyPaths.has(urlPath)) return false;\n          const ct = req.headers[\"content-type\"] ?? \"\";\n          return ct.includes(\"json\");\n        },\n      }),\n    );\n\n    const { endpoints, pluginConfigs } = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints, pluginConfigs);\n\n    const listenPort = await this.resolveListenPort();\n\n    const server = this.serverApplication.listen(\n      listenPort,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server has not started yet.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * Call this inside the `onPluginsReady` callback of `createApp` to register\n   * custom Express routes or middleware before the server starts listening.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   */\n  extend(fn: (app: express.Application) => void) {\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Register a server extension from another plugin during setup.\n   * Unlike extend(), this is designed for internal plugin-to-plugin\n   * coordination where extensions are registered before the server starts\n   * listening — typically called by PluginContext when flushing buffered routes.\n   */\n  addExtension(fn: (app: express.Application) => void) {\n    this.serverExtensions.push(fn);\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints,\n   * and a map of plugin names to their client-exposed configs.\n   */\n  private async extendRoutes(): Promise<{\n    endpoints: PluginEndpoints;\n    pluginConfigs: PluginClientConfigs;\n  }> {\n    const endpoints: PluginEndpoints = {};\n    const pluginConfigs: PluginClientConfigs = {};\n\n    const plugins = this.context?.getPlugins();\n    if (!plugins || plugins.size === 0) return { endpoints, pluginConfigs };\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of plugins.values()) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        endpoints[plugin.name] = plugin.getEndpoints();\n\n        // Collect paths that should skip body parsing\n        if (\n          plugin.getSkipBodyParsingPaths &&\n          typeof plugin.getSkipBodyParsingPaths === \"function\"\n        ) {\n          for (const p of plugin.getSkipBodyParsingPaths()) {\n            this.rawBodyPaths.add(p);\n          }\n        }\n      }\n\n      if (typeof plugin.clientConfig === \"function\") {\n        try {\n          const raw = plugin.clientConfig();\n          if (raw != null) {\n            const sanitized = sanitizeClientConfig(plugin.name, raw);\n            if (Object.keys(sanitized).length > 0) {\n              pluginConfigs[plugin.name] = sanitized;\n            }\n          }\n        } catch (error) {\n          logger.error(\n            \"Plugin '%s' clientConfig() failed, skipping its config: %O\",\n            plugin.name,\n            error,\n          );\n        }\n      }\n    }\n\n    return { endpoints, pluginConfigs };\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(\n    endpoints: PluginEndpoints,\n    pluginConfigs: PluginClientConfigs,\n  ) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n        pluginConfigs,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(\n        this.serverApplication,\n        endpoints,\n        pluginConfigs,\n      );\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n        pluginConfigs,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * In development, prefers {@link ServerConfig.port} / env / default (8000), then\n   * scans upward using `get-port`'s `portNumbers()` on the listen host until one binds.\n   * In non-development, uses config / env / default only (no fallback).\n   */\n  private async resolveListenPort(): Promise<number> {\n    const requested = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n\n    if (process.env.NODE_ENV !== \"development\") {\n      this.resolvedListenPort = requested;\n      return requested;\n    }\n\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n    const upper = Math.min(requested + devListenPortSpan - 1, 65_535);\n    const port = await getPort({\n      host,\n      port: portNumbers(requested, upper),\n    });\n    this.resolvedListenPort = port;\n    if (port !== requested) {\n      logger.info(\"Port %d was busy, picking %d\", requested, port);\n    }\n    return port;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port =\n      this.resolvedListenPort ??\n      this.config.port ??\n      ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    TelemetryReporter.getInstance()?.stop();\n\n    // 1. abort active operations from plugins\n    const shutdownPlugins = this.context?.getPlugins();\n    if (shutdownPlugins) {\n      for (const plugin of shutdownPlugins.values()) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n      /** @deprecated Server is now started automatically by createApp. */\n      start() {\n        throw new ServerError(\n          \"server.start() has been removed. Use the onPluginsReady callback instead:\\n\\n\" +\n            \"  createApp({\\n\" +\n            \"    plugins: [server(), ...],\\n\" +\n            \"    onPluginsReady(appkit) {\\n\" +\n            \"      appkit.server.extend(...);\\n\" +\n            \"    },\\n\" +\n            \"  });\\n\\n\" +\n            \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n        );\n      },\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS: string[] = [ServerPlugin.manifest.name];\n\n/** @internal Exported for unit tests. */\nexport function requestMetricsMiddleware(\n  req: express.Request,\n  res: express.Response,\n  next: express.NextFunction,\n) {\n  const startMs = Date.now();\n  res.on(\"finish\", () => {\n    const reporter = TelemetryReporter.getInstance();\n    if (!reporter) return;\n    const routePath = (req.route as { path?: string } | undefined)?.path;\n    if (!routePath) return;\n    const baseUrl = req.baseUrl ?? \"\";\n    const template = `${baseUrl}${routePath}`;\n    reporter.recordRequest(\n      req.method,\n      template,\n      res.statusCode,\n      Date.now() - startMs,\n    );\n  });\n  next();\n}\n\n/**\n * @internal\n */\nexport const server = toPlugin(ServerPlugin);\n// Export manifest and types\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["manifest"],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport getPort, { portNumbers } from \"get-port\";\nimport type { PluginClientConfigs, PluginPhase } from \"shared\";\nimport { AppKitError, ServerError } from \"../../errors\";\nimport { TelemetryReporter } from \"../../internal-telemetry\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { instrumentations } from \"../../telemetry\";\nimport { sanitizeClientConfig } from \"./client-config-sanitizer\";\nimport manifest from \"./manifest.json\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints, printRoutes } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/** Dev-only: try `requested` then consecutive ports (see `get-port` `portNumbers`). */\nconst devListenPortSpan = 100;\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * The server is started automatically by `createApp` after all plugins are set up\n * and the optional `onPluginsReady` callback has run.\n *\n * @example\n * ```ts\n * 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 *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /**\n   * Budget for awaiting `server.close()` during shutdown. Bounded because\n   * `closeAllConnections()` runs immediately before the await, so the close\n   * is expected to resolve promptly; the core lifecycle manager's overall\n   * force-exit timer is the ultimate backstop if it does not.\n   */\n  private static readonly SERVER_CLOSE_TIMEOUT_MS = 2_000;\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"server\">;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  /** Bound listen port after optional dev-time resolution. */\n  private resolvedListenPort?: number;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  private rawBodyPaths: Set<string> = new Set();\n  /**\n   * Resolves when `server.close()` completes. Created in\n   * {@link abortActiveOperations} (which initiates the close) and awaited in\n   * {@link closeRemainingConnections} after other plugins have drained.\n   */\n  private serverClosed?: Promise<void>;\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    if (\"autoStart\" in config) {\n      throw new ServerError(\n        \"server({ autoStart }) has been removed. \" +\n          \"The server is now started automatically by createApp.\\n\\n\" +\n          \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n      );\n    }\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n  }\n\n  attachContext(deps: Parameters<Plugin[\"attachContext\"]>[0] = {}): void {\n    super.attachContext(deps);\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n    this.context?.registerAsRouteTarget(this);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {}\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(requestMetricsMiddleware);\n    this.serverApplication.use(\n      express.json({\n        // Express's stock 100kb default is too tight for modern apps —\n        // agent chat payloads and any base64-encoded upload (e.g. the\n        // dev playground's smart-dashboard \"save view\" screenshot at\n        // ~105KB) blow past it instantly. Raise to 1mb by default and\n        // let consumers tune via `server({ bodyLimit })` if they need\n        // more headroom.\n        limit: this.config.bodyLimit ?? \"1mb\",\n        type: (req) => {\n          // Skip JSON parsing for routes that declared skipBodyParsing\n          // (e.g. file uploads where the raw body must flow through).\n          // rawBodyPaths is populated by extendRoutes() below; the type\n          // callback runs per-request so the set is already filled.\n          const urlPath = req.url?.split(\"?\")[0];\n          if (urlPath && this.rawBodyPaths.has(urlPath)) return false;\n          const ct = req.headers[\"content-type\"] ?? \"\";\n          return ct.includes(\"json\");\n        },\n      }),\n    );\n\n    const { endpoints, pluginConfigs } = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints, pluginConfigs);\n\n    // Terminal error handler — registered after all routes, extensions, and\n    // frontend middleware so that errors forwarded via next(err) from any of\n    // them (e.g. async handler rejections forwarded by Plugin.route()) are\n    // turned into JSON error responses instead of hanging the request.\n    this.serverApplication.use(errorHandlerMiddleware);\n\n    const listenPort = await this.resolveListenPort();\n\n    const server = this.serverApplication.listen(\n      listenPort,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    // Graceful shutdown is orchestrated by the core LifecycleManager, which\n    // owns the process signal handlers. This plugin only contributes its\n    // HTTP concerns: it aborts/initiates the socket close in\n    // abortActiveOperations(), drains dev servers in shutdown(), and force-\n    // closes remaining sockets in the \"shutdown\" lifecycle hook below (which\n    // fires after every plugin's shutdown() has run).\n    this.context?.onLifecycle(\"shutdown\", () =>\n      this.closeRemainingConnections(),\n    );\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      printRoutes(allRoutes);\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server has not started yet.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * Call this inside the `onPluginsReady` callback of `createApp` to register\n   * custom Express routes or middleware before the server starts listening.\n   *\n   * Note: async handlers registered directly on the app must handle their own\n   * rejections — Express 4 does not forward rejected promises to the error\n   * middleware. Errors passed explicitly to `next(err)` are formatted by the\n   * terminal error middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   */\n  extend(fn: (app: express.Application) => void) {\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Register a server extension from another plugin during setup.\n   * Unlike extend(), this is designed for internal plugin-to-plugin\n   * coordination where extensions are registered before the server starts\n   * listening — typically called by PluginContext when flushing buffered routes.\n   */\n  addExtension(fn: (app: express.Application) => void) {\n    this.serverExtensions.push(fn);\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints,\n   * and a map of plugin names to their client-exposed configs.\n   */\n  private async extendRoutes(): Promise<{\n    endpoints: PluginEndpoints;\n    pluginConfigs: PluginClientConfigs;\n  }> {\n    const endpoints: PluginEndpoints = {};\n    const pluginConfigs: PluginClientConfigs = {};\n\n    const plugins = this.context?.getPlugins();\n    if (!plugins || plugins.size === 0) return { endpoints, pluginConfigs };\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of plugins.values()) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        endpoints[plugin.name] = plugin.getEndpoints();\n\n        // Collect paths that should skip body parsing\n        if (\n          plugin.getSkipBodyParsingPaths &&\n          typeof plugin.getSkipBodyParsingPaths === \"function\"\n        ) {\n          for (const p of plugin.getSkipBodyParsingPaths()) {\n            this.rawBodyPaths.add(p);\n          }\n        }\n      }\n\n      if (typeof plugin.clientConfig === \"function\") {\n        try {\n          const raw = plugin.clientConfig();\n          if (raw != null) {\n            const sanitized = sanitizeClientConfig(plugin.name, raw);\n            if (Object.keys(sanitized).length > 0) {\n              pluginConfigs[plugin.name] = sanitized;\n            }\n          }\n        } catch (error) {\n          logger.error(\n            \"Plugin '%s' clientConfig() failed, skipping its config: %O\",\n            plugin.name,\n            error,\n          );\n        }\n      }\n    }\n\n    return { endpoints, pluginConfigs };\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(\n    endpoints: PluginEndpoints,\n    pluginConfigs: PluginClientConfigs,\n  ) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n        pluginConfigs,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(\n        this.serverApplication,\n        endpoints,\n        pluginConfigs,\n      );\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n        pluginConfigs,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * In development, prefers {@link ServerConfig.port} / env / default (8000), then\n   * scans upward using `get-port`'s `portNumbers()` on the listen host until one binds.\n   * In non-development, uses config / env / default only (no fallback).\n   */\n  private async resolveListenPort(): Promise<number> {\n    const requested = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n\n    if (process.env.NODE_ENV !== \"development\") {\n      this.resolvedListenPort = requested;\n      return requested;\n    }\n\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n    const upper = Math.min(requested + devListenPortSpan - 1, 65_535);\n    const port = await getPort({\n      host,\n      port: portNumbers(requested, upper),\n    });\n    this.resolvedListenPort = port;\n    if (port !== requested) {\n      logger.info(\"Port %d was busy, picking %d\", requested, port);\n    }\n    return port;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port =\n      this.resolvedListenPort ??\n      this.config.port ??\n      ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  /**\n   * Cancel in-flight work and begin closing the HTTP server.\n   *\n   * Runs in the first phase of the core LifecycleManager's graceful shutdown,\n   * before any plugin `shutdown()` hook. In addition to the base behavior\n   * (aborting SSE streams), it stops the server accepting new connections and\n   * drops idle keep-alive sockets — without `closeIdleConnections()`, a\n   * connected browser would pin `server.close()` open until the force-exit\n   * timer fires. The close is only *initiated* here; the returned promise is\n   * awaited later in {@link closeRemainingConnections} so peer plugins can\n   * still drain in-flight requests through the server first.\n   */\n  abortActiveOperations(): void {\n    super.abortActiveOperations();\n\n    if (this.server) {\n      const server = this.server;\n      this.serverClosed = new Promise((resolve) => {\n        server.close(() => resolve());\n      });\n      server.closeIdleConnections();\n    }\n  }\n\n  /**\n   * Drain the dev-only servers as this plugin's `shutdown()` hook.\n   *\n   * Runs concurrently with the other plugins' hooks during graceful shutdown.\n   * These are no-ops in production (neither is created), so this hook is\n   * effectively dev-only.\n   */\n  async shutdown(): Promise<void> {\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n  }\n\n  /**\n   * Force-close whatever sockets remain and await the server close.\n   *\n   * Registered on the `\"shutdown\"` lifecycle event in {@link start}, so it\n   * fires after every plugin's `shutdown()` hook has run — meaning any\n   * in-flight request a peer plugin was draining has already completed.\n   * `closeAllConnections()` destroys the leftover sockets (aborted SSE\n   * responses, keep-alive connections) synchronously so the pending\n   * `server.close()` can complete; the await is bounded because the close is\n   * expected to resolve promptly once the sockets are gone.\n   */\n  private async closeRemainingConnections(): Promise<void> {\n    if (this.server) {\n      this.server.closeAllConnections();\n    }\n    if (!this.serverClosed) return;\n\n    await Promise.race([\n      this.serverClosed,\n      new Promise<void>((resolve) => {\n        const timer = setTimeout(resolve, ServerPlugin.SERVER_CLOSE_TIMEOUT_MS);\n        timer.unref();\n      }),\n    ]);\n    logger.debug(\"Server closed gracefully\");\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n      /** @deprecated Server is now started automatically by createApp. */\n      start() {\n        throw new ServerError(\n          \"server.start() has been removed. Use the onPluginsReady callback instead:\\n\\n\" +\n            \"  createApp({\\n\" +\n            \"    plugins: [server(), ...],\\n\" +\n            \"    onPluginsReady(appkit) {\\n\" +\n            \"      appkit.server.extend(...);\\n\" +\n            \"    },\\n\" +\n            \"  });\\n\\n\" +\n            \"Run `npx appkit codemod on-plugins-ready --write` to auto-migrate.\",\n        );\n      },\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS: string[] = [ServerPlugin.manifest.name];\n\n/** @internal Exported for unit tests. */\nexport function requestMetricsMiddleware(\n  req: express.Request,\n  res: express.Response,\n  next: express.NextFunction,\n) {\n  const startMs = Date.now();\n  res.on(\"finish\", () => {\n    const reporter = TelemetryReporter.getInstance();\n    if (!reporter) return;\n    const routePath = (req.route as { path?: string } | undefined)?.path;\n    if (!routePath) return;\n    const baseUrl = req.baseUrl ?? \"\";\n    const template = `${baseUrl}${routePath}`;\n    reporter.recordRequest(\n      req.method,\n      template,\n      res.statusCode,\n      Date.now() - startMs,\n    );\n  });\n  next();\n}\n\n/**\n * Narrow an unknown thrown value to an Error that carries a numeric\n * `statusCode` property in the HTTP error range (e.g. `ApiError` from\n * `@databricks/sdk-experimental`).\n */\nfunction hasHttpStatusCode(\n  error: unknown,\n): error is Error & { statusCode: number } {\n  if (!(error instanceof Error) || !(\"statusCode\" in error)) return false;\n  const statusCode = error.statusCode;\n  return (\n    typeof statusCode === \"number\" &&\n    Number.isInteger(statusCode) &&\n    statusCode >= 400 &&\n    statusCode <= 599\n  );\n}\n\n/**\n * Terminal Express error-handling middleware.\n *\n * Converts errors forwarded via `next(err)` (including async handler\n * rejections forwarded by `Plugin.route()`) into JSON error responses,\n * following the same status/message conventions as `Plugin.execute()`:\n * - errors carrying an HTTP `statusCode` (including `AppKitError`) → that\n *   status; 5xx messages are masked in production to avoid leaking internals\n * - anything else → 500 with a generic message in production\n *\n * 4xx errors are expected client errors (e.g. missing auth headers) and are\n * logged at `warn` with just the message; 5xx/unknown errors are logged at\n * `error` with the full error.\n *\n * @internal Exported for unit tests.\n */\nexport function errorHandlerMiddleware(\n  err: unknown,\n  req: express.Request,\n  res: express.Response,\n  next: express.NextFunction,\n) {\n  const httpError =\n    err instanceof AppKitError || hasHttpStatusCode(err) ? err : null;\n  const statusCode = httpError ? httpError.statusCode : 500;\n  const isClientError = statusCode < 500;\n\n  if (isClientError) {\n    logger.warn(\n      \"Request failed for %s %s with status %d: %s\",\n      req.method,\n      req.originalUrl,\n      statusCode,\n      err instanceof Error ? err.message : String(err),\n    );\n  } else {\n    logger.error(\n      \"Unhandled error for %s %s: %O\",\n      req.method,\n      req.originalUrl,\n      // toJSON() redacts sensitive context fields; %O on a raw AppKitError\n      // would enumerate them unredacted.\n      err instanceof AppKitError ? err.toJSON() : err,\n    );\n  }\n\n  if (res.headersSent) {\n    next(err);\n    return;\n  }\n\n  const isDev = process.env.NODE_ENV !== \"production\";\n  const message = err instanceof Error ? err.message : \"Server error\";\n\n  res.status(statusCode).json({\n    error: isDev || isClientError ? message : \"Server error\",\n  });\n}\n\n/**\n * @internal\n */\nexport const server = toPlugin(ServerPlugin);\n// Export manifest and types\n"],"mappings":"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"}

package/dist/registry/resource-registry.d.ts

@@ -95,7 +95,7 @@ declare class ResourceRegistry {
    * const result = registry.validate();
    *
    * if (!result.valid) {
-   *   console.error("Missing resources:", result.missing.map(r => Object.values(r.fields).map(f => f.env)));
+   *   console.error(ResourceRegistry.formatMissingResources(result.missing));
    * }
    * ```
    */
@@ -112,6 +112,14 @@ declare class ResourceRegistry {
    * @throws {ConfigurationError} In production when required resources are missing, or in dev when APPKIT_STRICT_VALIDATION=true
    */
   enforceValidation(): ValidationResult;
+  /**
+   * Env var names for an entry's fields that are actually unset (undefined or
+   * empty), skipping fields that declare no env var (e.g. discovery-only
+   * fields resolved at deploy time). Mirrors the resolution check in
+   * {@link validate} so error output lists exactly what the caller must set —
+   * not every field on the resource.
+   */
+  private static unsetEnvVars;
   /**
    * Formats missing resources into a human-readable error message.
    *

package/dist/registry/resource-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-registry.d.ts","names":[],"sources":["../../src/registry/resource-registry.ts"],"mappings":";;;;;;;;;cAqDa,gBAAA;EAAA,QACH,SAAA;EAiYsC;;;;;;;;;;;;EAnXvC,QAAA,CAAS,MAAA,UAAgB,QAAA,EAAU,mBAAA;EAiKnC;;;;;;;EAtIA,gBAAA,CACL,UAAA,EAAY,UAAA,CAAW,iBAAA;EAyKlB;;;;EAAA,QAjIC,cAAA;EAqJD;;;;;;EAxDA,MAAA,CAAA,GAAU,aAAA;EA6L6B;;;;;;;EAlLvC,GAAA,CAAI,IAAA,UAAc,WAAA,WAAsB,aAAA;;;;;EAQxC,KAAA,CAAA;;;;EAOA,IAAA,CAAA;;;;;;;EAUA,WAAA,CAAY,UAAA,WAAqB,aAAA;;;;;;EAWjC,WAAA,CAAA,GAAe,aAAA;;;;;;EASf,WAAA,CAAA,GAAe,aAAA;;;;;;;;;;;;;;;;;;;;;;EAyBf,QAAA,CAAA,GAAY,gBAAA;;;;;;;;;;;;EA+DZ,iBAAA,CAAA,GAAqB,gBAAA;;;;;;;SA6Cd,sBAAA,CAAuB,OAAA,EAAS,aAAA;;;;;;;;SAqBhC,sBAAA,CAAuB,OAAA,EAAS,aAAA;AAAA"}
+{"version":3,"file":"resource-registry.d.ts","names":[],"sources":["../../src/registry/resource-registry.ts"],"mappings":";;;;;;;;;cAqDa,gBAAA;EAAA,QACH,SAAA;EAoZsC;;;;;;;;;;;;EAtYvC,QAAA,CAAS,MAAA,UAAgB,QAAA,EAAU,mBAAA;EAiKnC;;;;;;;EAtIA,gBAAA,CACL,UAAA,EAAY,UAAA,CAAW,iBAAA;EAyKlB;;;;EAAA,QAjIC,cAAA;EAqJD;;;;;;EAxDA,MAAA,CAAA,GAAU,aAAA;EAgNH;;;;;;;EArMP,GAAA,CAAI,IAAA,UAAc,WAAA,WAAsB,aAAA;;;;;EAQxC,KAAA,CAAA;;;;EAOA,IAAA,CAAA;;;;;;;EAUA,WAAA,CAAY,UAAA,WAAqB,aAAA;;;;;;EAWjC,WAAA,CAAA,GAAe,aAAA;;;;;;EASf,WAAA,CAAA,GAAe,aAAA;;;;;;;;;;;;;;;;;;;;;;EAyBf,QAAA,CAAA,GAAY,gBAAA;;;;;;;;;;;;EA+DZ,iBAAA,CAAA,GAAqB,gBAAA;;;;;;;;iBA8Cb,YAAA;;;;;;;SAkBD,sBAAA,CAAuB,OAAA,EAAS,aAAA;;;;;;;;SAqBhC,sBAAA,CAAuB,OAAA,EAAS,aAAA;AAAA"}