@databricks/appkit 0.38.1 → 0.40.0

package/dist/connectors/sql-warehouse/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/sql-warehouse/client.ts"],"sourcesContent":["import {\n  Context,\n  type sql,\n  type WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport type { TelemetryOptions } from \"shared\";\nimport {\n  AppKitError,\n  ConnectionError,\n  ExecutionError,\n  ValidationError,\n} from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { ArrowStreamProcessor } from \"../../stream/arrow-stream-processor\";\nimport type { TelemetryProvider } from \"../../telemetry\";\nimport {\n  type Counter,\n  type Histogram,\n  type Span,\n  SpanKind,\n  SpanStatusCode,\n  TelemetryManager,\n} from \"../../telemetry\";\nimport { executeStatementDefaults } from \"./defaults\";\n\nconst logger = createLogger(\"connectors:sql-warehouse\");\n\ninterface SQLWarehouseConfig {\n  timeout?: number;\n  telemetry?: TelemetryOptions;\n}\n\nexport class SQLWarehouseConnector {\n  private readonly name = \"sql-warehouse\";\n\n  private config: SQLWarehouseConfig;\n\n  // Lazy-initialized: only created when Arrow format is used\n  private _arrowProcessor: ArrowStreamProcessor | null = null;\n  // telemetry\n  private readonly telemetry: TelemetryProvider;\n  private readonly telemetryMetrics: {\n    queryCount: Counter;\n    queryDuration: Histogram;\n  };\n\n  constructor(config: SQLWarehouseConfig) {\n    this.config = config;\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      queryCount: this.telemetry.getMeter().createCounter(\"query.count\", {\n        description: \"Total number of queries executed\",\n        unit: \"1\",\n      }),\n      queryDuration: this.telemetry\n        .getMeter()\n        .createHistogram(\"query.duration\", {\n          description: \"Duration of queries executed\",\n          unit: \"ms\",\n        }),\n    };\n  }\n\n  /**\n   * Lazily initializes and returns the ArrowStreamProcessor.\n   * Only created on first Arrow format query to avoid unnecessary allocation.\n   */\n  private get arrowProcessor(): ArrowStreamProcessor {\n    if (!this._arrowProcessor) {\n      this._arrowProcessor = new ArrowStreamProcessor({\n        timeout: this.config.timeout || executeStatementDefaults.timeout,\n        maxConcurrentDownloads:\n          ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n        retries: ArrowStreamProcessor.DEFAULT_RETRIES,\n      });\n    }\n    return this._arrowProcessor;\n  }\n\n  async executeStatement(\n    workspaceClient: WorkspaceClient,\n    input: sql.ExecuteStatementRequest,\n    signal?: AbortSignal,\n  ) {\n    const startTime = Date.now();\n    let success = false;\n\n    // if signal is aborted, throw an error\n    if (signal?.aborted) {\n      throw ExecutionError.canceled();\n    }\n\n    return this.telemetry.startActiveSpan(\n      \"sql.query\",\n      {\n        kind: SpanKind.CLIENT,\n        attributes: {\n          \"db.system\": \"databricks\",\n          \"db.warehouse_id\": input.warehouse_id || \"\",\n          \"db.catalog\": input.catalog ?? \"\",\n          \"db.schema\": input.schema ?? \"\",\n          \"db.statement\": input.statement?.substring(0, 500) || \"\",\n          \"db.has_parameters\": !!input.parameters,\n        },\n      },\n      async (span: Span) => {\n        let abortHandler: (() => void) | undefined;\n        let isAborted = false;\n\n        if (signal) {\n          abortHandler = () => {\n            // abort span if not recording\n            if (!span.isRecording()) return;\n            isAborted = true;\n            span.setAttribute(\"cancelled\", true);\n            span.setStatus({\n              code: SpanStatusCode.ERROR,\n              message: \"Query cancelled by client\",\n            });\n            span.end();\n          };\n          signal.addEventListener(\"abort\", abortHandler, { once: true });\n        }\n\n        try {\n          // validate required fields\n          if (!input.statement) {\n            throw ValidationError.missingField(\"statement\");\n          }\n\n          if (!input.warehouse_id) {\n            throw ValidationError.missingField(\"warehouse_id\");\n          }\n\n          const body: sql.ExecuteStatementRequest = {\n            statement: input.statement,\n            parameters: input.parameters,\n            warehouse_id: input.warehouse_id,\n            catalog: input.catalog,\n            schema: input.schema,\n            wait_timeout:\n              input.wait_timeout || executeStatementDefaults.wait_timeout,\n            disposition:\n              input.disposition || executeStatementDefaults.disposition,\n            format: input.format || executeStatementDefaults.format,\n            byte_limit: input.byte_limit,\n            row_limit: input.row_limit,\n            on_wait_timeout:\n              input.on_wait_timeout || executeStatementDefaults.on_wait_timeout,\n          };\n\n          span.addEvent(\"statement.submitting\", {\n            \"db.warehouse_id\": input.warehouse_id,\n          });\n\n          const response =\n            await workspaceClient.statementExecution.executeStatement(\n              body,\n              this._createContext(signal),\n            );\n\n          if (!response) {\n            throw ConnectionError.apiFailure(\"SQL Warehouse\");\n          }\n          const status = response.status;\n          const statementId = response.statement_id as string;\n\n          span.setAttribute(\"db.statement_id\", statementId);\n          span.addEvent(\"statement.submitted\", {\n            \"db.statement_id\": response.statement_id,\n            \"db.status\": status?.state,\n          });\n\n          let result:\n            | sql.StatementResponse\n            | { result: { statement_id: string; status: sql.StatementStatus } };\n\n          switch (status?.state) {\n            case \"RUNNING\":\n            case \"PENDING\":\n              span.addEvent(\"statement.polling_started\", {\n                \"db.status\": response.status?.state,\n              });\n              result = await this._pollForStatementResult(\n                workspaceClient,\n                statementId,\n                this.config.timeout,\n                signal,\n              );\n              break;\n            case \"SUCCEEDED\":\n              result = this._transformDataArray(response);\n              break;\n            case \"FAILED\":\n              throw ExecutionError.statementFailed(status.error?.message);\n            case \"CANCELED\":\n              throw ExecutionError.canceled();\n            case \"CLOSED\":\n              throw ExecutionError.resultsClosed();\n            default:\n              throw ExecutionError.unknownState(\n                String(status?.state ?? \"unknown\"),\n              );\n          }\n\n          const resultData = result.result as any;\n          const rowCount =\n            resultData?.data?.length ?? resultData?.data_array?.length ?? 0;\n\n          if (rowCount > 0) {\n            span.setAttribute(\"db.result.row_count\", rowCount);\n          }\n\n          const duration = Date.now() - startTime;\n          logger.event()?.setContext(\"sql-warehouse\", {\n            warehouse_id: input.warehouse_id,\n            rows_returned: rowCount,\n            query_duration_ms: duration,\n          });\n\n          success = true;\n          // only set success status if not aborted\n          if (!isAborted) {\n            span.setStatus({ code: SpanStatusCode.OK });\n          }\n          return result;\n        } catch (error) {\n          // only record error if not already handled by abort\n          if (!isAborted) {\n            span.recordException(error as Error);\n            span.setStatus({\n              code: SpanStatusCode.ERROR,\n              message: error instanceof Error ? error.message : String(error),\n            });\n\n            logger.error(\n              \"Statement execution failed: %s\",\n              error instanceof Error ? error.message : String(error),\n            );\n          }\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        } finally {\n          // remove abort handler\n          if (abortHandler && signal) {\n            signal.removeEventListener(\"abort\", abortHandler);\n          }\n\n          const duration = Date.now() - startTime;\n\n          // end span if not already ended by abort handler\n          if (!isAborted) {\n            span.end();\n          }\n\n          const attributes = {\n            \"db.warehouse_id\": input.warehouse_id,\n            \"db.catalog\": input.catalog ?? \"\",\n            \"db.schema\": input.schema ?? \"\",\n            \"db.statement\": input.statement?.substring(0, 500) || \"\",\n            success: success.toString(),\n          };\n\n          this.telemetryMetrics.queryCount.add(1, attributes);\n          this.telemetryMetrics.queryDuration.record(duration, attributes);\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  private async _pollForStatementResult(\n    workspaceClient: WorkspaceClient,\n    statementId: string,\n    timeout = executeStatementDefaults.timeout,\n    signal?: AbortSignal,\n  ) {\n    return this.telemetry.startActiveSpan(\n      \"sql.poll\",\n      {\n        attributes: {\n          \"db.statement_id\": statementId,\n          \"db.polling.timeout\": timeout,\n        },\n      },\n      async (span: Span) => {\n        try {\n          const startTime = Date.now();\n          let delay = 1000;\n          const maxDelayBetweenPolls = 5000; // max 5 seconds between polls\n          let pollCount = 0;\n\n          while (true) {\n            pollCount++;\n            span.setAttribute(\"db.polling.current_attempt\", pollCount);\n\n            // check if timeout exceeded\n            const elapsedTime = Date.now() - startTime;\n            if (elapsedTime > timeout) {\n              const error = ExecutionError.statementFailed(\n                `Polling timeout exceeded after ${timeout}ms (elapsed: ${elapsedTime}ms)`,\n              );\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            }\n\n            if (signal?.aborted) {\n              const error = ExecutionError.canceled();\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            }\n\n            span.addEvent(\"polling.attempt\", {\n              \"poll.attempt\": pollCount,\n              \"poll.delay_ms\": delay,\n              \"poll.elapsed_ms\": elapsedTime,\n            });\n\n            const response =\n              await workspaceClient.statementExecution.getStatement(\n                {\n                  statement_id: statementId,\n                },\n                this._createContext(signal),\n              );\n            if (!response) {\n              throw ConnectionError.apiFailure(\"SQL Warehouse\");\n            }\n\n            const status = response.status;\n\n            span.addEvent(\"polling.status_check\", {\n              \"db.status\": status?.state,\n              \"poll.attempt\": pollCount,\n            });\n\n            switch (status?.state) {\n              case \"PENDING\":\n              case \"RUNNING\":\n                // continue polling\n                break;\n              case \"SUCCEEDED\":\n                span.setAttribute(\"db.polling.attempts\", pollCount);\n                span.setAttribute(\"db.polling.total_duration_ms\", elapsedTime);\n                span.addEvent(\"polling.completed\", {\n                  \"poll.attempts\": pollCount,\n                  \"poll.duration_ms\": elapsedTime,\n                });\n                span.setStatus({ code: SpanStatusCode.OK });\n                return this._transformDataArray(response);\n              case \"FAILED\":\n                throw ExecutionError.statementFailed(status.error?.message);\n              case \"CANCELED\":\n                throw ExecutionError.canceled();\n              case \"CLOSED\":\n                throw ExecutionError.resultsClosed();\n              default:\n                throw ExecutionError.unknownState(\n                  String(status?.state ?? \"unknown\"),\n                );\n            }\n\n            // continue polling after delay\n            await new Promise((resolve) => setTimeout(resolve, delay));\n            delay = Math.min(delay * 2, maxDelayBetweenPolls);\n          }\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({\n            code: SpanStatusCode.ERROR,\n            message: error instanceof Error ? error.message : String(error),\n          });\n\n          // error logging is handled by executeStatement's catch block (gated on isAborted)\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  private _transformDataArray(response: sql.StatementResponse) {\n    if (response.manifest?.format === \"ARROW_STREAM\") {\n      return this.updateWithArrowStatus(response);\n    }\n\n    if (!response.result?.data_array || !response.manifest?.schema?.columns) {\n      return response;\n    }\n\n    const columns = response.manifest.schema.columns;\n\n    const transformedData = response.result.data_array.map((row) => {\n      const obj: Record<string, unknown> = {};\n      row.forEach((value, index) => {\n        const column = columns[index];\n        const columnName = column?.name || `column_${index}`;\n\n        // attempt to parse JSON strings for string columns\n        if (\n          column?.type_name === \"STRING\" &&\n          typeof value === \"string\" &&\n          value &&\n          (value[0] === \"{\" || value[0] === \"[\")\n        ) {\n          try {\n            obj[columnName] = JSON.parse(value);\n          } catch {\n            // if parsing fails, keep as string\n            obj[columnName] = value;\n          }\n        } else {\n          obj[columnName] = value;\n        }\n      });\n      return obj;\n    });\n\n    // remove data_array\n    const { data_array: _data_array, ...restResult } = response.result;\n    return {\n      ...response,\n      result: {\n        ...restResult,\n        data: transformedData,\n      },\n    };\n  }\n\n  private updateWithArrowStatus(response: sql.StatementResponse): {\n    result: { statement_id: string; status: sql.StatementStatus };\n  } {\n    return {\n      result: {\n        statement_id: response.statement_id as string,\n        status: {\n          state: response.status?.state,\n          error: response.status?.error,\n        } as sql.StatementStatus,\n      },\n    };\n  }\n\n  async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.arrowProcessor.processChunks>> {\n    const startTime = Date.now();\n\n    return this.telemetry.startActiveSpan(\n      \"arrow.getData\",\n      {\n        kind: SpanKind.CLIENT,\n        attributes: {\n          \"db.system\": \"databricks\",\n          \"arrow.job_id\": jobId,\n        },\n      },\n      async (span: Span) => {\n        try {\n          const response =\n            await workspaceClient.statementExecution.getStatement(\n              { statement_id: jobId },\n              this._createContext(signal),\n            );\n\n          const chunks = response.result?.external_links;\n          const schema = response.manifest?.schema;\n\n          if (!chunks || !schema) {\n            throw ExecutionError.missingData(\"chunks or schema\");\n          }\n\n          span.setAttribute(\"arrow.chunk_count\", chunks.length);\n\n          const result = await this.arrowProcessor.processChunks(\n            chunks,\n            schema,\n            signal,\n          );\n\n          span.setAttribute(\"arrow.data_size_bytes\", result.data.length);\n          span.setStatus({ code: SpanStatusCode.OK });\n\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryDuration.record(duration, {\n            operation: \"arrow.getData\",\n            status: \"success\",\n          });\n\n          logger.event()?.setContext(\"sql-warehouse\", {\n            arrow_data_size_bytes: result.data.length,\n            arrow_job_id: jobId,\n          });\n\n          return result;\n        } catch (error) {\n          span.setStatus({\n            code: SpanStatusCode.ERROR,\n            message: error instanceof Error ? error.message : \"Unknown error\",\n          });\n          span.recordException(error as Error);\n\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryDuration.record(duration, {\n            operation: \"arrow.getData\",\n            status: \"error\",\n          });\n\n          logger.error(\"Failed Arrow job: %s %O\", jobId, error);\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        }\n      },\n    );\n  }\n\n  // create context for cancellation token\n  private _createContext(signal?: AbortSignal) {\n    return new Context({\n      cancellationToken: {\n        isCancellationRequested: signal?.aborted ?? false,\n        onCancellationRequested: (cb: () => void) => {\n          signal?.addEventListener(\"abort\", cb, { once: true });\n        },\n      },\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAyBA,MAAM,SAAS,aAAa,2BAA2B;AAOvD,IAAa,wBAAb,MAAmC;CACjC,AAAiB,OAAO;CAExB,AAAQ;CAGR,AAAQ,kBAA+C;CAEvD,AAAiB;CACjB,AAAiB;CAKjB,YAAY,QAA4B;AACtC,OAAK,SAAS;AAEd,OAAK,YAAY,iBAAiB,YAChC,KAAK,MACL,KAAK,OAAO,UACb;AACD,OAAK,mBAAmB;GACtB,YAAY,KAAK,UAAU,UAAU,CAAC,cAAc,eAAe;IACjE,aAAa;IACb,MAAM;IACP,CAAC;GACF,eAAe,KAAK,UACjB,UAAU,CACV,gBAAgB,kBAAkB;IACjC,aAAa;IACb,MAAM;IACP,CAAC;GACL;;;;;;CAOH,IAAY,iBAAuC;AACjD,MAAI,CAAC,KAAK,gBACR,MAAK,kBAAkB,IAAI,qBAAqB;GAC9C,SAAS,KAAK,OAAO,WAAW,yBAAyB;GACzD,wBACE,qBAAqB;GACvB,SAAS,qBAAqB;GAC/B,CAAC;AAEJ,SAAO,KAAK;;CAGd,MAAM,iBACJ,iBACA,OACA,QACA;EACA,MAAM,YAAY,KAAK,KAAK;EAC5B,IAAI,UAAU;AAGd,MAAI,QAAQ,QACV,OAAM,eAAe,UAAU;AAGjC,SAAO,KAAK,UAAU,gBACpB,aACA;GACE,MAAM,SAAS;GACf,YAAY;IACV,aAAa;IACb,mBAAmB,MAAM,gBAAgB;IACzC,cAAc,MAAM,WAAW;IAC/B,aAAa,MAAM,UAAU;IAC7B,gBAAgB,MAAM,WAAW,UAAU,GAAG,IAAI,IAAI;IACtD,qBAAqB,CAAC,CAAC,MAAM;IAC9B;GACF,EACD,OAAO,SAAe;GACpB,IAAI;GACJ,IAAI,YAAY;AAEhB,OAAI,QAAQ;AACV,yBAAqB;AAEnB,SAAI,CAAC,KAAK,aAAa,CAAE;AACzB,iBAAY;AACZ,UAAK,aAAa,aAAa,KAAK;AACpC,UAAK,UAAU;MACb,MAAM,eAAe;MACrB,SAAS;MACV,CAAC;AACF,UAAK,KAAK;;AAEZ,WAAO,iBAAiB,SAAS,cAAc,EAAE,MAAM,MAAM,CAAC;;AAGhE,OAAI;AAEF,QAAI,CAAC,MAAM,UACT,OAAM,gBAAgB,aAAa,YAAY;AAGjD,QAAI,CAAC,MAAM,aACT,OAAM,gBAAgB,aAAa,eAAe;IAGpD,MAAM,OAAoC;KACxC,WAAW,MAAM;KACjB,YAAY,MAAM;KAClB,cAAc,MAAM;KACpB,SAAS,MAAM;KACf,QAAQ,MAAM;KACd,cACE,MAAM,gBAAgB,yBAAyB;KACjD,aACE,MAAM,eAAe,yBAAyB;KAChD,QAAQ,MAAM,UAAU,yBAAyB;KACjD,YAAY,MAAM;KAClB,WAAW,MAAM;KACjB,iBACE,MAAM,mBAAmB,yBAAyB;KACrD;AAED,SAAK,SAAS,wBAAwB,EACpC,mBAAmB,MAAM,cAC1B,CAAC;IAEF,MAAM,WACJ,MAAM,gBAAgB,mBAAmB,iBACvC,MACA,KAAK,eAAe,OAAO,CAC5B;AAEH,QAAI,CAAC,SACH,OAAM,gBAAgB,WAAW,gBAAgB;IAEnD,MAAM,SAAS,SAAS;IACxB,MAAM,cAAc,SAAS;AAE7B,SAAK,aAAa,mBAAmB,YAAY;AACjD,SAAK,SAAS,uBAAuB;KACnC,mBAAmB,SAAS;KAC5B,aAAa,QAAQ;KACtB,CAAC;IAEF,IAAI;AAIJ,YAAQ,QAAQ,OAAhB;KACE,KAAK;KACL,KAAK;AACH,WAAK,SAAS,6BAA6B,EACzC,aAAa,SAAS,QAAQ,OAC/B,CAAC;AACF,eAAS,MAAM,KAAK,wBAClB,iBACA,aACA,KAAK,OAAO,SACZ,OACD;AACD;KACF,KAAK;AACH,eAAS,KAAK,oBAAoB,SAAS;AAC3C;KACF,KAAK,SACH,OAAM,eAAe,gBAAgB,OAAO,OAAO,QAAQ;KAC7D,KAAK,WACH,OAAM,eAAe,UAAU;KACjC,KAAK,SACH,OAAM,eAAe,eAAe;KACtC,QACE,OAAM,eAAe,aACnB,OAAO,QAAQ,SAAS,UAAU,CACnC;;IAGL,MAAM,aAAa,OAAO;IAC1B,MAAM,WACJ,YAAY,MAAM,UAAU,YAAY,YAAY,UAAU;AAEhE,QAAI,WAAW,EACb,MAAK,aAAa,uBAAuB,SAAS;IAGpD,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,WAAO,OAAO,EAAE,WAAW,iBAAiB;KAC1C,cAAc,MAAM;KACpB,eAAe;KACf,mBAAmB;KACpB,CAAC;AAEF,cAAU;AAEV,QAAI,CAAC,UACH,MAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAE7C,WAAO;YACA,OAAO;AAEd,QAAI,CAAC,WAAW;AACd,UAAK,gBAAgB,MAAe;AACpC,UAAK,UAAU;MACb,MAAM,eAAe;MACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;MAChE,CAAC;AAEF,YAAO,MACL,kCACA,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CACvD;;AAGH,QAAI,iBAAiB,YACnB,OAAM;AAER,UAAM,eAAe,gBACnB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CACvD;aACO;AAER,QAAI,gBAAgB,OAClB,QAAO,oBAAoB,SAAS,aAAa;IAGnD,MAAM,WAAW,KAAK,KAAK,GAAG;AAG9B,QAAI,CAAC,UACH,MAAK,KAAK;IAGZ,MAAM,aAAa;KACjB,mBAAmB,MAAM;KACzB,cAAc,MAAM,WAAW;KAC/B,aAAa,MAAM,UAAU;KAC7B,gBAAgB,MAAM,WAAW,UAAU,GAAG,IAAI,IAAI;KACtD,SAAS,QAAQ,UAAU;KAC5B;AAED,SAAK,iBAAiB,WAAW,IAAI,GAAG,WAAW;AACnD,SAAK,iBAAiB,cAAc,OAAO,UAAU,WAAW;;KAGpE;GAAE,MAAM,KAAK;GAAM,eAAe;GAAM,CACzC;;CAGH,MAAc,wBACZ,iBACA,aACA,UAAU,yBAAyB,SACnC,QACA;AACA,SAAO,KAAK,UAAU,gBACpB,YACA,EACE,YAAY;GACV,mBAAmB;GACnB,sBAAsB;GACvB,EACF,EACD,OAAO,SAAe;AACpB,OAAI;IACF,MAAM,YAAY,KAAK,KAAK;IAC5B,IAAI,QAAQ;IACZ,MAAM,uBAAuB;IAC7B,IAAI,YAAY;AAEhB,WAAO,MAAM;AACX;AACA,UAAK,aAAa,8BAA8B,UAAU;KAG1D,MAAM,cAAc,KAAK,KAAK,GAAG;AACjC,SAAI,cAAc,SAAS;MACzB,MAAM,QAAQ,eAAe,gBAC3B,kCAAkC,QAAQ,eAAe,YAAY,KACtE;AACD,WAAK,gBAAgB,MAAM;AAC3B,WAAK,UAAU,EAAE,MAAM,eAAe,OAAO,CAAC;AAC9C,YAAM;;AAGR,SAAI,QAAQ,SAAS;MACnB,MAAM,QAAQ,eAAe,UAAU;AACvC,WAAK,gBAAgB,MAAM;AAC3B,WAAK,UAAU,EAAE,MAAM,eAAe,OAAO,CAAC;AAC9C,YAAM;;AAGR,UAAK,SAAS,mBAAmB;MAC/B,gBAAgB;MAChB,iBAAiB;MACjB,mBAAmB;MACpB,CAAC;KAEF,MAAM,WACJ,MAAM,gBAAgB,mBAAmB,aACvC,EACE,cAAc,aACf,EACD,KAAK,eAAe,OAAO,CAC5B;AACH,SAAI,CAAC,SACH,OAAM,gBAAgB,WAAW,gBAAgB;KAGnD,MAAM,SAAS,SAAS;AAExB,UAAK,SAAS,wBAAwB;MACpC,aAAa,QAAQ;MACrB,gBAAgB;MACjB,CAAC;AAEF,aAAQ,QAAQ,OAAhB;MACE,KAAK;MACL,KAAK,UAEH;MACF,KAAK;AACH,YAAK,aAAa,uBAAuB,UAAU;AACnD,YAAK,aAAa,gCAAgC,YAAY;AAC9D,YAAK,SAAS,qBAAqB;QACjC,iBAAiB;QACjB,oBAAoB;QACrB,CAAC;AACF,YAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,cAAO,KAAK,oBAAoB,SAAS;MAC3C,KAAK,SACH,OAAM,eAAe,gBAAgB,OAAO,OAAO,QAAQ;MAC7D,KAAK,WACH,OAAM,eAAe,UAAU;MACjC,KAAK,SACH,OAAM,eAAe,eAAe;MACtC,QACE,OAAM,eAAe,aACnB,OAAO,QAAQ,SAAS,UAAU,CACnC;;AAIL,WAAM,IAAI,SAAS,YAAY,WAAW,SAAS,MAAM,CAAC;AAC1D,aAAQ,KAAK,IAAI,QAAQ,GAAG,qBAAqB;;YAE5C,OAAO;AACd,SAAK,gBAAgB,MAAe;AACpC,SAAK,UAAU;KACb,MAAM,eAAe;KACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;KAChE,CAAC;AAGF,QAAI,iBAAiB,YACnB,OAAM;AAER,UAAM,eAAe,gBACnB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CACvD;aACO;AACR,SAAK,KAAK;;KAGd;GAAE,MAAM,KAAK;GAAM,eAAe;GAAM,CACzC;;CAGH,AAAQ,oBAAoB,UAAiC;AAC3D,MAAI,SAAS,UAAU,WAAW,eAChC,QAAO,KAAK,sBAAsB,SAAS;AAG7C,MAAI,CAAC,SAAS,QAAQ,cAAc,CAAC,SAAS,UAAU,QAAQ,QAC9D,QAAO;EAGT,MAAM,UAAU,SAAS,SAAS,OAAO;EAEzC,MAAM,kBAAkB,SAAS,OAAO,WAAW,KAAK,QAAQ;GAC9D,MAAM,MAA+B,EAAE;AACvC,OAAI,SAAS,OAAO,UAAU;IAC5B,MAAM,SAAS,QAAQ;IACvB,MAAM,aAAa,QAAQ,QAAQ,UAAU;AAG7C,QACE,QAAQ,cAAc,YACtB,OAAO,UAAU,YACjB,UACC,MAAM,OAAO,OAAO,MAAM,OAAO,KAElC,KAAI;AACF,SAAI,cAAc,KAAK,MAAM,MAAM;YAC7B;AAEN,SAAI,cAAc;;QAGpB,KAAI,cAAc;KAEpB;AACF,UAAO;IACP;EAGF,MAAM,EAAE,YAAY,aAAa,GAAG,eAAe,SAAS;AAC5D,SAAO;GACL,GAAG;GACH,QAAQ;IACN,GAAG;IACH,MAAM;IACP;GACF;;CAGH,AAAQ,sBAAsB,UAE5B;AACA,SAAO,EACL,QAAQ;GACN,cAAc,SAAS;GACvB,QAAQ;IACN,OAAO,SAAS,QAAQ;IACxB,OAAO,SAAS,QAAQ;IACzB;GACF,EACF;;CAGH,MAAM,aACJ,iBACA,OACA,QAC+D;EAC/D,MAAM,YAAY,KAAK,KAAK;AAE5B,SAAO,KAAK,UAAU,gBACpB,iBACA;GACE,MAAM,SAAS;GACf,YAAY;IACV,aAAa;IACb,gBAAgB;IACjB;GACF,EACD,OAAO,SAAe;AACpB,OAAI;IACF,MAAM,WACJ,MAAM,gBAAgB,mBAAmB,aACvC,EAAE,cAAc,OAAO,EACvB,KAAK,eAAe,OAAO,CAC5B;IAEH,MAAM,SAAS,SAAS,QAAQ;IAChC,MAAM,SAAS,SAAS,UAAU;AAElC,QAAI,CAAC,UAAU,CAAC,OACd,OAAM,eAAe,YAAY,mBAAmB;AAGtD,SAAK,aAAa,qBAAqB,OAAO,OAAO;IAErD,MAAM,SAAS,MAAM,KAAK,eAAe,cACvC,QACA,QACA,OACD;AAED,SAAK,aAAa,yBAAyB,OAAO,KAAK,OAAO;AAC9D,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;IAE3C,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,SAAK,iBAAiB,cAAc,OAAO,UAAU;KACnD,WAAW;KACX,QAAQ;KACT,CAAC;AAEF,WAAO,OAAO,EAAE,WAAW,iBAAiB;KAC1C,uBAAuB,OAAO,KAAK;KACnC,cAAc;KACf,CAAC;AAEF,WAAO;YACA,OAAO;AACd,SAAK,UAAU;KACb,MAAM,eAAe;KACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU;KACnD,CAAC;AACF,SAAK,gBAAgB,MAAe;IAEpC,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,SAAK,iBAAiB,cAAc,OAAO,UAAU;KACnD,WAAW;KACX,QAAQ;KACT,CAAC;AAEF,WAAO,MAAM,2BAA2B,OAAO,MAAM;AAErD,QAAI,iBAAiB,YACnB,OAAM;AAER,UAAM,eAAe,gBACnB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,CACvD;;IAGN;;CAIH,AAAQ,eAAe,QAAsB;AAC3C,SAAO,IAAI,QAAQ,EACjB,mBAAmB;GACjB,yBAAyB,QAAQ,WAAW;GAC5C,0BAA0B,OAAmB;AAC3C,YAAQ,iBAAiB,SAAS,IAAI,EAAE,MAAM,MAAM,CAAC;;GAExD,EACF,CAAC"}
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/sql-warehouse/client.ts"],"sourcesContent":["import {\n  Context,\n  type sql,\n  type WorkspaceClient,\n} from \"@databricks/sdk-experimental\";\nimport type { TelemetryOptions } from \"shared\";\nimport {\n  AppKitError,\n  ConfigurationError,\n  ConnectionError,\n  ExecutionError,\n  ValidationError,\n} from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { ArrowStreamProcessor } from \"../../stream/arrow-stream-processor\";\nimport type { TelemetryProvider } from \"../../telemetry\";\nimport {\n  type Counter,\n  type Histogram,\n  type Span,\n  SpanKind,\n  SpanStatusCode,\n  TelemetryManager,\n} from \"../../telemetry\";\nimport { executeStatementDefaults } from \"./defaults\";\nimport { WarehousePollBackoff } from \"./warehouse-poll-backoff\";\nimport { WarehouseStatusEmitter } from \"./warehouse-status-emitter\";\n\nconst logger = createLogger(\"connectors:sql-warehouse\");\n\ninterface SQLWarehouseConfig {\n  timeout?: number;\n  telemetry?: TelemetryOptions;\n}\n\n/**\n * Default ceiling for how long {@link SQLWarehouseConnector.ensureWarehouseRunning}\n * will wait for a warehouse to reach the RUNNING state before giving up.\n *\n * Five minutes covers a cold-start of a classic warehouse on most workspaces;\n * serverless typically reaches RUNNING within ~30s.\n */\nexport const DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS = 5 * 60 * 1000;\n\n/**\n * Window during which a recent `RUNNING` observation lets subsequent calls\n * to {@link SQLWarehouseConnector.ensureWarehouseRunning} short-circuit\n * without making any SDK calls. Sized to roughly the upper bound of how\n * long Databricks keeps a warehouse \"stickily\" available between requests\n * — past that, we re-verify.\n */\nconst WAREHOUSE_RUNNING_CACHE_TTL_MS = 30_000;\n\n/**\n * A single observation of the warehouse state, emitted by\n * {@link SQLWarehouseConnector.ensureWarehouseRunning} so callers can stream\n * progress to clients (e.g. over SSE).\n *\n * Note: `health.summary` from the SDK is intentionally NOT exposed on this\n * type. It's free-form operator-oriented diagnostic text (cluster IDs,\n * capacity-failure reasons, internal RPC errors) that must not reach end\n * users. The raw value stays in the OTel span attributes for server-side\n * debugging only.\n */\nexport interface WarehouseStatusUpdate {\n  /** Current state from the SDK (RUNNING | STARTING | STOPPED | STOPPING | DELETED | DELETING). */\n  state: sql.State;\n  /** Milliseconds elapsed since `ensureWarehouseRunning` was called. */\n  elapsedMs: number;\n  /** 1-based attempt counter — useful for tests and telemetry. */\n  attempt: number;\n}\n\n/** Options for {@link SQLWarehouseConnector.ensureWarehouseRunning}. */\ninterface EnsureWarehouseRunningOptions {\n  /** Invoked every time the warehouse state changes during the wait. */\n  onStatus: (update: WarehouseStatusUpdate) => void;\n  /** Aborts the wait. The connector treats abort as `ExecutionError.canceled()`. */\n  signal?: AbortSignal;\n  /** Hard ceiling on the total wait. Defaults to {@link DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS}. */\n  timeoutMs?: number;\n  /**\n   * When `true` (default), a `STOPPED` warehouse is auto-started.\n   * When `false`, `STOPPED` surfaces as `ConfigurationError` immediately —\n   * useful for cost-controlled deployments that don't want any caller to\n   * trigger billable warehouse starts.\n   */\n  autoStart?: boolean;\n}\n\nexport class SQLWarehouseConnector {\n  private readonly name = \"sql-warehouse\";\n\n  private config: SQLWarehouseConfig;\n\n  // Lazy-initialized: only created when Arrow format is used\n  private _arrowProcessor: ArrowStreamProcessor | null = null;\n\n  /**\n   * Per-warehouse cache of the last RUNNING observation timestamp. Used by\n   * {@link ensureWarehouseRunning} to short-circuit warm-path callers; see\n   * {@link WAREHOUSE_RUNNING_CACHE_TTL_MS}.\n   */\n  private _recentlyRunning = new Map<string, number>();\n  // telemetry\n  private readonly telemetry: TelemetryProvider;\n  private readonly telemetryMetrics: {\n    queryCount: Counter;\n    queryDuration: Histogram;\n  };\n\n  constructor(config: SQLWarehouseConfig) {\n    this.config = config;\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      queryCount: this.telemetry.getMeter().createCounter(\"query.count\", {\n        description: \"Total number of queries executed\",\n        unit: \"1\",\n      }),\n      queryDuration: this.telemetry\n        .getMeter()\n        .createHistogram(\"query.duration\", {\n          description: \"Duration of queries executed\",\n          unit: \"ms\",\n        }),\n    };\n  }\n\n  /**\n   * Lazily initializes and returns the ArrowStreamProcessor.\n   * Only created on first Arrow format query to avoid unnecessary allocation.\n   */\n  private get arrowProcessor(): ArrowStreamProcessor {\n    if (!this._arrowProcessor) {\n      this._arrowProcessor = new ArrowStreamProcessor({\n        timeout: this.config.timeout || executeStatementDefaults.timeout,\n        maxConcurrentDownloads:\n          ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,\n        retries: ArrowStreamProcessor.DEFAULT_RETRIES,\n      });\n    }\n    return this._arrowProcessor;\n  }\n\n  async executeStatement(\n    workspaceClient: WorkspaceClient,\n    input: sql.ExecuteStatementRequest,\n    signal?: AbortSignal,\n  ) {\n    const startTime = Date.now();\n    let success = false;\n\n    // if signal is aborted, throw an error\n    if (signal?.aborted) {\n      throw ExecutionError.canceled();\n    }\n\n    return this.telemetry.startActiveSpan(\n      \"sql.query\",\n      {\n        kind: SpanKind.CLIENT,\n        attributes: {\n          \"db.system\": \"databricks\",\n          \"db.warehouse_id\": input.warehouse_id || \"\",\n          \"db.catalog\": input.catalog ?? \"\",\n          \"db.schema\": input.schema ?? \"\",\n          \"db.statement\": input.statement?.substring(0, 500) || \"\",\n          \"db.has_parameters\": !!input.parameters,\n        },\n      },\n      async (span: Span) => {\n        let abortHandler: (() => void) | undefined;\n        let isAborted = false;\n\n        if (signal) {\n          abortHandler = () => {\n            // abort span if not recording\n            if (!span.isRecording()) return;\n            isAborted = true;\n            span.setAttribute(\"cancelled\", true);\n            span.setStatus({\n              code: SpanStatusCode.ERROR,\n              message: \"Query cancelled by client\",\n            });\n            span.end();\n          };\n          signal.addEventListener(\"abort\", abortHandler, { once: true });\n        }\n\n        try {\n          // validate required fields\n          if (!input.statement) {\n            throw ValidationError.missingField(\"statement\");\n          }\n\n          if (!input.warehouse_id) {\n            throw ValidationError.missingField(\"warehouse_id\");\n          }\n\n          const body: sql.ExecuteStatementRequest = {\n            statement: input.statement,\n            parameters: input.parameters,\n            warehouse_id: input.warehouse_id,\n            catalog: input.catalog,\n            schema: input.schema,\n            wait_timeout:\n              input.wait_timeout || executeStatementDefaults.wait_timeout,\n            disposition:\n              input.disposition || executeStatementDefaults.disposition,\n            format: input.format || executeStatementDefaults.format,\n            byte_limit: input.byte_limit,\n            row_limit: input.row_limit,\n            on_wait_timeout:\n              input.on_wait_timeout || executeStatementDefaults.on_wait_timeout,\n          };\n\n          span.addEvent(\"statement.submitting\", {\n            \"db.warehouse_id\": input.warehouse_id,\n          });\n\n          const response =\n            await workspaceClient.statementExecution.executeStatement(\n              body,\n              this._createContext(signal),\n            );\n\n          if (!response) {\n            throw ConnectionError.apiFailure(\"SQL Warehouse\");\n          }\n          const status = response.status;\n          const statementId = response.statement_id as string;\n\n          span.setAttribute(\"db.statement_id\", statementId);\n          span.addEvent(\"statement.submitted\", {\n            \"db.statement_id\": response.statement_id,\n            \"db.status\": status?.state,\n          });\n\n          let result:\n            | sql.StatementResponse\n            | { result: { statement_id: string; status: sql.StatementStatus } };\n\n          switch (status?.state) {\n            case \"RUNNING\":\n            case \"PENDING\":\n              span.addEvent(\"statement.polling_started\", {\n                \"db.status\": response.status?.state,\n              });\n              result = await this._pollForStatementResult(\n                workspaceClient,\n                statementId,\n                this.config.timeout,\n                signal,\n              );\n              break;\n            case \"SUCCEEDED\":\n              result = this._transformDataArray(response);\n              break;\n            case \"FAILED\":\n              throw ExecutionError.statementFailed(status.error?.message);\n            case \"CANCELED\":\n              throw ExecutionError.canceled();\n            case \"CLOSED\":\n              throw ExecutionError.resultsClosed();\n            default:\n              throw ExecutionError.unknownState(\n                String(status?.state ?? \"unknown\"),\n              );\n          }\n\n          const resultData = result.result as any;\n          const rowCount =\n            resultData?.data?.length ?? resultData?.data_array?.length ?? 0;\n\n          if (rowCount > 0) {\n            span.setAttribute(\"db.result.row_count\", rowCount);\n          }\n\n          const duration = Date.now() - startTime;\n          logger.event()?.setContext(\"sql-warehouse\", {\n            warehouse_id: input.warehouse_id,\n            rows_returned: rowCount,\n            query_duration_ms: duration,\n          });\n\n          success = true;\n          // only set success status if not aborted\n          if (!isAborted) {\n            span.setStatus({ code: SpanStatusCode.OK });\n          }\n          return result;\n        } catch (error) {\n          // only record error if not already handled by abort\n          if (!isAborted) {\n            span.recordException(error as Error);\n            span.setStatus({\n              code: SpanStatusCode.ERROR,\n              message: error instanceof Error ? error.message : String(error),\n            });\n\n            logger.error(\n              \"Statement execution failed: %s\",\n              error instanceof Error ? error.message : String(error),\n            );\n          }\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        } finally {\n          // remove abort handler\n          if (abortHandler && signal) {\n            signal.removeEventListener(\"abort\", abortHandler);\n          }\n\n          const duration = Date.now() - startTime;\n\n          // end span if not already ended by abort handler\n          if (!isAborted) {\n            span.end();\n          }\n\n          const attributes = {\n            \"db.warehouse_id\": input.warehouse_id,\n            \"db.catalog\": input.catalog ?? \"\",\n            \"db.schema\": input.schema ?? \"\",\n            \"db.statement\": input.statement?.substring(0, 500) || \"\",\n            success: success.toString(),\n          };\n\n          this.telemetryMetrics.queryCount.add(1, attributes);\n          this.telemetryMetrics.queryDuration.record(duration, attributes);\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  /**\n   * Wait until the SQL warehouse is in the `RUNNING` state, auto-starting it\n   * if currently `STOPPED`. Emits a {@link WarehouseStatusUpdate} whenever\n   * the observed state changes, so callers can surface progress (e.g. over\n   * SSE) instead of letting the UI freeze on a cold warehouse. Equal\n   * successive observations are de-duplicated.\n   *\n   * Fast path: if this connector recently observed the warehouse RUNNING\n   * (within {@link WAREHOUSE_RUNNING_CACHE_TTL_MS}), the call returns\n   * immediately without any SDK round-trip or status emission. This keeps\n   * cache-hit analytics requests off the Databricks control plane.\n   *\n   * Behaviour by initial state:\n   * - `RUNNING`: emits one update, caches the observation, returns.\n   * - `STOPPED`: emits a synthetic `STARTING` update, calls\n   *   `workspaceClient.warehouses.start`, then polls until `RUNNING`.\n   *   When `autoStart: false`, throws `ConfigurationError` instead.\n   * - `STARTING` / `STOPPING`: polls until `RUNNING`.\n   * - `DELETED` / `DELETING`: throws `ConfigurationError.resourceNotFound`.\n   *\n   * Aborts and timeouts surface as `ExecutionError`. The poll loop uses\n   * exponential backoff with ±15% jitter (1s → 30s cap) and runs inside a\n   * `sql.warehouseReady` telemetry span.\n   */\n  async ensureWarehouseRunning(\n    workspaceClient: WorkspaceClient,\n    warehouseId: string,\n    opts: EnsureWarehouseRunningOptions,\n  ): Promise<void> {\n    const {\n      onStatus,\n      signal,\n      timeoutMs = DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS,\n      autoStart = true,\n    } = opts;\n\n    if (signal?.aborted) throw ExecutionError.canceled();\n    if (!warehouseId) throw ValidationError.missingField(\"warehouse_id\");\n    if (this._isRecentlyRunning(warehouseId)) return;\n\n    return this.telemetry.startActiveSpan(\n      \"sql.warehouseReady\",\n      {\n        kind: SpanKind.CLIENT,\n        attributes: {\n          \"db.system\": \"databricks\",\n          \"db.warehouse_id\": warehouseId,\n          \"db.warehouse.startup_timeout_ms\": timeoutMs,\n        },\n      },\n      async (span: Span) => {\n        const startTime = Date.now();\n        const emitter = new WarehouseStatusEmitter(span, startTime, onStatus);\n        let didStart = false;\n        const backoff = new WarehousePollBackoff();\n\n        try {\n          while (true) {\n            if (signal?.aborted) throw ExecutionError.canceled();\n            if (Date.now() - startTime > timeoutMs) {\n              throw ExecutionError.statementFailed(\n                `SQL warehouse did not reach RUNNING within ${timeoutMs}ms`,\n              );\n            }\n\n            const info = await workspaceClient.warehouses.get(\n              { id: warehouseId },\n              this._createContext(signal),\n            );\n            const state = info?.state;\n            const summary = info?.health?.summary;\n\n            switch (state) {\n              case \"RUNNING\":\n                emitter.emit(state, summary);\n                this._recentlyRunning.set(warehouseId, Date.now());\n                span.setAttribute(\"db.warehouse.attempts\", emitter.attempt);\n                span.setStatus({ code: SpanStatusCode.OK });\n                return;\n              case \"DELETED\":\n              case \"DELETING\":\n                throw ConfigurationError.resourceNotFound(\n                  \"Warehouse ID\",\n                  `The configured SQL warehouse is ${state}. Update DATABRICKS_WAREHOUSE_ID to point at an active warehouse.`,\n                );\n              case \"STOPPED\":\n                if (!autoStart) {\n                  // The warehouse exists, it's just in the wrong state and\n                  // policy forbids auto-starting it — use the base\n                  // ConfigurationError directly so the message isn't\n                  // prefixed with \"not found\".\n                  throw new ConfigurationError(\n                    \"The configured SQL warehouse is STOPPED and analytics auto-start is disabled. Start the warehouse manually or set analytics.autoStartWarehouse=true.\",\n                  );\n                }\n                if (!didStart) {\n                  emitter.emit(\"STARTING\", summary);\n                  await workspaceClient.warehouses.start(\n                    { id: warehouseId },\n                    this._createContext(signal),\n                  );\n                  didStart = true;\n                } else {\n                  // Warehouse fell back to STOPPED after our start attempt —\n                  // surface the state and keep polling.\n                  emitter.emit(state, summary);\n                }\n                break;\n              case \"STARTING\":\n              case \"STOPPING\":\n                emitter.emit(state, summary);\n                break;\n              default:\n                throw ExecutionError.unknownState(String(state ?? \"unknown\"));\n            }\n\n            // Preempt the next timeout check: if sleeping the full backoff\n            // would push us past `timeoutMs`, throw now rather than waste\n            // up to ~30s sleeping past the deadline (`backoff.next()` caps\n            // at WAREHOUSE_POLL_MAX_MS).\n            const sleepMs = backoff.next();\n            if (Date.now() + sleepMs - startTime >= timeoutMs) {\n              throw ExecutionError.statementFailed(\n                `SQL warehouse did not reach RUNNING within ${timeoutMs}ms`,\n              );\n            }\n            await this._sleepRespectingAbort(sleepMs, signal);\n          }\n        } catch (error) {\n          this._throwSanitizedReadinessError(error, warehouseId, span);\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  /**\n   * `true` if this connector observed `warehouseId` in the RUNNING state\n   * within the recent-cache TTL.\n   */\n  private _isRecentlyRunning(warehouseId: string): boolean {\n    const observedAt = this._recentlyRunning.get(warehouseId);\n    return (\n      observedAt !== undefined &&\n      Date.now() - observedAt < WAREHOUSE_RUNNING_CACHE_TTL_MS\n    );\n  }\n\n  /**\n   * Final landing for any error thrown by the readiness poll loop. Records\n   * the original on the span and (at debug level) on the logger, then\n   * rethrows either the structured AppKitError unchanged or a curated\n   * ExecutionError — never the raw SDK message, which can contain operator\n   * internals.\n   *\n   * The `logger.debug` covers environments where OTel isn't configured\n   * (common in dev) so the raw error isn't lost just because no span\n   * exporter is hooked up.\n   */\n  private _throwSanitizedReadinessError(\n    error: unknown,\n    warehouseId: string,\n    span: Span,\n  ): never {\n    if (error instanceof AppKitError) {\n      span.recordException(error);\n      span.setStatus({ code: SpanStatusCode.ERROR, message: error.code });\n      throw error;\n    }\n    span.recordException(\n      error instanceof Error ? error : new Error(String(error)),\n    );\n    logger.debug(\n      \"Warehouse readiness check raw error for %s: %O\",\n      warehouseId,\n      error,\n    );\n    const wrapped = ExecutionError.statementFailed(\n      \"Warehouse readiness check failed\",\n    );\n    span.setStatus({ code: SpanStatusCode.ERROR, message: wrapped.code });\n    throw wrapped;\n  }\n\n  /**\n   * Sleep for `ms` milliseconds, but resolve early (and reject with\n   * `ExecutionError.canceled()`) if `signal` aborts mid-sleep. Used by the\n   * warehouse readiness loop so that client disconnects don't keep the loop\n   * polling for the full interval.\n   */\n  private _sleepRespectingAbort(\n    ms: number,\n    signal?: AbortSignal,\n  ): Promise<void> {\n    if (signal?.aborted) return Promise.reject(ExecutionError.canceled());\n    return new Promise<void>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        signal?.removeEventListener(\"abort\", onAbort);\n        resolve();\n      }, ms);\n      const onAbort = () => {\n        clearTimeout(timer);\n        reject(ExecutionError.canceled());\n      };\n      signal?.addEventListener(\"abort\", onAbort, { once: true });\n    });\n  }\n\n  private async _pollForStatementResult(\n    workspaceClient: WorkspaceClient,\n    statementId: string,\n    timeout = executeStatementDefaults.timeout,\n    signal?: AbortSignal,\n  ) {\n    return this.telemetry.startActiveSpan(\n      \"sql.poll\",\n      {\n        attributes: {\n          \"db.statement_id\": statementId,\n          \"db.polling.timeout\": timeout,\n        },\n      },\n      async (span: Span) => {\n        try {\n          const startTime = Date.now();\n          let delay = 1000;\n          const maxDelayBetweenPolls = 5000; // max 5 seconds between polls\n          let pollCount = 0;\n\n          while (true) {\n            pollCount++;\n            span.setAttribute(\"db.polling.current_attempt\", pollCount);\n\n            // check if timeout exceeded\n            const elapsedTime = Date.now() - startTime;\n            if (elapsedTime > timeout) {\n              const error = ExecutionError.statementFailed(\n                `Polling timeout exceeded after ${timeout}ms (elapsed: ${elapsedTime}ms)`,\n              );\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            }\n\n            if (signal?.aborted) {\n              const error = ExecutionError.canceled();\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            }\n\n            span.addEvent(\"polling.attempt\", {\n              \"poll.attempt\": pollCount,\n              \"poll.delay_ms\": delay,\n              \"poll.elapsed_ms\": elapsedTime,\n            });\n\n            const response =\n              await workspaceClient.statementExecution.getStatement(\n                {\n                  statement_id: statementId,\n                },\n                this._createContext(signal),\n              );\n            if (!response) {\n              throw ConnectionError.apiFailure(\"SQL Warehouse\");\n            }\n\n            const status = response.status;\n\n            span.addEvent(\"polling.status_check\", {\n              \"db.status\": status?.state,\n              \"poll.attempt\": pollCount,\n            });\n\n            switch (status?.state) {\n              case \"PENDING\":\n              case \"RUNNING\":\n                // continue polling\n                break;\n              case \"SUCCEEDED\":\n                span.setAttribute(\"db.polling.attempts\", pollCount);\n                span.setAttribute(\"db.polling.total_duration_ms\", elapsedTime);\n                span.addEvent(\"polling.completed\", {\n                  \"poll.attempts\": pollCount,\n                  \"poll.duration_ms\": elapsedTime,\n                });\n                span.setStatus({ code: SpanStatusCode.OK });\n                return this._transformDataArray(response);\n              case \"FAILED\":\n                throw ExecutionError.statementFailed(status.error?.message);\n              case \"CANCELED\":\n                throw ExecutionError.canceled();\n              case \"CLOSED\":\n                throw ExecutionError.resultsClosed();\n              default:\n                throw ExecutionError.unknownState(\n                  String(status?.state ?? \"unknown\"),\n                );\n            }\n\n            // continue polling after delay\n            await new Promise((resolve) => setTimeout(resolve, delay));\n            delay = Math.min(delay * 2, maxDelayBetweenPolls);\n          }\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({\n            code: SpanStatusCode.ERROR,\n            message: error instanceof Error ? error.message : String(error),\n          });\n\n          // error logging is handled by executeStatement's catch block (gated on isAborted)\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  private _transformDataArray(response: sql.StatementResponse) {\n    if (response.manifest?.format === \"ARROW_STREAM\") {\n      return this.updateWithArrowStatus(response);\n    }\n\n    if (!response.result?.data_array || !response.manifest?.schema?.columns) {\n      return response;\n    }\n\n    const columns = response.manifest.schema.columns;\n\n    const transformedData = response.result.data_array.map((row) => {\n      const obj: Record<string, unknown> = {};\n      row.forEach((value, index) => {\n        const column = columns[index];\n        const columnName = column?.name || `column_${index}`;\n\n        // attempt to parse JSON strings for string columns\n        if (\n          column?.type_name === \"STRING\" &&\n          typeof value === \"string\" &&\n          value &&\n          (value[0] === \"{\" || value[0] === \"[\")\n        ) {\n          try {\n            obj[columnName] = JSON.parse(value);\n          } catch {\n            // if parsing fails, keep as string\n            obj[columnName] = value;\n          }\n        } else {\n          obj[columnName] = value;\n        }\n      });\n      return obj;\n    });\n\n    // remove data_array\n    const { data_array: _data_array, ...restResult } = response.result;\n    return {\n      ...response,\n      result: {\n        ...restResult,\n        data: transformedData,\n      },\n    };\n  }\n\n  private updateWithArrowStatus(response: sql.StatementResponse): {\n    result: { statement_id: string; status: sql.StatementStatus };\n  } {\n    return {\n      result: {\n        statement_id: response.statement_id as string,\n        status: {\n          state: response.status?.state,\n          error: response.status?.error,\n        } as sql.StatementStatus,\n      },\n    };\n  }\n\n  async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.arrowProcessor.processChunks>> {\n    const startTime = Date.now();\n\n    return this.telemetry.startActiveSpan(\n      \"arrow.getData\",\n      {\n        kind: SpanKind.CLIENT,\n        attributes: {\n          \"db.system\": \"databricks\",\n          \"arrow.job_id\": jobId,\n        },\n      },\n      async (span: Span) => {\n        try {\n          const response =\n            await workspaceClient.statementExecution.getStatement(\n              { statement_id: jobId },\n              this._createContext(signal),\n            );\n\n          const chunks = response.result?.external_links;\n          const schema = response.manifest?.schema;\n\n          if (!chunks || !schema) {\n            throw ExecutionError.missingData(\"chunks or schema\");\n          }\n\n          span.setAttribute(\"arrow.chunk_count\", chunks.length);\n\n          const result = await this.arrowProcessor.processChunks(\n            chunks,\n            schema,\n            signal,\n          );\n\n          span.setAttribute(\"arrow.data_size_bytes\", result.data.length);\n          span.setStatus({ code: SpanStatusCode.OK });\n\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryDuration.record(duration, {\n            operation: \"arrow.getData\",\n            status: \"success\",\n          });\n\n          logger.event()?.setContext(\"sql-warehouse\", {\n            arrow_data_size_bytes: result.data.length,\n            arrow_job_id: jobId,\n          });\n\n          return result;\n        } catch (error) {\n          span.setStatus({\n            code: SpanStatusCode.ERROR,\n            message: error instanceof Error ? error.message : \"Unknown error\",\n          });\n          span.recordException(error as Error);\n\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryDuration.record(duration, {\n            operation: \"arrow.getData\",\n            status: \"error\",\n          });\n\n          logger.error(\"Failed Arrow job: %s %O\", jobId, error);\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ExecutionError.statementFailed(\n            error instanceof Error ? error.message : String(error),\n          );\n        }\n      },\n    );\n  }\n\n  // create context for cancellation token\n  private _createContext(signal?: AbortSignal) {\n    return new Context({\n      cancellationToken: {\n        isCancellationRequested: signal?.aborted ?? false,\n        onCancellationRequested: (cb: () => void) => {\n          signal?.addEventListener(\"abort\", cb, { once: true });\n        },\n      },\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/connectors/sql-warehouse/index.js

@@ -1,3 +1,3 @@
-import { SQLWarehouseConnector } from "./client.js";
+import { DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS, SQLWarehouseConnector } from "./client.js";
 
 export {  };

package/dist/connectors/sql-warehouse/warehouse-poll-backoff.js

@@ -0,0 +1,24 @@
+//#region src/connectors/sql-warehouse/warehouse-poll-backoff.ts
+const WAREHOUSE_POLL_INITIAL_MS = 1e3;
+const WAREHOUSE_POLL_MAX_MS = 3e4;
+/**
+* Stateful exponential backoff for the warehouse readiness poll loop. Each
+* `next()` returns the next sleep duration with ±15% jitter applied, then
+* doubles the underlying interval up to {@link WAREHOUSE_POLL_MAX_MS}.
+*
+* Jitter spreads retries across concurrent waiters; the cap (30s) prevents
+* pathological starvation when a warehouse takes minutes to come up.
+*/
+var WarehousePollBackoff = class {
+	intervalMs = WAREHOUSE_POLL_INITIAL_MS;
+	/** Returns the next sleep duration in ms; advances internal state. */
+	next() {
+		const sleep = this.intervalMs * (.85 + Math.random() * .3);
+		this.intervalMs = Math.min(WAREHOUSE_POLL_MAX_MS, this.intervalMs * 2);
+		return sleep;
+	}
+};
+
+//#endregion
+export { WarehousePollBackoff };
+//# sourceMappingURL=warehouse-poll-backoff.js.map

package/dist/connectors/sql-warehouse/warehouse-poll-backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warehouse-poll-backoff.js","names":[],"sources":["../../../src/connectors/sql-warehouse/warehouse-poll-backoff.ts"],"sourcesContent":["const WAREHOUSE_POLL_INITIAL_MS = 1_000;\nconst WAREHOUSE_POLL_MAX_MS = 30_000;\n\n/**\n * Stateful exponential backoff for the warehouse readiness poll loop. Each\n * `next()` returns the next sleep duration with ±15% jitter applied, then\n * doubles the underlying interval up to {@link WAREHOUSE_POLL_MAX_MS}.\n *\n * Jitter spreads retries across concurrent waiters; the cap (30s) prevents\n * pathological starvation when a warehouse takes minutes to come up.\n */\nexport class WarehousePollBackoff {\n  private intervalMs = WAREHOUSE_POLL_INITIAL_MS;\n\n  /** Returns the next sleep duration in ms; advances internal state. */\n  next(): number {\n    const sleep = this.intervalMs * (0.85 + Math.random() * 0.3);\n    this.intervalMs = Math.min(WAREHOUSE_POLL_MAX_MS, this.intervalMs * 2);\n    return sleep;\n  }\n}\n"],"mappings":";AAAA,MAAM,4BAA4B;AAClC,MAAM,wBAAwB;;;;;;;;;AAU9B,IAAa,uBAAb,MAAkC;CAChC,AAAQ,aAAa;;CAGrB,OAAe;EACb,MAAM,QAAQ,KAAK,cAAc,MAAO,KAAK,QAAQ,GAAG;AACxD,OAAK,aAAa,KAAK,IAAI,uBAAuB,KAAK,aAAa,EAAE;AACtE,SAAO"}

package/dist/connectors/sql-warehouse/warehouse-status-emitter.js

@@ -0,0 +1,40 @@
+//#region src/connectors/sql-warehouse/warehouse-status-emitter.ts
+/**
+* Tracks state-change emissions for the warehouse readiness loop. Records
+* every poll on the OTel span and forwards real state changes (with de-dup)
+* to the route's `onStatus` callback. The raw SDK `health.summary` is
+* recorded on the span only — never on the wire.
+*/
+var WarehouseStatusEmitter = class {
+	attempt = 0;
+	lastEmittedState = null;
+	constructor(span, startTime, onStatus) {
+		this.span = span;
+		this.startTime = startTime;
+		this.onStatus = onStatus;
+	}
+	emit(state, summary) {
+		this.attempt += 1;
+		this.span.addEvent("warehouse.status", {
+			"db.warehouse.state": state,
+			"db.warehouse.attempt": this.attempt,
+			"db.warehouse.elapsed_ms": Date.now() - this.startTime,
+			...summary ? { "db.warehouse.summary": summary } : {}
+		});
+		if (state === this.lastEmittedState) return;
+		this.lastEmittedState = state;
+		try {
+			this.onStatus({
+				state,
+				elapsedMs: Date.now() - this.startTime,
+				attempt: this.attempt
+			});
+		} catch (err) {
+			this.span.addEvent("warehouse.onStatus.error", { "exception.message": err instanceof Error ? err.message : String(err) });
+		}
+	}
+};
+
+//#endregion
+export { WarehouseStatusEmitter };
+//# sourceMappingURL=warehouse-status-emitter.js.map

package/dist/connectors/sql-warehouse/warehouse-status-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warehouse-status-emitter.js","names":[],"sources":["../../../src/connectors/sql-warehouse/warehouse-status-emitter.ts"],"sourcesContent":["import type { sql } from \"@databricks/sdk-experimental\";\nimport type { Span } from \"../../telemetry\";\nimport type { WarehouseStatusUpdate } from \"./client\";\n\n/**\n * Tracks state-change emissions for the warehouse readiness loop. Records\n * every poll on the OTel span and forwards real state changes (with de-dup)\n * to the route's `onStatus` callback. The raw SDK `health.summary` is\n * recorded on the span only — never on the wire.\n */\nexport class WarehouseStatusEmitter {\n  attempt = 0;\n  private lastEmittedState: sql.State | null = null;\n\n  constructor(\n    private readonly span: Span,\n    private readonly startTime: number,\n    private readonly onStatus: (update: WarehouseStatusUpdate) => void,\n  ) {}\n\n  emit(state: sql.State, summary: string | undefined): void {\n    this.attempt += 1;\n    this.span.addEvent(\"warehouse.status\", {\n      \"db.warehouse.state\": state,\n      \"db.warehouse.attempt\": this.attempt,\n      \"db.warehouse.elapsed_ms\": Date.now() - this.startTime,\n      ...(summary ? { \"db.warehouse.summary\": summary } : {}),\n    });\n    if (state === this.lastEmittedState) return;\n    this.lastEmittedState = state;\n    try {\n      this.onStatus({\n        state,\n        elapsedMs: Date.now() - this.startTime,\n        attempt: this.attempt,\n      });\n    } catch (err) {\n      this.span.addEvent(\"warehouse.onStatus.error\", {\n        \"exception.message\": err instanceof Error ? err.message : String(err),\n      });\n    }\n  }\n}\n"],"mappings":";;;;;;;AAUA,IAAa,yBAAb,MAAoC;CAClC,UAAU;CACV,AAAQ,mBAAqC;CAE7C,YACE,AAAiB,MACjB,AAAiB,WACjB,AAAiB,UACjB;EAHiB;EACA;EACA;;CAGnB,KAAK,OAAkB,SAAmC;AACxD,OAAK,WAAW;AAChB,OAAK,KAAK,SAAS,oBAAoB;GACrC,sBAAsB;GACtB,wBAAwB,KAAK;GAC7B,2BAA2B,KAAK,KAAK,GAAG,KAAK;GAC7C,GAAI,UAAU,EAAE,wBAAwB,SAAS,GAAG,EAAE;GACvD,CAAC;AACF,MAAI,UAAU,KAAK,iBAAkB;AACrC,OAAK,mBAAmB;AACxB,MAAI;AACF,QAAK,SAAS;IACZ;IACA,WAAW,KAAK,KAAK,GAAG,KAAK;IAC7B,SAAS,KAAK;IACf,CAAC;WACK,KAAK;AACZ,QAAK,KAAK,SAAS,4BAA4B,EAC7C,qBAAqB,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,EACtE,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;;;;cAmCa,eAAA,SAAwB,MAAA,YAAkB,YAAA;;SAE9C,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EAtBV;;;;EAkDL,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA1CiB;;;;EAgFd,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAFI;;;;;;;;;;;;;;;EAgHD,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EAmEO;;;EAAA,UA3CM,YAAA,CACd,eAAA,EAAiB,eAAA,EACjB,KAAA,UACA,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,UAAA,aAAuB,SAAA,CAAU,YAAA;EAItC,QAAA,CAAA,GAAY,OAAA;EAAA,QAIV,KAAA;EAuBR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EApRgC;;;;;;;EA+RnC,OAAA,CAAQ,IAAA,GAXE,cAAA,GAWoD,MAAA,SAAA,YAAA;EA3R7C;;;;EAmSjB,OAAA,CAAA;;;;2BA1Fe,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAmGQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}
+{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;;;;cA0Fa,eAAA,SAAwB,MAAA,YAAkB,YAAA;;SAE9C,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EAtBV;;;;EAkDL,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA1CiB;;;;EAgFd,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAFI;;;;;;;;;;;;;;;EAwKD,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EAmEO;;;EAAA,UA3CM,YAAA,CACd,eAAA,EAAiB,eAAA,EACjB,KAAA,UACA,MAAA,GAAS,WAAA,GACR,OAAA,CAAQ,UAAA,aAAuB,SAAA,CAAU,YAAA;EAItC,QAAA,CAAA,GAAY,OAAA;EAAA,QAIV,KAAA;EAuBR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EA5UgC;;;;;;;EAuVnC,OAAA,CAAQ,IAAA,GAXE,cAAA,GAWoD,MAAA,SAAA,YAAA;EAnV7C;;;;EA2VjB,OAAA,CAAA;;;;2BA1Fe,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAmGQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}

package/dist/plugins/analytics/analytics.js

@@ -1,10 +1,12 @@
 import { createLogger } from "../../logging/logger.js";
+import { ExecutionError } from "../../errors/execution.js";
+import "../../errors/index.js";
 import { getWarehouseId, getWorkspaceClient } from "../../context/execution-context.js";
 import "../../context/index.js";
 import { Plugin } from "../../plugin/plugin.js";
 import { toPlugin } from "../../plugin/to-plugin.js";
 import "../../plugin/index.js";
-import { SQLWarehouseConnector } from "../../connectors/sql-warehouse/client.js";
+import { DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS, SQLWarehouseConnector } from "../../connectors/sql-warehouse/client.js";
 import "../../connectors/index.js";
 import { buildToolkitEntries } from "../../core/agent/build-toolkit.js";
 import { defineTool, executeFromRegistry, toolsFromRegistry } from "../../core/agent/tools/define-tool.js";
@@ -17,6 +19,43 @@ import { z } from "zod";
 
 //#region src/plugins/analytics/analytics.ts
 const logger = createLogger("analytics");
+/**
+* Bridges a callback-emitting async function into an async iterable.
+*
+* `start(emit)` runs concurrently; every value passed to `emit` is yielded
+* in order. The iterable completes when `start`'s promise resolves and
+* re-throws (after draining) if it rejects. Lets a callback-based progress
+* API (e.g. SQL warehouse readiness) be consumed with `for await`.
+*/
+async function* streamCallbacks(start) {
+	const queue = [];
+	let wake = null;
+	let settled = false;
+	let error = null;
+	const notify = () => {
+		wake?.();
+		wake = null;
+	};
+	start((value) => {
+		queue.push(value);
+		notify();
+	}).then(() => {
+		settled = true;
+		notify();
+	}, (err) => {
+		error = err;
+		settled = true;
+		notify();
+	});
+	while (!settled || queue.length > 0) {
+		while (queue.length > 0) yield queue.shift();
+		if (settled) break;
+		await new Promise((resolve) => {
+			wake = resolve;
+		});
+	}
+	if (error) throw error;
+}
 var AnalyticsPlugin = class extends Plugin {
 	/** Plugin manifest declaring metadata and resource requirements */
 	static manifest = manifest_default;
@@ -112,7 +151,7 @@ var AnalyticsPlugin = class extends Plugin {
 			type: "arrow"
 		} : { type: "result" };
 		const hashedQuery = this.queryProcessor.hashQuery(query);
-		const streamExecutionSettings = { default: {
+		const sqlConfig = {
 			...queryDefaults,
 			cache: {
 				...queryDefaults.cache,
@@ -125,14 +164,40 @@ var AnalyticsPlugin = class extends Plugin {
 					executorKey
 				]
 			}
+		};
+		const streamExecutionSettings = { default: {
+			cache: { enabled: false },
+			retry: { enabled: false }
 		} };
-		await executor.executeStream(res, async (signal) => {
-			const processedParams = await this.queryProcessor.processQueryParams(query, parameters);
-			const result = await executor.query(query, processedParams, queryParameters.formatParameters, signal);
-			return {
-				type: queryParameters.type,
-				...result
+		const startupTimeoutMs = this.config.warehouseStartupTimeoutMs ?? DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS;
+		const autoStartWarehouse = this.config.autoStartWarehouse ?? true;
+		const self = this;
+		await executor.executeStream(res, async function* (signal) {
+			const workspaceClient = getWorkspaceClient();
+			const warehouseId = await getWarehouseId();
+			const readinessUpdates = streamCallbacks((emit) => self.SQLClient.ensureWarehouseRunning(workspaceClient, warehouseId, {
+				signal,
+				timeoutMs: startupTimeoutMs,
+				autoStart: autoStartWarehouse,
+				onStatus: emit
+			}));
+			for await (const update of readinessUpdates) yield {
+				type: "warehouse_status",
+				status: {
+					state: update.state,
+					elapsedMs: update.elapsedMs
+				}
 			};
+			const sqlResult = await executor.execute(async (sig) => {
+				const processedParams = await self.queryProcessor.processQueryParams(query, parameters);
+				const result = await executor.query(query, processedParams, queryParameters.formatParameters, sig);
+				return {
+					type: queryParameters.type,
+					...result
+				};
+			}, { default: sqlConfig }, executorKey);
+			if (!sqlResult.ok) throw ExecutionError.statementFailed(sqlResult.message);
+			yield sqlResult.data;
 		}, streamExecutionSettings, executorKey);
 	}
 	/**

package/dist/plugins/analytics/analytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.js","names":["manifest"],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n  ToolProvider,\n} from \"shared\";\nimport { z } from \"zod\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport { getWarehouseId, getWorkspaceClient } from \"../../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 { queryDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\nimport { normalizeAnalyticsFormat } from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\nexport class AnalyticsPlugin extends Plugin implements ToolProvider {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"analytics\">;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Arrow data downloads always run as service principal and bypass the\n    // interceptor chain (execute/executeStream). The original query execution\n    // handles OBO via executeStream(); this endpoint fetches pre-computed\n    // results by job ID.\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format: rawFormat = \"JSON_ARRAY\" } =\n      req.body as IAnalyticsQueryRequest;\n    const format = normalizeAnalyticsFormat(rawFormat);\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const executorKey = isAsUser ? this.resolveUserId(req) : \"global\";\n\n    const queryParameters =\n      format === \"ARROW_STREAM\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await executor.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await executor.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  private tools = {\n    query: defineTool({\n      description:\n        \"Execute a read-only SQL query against the Databricks SQL warehouse. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted; writes are rejected. Returns the query results as JSON.\",\n      schema: z.object({\n        query: z\n          .string()\n          .describe(\n            \"The SQL query to execute. Must be a SELECT, WITH, SHOW, EXPLAIN, or DESCRIBE statement.\",\n          ),\n      }),\n      annotations: {\n        effect: \"read\",\n        requiresUserContext: true,\n      },\n      autoInheritable: true,\n      execute: (args, signal) => {\n        assertReadOnlySql(args.query);\n        return this.query(args.query, undefined, undefined, signal);\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  /**\n   * Returns the plugin's tools as a keyed record of `ToolkitEntry` markers.\n   * Called by the agents plugin (via `resolveToolkitFromProvider`) to spread\n   * a filtered, renamed view of the plugin's tools into an agent's tool\n   * index. Inside the function form of `AgentDefinition.tools`, callers\n   * reach this method via `plugins.analytics.toolkit(opts)`.\n   */\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin(AnalyticsPlugin);\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiCA,MAAM,SAAS,aAAa,YAAY;AAExC,IAAa,kBAAb,cAAqC,OAA+B;;CAElE,OAAO,WAAWA;CAElB,OAAiB,cAAc;CAI/B,AAAQ;CACR,AAAQ;CAER,YAAY,QAA0B;AACpC,QAAM,OAAO;AACb,OAAK,SAAS;AACd,OAAK,iBAAiB,IAAI,gBAAgB;AAE1C,OAAK,YAAY,IAAI,sBAAsB;GACzC,SAAS,OAAO;GAChB,WAAW,OAAO;GACnB,CAAC;;CAGJ,aAAa,QAAoB;AAK/B,OAAK,MAAM,QAAQ;GACjB,MAAM;GACN,QAAQ;GACR,MAAM;GACN,SAAS,OAAO,KAAsB,QAA0B;AAC9D,UAAM,KAAK,kBAAkB,KAAK,IAAI;;GAEzC,CAAC;AAEF,OAAK,MAA8B,QAAQ;GACzC,MAAM;GACN,QAAQ;GACR,MAAM;GACN,SAAS,OAAO,KAAsB,QAA0B;AAC9D,UAAM,KAAK,kBAAkB,KAAK,IAAI;;GAEzC,CAAC;;;;;;CAOJ,MAAM,kBACJ,KACA,KACe;AACf,MAAI;GACF,MAAM,EAAE,UAAU,IAAI;GACtB,MAAM,kBAAkB,oBAAoB;AAE5C,UAAO,MAAM,6CAA6C,MAAM;AAGhE,GADc,OAAO,MAAM,IAAI,EACxB,aAAa,aAAa,eAAe,CAAC,WAAW,aAAa;IACvE,QAAQ;IACR,QAAQ,KAAK;IACd,CAAC;GAEF,MAAM,SAAS,MAAM,KAAK,aAAa,iBAAiB,MAAM;AAE9D,OAAI,UAAU,gBAAgB,2BAA2B;AACzD,OAAI,UAAU,kBAAkB,OAAO,KAAK,OAAO,UAAU,CAAC;AAC9D,OAAI,UAAU,iBAAiB,uBAAuB;AAEtD,UAAO,MACL,6CACA,OAAO,KAAK,QACZ,MACD;AACD,OAAI,KAAK,OAAO,KAAK,OAAO,KAAK,CAAC;WAC3B,OAAO;AACd,UAAO,MAAM,uBAAuB,MAAM;AAC1C,OAAI,OAAO,IAAI,CAAC,KAAK;IACnB,OAAO,iBAAiB,QAAQ,MAAM,UAAU;IAChD,QAAQ,KAAK;IACd,CAAC;;;;;;;CAQN,MAAM,kBACJ,KACA,KACe;EACf,MAAM,EAAE,cAAc,IAAI;EAC1B,MAAM,EAAE,YAAY,QAAQ,YAAY,iBACtC,IAAI;EACN,MAAM,SAAS,yBAAyB,UAAU;AAGlD,SAAO,MAAM,KAAK,mCAAmC,WAAW,OAAO;AAGvE,EADc,OAAO,MAAM,IAAI,EACxB,aAAa,aAAa,eAAe,CAAC,WAAW,aAAa;GACvE;GACA;GACA,iBAAiB,aAAa,OAAO,KAAK,WAAW,CAAC,SAAS;GAC/D,QAAQ,KAAK;GACd,CAAC;AAEF,MAAI,CAAC,WAAW;AACd,OAAI,OAAO,IAAI,CAAC,KAAK,EAAE,OAAO,yBAAyB,CAAC;AACxD;;EAGF,MAAM,cAAc,MAAM,KAAK,IAAI,YACjC,WACA,KACA,KAAK,cACN;AAED,MAAI,CAAC,aAAa;AAChB,OAAI,OAAO,IAAI,CAAC,KAAK,EAAE,OAAO,mBAAmB,CAAC;AAClD;;EAGF,MAAM,EAAE,OAAO,aAAa;EAG5B,MAAM,WAAW,WAAW,KAAK,OAAO,IAAI,GAAG;EAC/C,MAAM,cAAc,WAAW,KAAK,cAAc,IAAI,GAAG;EAEzD,MAAM,kBACJ,WAAW,iBACP;GACE,kBAAkB;IAChB,aAAa;IACb,QAAQ;IACT;GACD,MAAM;GACP,GACD,EACE,MAAM,UACP;EAEP,MAAM,cAAc,KAAK,eAAe,UAAU,MAAM;EAiBxD,MAAM,0BAAmD,EACvD,SAhByC;GACzC,GAAG;GACH,OAAO;IACL,GAAG,cAAc;IACjB,UAAU;KACR;KACA;KACA,KAAK,UAAU,WAAW;KAC1B,KAAK,UAAU,OAAO;KACtB;KACA;KACD;IACF;GACF,EAIA;AAED,QAAM,SAAS,cACb,KACA,OAAO,WAAW;GAChB,MAAM,kBAAkB,MAAM,KAAK,eAAe,mBAChD,OACA,WACD;GAED,MAAM,SAAS,MAAM,SAAS,MAC5B,OACA,iBACA,gBAAgB,kBAChB,OACD;AAED,UAAO;IAAE,MAAM,gBAAgB;IAAM,GAAG;IAAQ;KAElD,yBACA,YACD;;;;;;;;;;;;;;;;;CAkBH,MAAM,MACJ,OACA,YACA,kBACA,QACc;EACd,MAAM,kBAAkB,oBAAoB;EAC5C,MAAM,cAAc,MAAM,gBAAgB;EAE1C,MAAM,EAAE,WAAW,YAAY,kBAC7B,KAAK,eAAe,uBAAuB,OAAO,WAAW;AAa/D,UAXiB,MAAM,KAAK,UAAU,iBACpC,iBACA;GACE;GACA,cAAc;GACd,YAAY;GACZ,GAAG;GACJ,EACD,OACD,EAEe;;;;;CAMlB,MAAgB,aACd,iBACA,OACA,QACyD;AACzD,SAAO,MAAM,KAAK,UAAU,aAAa,iBAAiB,OAAO,OAAO;;CAG1E,MAAM,WAA0B;AAC9B,OAAK,cAAc,UAAU;;CAG/B,AAAQ,QAAQ,EACd,OAAO,WAAW;EAChB,aACE;EACF,QAAQ,EAAE,OAAO,EACf,OAAO,EACJ,QAAQ,CACR,SACC,0FACD,EACJ,CAAC;EACF,aAAa;GACX,QAAQ;GACR,qBAAqB;GACtB;EACD,iBAAiB;EACjB,UAAU,MAAM,WAAW;AACzB,qBAAkB,KAAK,MAAM;AAC7B,UAAO,KAAK,MAAM,KAAK,OAAO,QAAW,QAAW,OAAO;;EAE9D,CAAC,EACH;CAED,gBAAuC;AACrC,SAAO,kBAAkB,KAAK,MAAM;;CAGtC,MAAM,iBACJ,MACA,MACA,QACkB;AAClB,SAAO,oBAAoB,KAAK,OAAO,MAAM,MAAM,OAAO;;;;;;;;;CAU5D,QAAQ,MAAwD;AAC9D,SAAO,oBAAoB,KAAK,MAAM,KAAK,OAAO,KAAK;;;;;;CAOzD,UAAU;AACR,SAAO,EAIL,OAAO,KAAK,OACb;;;;;;AAOL,MAAa,YAAY,SAAS,gBAAgB"}
+{"version":3,"file":"analytics.js","names":["manifest"],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n  ToolProvider,\n} from \"shared\";\nimport { z } from \"zod\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport {\n  DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS,\n  type WarehouseStatusUpdate,\n} from \"../../connectors/sql-warehouse/client\";\nimport { getWarehouseId, getWorkspaceClient } from \"../../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 { ExecutionError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest } from \"../../registry\";\nimport { queryDefaults } from \"./defaults\";\nimport manifest from \"./manifest.json\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  AnalyticsStreamMessage,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n  WarehouseStatus,\n} from \"./types\";\nimport { normalizeAnalyticsFormat } from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\n/**\n * Bridges a callback-emitting async function into an async iterable.\n *\n * `start(emit)` runs concurrently; every value passed to `emit` is yielded\n * in order. The iterable completes when `start`'s promise resolves and\n * re-throws (after draining) if it rejects. Lets a callback-based progress\n * API (e.g. SQL warehouse readiness) be consumed with `for await`.\n */\nasync function* streamCallbacks<T>(\n  start: (emit: (value: T) => void) => Promise<void>,\n): AsyncGenerator<T, void, unknown> {\n  const queue: T[] = [];\n  let wake: (() => void) | null = null;\n  let settled = false;\n  let error: unknown = null;\n\n  const notify = (): void => {\n    wake?.();\n    wake = null;\n  };\n\n  // The .then(_, err => ...) chain converts a rejection into a resolved\n  // promise; the consumer surfaces `error` after draining the queue.\n  void start((value) => {\n    queue.push(value);\n    notify();\n  }).then(\n    () => {\n      settled = true;\n      notify();\n    },\n    (err) => {\n      error = err;\n      settled = true;\n      notify();\n    },\n  );\n\n  while (!settled || queue.length > 0) {\n    while (queue.length > 0) yield queue.shift() as T;\n    if (settled) break;\n    await new Promise<void>((resolve) => {\n      wake = resolve;\n    });\n  }\n  if (error) throw error;\n}\n\nexport class AnalyticsPlugin extends Plugin implements ToolProvider {\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = manifest as PluginManifest<\"analytics\">;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Arrow data downloads always run as service principal and bypass the\n    // interceptor chain (execute/executeStream). The original query execution\n    // handles OBO via executeStream(); this endpoint fetches pre-computed\n    // results by job ID.\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format: rawFormat = \"JSON_ARRAY\" } =\n      req.body as IAnalyticsQueryRequest;\n    const format = normalizeAnalyticsFormat(rawFormat);\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const executorKey = isAsUser ? this.resolveUserId(req) : \"global\";\n\n    const queryParameters =\n      format === \"ARROW_STREAM\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\" as const,\n          }\n        : {\n            type: \"result\" as const,\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    // Cache/retry/timeout are scoped to the SQL execution itself (inner\n    // `execute`) so the warehouse-readiness phase isn't subject to retries\n    // and the generator value never leaks into the cache.\n    const sqlConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    // Outer stream: no cache/retry — `executeStream` would otherwise wrap the\n    // generator factory and cache the generator object itself. Telemetry +\n    // user-scoped trace context still apply.\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: {\n        cache: { enabled: false },\n        retry: { enabled: false },\n      },\n    };\n\n    const startupTimeoutMs =\n      this.config.warehouseStartupTimeoutMs ??\n      DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS;\n    const autoStartWarehouse = this.config.autoStartWarehouse ?? true;\n\n    const self = this;\n\n    await executor.executeStream(\n      res,\n      async function* (\n        signal,\n      ): AsyncGenerator<AnalyticsStreamMessage, void, unknown> {\n        const workspaceClient = getWorkspaceClient();\n        const warehouseId = await getWarehouseId();\n\n        // Stream warehouse-readiness updates as SSE events, then run SQL.\n        const readinessUpdates = streamCallbacks<WarehouseStatusUpdate>(\n          (emit) =>\n            self.SQLClient.ensureWarehouseRunning(\n              workspaceClient,\n              warehouseId,\n              {\n                signal,\n                timeoutMs: startupTimeoutMs,\n                autoStart: autoStartWarehouse,\n                onStatus: emit,\n              },\n            ),\n        );\n        for await (const update of readinessUpdates) {\n          yield {\n            type: \"warehouse_status\",\n            status: {\n              state: update.state as WarehouseStatus[\"state\"],\n              elapsedMs: update.elapsedMs,\n            },\n          };\n        }\n\n        const sqlResult = await executor.execute(\n          async (sig) => {\n            const processedParams =\n              await self.queryProcessor.processQueryParams(query, parameters);\n            const result = await executor.query(\n              query,\n              processedParams,\n              queryParameters.formatParameters,\n              sig,\n            );\n            return { type: queryParameters.type, ...result };\n          },\n          { default: sqlConfig },\n          executorKey,\n        );\n\n        if (!sqlResult.ok) {\n          // Surface a typed AppKitError so StreamManager can categorize via\n          // the structured `code`. The HTTP status code from `execute()`\n          // doesn't apply to SSE error frames.\n          throw ExecutionError.statementFailed(sqlResult.message);\n        }\n\n        yield sqlResult.data as AnalyticsStreamMessage;\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  private tools = {\n    query: defineTool({\n      description:\n        \"Execute a read-only SQL query against the Databricks SQL warehouse. Only SELECT, WITH, SHOW, EXPLAIN, and DESCRIBE statements are accepted; writes are rejected. Returns the query results as JSON.\",\n      schema: z.object({\n        query: z\n          .string()\n          .describe(\n            \"The SQL query to execute. Must be a SELECT, WITH, SHOW, EXPLAIN, or DESCRIBE statement.\",\n          ),\n      }),\n      annotations: {\n        effect: \"read\",\n        requiresUserContext: true,\n      },\n      autoInheritable: true,\n      execute: (args, signal) => {\n        assertReadOnlySql(args.query);\n        return this.query(args.query, undefined, undefined, signal);\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  /**\n   * Returns the plugin's tools as a keyed record of `ToolkitEntry` markers.\n   * Called by the agents plugin (via `resolveToolkitFromProvider`) to spread\n   * a filtered, renamed view of the plugin's tools into an agent's tool\n   * index. Inside the function form of `AgentDefinition.tools`, callers\n   * reach this method via `plugins.analytics.toolkit(opts)`.\n   */\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin(AnalyticsPlugin);\n"],"mappings":"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"}

package/dist/plugins/analytics/manifest.js

@@ -28,11 +28,23 @@ var manifest_default = {
 	} },
 	config: { "schema": {
 		"type": "object",
-		"properties": { "timeout": {
-			"type": "number",
-			"default": 3e4,
-			"description": "Query execution timeout in milliseconds"
-		} }
+		"properties": {
+			"timeout": {
+				"type": "number",
+				"default": 3e4,
+				"description": "Query execution timeout in milliseconds"
+			},
+			"warehouseStartupTimeoutMs": {
+				"type": "number",
+				"default": 3e5,
+				"description": "Maximum time (ms) to wait for a STOPPED/STARTING SQL warehouse to reach RUNNING before failing the request"
+			},
+			"autoStartWarehouse": {
+				"type": "boolean",
+				"default": true,
+				"description": "When true, a STOPPED SQL warehouse is auto-started on the first analytics request. Set to false for cost-controlled deployments where billable warehouse starts must not be triggered by user requests."
+			}
+		}
 	} }
 };
 

package/dist/plugins/analytics/types.d.ts

@@ -4,6 +4,19 @@ import "../../shared/src/index.js";
 //#region src/plugins/analytics/types.d.ts
 interface IAnalyticsConfig extends BasePluginConfig {
   timeout?: number;
+  /**
+   * Maximum time (ms) the analytics route waits for a STOPPED/STARTING SQL
+   * warehouse to reach RUNNING before failing the request. Defaults to 5 min.
+   */
+  warehouseStartupTimeoutMs?: number;
+  /**
+   * When `true` (default), a `STOPPED` SQL warehouse is auto-started on the
+   * first analytics request that reaches it. Set to `false` for cost-
+   * controlled deployments where billable warehouse starts must not be
+   * triggered by user requests; in that case `STOPPED` surfaces as a
+   * `ConfigurationError`.
+   */
+  autoStartWarehouse?: boolean;
 }
 //#endregion
 export { IAnalyticsConfig };

package/dist/plugins/analytics/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/analytics/types.ts"],"mappings":";;;;UAEiB,gBAAA,SAAyB,gBAAA;EACxC,OAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/analytics/types.ts"],"mappings":";;;;UAEiB,gBAAA,SAAyB,gBAAA;EACxC,OAAA;;AADF;;;EAME,yBAAA;EANwC;;;;;;;EAcxC,kBAAA;AAAA"}

package/dist/plugins/analytics/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/plugins/analytics/types.ts"],"sourcesContent":["import type { BasePluginConfig } from \"shared\";\n\nexport interface IAnalyticsConfig extends BasePluginConfig {\n  timeout?: number;\n}\n\n/**\n * Supported response formats for analytics queries.\n *\n * \"JSON\" and \"ARROW\" are legacy aliases kept for backwards compatibility\n * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on\n * a pre-0.33.0 version. The route handler normalizes them to their\n * canonical equivalents before any downstream code reads the value.\n */\nexport type AnalyticsFormat =\n  | \"JSON_ARRAY\"\n  | \"ARROW_STREAM\"\n  /** @deprecated Use \"JSON_ARRAY\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"JSON\"\n  /** @deprecated Use \"ARROW_STREAM\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"ARROW\";\n\n/** Canonical (post-normalization) analytics format values. */\ntype CanonicalAnalyticsFormat = \"JSON_ARRAY\" | \"ARROW_STREAM\";\n\n/**\n * Map a (possibly legacy) AnalyticsFormat to its canonical form.\n * Legacy values come from appkit/appkit-ui < 0.33.0 and can be removed\n * along with the deprecated aliases once no such consumer remains.\n */\nexport function normalizeAnalyticsFormat(\n  f: AnalyticsFormat,\n): CanonicalAnalyticsFormat {\n  if (f === \"JSON\") return \"JSON_ARRAY\";\n  if (f === \"ARROW\") return \"ARROW_STREAM\";\n  return f;\n}\n\nexport interface IAnalyticsQueryRequest {\n  parameters?: Record<string, any>;\n  format?: AnalyticsFormat;\n}\n\nexport interface AnalyticsQueryResponse {\n  chunk_index: number;\n  row_offset: number;\n  row_count: number;\n  data: any[];\n}\n"],"mappings":";;;;;;AA8BA,SAAgB,yBACd,GAC0B;AAC1B,KAAI,MAAM,OAAQ,QAAO;AACzB,KAAI,MAAM,QAAS,QAAO;AAC1B,QAAO"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/plugins/analytics/types.ts"],"sourcesContent":["import type { BasePluginConfig } from \"shared\";\n\nexport interface IAnalyticsConfig extends BasePluginConfig {\n  timeout?: number;\n  /**\n   * Maximum time (ms) the analytics route waits for a STOPPED/STARTING SQL\n   * warehouse to reach RUNNING before failing the request. Defaults to 5 min.\n   */\n  warehouseStartupTimeoutMs?: number;\n  /**\n   * When `true` (default), a `STOPPED` SQL warehouse is auto-started on the\n   * first analytics request that reaches it. Set to `false` for cost-\n   * controlled deployments where billable warehouse starts must not be\n   * triggered by user requests; in that case `STOPPED` surfaces as a\n   * `ConfigurationError`.\n   */\n  autoStartWarehouse?: boolean;\n}\n\n/**\n * SQL warehouse lifecycle states surfaced by the analytics route.\n * Mirrors the states emitted by the Databricks SQL SDK (`sql.State`).\n */\nexport type WarehouseState =\n  | \"RUNNING\"\n  | \"STARTING\"\n  | \"STOPPED\"\n  | \"STOPPING\"\n  | \"DELETED\"\n  | \"DELETING\";\n\n/**\n * Snapshot of warehouse readiness streamed to the client over SSE before the\n * SQL result. Lets the UI render a \"warehouse starting…\" affordance instead\n * of a frozen spinner during cold starts.\n *\n * Note: the SDK's `health.summary` is intentionally NOT forwarded here. It's\n * free-form operator-oriented diagnostic text (cluster IDs, capacity-failure\n * reasons, internal RPC errors) that must not reach end users; it stays in\n * server-side telemetry only.\n */\nexport interface WarehouseStatus {\n  state: WarehouseState;\n  /** Milliseconds elapsed since the route began waiting for the warehouse. */\n  elapsedMs: number;\n}\n\n/**\n * Discriminated union of every SSE message shape emitted by\n * `POST /api/analytics/query/:query_key`. Useful for typing the client-side\n * `onMessage` handler (and is the source of truth re-mirrored in\n * `appkit-ui` since that package can't depend on `appkit`).\n */\nexport type AnalyticsStreamMessage =\n  | { type: \"warehouse_status\"; status: WarehouseStatus }\n  | { type: \"result\"; data: unknown[] }\n  | {\n      type: \"arrow\";\n      statement_id: string;\n      status: { state: string };\n    }\n  | { type: \"error\"; error: string; code?: string };\n\n/**\n * Supported response formats for analytics queries.\n *\n * \"JSON\" and \"ARROW\" are legacy aliases kept for backwards compatibility\n * with appkit/appkit-ui < 0.33.0 — safe to remove once no consumer is on\n * a pre-0.33.0 version. The route handler normalizes them to their\n * canonical equivalents before any downstream code reads the value.\n */\nexport type AnalyticsFormat =\n  | \"JSON_ARRAY\"\n  | \"ARROW_STREAM\"\n  /** @deprecated Use \"JSON_ARRAY\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"JSON\"\n  /** @deprecated Use \"ARROW_STREAM\". Safe to remove once no consumer is on appkit < 0.33.0. */\n  | \"ARROW\";\n\n/** Canonical (post-normalization) analytics format values. */\ntype CanonicalAnalyticsFormat = \"JSON_ARRAY\" | \"ARROW_STREAM\";\n\n/**\n * Map a (possibly legacy) AnalyticsFormat to its canonical form.\n * Legacy values come from appkit/appkit-ui < 0.33.0 and can be removed\n * along with the deprecated aliases once no such consumer remains.\n */\nexport function normalizeAnalyticsFormat(\n  f: AnalyticsFormat,\n): CanonicalAnalyticsFormat {\n  if (f === \"JSON\") return \"JSON_ARRAY\";\n  if (f === \"ARROW\") return \"ARROW_STREAM\";\n  return f;\n}\n\nexport interface IAnalyticsQueryRequest {\n  parameters?: Record<string, any>;\n  format?: AnalyticsFormat;\n}\n\nexport interface AnalyticsQueryResponse {\n  chunk_index: number;\n  row_offset: number;\n  row_count: number;\n  data: any[];\n}\n"],"mappings":";;;;;;AAuFA,SAAgB,yBACd,GAC0B;AAC1B,KAAI,MAAM,OAAQ,QAAO;AACzB,KAAI,MAAM,QAAS,QAAO;AAC1B,QAAO"}