@fabric-harness/databricks 5.2.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -2267,6 +2267,39 @@ function jitter(ms) {
2267
2267
  return Math.max(1, Math.round(ms * (0.9 + Math.random() * 0.2)));
2268
2268
  }
2269
2269
 
2270
+ // src/resource-policy.ts
2271
+ var DatabricksResourceNotAllowedError = class extends Error {
2272
+ code = "DATABRICKS_RESOURCE_NOT_ALLOWED";
2273
+ resourceKind;
2274
+ constructor(resourceKind) {
2275
+ super(`Databricks ${resourceKind} is not allowed by the configured policy.`);
2276
+ this.name = "DatabricksResourceNotAllowedError";
2277
+ this.resourceKind = resourceKind;
2278
+ }
2279
+ };
2280
+ function resolveExactResourcePolicy(policy, allowedKey, allowAnyKey, resourceKind) {
2281
+ if (!policy || typeof policy !== "object" || Array.isArray(policy))
2282
+ throw new TypeError(`Databricks ${resourceKind} policy must be an object.`);
2283
+ const value = policy;
2284
+ const allowed = value[allowedKey];
2285
+ const allowAny = value[allowAnyKey];
2286
+ if (allowAny === true && allowed === void 0) return void 0;
2287
+ if (Array.isArray(allowed) && allowed.length > 0 && allowed.every((entry) => typeof entry === "string" && entry.trim().length > 0) && allowAny === void 0)
2288
+ return [...new Set(allowed.map((entry) => entry.trim()))];
2289
+ throw new TypeError(
2290
+ `Databricks ${resourceKind} policy must set either non-empty ${allowedKey} or ${allowAnyKey}: true.`
2291
+ );
2292
+ }
2293
+ function assertExactResourceAllowed(resourceKind, value, allowed) {
2294
+ if (allowed && !allowed.includes(value.trim()))
2295
+ throw new DatabricksResourceNotAllowedError(resourceKind);
2296
+ }
2297
+ function pinnedStringResourceSchema(allowed) {
2298
+ if (!allowed) return { type: "string" };
2299
+ if (allowed.length === 1) return { type: "string", const: allowed[0] };
2300
+ return { type: "string", enum: [...allowed] };
2301
+ }
2302
+
2270
2303
  // src/sql-exec.ts
2271
2304
  var TERMINAL_STATES = /* @__PURE__ */ new Set(["SUCCEEDED", "FAILED", "CANCELED", "CLOSED"]);
2272
2305
  async function runStatement(client, warehouseId, statement, parameters, poll) {
@@ -2303,25 +2336,53 @@ function parseStatementRows(response) {
2303
2336
  }
2304
2337
 
2305
2338
  // src/ai.ts
2306
- function databricksAiQueryTool(client, options) {
2307
- const poll = { intervalMs: options.pollIntervalMs ?? 2e3, timeoutMs: options.timeoutMs ?? 12e4 };
2339
+ function databricksAiQueryTool(client, endpointPolicy, options) {
2340
+ const poll = {
2341
+ intervalMs: options.pollIntervalMs ?? 2e3,
2342
+ timeoutMs: options.timeoutMs ?? 12e4
2343
+ };
2344
+ const allowedEndpoints = resolveExactResourcePolicy(
2345
+ endpointPolicy,
2346
+ "allowedEndpoints",
2347
+ "allowAnyEndpoint",
2348
+ "AI Functions endpoint"
2349
+ );
2308
2350
  return {
2309
2351
  name: options.name ?? "databricks_ai_query",
2310
2352
  description: options.description ?? "Run model inference inside the SQL warehouse via ai_query() against a Databricks serving endpoint.",
2311
2353
  inputSchema: {
2312
2354
  type: "object",
2313
2355
  additionalProperties: false,
2314
- properties: { endpoint: { type: "string" }, request: { type: "string" } },
2356
+ properties: {
2357
+ endpoint: pinnedStringResourceSchema(allowedEndpoints),
2358
+ request: { type: "string" }
2359
+ },
2315
2360
  required: ["endpoint", "request"]
2316
2361
  },
2317
- metadata: { effect: "execute", provider: "databricks", service: "ai-functions" },
2318
- execute: (input) => runStatement(
2319
- client,
2320
- options.warehouseId,
2321
- "SELECT ai_query(:endpoint, :request) AS result",
2322
- [{ name: "endpoint", value: input.endpoint }, { name: "request", value: input.request }],
2323
- poll
2324
- )
2362
+ metadata: {
2363
+ effect: "execute",
2364
+ provider: "databricks",
2365
+ service: "ai-functions",
2366
+ governance: {
2367
+ resources: [
2368
+ { kind: "serving-endpoint", path: "/endpoint" },
2369
+ { kind: "sql-warehouse", value: options.warehouseId }
2370
+ ]
2371
+ }
2372
+ },
2373
+ async execute(input) {
2374
+ assertExactResourceAllowed("AI Functions endpoint", input.endpoint, allowedEndpoints);
2375
+ return await runStatement(
2376
+ client,
2377
+ options.warehouseId,
2378
+ "SELECT ai_query(:endpoint, :request) AS result",
2379
+ [
2380
+ { name: "endpoint", value: input.endpoint },
2381
+ { name: "request", value: input.request }
2382
+ ],
2383
+ poll
2384
+ );
2385
+ }
2325
2386
  };
2326
2387
  }
2327
2388
 
@@ -22364,43 +22425,76 @@ function databricksPipelineStatusTool(client, options = {}) {
22364
22425
  execute: (input) => client.get({ pipelineId: input.pipelineId })
22365
22426
  };
22366
22427
  }
22367
- function databricksPipelineStartTool(client, options = {}) {
22428
+ function databricksPipelineStartTool(client, runPolicy, options = {}) {
22429
+ const allowedPipelineIds = resolveExactResourcePolicy(
22430
+ runPolicy,
22431
+ "allowedPipelineIds",
22432
+ "allowAnyPipelineId",
22433
+ "Lakeflow pipeline"
22434
+ );
22368
22435
  return {
22369
22436
  name: options.name ?? "databricks_pipeline_start",
22370
22437
  description: options.description ?? "Trigger a Lakeflow pipeline update (run). Set fullRefresh to reprocess all data.",
22371
22438
  inputSchema: {
22372
22439
  type: "object",
22373
22440
  additionalProperties: false,
22374
- properties: { pipelineId: { type: "string" }, fullRefresh: { type: "boolean" } },
22441
+ properties: {
22442
+ pipelineId: pinnedStringResourceSchema(allowedPipelineIds),
22443
+ fullRefresh: { type: "boolean" }
22444
+ },
22375
22445
  required: ["pipelineId"]
22376
22446
  },
22377
- metadata: { effect: "execute", provider: "databricks", service: "lakeflow" },
22378
- execute: (input) => client.start({
22379
- pipelineId: input.pipelineId,
22380
- ...input.fullRefresh !== void 0 ? { fullRefresh: input.fullRefresh } : {}
22381
- })
22447
+ metadata: {
22448
+ effect: "execute",
22449
+ provider: "databricks",
22450
+ service: "lakeflow",
22451
+ governance: { resources: [{ kind: "pipeline", path: "/pipelineId" }] }
22452
+ },
22453
+ async execute(input) {
22454
+ assertExactResourceAllowed("Lakeflow pipeline", input.pipelineId, allowedPipelineIds);
22455
+ return await client.start({
22456
+ pipelineId: input.pipelineId,
22457
+ ...input.fullRefresh !== void 0 ? { fullRefresh: input.fullRefresh } : {}
22458
+ });
22459
+ }
22382
22460
  };
22383
22461
  }
22384
- function databricksPipelineStopTool(client, options = {}) {
22462
+ function databricksPipelineStopTool(client, runPolicy, options = {}) {
22463
+ const allowedPipelineIds = resolveExactResourcePolicy(
22464
+ runPolicy,
22465
+ "allowedPipelineIds",
22466
+ "allowAnyPipelineId",
22467
+ "Lakeflow pipeline"
22468
+ );
22385
22469
  return {
22386
22470
  name: options.name ?? "databricks_pipeline_stop",
22387
22471
  description: options.description ?? "Stop the active update of a Lakeflow pipeline.",
22388
22472
  inputSchema: {
22389
22473
  type: "object",
22390
22474
  additionalProperties: false,
22391
- properties: { pipelineId: { type: "string" } },
22475
+ properties: { pipelineId: pinnedStringResourceSchema(allowedPipelineIds) },
22392
22476
  required: ["pipelineId"]
22393
22477
  },
22394
- metadata: { effect: "execute", provider: "databricks", service: "lakeflow" },
22395
- execute: (input) => client.stop({ pipelineId: input.pipelineId })
22478
+ metadata: {
22479
+ effect: "execute",
22480
+ provider: "databricks",
22481
+ service: "lakeflow",
22482
+ governance: { resources: [{ kind: "pipeline", path: "/pipelineId" }] }
22483
+ },
22484
+ async execute(input) {
22485
+ assertExactResourceAllowed("Lakeflow pipeline", input.pipelineId, allowedPipelineIds);
22486
+ return await client.stop({ pipelineId: input.pipelineId });
22487
+ }
22396
22488
  };
22397
22489
  }
22398
- function databricksLakeflowTools(client) {
22490
+ function databricksLakeflowTools(client, runPolicy) {
22399
22491
  return [
22400
22492
  databricksPipelineListTool(client),
22401
22493
  databricksPipelineStatusTool(client),
22402
- databricksPipelineStartTool(client),
22403
- databricksPipelineStopTool(client)
22494
+ ...runPolicy ? [
22495
+ databricksPipelineStartTool(client, runPolicy),
22496
+ databricksPipelineStopTool(client, runPolicy)
22497
+ ] : []
22404
22498
  ];
22405
22499
  }
22406
22500
 
@@ -58939,12 +59033,71 @@ var DatabricksRunTimeoutError = class extends Error {
58939
59033
  this.runId = runId;
58940
59034
  }
58941
59035
  };
59036
+ var DatabricksRunNotAllowedError = class extends Error {
59037
+ constructor(message) {
59038
+ super(message);
59039
+ this.name = "DatabricksRunNotAllowedError";
59040
+ }
59041
+ };
59042
+ function validateDatabricksJobRunPolicy(policy) {
59043
+ if (policy.allowAnyJobId === true) return;
59044
+ const ids = policy.allowedJobIds;
59045
+ if (!Array.isArray(ids) || ids.length === 0)
59046
+ throw new Error("databricks jobs: runPolicy.allowedJobIds must be non-empty when configured.");
59047
+ for (const id of ids)
59048
+ if (!Number.isSafeInteger(id) || id < 0)
59049
+ throw new Error(
59050
+ "databricks jobs: runPolicy.allowedJobIds must contain non-negative integer job ids."
59051
+ );
59052
+ }
59053
+ function validateDatabricksNotebookRunPolicy(policy) {
59054
+ if (policy.allowAnyNotebookPath === true) return;
59055
+ const paths = policy.allowedNotebookPaths ?? [];
59056
+ const prefixes = policy.allowedNotebookPathPrefixes ?? [];
59057
+ if (paths.length === 0 && prefixes.length === 0)
59058
+ throw new Error(
59059
+ "databricks jobs: notebookPolicy must configure a non-empty allowedNotebookPaths or allowedNotebookPathPrefixes."
59060
+ );
59061
+ for (const [name, values] of [
59062
+ ["allowedNotebookPaths", paths],
59063
+ ["allowedNotebookPathPrefixes", prefixes]
59064
+ ]) {
59065
+ for (const value of values) {
59066
+ if (typeof value !== "string" || !value.startsWith("/"))
59067
+ throw new Error(
59068
+ `databricks jobs: notebookPolicy.${name} entries must be absolute workspace paths.`
59069
+ );
59070
+ if (hasParentSegment(value))
59071
+ throw new Error(
59072
+ `databricks jobs: notebookPolicy.${name} entries cannot contain a ".." segment.`
59073
+ );
59074
+ }
59075
+ }
59076
+ }
59077
+ function hasParentSegment(path4) {
59078
+ return path4.split("/").includes("..");
59079
+ }
59080
+ function notebookPathAllowed(policy, path4) {
59081
+ if (policy.allowedNotebookPaths?.includes(path4)) return true;
59082
+ return (policy.allowedNotebookPathPrefixes ?? []).some((prefix) => {
59083
+ const normalized = prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
59084
+ return normalized === path4 || path4.startsWith(`${normalized}/`);
59085
+ });
59086
+ }
58942
59087
  var DatabricksJobs = class {
58943
- constructor(client) {
59088
+ constructor(client, options = {}) {
58944
59089
  this.client = client;
59090
+ if (options.runPolicy !== void 0) validateDatabricksJobRunPolicy(options.runPolicy);
59091
+ if (options.notebookPolicy !== void 0)
59092
+ validateDatabricksNotebookRunPolicy(options.notebookPolicy);
59093
+ this.runPolicy = options.runPolicy;
59094
+ this.notebookPolicy = options.notebookPolicy;
58945
59095
  }
58946
59096
  client;
59097
+ runPolicy;
59098
+ notebookPolicy;
58947
59099
  async runJob(input) {
59100
+ this.assertJobAllowed(input.jobId);
58948
59101
  const idempotencyToken = input.idempotencyToken ?? crypto.randomUUID();
58949
59102
  const request = {
58950
59103
  jobId: BigInt(input.jobId),
@@ -58957,6 +59110,7 @@ var DatabricksJobs = class {
58957
59110
  return receipt(waiter.runId, void 0, idempotencyToken, "job");
58958
59111
  }
58959
59112
  async submitNotebook(input) {
59113
+ this.assertNotebookAllowed(input.notebookPath);
58960
59114
  const idempotencyToken = input.idempotencyToken ?? crypto.randomUUID();
58961
59115
  const request = {
58962
59116
  idempotencyToken,
@@ -59029,9 +59183,27 @@ var DatabricksJobs = class {
59029
59183
  await store.put({ scope, ref, bytes });
59030
59184
  return ref;
59031
59185
  }
59186
+ /** Bound checked before `runNow`, so an out-of-policy id never reaches the workspace. */
59187
+ assertJobAllowed(jobId2) {
59188
+ const policy = this.runPolicy;
59189
+ if (!policy || policy.allowAnyJobId === true) return;
59190
+ if (!(policy.allowedJobIds ?? []).includes(jobId2))
59191
+ throw new DatabricksRunNotAllowedError(
59192
+ `databricks jobs: job ${jobId2} is not in the configured run allowlist.`
59193
+ );
59194
+ }
59195
+ /** Bound checked before `submitRun`, so an out-of-policy notebook is never executed. */
59196
+ assertNotebookAllowed(notebookPath) {
59197
+ const policy = this.notebookPolicy;
59198
+ if (!policy || policy.allowAnyNotebookPath === true) return;
59199
+ if (hasParentSegment(notebookPath) || !notebookPathAllowed(policy, notebookPath))
59200
+ throw new DatabricksRunNotAllowedError(
59201
+ `databricks jobs: notebook path ${JSON.stringify(notebookPath)} is not in the configured run allowlist.`
59202
+ );
59203
+ }
59032
59204
  };
59033
- function databricksJobs(client) {
59034
- return new DatabricksJobs(client);
59205
+ function databricksJobs(client, options) {
59206
+ return new DatabricksJobs(client, options);
59035
59207
  }
59036
59208
  function receipt(runIdValue, numberInJobValue, idempotencyToken, kind) {
59037
59209
  if (runIdValue === void 0)
@@ -59227,7 +59399,8 @@ function lexSqlReadStatement(statement) {
59227
59399
  function assertDatabricksSqlReadStatement(statement) {
59228
59400
  if (!statement.trim()) throw new Error("Databricks SQL read denied: statement cannot be empty.");
59229
59401
  const { tokens, semicolons } = lexSqlReadStatement(statement);
59230
- if (tokens.length === 0) throw new Error("Databricks SQL read denied: expected a SELECT statement.");
59402
+ if (tokens.length === 0)
59403
+ throw new Error("Databricks SQL read denied: expected a SELECT statement.");
59231
59404
  if (semicolons.length > 1)
59232
59405
  throw new Error("Databricks SQL read denied: multiple statements are not allowed.");
59233
59406
  if (semicolons.length === 1) {
@@ -59245,7 +59418,8 @@ function assertDatabricksSqlReadStatement(statement) {
59245
59418
  if (unsafe)
59246
59419
  throw new Error(`Databricks SQL read denied: unsafe keyword ${unsafe.value} is not allowed.`);
59247
59420
  }
59248
- function databricksSqlTool(client, options) {
59421
+ function databricksSqlTool(client, policy, options) {
59422
+ const executionPolicy = resolveSqlExecutionPolicy(policy);
59249
59423
  return {
59250
59424
  name: options.name ?? "databricks_sql",
59251
59425
  description: options.description ?? "Run a SQL statement on a Databricks SQL Warehouse.",
@@ -59253,23 +59427,55 @@ function databricksSqlTool(client, options) {
59253
59427
  type: "object",
59254
59428
  additionalProperties: false,
59255
59429
  properties: {
59256
- statement: { type: "string" },
59430
+ statement: executionPolicy.kind === "allowlist" ? pinnedStringResourceSchema(executionPolicy.statements) : { type: "string" },
59257
59431
  catalog: { type: "string" },
59258
59432
  schema: { type: "string" }
59259
59433
  },
59260
59434
  required: ["statement"]
59261
59435
  },
59262
- metadata: { effect: "execute", provider: "databricks", service: "sql" },
59263
- execute: (input) => client.executeStatement({
59264
- warehouseId: options.warehouseId,
59265
- statement: input.statement,
59266
- waitTimeout: options.waitTimeout ?? "30s",
59267
- disposition: options.disposition ?? "INLINE",
59268
- ...input.catalog ? { catalog: input.catalog } : {},
59269
- ...input.schema ? { schema: input.schema } : {}
59270
- })
59436
+ metadata: {
59437
+ effect: "execute",
59438
+ provider: "databricks",
59439
+ service: "sql",
59440
+ governance: {
59441
+ resources: [{ kind: "sql-warehouse", value: options.warehouseId }]
59442
+ }
59443
+ },
59444
+ async execute(input) {
59445
+ await assertSqlExecutionAllowed(input, executionPolicy);
59446
+ return await client.executeStatement({
59447
+ warehouseId: options.warehouseId,
59448
+ statement: input.statement,
59449
+ waitTimeout: options.waitTimeout ?? "30s",
59450
+ disposition: options.disposition ?? "INLINE",
59451
+ ...input.catalog ? { catalog: input.catalog } : {},
59452
+ ...input.schema ? { schema: input.schema } : {}
59453
+ });
59454
+ }
59271
59455
  };
59272
59456
  }
59457
+ function resolveSqlExecutionPolicy(policy) {
59458
+ if (!policy || typeof policy !== "object" || Array.isArray(policy))
59459
+ throw new TypeError("Databricks SQL execution policy must be an object.");
59460
+ if ("validateStatement" in policy && typeof policy.validateStatement === "function")
59461
+ return { kind: "validator", validate: policy.validateStatement };
59462
+ const statements = resolveExactResourcePolicy(
59463
+ policy,
59464
+ "allowedStatements",
59465
+ "allowAnyStatement",
59466
+ "SQL statement"
59467
+ );
59468
+ return statements ? { kind: "allowlist", statements } : { kind: "allow-any" };
59469
+ }
59470
+ async function assertSqlExecutionAllowed(input, policy) {
59471
+ if (policy.kind === "allow-any") return;
59472
+ if (policy.kind === "allowlist") {
59473
+ assertExactResourceAllowed("SQL statement", input.statement, policy.statements);
59474
+ return;
59475
+ }
59476
+ if (await policy.validate(input) !== true)
59477
+ throw new DatabricksResourceNotAllowedError("SQL statement");
59478
+ }
59273
59479
  function databricksSqlReadTool(client, options) {
59274
59480
  return {
59275
59481
  name: options.name ?? "sql_read",
@@ -59289,9 +59495,7 @@ function databricksSqlReadTool(client, options) {
59289
59495
  provider: "databricks",
59290
59496
  service: "sql",
59291
59497
  governance: {
59292
- resources: [
59293
- { kind: "catalog", path: "/catalog", catalogQualified: true, optional: true }
59294
- ]
59498
+ resources: [{ kind: "catalog", path: "/catalog", catalogQualified: true, optional: true }]
59295
59499
  }
59296
59500
  },
59297
59501
  async execute(input) {
@@ -59307,7 +59511,8 @@ function databricksSqlReadTool(client, options) {
59307
59511
  }
59308
59512
  };
59309
59513
  }
59310
- function databricksRunJobTool(client, options = {}) {
59514
+ function databricksRunJobTool(client, runPolicy, options = {}) {
59515
+ const jobs = databricksJobs(client, { runPolicy });
59311
59516
  return {
59312
59517
  name: options.name ?? "databricks_run_job",
59313
59518
  description: options.description ?? "Trigger an existing Databricks job by job id.",
@@ -59315,7 +59520,7 @@ function databricksRunJobTool(client, options = {}) {
59315
59520
  type: "object",
59316
59521
  additionalProperties: false,
59317
59522
  properties: {
59318
- jobId: { type: "number" },
59523
+ jobId: pinnedJobIdSchema(runPolicy),
59319
59524
  idempotencyToken: { type: "string" },
59320
59525
  notebookParams: { type: "object", additionalProperties: true },
59321
59526
  pythonParams: { type: "array", items: { type: "string" } },
@@ -59323,11 +59528,26 @@ function databricksRunJobTool(client, options = {}) {
59323
59528
  },
59324
59529
  required: ["jobId"]
59325
59530
  },
59326
- metadata: { effect: "execute", provider: "databricks", service: "jobs" },
59327
- execute: (input) => databricksJobs(client).runJob(input)
59531
+ metadata: {
59532
+ effect: "execute",
59533
+ provider: "databricks",
59534
+ service: "jobs",
59535
+ governance: { resources: [{ kind: "job", path: "/jobId" }] }
59536
+ },
59537
+ execute: (input, context) => jobs.runJob({
59538
+ ...input,
59539
+ ...input.idempotencyToken ? {} : context?.toolCallId ? { idempotencyToken: context.toolCallId } : {}
59540
+ })
59328
59541
  };
59329
59542
  }
59330
- function databricksNotebookTool(client, options = {}) {
59543
+ function pinnedJobIdSchema(policy) {
59544
+ const ids = policy.allowAnyJobId === true ? [] : policy.allowedJobIds ?? [];
59545
+ if (ids.length === 1) return { type: "number", const: ids[0] };
59546
+ if (ids.length > 1) return { type: "number", enum: ids };
59547
+ return { type: "number" };
59548
+ }
59549
+ function databricksNotebookTool(client, notebookPolicy, options = {}) {
59550
+ const jobs = databricksJobs(client, { notebookPolicy });
59331
59551
  return {
59332
59552
  name: options.name ?? "databricks_run_notebook",
59333
59553
  description: options.description ?? "Submit a one-off Databricks notebook run.",
@@ -59335,21 +59555,40 @@ function databricksNotebookTool(client, options = {}) {
59335
59555
  type: "object",
59336
59556
  additionalProperties: false,
59337
59557
  properties: {
59338
- notebookPath: { type: "string" },
59558
+ notebookPath: pinnedNotebookPathSchema(notebookPolicy),
59339
59559
  idempotencyToken: { type: "string" },
59340
59560
  baseParameters: { type: "object", additionalProperties: true },
59341
59561
  runName: { type: "string" }
59342
59562
  },
59343
59563
  required: ["notebookPath"]
59344
59564
  },
59345
- metadata: { effect: "execute", provider: "databricks", service: "jobs" },
59346
- execute: (input) => databricksJobs(client).submitNotebook({
59565
+ metadata: {
59566
+ effect: "execute",
59567
+ provider: "databricks",
59568
+ service: "jobs",
59569
+ governance: { resources: [{ kind: "notebook", path: "/notebookPath" }] }
59570
+ },
59571
+ execute: (input, context) => jobs.submitNotebook({
59347
59572
  ...input,
59573
+ ...input.idempotencyToken ? {} : context?.toolCallId ? { idempotencyToken: context.toolCallId } : {},
59348
59574
  ...options.existingClusterId ? { existingClusterId: options.existingClusterId } : {}
59349
59575
  })
59350
59576
  };
59351
59577
  }
59352
- function databricksMlflowLogMetricTool(client, options = {}) {
59578
+ function pinnedNotebookPathSchema(policy) {
59579
+ if (policy.allowAnyNotebookPath === true) return { type: "string" };
59580
+ const paths = policy.allowedNotebookPaths ?? [];
59581
+ if (paths.length > 0 && (policy.allowedNotebookPathPrefixes ?? []).length === 0)
59582
+ return { type: "string", enum: paths };
59583
+ return { type: "string" };
59584
+ }
59585
+ function databricksMlflowLogMetricTool(client, runPolicy, options = {}) {
59586
+ const allowedRunIds = resolveExactResourcePolicy(
59587
+ runPolicy,
59588
+ "allowedRunIds",
59589
+ "allowAnyRunId",
59590
+ "MLflow run"
59591
+ );
59353
59592
  return {
59354
59593
  name: options.name ?? "databricks_mlflow_log_metric",
59355
59594
  description: options.description ?? "Log a metric to an MLflow run hosted in Databricks.",
@@ -59357,7 +59596,7 @@ function databricksMlflowLogMetricTool(client, options = {}) {
59357
59596
  type: "object",
59358
59597
  additionalProperties: false,
59359
59598
  properties: {
59360
- runId: { type: "string" },
59599
+ runId: pinnedStringResourceSchema(allowedRunIds),
59361
59600
  key: { type: "string" },
59362
59601
  value: { type: "number" },
59363
59602
  step: { type: "number" },
@@ -59365,32 +59604,58 @@ function databricksMlflowLogMetricTool(client, options = {}) {
59365
59604
  },
59366
59605
  required: ["runId", "key", "value"]
59367
59606
  },
59368
- metadata: { effect: "write", provider: "databricks", service: "mlflow" },
59369
- execute: (input) => retryIdempotent(
59370
- () => client.logMetric({
59371
- runId: input.runId,
59372
- key: input.key,
59373
- value: input.value,
59374
- timestamp: BigInt(input.timestamp ?? Date.now()),
59375
- ...input.step !== void 0 ? { step: BigInt(input.step) } : {}
59376
- })
59377
- )
59607
+ metadata: {
59608
+ effect: "write",
59609
+ provider: "databricks",
59610
+ service: "mlflow",
59611
+ governance: { resources: [{ kind: "mlflow-run", path: "/runId" }] }
59612
+ },
59613
+ async execute(input) {
59614
+ assertExactResourceAllowed("MLflow run", input.runId, allowedRunIds);
59615
+ return await retryIdempotent(
59616
+ () => client.logMetric({
59617
+ runId: input.runId,
59618
+ key: input.key,
59619
+ value: input.value,
59620
+ timestamp: BigInt(input.timestamp ?? Date.now()),
59621
+ ...input.step !== void 0 ? { step: BigInt(input.step) } : {}
59622
+ })
59623
+ );
59624
+ }
59378
59625
  };
59379
59626
  }
59380
- function databricksMlflowLogParamTool(client, options = {}) {
59627
+ function databricksMlflowLogParamTool(client, runPolicy, options = {}) {
59628
+ const allowedRunIds = resolveExactResourcePolicy(
59629
+ runPolicy,
59630
+ "allowedRunIds",
59631
+ "allowAnyRunId",
59632
+ "MLflow run"
59633
+ );
59381
59634
  return {
59382
59635
  name: options.name ?? "databricks_mlflow_log_param",
59383
59636
  description: options.description ?? "Log a parameter to an MLflow run hosted in Databricks.",
59384
59637
  inputSchema: {
59385
59638
  type: "object",
59386
59639
  additionalProperties: false,
59387
- properties: { runId: { type: "string" }, key: { type: "string" }, value: { type: "string" } },
59640
+ properties: {
59641
+ runId: pinnedStringResourceSchema(allowedRunIds),
59642
+ key: { type: "string" },
59643
+ value: { type: "string" }
59644
+ },
59388
59645
  required: ["runId", "key", "value"]
59389
59646
  },
59390
- metadata: { effect: "write", provider: "databricks", service: "mlflow" },
59391
- execute: (input) => retryIdempotent(
59392
- () => client.logParam({ runId: input.runId, key: input.key, value: input.value })
59393
- )
59647
+ metadata: {
59648
+ effect: "write",
59649
+ provider: "databricks",
59650
+ service: "mlflow",
59651
+ governance: { resources: [{ kind: "mlflow-run", path: "/runId" }] }
59652
+ },
59653
+ async execute(input) {
59654
+ assertExactResourceAllowed("MLflow run", input.runId, allowedRunIds);
59655
+ return await retryIdempotent(
59656
+ () => client.logParam({ runId: input.runId, key: input.key, value: input.value })
59657
+ );
59658
+ }
59394
59659
  };
59395
59660
  }
59396
59661
  async function retryIdempotent(call, attempts = 3) {
@@ -60051,6 +60316,7 @@ function databricksPersistence(options) {
60051
60316
  let sessionStore;
60052
60317
  let submissionStore;
60053
60318
  let conversationStreamStore;
60319
+ let schedulerLeaseStore;
60054
60320
  const persistence = {
60055
60321
  client,
60056
60322
  async connect() {
@@ -60068,6 +60334,11 @@ function databricksPersistence(options) {
60068
60334
  conversationStreamStore ??= new module.PostgresConversationStreamStore({ client });
60069
60335
  return conversationStreamStore;
60070
60336
  },
60337
+ async connectSchedulerLeaseStore() {
60338
+ const module = await stores();
60339
+ schedulerLeaseStore ??= module.postgresSchedulerLeaseStore?.(client);
60340
+ return schedulerLeaseStore;
60341
+ },
60071
60342
  async connectAll() {
60072
60343
  return {
60073
60344
  store: await persistence.connect(),
@@ -60303,261 +60574,6 @@ async function queryDatabricksLineageEvidence(client, submissionId) {
60303
60574
  }));
60304
60575
  }
60305
60576
 
60306
- // src/volumes-attachment-store.ts
60307
- import {
60308
- AttachmentStoreError,
60309
- verifyAttachmentBytes
60310
- } from "@fabric-harness/sdk";
60311
- var UcVolumesAttachmentStore = class {
60312
- client;
60313
- volumeRoot;
60314
- rootPrefix;
60315
- constructor(options) {
60316
- this.client = options.client;
60317
- this.rootPrefix = options.rootPrefix ?? "fh-attachments";
60318
- this.volumeRoot = `/Volumes/${options.catalog}/${options.schema}/${options.volume}/${this.rootPrefix}`;
60319
- }
60320
- async put(input) {
60321
- await verifyAttachmentBytes(input.ref, input.bytes);
60322
- const refPath = this.refPath(input.scope, input.ref.digest);
60323
- if (await this.readFile(refPath)) return;
60324
- await this.writeFile(this.bytesPath(input.scope, input.ref.digest), input.bytes);
60325
- await this.writeFile(refPath, new TextEncoder().encode(JSON.stringify(input.ref)));
60326
- }
60327
- async get(scope, digest) {
60328
- const refBytes = await this.readFile(this.refPath(scope, digest));
60329
- if (!refBytes) return null;
60330
- const ref = parseAttachmentRef(refBytes);
60331
- const bytes = await this.readFile(this.bytesPath(scope, digest));
60332
- if (!bytes) return null;
60333
- return { ref, bytes };
60334
- }
60335
- async getByAttachmentId(scope, attachmentId) {
60336
- for (const ref of await this.list(scope)) {
60337
- if (ref.id === attachmentId) return this.get(scope, ref.digest);
60338
- }
60339
- return null;
60340
- }
60341
- async list(scope) {
60342
- const refs = [];
60343
- for (const prefixDir of await this.listDirectory(this.scopeDir(scope))) {
60344
- if (!prefixDir.isDirectory || !prefixDir.path) continue;
60345
- for (const entry of await this.listDirectory(prefixDir.path)) {
60346
- if (entry.isDirectory || !entry.path || !entry.path.endsWith(".json")) continue;
60347
- const refBytes = await this.readFile(entry.path);
60348
- if (refBytes) refs.push(parseAttachmentRef(refBytes));
60349
- }
60350
- }
60351
- return refs;
60352
- }
60353
- async delete(scope, digest) {
60354
- if (!await this.deleteFile(this.refPath(scope, digest))) {
60355
- throw new AttachmentStoreError("NOT_FOUND", `Attachment not found: ${scope}/${digest}`);
60356
- }
60357
- await this.deleteFile(this.bytesPath(scope, digest));
60358
- }
60359
- // ─── Volume paths ─────────────────────────────────────────────────────────
60360
- scopeDir(scope) {
60361
- return `${this.volumeRoot}/${encodeURIComponent(scope)}`;
60362
- }
60363
- bytesPath(scope, digest) {
60364
- return `${this.scopeDir(scope)}/${digest.slice(0, 2)}/${digest}`;
60365
- }
60366
- refPath(scope, digest) {
60367
- return `${this.bytesPath(scope, digest)}.json`;
60368
- }
60369
- // ─── Files API ────────────────────────────────────────────────────────────
60370
- async writeFile(path4, bytes) {
60371
- await this.client.uploadFile({
60372
- filePath: path4,
60373
- overwrite: true,
60374
- contents: new Blob([viewToBuffer(bytes)]).stream()
60375
- });
60376
- }
60377
- /** Raw file bytes, or `null` when the file does not exist (404). */
60378
- async readFile(path4) {
60379
- try {
60380
- const response = await this.client.downloadFile({ filePath: path4 });
60381
- if (!response.contents) return new Uint8Array();
60382
- return new Uint8Array(await new Response(response.contents).arrayBuffer());
60383
- } catch (error51) {
60384
- if (isNotFound(error51)) return null;
60385
- throw error51;
60386
- }
60387
- }
60388
- /** True when the file existed and was deleted; false on 404. */
60389
- async deleteFile(path4) {
60390
- try {
60391
- await this.client.deleteFile({ filePath: path4 });
60392
- return true;
60393
- } catch (error51) {
60394
- if (isNotFound(error51)) return false;
60395
- throw error51;
60396
- }
60397
- }
60398
- /** Immediate children of a directory; empty for a missing directory (404). */
60399
- async listDirectory(path4) {
60400
- const entries = [];
60401
- let pageToken;
60402
- do {
60403
- let listing;
60404
- try {
60405
- listing = await this.client.listDirectoryContents({
60406
- directoryPath: path4,
60407
- ...pageToken ? { pageToken } : {}
60408
- });
60409
- } catch (error51) {
60410
- if (isNotFound(error51)) return entries;
60411
- throw error51;
60412
- }
60413
- entries.push(...listing.contents ?? []);
60414
- pageToken = listing.nextPageToken;
60415
- } while (pageToken);
60416
- return entries;
60417
- }
60418
- };
60419
- function isNotFound(error51) {
60420
- if (error51 && typeof error51 === "object" && "httpStatusCode" in error51)
60421
- return error51.httpStatusCode === 404;
60422
- return /RESOURCE_DOES_NOT_EXIST|does not exist|404/iu.test(String(error51));
60423
- }
60424
- function parseAttachmentRef(bytes) {
60425
- const parsed = JSON.parse(new TextDecoder().decode(bytes));
60426
- if (typeof parsed.id !== "string" || typeof parsed.mimeType !== "string" || typeof parsed.sizeBytes !== "number" || typeof parsed.digest !== "string") {
60427
- throw new Error("databricks volumes: malformed attachment ref sidecar");
60428
- }
60429
- return {
60430
- id: parsed.id,
60431
- mimeType: parsed.mimeType,
60432
- sizeBytes: parsed.sizeBytes,
60433
- digest: parsed.digest,
60434
- ...typeof parsed.filename === "string" ? { filename: parsed.filename } : {}
60435
- };
60436
- }
60437
- function viewToBuffer(bytes) {
60438
- return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
60439
- }
60440
-
60441
- // src/app.ts
60442
- function databricksApp(options = {}) {
60443
- registerDatabricksModelProvider();
60444
- const env2 = options.env ?? (typeof process !== "undefined" ? process.env : {});
60445
- const principal = options.principal ?? appServicePrincipalFromEnv(env2);
60446
- if (!principal) {
60447
- throw new Error(
60448
- "databricksApp() could not resolve an identity: pass `principal` or set DATABRICKS_HOST + DATABRICKS_CLIENT_ID + DATABRICKS_CLIENT_SECRET (the Databricks Apps runtime provides these)."
60449
- );
60450
- }
60451
- const host = options.host ?? (principal.kind === "service-principal" || principal.kind === "cli-profile" ? principal.host : void 0) ?? (env2.DATABRICKS_HOST ? env2.DATABRICKS_HOST.includes("://") ? env2.DATABRICKS_HOST : `https://${env2.DATABRICKS_HOST}` : void 0);
60452
- if (!host) {
60453
- throw new Error(
60454
- "databricksApp() requires a workspace host: pass `host` or set DATABRICKS_HOST."
60455
- );
60456
- }
60457
- const identity = databricksIdentity(principal);
60458
- const fabricPrincipal = fabricPrincipalFor(principal, {
60459
- asAppPrincipal: true,
60460
- ...options.ucPrincipal ? { ucPrincipal: options.ucPrincipal } : {}
60461
- });
60462
- const actor = { principal: fabricPrincipal };
60463
- const native = createDatabricksNativeClients({
60464
- host,
60465
- credentials: databricksCredentials(principal),
60466
- tokenProvider: identity,
60467
- ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60468
- });
60469
- const model = options.model ?? env2.DATABRICKS_MODEL;
60470
- const envMode = parseInferenceMode(env2.DATABRICKS_INFERENCE_MODE);
60471
- const modelProvider = databricksFoundationModelProvider({
60472
- host,
60473
- token: identity,
60474
- ...model ? { defaultModel: model } : {},
60475
- ...env2.DATABRICKS_AI_GATEWAY_BASE_URL ? { baseUrl: env2.DATABRICKS_AI_GATEWAY_BASE_URL } : {},
60476
- ...envMode ? { mode: envMode } : {},
60477
- ...options.inference ?? {},
60478
- ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60479
- });
60480
- let persistence;
60481
- if (options.lakebase !== false) {
60482
- const lakebase = options.lakebase === void 0 ? {} : options.lakebase;
60483
- const lakebaseHost = lakebase.host ?? env2.DATABRICKS_LAKEBASE_HOST ?? env2.PGHOST;
60484
- const database = lakebase.database ?? env2.DATABRICKS_LAKEBASE_DATABASE ?? env2.PGDATABASE;
60485
- const endpoint = lakebase.endpoint ?? env2.DATABRICKS_LAKEBASE_ENDPOINT ?? env2.ENDPOINT_NAME;
60486
- const user = lakebase.user ?? env2.DATABRICKS_LAKEBASE_USER ?? env2.PGUSER ?? (principal.kind === "service-principal" ? principal.clientId : void 0);
60487
- if (lakebaseHost && database && user && endpoint) {
60488
- persistence = databricksPersistence({
60489
- lakebase: {
60490
- host: lakebaseHost,
60491
- database,
60492
- user,
60493
- endpoint,
60494
- credentialClient: native.postgres,
60495
- ...lakebase.port !== void 0 ? { port: lakebase.port } : env2.PGPORT ? { port: Number(env2.PGPORT) } : {},
60496
- ...lakebase.ssl !== void 0 ? { ssl: lakebase.ssl } : {},
60497
- ...lakebase.poolFactory ? { poolFactory: lakebase.poolFactory } : {}
60498
- },
60499
- ...options.loadPersistenceStores ? { loadStores: options.loadPersistenceStores } : {}
60500
- });
60501
- } else if (options.lakebase !== void 0) {
60502
- throw new Error(
60503
- "databricksApp({ lakebase }) is missing connection details: provide host/database/user/endpoint or the DATABRICKS_LAKEBASE_* (or PG*/ENDPOINT_NAME) environment variables from the app database resource."
60504
- );
60505
- }
60506
- }
60507
- const telemetry = persistence && options.telemetry !== false ? databricksTelemetry({ client: persistence.client }) : void 0;
60508
- const attachmentConfig = options.attachments === false ? void 0 : options.attachments ?? {};
60509
- const attachmentCatalog = attachmentConfig?.catalog ?? env2.DATABRICKS_CATALOG;
60510
- const attachmentSchema = attachmentConfig?.schema ?? env2.DATABRICKS_SCHEMA;
60511
- const attachmentVolume = attachmentConfig?.volume ?? env2.DATABRICKS_VOLUME;
60512
- const attachmentStore = attachmentCatalog && attachmentSchema && attachmentVolume ? new UcVolumesAttachmentStore({
60513
- client: native.files,
60514
- catalog: attachmentCatalog,
60515
- schema: attachmentSchema,
60516
- volume: attachmentVolume,
60517
- rootPrefix: attachmentConfig?.rootPrefix ?? env2.DATABRICKS_VOLUME_ROOT ?? "fh-attachments",
60518
- ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60519
- }) : void 0;
60520
- return {
60521
- identity,
60522
- principal: fabricPrincipal,
60523
- actor,
60524
- modelProvider,
60525
- ...persistence ? { persistence } : {},
60526
- ...telemetry ? { telemetry } : {},
60527
- ...attachmentStore ? { attachmentStore } : {},
60528
- mlflowTraceExporter: (traceOptions) => mlflowTraceExporter({ client: native.rawProtocol, ...traceOptions }),
60529
- async serverOptions() {
60530
- if (!persistence) return attachmentStore ? { attachmentStore } : {};
60531
- const { store, submissionStore, conversationStreamStore } = await persistence.connectAll();
60532
- return {
60533
- sessionStore: store,
60534
- submissionStore,
60535
- conversationStreamStore,
60536
- ...telemetry ? { telemetry: telemetry.sink } : {},
60537
- ...attachmentStore ? { attachmentStore } : {}
60538
- };
60539
- },
60540
- onBehalfOf(headers) {
60541
- const user = onBehalfOfFromHeaders(headers);
60542
- if (!user) return void 0;
60543
- return {
60544
- identity: databricksIdentity(user),
60545
- actor: { principal: fabricPrincipalFor(user), onBehalfOf: user.label ?? "user" }
60546
- };
60547
- },
60548
- async close() {
60549
- await persistence?.close();
60550
- }
60551
- };
60552
- }
60553
- function parseInferenceMode(value) {
60554
- if (!value) return void 0;
60555
- if (value === "auto" || value === "ai-gateway" || value === "serving-endpoints") return value;
60556
- throw new Error(
60557
- `Invalid DATABRICKS_INFERENCE_MODE "${value}". Use auto, ai-gateway, or serving-endpoints.`
60558
- );
60559
- }
60560
-
60561
60577
  // src/app-user-authorization.ts
60562
60578
  import { createHash as createHash3 } from "crypto";
60563
60579
  var DATABRICKS_APP_USER_PERMISSIONS = [
@@ -60587,7 +60603,7 @@ function createDatabricksAppUserAuthenticator(options) {
60587
60603
  id: forwardedUser.id,
60588
60604
  kind: "user",
60589
60605
  provider: "databricks-apps",
60590
- tenantId: `databricks-user:${createHash3("sha256").update(forwardedUser.id).digest("hex").slice(0, 24)}`,
60606
+ tenantId: databricksPrincipalTenantId("user", forwardedUser.id),
60591
60607
  permissions: [...permissions],
60592
60608
  ...forwardedUser.displayName ? { displayName: forwardedUser.displayName } : {},
60593
60609
  ...forwardedUser.ucPrincipal ? { ucPrincipal: forwardedUser.ucPrincipal } : {}
@@ -60609,7 +60625,7 @@ function createDatabricksAppUserAuthenticator(options) {
60609
60625
  id,
60610
60626
  kind: "service-principal",
60611
60627
  provider: "databricks-apps",
60612
- tenantId: `databricks-service-principal:${createHash3("sha256").update(id).digest("hex").slice(0, 24)}`,
60628
+ tenantId: databricksPrincipalTenantId("service-principal", id),
60613
60629
  permissions: [...permissions]
60614
60630
  };
60615
60631
  }
@@ -60625,7 +60641,7 @@ function createDatabricksAppUserAuthenticator(options) {
60625
60641
  ...options.now ? { now: options.now } : {}
60626
60642
  });
60627
60643
  const id = inspection.principal.id;
60628
- const tenantId = options.tenantId?.(inspection) ?? `databricks-user:${createHash3("sha256").update(id).digest("hex").slice(0, 24)}`;
60644
+ const tenantId = options.tenantId?.(inspection) ?? databricksPrincipalTenantId("user", id);
60629
60645
  if (!tenantId) return false;
60630
60646
  const principal = {
60631
60647
  id,
@@ -60653,10 +60669,13 @@ function appPrincipalFor(id, permissions) {
60653
60669
  id,
60654
60670
  kind: "app-principal",
60655
60671
  provider: "databricks-apps",
60656
- tenantId: `databricks-app:${createHash3("sha256").update(id).digest("hex").slice(0, 24)}`,
60672
+ tenantId: databricksPrincipalTenantId("app", id),
60657
60673
  permissions: [...permissions]
60658
60674
  };
60659
60675
  }
60676
+ function databricksPrincipalTenantId(kind, id) {
60677
+ return `databricks-${kind}:${createHash3("sha256").update(id).digest("hex").slice(0, 24)}`;
60678
+ }
60660
60679
  async function isAppAuthorizedCaller(headers, delegated, allowed) {
60661
60680
  const forwarded = forwardedIdentity(headers);
60662
60681
  if (forwarded && allowed.has(forwarded)) return true;
@@ -60755,6 +60774,275 @@ function jwtLifetimeClaims(token) {
60755
60774
  }
60756
60775
  }
60757
60776
 
60777
+ // src/volumes-attachment-store.ts
60778
+ import {
60779
+ AttachmentStoreError,
60780
+ verifyAttachmentBytes
60781
+ } from "@fabric-harness/sdk";
60782
+ var UcVolumesAttachmentStore = class {
60783
+ client;
60784
+ volumeRoot;
60785
+ rootPrefix;
60786
+ constructor(options) {
60787
+ this.client = options.client;
60788
+ this.rootPrefix = options.rootPrefix ?? "fh-attachments";
60789
+ this.volumeRoot = `/Volumes/${options.catalog}/${options.schema}/${options.volume}/${this.rootPrefix}`;
60790
+ }
60791
+ async put(input) {
60792
+ await verifyAttachmentBytes(input.ref, input.bytes);
60793
+ const refPath = this.refPath(input.scope, input.ref.digest);
60794
+ if (await this.readFile(refPath)) return;
60795
+ await this.writeFile(this.bytesPath(input.scope, input.ref.digest), input.bytes);
60796
+ await this.writeFile(refPath, new TextEncoder().encode(JSON.stringify(input.ref)));
60797
+ }
60798
+ async get(scope, digest) {
60799
+ const refBytes = await this.readFile(this.refPath(scope, digest));
60800
+ if (!refBytes) return null;
60801
+ const ref = parseAttachmentRef(refBytes);
60802
+ const bytes = await this.readFile(this.bytesPath(scope, digest));
60803
+ if (!bytes) return null;
60804
+ return { ref, bytes };
60805
+ }
60806
+ async getByAttachmentId(scope, attachmentId) {
60807
+ for (const ref of await this.list(scope)) {
60808
+ if (ref.id === attachmentId) return this.get(scope, ref.digest);
60809
+ }
60810
+ return null;
60811
+ }
60812
+ async list(scope) {
60813
+ const refs = [];
60814
+ for (const prefixDir of await this.listDirectory(this.scopeDir(scope))) {
60815
+ if (!prefixDir.isDirectory || !prefixDir.path) continue;
60816
+ for (const entry of await this.listDirectory(prefixDir.path)) {
60817
+ if (entry.isDirectory || !entry.path || !entry.path.endsWith(".json")) continue;
60818
+ const refBytes = await this.readFile(entry.path);
60819
+ if (refBytes) refs.push(parseAttachmentRef(refBytes));
60820
+ }
60821
+ }
60822
+ return refs;
60823
+ }
60824
+ async delete(scope, digest) {
60825
+ if (!await this.deleteFile(this.refPath(scope, digest))) {
60826
+ throw new AttachmentStoreError("NOT_FOUND", `Attachment not found: ${scope}/${digest}`);
60827
+ }
60828
+ await this.deleteFile(this.bytesPath(scope, digest));
60829
+ }
60830
+ // ─── Volume paths ─────────────────────────────────────────────────────────
60831
+ scopeDir(scope) {
60832
+ return `${this.volumeRoot}/${encodeURIComponent(scope)}`;
60833
+ }
60834
+ bytesPath(scope, digest) {
60835
+ return `${this.scopeDir(scope)}/${digest.slice(0, 2)}/${digest}`;
60836
+ }
60837
+ refPath(scope, digest) {
60838
+ return `${this.bytesPath(scope, digest)}.json`;
60839
+ }
60840
+ // ─── Files API ────────────────────────────────────────────────────────────
60841
+ async writeFile(path4, bytes) {
60842
+ await this.client.uploadFile({
60843
+ filePath: path4,
60844
+ overwrite: true,
60845
+ contents: new Blob([viewToBuffer(bytes)]).stream()
60846
+ });
60847
+ }
60848
+ /** Raw file bytes, or `null` when the file does not exist (404). */
60849
+ async readFile(path4) {
60850
+ try {
60851
+ const response = await this.client.downloadFile({ filePath: path4 });
60852
+ if (!response.contents) return new Uint8Array();
60853
+ return new Uint8Array(await new Response(response.contents).arrayBuffer());
60854
+ } catch (error51) {
60855
+ if (isNotFound(error51)) return null;
60856
+ throw error51;
60857
+ }
60858
+ }
60859
+ /** True when the file existed and was deleted; false on 404. */
60860
+ async deleteFile(path4) {
60861
+ try {
60862
+ await this.client.deleteFile({ filePath: path4 });
60863
+ return true;
60864
+ } catch (error51) {
60865
+ if (isNotFound(error51)) return false;
60866
+ throw error51;
60867
+ }
60868
+ }
60869
+ /** Immediate children of a directory; empty for a missing directory (404). */
60870
+ async listDirectory(path4) {
60871
+ const entries = [];
60872
+ let pageToken;
60873
+ do {
60874
+ let listing;
60875
+ try {
60876
+ listing = await this.client.listDirectoryContents({
60877
+ directoryPath: path4,
60878
+ ...pageToken ? { pageToken } : {}
60879
+ });
60880
+ } catch (error51) {
60881
+ if (isNotFound(error51)) return entries;
60882
+ throw error51;
60883
+ }
60884
+ entries.push(...listing.contents ?? []);
60885
+ pageToken = listing.nextPageToken;
60886
+ } while (pageToken);
60887
+ return entries;
60888
+ }
60889
+ };
60890
+ function isNotFound(error51) {
60891
+ if (error51 && typeof error51 === "object" && "httpStatusCode" in error51)
60892
+ return error51.httpStatusCode === 404;
60893
+ return /RESOURCE_DOES_NOT_EXIST|does not exist|404/iu.test(String(error51));
60894
+ }
60895
+ function parseAttachmentRef(bytes) {
60896
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
60897
+ if (typeof parsed.id !== "string" || typeof parsed.mimeType !== "string" || typeof parsed.sizeBytes !== "number" || typeof parsed.digest !== "string") {
60898
+ throw new Error("databricks volumes: malformed attachment ref sidecar");
60899
+ }
60900
+ return {
60901
+ id: parsed.id,
60902
+ mimeType: parsed.mimeType,
60903
+ sizeBytes: parsed.sizeBytes,
60904
+ digest: parsed.digest,
60905
+ ...typeof parsed.filename === "string" ? { filename: parsed.filename } : {}
60906
+ };
60907
+ }
60908
+ function viewToBuffer(bytes) {
60909
+ return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
60910
+ }
60911
+
60912
+ // src/app.ts
60913
+ function databricksApp(options = {}) {
60914
+ registerDatabricksModelProvider();
60915
+ const env2 = options.env ?? (typeof process !== "undefined" ? process.env : {});
60916
+ const principal = options.principal ?? appServicePrincipalFromEnv(env2);
60917
+ if (!principal) {
60918
+ throw new Error(
60919
+ "databricksApp() could not resolve an identity: pass `principal` or set DATABRICKS_HOST + DATABRICKS_CLIENT_ID + DATABRICKS_CLIENT_SECRET (the Databricks Apps runtime provides these)."
60920
+ );
60921
+ }
60922
+ const host = options.host ?? (principal.kind === "service-principal" || principal.kind === "cli-profile" ? principal.host : void 0) ?? (env2.DATABRICKS_HOST ? env2.DATABRICKS_HOST.includes("://") ? env2.DATABRICKS_HOST : `https://${env2.DATABRICKS_HOST}` : void 0);
60923
+ if (!host) {
60924
+ throw new Error(
60925
+ "databricksApp() requires a workspace host: pass `host` or set DATABRICKS_HOST."
60926
+ );
60927
+ }
60928
+ const identity = databricksIdentity(principal);
60929
+ const fabricPrincipal = fabricPrincipalFor(principal, {
60930
+ asAppPrincipal: true,
60931
+ ...options.ucPrincipal ? { ucPrincipal: options.ucPrincipal } : {}
60932
+ });
60933
+ const actor = { principal: fabricPrincipal };
60934
+ const schedulerIdentity = {
60935
+ tenantId: databricksPrincipalTenantId("app", fabricPrincipal.id),
60936
+ actor
60937
+ };
60938
+ const native = createDatabricksNativeClients({
60939
+ host,
60940
+ credentials: databricksCredentials(principal),
60941
+ tokenProvider: identity,
60942
+ ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60943
+ });
60944
+ const model = options.model ?? env2.DATABRICKS_MODEL;
60945
+ const envMode = parseInferenceMode(env2.DATABRICKS_INFERENCE_MODE);
60946
+ const modelProvider = databricksFoundationModelProvider({
60947
+ host,
60948
+ token: identity,
60949
+ ...model ? { defaultModel: model } : {},
60950
+ ...env2.DATABRICKS_AI_GATEWAY_BASE_URL ? { baseUrl: env2.DATABRICKS_AI_GATEWAY_BASE_URL } : {},
60951
+ ...envMode ? { mode: envMode } : {},
60952
+ ...options.inference ?? {},
60953
+ ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60954
+ });
60955
+ let persistence;
60956
+ if (options.lakebase !== false) {
60957
+ const lakebase = options.lakebase === void 0 ? {} : options.lakebase;
60958
+ const lakebaseHost = lakebase.host ?? env2.DATABRICKS_LAKEBASE_HOST ?? env2.PGHOST;
60959
+ const database = lakebase.database ?? env2.DATABRICKS_LAKEBASE_DATABASE ?? env2.PGDATABASE;
60960
+ const endpoint = lakebase.endpoint ?? env2.DATABRICKS_LAKEBASE_ENDPOINT ?? env2.ENDPOINT_NAME;
60961
+ const user = lakebase.user ?? env2.DATABRICKS_LAKEBASE_USER ?? env2.PGUSER ?? (principal.kind === "service-principal" ? principal.clientId : void 0);
60962
+ if (lakebaseHost && database && user && endpoint) {
60963
+ persistence = databricksPersistence({
60964
+ lakebase: {
60965
+ host: lakebaseHost,
60966
+ database,
60967
+ user,
60968
+ endpoint,
60969
+ credentialClient: native.postgres,
60970
+ ...lakebase.port !== void 0 ? { port: lakebase.port } : env2.PGPORT ? { port: Number(env2.PGPORT) } : {},
60971
+ ...lakebase.ssl !== void 0 ? { ssl: lakebase.ssl } : {},
60972
+ ...lakebase.poolFactory ? { poolFactory: lakebase.poolFactory } : {}
60973
+ },
60974
+ ...options.loadPersistenceStores ? { loadStores: options.loadPersistenceStores } : {}
60975
+ });
60976
+ } else if (options.lakebase !== void 0) {
60977
+ throw new Error(
60978
+ "databricksApp({ lakebase }) is missing connection details: provide host/database/user/endpoint or the DATABRICKS_LAKEBASE_* (or PG*/ENDPOINT_NAME) environment variables from the app database resource."
60979
+ );
60980
+ }
60981
+ }
60982
+ const telemetry = persistence && options.telemetry !== false ? databricksTelemetry({ client: persistence.client }) : void 0;
60983
+ const attachmentConfig = options.attachments === false ? void 0 : options.attachments ?? {};
60984
+ const attachmentCatalog = attachmentConfig?.catalog ?? env2.DATABRICKS_CATALOG;
60985
+ const attachmentSchema = attachmentConfig?.schema ?? env2.DATABRICKS_SCHEMA;
60986
+ const attachmentVolume = attachmentConfig?.volume ?? env2.DATABRICKS_VOLUME;
60987
+ const attachmentStore = attachmentCatalog && attachmentSchema && attachmentVolume ? new UcVolumesAttachmentStore({
60988
+ client: native.files,
60989
+ catalog: attachmentCatalog,
60990
+ schema: attachmentSchema,
60991
+ volume: attachmentVolume,
60992
+ rootPrefix: attachmentConfig?.rootPrefix ?? env2.DATABRICKS_VOLUME_ROOT ?? "fh-attachments",
60993
+ ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
60994
+ }) : void 0;
60995
+ return {
60996
+ identity,
60997
+ principal: fabricPrincipal,
60998
+ actor,
60999
+ modelProvider,
61000
+ ...persistence ? { persistence } : {},
61001
+ ...telemetry ? { telemetry } : {},
61002
+ ...attachmentStore ? { attachmentStore } : {},
61003
+ mlflowTraceExporter: (traceOptions) => mlflowTraceExporter({ client: native.rawProtocol, ...traceOptions }),
61004
+ async serverOptions() {
61005
+ if (!persistence)
61006
+ return {
61007
+ scheduler: { identity: () => schedulerIdentity, catchUp: "skip" },
61008
+ ...attachmentStore ? { attachmentStore } : {}
61009
+ };
61010
+ const { store, submissionStore, conversationStreamStore } = await persistence.connectAll();
61011
+ const schedulerLeaseStore = await persistence.connectSchedulerLeaseStore();
61012
+ return {
61013
+ sessionStore: store,
61014
+ submissionStore,
61015
+ conversationStreamStore,
61016
+ ...telemetry ? { telemetry: telemetry.sink } : {},
61017
+ ...attachmentStore ? { attachmentStore } : {},
61018
+ scheduler: {
61019
+ identity: () => schedulerIdentity,
61020
+ ...schedulerLeaseStore ? { leaseStore: schedulerLeaseStore } : {},
61021
+ catchUp: "run-once"
61022
+ }
61023
+ };
61024
+ },
61025
+ onBehalfOf(headers) {
61026
+ const user = onBehalfOfFromHeaders(headers);
61027
+ if (!user) return void 0;
61028
+ return {
61029
+ identity: databricksIdentity(user),
61030
+ actor: { principal: fabricPrincipalFor(user), onBehalfOf: user.label ?? "user" }
61031
+ };
61032
+ },
61033
+ async close() {
61034
+ await persistence?.close();
61035
+ }
61036
+ };
61037
+ }
61038
+ function parseInferenceMode(value) {
61039
+ if (!value) return void 0;
61040
+ if (value === "auto" || value === "ai-gateway" || value === "serving-endpoints") return value;
61041
+ throw new Error(
61042
+ `Invalid DATABRICKS_INFERENCE_MODE "${value}". Use auto, ai-gateway, or serving-endpoints.`
61043
+ );
61044
+ }
61045
+
60758
61046
  // src/serving-usage.ts
60759
61047
  import { currentSubmissionContext as currentSubmissionContext3, emitSubmissionTelemetry } from "@fabric-harness/sdk";
60760
61048
  function servingUsageCapture(options) {
@@ -62401,7 +62689,7 @@ var DATABRICKS_API_VERSIONS = {
62401
62689
  var DATABRICKS_PACKAGE_COMPATIBILITY = {
62402
62690
  node: ">=22.0.0",
62403
62691
  package: "@fabric-harness/databricks",
62404
- packageRange: ">=5.0.0 <6",
62692
+ packageRange: ">=6.0.0 <7",
62405
62693
  pg: "^8.11.0 (only for Lakebase)"
62406
62694
  };
62407
62695
  var DATABRICKS_AUTH_MODES = [
@@ -62891,7 +63179,17 @@ var DATABRICKS_CAPABILITY_DEFINITIONS = [
62891
63179
  certification: "protected-live",
62892
63180
  auth: ["oauth-m2m", "app-service-principal", "pat"],
62893
63181
  contractClouds: ALL_CLOUDS,
62894
- surfaces: [{ package: "@fabric-harness/databricks", exports: ["databricks", "scoreRagTurn"] }],
63182
+ surfaces: [
63183
+ {
63184
+ package: "@fabric-harness/databricks",
63185
+ exports: [
63186
+ "databricks",
63187
+ "scoreRagTurn",
63188
+ "databricksMlflowLogMetricTool",
63189
+ "databricksMlflowLogParamTool"
63190
+ ]
63191
+ }
63192
+ ],
62895
63193
  requiredEvidence: ["mlflow.trace", "mlflow.evaluate"],
62896
63194
  evidenceIds: ["dbx-cert-d03df5a0a5b69a98d8acb0ad4c1e9ef9bcffefea7e433cbd2ba0ff3d792fec71"],
62897
63195
  docs: "/docs/databricks/rag",
@@ -62941,7 +63239,7 @@ var DATABRICKS_CAPABILITY_DEFINITIONS = [
62941
63239
  requiredEvidence: ["lakeflow.read", "lakeflow.execute"],
62942
63240
  evidenceIds: [CURRENT_CONSUMPTION_EVIDENCE_ID],
62943
63241
  docs: "/docs/databricks/integrations",
62944
- notes: "Read/execute evidence remains separate from the beta lakeflow-authoring lifecycle."
63242
+ notes: "List/status are read-only defaults. Model-callable start/stop require a construction-time pipeline policy; read/execute evidence remains separate from authoring lifecycle evidence."
62945
63243
  },
62946
63244
  {
62947
63245
  id: "automation-bundles",
@@ -63833,7 +64131,8 @@ function defineDatabricksAgent(options = {}) {
63833
64131
  ...directTools.length > 0 ? { tools: directTools } : {},
63834
64132
  run: async (context) => {
63835
64133
  const env2 = context.env ?? {};
63836
- const config2 = explicitConfig ?? databricksConfigFromEnv(env2, { analyticsCopilot });
64134
+ const baseConfig = explicitConfig ?? databricksConfigFromEnv(env2, { analyticsCopilot });
64135
+ const config2 = baseConfig.warehouseId && !baseConfig.sqlRead && toolRefs.some((ref) => ref === "sql" || ref === "sql-read" || ref === "sql_read") ? { ...baseConfig, sqlRead: true } : baseConfig;
63837
64136
  const bundle = config2.mcp?.length ? await databricksWithManagedMcp(config2) : databricks(config2);
63838
64137
  try {
63839
64138
  const analyticsCostLimit = analyticsCopilot ? databricksAnalyticsCostLimitFromEnv(env2, config2, bundle) : void 0;
@@ -63934,7 +64233,7 @@ function resolveToolRefs(bundle, refs) {
63934
64233
  toolMap.set(tool7.name, tool7);
63935
64234
  }
63936
64235
  const shortNameMap = {
63937
- sql: "databricks_sql",
64236
+ sql: "sql_read",
63938
64237
  "sql-read": "sql_read",
63939
64238
  tables: "databricks_unity_catalog_tables",
63940
64239
  "table-info": "databricks_table_info",
@@ -64566,11 +64865,19 @@ function buildDatabricksBundle(config2, scope) {
64566
64865
  }
64567
64866
  const rawTools = [
64568
64867
  ...config2.sqlRead && config2.warehouseId ? [databricksSqlReadTool(native.statements, { warehouseId: config2.warehouseId })] : [],
64569
- ...config2.warehouseId ? [databricksSqlTool(native.statements, { warehouseId: config2.warehouseId })] : [],
64868
+ ...config2.sqlExecute && config2.warehouseId ? [
64869
+ databricksSqlTool(native.statements, config2.sqlExecute, {
64870
+ warehouseId: config2.warehouseId
64871
+ })
64872
+ ] : [],
64570
64873
  unityCatalogTablesTool(native.tables),
64571
64874
  databricksTableInfoTool(native.tables),
64572
64875
  ...searchTool ? [searchTool] : [],
64573
- ...config2.aiFunctions && config2.warehouseId ? [databricksAiQueryTool(native.statements, { warehouseId: config2.warehouseId })] : [],
64876
+ ...config2.aiFunctions && config2.warehouseId ? [
64877
+ databricksAiQueryTool(native.statements, config2.aiFunctions, {
64878
+ warehouseId: config2.warehouseId
64879
+ })
64880
+ ] : [],
64574
64881
  ...genie.conversations ? [
64575
64882
  databricksGenieTool(native.genie, {
64576
64883
  ...genie.conversations,
@@ -64596,7 +64903,10 @@ function buildDatabricksBundle(config2, scope) {
64596
64903
  ...genie.manage.sqlPolicy ? { sqlPolicy: genie.manage.sqlPolicy } : {}
64597
64904
  }
64598
64905
  ) : [],
64599
- ...config2.lakeflow ? databricksLakeflowTools(native.pipelines) : [],
64906
+ ...config2.lakeflow ? databricksLakeflowTools(
64907
+ native.pipelines,
64908
+ typeof config2.lakeflow === "object" ? config2.lakeflow.runPolicy : void 0
64909
+ ) : [],
64600
64910
  ...config2.consumption && config2.warehouseId ? [
64601
64911
  databricksConsumptionTool(native.statements, {
64602
64912
  warehouseId: config2.warehouseId
@@ -64633,16 +64943,19 @@ function buildDatabricksBundle(config2, scope) {
64633
64943
  ...config2.tools ?? []
64634
64944
  ];
64635
64945
  const authoringServices = enabledAuthoringServices(config2);
64636
- const customTools = new Set(config2.tools ?? []);
64637
- const authoringToolNames = new Set(
64946
+ const approvalServices = config2.governance?.approvalServices;
64947
+ const approvalRequiredToolNames = new Set(
64638
64948
  rawTools.filter((tool7) => {
64639
64949
  const effect = tool7.metadata?.effect;
64640
- return (effect === "write" || effect === "execute") && Boolean(governanceMetadata(tool7));
64950
+ if (effect !== "write" && effect !== "execute") return false;
64951
+ if (!approvalServices) return true;
64952
+ const service = tool7.metadata?.service;
64953
+ return typeof service === "string" && approvalServices.includes(service);
64641
64954
  }).map((tool7) => tool7.name)
64642
64955
  );
64643
64956
  for (const tool7 of rawTools) {
64644
64957
  const effect = tool7.metadata?.effect;
64645
- if ((authoringToolNames.has(tool7.name) || customTools.has(tool7)) && (effect === "write" || effect === "execute"))
64958
+ if (effect === "write" || effect === "execute")
64646
64959
  validateDatabricksGovernanceDescriptor(tool7, true);
64647
64960
  }
64648
64961
  const tools = withGovernanceTools(rawTools, {
@@ -64650,7 +64963,7 @@ function buildDatabricksBundle(config2, scope) {
64650
64963
  ...config2.governance?.onLineage ? { onLineage: config2.governance.onLineage } : {},
64651
64964
  ...config2.governance?.catalogs ? { catalogs: config2.governance.catalogs } : {},
64652
64965
  executingPrincipal,
64653
- ...config2.governance?.stewardAudience && !config2.allowUnapprovedAuthoring ? { requireApprovalGrantForTools: [...authoringToolNames] } : {}
64966
+ ...config2.governance?.stewardAudience && !config2.allowUnapprovedAuthoring ? { requireApprovalGrantForTools: [...approvalRequiredToolNames] } : {}
64654
64967
  });
64655
64968
  const policy = databricksGovernancePolicy({
64656
64969
  tools,
@@ -64781,11 +65094,9 @@ function validateAuthoringConfig(config2, genie = normalizeGenieConfig(config2))
64781
65094
  if (config2.jobAuthoring || config2.oneOffCompute)
64782
65095
  validateDatabricksComputePolicy(config2.computePolicy ?? {});
64783
65096
  const audience = config2.governance?.stewardAudience;
64784
- const excluded = config2.governance?.approvalServices ? services.filter((service) => !config2.governance?.approvalServices?.includes(service)) : [];
64785
- if (!config2.allowUnapprovedAuthoring && (!audience || excluded.length > 0)) {
64786
- const ungated = !audience ? services : excluded;
65097
+ if (!config2.allowUnapprovedAuthoring && !audience) {
64787
65098
  throw new Error(
64788
- `databricks: authoring services are not approval-gated: ${ungated.join(", ")}. Configure governance.stewardAudience${excluded.length ? " and include every service in governance.approvalServices" : ""}, or explicitly set allowUnapprovedAuthoring: true.`
65099
+ `databricks: authoring services are not approval-gated: ${services.join(", ")}. Configure governance.stewardAudience, or explicitly set allowUnapprovedAuthoring: true.`
64789
65100
  );
64790
65101
  }
64791
65102
  }
@@ -64869,6 +65180,8 @@ export {
64869
65180
  DatabricksJobsAuthoring,
64870
65181
  DatabricksLakeflowAuthoring,
64871
65182
  DatabricksManagedResourceConflictError,
65183
+ DatabricksResourceNotAllowedError,
65184
+ DatabricksRunNotAllowedError,
64872
65185
  DatabricksRunTimeoutError,
64873
65186
  DatabricksSecretsAuthoring,
64874
65187
  DatabricksServingAdmin,
@@ -64996,6 +65309,8 @@ export {
64996
65309
  validateDatabricksCrossTierEvidence,
64997
65310
  validateDatabricksGenieSqlReferences,
64998
65311
  validateDatabricksGovernanceDescriptor,
65312
+ validateDatabricksJobRunPolicy,
65313
+ validateDatabricksNotebookRunPolicy,
64999
65314
  validateDatabricksReleaseEvidence,
65000
65315
  validateDatabricksRollingEvidence,
65001
65316
  validateJobSpec,